moduix

Polished React components for product interfaces, built on Ark UI and styled with native CSS.

moduix pairs Ark's accessible interaction model with shadcn-inspired clarity: calm defaults, explicit composition, a token-first theme contract, and a hosted registry when you want to own the source. Use it as the @moduix/react package or copy selected components into your application with the shadcn CLI.

Documentation · Quick start · Components · npm

Why moduix

• Ark-backed behavior. Complex interaction, keyboard support, state, and composition stay close to Ark UI instead of being reimplemented in a styled wrapper.
• Polished defaults. Components share a compact visual rhythm, predictable states, and a consistent focus-ring language.
• Token-first CSS. Colors, typography, spacing, radii, sizes, focus geometry, motion, shadows, and component aliases are regular CSS custom properties.
• Composable APIs. Named parts keep important structure visible and leave room for product-level composition.
• Two ownership models. Choose package-managed updates or source ownership through the hosted shadcn registry.
• Small UI runtime. moduix uses Ark UI as its primitive layer and does not require a styling framework.

Choose an Ownership Model

Start with the npm package for the shortest setup. Use the registry when direct source ownership is a project requirement.

Both workflows use the same component contracts and design-token foundation.

Package Quick Start

Install moduix and its Ark UI peer dependency in an existing React 18 or 19 application:

npm install @moduix/react @ark-ui/react

Import the required foundation stylesheet once:

import '@moduix/react/style.css';

The optional reset is a separate entrypoint and must come first:

import '@moduix/react/reset.css';import '@moduix/react/style.css';

Then compose the components you need:

import { Button, Dialog } from '@moduix/react';
export function Example() {  return (    <Dialog.Root>      <Dialog.Trigger asChild>        <Button>Open settings</Button>      </Dialog.Trigger>      <Dialog.Backdrop />      <Dialog.Positioner>        <Dialog.Content>          <Dialog.Header>            <Dialog.Title>Project settings</Dialog.Title>            <Dialog.Description>Update how this workspace behaves.</Dialog.Description>          </Dialog.Header>          <Dialog.Footer>            <Dialog.CloseTrigger asChild>              <Button variant="outline">Done</Button>            </Dialog.CloseTrigger>          </Dialog.Footer>        </Dialog.Content>      </Dialog.Positioner>    </Dialog.Root>  );}

style.css provides shared tokens and base styles. Component imports bring along their own CSS, so unused component styles can stay out of the consuming bundle.

Copy-Owned Quick Start

Create the ready-to-use components.json from the complete Quick Start, then add the components you need:

npx shadcn@latest add @moduix-react/button @moduix-react/dialog

Make sure the @/* alias resolves to src/* in TypeScript and your bundler. Generated component files land under src/components/moduix/*; shared styles, icons, and utilities land under src/lib/moduix/*.

Import the generated foundation stylesheet once:

import '@/lib/moduix/styles/style.css';

See the complete Quick Start for Vite and Rsbuild aliases, registry inspection, dry runs, optional reset setup, and alternative package managers.

Theming

The default visual rhythm uses --moduix-size-md: 36px for primary controls and --moduix-size-sm: 32px for popup rows. Inputs, buttons, select and combobox triggers, date controls, pagination, and menu-like items resolve through that shared scale.

Theme the system from broad decisions to narrow exceptions:

1. Override primitives such as --moduix-primary, --moduix-radius, --moduix-spacing-2, and --moduix-size-md.
2. Use shared family tokens such as --moduix-popup-item-min-height and --moduix-focus-ring-width.
3. Reach for component aliases such as --moduix-input-height only when one component should diverge.

:root {  --moduix-primary: oklch(0.52 0.18 145);  --moduix-radius: 0.75rem;  --moduix-size-md: 36px;  --moduix-size-sm: 32px;}

All moduix-owned variables use the --moduix-* namespace, so they do not replace tokens from an existing product design system. Map the tokens you want to share; for example, --moduix-primary: var(--product-action-primary). Ark UI runtime variables remain unprefixed on the component parts that Ark controls.

Components expose className, stable moduix data-slot hooks, and Ark data-scope, data-part, and state attributes where the underlying primitive provides them.

Optional dense, soft, and contrast presets are shipped separately:

import '@moduix/react/style.css';import '@moduix/react/presets/soft.css';

<html data-moduix-theme="soft"></html>

Read Tokens for the full hierarchy and Themes for preset and custom-theme workflows.

Repository

The workspace uses npm, Turborepo, oxlint, oxfmt, and Changesets.

npm installnpm run build:reactnpm run dev

Before opening a pull request, run the repository checks in order:

npm run fmt:fixnpm run lint:checknpm run build:reactnpm run tsc:check

Run npm run build:registry after changing registry-shipped React source.

Acknowledgements

moduix is possible because of the work and ideas of these projects:

• Ark UI for the accessible, state-machine-backed primitives that define the behavioral foundation.
• Chakra UI for Ark-aligned composition ergonomics and enduring design-system craft.
• shadcn/ui for open-code distribution, beautiful defaults, and practical documentation.
• UnoCSS and Tailwind CSS for the foundations adapted by the optional reset.
• Rspress for the documentation experience and application foundation.
• VoidZero for the JavaScript tooling used throughout the workspace.

Contributing

Contributions are welcome, especially focused component improvements, accessibility fixes, bug reports, and documentation corrections. Keep package behavior, local component notes, public docs, and registry output synchronized when a public contract changes.

See AGENTS.md for repository conventions used by maintainers and coding agents.

License

MIT