DESIGN TOKENS ONLY — Never use raw Tailwind colors. Always use semantic token classes:
text-text-primary not text-gray-900bg-surface-default not bg-whiteborder-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.
- Create a new component (with story) → Read
workflows/create-component.md
- Add stories to an existing component → Read
workflows/add-stories.md
- Add an Untitled UI source-owned component → Read
untitled-ui.md for CLI commands, then follow workflow 1 for customization and story creation
- 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).
1---2name: create-ui-component-23description: Creates UI components for the Foundry platform using the design system, UntitledUI icons, dark/light mode support, and Storybook stories. Use when building new UI components, adding stories, or when the user invokes /create-ui-component.4---56<objective>7Build design-system-compliant React components for the Foundry platform with automatic dark/light theme support and Storybook coverage. Covers new component creation, adding Untitled UI source-owned components, and adding stories to existing components.8</objective>910<quick_start>11Determine the user's intent using the intake section below, then route to the appropriate workflow file.12</quick_start>1314<essential_principles>15These rules are non-negotiable for every component:1617DESIGN TOKENS ONLY — Never use raw Tailwind colors. Always use semantic token classes:18- `text-text-primary` not `text-gray-900`19- `bg-surface-default` not `bg-white`20- `border-border-default` not `border-slate-200`2122DARK/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.2324ICONS FROM @untitledui/icons — Import individual icons by name:25```tsx26import { Grid01, AlertTriangle, Activity } from "@untitledui/icons";27<Grid01 size={20} className="text-text-muted" />28```29Icon sizes: 16 (sm), 20 (default), 24 (lg)3031"use client" DIRECTIVE — Add `"use client"` at the top of every interactive component (event handlers, hooks, state).3233CO-LOCATE STORIES — Story files live next to their component: `ComponentName.stories.tsx` beside `ComponentName.tsx`.3435NO PURPLE — Never use purple color schemes. Use the existing blue/slate palette.3637USE UTILITY CLASSES WHERE APPLICABLE — Prefer globals.css utility classes when they exist:38- `.btn-primary`, `.btn-secondary`, `.btn-ghost` for buttons39- `.card`, `.card-interactive` for card containers40- `.input`, `.textarea`, `.select` for form inputs41- `.badge`, `.badge-success`, `.badge-warning`, `.badge-error`, `.badge-info` for badges42- `.modal`, `.modal-overlay` for modals43- `.tooltip` for tooltips44- `.table-header`, `.table-cell`, `.table-row-hover` for tables45- `.type-display-xl` through `.type-code` for typography4647FONTS:48- Display headings: `font-display` (Instrument Serif)49- Body text: `font-sans` (DM Sans) — this is the default50- Code/monospace: `font-mono` (DM Mono)5152UNTITLED 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.53</essential_principles>5455<intake>56Determine the user's intent and route to the appropriate workflow:57581. Create a new component (with story) → Read `workflows/create-component.md`592. Add stories to an existing component → Read `workflows/add-stories.md`603. Add an Untitled UI source-owned component → Read `untitled-ui.md` for CLI commands, then follow workflow 1 for customization and story creation614. Something else → Clarify the user's intent, then select the appropriate workflow6263If the user provides a component description, default to workflow 1 (create new component).64</intake>6566<reference_guides>67- `references/design-tokens.md` — Complete token reference (surfaces, text, borders, status, interactive, component-specific)68- `references/storybook-patterns.md` — CSF3 format, mock system, play functions, decorators69- `references/component-patterns.md` — Existing patterns (status badges, cards, hover states, terminals, tooltips)70- `untitled-ui.md` — Untitled UI React framework reference (CLI, components, MCP, theming, icons)71- `templates/component.tsx.md` — Component file template72- `templates/story.tsx.md` — Story file template (CSF3 with all standard variants)73</reference_guides>7475<success_criteria>76- Component file created at `src/components/{domain}/{ComponentName}.tsx`77- Story file co-located at `src/components/{domain}/{ComponentName}.stories.tsx`78- No raw Tailwind colors used (no `text-gray-*`, `bg-white`, `bg-slate-*`, `border-gray-*`)79- No `dark:` Tailwind prefix used anywhere80- Icons imported from `@untitledui/icons` (not inline SVGs)81- Story includes at minimum Default and Mobile variants82- Component uses globals.css utility classes where applicable83- No purple color schemes84</success_criteria>
qdhenry