design system token v0.1

2026-04-13 15:33:00 -05:00
parent 52b4156653
commit c3215945f2
63 changed files with 11562 additions and 181 deletions
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -0,0 +1,662 @@
+# Greyhaven Design System -- Claude Skill
+
+> **Auto-generated** by `scripts/generate-skill.ts` -- DO NOT EDIT by hand.
+> Re-generate: `pnpm skill:build`
+>
+> **Components**: 37 | **Style**: shadcn/ui "new-york"
+> **Stack**: React 19, Radix UI, Tailwind CSS v4, CVA, tailwind-merge, clsx, Lucide icons
+> **Framework-agnostic**: No Next.js imports. Works with Vite, Remix, Astro, CRA, or any React setup.
+
+This skill gives you full context to generate pixel-perfect, on-brand UI using the Greyhaven Design System. Every component lives in `components/ui/`. Use semantic tokens, never raw colors. Follow the patterns exactly.
+
+
+---
+
+## 1. Design Philosophy
+
+- **Minimal and restrained**: Off-white + off-black + warm greys. One single accent color (orange). No gradients, no decorative color, no multiple accent hues.
+- **Typography-driven**: Source Serif 4/Pro (serif) for headings and body content. Aspekta/Inter (sans) for UI labels, buttons, navigation, and form elements.
+- **Calm, professional aesthetic**: Tight border-radii, subtle shadows, generous whitespace.
+- **Accessibility-first**: Built on Radix UI primitives for keyboard navigation, focus management, screen reader support. Visible focus rings, disabled states, ARIA attributes.
+- **Dark mode native**: Thoughtful dark theme using inverted warm greys. Orange accent persists across both modes. Toggled via `.dark` class.
+- **Framework-agnostic**: Pure React + Radix + Tailwind. No Next.js, no framework-specific imports.
+
+
+---
+
+## 2. Token Quick Reference
+
+Source of truth: `tokens/*.json` (W3C DTCG format).
+
+### Color
+
+| Token | Value | Description |
+|-------|-------|-------------|
+| `color.primitive.off-white` | `#F9F9F7` | Primary light surface — cards, elevated areas |
+| `color.primitive.off-black` | `#161614` | Primary dark — foreground text, dark mode background |
+| `color.primitive.orange` | `#D95E2A` | Only accent color — used sparingly for primary actions and emphasis |
+| `color.primitive.destructive-red` | `#B43232` | Error/danger states |
+| `color.primitive.grey.1` | `#F0F0EC` | 5% — Subtle backgrounds, secondary, muted |
+| `color.primitive.grey.2` | `#DDDDD7` | 10% — Accent hover, light borders |
+| `color.primitive.grey.3` | `#C4C4BD` | 20% — Border, input |
+| `color.primitive.grey.4` | `#A6A69F` | 50% — Mid-tone |
+| `color.primitive.grey.5` | `#7F7F79` | 60% — Mid-dark |
+| `color.primitive.grey.7` | `#575753` | 70% — Secondary foreground, muted foreground |
+| `color.primitive.grey.8` | `#2F2F2C` | 80% — Dark mode card, dark surfaces |
+| `color.semantic.background` | `{color.primitive.grey.1}` | Page background |
+| `color.semantic.foreground` | `{color.primitive.off-black}` | Primary text |
+| `color.semantic.card` | `{color.primitive.off-white}` | Card/elevated surface background |
+| `color.semantic.card-foreground` | `{color.primitive.off-black}` | Card text |
+| `color.semantic.popover` | `{color.primitive.off-white}` | Popover background |
+| `color.semantic.popover-foreground` | `{color.primitive.off-black}` | Popover text |
+| `color.semantic.primary` | `{color.primitive.orange}` | Primary accent — buttons, links, focus rings |
+| `color.semantic.primary-foreground` | `{color.primitive.off-white}` | Text on primary accent |
+| `color.semantic.secondary` | `{color.primitive.grey.1}` | Secondary button/surface |
+| `color.semantic.secondary-foreground` | `{color.primitive.grey.8}` | Text on secondary surface |
+| `color.semantic.muted` | `{color.primitive.grey.1}` | Muted/subdued background |
+| `color.semantic.muted-foreground` | `{color.primitive.grey.7}` | Muted/subdued text |
+| `color.semantic.accent` | `{color.primitive.grey.2}` | Subtle hover state |
+| `color.semantic.accent-foreground` | `{color.primitive.off-black}` | Text on accent hover |
+| `color.semantic.destructive` | `{color.primitive.destructive-red}` | Destructive/error actions |
+| `color.semantic.destructive-foreground` | `{color.primitive.off-white}` | Text on destructive |
+| `color.semantic.border` | `{color.primitive.grey.3}` | Default border |
+| `color.semantic.input` | `{color.primitive.grey.3}` | Input border |
+| `color.semantic.ring` | `{color.primitive.orange}` | Focus ring |
+| `color.semantic.chart.1` | `{color.primitive.orange}` | Chart accent |
+| `color.semantic.chart.2` | `{color.primitive.grey.7}` | Chart secondary |
+| `color.semantic.chart.3` | `{color.primitive.grey.5}` | Chart tertiary |
+| `color.semantic.chart.4` | `{color.primitive.grey.4}` | Chart quaternary |
+| `color.semantic.chart.5` | `{color.primitive.grey.8}` | Chart quinary |
+| `color.semantic.sidebar.background` | `{color.primitive.grey.1}` | Sidebar background |
+| `color.semantic.sidebar.foreground` | `{color.primitive.off-black}` | Sidebar text |
+| `color.semantic.sidebar.primary` | `{color.primitive.orange}` | Sidebar primary accent |
+| `color.semantic.sidebar.primary-foreground` | `{color.primitive.off-white}` | Sidebar primary text |
+| `color.semantic.sidebar.accent` | `{color.primitive.grey.3}` | Sidebar accent/hover |
+| `color.semantic.sidebar.accent-foreground` | `{color.primitive.off-black}` | Sidebar accent text |
+| `color.semantic.sidebar.border` | `{color.primitive.grey.3}` | Sidebar border |
+| `color.semantic.sidebar.ring` | `{color.primitive.orange}` | Sidebar focus ring |
+| `color.dark.background` | `{color.primitive.off-black}` | Dark page background |
+| `color.dark.foreground` | `{color.primitive.off-white}` | Dark primary text |
+| `color.dark.card` | `{color.primitive.grey.8}` | Dark card surface |
+| `color.dark.card-foreground` | `{color.primitive.off-white}` | Dark card text |
+| `color.dark.popover` | `{color.primitive.grey.8}` | Dark popover |
+| `color.dark.popover-foreground` | `{color.primitive.off-white}` | Dark popover text |
+| `color.dark.primary` | `{color.primitive.orange}` | Same orange in dark mode |
+| `color.dark.primary-foreground` | `{color.primitive.off-white}` | Dark primary foreground |
+| `color.dark.secondary` | `{color.primitive.grey.7}` | Dark secondary |
+| `color.dark.secondary-foreground` | `{color.primitive.off-white}` | Dark secondary text |
+| `color.dark.muted` | `{color.primitive.grey.7}` | Dark muted |
+| `color.dark.muted-foreground` | `{color.primitive.grey.3}` | Dark muted text |
+| `color.dark.accent` | `{color.primitive.grey.7}` | Dark accent/hover |
+| `color.dark.accent-foreground` | `{color.primitive.off-white}` | Dark accent text |
+| `color.dark.destructive` | `{color.primitive.destructive-red}` | Same destructive in dark mode |
+| `color.dark.destructive-foreground` | `{color.primitive.off-white}` | Dark destructive text |
+| `color.dark.border` | `{color.primitive.grey.7}` | Dark border |
+| `color.dark.input` | `{color.primitive.grey.7}` | Dark input border |
+| `color.dark.ring` | `{color.primitive.orange}` | Dark focus ring |
+| `color.dark.chart.1` | `{color.primitive.orange}` | Dark chart accent |
+| `color.dark.chart.2` | `{color.primitive.grey.3}` | Dark chart secondary |
+| `color.dark.chart.3` | `{color.primitive.grey.4}` | Dark chart tertiary |
+| `color.dark.chart.4` | `{color.primitive.grey.5}` | Dark chart quaternary |
+| `color.dark.chart.5` | `{color.primitive.grey.1}` | Dark chart quinary |
+| `color.dark.sidebar.background` | `{color.primitive.grey.8}` | Dark sidebar background |
+| `color.dark.sidebar.foreground` | `{color.primitive.off-white}` | Dark sidebar text |
+| `color.dark.sidebar.primary` | `{color.primitive.orange}` | Dark sidebar primary |
+| `color.dark.sidebar.primary-foreground` | `{color.primitive.off-white}` | Dark sidebar primary text |
+| `color.dark.sidebar.accent` | `{color.primitive.grey.7}` | Dark sidebar accent |
+| `color.dark.sidebar.accent-foreground` | `{color.primitive.off-white}` | Dark sidebar accent text |
+| `color.dark.sidebar.border` | `{color.primitive.grey.7}` | Dark sidebar border |
+| `color.dark.sidebar.ring` | `{color.primitive.orange}` | Dark sidebar ring |
+
+### Typography
+
+| Token | Value | Description |
+|-------|-------|-------------|
+| `typography.fontFamily.sans` | `["Aspekta","Inter","ui-sans-serif","system-ui","sans-serif"]` | UI labels, buttons, nav, forms — Aspekta primary, Inter fallback |
+| `typography.fontFamily.serif` | `["Source Serif 4","Source Serif Pro","Georgia","serif"]` | Headings, body content, reading — Source Serif primary |
+| `typography.fontFamily.mono` | `["ui-monospace","SFMono-Regular","Menlo","Monaco","Consolas","monospace"]` | Code blocks and monospaced content |
+| `typography.fontSize.xs` | `0.75rem` | 12px — metadata, fine print |
+| `typography.fontSize.sm` | `0.875rem` | 14px — captions, nav, labels, buttons |
+| `typography.fontSize.base` | `1rem` | 16px — body text |
+| `typography.fontSize.lg` | `1.125rem` | 18px — large body, subtitles |
+| `typography.fontSize.xl` | `1.25rem` | 20px — H3 |
+| `typography.fontSize.2xl` | `1.5rem` | 24px — H2 |
+| `typography.fontSize.3xl` | `1.875rem` | 30px — large H2 |
+| `typography.fontSize.4xl` | `2.25rem` | 36px — H1 |
+| `typography.fontSize.5xl` | `3rem` | 48px — hero heading |
+| `typography.fontWeight.normal` | `400` | Regular body text |
+| `typography.fontWeight.medium` | `500` | H3, labels, nav items |
+| `typography.fontWeight.semibold` | `600` | H1, H2, buttons |
+| `typography.fontWeight.bold` | `700` | Strong emphasis |
+| `typography.lineHeight.tight` | `1.25` | Headings |
+| `typography.lineHeight.normal` | `1.5` | Default |
+| `typography.lineHeight.relaxed` | `1.625` | Body content for readability |
+| `typography.letterSpacing.tight` | `-0.025em` | Headings — tracking-tight |
+| `typography.letterSpacing.normal` | `0em` | Body text |
+| `typography.letterSpacing.wide` | `0.05em` | Uppercase labels |
+
+### Spacing
+
+| Token | Value | Description |
+|-------|-------|-------------|
+| `spacing.0` | `0` | None |
+| `spacing.1` | `0.25rem` | 4px — tight gaps |
+| `spacing.2` | `0.5rem` | 8px — card header gap, form description spacing |
+| `spacing.3` | `0.75rem` | 12px |
+| `spacing.4` | `1rem` | 16px — form field gap, button padding |
+| `spacing.5` | `1.25rem` | 20px |
+| `spacing.6` | `1.5rem` | 24px — card padding, card internal gap |
+| `spacing.8` | `2rem` | 32px — section margin-bottom |
+| `spacing.10` | `2.5rem` | 40px |
+| `spacing.12` | `3rem` | 48px |
+| `spacing.16` | `4rem` | 64px — major section padding (py-16) |
+| `spacing.20` | `5rem` | 80px |
+| `spacing.24` | `6rem` | 96px — hero padding |
+| `spacing.0.5` | `0.125rem` | 2px — micro spacing |
+| `spacing.1.5` | `0.375rem` | 6px |
+| `spacing.component.card-padding` | `1.5rem` | Card internal padding (px-6) |
+| `spacing.component.card-gap` | `1.5rem` | Gap between cards (gap-6) |
+| `spacing.component.section-padding` | `4rem` | Vertical padding between major sections (py-16) |
+| `spacing.component.form-gap` | `1rem` | Gap between form fields (gap-4) |
+| `spacing.component.button-padding-x` | `1rem` | Button horizontal padding (px-4) |
+| `spacing.component.navbar-height` | `4rem` | Navbar height (h-16) |
+
+### Radii
+
+| Token | Value | Description |
+|-------|-------|-------------|
+| `radii.base` | `0.375rem` | 6px — base radius |
+| `radii.sm` | `calc(0.375rem - 2px)` | 4px — small variant |
+| `radii.md` | `0.375rem` | 6px — medium (same as base) |
+| `radii.lg` | `calc(0.375rem + 2px)` | 8px — large variant |
+| `radii.xl` | `calc(0.375rem + 4px)` | 10px — extra large variant (cards) |
+| `radii.full` | `9999px` | Fully round (pills, avatars) |
+
+### Shadows
+
+| Token | Value | Description |
+|-------|-------|-------------|
+| `shadow.xs` | `{"offsetX":"0","offsetY":"1px","blur":"2px","spread":"0","color":"rgba(22, 22, 20, 0.05)"}` | Subtle shadow for buttons, inputs |
+| `shadow.sm` | `{"offsetX":"0","offsetY":"1px","blur":"3px","spread":"0","color":"rgba(22, 22, 20, 0.1)"}` | Small shadow for cards |
+| `shadow.md` | `{"offsetX":"0","offsetY":"4px","blur":"6px","spread":"-1px","color":"rgba(22, 22, 20, 0.1)"}` | Medium shadow for dropdowns, popovers |
+| `shadow.lg` | `{"offsetX":"0","offsetY":"10px","blur":"15px","spread":"-3px","color":"rgba(22, 22, 20, 0.1)"}` | Large shadow for dialogs, modals |
+
+### Motion
+
+| Token | Value | Description |
+|-------|-------|-------------|
+| `motion.duration.fast` | `150ms` | Quick transitions — tooltips, hover states |
+| `motion.duration.normal` | `200ms` | Default transitions — most UI interactions |
+| `motion.duration.slow` | `300ms` | Deliberate transitions — modals, drawers, accordions |
+| `motion.easing.default` | `[0.4,0,0.2,1]` | Standard ease-in-out |
+| `motion.easing.in` | `[0.4,0,1,1]` | Ease-in for exits |
+| `motion.easing.out` | `[0,0,0.2,1]` | Ease-out for entrances |
+
+
+---
+
+## 3. Component Catalog (37 components)
+
+All components live in `components/ui/`. Import with `@/components/ui/<name>`.
+
+### Primitives
+
+#### Button
+- **File**: `components/ui/button.tsx`
+- **Exports**: `Button`, `buttonVariants`
+- **Description**: Primary interactive element. 6 variants: default (orange), secondary, outline, ghost, link, destructive. Sizes: default (h-9), sm (h-8), lg (h-10), icon (size-9).
+- **Props**: `variant?: "default" | "secondary" | "outline" | "ghost" | "link" | "destructive"; size?: "default" | "sm" | "lg" | "icon" | "icon-sm" | "icon-lg"; asChild?: boolean`
+- **Example**:
+```tsx
+<Button variant="default" size="default">Click me</Button>
+```
+
+#### Badge
+- **File**: `components/ui/badge.tsx`
+- **Exports**: `Badge`, `badgeVariants`
+- **Description**: Status indicator / tag. Variants include default, secondary, outline, destructive, success, warning, info, plus channel pills (WhatsApp, Email, Telegram, Zulip).
+- **Props**: `variant?: "default" | "secondary" | "destructive" | "outline" | "success" | "warning" | "info" | ...; asChild?: boolean`
+- **Example**:
+```tsx
+<Badge variant="success">Active</Badge>
+```
+
+#### Input
+- **File**: `components/ui/input.tsx`
+- **Exports**: `Input`
+- **Description**: Text input field with focus ring, disabled, and aria-invalid states.
+- **Props**: `All standard HTML input props`
+- **Example**:
+```tsx
+<Input type="email" placeholder="you@example.com" />
+```
+
+#### Textarea
+- **File**: `components/ui/textarea.tsx`
+- **Exports**: `Textarea`
+- **Description**: Multi-line text input.
+- **Props**: `All standard HTML textarea props`
+- **Example**:
+```tsx
+<Textarea placeholder="Write your message..." />
+```
+
+#### Label
+- **File**: `components/ui/label.tsx`
+- **Exports**: `Label`
+- **Description**: Form label using Radix Label primitive.
+- **Props**: `All standard HTML label props + Radix Label props`
+- **Example**:
+```tsx
+<Label htmlFor="email">Email</Label>
+```
+
+#### Checkbox
+- **File**: `components/ui/checkbox.tsx`
+- **Exports**: `Checkbox`
+- **Description**: Checkbox using Radix Checkbox primitive.
+- **Props**: `checked?: boolean; onCheckedChange?: (checked: boolean) => void`
+- **Example**:
+```tsx
+<Checkbox id="terms" />
+```
+
+#### Switch
+- **File**: `components/ui/switch.tsx`
+- **Exports**: `Switch`
+- **Description**: Toggle switch using Radix Switch primitive.
+- **Props**: `checked?: boolean; onCheckedChange?: (checked: boolean) => void`
+- **Example**:
+```tsx
+<Switch id="dark-mode" />
+```
+
+#### Select
+- **File**: `components/ui/select.tsx`
+- **Exports**: `Select`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectTrigger`, `SelectValue`
+- **Description**: Dropdown select using Radix Select.
+- **Props**: `value?: string; onValueChange?: (value: string) => void`
+- **Example**:
+```tsx
+<Select><SelectTrigger><SelectValue placeholder="Choose..." /></SelectTrigger><SelectContent><SelectItem value="a">Option A</SelectItem></SelectContent></Select>
+```
+
+#### RadioGroup
+- **File**: `components/ui/radio-group.tsx`
+- **Exports**: `RadioGroup`, `RadioGroupItem`
+- **Description**: Radio button group using Radix RadioGroup.
+- **Props**: `value?: string; onValueChange?: (value: string) => void`
+- **Example**:
+```tsx
+<RadioGroup defaultValue="a"><RadioGroupItem value="a" /><RadioGroupItem value="b" /></RadioGroup>
+```
+
+#### Toggle
+- **File**: `components/ui/toggle.tsx`
+- **Exports**: `Toggle`, `toggleVariants`
+- **Description**: Toggle button. Variants: default, outline.
+- **Props**: `variant?: "default" | "outline"; size?: "default" | "sm" | "lg"; pressed?: boolean`
+- **Example**:
+```tsx
+<Toggle aria-label="Bold"><BoldIcon /></Toggle>
+```
+
+### Layout
+
+#### Card
+- **File**: `components/ui/card.tsx`
+- **Exports**: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`
+- **Description**: Container with header/content/footer slots. Off-white bg, rounded-xl, subtle shadow.
+- **Props**: `Standard div props. Compose with CardHeader, CardTitle, CardDescription, CardContent, CardFooter sub-components.`
+- **Example**:
+```tsx
+<Card><CardHeader><CardTitle>Title</CardTitle><CardDescription>Description</CardDescription></CardHeader><CardContent>Content</CardContent></Card>
+```
+
+#### Accordion
+- **File**: `components/ui/accordion.tsx`
+- **Exports**: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
+- **Description**: Expandable sections using Radix Accordion.
+- **Props**: `type: "single" | "multiple"; collapsible?: boolean`
+- **Example**:
+```tsx
+<Accordion type="single" collapsible><AccordionItem value="item-1"><AccordionTrigger>Section 1</AccordionTrigger><AccordionContent>Content</AccordionContent></AccordionItem></Accordion>
+```
+
+#### Tabs
+- **File**: `components/ui/tabs.tsx`
+- **Exports**: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
+- **Description**: Tab navigation using Radix Tabs. Pill-style triggers.
+- **Props**: `value?: string; onValueChange?: (value: string) => void`
+- **Example**:
+```tsx
+<Tabs defaultValue="tab1"><TabsList><TabsTrigger value="tab1">Tab 1</TabsTrigger></TabsList><TabsContent value="tab1">Content</TabsContent></Tabs>
+```
+
+#### Separator
+- **File**: `components/ui/separator.tsx`
+- **Exports**: `Separator`
+- **Description**: Visual divider line. Horizontal or vertical.
+- **Props**: `orientation?: "horizontal" | "vertical"; decorative?: boolean`
+- **Example**:
+```tsx
+<Separator />
+```
+
+### Overlay
+
+#### Dialog
+- **File**: `components/ui/dialog.tsx`
+- **Exports**: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`
+- **Description**: Modal dialog using Radix Dialog.
+- **Props**: `open?: boolean; onOpenChange?: (open: boolean) => void`
+- **Example**:
+```tsx
+<Dialog><DialogTrigger asChild><Button>Open</Button></DialogTrigger><DialogContent><DialogHeader><DialogTitle>Title</DialogTitle></DialogHeader></DialogContent></Dialog>
+```
+
+#### AlertDialog
+- **File**: `components/ui/alert-dialog.tsx`
+- **Exports**: `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogHeader`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogFooter`, `AlertDialogAction`, `AlertDialogCancel`
+- **Description**: Confirmation dialog requiring user action.
+- **Props**: `open?: boolean; onOpenChange?: (open: boolean) => void`
+- **Example**:
+```tsx
+<AlertDialog><AlertDialogTrigger asChild><Button variant="destructive">Delete</Button></AlertDialogTrigger><AlertDialogContent>...</AlertDialogContent></AlertDialog>
+```
+
+#### Tooltip
+- **File**: `components/ui/tooltip.tsx`
+- **Exports**: `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`
+- **Description**: Tooltip popup (0ms delay) using Radix Tooltip.
+- **Props**: `Standard Radix Tooltip props`
+- **Example**:
+```tsx
+<TooltipProvider><Tooltip><TooltipTrigger>Hover me</TooltipTrigger><TooltipContent>Tooltip text</TooltipContent></Tooltip></TooltipProvider>
+```
+
+#### Popover
+- **File**: `components/ui/popover.tsx`
+- **Exports**: `Popover`, `PopoverTrigger`, `PopoverContent`
+- **Description**: Floating content panel using Radix Popover.
+- **Props**: `open?: boolean; onOpenChange?: (open: boolean) => void`
+- **Example**:
+```tsx
+<Popover><PopoverTrigger asChild><Button>Open</Button></PopoverTrigger><PopoverContent>Content</PopoverContent></Popover>
+```
+
+#### Drawer
+- **File**: `components/ui/drawer.tsx`
+- **Exports**: `Drawer`, `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerTitle`, `DrawerDescription`, `DrawerFooter`, `DrawerClose`
+- **Description**: Bottom sheet drawer using Vaul.
+- **Props**: `open?: boolean; onOpenChange?: (open: boolean) => void`
+- **Example**:
+```tsx
+<Drawer><DrawerTrigger asChild><Button>Open</Button></DrawerTrigger><DrawerContent><DrawerHeader><DrawerTitle>Title</DrawerTitle></DrawerHeader></DrawerContent></Drawer>
+```
+
+### Navigation
+
+#### Navbar
+- **File**: `components/ui/navbar.tsx`
+- **Exports**: `Navbar`, `NavbarLink`, `navbarVariants`
+- **Description**: Top navigation bar. Fixed top, z-50, h-16. Variants: solid, transparent, minimal. Logo left, nav center, actions right. Mobile hamburger.
+- **Props**: `variant?: "solid" | "transparent" | "minimal"; logo?: ReactNode; actions?: ReactNode`
+- **Example**:
+```tsx
+<Navbar variant="solid" logo={<Logo size="sm" />}><NavbarLink href="/">Home</NavbarLink></Navbar>
+```
+
+#### Breadcrumb
+- **File**: `components/ui/breadcrumb.tsx`
+- **Exports**: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`
+- **Description**: Breadcrumb navigation trail.
+- **Props**: `Standard list composition`
+- **Example**:
+```tsx
+<Breadcrumb><BreadcrumbList><BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem><BreadcrumbSeparator /><BreadcrumbItem><BreadcrumbPage>Current</BreadcrumbPage></BreadcrumbItem></BreadcrumbList></Breadcrumb>
+```
+
+#### Pagination
+- **File**: `components/ui/pagination.tsx`
+- **Exports**: `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis`
+- **Description**: Page navigation controls.
+- **Props**: `Standard list composition with PaginationLink items`
+- **Example**:
+```tsx
+<Pagination><PaginationContent><PaginationItem><PaginationPrevious href="#" /></PaginationItem><PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem><PaginationItem><PaginationNext href="#" /></PaginationItem></PaginationContent></Pagination>
+```
+
+### Data
+
+#### Table
+- **File**: `components/ui/table.tsx`
+- **Exports**: `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`, `TableFooter`
+- **Description**: Data table with header, body, footer.
+- **Props**: `Standard HTML table element composition`
+- **Example**:
+```tsx
+<Table><TableHeader><TableRow><TableHead>Name</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>John</TableCell></TableRow></TableBody></Table>
+```
+
+#### Progress
+- **File**: `components/ui/progress.tsx`
+- **Exports**: `Progress`
+- **Description**: Progress bar using Radix Progress.
+- **Props**: `value?: number (0-100)`
+- **Example**:
+```tsx
+<Progress value={60} />
+```
+
+#### Avatar
+- **File**: `components/ui/avatar.tsx`
+- **Exports**: `Avatar`, `AvatarImage`, `AvatarFallback`
+- **Description**: User avatar with image and fallback.
+- **Props**: `Standard Radix Avatar composition`
+- **Example**:
+```tsx
+<Avatar><AvatarImage src="/avatar.jpg" /><AvatarFallback>JD</AvatarFallback></Avatar>
+```
+
+#### Calendar
+- **File**: `components/ui/calendar.tsx`
+- **Exports**: `Calendar`
+- **Description**: Date picker calendar using react-day-picker.
+- **Props**: `mode?: "single" | "range" | "multiple"; selected?: Date; onSelect?: (date: Date) => void`
+- **Example**:
+```tsx
+<Calendar mode="single" selected={date} onSelect={setDate} />
+```
+
+### Feedback
+
+#### Alert
+- **File**: `components/ui/alert.tsx`
+- **Exports**: `Alert`, `AlertTitle`, `AlertDescription`
+- **Description**: Inline alert message. Variants: default, destructive.
+- **Props**: `variant?: "default" | "destructive"`
+- **Example**:
+```tsx
+<Alert><AlertTitle>Heads up!</AlertTitle><AlertDescription>This is an alert.</AlertDescription></Alert>
+```
+
+#### Skeleton
+- **File**: `components/ui/skeleton.tsx`
+- **Exports**: `Skeleton`
+- **Description**: Loading placeholder with pulse animation.
+- **Props**: `Standard div props (set dimensions with className)`
+- **Example**:
+```tsx
+<Skeleton className="h-4 w-[250px]" />
+```
+
+#### Spinner
+- **File**: `components/ui/spinner.tsx`
+- **Exports**: `Spinner`
+- **Description**: Loading spinner (Loader2Icon with spin animation).
+- **Props**: `Standard SVG icon props`
+- **Example**:
+```tsx
+<Spinner />
+```
+
+#### Empty
+- **File**: `components/ui/empty.tsx`
+- **Exports**: `Empty`
+- **Description**: Empty state placeholder with header/media/title/description.
+- **Props**: `Standard composition with sub-components`
+- **Example**:
+```tsx
+<Empty><EmptyTitle>No results</EmptyTitle><EmptyDescription>Try a different search</EmptyDescription></Empty>
+```
+
+### Form
+
+#### Form
+- **File**: `components/ui/form.tsx`
+- **Exports**: `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`
+- **Description**: Form wrapper using react-hook-form. Provides field-level validation and error display via Zod.
+- **Props**: `Wraps react-hook-form useForm return value. FormField takes name + render prop.`
+- **Example**:
+```tsx
+<Form {...form}><FormField name="email" render={({field}) => (<FormItem><FormLabel>Email</FormLabel><FormControl><Input {...field} /></FormControl><FormMessage /></FormItem>)} /></Form>
+```
+
+### Composition
+
+#### Logo
+- **File**: `components/ui/logo.tsx`
+- **Exports**: `Logo`, `logoVariants`
+- **Description**: Greyhaven logo SVG. Size: sm/md/lg/xl. Variant: color (orange icon + foreground text) or monochrome (all foreground).
+- **Props**: `size?: "sm" | "md" | "lg" | "xl"; variant?: "color" | "monochrome"`
+- **Example**:
+```tsx
+<Logo size="md" variant="color" />
+```
+
+#### Hero
+- **File**: `components/ui/hero.tsx`
+- **Exports**: `Hero`, `heroVariants`
+- **Description**: Full-width hero section. Variants: centered, left-aligned, split (text + media). Heading in Source Serif, subheading in sans.
+- **Props**: `variant?: "centered" | "left-aligned" | "split"; background?: "default" | "muted" | "accent" | "dark"; heading: ReactNode; subheading?: ReactNode; actions?: ReactNode; media?: ReactNode`
+- **Example**:
+```tsx
+<Hero variant="centered" heading="Build something great" subheading="With the Greyhaven Design System" actions={<Button>Get Started</Button>} />
+```
+
+#### CTASection
+- **File**: `components/ui/cta-section.tsx`
+- **Exports**: `CTASection`, `ctaSectionVariants`
+- **Description**: Call-to-action section block. Centered or left-aligned, with heading, description, and action buttons.
+- **Props**: `variant?: "centered" | "left-aligned"; background?: "default" | "muted" | "accent" | "subtle"; heading: ReactNode; description?: ReactNode; actions?: ReactNode`
+- **Example**:
+```tsx
+<CTASection heading="Ready to start?" description="Join thousands of developers" actions={<Button>Sign up free</Button>} />
+```
+
+#### Section
+- **File**: `components/ui/section.tsx`
+- **Exports**: `Section`, `sectionVariants`
+- **Description**: Titled content section with spacing. py-16 between sections.
+- **Props**: `variant?: "default" | "highlighted" | "accent"; width?: "narrow" | "default" | "wide" | "full"; title?: string; description?: string`
+- **Example**:
+```tsx
+<Section title="Features" description="What we offer" width="wide">Content</Section>
+```
+
+#### Footer
+- **File**: `components/ui/footer.tsx`
+- **Exports**: `Footer`, `footerVariants`
+- **Description**: Page footer. Minimal (single row) or full (multi-column with link groups).
+- **Props**: `variant?: "minimal" | "full"; logo?: ReactNode; copyright?: ReactNode; linkGroups?: FooterLinkGroup[]; actions?: ReactNode`
+- **Example**:
+```tsx
+<Footer variant="minimal" copyright="&copy; 2024 Greyhaven" />
+```
+
+#### PageLayout
+- **File**: `components/ui/page-layout.tsx`
+- **Exports**: `PageLayout`
+- **Description**: Full page shell composing Navbar + main content + optional sidebar + Footer. Auto-offsets for fixed navbar.
+- **Props**: `navbar?: ReactNode; sidebar?: ReactNode; footer?: ReactNode`
+- **Example**:
+```tsx
+<PageLayout navbar={<Navbar />} footer={<Footer />}>Main content</PageLayout>
+```
+
+
+---
+
+## 4. Composition Rules
+
+- **Card spacing**: `gap-6` between cards, `p-6` internal padding
+- **Section rhythm**: `py-16` between major page sections
+- **Button placement**: Primary action right, secondary left
+- **Form layout**: Vertical stack with `gap-4`, labels above inputs
+- **Navbar**: Fixed top, `z-50`, `h-16`, logo left, nav center, actions right
+- **Typography pairing**: Serif (`font-serif`) for content headings, sans (`font-sans`) for UI labels/buttons
+- **Color restraint**: Orange ONLY for primary actions and key emphasis -- never decorative
+- **Focus pattern**: `focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]`
+- **Disabled pattern**: `disabled:pointer-events-none disabled:opacity-50`
+- **Aria-invalid pattern**: `aria-invalid:ring-destructive/20 aria-invalid:border-destructive`
+- **Slot naming**: All components use `data-slot="component-name"`
+- **Icon sizing**: `[&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0`
+
+
+---
+
+## 5. Extension Protocol
+
+When adding new components to the system:
+
+1. **Use CVA** for variants (`class-variance-authority`)
+2. **Accept HTML element props** via spread: `React.ComponentProps<'div'>`
+3. **Use `data-slot`** attribute: `data-slot="component-name"`
+4. **Use `cn()`** from `@/lib/utils` for class merging
+5. **Follow focus/disabled/aria patterns** from existing components
+6. **Use semantic tokens only** -- never raw hex colors
+7. **Support `asChild`** via `@radix-ui/react-slot` for polymorphism where appropriate
+8. **Add to Storybook** with `tags: ['autodocs']` and all variant stories
+9. **Add to `lib/catalog.ts`** so MCP server and SKILL.md pick it up automatically
+10. **Run `pnpm skill:build`** to regenerate this file
+
+### Template
+
+```tsx
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '@/lib/utils'
+
+const myComponentVariants = cva('base-classes', {
+  variants: {
+    variant: {
+      default: 'default-classes',
+    },
+    size: {
+      default: 'size-classes',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+    size: 'default',
+  },
+})
+
+function MyComponent({
+  className,
+  variant,
+  size,
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof myComponentVariants>) {
+  return (
+    <div
+      data-slot="my-component"
+      className={cn(myComponentVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { MyComponent, myComponentVariants }
+```
--- a/skill/install.sh
+++ b/skill/install.sh
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# install.sh — Symlink the Greyhaven Design System SKILL.md into a consuming project's
+# .claude/skills/ directory so that any Claude Code session gets full design system context.
+#
+# Usage:
+#   From the greyhaven-design-system repo:
+#     ./skill/install.sh /path/to/your/project
+#
+#   Or from any directory:
+#     /path/to/greyhaven-design-system/skill/install.sh /path/to/your/project
+
+set -euo pipefail
+
+# Resolve the absolute path of the SKILL.md file relative to this script
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_FILE="${SCRIPT_DIR}/SKILL.md"
+
+# Validate SKILL.md exists
+if [ ! -f "$SKILL_FILE" ]; then
+  echo "Error: SKILL.md not found at ${SKILL_FILE}"
+  exit 1
+fi
+
+# Get target project directory from argument or prompt
+if [ $# -ge 1 ]; then
+  TARGET_PROJECT="$1"
+else
+  echo "Usage: $0 <target-project-directory>"
+  echo ""
+  echo "Example:"
+  echo "  $0 /path/to/my-app"
+  echo "  $0 ."
+  exit 1
+fi
+
+# Resolve to absolute path
+TARGET_PROJECT="$(cd "$TARGET_PROJECT" && pwd)"
+
+# Validate target directory exists
+if [ ! -d "$TARGET_PROJECT" ]; then
+  echo "Error: Directory not found: ${TARGET_PROJECT}"
+  exit 1
+fi
+
+# Create .claude/skills/ directory in target project if it doesn't exist
+SKILLS_DIR="${TARGET_PROJECT}/.claude/skills"
+mkdir -p "$SKILLS_DIR"
+
+# Create the symlink
+LINK_PATH="${SKILLS_DIR}/greyhaven-design-system.md"
+
+if [ -L "$LINK_PATH" ]; then
+  echo "Updating existing symlink at ${LINK_PATH}"
+  rm "$LINK_PATH"
+elif [ -f "$LINK_PATH" ]; then
+  echo "Warning: ${LINK_PATH} exists as a regular file. Backing up to ${LINK_PATH}.bak"
+  mv "$LINK_PATH" "${LINK_PATH}.bak"
+fi
+
+ln -s "$SKILL_FILE" "$LINK_PATH"
+
+echo "Done! Greyhaven Design System skill installed."
+echo ""
+echo "  Symlink: ${LINK_PATH}"
+echo "  Target:  ${SKILL_FILE}"
+echo ""
+echo "Any Claude Code session in ${TARGET_PROJECT} will now have"
+echo "full Greyhaven Design System context available."