@hex-core/components 1.3.1 → 1.4.0

package/dist/schemas.js

@@ -0,0 +1,4643 @@
+// src/primitives/button/button.schema.ts
+var buttonSchema = {
+  name: "button",
+  displayName: "Button",
+  description: "A versatile button component with multiple variants, sizes, and states. Supports icons, loading state, and composition via asChild.",
+  category: "primitive",
+  subcategory: "actions",
+  props: [
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "The visual style of the button",
+      enumValues: ["default", "destructive", "outline", "secondary", "ghost", "link"]
+    },
+    {
+      name: "size",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "The size of the button",
+      enumValues: ["default", "sm", "lg", "icon"]
+    },
+    {
+      name: "asChild",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Render as a Slot component, merging props with the child element. Use to render as a link or other element."
+    },
+    {
+      name: "loading",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Show loading spinner and disable interaction"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the button"
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes to merge with the component styles"
+    }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Visual style variants",
+      values: [
+        {
+          value: "default",
+          description: "Primary filled button with subtle shadow for main actions",
+          useWhen: "the single most important action on the screen \u2014 exactly one per view (Save, Submit, Continue)"
+        },
+        {
+          value: "destructive",
+          description: "Red button with shadow for dangerous/irreversible actions",
+          useWhen: "the action cannot be undone without recreating data: Delete, Archive, Deactivate, Leave team, Force-quit"
+        },
+        {
+          value: "outline",
+          description: "Bordered button with hover fill for secondary actions",
+          useWhen: "tertiary actions on a flat (non-elevated) surface; signals 'optional' next to a primary"
+        },
+        {
+          value: "secondary",
+          description: "Muted filled button for less prominent actions",
+          useWhen: "the second-most-important action next to a primary CTA: Cancel, Save Draft, Skip"
+        },
+        {
+          value: "ghost",
+          description: "Transparent button, background appears on hover",
+          useWhen: "low-emphasis action inside a list, toolbar, or row where chrome should disappear at rest"
+        },
+        {
+          value: "link",
+          description: "Styled as a hyperlink with underline on hover, no padding",
+          useWhen: "an inline action inside flowing text, or a 'Learn more' affordance in an empty state"
+        }
+      ],
+      default: "default"
+    },
+    {
+      name: "size",
+      description: "Size variants",
+      values: [
+        {
+          value: "default",
+          description: "Standard size (h-10, px-4)",
+          useWhen: "default everywhere; the only size you need on most surfaces"
+        },
+        {
+          value: "sm",
+          description: "Compact size (h-9, px-3)",
+          useWhen: "buttons living inside a row, toolbar, or table cell where vertical density matters"
+        },
+        {
+          value: "lg",
+          description: "Large size (h-11, px-8, text-base)",
+          useWhen: "the single hero CTA on a marketing page, pricing card, or empty-state action"
+        },
+        {
+          value: "icon",
+          description: "Square icon-only size (h-10, w-10)",
+          useWhen: "icon-only actions (close, settings, more). Always pair with aria-label"
+        }
+      ],
+      default: "default"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Button label content",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority", "@radix-ui/react-slot", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [
+    "primary",
+    "primary-foreground",
+    "destructive",
+    "destructive-foreground",
+    "secondary",
+    "secondary-foreground",
+    "accent",
+    "accent-foreground",
+    "background",
+    "input",
+    "ring"
+  ],
+  examples: [
+    {
+      title: "Basic usage",
+      description: "A simple primary button",
+      code: "<Button>Click me</Button>",
+      composition: ["form-action"]
+    },
+    {
+      title: "Variants",
+      description: "Different visual styles",
+      code: '<>\n  <Button variant="default">Primary</Button>\n  <Button variant="outline">Outline</Button>\n  <Button variant="secondary">Secondary</Button>\n  <Button variant="ghost">Ghost</Button>\n  <Button variant="destructive">Delete</Button>\n  <Button variant="link">Link</Button>\n</>',
+      composition: ["showcase"]
+    },
+    {
+      title: "Destructive confirm in dialog",
+      description: "The canonical destructive action, paired with Cancel inside an alert-dialog footer",
+      code: '<AlertDialog>\n  <AlertDialogTrigger asChild>\n    <Button variant="outline">Delete account</Button>\n  </AlertDialogTrigger>\n  <AlertDialogContent>\n    <AlertDialogHeader>\n      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>\n      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>\n    </AlertDialogHeader>\n    <AlertDialogFooter>\n      <AlertDialogCancel>Cancel</AlertDialogCancel>\n      <AlertDialogAction variant="destructive">Delete</AlertDialogAction>\n    </AlertDialogFooter>\n  </AlertDialogContent>\n</AlertDialog>',
+      composition: ["dialog", "alert-dialog", "destructive", "confirm"]
+    },
+    {
+      title: "Form action pair",
+      description: "Primary submit + secondary cancel \u2014 the universal end-of-form pattern",
+      code: '<div className="flex justify-end gap-2">\n  <Button variant="secondary" type="button">Cancel</Button>\n  <Button type="submit">Save changes</Button>\n</div>',
+      composition: ["form", "form-action"]
+    },
+    {
+      title: "With loading state",
+      description: "Button showing a spinner while loading",
+      code: "<Button loading>Submitting...</Button>",
+      composition: ["form-action", "async"]
+    },
+    {
+      title: "As link",
+      description: "Button rendered as an anchor tag",
+      code: '<Button asChild>\n  <a href="/login">Login</a>\n</Button>',
+      composition: ["navigation", "as-child"]
+    },
+    {
+      title: "Icon button",
+      description: "Square button with just an icon",
+      code: '<Button variant="outline" size="icon" aria-label="Settings">\n  <SettingsIcon />\n</Button>',
+      composition: ["icon-only", "toolbar"]
+    },
+    {
+      title: "Leading icon",
+      description: "Button with an icon before its label \u2014 clarifies intent without sacrificing readability",
+      code: "<Button>\n  <PlusIcon />\n  Add member\n</Button>",
+      composition: ["icon-leading", "form-action"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use for clickable actions: form submissions, confirmations, triggering operations. Use 'default' variant for primary CTAs, 'outline' or 'secondary' for less important actions, 'ghost' for toolbar-style actions.",
+    whenNotToUse: "Don't use for navigation between pages (use Link or anchor with asChild). Don't use 'destructive' for non-dangerous actions. Don't use for toggling state (use Toggle or Switch).",
+    commonMistakes: [
+      "Nesting interactive elements inside asChild button",
+      "Using <Button> with plain onClick for navigation instead of <Button asChild><a href=...></a></Button> \u2014 breaks middle-click, cmd-click, and right-click \u2192 'open in new tab', and skips the browser history entry",
+      "Using <Button variant='destructive'> for recoverable actions like 'Reset filters' \u2014 reserve destructive for delete/archive/leave; use 'secondary' or 'ghost' for resets",
+      "Using <Button size='icon'> without an aria-label \u2014 screen readers have nothing to announce; always pair icon-only buttons with aria-label or visible text"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using <Button> to flip a boolean state on/off (volume mute, dark mode, airplane mode)",
+        insteadUse: "switch",
+        why: "Switch communicates the on/off semantic to assistive tech (role=switch + aria-checked). A button announces 'press' which loses the state semantic."
+      },
+      {
+        mistake: "Using <Button> as a tab to switch between sibling content panels",
+        insteadUse: "tabs",
+        why: "Tabs ship role=tablist + roving tabindex + arrow-key navigation. Buttons in a row don't \u2014 assistive tech will announce them as N independent actions instead of a tab group."
+      },
+      {
+        mistake: "Using <Button> to expand/collapse a content section",
+        insteadUse: "accordion",
+        why: "Accordion handles aria-expanded / aria-controls automatically and ships the chevron rotation animation. A bare button doing the same job is missing those affordances."
+      }
+    ],
+    relatedComponents: ["toggle", "toggle-group", "dropdown-menu", "badge"],
+    accessibilityNotes: "Automatically handles focus ring, disabled state, and aria attributes. Icon-only buttons MUST have aria-label. Loading state automatically sets disabled.",
+    tokenBudget: 500
+  },
+  tags: ["button", "action", "cta", "form", "interactive", "click"]
+};
+
+// src/primitives/input/input.schema.ts
+var inputSchema = {
+  name: "input",
+  displayName: "Input",
+  description: "A styled text input with smooth focus transitions, shadow effects, and full HTML input compatibility.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    {
+      name: "type",
+      type: "enum",
+      required: false,
+      default: "text",
+      description: "The HTML input type",
+      enumValues: ["text", "password", "email", "number", "search", "tel", "url", "file", "hidden"]
+    },
+    {
+      name: "placeholder",
+      type: "string",
+      required: false,
+      description: "Placeholder text shown when the input is empty"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the input"
+    },
+    {
+      name: "value",
+      type: "string",
+      required: false,
+      description: "Controlled input value"
+    },
+    {
+      name: "defaultValue",
+      type: "string",
+      required: false,
+      description: "Default value for uncontrolled usage"
+    },
+    {
+      name: "onChange",
+      type: "function",
+      required: false,
+      description: "Change handler for controlled usage: (e: ChangeEvent<HTMLInputElement>) => void"
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes to merge with the component styles"
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["input", "background", "ring", "muted-foreground", "foreground"],
+  examples: [
+    {
+      title: "Basic usage",
+      description: "A simple text input",
+      code: '<Input placeholder="Enter your name" />'
+    },
+    {
+      title: "Email input",
+      description: "An email-type input",
+      code: '<Input type="email" placeholder="you@example.com" />'
+    },
+    {
+      title: "File upload",
+      description: "File input with styled file button",
+      code: '<Input type="file" />'
+    },
+    {
+      title: "With label",
+      description: "Input paired with a Label component",
+      code: '<div className="grid w-full max-w-sm gap-1.5">\n  <Label htmlFor="email">Email</Label>\n  <Input type="email" id="email" placeholder="Email" />\n</div>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for single-line text input: names, emails, passwords, search, numbers. Always pair with a Label for accessibility.",
+    whenNotToUse: "Don't use for multi-line text (use Textarea). Don't use for selection from predefined options (use Select). Don't use for rich text editing.",
+    commonMistakes: [
+      "Missing associated Label element for accessibility",
+      "Using type='number' without min/max constraints",
+      "Not providing placeholder text for context"
+    ],
+    relatedComponents: ["label", "textarea", "form"],
+    accessibilityNotes: "Always pair with a Label using htmlFor/id. Consider aria-describedby for helper text or error messages.",
+    tokenBudget: 300
+  },
+  tags: ["input", "text", "form", "field", "text-field"]
+};
+
+// src/primitives/label/label.schema.ts
+var labelSchema = {
+  name: "label",
+  displayName: "Label",
+  description: "An accessible label component built on Radix UI Label primitive. Associates with form controls via htmlFor.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    {
+      name: "htmlFor",
+      type: "string",
+      required: false,
+      description: "The id of the form control this label is associated with"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Label text content",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-label", "class-variance-authority", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [],
+  examples: [
+    {
+      title: "Basic usage",
+      description: "A label paired with an input",
+      code: '<div className="grid gap-1.5">\n  <Label htmlFor="name">Name</Label>\n  <Input id="name" placeholder="Enter your name" />\n</div>'
+    },
+    {
+      title: "Required field",
+      description: "Label with required indicator",
+      code: '<Label htmlFor="email">\n  Email <span className="text-destructive">*</span>\n</Label>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use as a label for every form input, select, textarea, checkbox, or radio group. Always use htmlFor to associate with the control's id.",
+    whenNotToUse: "Don't use as a standalone text element \u2014 use a paragraph or heading instead. Don't use for non-form contexts.",
+    commonMistakes: [
+      "Forgetting to set htmlFor matching the input's id",
+      "Using Label for non-form text content",
+      "Nesting interactive elements inside Label"
+    ],
+    relatedComponents: ["input", "textarea", "checkbox", "select", "form"],
+    accessibilityNotes: "Clicking the label focuses the associated control. Automatically communicates the label to screen readers. Use htmlFor/id pairing, not nesting.",
+    tokenBudget: 200
+  },
+  tags: ["label", "form", "accessibility", "text"]
+};
+
+// src/primitives/textarea/textarea.schema.ts
+var textareaSchema = {
+  name: "textarea",
+  displayName: "Textarea",
+  description: "A styled multi-line text input with smooth focus transitions and shadow effects.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    { name: "placeholder", type: "string", required: false, description: "Placeholder text" },
+    { name: "rows", type: "number", required: false, default: 3, description: "Number of visible text rows" },
+    { name: "disabled", type: "boolean", required: false, default: false, description: "Disable the textarea" },
+    { name: "value", type: "string", required: false, description: "Controlled textarea value" },
+    { name: "defaultValue", type: "string", required: false, description: "Default value for uncontrolled usage" },
+    { name: "onChange", type: "function", required: false, description: "Change handler: (e: ChangeEvent<HTMLTextAreaElement>) => void" },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["input", "background", "ring", "muted-foreground"],
+  examples: [
+    { title: "Basic", description: "Simple textarea", code: '<Textarea placeholder="Type your message..." />' },
+    { title: "With label", description: "Textarea paired with a label", code: '<div className="grid gap-1.5">\n  <Label htmlFor="message">Message</Label>\n  <Textarea id="message" placeholder="Type your message..." />\n</div>' }
+  ],
+  ai: {
+    whenToUse: "Use for multi-line text input: comments, descriptions, messages, notes. Always pair with a Label.",
+    whenNotToUse: "Don't use for single-line input (use Input). Don't use for rich text editing.",
+    commonMistakes: ["Missing associated Label", "Not setting a reasonable min-height or rows"],
+    relatedComponents: ["input", "label", "form"],
+    accessibilityNotes: "Always pair with a Label using htmlFor/id. Consider aria-describedby for character limits.",
+    tokenBudget: 250
+  },
+  tags: ["textarea", "text", "form", "multiline", "input"]
+};
+
+// src/primitives/checkbox/checkbox.schema.ts
+var checkboxSchema = {
+  name: "checkbox",
+  displayName: "Checkbox",
+  description: "An accessible checkbox with checked, unchecked, and indeterminate states. Built on Radix UI.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    { name: "checked", type: "boolean", required: false, description: "Controlled checked state" },
+    { name: "defaultChecked", type: "boolean", required: false, description: "Default checked for uncontrolled" },
+    { name: "onCheckedChange", type: "function", required: false, description: "Callback: (checked: boolean | 'indeterminate') => void" },
+    { name: "disabled", type: "boolean", required: false, default: false, description: "Disable the checkbox" },
+    { name: "required", type: "boolean", required: false, default: false, description: "Mark as required for form validation" },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-checkbox", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["input", "primary", "primary-foreground", "ring"],
+  examples: [
+    { title: "Basic", description: "Checkbox with label", code: '<div className="flex items-center gap-2">\n  <Checkbox id="terms" />\n  <Label htmlFor="terms">Accept terms</Label>\n</div>' },
+    { title: "Controlled", description: "Controlled checkbox", code: "const [checked, setChecked] = useState(false);\n<Checkbox checked={checked} onCheckedChange={setChecked} />" },
+    {
+      title: "Indeterminate (parent/children)",
+      description: "Parent renders a dash when some (but not all) children are selected",
+      code: 'const [items, setItems] = useState({ email: true, push: false });\nconst count = Object.values(items).filter(Boolean).length;\nconst parent = count === 0 ? false : count === 2 ? true : "indeterminate";\n\n<Checkbox\n  checked={parent}\n  onCheckedChange={(v) => setItems({ email: v === true, push: v === true })}\n/>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for boolean toggles in forms (agree to terms, enable options), multi-select lists, or parent/children trees where the parent reflects partial selection via the `indeterminate` state.",
+    whenNotToUse: "Don't use for mutually exclusive options (use RadioGroup). Don't use for instant toggles (use Switch).",
+    commonMistakes: [
+      "Missing Label pairing",
+      "Using onChange instead of onCheckedChange",
+      "Forgetting that onCheckedChange can receive 'indeterminate' as well as boolean"
+    ],
+    relatedComponents: ["label", "switch", "form"],
+    accessibilityNotes: "Always pair with Label via htmlFor/id. Radix handles aria-checked automatically.",
+    tokenBudget: 300
+  },
+  tags: ["checkbox", "form", "toggle", "boolean", "check"]
+};
+
+// src/primitives/switch/switch.schema.ts
+var switchSchema = {
+  name: "switch",
+  displayName: "Switch",
+  description: "An accessible toggle switch for instant on/off settings. Built on Radix UI.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    { name: "checked", type: "boolean", required: false, description: "Controlled checked state" },
+    { name: "defaultChecked", type: "boolean", required: false, description: "Default for uncontrolled" },
+    { name: "onCheckedChange", type: "function", required: false, description: "Callback: (checked: boolean) => void" },
+    { name: "disabled", type: "boolean", required: false, default: false, description: "Disable the switch" },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-switch", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "input", "background", "ring"],
+  examples: [
+    {
+      title: "Basic",
+      description: "Switch with label",
+      code: '<div className="flex items-center gap-2">\n  <Switch id="airplane" />\n  <Label htmlFor="airplane">Airplane Mode</Label>\n</div>',
+      composition: ["form", "boolean"]
+    },
+    {
+      title: "Settings row",
+      description: "Right-aligned switch in a settings list \u2014 the canonical Apple-style preference UI",
+      code: '<div className="flex items-center justify-between py-3">\n  <div>\n    <Label htmlFor="notifications">Email notifications</Label>\n    <p className="text-sm text-muted-foreground">Daily digest, mentions, and replies</p>\n  </div>\n  <Switch id="notifications" />\n</div>',
+      composition: ["settings", "preference-row", "boolean"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use for instant-effect boolean settings: dark mode, notifications on/off, feature toggles, airplane mode. The change takes effect immediately \u2014 no submit step.",
+    whenNotToUse: "Don't use for form fields that get submitted in a batch (use Checkbox). Don't use for mutually exclusive options (use RadioGroup). Don't use to filter a list of options (use Toggle or ToggleGroup).",
+    commonMistakes: [
+      "Using Switch for form fields that need explicit submit",
+      "Missing <Label> for the switch \u2014 without htmlFor/id pairing, screen readers announce the toggle without context",
+      "Putting the switch label INSIDE the switch instead of next to it"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using Switch inside a form that gets submitted with a Save button",
+        insteadUse: "checkbox",
+        why: "Switch implies the change applies immediately. A Save button suggests batch submission \u2014 that's Checkbox semantics. Mixing them confuses the user about whether they need to click Save."
+      },
+      {
+        mistake: "Putting two Switches side-by-side to choose between mutually exclusive options",
+        insteadUse: "radio-group",
+        why: "Switches don't represent 'pick one of N'. RadioGroup announces the group + the active selection to assistive tech and prevents the user from selecting both."
+      }
+    ],
+    relatedComponents: ["checkbox", "label", "form", "toggle"],
+    accessibilityNotes: "Always pair with Label (htmlFor / id). Radix handles role='switch' + aria-checked + keyboard activation (Space).",
+    tokenBudget: 350
+  },
+  tags: ["switch", "toggle", "form", "boolean", "setting"]
+};
+
+// src/primitives/badge/badge.schema.ts
+var badgeSchema = {
+  name: "badge",
+  displayName: "Badge",
+  description: "A small status indicator with multiple style variants. Used for tags, statuses, and categorization.",
+  category: "primitive",
+  subcategory: "display",
+  props: [
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Visual style",
+      enumValues: ["default", "secondary", "destructive", "outline"]
+    },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Visual style variants",
+      values: [
+        { value: "default", description: "Primary colored badge" },
+        { value: "secondary", description: "Muted background badge" },
+        { value: "destructive", description: "Red/danger badge" },
+        { value: "outline", description: "Bordered badge, no fill" }
+      ],
+      default: "default"
+    }
+  ],
+  slots: [{ name: "children", description: "Badge content text", required: true, acceptedTypes: ["ReactNode"] }],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "primary-foreground", "secondary", "secondary-foreground", "destructive", "destructive-foreground", "foreground", "ring"],
+  examples: [
+    { title: "Variants", description: "All badge styles", code: '<>\n  <Badge>Default</Badge>\n  <Badge variant="secondary">Secondary</Badge>\n  <Badge variant="destructive">Error</Badge>\n  <Badge variant="outline">Outline</Badge>\n</>' }
+  ],
+  ai: {
+    whenToUse: "Use for status indicators, tags, counts, categories. Place next to headings, in lists, or in table cells.",
+    whenNotToUse: "Don't use for interactive actions (use Button). Don't use for long text content.",
+    commonMistakes: ["Using destructive variant for non-error states", "Badge text too long"],
+    relatedComponents: ["button", "card"],
+    accessibilityNotes: "Purely decorative by default. Add role='status' for dynamic status badges.",
+    tokenBudget: 200
+  },
+  tags: ["badge", "tag", "status", "label", "indicator"]
+};
+
+// src/primitives/separator/separator.schema.ts
+var separatorSchema = {
+  name: "separator",
+  displayName: "Separator",
+  description: "A visual divider between content sections with horizontal or vertical orientation.",
+  category: "primitive",
+  subcategory: "layout",
+  props: [
+    { name: "orientation", type: "enum", required: false, default: "horizontal", description: "Direction of the separator", enumValues: ["horizontal", "vertical"] },
+    { name: "decorative", type: "boolean", required: false, default: true, description: "If true, separator is purely visual and hidden from screen readers" },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-separator", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["border"],
+  examples: [
+    { title: "Horizontal", description: "Default horizontal divider", code: "<Separator />" },
+    { title: "Vertical", description: "Vertical divider in a flex row", code: '<div className="flex h-5 items-center gap-4">\n  <span>Left</span>\n  <Separator orientation="vertical" />\n  <span>Right</span>\n</div>' }
+  ],
+  ai: {
+    whenToUse: "Use to visually separate content sections, menu items, or sidebar groups.",
+    whenNotToUse: "Don't use for spacing (use margin/padding). Don't use between every list item.",
+    commonMistakes: ["Using as spacing instead of semantic separation", "Forgetting orientation='vertical' needs parent height"],
+    relatedComponents: ["card", "breadcrumb", "dropdown-menu", "menubar"],
+    accessibilityNotes: "Set decorative=false if the separator conveys semantic meaning. Radix handles role='separator'.",
+    tokenBudget: 150
+  },
+  tags: ["separator", "divider", "hr", "layout"]
+};
+
+// src/components/card/card.schema.ts
+var cardSchema = {
+  name: "card",
+  displayName: "Card",
+  description: "A container component with header, content, and footer sections. Includes subtle shadow and hover effects.",
+  category: "component",
+  subcategory: "layout",
+  props: [
+    { name: "className", type: "string", required: false, description: "Additional CSS classes on the root card" }
+  ],
+  variants: [],
+  slots: [
+    { name: "children", description: "Card content \u2014 use CardHeader, CardContent, CardFooter subcomponents", required: true, acceptedTypes: ["ReactNode"] }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "border", "muted-foreground"],
+  examples: [
+    {
+      title: "Complete card",
+      description: "Card with header, content, and footer",
+      code: "<Card>\n  <CardHeader>\n    <CardTitle>Create project</CardTitle>\n    <CardDescription>Deploy your new project in one-click.</CardDescription>\n  </CardHeader>\n  <CardContent>\n    <p>Card content here</p>\n  </CardContent>\n  <CardFooter>\n    <Button>Deploy</Button>\n  </CardFooter>\n</Card>",
+      composition: ["showcase", "settings"]
+    },
+    {
+      title: "Stat card",
+      description: "Single-metric dashboard card \u2014 title + large number + trend",
+      code: '<Card>\n  <CardHeader className="pb-2">\n    <CardDescription>Total revenue</CardDescription>\n    <CardTitle className="text-3xl tabular-nums">$45,231.89</CardTitle>\n  </CardHeader>\n  <CardContent>\n    <p className="text-xs text-muted-foreground">+20.1% from last month</p>\n  </CardContent>\n</Card>',
+      composition: ["dashboard", "stat", "metric"]
+    },
+    {
+      title: "Form section card",
+      description: "Card framing a form section, with submit pinned to the footer",
+      code: '<Card>\n  <CardHeader>\n    <CardTitle>Profile</CardTitle>\n    <CardDescription>Update your account details.</CardDescription>\n  </CardHeader>\n  <CardContent className="space-y-4">\n    <Input placeholder="Display name" />\n    <Input type="email" placeholder="Email" />\n  </CardContent>\n  <CardFooter className="justify-end gap-2">\n    <Button variant="secondary">Cancel</Button>\n    <Button type="submit">Save</Button>\n  </CardFooter>\n</Card>',
+      composition: ["form", "settings", "form-action"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use to group related content with a visual boundary: settings panels, product listings, dashboard widgets, form sections, content previews. Each card should feel like one self-contained unit.",
+    whenNotToUse: "Don't use for full-page layouts (use plain divs). Don't use a card to hold one tiny thing (use a Badge or inline content). Don't use a card as a button \u2014 use Button with asChild.",
+    commonMistakes: [
+      "Nesting cards",
+      "Using Card when a simple div with border would suffice",
+      "Forgetting CardContent padding when placing forms inside"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Nesting <Card> inside <Card> to group sub-sections",
+        insteadUse: "separator",
+        why: "Two raised surfaces inside each other muddles the elevation model \u2014 readers can't tell which container 'owns' an action. Use Separator + extra padding within a single Card to visually divide sections, or split into sibling Cards."
+      },
+      {
+        mistake: "Putting an entire Card inside a <button> or <a> to make it clickable",
+        insteadUse: "button",
+        why: "Browsers don't fully support nested interactive content; screen readers announce the full card text every focus. Use <Card asChild><a>...</a></Card> patterns or move just the action inside CardFooter."
+      },
+      {
+        mistake: "Using Card for a top-bar / app-shell wrapper",
+        insteadUse: "container",
+        why: "Card adds elevation chrome that fights with the chrome of the app shell. Use Container for layout boundaries and reserve Card for the content INSIDE the layout."
+      }
+    ],
+    relatedComponents: ["button", "separator", "container", "stack"],
+    accessibilityNotes: "Card is a div by default. Add role='region' and aria-labelledby (pointing to CardTitle's id) for landmark cards. CardTitle renders h3 \u2014 ensure heading hierarchy is correct on the page.",
+    tokenBudget: 400
+  },
+  tags: ["card", "container", "panel", "layout", "surface"]
+};
+
+// src/components/tabs/tabs.schema.ts
+var tabsSchema = {
+  name: "tabs",
+  displayName: "Tabs",
+  description: "A tabbed interface with accessible keyboard navigation. Built on Radix UI Tabs.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    { name: "defaultValue", type: "string", required: false, description: "Default active tab value (uncontrolled)" },
+    { name: "value", type: "string", required: false, description: "Controlled active tab value" },
+    { name: "onValueChange", type: "function", required: false, description: "Callback: (value: string) => void" },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [],
+  slots: [
+    { name: "children", description: "TabsList + TabsContent elements", required: true, acceptedTypes: ["ReactNode"] }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-tabs", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "muted-foreground", "background", "foreground", "ring"],
+  examples: [
+    {
+      title: "Basic tabs",
+      description: "Two-tab interface",
+      code: '<Tabs defaultValue="account">\n  <TabsList>\n    <TabsTrigger value="account">Account</TabsTrigger>\n    <TabsTrigger value="password">Password</TabsTrigger>\n  </TabsList>\n  <TabsContent value="account">Account settings here.</TabsContent>\n  <TabsContent value="password">Password settings here.</TabsContent>\n</Tabs>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use to organize content into switchable panels: settings pages, dashboards, product details with multiple sections.",
+    whenNotToUse: "Don't use for navigation between pages (use router/links). Don't use for steppers/wizards (use a stepper component).",
+    commonMistakes: ["Missing defaultValue causing no tab selected initially", "TabsTrigger value not matching TabsContent value", "Using for page navigation instead of in-page content switching"],
+    relatedComponents: ["card", "separator"],
+    accessibilityNotes: "Full keyboard navigation built-in (arrow keys, Home, End). Radix handles aria-selected, role='tabpanel', etc.",
+    tokenBudget: 350
+  },
+  tags: ["tabs", "navigation", "panel", "tabbed", "sections"]
+};
+
+// src/components/accordion/accordion.schema.ts
+var accordionSchema = {
+  name: "accordion",
+  displayName: "Accordion",
+  description: "A vertically stacked set of collapsible content sections. Built on Radix UI Accordion.",
+  category: "component",
+  subcategory: "disclosure",
+  props: [
+    { name: "type", type: "enum", required: true, description: "Single allows one item open at a time, multiple allows many", enumValues: ["single", "multiple"] },
+    { name: "defaultValue", type: "string", required: false, description: "Default open item(s): string for type='single', string[] for type='multiple'" },
+    { name: "value", type: "string", required: false, description: "Controlled open item(s): string for type='single', string[] for type='multiple'" },
+    { name: "onValueChange", type: "function", required: false, description: "Callback when open items change: (value: string) => void for single, (value: string[]) => void for multiple" },
+    { name: "collapsible", type: "boolean", required: false, default: false, description: "Allow all items to be closed (type='single' only)" },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [],
+  slots: [
+    { name: "children", description: "AccordionItem elements", required: true, acceptedTypes: ["ReactNode"] }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-accordion", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["border"],
+  examples: [
+    {
+      title: "FAQ accordion",
+      description: "Single-open accordion for FAQ sections",
+      code: '<Accordion type="single" collapsible>\n  <AccordionItem value="item-1">\n    <AccordionTrigger>Is it accessible?</AccordionTrigger>\n    <AccordionContent>Yes, it adheres to the WAI-ARIA design pattern.</AccordionContent>\n  </AccordionItem>\n  <AccordionItem value="item-2">\n    <AccordionTrigger>Is it styled?</AccordionTrigger>\n    <AccordionContent>Yes, with Tailwind CSS and smooth animations.</AccordionContent>\n  </AccordionItem>\n</Accordion>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for FAQ sections, settings groups, or any content that benefits from progressive disclosure. Use type='single' for FAQs, type='multiple' for settings.",
+    whenNotToUse: "Don't use for navigation (use tabs). Don't use for a single collapsible (use Collapsible).",
+    commonMistakes: ["Forgetting type prop (it's required)", "Not setting collapsible=true for single type when all items should be closeable", "Missing value on AccordionItem"],
+    relatedComponents: ["tabs", "card"],
+    accessibilityNotes: "Full keyboard navigation (arrow keys, Home, End, Enter/Space). Radix handles aria-expanded, aria-controls, role='region'.",
+    tokenBudget: 400
+  },
+  tags: ["accordion", "collapsible", "faq", "disclosure", "expandable"]
+};
+
+// src/components/dialog/dialog.schema.ts
+var dialogSchema = {
+  name: "dialog",
+  displayName: "Dialog",
+  description: "A modal dialog that interrupts the user with important content. Built on Radix UI with focus trap, escape handling, and scroll lock.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    {
+      name: "open",
+      type: "boolean",
+      required: false,
+      description: "Controlled open state"
+    },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Default open state for uncontrolled usage"
+    },
+    {
+      name: "onOpenChange",
+      type: "function",
+      required: false,
+      description: "Callback fired when open state changes: (open: boolean) => void"
+    },
+    {
+      name: "modal",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "When true, content outside the dialog is inert"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "DialogTrigger + DialogContent (with DialogHeader, DialogFooter, etc.)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-dialog", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "foreground", "muted-foreground", "border", "ring"],
+  examples: [
+    {
+      title: "Edit profile",
+      description: "Dialog wrapping a short form \u2014 the canonical 'edit detail in place' pattern",
+      code: '<Dialog>\n  <DialogTrigger asChild>\n    <Button variant="outline">Edit Profile</Button>\n  </DialogTrigger>\n  <DialogContent>\n    <DialogHeader>\n      <DialogTitle>Edit profile</DialogTitle>\n      <DialogDescription>Make changes to your profile here.</DialogDescription>\n    </DialogHeader>\n    <div className="grid gap-4 py-4">\n      <Input placeholder="Name" />\n    </div>\n    <DialogFooter>\n      <Button>Save changes</Button>\n    </DialogFooter>\n  </DialogContent>\n</Dialog>',
+      composition: ["form", "edit-in-place"]
+    },
+    {
+      title: "Confirm dialog",
+      description: "Non-destructive confirmation with primary + secondary actions",
+      code: '<Dialog>\n  <DialogTrigger asChild>\n    <Button>Publish post</Button>\n  </DialogTrigger>\n  <DialogContent>\n    <DialogHeader>\n      <DialogTitle>Publish post?</DialogTitle>\n      <DialogDescription>Your followers will be notified by email.</DialogDescription>\n    </DialogHeader>\n    <DialogFooter>\n      <DialogClose asChild>\n        <Button variant="secondary">Cancel</Button>\n      </DialogClose>\n      <Button>Publish</Button>\n    </DialogFooter>\n  </DialogContent>\n</Dialog>',
+      composition: ["confirm", "form-action"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use for focused, interruptive tasks: short forms, confirmations, detail views. The user must address the dialog before continuing.",
+    whenNotToUse: "Don't use for destructive confirmations (use AlertDialog). Don't use for complex multi-step flows (use a full page). Don't use for non-critical info (use Tooltip or Popover). Don't use for mobile-bottom-sheet patterns (use Drawer).",
+    commonMistakes: [
+      "Nesting dialogs inside each other",
+      "Forgetting DialogTitle (breaks accessibility \u2014 screen readers need it)",
+      "Using DialogDescription for long-form content (keep it short)",
+      "Putting too many primary actions in DialogFooter"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using <Dialog> for irreversible actions like Delete account",
+        insteadUse: "alert-dialog",
+        why: "AlertDialog uses role='alertdialog' which forces the user to interact (cannot click-outside to dismiss) and announces destructively to screen readers. Dialog can be dismissed by clicking the overlay \u2014 the wrong default for delete confirmations."
+      },
+      {
+        mistake: "Using <Dialog> for a long multi-step wizard",
+        insteadUse: "stepper",
+        why: "Modals trap focus and disable scroll on the page below \u2014 that fights long content. Multi-step flows belong on a full page with a Stepper for orientation."
+      },
+      {
+        mistake: "Using <Dialog> for the mobile-only 'pull up from bottom' interaction",
+        insteadUse: "drawer",
+        why: "Drawer is purpose-built for the bottom-sheet gesture (swipe handle, drag-to-dismiss). Dialog will technically work but loses the native-feeling affordance."
+      },
+      {
+        mistake: "Putting two equal-weight primary buttons in DialogFooter ('Save and continue' + 'Save and close')",
+        insteadUse: "button",
+        why: "Two primaries dilute the call to action \u2014 users hesitate. Pick one primary; demote the other to secondary or split them via a DropdownMenu attached to a single Button."
+      }
+    ],
+    relatedComponents: ["alert-dialog", "popover", "sheet", "drawer"],
+    accessibilityNotes: "Radix traps focus, handles Escape to close, and wires aria-labelledby/describedby to DialogTitle/DialogDescription. Always include a DialogTitle. DialogContent is constrained to `max-h-[calc(100vh-2rem)]` and scrolls internally so long content stays inside the focus trap.",
+    tokenBudget: 600
+  },
+  tags: ["dialog", "modal", "overlay", "popup", "form"]
+};
+
+// src/components/alert-dialog/alert-dialog.schema.ts
+var alertDialogSchema = {
+  name: "alert-dialog",
+  displayName: "Alert Dialog",
+  description: "A modal dialog for destructive confirmations. The user must explicitly accept or cancel \u2014 there is no close button. Built on Radix UI AlertDialog.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    { name: "open", type: "boolean", required: false, description: "Controlled open state" },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Default open state for uncontrolled usage"
+    },
+    {
+      name: "onOpenChange",
+      type: "function",
+      required: false,
+      description: "Callback fired on open state change: (open: boolean) => void"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "AlertDialogTrigger + AlertDialogContent (with Header, Footer, Action, Cancel)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-alert-dialog", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [
+    "background",
+    "foreground",
+    "muted-foreground",
+    "destructive",
+    "destructive-foreground",
+    "accent",
+    "accent-foreground",
+    "border",
+    "input",
+    "ring"
+  ],
+  examples: [
+    {
+      title: "Destructive confirmation",
+      description: "Confirm before deleting a resource",
+      code: '<AlertDialog>\n  <AlertDialogTrigger asChild>\n    <Button variant="destructive">Delete account</Button>\n  </AlertDialogTrigger>\n  <AlertDialogContent>\n    <AlertDialogHeader>\n      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>\n      <AlertDialogDescription>\n        This action cannot be undone. This will permanently delete your account.\n      </AlertDialogDescription>\n    </AlertDialogHeader>\n    <AlertDialogFooter>\n      <AlertDialogCancel>Cancel</AlertDialogCancel>\n      <AlertDialogAction>Yes, delete</AlertDialogAction>\n    </AlertDialogFooter>\n  </AlertDialogContent>\n</AlertDialog>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for destructive or irreversible confirmations: delete account, discard changes, permanent actions. The user must explicitly choose Action or Cancel.",
+    whenNotToUse: "Don't use for non-destructive dialogs (use Dialog). Don't use for simple notifications (use Toast). Don't use when there's only one action to take.",
+    commonMistakes: [
+      "Using Dialog when AlertDialog is semantically required",
+      "Omitting AlertDialogCancel (user must have an escape hatch)",
+      "Putting more than one AlertDialogAction (the pattern expects one destructive action)",
+      "Making the action button non-destructive styled"
+    ],
+    relatedComponents: ["dialog", "toast"],
+    accessibilityNotes: "Radix sets role='alertdialog', traps focus, focuses AlertDialogCancel by default, and closes on Escape. Clicks outside the dialog are prevented (user must choose Cancel or Action).",
+    tokenBudget: 650
+  },
+  tags: ["alert-dialog", "confirm", "destructive", "modal", "overlay"]
+};
+
+// src/components/dropdown-menu/dropdown-menu.schema.ts
+var dropdownMenuSchema = {
+  name: "dropdown-menu",
+  displayName: "Dropdown Menu",
+  description: "A menu of actions displayed to the user when a trigger is activated. Supports items, checkboxes, radio groups, sub-menus, and keyboard shortcuts.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    { name: "open", type: "boolean", required: false, description: "Controlled open state" },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Default open state"
+    },
+    {
+      name: "onOpenChange",
+      type: "function",
+      required: false,
+      description: "Callback on open state change: (open: boolean) => void"
+    },
+    {
+      name: "modal",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "When true, interaction outside the menu is blocked"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "DropdownMenuTrigger + DropdownMenuContent (with Items, CheckboxItems, etc.)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-dropdown-menu", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["popover", "popover-foreground", "accent", "accent-foreground", "muted", "muted-foreground", "border"],
+  examples: [
+    {
+      title: "Basic dropdown",
+      description: "Standard action menu",
+      code: '<DropdownMenu>\n  <DropdownMenuTrigger asChild>\n    <Button variant="outline">Open Menu</Button>\n  </DropdownMenuTrigger>\n  <DropdownMenuContent>\n    <DropdownMenuLabel>My Account</DropdownMenuLabel>\n    <DropdownMenuSeparator />\n    <DropdownMenuItem>Profile</DropdownMenuItem>\n    <DropdownMenuItem>Settings</DropdownMenuItem>\n    <DropdownMenuItem>\n      Log out\n      <DropdownMenuShortcut>\u2318Q</DropdownMenuShortcut>\n    </DropdownMenuItem>\n  </DropdownMenuContent>\n</DropdownMenu>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for action menus triggered by a button: user menus, row-action menus, toolbar overflow. Include DropdownMenuLabel for context, DropdownMenuSeparator for grouping.",
+    whenNotToUse: "Don't use for navigation between pages (use NavigationMenu or links). Don't use for selection inputs (use Select or Combobox). Don't use for right-click menus (use ContextMenu).",
+    commonMistakes: [
+      "Using DropdownMenu as a form Select (use Select instead)",
+      "Putting interactive elements directly in the trigger without asChild",
+      "Too many items without grouping (use DropdownMenuLabel + DropdownMenuSeparator)",
+      "Forgetting DropdownMenuShortcut for keyboard-accessible actions"
+    ],
+    relatedComponents: ["select", "context-menu", "popover"],
+    accessibilityNotes: "Full keyboard navigation: arrow keys, Home, End, typeahead, Escape. Radix handles role='menu', role='menuitem', and aria-labelledby.",
+    tokenBudget: 700
+  },
+  tags: ["dropdown", "menu", "actions", "overflow", "contextual"]
+};
+
+// src/components/popover/popover.schema.ts
+var popoverSchema = {
+  name: "popover",
+  displayName: "Popover",
+  description: "Floating content anchored to a trigger element. Non-modal by default \u2014 clicks outside dismiss it. Use for inline forms, info, or quick actions.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    { name: "open", type: "boolean", required: false, description: "Controlled open state" },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Default open state"
+    },
+    {
+      name: "onOpenChange",
+      type: "function",
+      required: false,
+      description: "Callback on open state change: (open: boolean) => void"
+    },
+    {
+      name: "modal",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "When true, content outside the popover is inert"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "PopoverTrigger + PopoverContent",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-popover", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["popover", "popover-foreground", "border"],
+  examples: [
+    {
+      title: "Basic popover",
+      description: "Quick settings anchored to a button",
+      code: '<Popover>\n  <PopoverTrigger asChild>\n    <Button variant="outline">Open</Button>\n  </PopoverTrigger>\n  <PopoverContent>\n    <div className="space-y-2">\n      <h4 className="font-medium">Dimensions</h4>\n      <p className="text-sm text-muted-foreground">Set the dimensions for the layer.</p>\n    </div>\n  </PopoverContent>\n</Popover>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for inline forms, quick settings, info panels, or color pickers. Anchored to a trigger, non-modal, dismisses on outside click.",
+    whenNotToUse: "Don't use for critical tasks that interrupt (use Dialog). Don't use for hover-only info (use Tooltip or HoverCard). Don't use for menu actions (use DropdownMenu).",
+    commonMistakes: [
+      "Using Popover when the user must address the content (should be Dialog)",
+      "Missing asChild on PopoverTrigger when using a styled Button",
+      "Popover content too wide \u2014 keep it focused and compact"
+    ],
+    relatedComponents: ["tooltip", "hover-card", "dialog", "dropdown-menu"],
+    accessibilityNotes: "Radix manages focus, aria-expanded on the trigger, and closes on Escape. Content is portalled to body so stacking contexts don't clip it.",
+    tokenBudget: 400
+  },
+  tags: ["popover", "overlay", "floating", "inline", "anchored"]
+};
+
+// src/components/tooltip/tooltip.schema.ts
+var tooltipSchema = {
+  name: "tooltip",
+  displayName: "Tooltip",
+  description: "A small floating label that reveals on hover or focus. Wrap your app in TooltipProvider, then use Tooltip/TooltipTrigger/TooltipContent per tooltip.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    {
+      name: "delayDuration",
+      type: "number",
+      required: false,
+      default: 700,
+      description: "[TooltipProvider prop] Milliseconds before the tooltip appears on hover"
+    },
+    {
+      name: "disableHoverableContent",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "[TooltipProvider prop] When true, tooltip dismisses when cursor enters it"
+    },
+    {
+      name: "open",
+      type: "boolean",
+      required: false,
+      description: "[Tooltip root prop] Controlled open state"
+    },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "[Tooltip root prop] Default open state for uncontrolled usage"
+    },
+    {
+      name: "onOpenChange",
+      type: "function",
+      required: false,
+      description: "[Tooltip root prop] Callback on open state change: (open: boolean) => void"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "TooltipTrigger + TooltipContent, all inside a TooltipProvider",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-tooltip", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "primary-foreground"],
+  examples: [
+    {
+      title: "Basic tooltip",
+      description: "Icon button with hover label",
+      code: '<TooltipProvider>\n  <Tooltip>\n    <TooltipTrigger asChild>\n      <Button variant="outline" size="icon" aria-label="Add">+</Button>\n    </TooltipTrigger>\n    <TooltipContent>\n      <p>Add item</p>\n    </TooltipContent>\n  </Tooltip>\n</TooltipProvider>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for terse hover/focus-reveal info: icon button labels, abbreviation expansions, keyboard shortcut hints. Content should fit in one line.",
+    whenNotToUse: "Don't use for rich content with images or actions (use HoverCard or Popover). Don't use for the only way to convey essential info \u2014 it's invisible to touch users.",
+    commonMistakes: [
+      "Forgetting TooltipProvider at the app root",
+      "Tooltip content too long (keep it under one line)",
+      "Using Tooltip as the only label for icon buttons (still add aria-label)",
+      "Triggering tooltips on non-interactive elements"
+    ],
+    relatedComponents: ["hover-card", "popover"],
+    accessibilityNotes: "Triggers on focus and hover. Radix sets role='tooltip' and aria-describedby. Still pair icon buttons with aria-label since tooltips don't announce on touch.",
+    tokenBudget: 300
+  },
+  tags: ["tooltip", "hint", "label", "hover", "overlay"]
+};
+
+// src/primitives/select/select.schema.ts
+var selectSchema = {
+  name: "select",
+  displayName: "Select",
+  description: "An accessible dropdown select for choosing one option from a list. Built on Radix UI Select with full keyboard navigation, typeahead, and RTL support.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    {
+      name: "value",
+      type: "string",
+      required: false,
+      description: "[Select root prop] Controlled selected value"
+    },
+    {
+      name: "defaultValue",
+      type: "string",
+      required: false,
+      description: "[Select root prop] Default selected value for uncontrolled usage"
+    },
+    {
+      name: "onValueChange",
+      type: "function",
+      required: false,
+      description: "[Select root prop] Callback on value change: (value: string) => void"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "[Select root prop] Disable the entire select"
+    },
+    {
+      name: "required",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "[Select root prop] Mark as required for form validation"
+    },
+    {
+      name: "name",
+      type: "string",
+      required: false,
+      description: "[Select root prop] Form field name (for native form submission)"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "SelectTrigger + SelectContent (with SelectItems, Groups, Labels)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-select", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [
+    "input",
+    "background",
+    "ring",
+    "muted-foreground",
+    "popover",
+    "popover-foreground",
+    "accent",
+    "accent-foreground",
+    "muted",
+    "border"
+  ],
+  examples: [
+    {
+      title: "Basic select",
+      description: "Choose a timezone",
+      code: '<Select>\n  <SelectTrigger className="w-[180px]">\n    <SelectValue placeholder="Select a fruit" />\n  </SelectTrigger>\n  <SelectContent>\n    <SelectGroup>\n      <SelectLabel>Fruits</SelectLabel>\n      <SelectItem value="apple">Apple</SelectItem>\n      <SelectItem value="banana">Banana</SelectItem>\n      <SelectItem value="orange">Orange</SelectItem>\n    </SelectGroup>\n  </SelectContent>\n</Select>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for choosing one option from a known, finite list (<= ~20 items): timezones, categories, roles, country codes. Pair with Label.",
+    whenNotToUse: "Don't use for large searchable lists (use Combobox). Don't use for boolean choices (use Switch/Checkbox). Don't use for action menus (use DropdownMenu). Don't use for multi-select (needs a different component).",
+    commonMistakes: [
+      "Missing Label pairing",
+      "Forgetting SelectValue inside SelectTrigger",
+      "Using Select when the list is large (use Combobox)",
+      "Putting non-SelectItem children inside SelectContent"
+    ],
+    relatedComponents: ["combobox", "dropdown-menu", "radio-group"],
+    accessibilityNotes: "Full keyboard nav: arrow keys, Home, End, typeahead, Escape to close. Radix handles role='combobox' on trigger, role='listbox' on content, aria-selected on items.",
+    tokenBudget: 800
+  },
+  tags: ["select", "dropdown", "form", "field", "options", "choose"]
+};
+
+// src/primitives/radio-group/radio-group.schema.ts
+var radioGroupSchema = {
+  name: "radio-group",
+  displayName: "Radio Group",
+  description: "A set of mutually exclusive radio options. Built on Radix UI RadioGroup with roving focus and arrow-key navigation.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    { name: "value", type: "string", required: false, description: "Controlled selected value" },
+    {
+      name: "defaultValue",
+      type: "string",
+      required: false,
+      description: "Default selected value for uncontrolled usage"
+    },
+    {
+      name: "onValueChange",
+      type: "function",
+      required: false,
+      description: "Callback on value change: (value: string) => void"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable all items"
+    },
+    {
+      name: "name",
+      type: "string",
+      required: false,
+      description: "Form field name (for native form submission)"
+    },
+    {
+      name: "orientation",
+      type: "enum",
+      required: false,
+      default: "vertical",
+      description: "Layout direction",
+      enumValues: ["horizontal", "vertical"]
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "RadioGroupItem elements, typically paired with Labels",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-radio-group", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["input", "primary", "ring"],
+  examples: [
+    {
+      title: "Basic radio group",
+      description: "Select a notification preference",
+      code: '<RadioGroup defaultValue="comfortable">\n  <div className="flex items-center gap-2">\n    <RadioGroupItem value="default" id="r1" />\n    <Label htmlFor="r1">Default</Label>\n  </div>\n  <div className="flex items-center gap-2">\n    <RadioGroupItem value="comfortable" id="r2" />\n    <Label htmlFor="r2">Comfortable</Label>\n  </div>\n  <div className="flex items-center gap-2">\n    <RadioGroupItem value="compact" id="r3" />\n    <Label htmlFor="r3">Compact</Label>\n  </div>\n</RadioGroup>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for mutually exclusive choices from a short list (2-5 options) where all options should be visible. Pair each RadioGroupItem with a Label.",
+    whenNotToUse: "Don't use for many options (use Select). Don't use for boolean toggles (use Switch or Checkbox). Don't use for multi-select.",
+    commonMistakes: [
+      "Missing Label for each RadioGroupItem",
+      "Using for more than 5 options (use Select)",
+      "Using htmlFor id mismatch between Label and RadioGroupItem"
+    ],
+    relatedComponents: ["select", "checkbox", "label"],
+    accessibilityNotes: "Radix implements the WAI-ARIA radio group pattern. Arrow keys move focus+selection. Radix handles aria-checked, role='radiogroup', role='radio'.",
+    tokenBudget: 400
+  },
+  tags: ["radio", "radio-group", "form", "choice", "mutually-exclusive"]
+};
+
+// src/primitives/slider/slider.schema.ts
+var sliderSchema = {
+  name: "slider",
+  displayName: "Slider",
+  description: "A range input with draggable thumbs. Supports single value, ranges (two thumbs), custom steps, and full keyboard control.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    {
+      name: "value",
+      type: "object",
+      required: false,
+      description: "Controlled array of thumb values (number[]), e.g. [50] for single, [20, 80] for range"
+    },
+    {
+      name: "defaultValue",
+      type: "object",
+      required: false,
+      description: "Default array of thumb values (number[]) for uncontrolled usage"
+    },
+    {
+      name: "onValueChange",
+      type: "function",
+      required: false,
+      description: "Callback on value change: (value: number[]) => void"
+    },
+    { name: "min", type: "number", required: false, default: 0, description: "Minimum value" },
+    { name: "max", type: "number", required: false, default: 100, description: "Maximum value" },
+    {
+      name: "step",
+      type: "number",
+      required: false,
+      default: 1,
+      description: "Step interval between valid values"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the slider"
+    },
+    {
+      name: "orientation",
+      type: "enum",
+      required: false,
+      default: "horizontal",
+      description: "Slider direction",
+      enumValues: ["horizontal", "vertical"]
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: false,
+      description: "Accessible label for the slider as a whole. Mirrored onto a single thumb automatically; for range sliders prefer thumbLabels."
+    },
+    {
+      name: "aria-labelledby",
+      type: "string",
+      required: false,
+      description: "Id of an external visible label that names the slider."
+    },
+    {
+      name: "thumbLabels",
+      type: "object",
+      required: false,
+      description: "Per-thumb accessible labels (string[]). Required for range sliders so each thumb has a meaningful name (e.g. ['Minimum price', 'Maximum price']). For a single-thumb slider, the Root's aria-label is mirrored onto the thumb automatically and thumbLabels is only needed when overriding that default."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-slider", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["secondary", "primary", "background", "ring"],
+  examples: [
+    {
+      title: "Volume control with display",
+      description: "Single-thumb slider paired with the live numeric value \u2014 the canonical 'continuous range with feedback' pattern",
+      code: 'function VolumeControl() {\n  const [value, setValue] = React.useState([60]);\n  return (\n    <div className="space-y-2">\n      <div className="flex justify-between text-sm">\n        <Label htmlFor="vol">Volume</Label>\n        <span className="text-muted-foreground tabular-nums">{value[0]}%</span>\n      </div>\n      <Slider id="vol" value={value} onValueChange={setValue} max={100} step={1} aria-label="Volume" />\n    </div>\n  );\n}',
+      composition: ["form", "settings", "continuous-range", "with-display"]
+    },
+    {
+      title: "Price-range filter",
+      description: "Two-thumb range slider with per-thumb labels \u2014 the canonical e-commerce filter UI",
+      code: '<Slider\n  defaultValue={[20, 80]}\n  max={100}\n  step={1}\n  thumbLabels={["Minimum price", "Maximum price"]}\n/>',
+      composition: ["filter", "range", "ecommerce"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use for continuous numeric inputs with a known range: volume, brightness, price range filter, opacity. Pair value with a visible number display when the exact value matters.",
+    whenNotToUse: "Don't use when the user needs to enter an exact number (use Input type=number). Don't use for discrete choices (use Select or RadioGroup). Don't use for boolean on/off (use Switch).",
+    commonMistakes: [
+      "Using Slider for exact values without showing the number",
+      "Missing min/max bounds",
+      "Using step=1 for fractional values (set step=0.01)",
+      "Not providing aria-label / aria-labelledby when there's no visible label",
+      "Range slider with only Root aria-label and no thumbLabels \u2014 both thumbs fall back to '(N of 2)' indexed names instead of meaningful per-thumb labels",
+      "thumbLabels.length !== value.length \u2014 extra labels are ignored, missing labels fall back to indexed names (dev-mode warning)"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using Slider with min=0/max=1 to represent on/off",
+        insteadUse: "switch",
+        why: "Slider is 'continuous range'. Switch is 'boolean'. Assistive tech announces them differently \u2014 Slider says '0 of 1, 1 of 1'; Switch says 'on / off'. Always reach for Switch when the values are binary."
+      },
+      {
+        mistake: "Using Slider for picking a number from a small discrete set (1\u20135 rating, 'pages per row')",
+        insteadUse: "radio-group",
+        why: "Sliders make exact target values hard to land on. RadioGroup gives 5 buttons that name themselves and are easier with assistive tech. Reach for Slider only when 50+ values are valid."
+      },
+      {
+        mistake: "Using Slider for the user to type a known exact number (price, age, count)",
+        insteadUse: "input",
+        why: "Drag-to-set is slower and less accurate than typing. Use <Input type='number'> when the user has the exact value in mind."
+      }
+    ],
+    relatedComponents: ["input", "switch", "radio-group"],
+    accessibilityNotes: "Arrow keys step by step, Home/End jump to min/max, PageUp/PageDown step larger. Radix handles aria-valuemin/max/now. Each thumb has its own accessible name: explicit via thumbLabels[i], else mirrored from the Root's aria-label (single thumb) or indexed '(i of N)' fallback (range). Add aria-label / aria-labelledby on the Root when there's no visible label.",
+    tokenBudget: 450
+  },
+  tags: ["slider", "range", "form", "numeric", "input"]
+};
+
+// src/primitives/toggle/toggle.schema.ts
+var toggleSchema = {
+  name: "toggle",
+  displayName: "Toggle",
+  description: "A two-state button that stays pressed when toggled on. Used for formatting toolbars (bold/italic) or option toggles.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    {
+      name: "pressed",
+      type: "boolean",
+      required: false,
+      description: "Controlled pressed state"
+    },
+    {
+      name: "defaultPressed",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Default pressed state for uncontrolled usage"
+    },
+    {
+      name: "onPressedChange",
+      type: "function",
+      required: false,
+      description: "Callback on pressed change: (pressed: boolean) => void"
+    },
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Visual style",
+      enumValues: ["default", "outline"]
+    },
+    {
+      name: "size",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Toggle size",
+      enumValues: ["default", "sm", "lg"]
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the toggle"
+    }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Visual variants",
+      values: [
+        { value: "default", description: "Transparent ghost-style toggle" },
+        { value: "outline", description: "Bordered toggle" }
+      ],
+      default: "default"
+    },
+    {
+      name: "size",
+      description: "Size variants",
+      values: [
+        { value: "default", description: "Standard size (h-10)" },
+        { value: "sm", description: "Compact size (h-9)" },
+        { value: "lg", description: "Large size (h-11)" }
+      ],
+      default: "default"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Toggle label or icon",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-toggle", "class-variance-authority", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "muted-foreground", "accent", "accent-foreground", "input", "ring"],
+  examples: [
+    {
+      title: "Basic toggle",
+      description: "Bold text toggle",
+      code: '<Toggle aria-label="Toggle bold">B</Toggle>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for binary on/off actions that persist: toolbar formatting buttons (bold, italic), layout mode switches, filter toggles. Not submitted as form data.",
+    whenNotToUse: "Don't use for instant settings (use Switch). Don't use for form boolean fields (use Checkbox). Don't use for choosing one of many (use ToggleGroup).",
+    commonMistakes: [
+      "Using for form field submission (use Checkbox instead)",
+      "Forgetting aria-label on icon-only toggles",
+      "Using Toggle when ToggleGroup's single-select mode is needed"
+    ],
+    relatedComponents: ["toggle-group", "switch", "checkbox", "button"],
+    accessibilityNotes: "Radix sets aria-pressed correctly. Icon-only toggles MUST have aria-label. Space/Enter toggles state.",
+    tokenBudget: 400
+  },
+  tags: ["toggle", "button", "pressed", "two-state", "toolbar"]
+};
+
+// src/primitives/toggle-group/toggle-group.schema.ts
+var toggleGroupSchema = {
+  name: "toggle-group",
+  displayName: "Toggle Group",
+  description: "A set of toggles where one or multiple can be pressed. Inherits Toggle's variant/size via context. Useful for alignment/formatting toolbars.",
+  category: "primitive",
+  subcategory: "forms",
+  props: [
+    {
+      name: "type",
+      type: "enum",
+      required: true,
+      description: "Single allows one pressed at a time, multiple allows many",
+      enumValues: ["single", "multiple"]
+    },
+    {
+      name: "value",
+      type: "object",
+      required: false,
+      description: "Controlled pressed value(s). string when type='single', string[] when type='multiple'"
+    },
+    {
+      name: "defaultValue",
+      type: "object",
+      required: false,
+      description: "Default pressed value(s). string when type='single', string[] when type='multiple'"
+    },
+    {
+      name: "onValueChange",
+      type: "function",
+      required: false,
+      description: "Callback on value change"
+    },
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Inherited by all ToggleGroupItems",
+      enumValues: ["default", "outline"]
+    },
+    {
+      name: "size",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Inherited by all ToggleGroupItems",
+      enumValues: ["default", "sm", "lg"]
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable all items"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "ToggleGroupItem elements",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: [
+      "@radix-ui/react-toggle-group",
+      "@radix-ui/react-toggle",
+      "class-variance-authority",
+      "clsx",
+      "tailwind-merge"
+    ],
+    internal: ["toggle"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "accent", "accent-foreground", "ring"],
+  examples: [
+    {
+      title: "Text alignment group",
+      description: "Single-select toggle group for text alignment",
+      code: '<ToggleGroup type="single" defaultValue="left">\n  <ToggleGroupItem value="left" aria-label="Left align">L</ToggleGroupItem>\n  <ToggleGroupItem value="center" aria-label="Center align">C</ToggleGroupItem>\n  <ToggleGroupItem value="right" aria-label="Right align">R</ToggleGroupItem>\n</ToggleGroup>'
+    },
+    {
+      title: "Formatting group",
+      description: "Multiple-select toggle group for text formatting",
+      code: '<ToggleGroup type="multiple">\n  <ToggleGroupItem value="bold" aria-label="Bold">B</ToggleGroupItem>\n  <ToggleGroupItem value="italic" aria-label="Italic">I</ToggleGroupItem>\n  <ToggleGroupItem value="underline" aria-label="Underline">U</ToggleGroupItem>\n</ToggleGroup>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for toolbar toggles where users pick one of many (type='single') or multiple (type='multiple'): text alignment, formatting (bold/italic/underline), view modes.",
+    whenNotToUse: "Don't use for form radio fields (use RadioGroup). Don't use for standalone two-state buttons (use Toggle). Don't use for navigation (use Tabs).",
+    commonMistakes: [
+      "Forgetting the type prop (required)",
+      "Missing aria-label on icon-only items",
+      "Using for form submission without name prop"
+    ],
+    relatedComponents: ["toggle", "radio-group", "tabs"],
+    accessibilityNotes: "Radix implements the WAI-ARIA toolbar pattern with roving focus. Arrow keys move focus, Space/Enter toggles. Each icon-only item needs aria-label.",
+    tokenBudget: 500
+  },
+  tags: ["toggle-group", "toolbar", "formatting", "alignment", "multi-select"]
+};
+
+// src/components/form/form.schema.ts
+var formSchema = {
+  name: "form",
+  displayName: "Form",
+  description: "A form primitive built on react-hook-form + zod. Provides Form/FormField/FormItem/FormLabel/FormControl/FormDescription/FormMessage with automatic aria wiring and error display.",
+  category: "component",
+  subcategory: "forms",
+  props: [],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "FormField + FormItem subtrees",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: [
+      "react-hook-form",
+      "@hookform/resolvers",
+      "zod",
+      "@radix-ui/react-label",
+      "@radix-ui/react-slot",
+      "clsx",
+      "tailwind-merge"
+    ],
+    internal: ["label"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["destructive", "muted-foreground"],
+  examples: [
+    {
+      title: "Zod-validated form",
+      description: "Username form with react-hook-form + zod",
+      code: 'import { zodResolver } from "@hookform/resolvers/zod";\nimport { useForm } from "react-hook-form";\nimport { z } from "zod";\n\nconst formSchema = z.object({\n  username: z.string().min(2, "Username must be at least 2 characters"),\n});\n\nfunction ProfileForm() {\n  const form = useForm({\n    resolver: zodResolver(formSchema),\n    defaultValues: { username: "" },\n  });\n\n  return (\n    <Form {...form}>\n      <form onSubmit={form.handleSubmit((values) => console.log(values))} className="space-y-6">\n        <FormField\n          control={form.control}\n          name="username"\n          render={({ field }) => (\n            <FormItem>\n              <FormLabel>Username</FormLabel>\n              <FormControl><Input placeholder="shadcn" {...field} /></FormControl>\n              <FormDescription>Your public display name.</FormDescription>\n              <FormMessage />\n            </FormItem>\n          )}\n        />\n        <Button type="submit">Submit</Button>\n      </form>\n    </Form>\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for any form that needs validation, per-field errors, and accessible aria-describedby/aria-invalid wiring. Pair with zod schemas via @hookform/resolvers/zod.",
+    whenNotToUse: "Don't use for trivial single-input forms that don't need validation (render a plain Input + Button). Don't use for server actions forms in Next.js 16 (consider useActionState + useFormStatus instead).",
+    commonMistakes: [
+      "Forgetting to spread {...field} into the form control (connects value/onChange)",
+      "Putting FormLabel outside FormItem (loses htmlFor wiring)",
+      "Using useForm without a resolver when zod validation is desired",
+      "Calling form.handleSubmit without a callback"
+    ],
+    relatedComponents: ["input", "textarea", "select", "checkbox", "radio-group", "switch"],
+    accessibilityNotes: "FormControl automatically wires id, aria-describedby, and aria-invalid. FormLabel uses htmlFor matching the control id. Errors are announced via FormMessage with matching aria-describedby.",
+    tokenBudget: 900
+  },
+  tags: ["form", "react-hook-form", "zod", "validation", "field"]
+};
+
+// src/primitives/avatar/avatar.schema.ts
+var avatarSchema = {
+  name: "avatar",
+  displayName: "Avatar",
+  description: "A user profile image with a fallback (usually initials) rendered when the image is missing or fails to load. Built on Radix UI Avatar \u2014 AvatarFallback accepts a delayMs prop to avoid flashing during fast loads.",
+  category: "primitive",
+  subcategory: "display",
+  props: [{ name: "className", type: "string", required: false, description: "Additional CSS classes on the root" }],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "AvatarImage + AvatarFallback",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-avatar", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "muted-foreground"],
+  examples: [
+    {
+      title: "Basic avatar",
+      description: "Image with initials fallback",
+      code: '<Avatar>\n  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />\n  <AvatarFallback>CN</AvatarFallback>\n</Avatar>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for user profile images: headers, comments, user lists. Always include AvatarFallback for accessibility and loading states.",
+    whenNotToUse: "Don't use for decorative icons (use an <img> or icon component). Don't use for product/brand images (use <img> with proper sizing).",
+    commonMistakes: [
+      "Missing alt text on AvatarImage",
+      "No AvatarFallback \u2014 shows nothing when image is missing or errors",
+      "Omitting delayMs on AvatarFallback causes flicker for fast-loading images",
+      "Using for non-circular images (override rounded-full if needed)"
+    ],
+    relatedComponents: ["badge", "card"],
+    accessibilityNotes: "AvatarImage requires alt text. AvatarFallback renders initials or an icon \u2014 ensure the visible text is meaningful.",
+    tokenBudget: 250
+  },
+  tags: ["avatar", "profile", "user", "image", "display"]
+};
+
+// src/primitives/skeleton/skeleton.schema.ts
+var skeletonSchema = {
+  name: "skeleton",
+  displayName: "Skeleton",
+  description: "A pulsing placeholder shown while content is loading. Pair with explicit dimensions.",
+  category: "primitive",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Width/height and any additional styling via Tailwind classes"
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted"],
+  examples: [
+    {
+      title: "Card skeleton",
+      description: "Avatar + two lines of text placeholder",
+      code: '<div className="flex items-center gap-4">\n  <Skeleton className="h-12 w-12 rounded-full" />\n  <div className="space-y-2">\n    <Skeleton className="h-4 w-[250px]" />\n    <Skeleton className="h-4 w-[200px]" />\n  </div>\n</div>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use during async data loads to show the shape of forthcoming content. Match the dimensions and layout of the real content to avoid layout shift on load.",
+    whenNotToUse: "Don't use for fast operations (<200ms \u2014 users prefer a brief spinner or nothing). Don't use as a permanent empty state (use proper empty-state UI).",
+    commonMistakes: [
+      "Skeleton dimensions don't match loaded content \u2014 causes layout shift",
+      "Leaving Skeleton visible for long loads without a timeout/retry",
+      "Using Skeleton for interactive elements users might tap"
+    ],
+    relatedComponents: ["progress", "avatar", "card", "table"],
+    accessibilityNotes: "Add aria-busy='true' on the loading container and a visually hidden status (aria-live='polite') to announce load completion to screen readers.",
+    tokenBudget: 200
+  },
+  tags: ["skeleton", "loading", "placeholder", "shimmer"]
+};
+
+// src/primitives/progress/progress.schema.ts
+var progressSchema = {
+  name: "progress",
+  displayName: "Progress",
+  description: "A horizontal progress bar showing completion from 0 to 100%. Built on Radix UI Progress.",
+  category: "primitive",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "value",
+      type: "number",
+      required: false,
+      description: "Current value (0\u2013max). Omit to render at 0% (both visually and in ARIA \u2014 the component clamps undefined to 0). Use Skeleton for indeterminate loading states."
+    },
+    { name: "max", type: "number", required: false, default: 100, description: "Maximum value" },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-progress", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["secondary", "primary"],
+  examples: [
+    {
+      title: "Basic progress",
+      description: "At 60%",
+      code: "<Progress value={60} />"
+    }
+  ],
+  ai: {
+    whenToUse: "Use for deterministic progress where completion is measurable: file uploads, multi-step form completion, batch processing. Pair with a visible numeric label where precision matters.",
+    whenNotToUse: "Don't use for indeterminate waits (use a spinner or Skeleton). Don't use for completion over long time-spans without a human-readable ETA.",
+    commonMistakes: [
+      "Passing 0\u20131 float instead of 0\u2013100",
+      "Not labeling the progress (users can't tell what's progressing)",
+      "Updating too frequently (>30fps) \u2014 wastes renders"
+    ],
+    relatedComponents: ["skeleton", "slider", "sonner"],
+    accessibilityNotes: "Radix wires role='progressbar', aria-valuenow, aria-valuemin, aria-valuemax. Pair with a visible label or aria-label for context.",
+    tokenBudget: 250
+  },
+  tags: ["progress", "loading", "bar", "feedback", "determinate"]
+};
+
+// src/primitives/scroll-area/scroll-area.schema.ts
+var scrollAreaSchema = {
+  name: "scroll-area",
+  displayName: "Scroll Area",
+  description: "A scrollable region with custom-styled scrollbars that match the design system. Content must be explicitly sized.",
+  category: "primitive",
+  subcategory: "layout",
+  props: [
+    {
+      name: "type",
+      type: "enum",
+      required: false,
+      default: "hover",
+      description: "When scrollbars are visible",
+      enumValues: ["auto", "always", "scroll", "hover"]
+    },
+    { name: "className", type: "string", required: false, description: "Set dimensions via Tailwind (e.g. h-72 w-48)" },
+    {
+      name: "viewportTabIndex",
+      type: "number",
+      required: false,
+      default: 0,
+      description: "tabIndex applied to the scroll viewport. Defaults to 0 so keyboard users can scroll without a pointer; pass -1 to skip the viewport in the tab order when wrapping decorative or already-keyboard-reachable content."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Any content \u2014 will be wrapped in a scrollable viewport",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-scroll-area", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["border"],
+  examples: [
+    {
+      title: "Fixed-height list",
+      description: "50 items in a 200px-tall scrollable region",
+      code: '<ScrollArea className="h-[200px] w-[350px] rounded-md border p-4">\n  {Array.from({ length: 50 }).map((_, i) => (\n    <div key={i} className="text-sm">Item {i + 1}</div>\n  ))}\n</ScrollArea>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use when you need styled scrollbars that match the design system \u2014 sidebars, code blocks, large lists in dialogs. Must have explicit dimensions (height/width).",
+    whenNotToUse: "Don't use for the whole page (use native browser scrollbars). Don't use for content that should grow freely (omit the ScrollArea and use overflow-auto directly).",
+    commonMistakes: [
+      "Forgetting to set height/width \u2014 scrollbars don't appear",
+      "Using for the whole page",
+      "Nesting ScrollAreas (confusing UX)",
+      "Wrapping decorative or already-keyboard-reachable content without setting viewportTabIndex={-1} \u2014 adds an unnecessary tab stop"
+    ],
+    relatedComponents: [],
+    accessibilityNotes: "The viewport is keyboard-focusable by default (viewportTabIndex=0) so users can scroll long content via arrow keys / PgUp / PgDn / Home / End without a pointer. Pass viewportTabIndex={-1} when the contents are already in the tab order or purely decorative. For very long lists, consider pagination or virtualization.",
+    tokenBudget: 350
+  },
+  tags: ["scroll-area", "scroll", "overflow", "scrollbar", "layout"]
+};
+
+// src/primitives/aspect-ratio/aspect-ratio.schema.ts
+var aspectRatioSchema = {
+  name: "aspect-ratio",
+  displayName: "Aspect Ratio",
+  description: "Constrain children to a specific width-to-height ratio (e.g. 16/9 for video, 1/1 for square).",
+  category: "primitive",
+  subcategory: "layout",
+  props: [
+    {
+      name: "ratio",
+      type: "number",
+      required: false,
+      default: 1,
+      description: "Width-to-height ratio (e.g. 16/9 \u2248 1.778)"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Content to constrain (usually an image or iframe)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-aspect-ratio"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [],
+  examples: [
+    {
+      title: "16:9 video thumbnail",
+      description: "Image constrained to widescreen ratio",
+      code: '<AspectRatio ratio={16 / 9} className="bg-muted">\n  <img src="/hero.jpg" alt="Hero" className="h-full w-full rounded-md object-cover" />\n</AspectRatio>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use when an image or iframe must maintain a specific ratio regardless of container width: video thumbnails, product images, hero banners, embeds.",
+    whenNotToUse: "Don't use for content with known fixed dimensions (just use width/height). Don't use for text content (ratios don't make sense for prose).",
+    commonMistakes: [
+      "Passing ratio as a string instead of a number (use {16/9}, not '16/9')",
+      "Forgetting that children must fill 100% width + height (add object-cover or similar)"
+    ],
+    relatedComponents: ["card", "avatar", "skeleton"],
+    accessibilityNotes: "AspectRatio is purely structural. Ensure inner <img> has alt text and inner <iframe> has a descriptive title.",
+    tokenBudget: 200
+  },
+  tags: ["aspect-ratio", "layout", "image", "video", "ratio"]
+};
+
+// src/primitives/container/container.schema.ts
+var containerSchema = {
+  name: "container",
+  displayName: "Container",
+  description: "Centered max-width wrapper that constrains content to readable widths. Sizes map to `--container-*` prose-width tokens; padding maps to `--space-*`.",
+  category: "primitive",
+  subcategory: "layout",
+  props: [
+    {
+      name: "size",
+      type: "enum",
+      required: false,
+      default: "lg",
+      description: "Max-width preset bound to `--container-*` tokens (sm=33rem, md=40rem, lg=50rem, xl=66rem, full=100%).",
+      enumValues: ["sm", "md", "lg", "xl", "full"]
+    },
+    {
+      name: "padding",
+      type: "enum",
+      required: false,
+      default: "md",
+      description: "Horizontal padding bound to `--space-*` tokens (none=0, sm=0.75rem, md=1rem, lg=2rem).",
+      enumValues: ["none", "sm", "md", "lg"]
+    },
+    {
+      name: "asChild",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Render as a different element via Radix `Slot`. Use to render as `<main>`, `<section>`, etc. for landmark semantics."
+    }
+  ],
+  variants: [
+    {
+      name: "size",
+      description: "Max-width preset bound to `--container-*` tokens.",
+      values: [
+        { value: "sm", description: "33rem (\u2248530px) \u2014 narrow column for short content." },
+        { value: "md", description: "40rem (\u2248640px) \u2014 comfortable reading width." },
+        { value: "lg", description: "50rem (\u2248800px) \u2014 default; standard article width." },
+        { value: "xl", description: "66rem (\u22481056px) \u2014 wider canvas for dashboards or marketing." },
+        { value: "full", description: "100% \u2014 disable max-width clamp." }
+      ],
+      default: "lg"
+    },
+    {
+      name: "padding",
+      description: "Horizontal padding bound to `--space-*` tokens.",
+      values: [
+        { value: "none", description: "0 \u2014 flush to container edges." },
+        { value: "sm", description: "0.75rem \u2014 tight gutter." },
+        { value: "md", description: "1rem \u2014 default; standard reading gutter." },
+        { value: "lg", description: "2rem \u2014 generous gutter for marketing pages." }
+      ],
+      default: "md"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Page content to constrain \u2014 typically a section, article, or grid.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority", "@radix-ui/react-slot"],
+    internal: ["lib/utils"],
+    peer: ["react"]
+  },
+  tokensUsed: [
+    "--container-sm",
+    "--container-md",
+    "--container-lg",
+    "--container-xl",
+    "--space-3",
+    "--space-4",
+    "--space-8"
+  ],
+  examples: [
+    {
+      title: "Reading-width article",
+      description: "lg size (50rem) + md padding for an article body.",
+      code: '<Container size="lg" padding="md">\n  <article>...</article>\n</Container>'
+    },
+    {
+      title: "Full-width hero",
+      description: "Use size=full when you want the section to span the viewport.",
+      code: '<Container size="full" padding="none">\n  <Hero />\n</Container>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use to constrain page content to readable widths. Pair with `Stack` or `Grid` inside for vertical/grid layouts. Default for any centered article, settings page, or marketing section.",
+    whenNotToUse: 'Don\'t use inside another `Container` (double-clamping). Don\'t use as a drop-in for `<main>` semantics \u2014 it\'s a layout primitive, not a landmark. For full-bleed sections (edge-to-edge banners), pass `size="full" padding="none"`.',
+    commonMistakes: [
+      "Wrapping a `Container` in another `Container` and getting an unexpectedly narrow column",
+      'Using `padding="none"` and forgetting that children still need their own gutter \u2014 the parent contributes nothing',
+      "Treating `lg` as the largest size \u2014 `xl` (66rem) and `full` are bigger"
+    ],
+    relatedComponents: ["stack", "grid", "cluster"],
+    accessibilityNotes: "Container is presentational. Wrap in a semantic landmark (`<main>`, `<section>`, `<article>`) when the page structure needs it; Container itself renders a plain `<div>`.",
+    tokenBudget: 250
+  },
+  tags: ["container", "layout", "wrapper", "max-width", "primitive"]
+};
+
+// src/primitives/stack/stack.schema.ts
+var stackSchema = {
+  name: "stack",
+  displayName: "Stack",
+  description: 'Vertical flex flow with token-bound gap. The headless equivalent of `<div className="flex flex-col gap-X">` with consistent spacing scale.',
+  category: "primitive",
+  subcategory: "layout",
+  props: [
+    {
+      name: "gap",
+      type: "enum",
+      required: false,
+      default: "md",
+      description: "Vertical spacing between children, bound to `--gap-*` tokens.",
+      enumValues: ["xs", "sm", "md", "lg", "xl"]
+    },
+    {
+      name: "align",
+      type: "enum",
+      required: false,
+      default: "stretch",
+      description: "Cross-axis alignment (CSS `align-items`).",
+      enumValues: ["start", "center", "end", "stretch"]
+    },
+    {
+      name: "justify",
+      type: "enum",
+      required: false,
+      default: "start",
+      description: "Main-axis distribution (CSS `justify-content`).",
+      enumValues: ["start", "center", "end", "between"]
+    }
+  ],
+  variants: [
+    {
+      name: "gap",
+      description: "Vertical gap between children, bound to `--gap-*` tokens.",
+      values: [
+        { value: "xs", description: "0.25rem \u2014 barely-there spacing." },
+        { value: "sm", description: "0.5rem \u2014 tight grouping." },
+        { value: "md", description: "1rem \u2014 default; standard rhythm." },
+        { value: "lg", description: "1.5rem \u2014 section-level spacing." },
+        { value: "xl", description: "2rem \u2014 major separation." }
+      ],
+      default: "md"
+    },
+    {
+      name: "align",
+      description: "Cross-axis alignment (CSS `align-items`).",
+      values: [
+        { value: "start", description: "Children align to left edge." },
+        { value: "center", description: "Children center horizontally." },
+        { value: "end", description: "Children align to right edge." },
+        { value: "stretch", description: "Default \u2014 children fill container width." }
+      ],
+      default: "stretch"
+    },
+    {
+      name: "justify",
+      description: "Main-axis distribution (CSS `justify-content`).",
+      values: [
+        { value: "start", description: "Default \u2014 children pack to top." },
+        { value: "center", description: "Children center vertically." },
+        { value: "end", description: "Children pack to bottom." },
+        { value: "between", description: "First child to top, last to bottom, even distribution." }
+      ],
+      default: "start"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Items to stack vertically.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority"],
+    internal: ["lib/utils"],
+    peer: ["react"]
+  },
+  tokensUsed: ["--gap-xs", "--gap-sm", "--gap-md", "--gap-lg", "--gap-xl"],
+  examples: [
+    {
+      title: "Form sections",
+      description: "Lg gap separates labelled groups; nested Stack with sm gap groups label+input.",
+      code: '<Stack gap="lg">\n  <Stack gap="sm"><Label>Email</Label><Input /></Stack>\n  <Stack gap="sm"><Label>Password</Label><Input type="password" /></Stack>\n  <Button>Submit</Button>\n</Stack>'
+    },
+    {
+      title: "Centered hero",
+      description: "Center children horizontally for a centered call-to-action stack.",
+      code: '<Stack gap="md" align="center">\n  <h1>Title</h1>\n  <p>Subtitle</p>\n  <Button>Get started</Button>\n</Stack>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use anywhere you'd write `flex flex-col gap-X`. Default for vertical lists of dissimilar items (label + input + helper text), section bodies, sidebar items, button groups stacked vertically.",
+    whenNotToUse: "Don't use for tabular data \u2014 use `<table>` or DataTable. Don't use for grid-like layouts \u2014 use `Grid`. Don't reach for `Stack` when a single child needs no spacing \u2014 just render the child.",
+    commonMistakes: [
+      'Setting `gap="md"` then adding `mt-*` / `space-y-*` on individual children \u2014 pick one spacing system',
+      'Using `align="center"` and wondering why children expand to full width \u2014 that\'s the `stretch` default for cross-axis',
+      "Nesting Stack inside Stack with the same gap when one Stack with two children would suffice"
+    ],
+    relatedComponents: ["cluster", "grid", "container"],
+    accessibilityNotes: "Stack is presentational. Wrap stacked navigation links in a `<nav>`, stacked form fields in a `<form>`, etc. \u2014 Stack does not contribute landmark semantics.",
+    tokenBudget: 250
+  },
+  tags: ["stack", "layout", "flex", "column", "vertical", "primitive"]
+};
+
+// src/primitives/cluster/cluster.schema.ts
+var clusterSchema = {
+  name: "cluster",
+  displayName: "Cluster",
+  description: "Horizontal flex flow with wrap and token-bound gap. Use for tag lists, button rows, breadcrumbs, and any group of equally-weighted inline items.",
+  category: "primitive",
+  subcategory: "layout",
+  props: [
+    {
+      name: "gap",
+      type: "enum",
+      required: false,
+      default: "md",
+      description: "Gap between items, bound to `--gap-*` tokens. Applies to both row and column gaps when wrapping.",
+      enumValues: ["xs", "sm", "md", "lg", "xl"]
+    },
+    {
+      name: "align",
+      type: "enum",
+      required: false,
+      default: "center",
+      description: "Cross-axis alignment (CSS `align-items`). `baseline` aligns text-baselines for mixed-size siblings; `stretch` makes items fill row height (useful for wrap-card layouts).",
+      enumValues: ["start", "center", "end", "stretch", "baseline"]
+    },
+    {
+      name: "justify",
+      type: "enum",
+      required: false,
+      default: "start",
+      description: "Main-axis distribution (CSS `justify-content`).",
+      enumValues: ["start", "center", "end", "between"]
+    }
+  ],
+  variants: [
+    {
+      name: "gap",
+      description: "Gap between items, bound to `--gap-*` tokens (applies to row + column gaps when wrapping).",
+      values: [
+        { value: "xs", description: "0.25rem \u2014 barely-there spacing." },
+        { value: "sm", description: "0.5rem \u2014 tight chip group." },
+        { value: "md", description: "1rem \u2014 default; standard rhythm." },
+        { value: "lg", description: "1.5rem \u2014 generous separation." },
+        { value: "xl", description: "2rem \u2014 section-scale spacing." }
+      ],
+      default: "md"
+    },
+    {
+      name: "align",
+      description: "Cross-axis alignment (CSS `align-items`).",
+      values: [
+        { value: "start", description: "Items align to top of row." },
+        { value: "center", description: "Default \u2014 items center vertically in the row." },
+        { value: "end", description: "Items align to bottom of row." },
+        { value: "stretch", description: "Items fill row height \u2014 use for wrap layouts of equal-height cards." },
+        { value: "baseline", description: "Text-baselines align across mixed-size siblings." }
+      ],
+      default: "center"
+    },
+    {
+      name: "justify",
+      description: "Main-axis distribution (CSS `justify-content`).",
+      values: [
+        { value: "start", description: "Default \u2014 items pack to start of row." },
+        { value: "center", description: "Items center horizontally." },
+        { value: "end", description: "Items pack to end of row." },
+        { value: "between", description: "First item flush left, last flush right, even distribution." }
+      ],
+      default: "start"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Items to lay out horizontally with wrap.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority"],
+    internal: ["lib/utils"],
+    peer: ["react"]
+  },
+  tokensUsed: ["--gap-xs", "--gap-sm", "--gap-md", "--gap-lg", "--gap-xl"],
+  examples: [
+    {
+      title: "Tag chips",
+      description: "Small gap, wraps when overflowing the row.",
+      code: '<Cluster gap="sm">\n  {tags.map((t) => <Badge key={t}>{t}</Badge>)}\n</Cluster>'
+    },
+    {
+      title: "Action bar",
+      description: "Right-aligned buttons inside a panel footer.",
+      code: '<Cluster gap="sm" justify="end">\n  <Button variant="ghost">Cancel</Button>\n  <Button>Save</Button>\n</Cluster>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for any horizontal row of items that should wrap when space runs out: tag clouds, breadcrumbs, button rows, social-link icon strips, inline metadata badges. Pick `Cluster` over `flex` when you want predictable wrap + gap behavior.",
+    whenNotToUse: "Don't use for two-element rows where you need precise positional control (left/right) \u2014 use `Stack` rotated or a flex with `justify-between` directly. Don't use for grid-aligned layouts where columns must line up across rows \u2014 use `Grid`.",
+    commonMistakes: [
+      "Forgetting that `Cluster` wraps \u2014 adding `flex-nowrap` defeats the purpose; if you don't want wrap, use a flex row or `Stack` rotated",
+      "Setting `align=\"baseline\"` for icon+text rows where the icon's bbox doesn't have a baseline \u2014 use `center` instead",
+      "Reaching for `Cluster` for tabular alignment \u2014 use `Grid` or a real `<table>` when columns must line up"
+    ],
+    relatedComponents: ["stack", "grid", "container"],
+    accessibilityNotes: "Cluster is presentational. Lists of navigational items should be wrapped in `<nav>` (and ideally `<ul>` / `<li>`). Lists of tags can use a list element for screen-reader semantics; the visual wrap is independent.",
+    tokenBudget: 250
+  },
+  tags: ["cluster", "layout", "flex", "wrap", "horizontal", "primitive"]
+};
+
+// src/primitives/grid/grid.schema.ts
+var gridSchema = {
+  name: "grid",
+  displayName: "Grid",
+  description: 'CSS grid with column-count presets and token-bound gap. Pass `cols="auto-fit"` + `minColWidth` for responsive grids without media queries.',
+  category: "primitive",
+  subcategory: "layout",
+  props: [
+    {
+      name: "cols",
+      type: "enum",
+      required: false,
+      default: "3",
+      description: 'Number of fixed columns, or `"auto-fit"` for responsive tracks (use with `minColWidth`).',
+      enumValues: ["1", "2", "3", "4", "6", "auto-fit"]
+    },
+    {
+      name: "gap",
+      type: "enum",
+      required: false,
+      default: "md",
+      description: "Gap between cells, bound to `--gap-*` tokens.",
+      enumValues: ["xs", "sm", "md", "lg", "xl"]
+    },
+    {
+      name: "align",
+      type: "enum",
+      required: false,
+      default: "stretch",
+      description: "Cell vertical alignment within their grid row.",
+      enumValues: ["start", "center", "end", "stretch"]
+    },
+    {
+      name: "minColWidth",
+      type: "string",
+      required: false,
+      default: "16rem",
+      description: 'Min track size for `cols="auto-fit"` (e.g. `"20rem"`). Ignored when `cols` is a fixed integer.'
+    }
+  ],
+  variants: [
+    {
+      name: "cols",
+      description: "Column count or `auto-fit` mode.",
+      values: [
+        { value: "1", description: "Single column \u2014 items stack vertically inside the grid." },
+        { value: "2", description: "Two even columns." },
+        { value: "3", description: "Default \u2014 three even columns." },
+        { value: "4", description: "Four even columns." },
+        { value: "6", description: "Six even columns \u2014 dense layouts." },
+        { value: "auto-fit", description: "Tracks repeat to fill width, never below `minColWidth`." }
+      ],
+      default: "3"
+    },
+    {
+      name: "gap",
+      description: "Gap between cells, bound to `--gap-*` tokens.",
+      values: [
+        { value: "xs", description: "0.25rem \u2014 minimal separation." },
+        { value: "sm", description: "0.5rem \u2014 tight grid." },
+        { value: "md", description: "1rem \u2014 default; standard rhythm." },
+        { value: "lg", description: "1.5rem \u2014 generous separation." },
+        { value: "xl", description: "2rem \u2014 major separation between cards." }
+      ],
+      default: "md"
+    },
+    {
+      name: "align",
+      description: "Cell vertical alignment within their grid row.",
+      values: [
+        { value: "start", description: "Cells align to top of row." },
+        { value: "center", description: "Cells center vertically." },
+        { value: "end", description: "Cells align to bottom of row." },
+        { value: "stretch", description: "Default \u2014 cells fill row height." }
+      ],
+      default: "stretch"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Grid cells \u2014 typically Cards, images, or any uniform block.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority"],
+    internal: ["lib/utils"],
+    peer: ["react"]
+  },
+  tokensUsed: ["--gap-xs", "--gap-sm", "--gap-md", "--gap-lg", "--gap-xl"],
+  examples: [
+    {
+      title: "Three-column card grid",
+      description: "Fixed 3 columns with medium gap.",
+      code: '<Grid cols={3} gap="md">\n  {items.map((i) => <Card key={i.id}>{i.title}</Card>)}\n</Grid>'
+    },
+    {
+      title: "Responsive auto-fit",
+      description: "Tracks fit as many 20rem columns as the viewport allows; no media queries needed.",
+      code: '<Grid cols="auto-fit" minColWidth="20rem" gap="lg">\n  {items.map(...)}\n</Grid>'
+    }
+  ],
+  ai: {
+    whenToUse: 'Use for visually-aligned grids of similar items: card galleries, image walls, dashboard tiles, settings panels. Prefer `cols="auto-fit"` + `minColWidth` over hand-written breakpoints when the column count should adapt to viewport width.',
+    whenNotToUse: "Don't use for one-dimensional flows \u2014 use `Stack` (vertical) or `Cluster` (horizontal). Don't use for tabular data \u2014 use `<table>` or DataTable. Don't fight `Grid` to make uneven columns; if cells need different sizes, use a flexbox layout or a CSS grid with named tracks directly.",
+    commonMistakes: [
+      'Setting `cols={5}` and getting nothing \u2014 the preset only supports 1/2/3/4/6 (deliberate, to avoid odd visual rhythms); use `cols="auto-fit"` for arbitrary counts',
+      'Passing `cols="auto-fit"` without `minColWidth` \u2014 the default `16rem` may not match your design intent',
+      "Using `Grid` for two children when `Cluster` or `Stack` would communicate intent better"
+    ],
+    relatedComponents: ["stack", "cluster", "container", "card"],
+    accessibilityNotes: "Grid is presentational. If the grid renders a list of similar items, wrap in `<ul>`/`<li>` for screen-reader semantics \u2014 Grid only handles visual layout.",
+    tokenBudget: 300
+  },
+  tags: ["grid", "layout", "css-grid", "responsive", "auto-fit", "primitive"]
+};
+
+// src/primitives/spacer/spacer.schema.ts
+var spacerSchema = {
+  name: "spacer",
+  displayName: "Spacer",
+  description: "Declarative whitespace block bound to `--space-*` tokens. Use when sibling spacing can't come from a parent's `gap`.",
+  category: "primitive",
+  subcategory: "layout",
+  props: [
+    {
+      name: "size",
+      type: "enum",
+      required: false,
+      default: "md",
+      description: "Spacing token (xs=0.25rem, sm=0.5rem, md=1rem, lg=2rem, xl=4rem). Bound to `--space-*`.",
+      enumValues: ["xs", "sm", "md", "lg", "xl"]
+    },
+    {
+      name: "axis",
+      type: "enum",
+      required: false,
+      default: "vertical",
+      description: "Which axis to expand. Vertical = height; horizontal = width; both = square.",
+      enumValues: ["vertical", "horizontal", "both"]
+    }
+  ],
+  variants: [
+    {
+      name: "size",
+      description: "Spacer extent bound to `--space-*` tokens.",
+      values: [
+        { value: "xs", description: "0.25rem \u2014 micro-gap." },
+        { value: "sm", description: "0.5rem \u2014 tight separation." },
+        { value: "md", description: "1rem \u2014 default; standard breathing room." },
+        { value: "lg", description: "2rem \u2014 section-scale separation." },
+        { value: "xl", description: "4rem \u2014 major separation between hero areas." }
+      ],
+      default: "md"
+    },
+    {
+      name: "axis",
+      description: "Which axis the spacer extends along.",
+      values: [
+        { value: "vertical", description: "Default \u2014 fixed height, 1px width." },
+        { value: "horizontal", description: "Fixed width, 1px height \u2014 for flex rows." },
+        { value: "both", description: "Square block \u2014 rare; usually pick one axis." }
+      ],
+      default: "vertical"
+    }
+  ],
+  slots: [],
+  dependencies: {
+    npm: ["class-variance-authority"],
+    internal: ["lib/utils"],
+    peer: ["react"]
+  },
+  tokensUsed: ["--space-1", "--space-2", "--space-4", "--space-8", "--space-16"],
+  examples: [
+    {
+      title: "Vertical breathing room",
+      description: "Push two sections apart inside a parent that doesn't manage gap.",
+      code: '<>\n  <Hero />\n  <Spacer size="xl" />\n  <Features />\n</>'
+    },
+    {
+      title: "Horizontal flex spacer",
+      description: "Push siblings to opposite ends of a flex row.",
+      code: '<div className="flex items-center">\n  <Logo />\n  <Spacer axis="horizontal" size="lg" />\n  <Nav />\n</div>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use as an explicit whitespace primitive when you can't (or don't want to) use `gap` on the parent \u2014 typically: pushing siblings apart inside a flex row that already has gap-0, or inserting one-off vertical breathing room between top-level sections that aren't wrapped in a Stack.",
+    whenNotToUse: "Don't use Spacer when a `Stack` or `Cluster` parent's `gap` would do the same thing \u2014 that scales better and keeps the spacing concern with the layout primitive. Don't use Spacer to flush content to one edge of a flex container \u2014 use `ml-auto` / `justify-between` directly.",
+    commonMistakes: [
+      "Using `<Spacer />` between every child in a Stack \u2014 just set the Stack's `gap` instead",
+      'Using `axis="both"` and getting a square block where you wanted a line \u2014 `both` is rare, usually you want vertical or horizontal',
+      `Setting size="lg" on a horizontal spacer and getting nothing visible because the parent isn't a flex row \u2014 Spacer reserves space, it doesn't push siblings on its own`
+    ],
+    relatedComponents: ["stack", "cluster", "separator"],
+    accessibilityNotes: 'Spacer is `aria-hidden="true"` \u2014 screen readers skip it. Don\'t use a Spacer where a `Separator` would convey meaning (a thematic break should be `Separator`, not `Spacer`).',
+    tokenBudget: 200
+  },
+  tags: ["spacer", "layout", "whitespace", "spacing", "primitive"]
+};
+
+// src/components/collapsible/collapsible.schema.ts
+var collapsibleSchema = {
+  name: "collapsible",
+  displayName: "Collapsible",
+  description: "A single section that can be expanded or collapsed. For multiple independent sections use Accordion with type='multiple'.",
+  category: "component",
+  subcategory: "disclosure",
+  props: [
+    { name: "open", type: "boolean", required: false, description: "Controlled open state" },
+    { name: "defaultOpen", type: "boolean", required: false, default: false, description: "Default open state" },
+    { name: "onOpenChange", type: "function", required: false, description: "Callback on open change: (open: boolean) => void" },
+    { name: "disabled", type: "boolean", required: false, default: false, description: "Disable toggling" }
+  ],
+  variants: [],
+  slots: [
+    { name: "children", description: "CollapsibleTrigger + CollapsibleContent", required: true, acceptedTypes: ["ReactNode"] }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-collapsible"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [],
+  examples: [
+    {
+      title: "Show more",
+      description: "Expand additional content below a preview",
+      code: '<Collapsible>\n  <div>Yesterday at 9:00 AM</div>\n  <CollapsibleTrigger asChild>\n    <Button variant="ghost" size="sm">Toggle</Button>\n  </CollapsibleTrigger>\n  <CollapsibleContent>\n    <div>Additional details here</div>\n  </CollapsibleContent>\n</Collapsible>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for a single show-more/show-less section: 'View full details', 'Advanced settings', preview cards with expandable notes.",
+    whenNotToUse: "Don't use for multiple related sections (use Accordion). Don't use for overlays (use Dialog/Popover). Don't use for navigation (use DropdownMenu).",
+    commonMistakes: [
+      "Using Collapsible for multiple sections instead of Accordion",
+      "Missing asChild when passing a Button as trigger",
+      "Not animating content height (Radix exposes --radix-collapsible-content-height for CSS keyframes)"
+    ],
+    relatedComponents: ["accordion", "dropdown-menu"],
+    accessibilityNotes: "Radix sets aria-expanded on the trigger and aria-controls \u2192 content id. Trigger is keyboard-operable (Enter/Space).",
+    tokenBudget: 250
+  },
+  tags: ["collapsible", "disclosure", "expand", "show-more"]
+};
+
+// src/components/hover-card/hover-card.schema.ts
+var hoverCardSchema = {
+  name: "hover-card",
+  displayName: "Hover Card",
+  description: "Rich floating content revealed on hover or focus. Use when Tooltip is too small and Popover requires a click.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    { name: "open", type: "boolean", required: false, description: "Controlled open state" },
+    { name: "defaultOpen", type: "boolean", required: false, default: false, description: "Default open state" },
+    { name: "onOpenChange", type: "function", required: false, description: "Callback on open change" },
+    { name: "openDelay", type: "number", required: false, default: 700, description: "Milliseconds before the card appears" },
+    { name: "closeDelay", type: "number", required: false, default: 300, description: "Milliseconds before the card closes after leaving" }
+  ],
+  variants: [],
+  slots: [
+    { name: "children", description: "HoverCardTrigger + HoverCardContent", required: true, acceptedTypes: ["ReactNode"] }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-hover-card", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["popover", "popover-foreground", "border"],
+  examples: [
+    {
+      title: "User profile preview",
+      description: "Username link that expands into a mini profile on hover",
+      code: '<HoverCard>\n  <HoverCardTrigger asChild>\n    <a href="#">@shadcn</a>\n  </HoverCardTrigger>\n  <HoverCardContent>\n    <div className="flex gap-3">\n      <Avatar><AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" /><AvatarFallback>CN</AvatarFallback></Avatar>\n      <div>\n        <h4 className="font-semibold">@shadcn</h4>\n        <p className="text-xs text-muted-foreground">Builds UI components</p>\n      </div>\n    </div>\n  </HoverCardContent>\n</HoverCard>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for rich hover previews: user profile cards, link previews, inline references. Contains multiple elements \u2014 more than a tooltip can hold.",
+    whenNotToUse: "Don't use for simple hover labels (use Tooltip). Don't use for click-triggered content (use Popover). Don't use as primary info on touch devices \u2014 hover doesn't exist there.",
+    commonMistakes: [
+      "Using HoverCard for critical info (invisible on touch)",
+      "Too-short openDelay causes flicker on mouse-over traffic",
+      "Omitting asChild on HoverCardTrigger with a custom element"
+    ],
+    relatedComponents: ["tooltip", "popover"],
+    accessibilityNotes: "Radix opens on hover and keyboard focus. Content must be meaningful on focus as well as hover. Consider an alternative for touch users.",
+    tokenBudget: 400
+  },
+  tags: ["hover-card", "preview", "overlay", "rich-tooltip"]
+};
+
+// src/components/context-menu/context-menu.schema.ts
+var contextMenuSchema = {
+  name: "context-menu",
+  displayName: "Context Menu",
+  description: "Right-click (or long-press on touch) menu anchored to the trigger region. Same item vocabulary as DropdownMenu.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    { name: "onOpenChange", type: "function", required: false, description: "Callback on open change" },
+    { name: "modal", type: "boolean", required: false, default: true, description: "When true, interaction outside is blocked" },
+    { name: "dir", type: "enum", required: false, description: "Reading direction", enumValues: ["ltr", "rtl"] }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "ContextMenuTrigger + ContextMenuContent. Content accepts ContextMenuItem, ContextMenuCheckboxItem, ContextMenuRadioGroup/ContextMenuRadioItem, ContextMenuLabel, ContextMenuSeparator, and ContextMenuShortcut.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-context-menu", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["popover", "popover-foreground", "accent", "accent-foreground", "border", "foreground", "muted-foreground"],
+  examples: [
+    {
+      title: "Right-click menu",
+      description: "Right-click the trigger region for actions",
+      code: '<ContextMenu>\n  <ContextMenuTrigger className="flex h-40 items-center justify-center rounded-md border border-dashed">Right-click here</ContextMenuTrigger>\n  <ContextMenuContent>\n    <ContextMenuItem>Back</ContextMenuItem>\n    <ContextMenuItem disabled>Forward</ContextMenuItem>\n    <ContextMenuSeparator />\n    <ContextMenuItem>Reload<ContextMenuShortcut>\u2318R</ContextMenuShortcut></ContextMenuItem>\n  </ContextMenuContent>\n</ContextMenu>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for right-click menus on a specific region: file-manager-style actions, canvas/editor context actions, row-level actions in tables.",
+    whenNotToUse: "Don't use for actions triggered by a button (use DropdownMenu). Don't use as the only way to access an action \u2014 must have a keyboard/button alternative.",
+    commonMistakes: [
+      "Using ContextMenu as the only affordance (unreachable on touch)",
+      "Triggering on the whole document (put it on a specific region)",
+      "Missing a keyboard alternative for items"
+    ],
+    relatedComponents: ["dropdown-menu", "menubar"],
+    accessibilityNotes: "Triggered via right-click or Shift+F10 on keyboard. Radix handles role='menu', aria-labelledby, focus management.",
+    tokenBudget: 700
+  },
+  tags: ["context-menu", "right-click", "menu", "actions"]
+};
+
+// src/components/menubar/menubar.schema.ts
+var menubarSchema = {
+  name: "menubar",
+  displayName: "Menubar",
+  description: "Desktop-app style menu bar (File / Edit / View). Horizontal menu strip with nested dropdowns.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    { name: "value", type: "string", required: false, description: "Controlled open menu id" },
+    { name: "defaultValue", type: "string", required: false, description: "Default open menu for uncontrolled usage" },
+    { name: "onValueChange", type: "function", required: false, description: "Callback when open menu changes" },
+    { name: "loop", type: "boolean", required: false, default: true, description: "When true, arrow-key navigation wraps" },
+    { name: "dir", type: "enum", required: false, description: "Reading direction", enumValues: ["ltr", "rtl"] },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes on the Menubar root" }
+  ],
+  variants: [],
+  slots: [
+    { name: "children", description: "MenubarMenu elements (each containing MenubarTrigger + MenubarContent)", required: true, acceptedTypes: ["ReactNode"] }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-menubar", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "popover", "popover-foreground", "accent", "accent-foreground", "muted", "muted-foreground"],
+  examples: [
+    {
+      title: "File / Edit bar",
+      description: "Two-menu bar with keyboard shortcuts",
+      code: "<Menubar>\n  <MenubarMenu>\n    <MenubarTrigger>File</MenubarTrigger>\n    <MenubarContent>\n      <MenubarItem>New Tab<MenubarShortcut>\u2318T</MenubarShortcut></MenubarItem>\n      <MenubarItem>New Window<MenubarShortcut>\u2318N</MenubarShortcut></MenubarItem>\n      <MenubarSeparator />\n      <MenubarItem>Share</MenubarItem>\n      <MenubarSeparator />\n      <MenubarItem>Print\u2026<MenubarShortcut>\u2318P</MenubarShortcut></MenubarItem>\n    </MenubarContent>\n  </MenubarMenu>\n  <MenubarMenu>\n    <MenubarTrigger>Edit</MenubarTrigger>\n    <MenubarContent>\n      <MenubarItem>Undo<MenubarShortcut>\u2318Z</MenubarShortcut></MenubarItem>\n      <MenubarItem>Redo<MenubarShortcut>\u21E7\u2318Z</MenubarShortcut></MenubarItem>\n    </MenubarContent>\n  </MenubarMenu>\n</Menubar>"
+    }
+  ],
+  ai: {
+    whenToUse: "Use for desktop-app shell menus: editors, IDEs, creative tools. Provides persistent menu bar with keyboard shortcuts.",
+    whenNotToUse: "Don't use for website navigation (use NavigationMenu). Don't use for single-button menus (use DropdownMenu). Poor fit for mobile \u2014 consider a hamburger menu.",
+    commonMistakes: [
+      "Using for website navigation (user expectations don't match)",
+      "Missing shortcuts (expected affordance in menubar UX)",
+      "Deeply nested sub-menus (>2 levels feels labyrinthine)"
+    ],
+    relatedComponents: ["navigation-menu", "dropdown-menu"],
+    accessibilityNotes: "Full WAI-ARIA menubar pattern: arrow keys navigate menus, Enter/Space opens, Escape closes. Radix handles roles and state.",
+    tokenBudget: 700
+  },
+  tags: ["menubar", "menu", "desktop", "app-shell", "navigation"]
+};
+
+// src/components/navigation-menu/navigation-menu.schema.ts
+var navigationMenuSchema = {
+  name: "navigation-menu",
+  displayName: "Navigation Menu",
+  description: "Website-style mega-menu with hover-triggered content panels. Used for marketing/site navigation headers.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    { name: "value", type: "string", required: false, description: "Controlled active menu value" },
+    { name: "onValueChange", type: "function", required: false, description: "Callback when active menu changes" },
+    { name: "delayDuration", type: "number", required: false, default: 200, description: "Delay before opening a menu on hover (ms)" },
+    { name: "orientation", type: "enum", required: false, default: "horizontal", description: "Layout direction", enumValues: ["horizontal", "vertical"] }
+  ],
+  variants: [],
+  slots: [
+    { name: "children", description: "NavigationMenuList containing NavigationMenuItem elements", required: true, acceptedTypes: ["ReactNode"] }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-navigation-menu", "class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "accent", "accent-foreground", "popover", "popover-foreground", "border"],
+  examples: [
+    {
+      title: "Simple nav",
+      description: "Top-level link + mega-menu trigger",
+      code: '<NavigationMenu>\n  <NavigationMenuList>\n    <NavigationMenuItem>\n      <NavigationMenuTrigger>Products</NavigationMenuTrigger>\n      <NavigationMenuContent>\n        <ul className="grid w-[400px] gap-3 p-4">\n          <li><NavigationMenuLink href="/docs">Docs</NavigationMenuLink></li>\n          <li><NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink></li>\n        </ul>\n      </NavigationMenuContent>\n    </NavigationMenuItem>\n    <NavigationMenuItem>\n      <NavigationMenuLink className={navigationMenuTriggerStyle()} href="/about">About</NavigationMenuLink>\n    </NavigationMenuItem>\n  </NavigationMenuList>\n</NavigationMenu>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for marketing-site top nav with grouped links and mega-menus: Products, Resources, Pricing flyouts. Desktop-first but keyboard accessible.",
+    whenNotToUse: "Don't use for app shell menus (use Menubar). Don't use for single dropdowns (use DropdownMenu). On mobile, pair with a separate hamburger/Drawer pattern \u2014 NavigationMenu collapses poorly on small screens.",
+    commonMistakes: [
+      "Mixing regular <a> with NavigationMenuLink \u2014 must use NavigationMenuLink for keyboard/roving focus",
+      "Forgetting the viewport \u2014 handled automatically when using the composed NavigationMenu root",
+      "Too many top-level items overflow on mobile"
+    ],
+    relatedComponents: ["menubar", "dropdown-menu"],
+    accessibilityNotes: "Radix implements the WAI-ARIA menu-button pattern with hover-intent delays and focus trapping in content. Links inside NavigationMenuLink get roving tabindex.",
+    tokenBudget: 800
+  },
+  tags: ["navigation-menu", "mega-menu", "nav", "header", "site"]
+};
+
+// src/components/breadcrumb/breadcrumb.schema.ts
+var breadcrumbSchema = {
+  name: "breadcrumb",
+  displayName: "Breadcrumb",
+  description: "A path trail showing the user's location within a hierarchy, with links back to ancestors and a non-interactive current page.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    { name: "className", type: "string", required: false, description: "Additional CSS classes on the nav element" }
+  ],
+  variants: [],
+  slots: [
+    { name: "children", description: "BreadcrumbList containing BreadcrumbItem + BreadcrumbSeparator elements", required: true, acceptedTypes: ["ReactNode"] }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-slot", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["foreground", "muted-foreground"],
+  examples: [
+    {
+      title: "Three-level path",
+      description: "Home / Components / Breadcrumb",
+      code: '<Breadcrumb>\n  <BreadcrumbList>\n    <BreadcrumbItem>\n      <BreadcrumbLink href="/">Home</BreadcrumbLink>\n    </BreadcrumbItem>\n    <BreadcrumbSeparator />\n    <BreadcrumbItem>\n      <BreadcrumbLink href="/docs/components">Components</BreadcrumbLink>\n    </BreadcrumbItem>\n    <BreadcrumbSeparator />\n    <BreadcrumbItem>\n      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>\n    </BreadcrumbItem>\n  </BreadcrumbList>\n</Breadcrumb>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use to show location within a hierarchical site or app: docs pages, product categories, nested settings. Include the current page as a non-link BreadcrumbPage.",
+    whenNotToUse: "Don't use for primary navigation (use NavigationMenu). Don't use for flat sites without hierarchy. Don't use when the hierarchy is too deep to display \u2014 truncate with BreadcrumbEllipsis.",
+    commonMistakes: [
+      "Making the current page a link (use BreadcrumbPage)",
+      "Showing just one item (defeats the purpose)",
+      "Using plain text separators without aria-hidden"
+    ],
+    relatedComponents: ["navigation-menu"],
+    accessibilityNotes: "Root <nav aria-label='breadcrumb'> creates a landmark. BreadcrumbPage has aria-current='page'. Separators are aria-hidden (decorative). BreadcrumbEllipsis is decorative (SVG aria-hidden) with a sr-only 'More pages' label.",
+    tokenBudget: 400
+  },
+  tags: ["breadcrumb", "navigation", "path", "trail", "hierarchy"]
+};
+
+// src/components/alert/alert.schema.ts
+var alertSchema = {
+  name: "alert",
+  displayName: "Alert",
+  description: "An inline notification banner for important messages. Supports default and destructive variants with optional leading icon.",
+  category: "component",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Visual style",
+      enumValues: ["default", "destructive"]
+    },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Alert style",
+      values: [
+        { value: "default", description: "Neutral inline notification" },
+        { value: "destructive", description: "Error or warning with red accent + tinted background" }
+      ],
+      default: "default"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Optional icon SVG + AlertTitle + AlertDescription",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "foreground", "destructive", "border"],
+  examples: [
+    {
+      title: "Info alert",
+      description: "Default alert with title and description",
+      code: "<Alert>\n  <AlertTitle>Heads up!</AlertTitle>\n  <AlertDescription>You can add components to your app via the CLI.</AlertDescription>\n</Alert>"
+    },
+    {
+      title: "Destructive alert",
+      description: "Error alert",
+      code: '<Alert variant="destructive">\n  <AlertTitle>Error</AlertTitle>\n  <AlertDescription>Your session has expired. Please sign in again.</AlertDescription>\n</Alert>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for inline, persistent messages that contextualize a page or section: info banners, warning about deprecated features, error summaries above forms.",
+    whenNotToUse: "Don't use for transient messages (use Toast/Sonner). Don't use for modal confirmations (use AlertDialog). Don't use as the only way to communicate a critical error \u2014 pair with field-level feedback.",
+    commonMistakes: [
+      "Using destructive for non-error messages",
+      "Missing AlertTitle (reduces scannability)",
+      "Stacking multiple Alerts on the same page instead of grouping"
+    ],
+    relatedComponents: ["alert-dialog", "sonner"],
+    accessibilityNotes: "Root renders role='alert' so screen readers announce it. For non-urgent info banners consider role='status' or aria-live='polite' via className overrides.",
+    tokenBudget: 350
+  },
+  tags: ["alert", "notification", "banner", "info", "warning", "error"]
+};
+
+// src/components/sonner/sonner.schema.ts
+var sonnerSchema = {
+  name: "sonner",
+  displayName: "Sonner (Toast)",
+  description: "Ephemeral toast notifications via Sonner. Render <Toaster /> once at app root, then call toast() anywhere.",
+  category: "component",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "position",
+      type: "enum",
+      required: false,
+      default: "bottom-right",
+      description: "Where toasts appear on screen",
+      enumValues: [
+        "top-left",
+        "top-center",
+        "top-right",
+        "bottom-left",
+        "bottom-center",
+        "bottom-right"
+      ]
+    },
+    {
+      name: "richColors",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Enable success/error/warning color variants via toast.success/error/warning"
+    },
+    {
+      name: "closeButton",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Show a close button on each toast"
+    },
+    {
+      name: "theme",
+      type: "enum",
+      required: false,
+      default: "system",
+      description: "Visual theme",
+      enumValues: ["light", "dark", "system"]
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["sonner"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "foreground", "border", "muted", "muted-foreground", "primary", "primary-foreground"],
+  examples: [
+    {
+      title: "App setup + fire toast",
+      description: "Render Toaster once, call toast() anywhere",
+      code: '// In your root layout:\n<Toaster />\n\n// Anywhere in your app:\nimport { toast } from "@/components/ui/sonner";\n\n<Button onClick={() => toast("Event created", { description: "Friday, Dec 11 at 10:00 AM" })}>\n  Show toast\n</Button>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for transient feedback: save confirmations, error messages, background task completion. Pairs well with mutation handlers (onSuccess/onError).",
+    whenNotToUse: "Don't use for persistent info (use Alert). Don't use for destructive confirmations (use AlertDialog). Don't use for critical errors that block user workflow.",
+    commonMistakes: [
+      "Rendering multiple <Toaster /> components (one is enough)",
+      "Calling toast() during server rendering (must be client-side)",
+      "Using toast for messages the user needs to re-read (they auto-dismiss)"
+    ],
+    relatedComponents: ["alert", "alert-dialog"],
+    accessibilityNotes: "Sonner handles aria-live='polite' on the toast region so screen readers announce new toasts. Critical messages should still use Alert/AlertDialog for persistent visibility.",
+    tokenBudget: 450
+  },
+  tags: ["toast", "sonner", "notification", "transient", "feedback"]
+};
+
+// src/components/table/table.schema.ts
+var tableSchema = {
+  name: "table",
+  displayName: "Table",
+  description: "Styled HTML table primitives (Table / TableHeader / TableBody / TableRow / TableHead / TableCell / TableCaption / TableFooter). Low-level building blocks \u2014 use DataTable for sorting/filtering/pagination.",
+  category: "component",
+  subcategory: "data",
+  props: [
+    { name: "className", type: "string", required: false, description: "Additional CSS classes on the <table>" }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "TableHeader + TableBody + TableFooter + TableCaption. Use TableRow/TableHead/TableCell inside.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "muted-foreground", "border"],
+  examples: [
+    {
+      title: "Basic table",
+      description: "Three-column styled table with header + rows",
+      code: '<Table>\n  <TableCaption>A list of your recent invoices.</TableCaption>\n  <TableHeader>\n    <TableRow>\n      <TableHead>Invoice</TableHead>\n      <TableHead>Status</TableHead>\n      <TableHead className="text-right">Amount</TableHead>\n    </TableRow>\n  </TableHeader>\n  <TableBody>\n    <TableRow>\n      <TableCell className="font-medium">INV001</TableCell>\n      <TableCell>Paid</TableCell>\n      <TableCell className="text-right">$250.00</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for simple tabular data where you render rows manually: invoice lists, pricing rows, settings tables. Responsive container wraps the <table> to allow horizontal scroll on small screens.",
+    whenNotToUse: "Don't use for large datasets that need sorting/filtering/pagination (use DataTable). Don't use for layout (use CSS grid/flex). Don't use for <form> field arrays (use native fields).",
+    commonMistakes: [
+      "Using <div> grids instead of a real <table> for tabular data (breaks a11y)",
+      "Putting interactive controls in headers without keyboard semantics",
+      "Missing TableCaption when the table has no other label"
+    ],
+    relatedComponents: ["data-table", "pagination"],
+    accessibilityNotes: "Semantic <table> / <thead> / <tbody> is used, so screen readers announce rows/columns. Include a TableCaption or aria-label. Mark column sort buttons with aria-sort.",
+    tokenBudget: 450
+  },
+  tags: ["table", "data", "rows", "tabular"]
+};
+
+// src/components/data-table/data-table.schema.ts
+var dataTableSchema = {
+  name: "data-table",
+  displayName: "Data Table",
+  description: "Generic data-driven table built on TanStack Table + Hex UI Table primitives. Pass columns + data; add sorting/filtering/pagination via TanStack hooks.",
+  category: "component",
+  subcategory: "data",
+  props: [
+    { name: "columns", type: "object", required: true, description: "ColumnDef<TData, TValue>[] from @tanstack/react-table" },
+    { name: "data", type: "object", required: true, description: "Array of row data" },
+    {
+      name: "caption",
+      type: "ReactNode",
+      required: false,
+      description: "Visible caption rendered below the table; announced by screen readers when entering the table"
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: false,
+      description: "Accessible label forwarded as aria-label on the underlying <table>; use when no visible caption is shown"
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@tanstack/react-table", "clsx", "tailwind-merge"],
+    internal: ["lib/utils", "components/table/table"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["border", "muted", "muted-foreground"],
+  examples: [
+    {
+      title: "Basic data table",
+      description: "Three-column table rendered from TanStack column defs",
+      code: 'import type { ColumnDef } from "@tanstack/react-table";\nimport { DataTable } from "@/components/ui/data-table";\n\ntype Payment = { id: string; amount: number; status: "pending" | "paid" | "failed"; email: string };\n\nconst columns: ColumnDef<Payment>[] = [\n  { accessorKey: "status", header: "Status" },\n  { accessorKey: "email", header: "Email" },\n  { accessorKey: "amount", header: "Amount" },\n];\n\nconst data: Payment[] = [\n  { id: "1", amount: 100, status: "paid", email: "a@x.com" },\n  { id: "2", amount: 250, status: "pending", email: "b@x.com" },\n];\n\nexport function Example() {\n  return <DataTable columns={columns} data={data} />;\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for tabular data that needs sorting, filtering, pagination, or row selection. Define columns once, feed data \u2014 TanStack handles the row model. Add more features incrementally (getSortedRowModel, getFilteredRowModel, getPaginationRowModel).",
+    whenNotToUse: "Don't use for static/simple tables (use Table primitives directly). Don't use for virtualized very-large lists (use TanStack Virtual). Don't use for grid layouts (use CSS grid). DataTable is a Client Component (uses useReactTable hook) \u2014 fetch data in a Server Component and pass it as props.",
+    commonMistakes: [
+      "Forgetting getCoreRowModel() (table renders nothing)",
+      "Recreating columns array on every render (breaks memoization \u2014 wrap in useMemo or define outside the component)",
+      "Using accessorKey with nested paths without accessorFn",
+      "Not adding filter/sort row models when those features are needed",
+      "Shipping a table without `caption` or `aria-label` \u2014 the table is unlabelled to assistive tech"
+    ],
+    relatedComponents: ["table", "pagination"],
+    accessibilityNotes: "Pass either `caption` (visible) or `aria-label` so screen readers announce the table when the user enters it. Add aria-sort to sortable column headers. Announce filter/sort changes via aria-live for dynamic updates.",
+    tokenBudget: 900
+  },
+  tags: ["data-table", "tanstack", "sortable", "filterable", "paginated"]
+};
+
+// src/components/pagination/pagination.schema.ts
+var paginationSchema = {
+  name: "pagination",
+  displayName: "Pagination",
+  description: "Composable pagination controls (Pagination / PaginationContent / PaginationItem / PaginationLink / PaginationPrevious / PaginationNext / PaginationEllipsis). Link-based by default \u2014 pair with client-side navigation or server params.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    { name: "className", type: "string", required: false, description: "Additional CSS classes on the <nav>" }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "PaginationContent containing PaginationItem elements (PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils", "primitives/button/button"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["accent", "accent-foreground", "input", "background"],
+  examples: [
+    {
+      title: "Basic pagination",
+      description: "Previous + 3 pages + ellipsis + Next with current page marked",
+      code: '<Pagination>\n  <PaginationContent>\n    <PaginationItem>\n      <PaginationPrevious href="#" />\n    </PaginationItem>\n    <PaginationItem>\n      <PaginationLink href="#">1</PaginationLink>\n    </PaginationItem>\n    <PaginationItem>\n      <PaginationLink href="#" isActive>2</PaginationLink>\n    </PaginationItem>\n    <PaginationItem>\n      <PaginationLink href="#">3</PaginationLink>\n    </PaginationItem>\n    <PaginationItem>\n      <PaginationEllipsis />\n    </PaginationItem>\n    <PaginationItem>\n      <PaginationNext href="#" />\n    </PaginationItem>\n  </PaginationContent>\n</Pagination>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for navigating between pages of a paginated dataset: blog lists, search results, table rows. Use PaginationEllipsis to truncate long ranges.",
+    whenNotToUse: "Don't use for infinite scroll (use IntersectionObserver). Don't use for step-by-step wizards (use a stepper). Don't use for fewer than ~3 pages (just show all the items).",
+    commonMistakes: [
+      "Using PaginationLink without href (anchor is not keyboard-reachable)",
+      "Forgetting isActive on the current page (no visual or aria-current feedback)",
+      "Showing every page number on long ranges \u2014 use PaginationEllipsis to truncate",
+      "Using onClick-only <button> instead of PaginationLink \u2014 loses right-click-open-new-tab affordance; prefer href + Next.js Link when client-side routing is needed"
+    ],
+    relatedComponents: ["table", "data-table"],
+    accessibilityNotes: "Root is role='navigation' aria-label='pagination'. Active link gets aria-current='page'. Previous/Next have aria-label. Ellipsis is decorative (aria-hidden) with a sr-only 'More pages' label.",
+    tokenBudget: 500
+  },
+  tags: ["pagination", "pages", "navigation", "list"]
+};
+
+// src/components/calendar/calendar.schema.ts
+var calendarSchema = {
+  name: "calendar",
+  displayName: "Calendar",
+  description: "Date grid built on react-day-picker v9. Supports single, multiple, and range selection modes. Keyboard navigable and localizable.",
+  category: "component",
+  subcategory: "input",
+  props: [
+    {
+      name: "mode",
+      type: "string",
+      required: false,
+      default: "single",
+      description: "Selection mode: 'single' | 'multiple' | 'range'"
+    },
+    {
+      name: "selected",
+      type: "object",
+      required: false,
+      description: "Controlled selected value (Date, Date[], or DateRange depending on mode)"
+    },
+    {
+      name: "onSelect",
+      type: "function",
+      required: false,
+      description: "Callback when selection changes"
+    },
+    {
+      name: "disabled",
+      type: "object",
+      required: false,
+      description: "DayPicker Matcher \u2014 accepts a Date, Date[], { from, to }, { before | after }, or a (date: Date) => boolean predicate"
+    },
+    {
+      name: "showOutsideDays",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Render days from the previous/next month in the grid"
+    },
+    {
+      name: "numberOfMonths",
+      type: "number",
+      required: false,
+      default: 1,
+      description: "How many months to display side-by-side"
+    },
+    {
+      name: "defaultMonth",
+      type: "object",
+      required: false,
+      description: "The month to render first (uncontrolled). Date object."
+    },
+    {
+      name: "fromDate",
+      type: "object",
+      required: false,
+      description: "Earliest selectable date (Date). Days before are disabled."
+    },
+    {
+      name: "toDate",
+      type: "object",
+      required: false,
+      description: "Latest selectable date (Date). Days after are disabled."
+    },
+    {
+      name: "locale",
+      type: "object",
+      required: false,
+      description: "date-fns Locale object (e.g. `import { es } from 'date-fns/locale'`) for weekday/month labels"
+    },
+    {
+      name: "weekStartsOn",
+      type: "number",
+      required: false,
+      default: 0,
+      description: "First day of the week (0 = Sunday, 1 = Monday, \u2026, 6 = Saturday)"
+    },
+    {
+      name: "classNames",
+      type: "object",
+      required: false,
+      description: "Per-part className overrides (merged with defaults)"
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["react-day-picker", "date-fns", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["accent", "accent-foreground", "primary", "primary-foreground", "muted-foreground", "ring"],
+  examples: [
+    {
+      title: "Single date selection",
+      description: "Bind a Date state to selected/onSelect",
+      code: 'import { useState } from "react";\nimport { Calendar } from "@/components/ui/calendar";\n\nexport function Example() {\n  const [date, setDate] = useState<Date | undefined>(new Date());\n  return <Calendar mode="single" selected={date} onSelect={setDate} className="rounded-md border" />;\n}'
+    },
+    {
+      title: "Range selection",
+      description: "Pick a start and end date",
+      code: 'import { useState } from "react";\nimport type { DateRange } from "react-day-picker";\nimport { Calendar } from "@/components/ui/calendar";\n\nexport function Example() {\n  const [range, setRange] = useState<DateRange | undefined>();\n  return <Calendar mode="range" selected={range} onSelect={setRange} numberOfMonths={2} />;\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for inline date selection UIs, or as the month-grid inside a DatePicker (wrapped in a Popover). Supports single date, multi-date, and range modes.",
+    whenNotToUse: "Don't use when only a text date input is needed (use Input type=date). Don't embed inside a very narrow container \u2014 the grid needs ~280px min width. For scheduling UIs with time, combine with a separate time picker.",
+    commonMistakes: [
+      "Passing a string to selected (must be a Date, Date[], or DateRange object)",
+      "Forgetting mode prop (default is single, but being explicit avoids confusion)",
+      "Overriding classNames completely instead of spreading \u2014 loses default styling",
+      "Using inside a Server Component without marking the consumer 'use client'"
+    ],
+    relatedComponents: ["date-picker", "popover", "input"],
+    accessibilityNotes: "react-day-picker wires aria-label, aria-selected, and keyboard navigation (arrows, Home/End, PageUp/Down). Focus rings on day buttons use the ring token.",
+    tokenBudget: 800
+  },
+  tags: ["calendar", "date", "date-picker", "input"]
+};
+
+// src/components/date-picker/date-picker.schema.ts
+var datePickerSchema = {
+  name: "date-picker",
+  displayName: "Date Picker",
+  description: "Date input composed from Popover + Calendar. Shows the selected date formatted via date-fns, opens a calendar grid on click.",
+  category: "component",
+  subcategory: "input",
+  props: [
+    {
+      name: "value",
+      type: "object",
+      required: false,
+      description: "Controlled selected Date"
+    },
+    {
+      name: "onChange",
+      type: "function",
+      required: false,
+      description: "Callback when the user selects a date: (date: Date | undefined) => void"
+    },
+    {
+      name: "placeholder",
+      type: "string",
+      required: false,
+      default: "Pick a date",
+      description: "Text shown on the trigger when no date is selected"
+    },
+    {
+      name: "dateFormat",
+      type: "string",
+      required: false,
+      default: "PPP",
+      description: "date-fns format token for the trigger label (e.g. 'PPP', 'yyyy-MM-dd')"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the picker trigger"
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: false,
+      description: "Accessible label \u2014 required when no adjacent visible <label> is used"
+    },
+    {
+      name: "captionLayout",
+      type: "string",
+      required: false,
+      description: "Caption layout forwarded to react-day-picker. Use 'dropdown' (or 'dropdown-years' / 'dropdown-months') for native <select> navigation \u2014 common for birth-date pickers. Default is 'label' (chevron buttons only)."
+    },
+    {
+      name: "startMonth",
+      type: "object",
+      required: false,
+      description: "Earliest month/year navigable in the calendar (Date). Forwarded to react-day-picker. Pair with captionLayout='dropdown'."
+    },
+    {
+      name: "endMonth",
+      type: "object",
+      required: false,
+      description: "Latest month/year navigable in the calendar (Date). Forwarded to react-day-picker. Pair with captionLayout='dropdown'."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["react-day-picker", "date-fns", "@radix-ui/react-popover", "clsx", "tailwind-merge"],
+    internal: ["components/calendar/calendar", "components/popover/popover", "lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "border", "input", "ring", "accent", "accent-foreground", "muted-foreground"],
+  examples: [
+    {
+      title: "Basic date picker",
+      description: "Bind a Date state and render the picker",
+      code: 'import { useState } from "react";\nimport { DatePicker } from "@/components/ui/date-picker";\n\nexport function Example() {\n  const [date, setDate] = useState<Date | undefined>();\n  return <DatePicker value={date} onChange={setDate} />;\n}'
+    },
+    {
+      title: "Birth-date picker with year dropdown",
+      description: "Use captionLayout='dropdown' with explicit startMonth/endMonth to get native <select> year navigation",
+      code: 'import { useState } from "react";\nimport { DatePicker } from "@/components/ui/date-picker";\n\nexport function Example() {\n  const [dob, setDob] = useState<Date | undefined>();\n  return (\n    <DatePicker\n      value={dob}\n      onChange={setDob}\n      placeholder="Date of birth"\n      captionLayout="dropdown"\n      startMonth={new Date(1925, 0)}\n      endMonth={new Date(new Date().getFullYear(), 11)}\n    />\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for selecting a single date in a form. Shows a formatted text label and opens a month grid on click. Composes Popover + Calendar + button trigger. For far-away years (birthdays, historical dates), pass captionLayout='dropdown' plus startMonth/endMonth.",
+    whenNotToUse: "Don't use for date ranges (compose Calendar mode='range' + Popover yourself). Don't use for native mobile date UX (<input type='date'> is often better on phones). Don't use if you need time selection \u2014 combine with a separate time picker.",
+    commonMistakes: [
+      "Passing a string to value \u2014 must be a Date object",
+      "Missing aria-label when the picker has no adjacent visible <label>",
+      "Overriding className in a way that hurts focus ring visibility",
+      "Forgetting that the popover auto-closes on select \u2014 provide onChange to capture the value",
+      "Setting captionLayout='dropdown' without startMonth/endMonth \u2014 react-day-picker defaults to \xB1100 years, producing a 200-option dropdown"
+    ],
+    relatedComponents: ["calendar", "popover", "input"],
+    accessibilityNotes: "Trigger is a real <button> with focus ring. When rendered without a visible label, pass aria-label. The popover portals and traps keyboard focus inside Calendar until the user selects or presses Escape.",
+    tokenBudget: 700
+  },
+  tags: ["date-picker", "date", "input", "popover", "calendar"]
+};
+
+// src/components/input-otp/input-otp.schema.ts
+var inputOTPSchema = {
+  name: "input-otp",
+  displayName: "Input OTP",
+  description: "One-time-password / verification-code entry built on the input-otp library. Renders N character slots with active/caret state and auto-advance on type.",
+  category: "component",
+  subcategory: "forms",
+  props: [
+    {
+      name: "maxLength",
+      type: "number",
+      required: true,
+      description: "Total number of slots (typically 4\u20138 for OTPs)"
+    },
+    {
+      name: "value",
+      type: "string",
+      required: false,
+      description: "Controlled value \u2014 the current entered string"
+    },
+    {
+      name: "onChange",
+      type: "function",
+      required: false,
+      description: "Callback fired as the user types: (value: string) => void"
+    },
+    {
+      name: "onComplete",
+      type: "function",
+      required: false,
+      description: "Called when all slots are filled (useful to auto-submit)"
+    },
+    {
+      name: "pattern",
+      type: "string",
+      required: false,
+      description: "Regex to restrict input (use REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, or REGEXP_ONLY_DIGITS_AND_CHARS)"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the whole input"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "InputOTPGroup with InputOTPSlot index={0..maxLength-1}, optional InputOTPSeparator",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["input-otp", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["input", "ring", "background", "foreground", "muted-foreground"],
+  examples: [
+    {
+      title: "6-digit OTP with separator",
+      description: "Two groups of 3 slots divided by a bullet",
+      code: 'import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from "@/components/ui/input-otp";\nimport { REGEXP_ONLY_DIGITS } from "input-otp";\n\nexport function Example() {\n  return (\n    <InputOTP maxLength={6} pattern={REGEXP_ONLY_DIGITS}>\n      <InputOTPGroup>\n        <InputOTPSlot index={0} />\n        <InputOTPSlot index={1} />\n        <InputOTPSlot index={2} />\n      </InputOTPGroup>\n      <InputOTPSeparator />\n      <InputOTPGroup>\n        <InputOTPSlot index={3} />\n        <InputOTPSlot index={4} />\n        <InputOTPSlot index={5} />\n      </InputOTPGroup>\n    </InputOTP>\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for one-time password, email verification code, 2FA code, or any fixed-length code entry. Auto-advances on type, supports paste of the full code, and supports regex validation.",
+    whenNotToUse: "Don't use for variable-length codes (use a plain Input). Don't use for passwords (use Input type='password'). Don't use for open-ended short text \u2014 the slot UI implies a code.",
+    commonMistakes: [
+      "Forgetting to render maxLength slots \u2014 the underlying input's maxLength won't match the visible UI",
+      "Using pattern without importing one of the REGEXP_ONLY_* constants from 'input-otp'",
+      "Wrapping the whole thing in a <form> without a submit handler \u2014 onComplete is often a better auto-submit hook",
+      "Overriding slot className in a way that removes the first/last border-radius rules"
+    ],
+    relatedComponents: ["input", "form"],
+    accessibilityNotes: "input-otp manages a single hidden <input> so screen readers hear one field of N characters. Each slot is a visual representation. The active slot gets a focus ring via the ring token.",
+    tokenBudget: 700
+  },
+  tags: ["input-otp", "otp", "verification", "2fa", "code", "pin"]
+};
+
+// src/components/command/command.schema.ts
+var commandSchema = {
+  name: "command",
+  displayName: "Command",
+  description: "Composable command menu built on cmdk \u2014 search input + filtered list with keyboard navigation. Use as an inline palette or, wrapped in CommandDialog, as a \u2318K-style launcher.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    {
+      name: "shouldFilter",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Built-in filtering. Set to false for fully-controlled filtering."
+    },
+    {
+      name: "filter",
+      type: "function",
+      required: false,
+      description: "Custom scoring function: (value, search, keywords?) => number (0..1)"
+    },
+    {
+      name: "value",
+      type: "string",
+      required: false,
+      description: "Controlled active-item value"
+    },
+    {
+      name: "onValueChange",
+      type: "function",
+      required: false,
+      description: "Callback when the highlighted item changes"
+    },
+    {
+      name: "loop",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Loop arrow-key navigation at the ends of the list"
+    },
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      description: "Accessible label for the menu (not shown visually)"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "CommandInput + CommandList with CommandEmpty, CommandGroup, CommandItem, CommandSeparator",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["cmdk", "@radix-ui/react-dialog", "clsx", "tailwind-merge"],
+    internal: ["components/dialog/dialog", "lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["popover", "popover-foreground", "accent", "accent-foreground", "border", "muted-foreground"],
+  examples: [
+    {
+      title: "Command dialog launcher (\u2318K)",
+      description: "Toggle a command palette with keyboard shortcut",
+      code: 'import { useEffect, useState } from "react";\nimport { CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from "@/components/ui/command";\n\nexport function Example() {\n  const [open, setOpen] = useState(false);\n  useEffect(() => {\n    const down = (e: KeyboardEvent) => {\n      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {\n        e.preventDefault();\n        setOpen(v => !v);\n      }\n    };\n    document.addEventListener("keydown", down);\n    return () => document.removeEventListener("keydown", down);\n  }, []);\n  return (\n    <CommandDialog open={open} onOpenChange={setOpen}>\n      <CommandInput placeholder="Type a command or search\u2026" />\n      <CommandList>\n        <CommandEmpty>No results found.</CommandEmpty>\n        <CommandGroup heading="Suggestions">\n          <CommandItem onSelect={() => setOpen(false)}>Profile</CommandItem>\n          <CommandItem onSelect={() => setOpen(false)}>Settings</CommandItem>\n        </CommandGroup>\n      </CommandList>\n    </CommandDialog>\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for searchable menus, command palettes, \u2318K launchers, or as the list body of a Combobox. Built-in fuzzy filter + arrow-key nav + Enter-to-select.",
+    whenNotToUse: "Don't use for small static lists (use plain DropdownMenu). Don't use for large data tables (use DataTable). If you need a select input with a single bound value, Combobox is the higher-level wrapper.",
+    commonMistakes: [
+      "Forgetting CommandList \u2014 items won't be scrollable or grouped properly",
+      "Giving CommandItem non-unique values (breaks filtering and controlled state)",
+      "Overriding CommandInput className to remove the border/padding \u2014 breaks the \u2318K icon layout",
+      "Not rendering CommandEmpty \u2014 the list looks broken when a search has no matches",
+      "Querying CommandSeparator via cmdk's internal Separator state \u2014 Hex UI renders it as a presentational div with role='none' (and the `data-cmdk-separator` attribute preserved for selector compatibility) so it can sit inside CommandList's role=listbox without violating ARIA"
+    ],
+    relatedComponents: ["combobox", "dialog", "dropdown-menu"],
+    accessibilityNotes: "cmdk wires role=listbox/option and aria-activedescendant. Use the `label` prop on Command for a screen-reader-only name when no visible heading exists. CommandSeparator renders with role='none' (still selectable via `[data-cmdk-separator]`) so listbox-children rules are satisfied.",
+    tokenBudget: 900
+  },
+  tags: ["command", "cmdk", "palette", "search", "launcher"]
+};
+
+// src/components/combobox/combobox.schema.ts
+var comboboxSchema = {
+  name: "combobox",
+  displayName: "Combobox",
+  description: "Searchable single-select input. Composes Popover + Command (cmdk) + a styled trigger. Pass a list of { value, label } options.",
+  category: "component",
+  subcategory: "input",
+  props: [
+    {
+      name: "options",
+      type: "object",
+      required: true,
+      description: "Array of { value: string, label: string, disabled?: boolean }"
+    },
+    {
+      name: "value",
+      type: "string",
+      required: false,
+      description: "Controlled selected option value"
+    },
+    {
+      name: "onChange",
+      type: "function",
+      required: false,
+      description: "Callback when the user picks an option: (value: string) => void"
+    },
+    {
+      name: "placeholder",
+      type: "string",
+      required: false,
+      default: "Select\u2026",
+      description: "Text shown on the trigger when nothing is selected"
+    },
+    {
+      name: "searchPlaceholder",
+      type: "string",
+      required: false,
+      default: "Search\u2026",
+      description: "Placeholder for the filter input"
+    },
+    {
+      name: "emptyText",
+      type: "string",
+      required: false,
+      default: "No results found.",
+      description: "Shown inside the list when the search has no matches"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the trigger"
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: false,
+      description: "Accessible label \u2014 required when no adjacent visible label is used"
+    },
+    {
+      name: "aria-labelledby",
+      type: "string",
+      required: false,
+      description: "Id of an external visible label that names the combobox"
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["cmdk", "@radix-ui/react-popover", "clsx", "tailwind-merge"],
+    internal: [
+      "components/command/command",
+      "components/popover/popover",
+      "lib/utils"
+    ],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "input", "ring", "accent", "accent-foreground", "muted-foreground"],
+  examples: [
+    {
+      title: "Framework picker",
+      description: "Searchable single-select with a small static list",
+      code: 'import { useState } from "react";\nimport { Combobox } from "@/components/ui/combobox";\n\nconst frameworks = [\n  { value: "next", label: "Next.js" },\n  { value: "remix", label: "Remix" },\n  { value: "astro", label: "Astro" },\n  { value: "nuxt", label: "Nuxt" },\n];\n\nexport function Example() {\n  const [value, setValue] = useState<string>();\n  return <Combobox options={frameworks} value={value} onChange={setValue} placeholder="Pick a framework" />;\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for a select input when the list is >~8 items or users benefit from typing to narrow. Fuzzy search + keyboard nav + selected-item checkmark.",
+    whenNotToUse: "Don't use for native-select parity on mobile (use Select). Don't use for multi-select (this component is single-value \u2014 compose Command + Popover yourself for multi). Don't use for free-text entry (use Input).",
+    commonMistakes: [
+      "Passing duplicate option values (breaks selection and filtering)",
+      "Two options with identical labels \u2014 cmdk dedupes by the Item's filter value (the label here), so one will be dropped from the list",
+      "Using the label as the value \u2014 fine if stable, but prefer a short stable `value` string",
+      "Forgetting to bind value + onChange \u2014 uncontrolled mode doesn't exist on this wrapper",
+      "Mixing translated labels without keying on value \u2014 label changes won't update selection",
+      "Missing aria-label / aria-labelledby \u2014 role='combobox' does not allow name from contents, so without one of these the trigger has no accessible name"
+    ],
+    relatedComponents: ["command", "popover", "select"],
+    accessibilityNotes: "Trigger has role='combobox' + aria-expanded + aria-haspopup='listbox'. aria-controls points at the inner CommandList (a useId-stabilized listbox). Pass aria-label or aria-labelledby \u2014 combobox does not derive its name from contents.",
+    tokenBudget: 900
+  },
+  tags: ["combobox", "select", "search", "cmdk", "input"]
+};
+
+// src/components/multi-combobox/multi-combobox.schema.ts
+var multiComboboxSchema = {
+  name: "multi-combobox",
+  displayName: "MultiCombobox",
+  description: "Searchable multi-select input. Composes Popover + Command (cmdk) + a styled trigger. Trigger shows '{n} selected'; each option exposes aria-selected.",
+  category: "component",
+  subcategory: "input",
+  props: [
+    {
+      name: "options",
+      type: "object",
+      required: true,
+      description: "Array of { value: string, label: string, disabled?: boolean }"
+    },
+    {
+      name: "value",
+      type: "object",
+      required: false,
+      description: "Controlled selected values (string[])"
+    },
+    {
+      name: "onChange",
+      type: "function",
+      required: false,
+      description: "Callback when the user toggles an option: (values: string[]) => void"
+    },
+    {
+      name: "placeholder",
+      type: "string",
+      required: false,
+      default: "Select\u2026",
+      description: "Text shown on the trigger when nothing is selected"
+    },
+    {
+      name: "searchPlaceholder",
+      type: "string",
+      required: false,
+      default: "Search\u2026",
+      description: "Placeholder for the filter input"
+    },
+    {
+      name: "emptyText",
+      type: "string",
+      required: false,
+      default: "No results found.",
+      description: "Shown inside the list when the search has no matches"
+    },
+    {
+      name: "maxSelected",
+      type: "number",
+      required: false,
+      description: "Soft cap on selections \u2014 once reached, unselected options become aria-disabled and clicks are ignored"
+    },
+    {
+      name: "closeOnSelect",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Close the popover after every pick. Default false matches multi-select UX (Linear/Notion)."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the trigger"
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: false,
+      description: "Accessible label \u2014 required when no adjacent visible label is used"
+    },
+    {
+      name: "aria-labelledby",
+      type: "string",
+      required: false,
+      description: "Id of an external visible label that names the combobox"
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["cmdk", "@radix-ui/react-popover", "clsx", "tailwind-merge"],
+    internal: [
+      "components/command/command",
+      "components/popover/popover",
+      "lib/utils"
+    ],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [
+    "background",
+    "input",
+    "ring",
+    "accent",
+    "accent-foreground",
+    "muted-foreground"
+  ],
+  examples: [
+    {
+      title: "Tag picker",
+      description: "Multi-select with a small static list and chip count",
+      code: 'import { useState } from "react";\nimport { MultiCombobox } from "@/components/ui/multi-combobox";\n\nconst tags = [\n  { value: "bug", label: "Bug" },\n  { value: "feature", label: "Feature" },\n  { value: "question", label: "Question" },\n  { value: "docs", label: "Documentation" },\n];\n\nexport function Example() {\n  const [picks, setPicks] = useState<string[]>([]);\n  return (\n    <MultiCombobox\n      options={tags}\n      value={picks}\n      onChange={setPicks}\n      placeholder="Pick tags"\n      aria-label="Tags"\n    />\n  );\n}'
+    },
+    {
+      title: "Capped selection",
+      description: "Limit the number of items the user can pick",
+      code: 'import { useState } from "react";\nimport { MultiCombobox } from "@/components/ui/multi-combobox";\n\nexport function Example() {\n  const [picks, setPicks] = useState<string[]>([]);\n  return (\n    <MultiCombobox\n      options={tags}\n      value={picks}\n      onChange={setPicks}\n      maxSelected={3}\n      aria-label="Up to 3 tags"\n    />\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use to pick multiple items from a list of >~8 options where users benefit from typing to narrow. Common for tags, recipients, filters. Trigger shows count, each option exposes aria-selected.",
+    whenNotToUse: "Don't use for single-select (use Combobox). Don't use for free-text entry (use Input or a tag input). Don't use for very large lists (>500 options) without server-side filtering \u2014 cmdk filters in-memory.",
+    commonMistakes: [
+      "Passing duplicate option values \u2014 Set-based selection treats them as one",
+      "Two options with identical labels \u2014 cmdk dedupes by the Item's filter value (the label here), so one will be dropped from the list",
+      "Forgetting that value is string[] not string \u2014 passing a single string breaks Array iteration",
+      "Setting closeOnSelect={true} for a power-user picker \u2014 multi-select normally stays open until the user dismisses",
+      "Missing aria-label / aria-labelledby \u2014 role='combobox' does not derive its name from contents, so the trigger has no accessible name without one",
+      "Relying on maxSelected to enforce business rules \u2014 the cap is a UX hint; always validate the array length on submit"
+    ],
+    relatedComponents: ["combobox", "command", "popover", "select"],
+    accessibilityNotes: "Trigger has role='combobox' + aria-expanded + aria-haspopup='listbox'. aria-controls points at the inner CommandList only when open. Each option carries aria-selected; capped/disabled options carry aria-disabled. A visually-hidden aria-live='polite' region inside the trigger announces selection-count changes.",
+    tokenBudget: 1100
+  },
+  tags: ["combobox", "multi-select", "select", "search", "cmdk", "input"]
+};
+
+// src/components/stepper/stepper.schema.ts
+var stepperSchema = {
+  name: "stepper",
+  displayName: "Stepper",
+  description: "Linear progress indicator for multi-step flows (form wizards, onboarding, checkout). Pure semantic <ol>/<li> with aria-current='step' on the active step and a per-step error status override.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    {
+      name: "steps",
+      type: "object",
+      required: true,
+      description: "Ordered list of { id, label, description?, disabled?, status? }. `status` overrides the index-derived value."
+    },
+    {
+      name: "current",
+      type: "number",
+      required: true,
+      description: "Index of the current step (controlled)."
+    },
+    {
+      name: "orientation",
+      type: "string",
+      required: false,
+      default: "horizontal",
+      description: "Layout direction: 'horizontal' | 'vertical'"
+    },
+    {
+      name: "size",
+      type: "string",
+      required: false,
+      default: "md",
+      description: "Indicator size: 'sm' | 'md'"
+    },
+    {
+      name: "onStepClick",
+      type: "function",
+      required: false,
+      description: "When provided, each step renders as a clickable <button>; otherwise steps are non-interactive <span>s. Signature: (index: number) => void"
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: true,
+      description: "Required accessible name for the ordered list (e.g. 'Onboarding steps', 'Checkout progress')"
+    }
+  ],
+  variants: [
+    {
+      name: "orientation",
+      description: "Layout direction",
+      values: [
+        { value: "horizontal", description: "Steps laid out left-to-right" },
+        { value: "vertical", description: "Steps stacked top-to-bottom" }
+      ],
+      default: "horizontal"
+    },
+    {
+      name: "size",
+      description: "Indicator size",
+      values: [
+        { value: "sm", description: "Compact indicator (1.75rem)" },
+        {
+          value: "md",
+          description: "Default indicator (matches control-height-sm)"
+        }
+      ],
+      default: "md"
+    }
+  ],
+  slots: [],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [
+    "primary",
+    "primary-foreground",
+    "foreground",
+    "muted-foreground",
+    "input",
+    "destructive",
+    "destructive-foreground",
+    "ring"
+  ],
+  examples: [
+    {
+      title: "Form wizard",
+      description: "Three-step horizontal stepper with the second step active",
+      code: 'import { Stepper } from "@/components/ui/stepper";\n\nexport function Example() {\n  return (\n    <Stepper\n      aria-label="Onboarding"\n      current={1}\n      steps={[\n        { id: "account", label: "Account", description: "Email + password" },\n        { id: "profile", label: "Profile", description: "Name + photo" },\n        { id: "confirm", label: "Confirm" },\n      ]}\n    />\n  );\n}'
+    },
+    {
+      title: "With error state",
+      description: "Mark a failed step explicitly with status='error'",
+      code: 'import { Stepper } from "@/components/ui/stepper";\n\nexport function Example() {\n  return (\n    <Stepper\n      aria-label="Checkout"\n      current={2}\n      steps={[\n        { id: "cart", label: "Cart" },\n        { id: "shipping", label: "Shipping", status: "error" },\n        { id: "payment", label: "Payment" },\n      ]}\n    />\n  );\n}'
+    },
+    {
+      title: "Vertical, clickable",
+      description: "Vertical orientation with onStepClick to jump back",
+      code: 'import { Stepper } from "@/components/ui/stepper";\n\nexport function Example() {\n  return (\n    <Stepper\n      aria-label="Settings"\n      orientation="vertical"\n      current={1}\n      onStepClick={(i) => console.log(i)}\n      steps={[\n        { id: "profile", label: "Profile" },\n        { id: "security", label: "Security" },\n        { id: "billing", label: "Billing" },\n      ]}\n    />\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use to communicate progress through a multi-step flow with a known fixed sequence: form wizards, onboarding, checkout, ticket triage. Mark per-step error status when validation fails.",
+    whenNotToUse: "Don't use for free navigation across unrelated sections (use Tabs). Don't use for indeterminate progress (use Progress with no value). Don't use for >7 steps \u2014 collapse into a multi-screen wizard with a sub-stepper instead.",
+    commonMistakes: [
+      "Forgetting aria-label \u2014 the <ol> needs an accessible name to be understood as a step list",
+      "Setting current to an out-of-range index \u2014 derives all steps as 'upcoming'",
+      "Mixing index-derived status with manual status overrides without intent \u2014 once you set status on one step, set it on all of them or know the precedence rules",
+      "Making the stepper interactive (onStepClick) but allowing forward jumps before validation \u2014 gate jumps in your handler",
+      "Treating it as a tab control \u2014 Stepper communicates direction; users can't pick step 5 then go back to 2 to review without your wiring"
+    ],
+    relatedComponents: ["progress", "tabs", "breadcrumb"],
+    accessibilityNotes: "Renders <ol> with the provided aria-label. The active step's interactive element gets aria-current='step'. Completed steps prefix the label with visually-hidden 'Completed:'; error steps prefix with 'Error:' and set aria-invalid='true' on the indicator. Connector lines are aria-hidden. When onStepClick is omitted, steps are plain <span>s \u2014 not fake buttons.",
+    tokenBudget: 1400
+  },
+  tags: ["stepper", "wizard", "progress", "navigation", "form"]
+};
+
+// src/components/timeline/timeline.schema.ts
+var timelineSchema = {
+  name: "timeline",
+  displayName: "Timeline",
+  description: "Vertical chronological event feed for activity logs, audit trails, release notes, and notification streams. Pure semantic <ol>/<li> with a status-colored indicator and an optional icon override.",
+  category: "component",
+  subcategory: "data-display",
+  props: [
+    {
+      name: "events",
+      type: "object",
+      required: true,
+      description: "Ordered list of { id, title, timestamp?, description?, icon?, status? } events."
+    },
+    {
+      name: "size",
+      type: "string",
+      required: false,
+      default: "md",
+      description: "Indicator size: 'sm' | 'md'"
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: true,
+      description: "Required accessible name for the ordered list (e.g. 'Activity log', 'Release notes')"
+    }
+  ],
+  variants: [
+    {
+      name: "size",
+      description: "Indicator size",
+      values: [
+        { value: "sm", description: "Compact 1.25rem indicator" },
+        { value: "md", description: "Default 1.75rem indicator" }
+      ],
+      default: "md"
+    }
+  ],
+  slots: [],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [
+    "background",
+    "foreground",
+    "muted-foreground",
+    "input",
+    "primary",
+    "destructive",
+    "destructive-foreground",
+    "ring"
+  ],
+  examples: [
+    {
+      title: "Activity log",
+      description: "Three-entry vertical feed with mixed status colors",
+      code: 'import { Timeline } from "@/components/ui/timeline";\n\nexport function Example() {\n  return (\n    <Timeline\n      aria-label="Activity"\n      events={[\n        { id: "1", title: "Pull request opened", timestamp: "2 hours ago", status: "info" },\n        { id: "2", title: "CI passed", timestamp: "1 hour ago", status: "success" },\n        { id: "3", title: "Merged to main", timestamp: "12 minutes ago", description: "Squash + merge by @oscar", status: "success" },\n      ]}\n    />\n  );\n}'
+    },
+    {
+      title: "Custom icon",
+      description: "Override the default dot with a custom node",
+      code: 'import { Timeline } from "@/components/ui/timeline";\n\nexport function Example() {\n  return (\n    <Timeline\n      aria-label="Release notes"\n      events={[\n        { id: "v1", title: "v1.0", timestamp: "Apr 24", icon: <span>\u26A1</span> },\n        { id: "v2", title: "v1.1", timestamp: "Apr 27", icon: <span>\u{1F41B}</span>, status: "warning" },\n      ]}\n    />\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use to show a chronological event feed: activity logs, audit trails, release notes, notification history, ticket events. Each event has a title and optional timestamp + description.",
+    whenNotToUse: "Don't use for project schedules / Gantt charts (build a custom layout). Don't use for navigation between time periods (use Tabs or Stepper). Don't use for paginated data (use Table or DataTable). Don't use for >50 events without virtualization \u2014 Timeline renders every item.",
+    commonMistakes: [
+      "Forgetting aria-label \u2014 the <ol> needs an accessible name to be understood as a feed",
+      "Using duplicate event ids \u2014 breaks React keys and event reconciliation on re-render",
+      "Stuffing the description with rich layouts that overflow the timeline rail \u2014 keep it short or move to a Card",
+      "Setting status='error' on every event for emphasis \u2014 color loses meaning when overused",
+      "Mixing controlled timestamps as Date objects without formatting \u2014 Timeline accepts ReactNode, so format upstream (date-fns) before passing in"
+    ],
+    relatedComponents: ["card", "stepper", "separator"],
+    accessibilityNotes: "Renders <ol> with the provided aria-label. The status-colored indicator and connector line are aria-hidden \u2014 meaning is carried entirely by the title/timestamp/description text. No aria-current; events are historical, not navigational. For >50 events consider a windowing solution outside Timeline.",
+    tokenBudget: 1100
+  },
+  tags: ["timeline", "feed", "activity", "audit-log", "history"]
+};
+
+// src/components/dropzone/dropzone.schema.ts
+var dropzoneSchema = {
+  name: "dropzone",
+  displayName: "Dropzone",
+  description: "Drag-and-drop file input built on the native HTML5 drag-drop API plus a visually-hidden <input type='file'> for keyboard + screen-reader access. Filters by accept/maxSize/maxFiles before emitting.",
+  category: "component",
+  subcategory: "input",
+  props: [
+    {
+      name: "onFilesSelected",
+      type: "function",
+      required: false,
+      description: "Callback fired with the accepted File[] on pick or drop."
+    },
+    {
+      name: "onFilesRejected",
+      type: "function",
+      required: false,
+      description: "Callback fired with the rejected File[] when files fail accept/maxSize/maxFiles, OR when multiple={false} and extras were sliced off. Receives the rejected File[]. Use to surface 'wrong type' / 'too large' toasts."
+    },
+    {
+      name: "accept",
+      type: "string",
+      required: false,
+      description: "Accept attribute forwarded to the hidden file input. Three forms: MIME type ('application/pdf'), MIME wildcard ('image/*'), or extension with leading dot ('.csv'). Extension matching is suffix-based (mirrors HTML5) \u2014 '.csv' will match 'notes.md.csv' as well."
+    },
+    {
+      name: "multiple",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Allow multiple files. With `multiple={false}`, the first accepted file flows to onFilesSelected and any extras flow to onFilesRejected so consumers can toast them."
+    },
+    {
+      name: "maxFiles",
+      type: "number",
+      required: false,
+      description: "Cap on the number of accepted files. Excess files are dropped silently \u2014 surface in your handler if needed."
+    },
+    {
+      name: "maxSize",
+      type: "number",
+      required: false,
+      description: "Maximum size per file in bytes. Files over the cap are filtered before onFilesSelected fires."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable interaction (click + drop + keyboard)."
+    },
+    {
+      name: "children",
+      type: "object",
+      required: false,
+      description: "Render override for the body. Pass a node, or a function receiving { isDragOver, isDisabled, openFileDialog } for layout control."
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: true,
+      description: "Required accessible name for the drop area."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Body of the drop area (icon + copy). Optional \u2014 sensible default included.",
+      required: false,
+      acceptedTypes: ["ReactNode", "function"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [
+    "background",
+    "input",
+    "primary",
+    "accent",
+    "accent-foreground",
+    "muted-foreground",
+    "ring"
+  ],
+  examples: [
+    {
+      title: "Image upload",
+      description: "Filter to images only with a 5MB cap",
+      code: 'import { useState } from "react";\nimport { Dropzone } from "@/components/ui/dropzone";\n\nexport function Example() {\n  const [files, setFiles] = useState<File[]>([]);\n  return (\n    <>\n      <Dropzone\n        accept="image/*"\n        maxSize={5 * 1024 * 1024}\n        onFilesSelected={(picked) => setFiles((f) => [...f, ...picked])}\n        aria-label="Upload images"\n      />\n      <ul>{files.map((f) => <li key={f.name}>{f.name}</li>)}</ul>\n    </>\n  );\n}'
+    },
+    {
+      title: "Custom body via render prop",
+      description: "Take full control of the drop area visuals",
+      code: 'import { Dropzone } from "@/components/ui/dropzone";\n\nexport function Example() {\n  return (\n    <Dropzone aria-label="Upload" onFilesSelected={(f) => console.log(f)}>\n      {({ isDragOver }) => (\n        <span>{isDragOver ? "Release to upload" : "Drop a file or click"}</span>\n      )}\n    </Dropzone>\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for any file upload UX where drag-drop is helpful (image uploaders, CSV import, attachment pickers). Built on native HTML5 + a hidden <input type='file'> so keyboard and screen-reader users get the same affordance.",
+    whenNotToUse: "Don't use for camera/microphone capture (use <input type='file' capture> directly or a media-specific component). Don't use for chunked/resumable uploads \u2014 Dropzone only emits File[]; pair with a real upload pipeline (tus, S3 multipart). Don't use for clipboard paste image upload \u2014 listen on document for that.",
+    commonMistakes: [
+      "Forgetting aria-label \u2014 without it the drop area is announced as just 'button' to screen readers",
+      "Setting accept='image' (missing the slash or wildcard) \u2014 must be a MIME type, MIME prefix with /*, or a .extension",
+      "Forgetting that extension matching is suffix-based \u2014 '.csv' will match 'notes.md.csv'. Acceptable (mirrors HTML5) but document upstream if business logic requires strict suffix-only",
+      "Treating maxFiles as enforcement \u2014 files past the cap are dropped silently; if business rules require it, validate again on submit",
+      "Forgetting to clear the file input value after a successful upload \u2014 Dropzone resets the hidden input automatically; if you wrap it, do the same",
+      "Calling preventDefault on parent containers' onDragOver \u2014 without it the browser opens the file when dropped on the window outside the dropzone",
+      "Treating empty drops as no-op silently when the user expected feedback \u2014 pair with onFilesRejected to surface filter failures"
+    ],
+    relatedComponents: ["input", "button", "card"],
+    accessibilityNotes: "The drop area is a role='button' div with tabIndex=0 and the required aria-label; Enter and Space open the file dialog. The file input is visually-hidden but live in the DOM so keyboard focus + assistive-tech file pickers work. Drag-state is exposed via data-drag-over for CSS-only state styling. When disabled, the drop area is removed from the tab order and aria-disabled is set.",
+    tokenBudget: 1500
+  },
+  tags: ["dropzone", "file-upload", "drag-drop", "input"]
+};
+
+// src/components/time-picker/time-picker.schema.ts
+var timePickerSchema = {
+  name: "time-picker",
+  displayName: "Time Picker",
+  description: "Time input \u2014 styled wrapper around the native <input type='time'>. Value is a 'HH:MM' (or 'HH:MM:SS' with step=1) string. The browser provides 12/24-hour locale handling, keyboard arrow spinning, and screen-reader announcement.",
+  category: "component",
+  subcategory: "input",
+  props: [
+    {
+      name: "value",
+      type: "string",
+      required: false,
+      description: "Controlled time value as 'HH:MM' or 'HH:MM:SS' (24-hour)."
+    },
+    {
+      name: "onChange",
+      type: "function",
+      required: false,
+      description: "Callback when the user picks a time: (value: string) => void. Value is always 24-hour 'HH:MM' (or 'HH:MM:SS' when step=1)."
+    },
+    {
+      name: "step",
+      type: "number",
+      required: false,
+      description: "Step in seconds. Use 60 (default) for HH:MM, 1 for HH:MM:SS, 300 for 5-minute steps, 900 for 15-minute. Note: Chrome/Edge picker dropdown UI does NOT visually snap minutes to the step \u2014 it only affects keyboard arrow stepping and form validation. Off-step values are still rejected."
+    },
+    {
+      name: "min",
+      type: "string",
+      required: false,
+      description: "Earliest selectable time as 'HH:MM'."
+    },
+    {
+      name: "max",
+      type: "string",
+      required: false,
+      description: "Latest selectable time as 'HH:MM'."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the input."
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: false,
+      description: "Accessible label \u2014 required when no adjacent visible <label> is used."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "input", "ring"],
+  examples: [
+    {
+      title: "Basic time picker",
+      description: "Bind a string state and render the picker",
+      code: 'import { useState } from "react";\nimport { TimePicker } from "@/components/ui/time-picker";\n\nexport function Example() {\n  const [time, setTime] = useState<string>();\n  return <TimePicker value={time} onChange={setTime} aria-label="Meeting time" />;\n}'
+    },
+    {
+      title: "With seconds + 5-minute step",
+      description: "step={1} adds a seconds segment; step={300} steps minutes by 5 in browsers that support it",
+      code: 'import { useState } from "react";\nimport { TimePicker } from "@/components/ui/time-picker";\n\nexport function Example() {\n  const [time, setTime] = useState<string>("09:00");\n  return <TimePicker value={time} onChange={setTime} step={300} min="09:00" max="17:00" aria-label="Working hours start" />;\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for selecting a time of day in a form (meeting time, reminder, business hours start/end). Browser handles 12/24-hour locale automatically based on user system settings; the wire format is always 24-hour 'HH:MM'. Component is controlled-only \u2014 pair `value` with `onChange`; for uncontrolled use, the input behaves as a controlled empty input with no upstream state.",
+    whenNotToUse: "Don't use for durations (hours/minutes elapsed) \u2014 use composite Input fields. Don't use for date+time together \u2014 combine with DatePicker. Don't use when explicit AM/PM segments matter for layout \u2014 compose Input + Select yourself; the native input renders AM/PM only in 12-hour locales. Don't use when you need pixel-identical chrome across browsers \u2014 the dropdown indicator is webkit-styled (Chrome/Edge/Safari) and absent in Firefox.",
+    commonMistakes: [
+      "Passing a Date object to value \u2014 must be a string in 'HH:MM' format",
+      "Treating onChange as 12-hour \u2014 the value is always 24-hour, the browser only displays it in user locale",
+      "Missing aria-label when there's no adjacent visible <label> \u2014 input gets no accessible name",
+      "Setting step to a value that doesn't divide evenly into 3600 (e.g. step=7) \u2014 confusing UX in browsers that snap to it",
+      "Expecting Chrome/Edge's picker dropdown to visually skip minutes per step \u2014 it doesn't. The minute scroll wheel always shows every minute; step only constrains keyboard arrow stepping and form validation",
+      "Setting min/max with seconds when step!=1 \u2014 the seconds segment is hidden, so users can't actually reach values that need it",
+      "Expecting the dropdown picker indicator to render in Firefox \u2014 only webkit browsers paint it; Firefox renders the input without that affordance",
+      "Expecting an uncontrolled mode \u2014 TimePicker is controlled-only. Pass both value + onChange, or omit both and accept that user input has no place to live"
+    ],
+    relatedComponents: ["date-picker", "input", "select"],
+    accessibilityNotes: "Native <input type='time'> \u2014 assistive tech announces hour/minute (and seconds if shown) segments individually. Arrow keys spin each segment. Disabled state is announced. Pass aria-label or wrap with a <label htmlFor>. Visual chrome (icon, dropdown affordance) is browser-controlled and varies across Chrome/Edge/Safari (rendered) and Firefox (absent).",
+    tokenBudget: 700
+  },
+  tags: ["time-picker", "time", "input", "form"]
+};
+
+// src/components/file-tree/file-tree.schema.ts
+var fileTreeSchema = {
+  name: "file-tree",
+  displayName: "File Tree",
+  description: "Hierarchical tree view for files, folders, and any nested navigation. Implements the WAI-ARIA tree pattern with role='tree' / 'treeitem' / 'group', aria-level, aria-expanded, aria-selected, and full keyboard navigation (Up/Down/Left/Right/Home/End/Enter/Space).",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    {
+      name: "nodes",
+      type: "object",
+      required: true,
+      description: "Tree of { id, name, children?, icon?, disabled? }. Presence of `children` (even an empty array) marks the node as a folder."
+    },
+    {
+      name: "defaultExpanded",
+      type: "object",
+      required: false,
+      description: "Uncontrolled \u2014 initial expanded ids (string[])."
+    },
+    {
+      name: "expanded",
+      type: "object",
+      required: false,
+      description: "Controlled expanded ids (string[]). Pair with onExpandedChange."
+    },
+    {
+      name: "onExpandedChange",
+      type: "function",
+      required: false,
+      description: "Fired with the new expanded ids: (ids: string[]) => void"
+    },
+    {
+      name: "selected",
+      type: "string",
+      required: false,
+      description: "Controlled selected node id."
+    },
+    {
+      name: "onSelect",
+      type: "function",
+      required: false,
+      description: "Fired when the user activates a node via click, Enter, or Space: (id: string) => void"
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: true,
+      description: "Required accessible name for the tree (e.g. 'File explorer', 'Settings sections')."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [
+    "accent",
+    "accent-foreground",
+    "muted-foreground",
+    "ring"
+  ],
+  examples: [
+    {
+      title: "Basic file tree",
+      description: "Uncontrolled expanded set; selected state controlled",
+      code: 'import { useState } from "react";\nimport { FileTree } from "@/components/ui/file-tree";\n\nconst nodes = [\n  {\n    id: "src",\n    name: "src",\n    children: [\n      { id: "src/index.tsx", name: "index.tsx" },\n      {\n        id: "src/components",\n        name: "components",\n        children: [\n          { id: "src/components/Button.tsx", name: "Button.tsx" },\n          { id: "src/components/Input.tsx", name: "Input.tsx" },\n        ],\n      },\n    ],\n  },\n  { id: "package.json", name: "package.json" },\n];\n\nexport function Example() {\n  const [selected, setSelected] = useState<string>();\n  return (\n    <FileTree\n      aria-label="Project files"\n      nodes={nodes}\n      defaultExpanded={["src"]}\n      selected={selected}\n      onSelect={setSelected}\n    />\n  );\n}'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for hierarchical navigation: file/folder explorers, settings sections, org charts, taxonomy browsers. Renders a real ARIA tree with full keyboard support, so it works for sighted, keyboard, and screen-reader users.",
+    whenNotToUse: "Don't use for flat lists (use ScrollArea + a list). Don't use for navigation menus (use NavigationMenu). Don't use for very deep trees (>5 levels) without virtualization \u2014 every node is rendered. Don't use for selecting multiple files concurrently \u2014 multi-select tree UX is a different beast; ship a separate component when you need it.",
+    commonMistakes: [
+      "Mixing controlled `expanded` with `defaultExpanded` \u2014 pass exactly one",
+      "Using non-stable node ids (e.g. array index) \u2014 collapsing/expanding shifts state",
+      "Marking a leaf with `children: []` instead of omitting `children` \u2014 empty array still flags it as a folder, so the chevron shows",
+      "Forgetting aria-label \u2014 the tree gets no accessible name and screen readers announce just 'tree'",
+      "Calling onSelect to navigate without de-bouncing arrow-key focus changes \u2014 focus moves on arrows but does NOT call onSelect; only Enter/Space/click selects, so navigation should hang off onSelect, not focused state",
+      "Expecting row-click to toggle expand \u2014 per WAI-ARIA tree pattern the row click only selects; toggling is the chevron button (or ArrowRight/Left, or Enter/Space when the row is focused). Common surprise after coming from VS Code-style trees",
+      "Passing `selected` pointing at a node inside a collapsed branch \u2014 the tree falls back to the first visible node for tab focus, so the consumer can't rely on tabIndex to land on the selected target until it's revealed via expanded"
+    ],
+    relatedComponents: ["accordion", "navigation-menu", "sidebar"],
+    accessibilityNotes: "Root: role='tree' with aria-label. Each node: role='treeitem' with aria-level, aria-expanded (folders only), aria-selected, tabIndex=0 only on the active visible node (roving tabindex). Children container: role='group'. Click semantics: row click selects only; the chevron is a separate decorative button that toggles. Keyboard: ArrowDown/Up move through visible non-disabled nodes (disabled nodes are skipped); ArrowRight expands a closed folder or moves to first child; ArrowLeft collapses an open folder or moves to parent; Home/End jump to first/last visible; Enter/Space activate (toggle on folders, select on all).",
+    tokenBudget: 2e3
+  },
+  tags: ["file-tree", "tree", "navigation", "explorer", "hierarchy"]
+};
+
+// src/components/color-picker/color-picker.schema.ts
+var colorPickerSchema = {
+  name: "color-picker",
+  displayName: "Color Picker",
+  description: "HSL-native color picker that edits an HSL triplet directly via three sliders (H/S/L). Hex input is a display adapter; sliders are the source of truth so the value round-trips losslessly through the `@hex-core/tokens` triplet format.",
+  category: "component",
+  subcategory: "input",
+  props: [
+    {
+      name: "value",
+      type: "string",
+      required: true,
+      description: 'Current color as an HSL triplet string (`"<H> <S>% <L>%"`, e.g. `"240 5.9% 10%"`). Match the format used by `@hex-core/tokens`.'
+    },
+    {
+      name: "onChange",
+      type: "function",
+      required: true,
+      description: "Called with the next HSL triplet when the user drags a slider or commits a valid hex value. Not called for invalid hex input."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable interaction. Trigger renders dimmed; mouse and keyboard activation are blocked by the native `disabled` attribute."
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: false,
+      default: '"Pick color"',
+      description: "Accessible name for the trigger button."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional class names merged onto the trigger."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-popover", "@radix-ui/react-slider", "@radix-ui/react-label"],
+    internal: [
+      "primitives/slider/slider",
+      "primitives/input/input",
+      "primitives/label/label",
+      "components/popover/popover",
+      "lib/color",
+      "lib/utils"
+    ],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["input", "background", "ring", "border", "muted-foreground"],
+  examples: [
+    {
+      title: "Edit a token live",
+      description: "Bind a state variable to a CSS custom property to preview a token edit in real time.",
+      code: 'const [color, setColor] = React.useState("240 5.9% 10%");\n\nreturn (\n  <div style={{ "--primary": color } as React.CSSProperties}>\n    <ColorPicker value={color} onChange={setColor} aria-label="Primary color" />\n    <Button>Live preview</Button>\n  </div>\n);'
+    },
+    {
+      title: "Disabled",
+      description: "Prevent edits while a parent operation is in flight.",
+      code: '<ColorPicker value="240 5.9% 10%" onChange={() => {}} disabled />'
+    }
+  ],
+  ai: {
+    whenToUse: "Use whenever the user is editing a color that will round-trip through the `@hex-core/tokens` HSL triplet format \u2014 token editors, theme builders, branding panels, custom-color surfaces in design tools.",
+    whenNotToUse: "Don't use for picking a color from a fixed palette \u2014 use a `Select` or `RadioGroup` of swatches. Don't use for image-based color sampling (eyedropper) \u2014 that's a separate primitive. Don't reach for ColorPicker when only a hex string matters: bind it directly to `<input type=\"color\">` for the simplest cases.",
+    commonMistakes: [
+      "Treating the value as hex \u2014 the prop is an HSL triplet, not a hex string. Use `hexToHslTriplet` and `hslTripletToHex` from `@hex-core/components/lib/color` if you need to bridge.",
+      "Forgetting to wrap the value in `hsl(...)` when applying it as a CSS color: `style={{ color: \\`hsl(${value})\\` }}`.",
+      "Calling `onChange` synchronously inside a parent's render \u2014 the picker batches slider updates and that pattern can desync controlled state."
+    ],
+    relatedComponents: ["slider", "input", "label", "popover"],
+    accessibilityNotes: 'Each slider has a per-axis `aria-label` (Hue / Saturation / Lightness). The trigger button needs an explicit `aria-label` describing what color is being edited (e.g. `"Primary color"`) \u2014 the default `"Pick color"` is generic. The hex input is keyboard-accessible and round-trips with the sliders.',
+    tokenBudget: 350
+  },
+  tags: ["color-picker", "color", "hsl", "hex", "form", "theme-editor", "primitive"]
+};
+
+// src/components/sheet/sheet.schema.ts
+var sheetSchema = {
+  name: "sheet",
+  displayName: "Sheet",
+  description: "Side drawer built on Radix Dialog with a directional slide animation. Use for navigation, filters, quick edit, or any off-canvas panel.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    { name: "open", type: "boolean", required: false, description: "Controlled open state" },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Default open state for uncontrolled usage"
+    },
+    {
+      name: "onOpenChange",
+      type: "function",
+      required: false,
+      description: "Callback when open state changes: (open: boolean) => void"
+    },
+    {
+      name: "modal",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "When true, content outside the sheet is inert"
+    }
+  ],
+  variants: [
+    {
+      name: "side",
+      description: "Which edge the sheet slides in from",
+      values: [
+        { value: "top", description: "Slides down from the top edge" },
+        { value: "bottom", description: "Slides up from the bottom edge" },
+        { value: "left", description: "Slides in from the left edge" },
+        { value: "right", description: "Slides in from the right edge (default)" }
+      ],
+      default: "right"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "SheetTrigger + SheetContent (with SheetHeader/Footer/Title/Description)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-dialog", "class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "foreground", "muted-foreground", "border", "ring"],
+  examples: [
+    {
+      title: "Right-side sheet",
+      description: "Quick edit panel anchored to the right edge",
+      code: '<Sheet>\n  <SheetTrigger asChild>\n    <Button variant="outline">Open</Button>\n  </SheetTrigger>\n  <SheetContent>\n    <SheetHeader>\n      <SheetTitle>Edit profile</SheetTitle>\n      <SheetDescription>Make changes and save when done.</SheetDescription>\n    </SheetHeader>\n    <div className="grid gap-4 py-4">\n      <Input placeholder="Name" />\n    </div>\n    <SheetFooter>\n      <Button>Save</Button>\n    </SheetFooter>\n  </SheetContent>\n</Sheet>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for off-canvas panels \u2014 mobile nav menus, filter panels, side forms, detail views, or multi-step flows. Slides in from an edge, dismisses on outside click, Escape, or close button.",
+    whenNotToUse: "Don't use for center-focused modals (use Dialog). Don't use for transient bottom sheets on mobile (use Drawer). Don't use for dropdown menus or quick popover actions (use DropdownMenu or Popover).",
+    commonMistakes: [
+      "Forgetting SheetTitle \u2014 Radix warns at runtime and screen readers announce an unnamed dialog",
+      "Putting a full page's content inside a sheet \u2014 too much friction; use a route instead",
+      "Overriding the side slide animation without matching the 'side' variant",
+      "Not handling controlled open state after SheetClose \u2014 use onOpenChange not manual state"
+    ],
+    relatedComponents: ["dialog", "drawer", "popover"],
+    accessibilityNotes: "Radix traps focus, handles Escape to close, and wires aria-labelledby/describedby to SheetTitle/Description. The Close button has sr-only text. Always include a SheetTitle.",
+    tokenBudget: 700
+  },
+  tags: ["sheet", "drawer", "side-panel", "off-canvas", "overlay"]
+};
+
+// src/components/drawer/drawer.schema.ts
+var drawerSchema = {
+  name: "drawer",
+  displayName: "Drawer",
+  description: "Bottom-sheet drawer built on vaul. Mobile-native feel: drag-to-dismiss, snap points, body-scale-on-open. Use for quick mobile actions, filters, pickers.",
+  category: "component",
+  subcategory: "overlay",
+  props: [
+    { name: "open", type: "boolean", required: false, description: "Controlled open state" },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Default open state"
+    },
+    {
+      name: "onOpenChange",
+      type: "function",
+      required: false,
+      description: "Callback when open state changes: (open: boolean) => void"
+    },
+    {
+      name: "shouldScaleBackground",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Scale the <body> element when the drawer opens (creates depth)"
+    },
+    {
+      name: "snapPoints",
+      type: "object",
+      required: false,
+      description: "Array of snap positions ('40%', 400, '100%') \u2014 defines resting heights the user can snap to"
+    },
+    {
+      name: "activeSnapPoint",
+      type: "object",
+      required: false,
+      description: "Controlled active snap point value (matches one entry in snapPoints)"
+    },
+    {
+      name: "closeThreshold",
+      type: "number",
+      required: false,
+      default: 0.25,
+      description: "Fraction of height the user must drag down to close (0..1)"
+    },
+    {
+      name: "dismissible",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Allow drag-to-dismiss and outside-click-to-dismiss"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "DrawerTrigger + DrawerContent (with DrawerHeader/Footer/Title/Description)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["vaul", "@radix-ui/react-dialog", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "foreground", "muted", "muted-foreground", "border"],
+  examples: [
+    {
+      title: "Basic drawer",
+      description: "Mobile-friendly bottom sheet with a quick action",
+      code: '<Drawer>\n  <DrawerTrigger asChild>\n    <Button variant="outline">Open drawer</Button>\n  </DrawerTrigger>\n  <DrawerContent>\n    <DrawerHeader>\n      <DrawerTitle>Edit profile</DrawerTitle>\n      <DrawerDescription>Make changes to your profile.</DrawerDescription>\n    </DrawerHeader>\n    <div className="p-4"><Input placeholder="Name" /></div>\n    <DrawerFooter>\n      <Button>Save</Button>\n      <DrawerClose asChild>\n        <Button variant="outline">Cancel</Button>\n      </DrawerClose>\n    </DrawerFooter>\n  </DrawerContent>\n</Drawer>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use on mobile-first or mobile-primary UX when a native app-like bottom sheet matters. Good for filters, quick pickers, confirm-then-do flows, or anywhere a user expects drag-to-dismiss.",
+    whenNotToUse: "Don't use on desktop-primary UIs (use Dialog or Sheet). Don't use for side navigation (use Sheet). Don't use for transient info (use Popover or Tooltip). Don't use when you must prevent dismissal \u2014 drawers invite drag-down.",
+    commonMistakes: [
+      "Forgetting DrawerTitle \u2014 vaul/Radix warn and screen readers announce an unnamed dialog",
+      "Placing long forms inside a drawer without snap points \u2014 content gets cramped",
+      "Disabling shouldScaleBackground when the background context-cue matters for UX",
+      "Wrapping DrawerContent in Portal yourself \u2014 DrawerContent already portals via DrawerPortal"
+    ],
+    relatedComponents: ["sheet", "dialog"],
+    accessibilityNotes: "vaul delegates to Radix Dialog: focus trap, Escape to close, aria-labelledby/describedby wired to DrawerTitle/Description. The top handle is decorative (aria-hidden).",
+    tokenBudget: 700
+  },
+  tags: ["drawer", "bottom-sheet", "vaul", "mobile", "overlay"]
+};
+
+// src/components/resizable/resizable.schema.ts
+var resizableSchema = {
+  name: "resizable",
+  displayName: "Resizable",
+  description: "Draggable split panes built on react-resizable-panels v4. Horizontal or vertical, with keyboard-accessible handles and persistable layout.",
+  category: "component",
+  subcategory: "layout",
+  props: [
+    {
+      name: "orientation",
+      type: "string",
+      required: false,
+      default: "horizontal",
+      description: "Group orientation: 'horizontal' | 'vertical'"
+    },
+    {
+      name: "defaultLayout",
+      type: "object",
+      required: false,
+      description: "Array of initial panel sizes in order (percentages summing to 100)"
+    },
+    {
+      name: "onLayoutChange",
+      type: "function",
+      required: false,
+      description: "Fires when the user drags a handle; receives the new layout array"
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable resizing for the whole group"
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Alternating ResizablePanel + ResizableHandle nodes",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["react-resizable-panels", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["border", "ring"],
+  examples: [
+    {
+      title: "Horizontal split pane",
+      description: "Two resizable panels with a grab-grip handle",
+      code: '<ResizablePanelGroup orientation="horizontal" className="min-h-[300px] max-w-md rounded-lg border">\n  <ResizablePanel defaultSize={50}>\n    <div className="flex h-full items-center justify-center p-6">One</div>\n  </ResizablePanel>\n  <ResizableHandle withHandle />\n  <ResizablePanel defaultSize={50}>\n    <div className="flex h-full items-center justify-center p-6">Two</div>\n  </ResizablePanel>\n</ResizablePanelGroup>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for editor-style layouts (file tree + editor), dashboards with configurable panels, or any UI where users need to trade space between regions. Layouts can be persisted to localStorage via the group's id.",
+    whenNotToUse: "Don't use for responsive layouts \u2014 use CSS grid/flex with breakpoints. Don't use for modal layouts (use Dialog/Sheet). Don't nest deeply (>2 levels) \u2014 it hurts a11y and perception. Don't use if panels need to collapse/expand as a single action (use Collapsible).",
+    commonMistakes: [
+      "Forgetting ResizableHandle between panels \u2014 they won't resize",
+      "Using 'cols'/'rows' instead of orientation='horizontal'/'vertical' (old v1 API)",
+      "Not providing defaultSize on each panel \u2014 initial layout will be uneven",
+      "Rendering panel content that changes DOM size during drag \u2014 react-resizable-panels performance suffers",
+      "Omitting a group id when you want layout to persist via localStorage"
+    ],
+    relatedComponents: ["separator", "collapsible"],
+    accessibilityNotes: "ResizableHandle is focusable and resizable via keyboard arrows. role='separator' is set, with aria-valuenow/min/max wired by react-resizable-panels. The grab-grip is aria-hidden (decorative).",
+    tokenBudget: 700
+  },
+  tags: ["resizable", "split-pane", "layout", "panels"]
+};
+
+// src/components/sidebar/sidebar.schema.ts
+var sidebarSchema = {
+  name: "sidebar",
+  displayName: "Sidebar",
+  description: "App-shell sidebar with collapsible width, context-driven open state, and composable Header/Content/Footer/Item parts. Provider-based so any descendant can toggle it.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    {
+      name: "open",
+      type: "boolean",
+      required: false,
+      description: "Controlled open state \u2014 read from SidebarProvider"
+    },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Initial open state (uncontrolled)"
+    },
+    {
+      name: "onOpenChange",
+      type: "function",
+      required: false,
+      description: "Callback when open state flips: (open: boolean) => void"
+    },
+    {
+      name: "side",
+      type: "string",
+      required: false,
+      default: "left",
+      description: "Which edge the sidebar sits on: 'left' | 'right'"
+    }
+  ],
+  variants: [
+    {
+      name: "side",
+      description: "Which edge the sidebar docks against",
+      values: [
+        { value: "left", description: "Docks to the left edge (default)" },
+        { value: "right", description: "Docks to the right edge" }
+      ],
+      default: "left"
+    },
+    {
+      name: "state",
+      description: "Width state (derived from SidebarProvider open value)",
+      values: [
+        { value: "open", description: "Sidebar expanded at full width" },
+        { value: "closed", description: "Sidebar collapsed to zero width" }
+      ],
+      default: "open"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "SidebarHeader + SidebarContent + SidebarFooter (any combination)",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-slot", "class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "foreground", "border", "accent", "accent-foreground", "muted-foreground", "ring"],
+  examples: [
+    {
+      title: "App shell with collapsible sidebar",
+      description: "Provider holds open state; the trigger toggles it",
+      code: '<SidebarProvider>\n  <Sidebar>\n    <SidebarHeader>\n      <span className="font-semibold">Acme</span>\n    </SidebarHeader>\n    <SidebarContent>\n      <SidebarItem active>Dashboard</SidebarItem>\n      <SidebarItem>Projects</SidebarItem>\n      <SidebarItem>Settings</SidebarItem>\n    </SidebarContent>\n    <SidebarFooter>Signed in as jane</SidebarFooter>\n  </Sidebar>\n  <main className="flex-1 p-4">\n    <SidebarTrigger />\n    <h1>Hello</h1>\n  </main>\n</SidebarProvider>'
+    }
+  ],
+  ai: {
+    whenToUse: "Use for persistent app-shell navigation: admin dashboards, document editors, SaaS sidebars. The Provider pattern lets any descendant component toggle the sidebar (e.g. a topbar button on mobile).",
+    whenNotToUse: "Don't use for mobile-first UX (use Sheet \u2014 sidebar collapses to zero-width but Sheet gives a native drawer feel). Don't use for marketing sites (no shell). Don't use for contextual menus (use DropdownMenu or NavigationMenu).",
+    commonMistakes: [
+      "Rendering Sidebar outside SidebarProvider \u2014 useSidebar throws",
+      "Forgetting that SidebarProvider is a flex container \u2014 main content must be its direct sibling",
+      "Using the wrong ordering for side='right' \u2014 SidebarProvider handles this via order-last",
+      "Overriding the width variant manually instead of toggling open state"
+    ],
+    relatedComponents: ["sheet", "navigation-menu", "separator"],
+    accessibilityNotes: "Sidebar is an <aside> landmark (not a modal \u2014 no focus trap). When collapsed, the aside sets inert + aria-hidden so its children are removed from the tab order and the accessibility tree. SidebarTrigger exposes aria-expanded and a rotating aria-label (suppressed when asChild so the consumer's visible label/aria-label wins). SidebarItem uses aria-current='page' when active. Focus rings use the ring token.",
+    tokenBudget: 900
+  },
+  tags: ["sidebar", "navigation", "app-shell", "layout"]
+};
+
+export { accordionSchema, alertDialogSchema, alertSchema, aspectRatioSchema, avatarSchema, badgeSchema, breadcrumbSchema, buttonSchema, calendarSchema, cardSchema, checkboxSchema, clusterSchema, collapsibleSchema, colorPickerSchema, comboboxSchema, commandSchema, containerSchema, contextMenuSchema, dataTableSchema, datePickerSchema, dialogSchema, drawerSchema, dropdownMenuSchema, dropzoneSchema, fileTreeSchema, formSchema, gridSchema, hoverCardSchema, inputOTPSchema, inputSchema, labelSchema, menubarSchema, multiComboboxSchema, navigationMenuSchema, paginationSchema, popoverSchema, progressSchema, radioGroupSchema, resizableSchema, scrollAreaSchema, selectSchema, separatorSchema, sheetSchema, sidebarSchema, skeletonSchema, sliderSchema, sonnerSchema, spacerSchema, stackSchema, stepperSchema, switchSchema, tableSchema, tabsSchema, textareaSchema, timePickerSchema, timelineSchema, toggleGroupSchema, toggleSchema, tooltipSchema };
+//# sourceMappingURL=schemas.js.map
+//# sourceMappingURL=schemas.js.map