moduix

Composable React components for product interfaces, built on top of Base UI primitives.

moduix gives you ready-made components with accessible behavior, native CSS styles, and a composition-first API. It is inspired by the clarity of shadcn/ui, and it is trying to combine two useful workflows: install components as a regular npm package when that fits your project, or copy component source when you need direct ownership.

Why It Exists

moduix started as an internal tool for shared product UI. We needed a component library that was practical enough for real application screens, predictable enough to use across teams, and small enough to stay easy to understand.

The library is now public because it may be useful outside of the original company context. If it helps another team build consistent interfaces faster, that is already a good outcome.

Principles

• Base UI underneath. Components are built on accessible Base UI primitives instead of reimplementing low-level interaction behavior.
• Small dependency surface. Base UI is the only external UI primitive layer. The package keeps the runtime stack intentionally small and does not bring a styling framework with it.
• Two installation paths. Use moduix as an npm package, or copy component source into your project when direct ownership is more important than package-managed updates.
• Composable API. Components are exposed as named parts, so complex UI can be assembled without hiding important structure.
• Native CSS. Styles are distributed as CSS, use CSS custom properties, and are designed to work with your existing styling approach.
• Not a shadcn/ui competitor. shadcn/ui is a major inspiration for the developer experience. moduix explores whether package-managed components and copy-owned components can coexist in one library.

Installation

npm install moduix @base-ui/react

react, react-dom, and @base-ui/react are peer dependencies. They stay in your application bundle, so moduix does not ship duplicate React or Base UI runtimes.

Usage

Import the library styles once in your application entry point:

import 'moduix/style.css';

Then import and compose the components you need:

import { Button, Dialog, DialogContent, DialogTitle, DialogTrigger } from 'moduix';

export function Example() {
  return (
    <Dialog>
      <DialogTrigger render={<Button />}>Open dialog</DialogTrigger>
      <DialogContent>
        <DialogTitle>Project settings</DialogTitle>
      </DialogContent>
    </Dialog>
  );
}

The distributed stylesheet includes component styles and design tokens. It does not force a global application theme or utility CSS runtime.

Styling

Components accept className where customization is expected and expose stable data-slot attributes for targeted styling. Theme values are regular CSS custom properties:

:root {
  --color-primary: oklch(0.205 0 0);
  --button-radius: 0.5rem;
}

Library CSS is organized with cascade layers:

@layer ui.reset, ui.tokens, ui.components;

This keeps defaults predictable while still letting application styles override tokens, classes, or component-level variables.

What Is Included

The package exports composed components for common product UI needs, including Accordion, AlertDialog, Autocomplete, Avatar, Button, Checkbox, Dialog, Drawer, Field, Form, Input, Menu, NavigationMenu, Popover, Select, Tabs, Toast, Tooltip, and supporting primitives.

Documentation

• Documentation: https://moduix.blinks44.workers.dev/
• npm package: https://www.npmjs.com/package/moduix
• UI package README: packages/ui/README.md
• Docs app README: apps/docs/README.md

Repository Quick Start

From the monorepo root:

npm install
npm run build:ui
npm run dev

Acknowledgements

This project could not exist without the work of these teams and communities:

• Base UI for the accessible React primitives that power the components.
• shadcn/ui for the API inspiration and the culture of practical, readable component composition.
• Tailwind CSS for the reset.css implementation.
• Fumadocs for the documentation foundation.
• TanStack for the application tooling used by the docs.
• Voidzero for awesome JS tools

Contributing

Contributions are welcome, especially bug reports, accessibility fixes, documentation improvements, and focused component improvements.

Before opening a pull request:

1. Install dependencies from the repository root:

   npm install

2. Build the UI package when your change affects packages/ui or documentation examples:

   npm run build:ui

3. Run the required checks:

   npm run fmt:fix
   npm run lint:check
   npm run tsc:check

Keep pull requests small and specific. For component changes, update the related stories, exports, and documentation so the package and docs stay in sync.

Feel free to use agents or code generation tools, but please review the result before submitting. The components are intentionally small and direct, so the goal is to keep the code readable, maintainable, and free from unnecessary abstractions. I added the skills folder so code written with agents stays consistent with the rest of the library components.