@molano/ui

Component library for the Molano Design System. 74 components built on React 19, Tailwind v4, and @base-ui/react.

Installation

npm install @molano/ui @molano/tokens

// Import components
import { Button, Card, DataTable, Dialog } from "@molano/ui"

// Import global styles (once, in your root layout)
import "@molano/tokens"
import "@molano/ui/globals"

Component Inventory

Actions (5)

| Component | File | Description | |-----------|------|-------------| | Button | button.tsx | Primary action element with 6 variants and 5 sizes | | ButtonGroup | button-group.tsx | Group buttons with separator | | CopyButton | copy-button.tsx | Copy text to clipboard with feedback | | Toggle | toggle.tsx | On/off toggle button | | ToggleGroup | toggle-group.tsx | Exclusive or multi-select toggle buttons |

Data Display (12)

| Component | File | Description | |-----------|------|-------------| | Avatar | avatar.tsx | User avatar with image, fallback, badge, group | | Badge | badge.tsx | Status labels and counts | | Card | card.tsx | Content container with header, footer, actions | | DataTable | data-table.tsx | Full-featured table: sorting, filtering, pagination | | Empty | empty.tsx | Empty state primitive | | Item | item.tsx | List item with media, content, actions | | Progress | progress.tsx | Progress bar with track, indicator, label | | Skeleton | skeleton.tsx | Loading placeholder | | Table | table.tsx | Basic HTML table with DS styling | | Tag | tag.tsx | Removable tag with group support | | Timeline | timeline.tsx | Vertical timeline with indicators and connectors |

Forms (16)

| Component | File | Description | |-----------|------|-------------| | Calendar | calendar.tsx | Date picker calendar | | Checkbox | checkbox.tsx | Checkbox input | | Combobox | combobox.tsx | Searchable select with chips and multi-select | | DatePicker | date-picker.tsx | Single date and date range picker | | Field | field.tsx | Form field wrapper: label, description, error | | FileUpload | file-upload.tsx | Drag-and-drop file upload | | Input | input.tsx | Text input | | InputGroup | input-group.tsx | Input with addons and buttons | | InputOTP | input-otp.tsx | One-time password input | | Label | label.tsx | Form label | | NativeSelect | native-select.tsx | Native HTML select | | RadioGroup | radio-group.tsx | Radio button group | | Select | select.tsx | Custom select dropdown | | Slider | slider.tsx | Range slider | | Switch | switch.tsx | Toggle switch | | Textarea | textarea.tsx | Multi-line text input |

Feedback (3)

| Component | File | Description | |-----------|------|-------------| | Alert | alert.tsx | Inline alert with variants and action | | Sonner | sonner.tsx | Toast notification system | | Spinner | spinner.tsx | Loading spinner |

Layout (4)

| Component | File | Description | |-----------|------|-------------| | AppShell | app-shell.tsx | Root layout shell with sidebar, header, footer | | AuthLayout | auth-layout.tsx | Centered auth page layout | | DashboardLayout | dashboard-layout.tsx | Dashboard with header and content | | PageLayout | page-layout.tsx | Page with title, description, actions, content |

Navigation (6)

| Component | File | Description | |-----------|------|-------------| | Breadcrumb | breadcrumb.tsx | Breadcrumb navigation | | Menubar | menubar.tsx | Horizontal menu bar | | NavigationMenu | navigation-menu.tsx | Top navigation with dropdowns | | Pagination | pagination.tsx | Page navigation | | Sidebar | sidebar.tsx | Collapsible sidebar navigation | | Tabs | tabs.tsx | Tab navigation |

Overlays (10)

| Component | File | Description | |-----------|------|-------------| | AlertDialog | alert-dialog.tsx | Confirmation dialog | | Command | command.tsx | Command palette (cmdk) | | ContextMenu | context-menu.tsx | Right-click context menu | | Dialog | dialog.tsx | Modal dialog | | Drawer | drawer.tsx | Bottom/side drawer (vaul) | | DropdownMenu | dropdown-menu.tsx | Dropdown menu | | HoverCard | hover-card.tsx | Hover card popup | | Popover | popover.tsx | Popover content | | Sheet | sheet.tsx | Side sheet overlay | | Tooltip | tooltip.tsx | Tooltip on hover |

Utilities (12)

| Component | File | Description | |-----------|------|-------------| | Accordion | accordion.tsx | Expandable sections | | AspectRatio | aspect-ratio.tsx | Maintain aspect ratio | | Carousel | carousel.tsx | Image/content carousel (embla) | | Chart | chart.tsx | Charts with recharts | | Collapsible | collapsible.tsx | Collapsible section | | Direction | direction.tsx | RTL/LTR direction provider | | Kbd | kbd.tsx | Keyboard shortcut display | | Resizable | resizable.tsx | Resizable panels | | ScrollArea | scroll-area.tsx | Custom scrollbar | | Separator | separator.tsx | Visual separator | | Stepper | stepper.tsx | Multi-step wizard |

Recipes (24)

Pre-composed patterns built from primitives:

| Recipe | File | Composes | |--------|------|----------| | LoginForm | auth-recipes.tsx | Card, Field, Input, Button | | RegisterForm | auth-recipes.tsx | Card, Field, Input, Button, Checkbox | | StatCard | cards.tsx | Card, Badge | | ActionCard | cards.tsx | Card, Button | | ProfileCard | cards.tsx | Card, Avatar, Badge | | PricingCard | cards.tsx | Card, Button, Separator | | CommandPalette | command-palette-recipes.tsx | Command, Dialog | | StatsRow | data-display-recipes.tsx | Card | | DetailHeader | data-display-recipes.tsx | Avatar, Badge, Button | | ActivityFeed | data-display-recipes.tsx | Avatar, Timeline | | ErrorPage | feedback-recipes.tsx | Button | | EmptyState | feedback-recipes.tsx | Empty, Button | | SkeletonCard | feedback-recipes.tsx | Skeleton, Card | | LoadingScreen | feedback-recipes.tsx | Spinner | | ConfirmDialog | feedback-recipes.tsx | AlertDialog, Button | | SkeletonTableRow | feedback-recipes.tsx | Skeleton | | FormCard | form-recipes.tsx | Card, Field | | InlineEdit | form-recipes.tsx | Input, Button | | StepperForm | form-recipes.tsx | Stepper, Card | | SearchFilter | navigation-recipes.tsx | Input, Button | | SectionHeader | navigation-recipes.tsx | — | | SettingsPage | settings-recipes.tsx | Card, Switch | | SettingsItem | settings-recipes.tsx | Switch, Select | | SettingsSection | settings-recipes.tsx | Card |

Component Conventions

All components follow these patterns:

// data-slot for test selection and styling
<div data-slot="card" className={cn("...", className)} {...props}>

// displayName for DevTools
Card.displayName = "Card"

// No forwardRef — React 19 passes ref via props
function Card({ className, ref, ...props }) {

// cn() for className merging
import { cn } from "@/lib/utils"

// render prop for polymorphism (NOT asChild)
<DialogTrigger render={<Button />}>Open</DialogTrigger>

Testing

npm run test              # 199 tests across 14 files
npm run test:watch        # Watch mode
npm run test:coverage     # With coverage report

Test files: src/__tests__/*.test.tsx

Tests cover: rendering, props, variants, a11y (axe-core), keyboard interaction, data-slot attributes.

Scripts

| Script | Purpose | |--------|---------| | npm run build | Build with tsup (ESM + CJS + DTS) | | npm run dev | Build in watch mode | | npm run test | Run vitest | | npm run lint | ESLint | | npm run typecheck | tsc --noEmit | | npm run check:bundle | Bundle size analysis | | npm run check:treeshake | Tree-shaking verification |

Key Files

| File | Purpose | |------|---------| | COMPONENT-METADATA.json | Registry of all components with lifecycle status, category, sub-components | | PATTERN-REGISTRY.json | 12 UI pattern definitions for the MCP server | | eslint-plugin-ds.mjs | Custom ESLint rules: no native elements, no hardcoded colors, etc. | | docs/*.md | 91 knowledge base documents (one per component) | | tsup.config.ts | Build configuration | | vitest.config.ts | Test configuration |

Dependencies

Direct:

• @base-ui/react — Headless primitives (not Radix)
• class-variance-authority — Variant management
• clsx + tailwind-merge — className utilities
• lucide-react — Icons
• sonner — Toast notifications
• vaul — Drawer component
• cmdk — Command palette
• input-otp — OTP input

Peer (optional):

• @tanstack/react-table — DataTable
• embla-carousel-react — Carousel
• react-day-picker — Calendar/DatePicker
• react-resizable-panels — Resizable
• recharts — Charts