Create UI Component

DESIGN TOKENS ONLY — Never use raw Tailwind colors. Always use semantic token classes:

• text-text-primary not text-gray-900
• bg-surface-default not bg-white
• border-border-default not border-slate-200

DARK/LIGHT MODE VIA CSS CUSTOM PROPERTIES — Components must NOT use the dark: Tailwind prefix. The token system handles theming automatically via CSS variables on :root and .dark class. A component styled with bg-surface-default text-text-primary works correctly in both themes without any dark-mode-specific code.

ICONS FROM @untitledui/icons — Import individual icons by name:

import { Grid01, AlertTriangle, Activity } from "@untitledui/icons";
<Grid01 size={20} className="text-text-muted" />

Icon sizes: 16 (sm), 20 (default), 24 (lg)

"use client" DIRECTIVE — Add "use client" at the top of every interactive component (event handlers, hooks, state).

CO-LOCATE STORIES — Story files live next to their component: ComponentName.stories.tsx beside ComponentName.tsx.

NO PURPLE — Never use purple color schemes. Use the existing blue/slate palette.

USE UTILITY CLASSES WHERE APPLICABLE — Prefer globals.css utility classes when they exist:

• .btn-primary, .btn-secondary, .btn-ghost for buttons
• .card, .card-interactive for card containers
• .input, .textarea, .select for form inputs
• .badge, .badge-success, .badge-warning, .badge-error, .badge-info for badges
• .modal, .modal-overlay for modals
• .tooltip for tooltips
• .table-header, .table-cell, .table-row-hover for tables
• .type-display-xl through .type-code for typography

FONTS:

• Display headings: font-display (Instrument Serif)
• Body text: font-sans (DM Sans) — this is the default
• Code/monospace: font-mono (DM Mono)

UNTITLED UI FRAMEWORK — Source-owned components from Untitled UI React can be added via CLI (bunx untitledui@latest add <component>). See untitled-ui.md for the full framework reference including CLI commands, component categories, MCP integration, and theming.

1. Create a new component (with story) → Read workflows/create-component.md
2. Add stories to an existing component → Read workflows/add-stories.md
3. Add an Untitled UI source-owned component → Read untitled-ui.md for CLI commands, then follow workflow 1 for customization and story creation
4. Something else → Clarify the user's intent, then select the appropriate workflow

If the user provides a component description, default to workflow 1 (create new component).