Novie UI

Novie's React component library and design system, built with TypeScript, Tailwind CSS v4, Radix UI, and Storybook.

Install

npm install @novie/ui

The package supports React 18 or 19 and requires Tailwind CSS v4. Import the compiled stylesheet once in your application entry point:

import "@novie/ui/styles.css"

Then import components from the public package entry point:

import { Button, IconCommEmail } from "@novie/ui"

export function SendButton() {
  return (
    <Button>
      <IconCommEmail />
      Send
    </Button>
  )
}

Do not import files from @novie/ui/dist or copy internal component paths. Only exports from @novie/ui are public API.

Documentation

• Storybook — interactive component catalog, props, states, and examples
• Getting started — installation, styles, themes, and application setup
• Component guidelines — choosing, composing, and documenting components
• Design tokens — semantic colors, typography, spacing, and dark mode
• Accessibility — labels, keyboard interaction, validation, and feedback

When Storybook is running locally, structured documentation is also available to tools and AI agents:

• Components manifest: http://localhost:6006/manifests/components.json
• Docs manifest: http://localhost:6006/manifests/docs.json
• Storybook MCP server: http://localhost:6006/mcp

Component families

Storybook is the complete inventory. The public package includes:

• Foundations: logo, symbol, icons, typography, spacing, and grid guidance
• Primitives: buttons, inputs, labels, checkboxes, switches, radios, badges, tags, avatars, progress, and separators
• Composites: form fields, search, select, calendar, cards, tables, menus, dialogs, alerts, notifications, tabs, breadcrumbs, and steppers
• Layout patterns: navigation bars, sidebars, data tables, and navigation breadcrumbs

Themes and customization

Novie UI uses semantic CSS variables and Tailwind utilities. Add the dark class to an ancestor, normally <html>, to enable dark mode:

document.documentElement.classList.toggle("dark", isDark)

Use component props and className for supported customization. Prefer semantic utilities such as bg-primary, text-muted-foreground, and border-border; do not depend on internal selectors or hard-coded palette values.

Development

npm install
npm run storybook             # Interactive Storybook at http://localhost:6006
npm run storybook:docs        # Documentation-focused Storybook
npm test                      # Story and interaction tests
npm run test:unit             # Component and icon unit tests
npm run build                 # Package JavaScript, CSS, and declarations
npm run build-storybook:docs  # Static documentation and AI manifests

Repository-aware AI tools should follow AGENTS.md. Contributor implementation conventions and Figma source rules are documented in CLAUDE.md.

Package exports

import { Button } from "@novie/ui"
import "@novie/ui/styles.css"

The root export contains components, public component types, utilities, and the Novie icon set. @novie/ui/styles.css contains the compiled theme, design tokens, fonts, and component utilities.

License

MIT