@thesage/mcp 0.2.1 → 0.5.0

package/dist/index.mjs

@@ -13,37 +13,57 @@ var COMPONENT_CATEGORIES = {
   actions: {
     label: "Actions",
     description: "Interactive elements that trigger behaviors",
-    count: 3
+    count: 5
   },
   forms: {
     label: "Forms",
     description: "Input controls for data collection",
-    count: 11
+    count: 18
   },
   navigation: {
     label: "Navigation",
     description: "Moving through content and hierarchy",
-    count: 6
+    count: 10
   },
   overlays: {
     label: "Overlays",
     description: "Contextual content that appears above the main UI",
-    count: 9
+    count: 11
   },
   feedback: {
     label: "Feedback",
     description: "Communicating system state and user action results",
-    count: 5
+    count: 7
   },
   "data-display": {
     label: "Data Display",
     description: "Presenting information in structured formats",
-    count: 6
+    count: 16
   },
   layout: {
     label: "Layout",
     description: "Spatial organization and structural elements",
-    count: 8
+    count: 17
+  },
+  backgrounds: {
+    label: "Backgrounds",
+    description: "Animated background effects and decorative elements",
+    count: 3
+  },
+  cursor: {
+    label: "Cursor",
+    description: "Custom cursor effects and interactions",
+    count: 2
+  },
+  motion: {
+    label: "Motion",
+    description: "Animation components and motion effects",
+    count: 1
+  },
+  blocks: {
+    label: "Blocks",
+    description: "Composed page sections and layouts",
+    count: 2
   }
 };
 var COMPONENT_REGISTRY = {
@@ -62,7 +82,14 @@ var COMPONENT_REGISTRY = {
       "Call-to-action elements"
     ],
     dependencies: ["@radix-ui/react-slot"],
-    radixPrimitive: "@radix-ui/react-slot"
+    radixPrimitive: "@radix-ui/react-slot",
+    props: {
+      variant: { type: "'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'", default: "'default'", description: "Visual style variant" },
+      size: { type: "'sm' | 'default' | 'lg' | 'icon'", default: "'default'", description: "Size variant" },
+      disabled: { type: "boolean", default: "false", description: "Disable interaction" },
+      asChild: { type: "boolean", default: "false", description: "Render as child element via Radix Slot" }
+    },
+    example: `<Button variant="outline" size="sm" onClick={handleClick}>Click Me</Button>`
   },
   toggle: {
     name: "Toggle",
@@ -76,7 +103,15 @@ var COMPONENT_REGISTRY = {
       "Filter activation"
     ],
     dependencies: ["@radix-ui/react-toggle"],
-    radixPrimitive: "@radix-ui/react-toggle"
+    radixPrimitive: "@radix-ui/react-toggle",
+    props: {
+      pressed: { type: "boolean", description: "Controlled pressed state" },
+      onPressedChange: { type: "(pressed: boolean) => void", description: "Callback on press change" },
+      variant: { type: "'default' | 'outline'", default: "'default'", description: "Visual variant" },
+      size: { type: "'sm' | 'default' | 'lg'", default: "'default'", description: "Size variant" },
+      disabled: { type: "boolean", default: "false", description: "Disable interaction" }
+    },
+    example: `<Toggle pressed={isBold} onPressedChange={setIsBold}><Bold className="h-4 w-4" /></Toggle>`
   },
   "toggle-group": {
     name: "ToggleGroup",
@@ -90,7 +125,19 @@ var COMPONENT_REGISTRY = {
       "Option selection"
     ],
     dependencies: ["@radix-ui/react-toggle-group"],
-    radixPrimitive: "@radix-ui/react-toggle-group"
+    radixPrimitive: "@radix-ui/react-toggle-group",
+    props: {
+      type: { type: "'single' | 'multiple'", description: "Selection mode", required: true },
+      value: { type: "string | string[]", description: "Selected value(s)" },
+      onValueChange: { type: "(value) => void", description: "Callback on value change" },
+      variant: { type: "'default' | 'outline'", default: "'default'", description: "Visual variant" },
+      size: { type: "'sm' | 'default' | 'lg'", default: "'default'", description: "Size variant" }
+    },
+    subComponents: ["ToggleGroupItem"],
+    example: `<ToggleGroup type="single" value={align} onValueChange={setAlign}>
+  <ToggleGroupItem value="left">Left</ToggleGroupItem>
+  <ToggleGroupItem value="center">Center</ToggleGroupItem>
+</ToggleGroup>`
   },
   // ============================================================================
   // FORMS (11)
@@ -107,7 +154,16 @@ var COMPONENT_REGISTRY = {
       "Bulk actions"
     ],
     dependencies: ["@radix-ui/react-checkbox"],
-    radixPrimitive: "@radix-ui/react-checkbox"
+    radixPrimitive: "@radix-ui/react-checkbox",
+    props: {
+      checked: { type: "boolean | 'indeterminate'", description: "Checked state" },
+      onCheckedChange: { type: "(checked: boolean) => void", description: "Callback on check change" },
+      disabled: { type: "boolean", default: "false", description: "Disable interaction" }
+    },
+    example: `<div className="flex items-center gap-2">
+  <Checkbox id="terms" checked={accepted} onCheckedChange={setAccepted} />
+  <Label htmlFor="terms">Accept terms</Label>
+</div>`
   },
   combobox: {
     name: "Combobox",
@@ -121,7 +177,21 @@ var COMPONENT_REGISTRY = {
       "Large option lists"
     ],
     dependencies: ["cmdk", "@radix-ui/react-popover"],
-    radixPrimitive: "@radix-ui/react-popover"
+    radixPrimitive: "@radix-ui/react-popover",
+    props: {
+      options: { type: "{ value: string; label: string }[]", description: "List of options", required: true },
+      value: { type: "string", description: "Selected value" },
+      onValueChange: { type: "(value: string) => void", description: "Callback on selection" },
+      placeholder: { type: "string", description: "Trigger placeholder text" },
+      searchPlaceholder: { type: "string", description: "Search input placeholder" },
+      emptyText: { type: "string", description: "Text when no results found" }
+    },
+    example: `<Combobox
+  options={[{ value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}
+  value={framework}
+  onValueChange={setFramework}
+  placeholder="Select framework"
+/>`
   },
   form: {
     name: "Form",
@@ -134,7 +204,23 @@ var COMPONENT_REGISTRY = {
       "Data entry",
       "Multi-step forms"
     ],
-    dependencies: ["react-hook-form", "@hookform/resolvers", "zod"]
+    dependencies: ["react-hook-form", "@hookform/resolvers", "zod"],
+    props: {
+      "...form": { type: "UseFormReturn", description: "Spread react-hook-form useForm() return value", required: true }
+    },
+    subComponents: ["FormControl", "FormDescription", "FormField", "FormItem", "FormLabel", "FormMessage"],
+    example: `<Form {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)}>
+    <FormField control={form.control} name="email" render={({ field }) => (
+      <FormItem>
+        <FormLabel>Email</FormLabel>
+        <FormControl><Input {...field} /></FormControl>
+        <FormMessage />
+      </FormItem>
+    )} />
+    <Button type="submit">Submit</Button>
+  </form>
+</Form>`
   },
   input: {
     name: "Input",
@@ -147,7 +233,13 @@ var COMPONENT_REGISTRY = {
       "Passwords",
       "Numeric input"
     ],
-    dependencies: []
+    dependencies: [],
+    props: {
+      type: { type: "string", default: "'text'", description: "HTML input type" },
+      placeholder: { type: "string", description: "Placeholder text" },
+      disabled: { type: "boolean", default: "false", description: "Disable interaction" }
+    },
+    example: `<Input type="email" placeholder="Enter email" />`
   },
   "input-otp": {
     name: "InputOTP",
@@ -160,7 +252,26 @@ var COMPONENT_REGISTRY = {
       "Phone verification",
       "Security codes"
     ],
-    dependencies: ["input-otp"]
+    dependencies: ["input-otp"],
+    props: {
+      maxLength: { type: "number", default: "6", description: "Maximum number of characters" },
+      value: { type: "string", description: "Controlled input value" },
+      onChange: { type: "(value: string) => void", description: "Callback on value change" }
+    },
+    subComponents: ["InputOTPGroup", "InputOTPSlot", "InputOTPSeparator"],
+    example: `<InputOTP maxLength={6}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>`
   },
   label: {
     name: "Label",
@@ -173,7 +284,12 @@ var COMPONENT_REGISTRY = {
       "Accessible forms"
     ],
     dependencies: ["@radix-ui/react-label"],
-    radixPrimitive: "@radix-ui/react-label"
+    radixPrimitive: "@radix-ui/react-label",
+    props: {
+      htmlFor: { type: "string", description: "ID of the associated form control" }
+    },
+    example: `<Label htmlFor="email">Email Address</Label>
+<Input id="email" type="email" />`
   },
   "radio-group": {
     name: "RadioGroup",
@@ -187,7 +303,19 @@ var COMPONENT_REGISTRY = {
       "Shipping options"
     ],
     dependencies: ["@radix-ui/react-radio-group"],
-    radixPrimitive: "@radix-ui/react-radio-group"
+    radixPrimitive: "@radix-ui/react-radio-group",
+    props: {
+      value: { type: "string", description: "Controlled selected value" },
+      onValueChange: { type: "(value: string) => void", description: "Callback on selection" },
+      disabled: { type: "boolean", default: "false", description: "Disable interaction" }
+    },
+    subComponents: ["RadioGroupItem"],
+    example: `<RadioGroup value={plan} onValueChange={setPlan}>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem value="free" id="free" />
+    <Label htmlFor="free">Free</Label>
+  </div>
+</RadioGroup>`
   },
   select: {
     name: "Select",
@@ -201,7 +329,22 @@ var COMPONENT_REGISTRY = {
       "Data sorting"
     ],
     dependencies: ["@radix-ui/react-select"],
-    radixPrimitive: "@radix-ui/react-select"
+    radixPrimitive: "@radix-ui/react-select",
+    props: {
+      value: { type: "string", description: "Controlled selected value" },
+      onValueChange: { type: "(value: string) => void", description: "Callback on selection" },
+      defaultValue: { type: "string", description: "Default selected value" }
+    },
+    subComponents: ["SelectTrigger", "SelectValue", "SelectContent", "SelectItem", "SelectGroup", "SelectLabel", "SelectSeparator"],
+    example: `<Select value={theme} onValueChange={setTheme}>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Select theme" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="light">Light</SelectItem>
+    <SelectItem value="dark">Dark</SelectItem>
+  </SelectContent>
+</Select>`
   },
   slider: {
     name: "Slider",
@@ -215,7 +358,16 @@ var COMPONENT_REGISTRY = {
       "Zoom level"
     ],
     dependencies: ["@radix-ui/react-slider"],
-    radixPrimitive: "@radix-ui/react-slider"
+    radixPrimitive: "@radix-ui/react-slider",
+    props: {
+      value: { type: "number[]", description: "Current value(s)" },
+      onValueChange: { type: "(value: number[]) => void", description: "Callback on value change" },
+      min: { type: "number", default: "0", description: "Minimum value" },
+      max: { type: "number", default: "100", description: "Maximum value" },
+      step: { type: "number", default: "1", description: "Step increment" },
+      disabled: { type: "boolean", default: "false", description: "Disable interaction" }
+    },
+    example: `<Slider value={[volume]} onValueChange={(v) => setVolume(v[0])} max={100} step={1} />`
   },
   switch: {
     name: "Switch",
@@ -229,7 +381,15 @@ var COMPONENT_REGISTRY = {
       "Mode switches"
     ],
     dependencies: ["@radix-ui/react-switch"],
-    radixPrimitive: "@radix-ui/react-switch"
+    radixPrimitive: "@radix-ui/react-switch",
+    props: {
+      checked: { type: "boolean", description: "Controlled checked state" },
+      onCheckedChange: { type: "(checked: boolean) => void", description: "Callback on toggle" },
+      size: { type: "'sm' | 'md' | 'lg'", default: "'md'", description: "Size variant" },
+      disabled: { type: "boolean", default: "false", description: "Disable interaction" },
+      label: { type: "string", description: "Optional label text" }
+    },
+    example: `<Switch checked={enabled} onCheckedChange={setEnabled} size="md" />`
   },
   textarea: {
     name: "Textarea",
@@ -242,7 +402,13 @@ var COMPONENT_REGISTRY = {
       "Descriptions",
       "Long-form text"
     ],
-    dependencies: []
+    dependencies: [],
+    props: {
+      placeholder: { type: "string", description: "Placeholder text" },
+      disabled: { type: "boolean", default: "false", description: "Disable interaction" },
+      rows: { type: "number", description: "Number of visible rows" }
+    },
+    example: `<Textarea placeholder="Write your message..." rows={4} />`
   },
   // ============================================================================
   // NAVIGATION (6)
@@ -258,7 +424,17 @@ var COMPONENT_REGISTRY = {
       "Location context",
       "Back navigation"
     ],
-    dependencies: []
+    dependencies: [],
+    subComponents: ["BreadcrumbList", "BreadcrumbItem", "BreadcrumbLink", "BreadcrumbPage", "BreadcrumbSeparator", "BreadcrumbEllipsis"],
+    example: `<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbLink href="/docs">Docs</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbPage>Current</BreadcrumbPage></BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>`
   },
   command: {
     name: "Command",
@@ -271,7 +447,18 @@ var COMPONENT_REGISTRY = {
       "Keyboard shortcuts",
       "Power user features"
     ],
-    dependencies: ["cmdk"]
+    dependencies: ["cmdk"],
+    subComponents: ["CommandInput", "CommandList", "CommandEmpty", "CommandGroup", "CommandItem", "CommandSeparator", "CommandShortcut", "CommandDialog"],
+    example: `<Command>
+  <CommandInput placeholder="Type a command..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Actions">
+      <CommandItem>Search</CommandItem>
+      <CommandItem>Settings</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>`
   },
   menubar: {
     name: "Menubar",
@@ -285,7 +472,19 @@ var COMPONENT_REGISTRY = {
       "Editor toolbars"
     ],
     dependencies: ["@radix-ui/react-menubar"],
-    radixPrimitive: "@radix-ui/react-menubar"
+    radixPrimitive: "@radix-ui/react-menubar",
+    subComponents: ["MenubarMenu", "MenubarTrigger", "MenubarContent", "MenubarItem", "MenubarSeparator", "MenubarLabel", "MenubarCheckboxItem", "MenubarRadioGroup", "MenubarRadioItem", "MenubarSub", "MenubarSubTrigger", "MenubarSubContent", "MenubarShortcut"],
+    example: `<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New <MenubarShortcut>\u2318N</MenubarShortcut></MenubarItem>
+      <MenubarItem>Open <MenubarShortcut>\u2318O</MenubarShortcut></MenubarItem>
+      <MenubarSeparator />
+      <MenubarItem>Exit</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>`
   },
   "navigation-menu": {
     name: "NavigationMenu",
@@ -299,7 +498,18 @@ var COMPONENT_REGISTRY = {
       "Multi-level navigation"
     ],
     dependencies: ["@radix-ui/react-navigation-menu"],
-    radixPrimitive: "@radix-ui/react-navigation-menu"
+    radixPrimitive: "@radix-ui/react-navigation-menu",
+    subComponents: ["NavigationMenuList", "NavigationMenuItem", "NavigationMenuTrigger", "NavigationMenuContent", "NavigationMenuLink", "NavigationMenuIndicator", "NavigationMenuViewport"],
+    example: `<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Getting Started</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <NavigationMenuLink href="/docs">Documentation</NavigationMenuLink>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>`
   },
   pagination: {
     name: "Pagination",
@@ -312,7 +522,17 @@ var COMPONENT_REGISTRY = {
       "Content lists",
       "Multi-page forms"
     ],
-    dependencies: []
+    dependencies: [],
+    subComponents: ["PaginationContent", "PaginationItem", "PaginationLink", "PaginationPrevious", "PaginationNext", "PaginationEllipsis"],
+    example: `<Pagination>
+  <PaginationContent>
+    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
+    <PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationLink href="#" isActive>2</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationLink href="#">3</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationNext href="#" /></PaginationItem>
+  </PaginationContent>
+</Pagination>`
   },
   tabs: {
     name: "Tabs",
@@ -326,7 +546,21 @@ var COMPONENT_REGISTRY = {
       "Dashboard sections"
     ],
     dependencies: ["@radix-ui/react-tabs"],
-    radixPrimitive: "@radix-ui/react-tabs"
+    radixPrimitive: "@radix-ui/react-tabs",
+    props: {
+      defaultValue: { type: "string", description: "Default active tab value" },
+      value: { type: "string", description: "Controlled active tab value" },
+      onValueChange: { type: "(value: string) => void", description: "Callback on tab change" }
+    },
+    subComponents: ["TabsList", "TabsTrigger", "TabsContent"],
+    example: `<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">Account settings here.</TabsContent>
+  <TabsContent value="password">Password settings here.</TabsContent>
+</Tabs>`
   },
   // ============================================================================
   // OVERLAYS (9)
@@ -343,7 +577,25 @@ var COMPONENT_REGISTRY = {
       "Irreversible operations"
     ],
     dependencies: ["@radix-ui/react-alert-dialog"],
-    radixPrimitive: "@radix-ui/react-alert-dialog"
+    radixPrimitive: "@radix-ui/react-alert-dialog",
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" }
+    },
+    subComponents: ["AlertDialogTrigger", "AlertDialogContent", "AlertDialogHeader", "AlertDialogTitle", "AlertDialogDescription", "AlertDialogFooter", "AlertDialogAction", "AlertDialogCancel"],
+    example: `<AlertDialog>
+  <AlertDialogTrigger asChild><Button variant="destructive">Delete</Button></AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>`
   },
   "context-menu": {
     name: "ContextMenu",
@@ -357,7 +609,17 @@ var COMPONENT_REGISTRY = {
       "Item actions"
     ],
     dependencies: ["@radix-ui/react-context-menu"],
-    radixPrimitive: "@radix-ui/react-context-menu"
+    radixPrimitive: "@radix-ui/react-context-menu",
+    subComponents: ["ContextMenuTrigger", "ContextMenuContent", "ContextMenuItem", "ContextMenuCheckboxItem", "ContextMenuRadioItem", "ContextMenuLabel", "ContextMenuSeparator", "ContextMenuShortcut", "ContextMenuSub", "ContextMenuSubTrigger", "ContextMenuSubContent", "ContextMenuRadioGroup"],
+    example: `<ContextMenu>
+  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Edit</ContextMenuItem>
+    <ContextMenuItem>Duplicate</ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuItem>Delete</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>`
   },
   dialog: {
     name: "Dialog",
@@ -371,7 +633,25 @@ var COMPONENT_REGISTRY = {
       "User input"
     ],
     dependencies: ["@radix-ui/react-dialog"],
-    radixPrimitive: "@radix-ui/react-dialog"
+    radixPrimitive: "@radix-ui/react-dialog",
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" }
+    },
+    subComponents: ["DialogTrigger", "DialogContent", "DialogHeader", "DialogTitle", "DialogDescription", "DialogFooter", "DialogClose"],
+    example: `<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description here.</DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>`
   },
   drawer: {
     name: "Drawer",
@@ -384,7 +664,26 @@ var COMPONENT_REGISTRY = {
       "Bottom sheets",
       "Mobile menus"
     ],
-    dependencies: ["vaul"]
+    dependencies: ["vaul"],
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" }
+    },
+    subComponents: ["DrawerTrigger", "DrawerContent", "DrawerHeader", "DrawerTitle", "DrawerDescription", "DrawerFooter", "DrawerClose"],
+    example: `<Drawer>
+  <DrawerTrigger asChild><Button>Open Drawer</Button></DrawerTrigger>
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Settings</DrawerTitle>
+      <DrawerDescription>Adjust preferences.</DrawerDescription>
+    </DrawerHeader>
+    <div className="p-4">Content here.</div>
+    <DrawerFooter>
+      <Button>Save</Button>
+      <DrawerClose asChild><Button variant="outline">Cancel</Button></DrawerClose>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>`
   },
   "dropdown-menu": {
     name: "DropdownMenu",
@@ -398,7 +697,21 @@ var COMPONENT_REGISTRY = {
       "Overflow menus"
     ],
     dependencies: ["@radix-ui/react-dropdown-menu"],
-    radixPrimitive: "@radix-ui/react-dropdown-menu"
+    radixPrimitive: "@radix-ui/react-dropdown-menu",
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" }
+    },
+    subComponents: ["DropdownMenuTrigger", "DropdownMenuContent", "DropdownMenuItem", "DropdownMenuLabel", "DropdownMenuSeparator", "DropdownMenuCheckboxItem", "DropdownMenuRadioGroup", "DropdownMenuRadioItem", "DropdownMenuSub", "DropdownMenuSubTrigger", "DropdownMenuSubContent"],
+    example: `<DropdownMenu>
+  <DropdownMenuTrigger asChild><Button variant="ghost">Options</Button></DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuLabel>Actions</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Edit</DropdownMenuItem>
+    <DropdownMenuItem>Delete</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>`
   },
   "hover-card": {
     name: "HoverCard",
@@ -412,7 +725,21 @@ var COMPONENT_REGISTRY = {
       "Additional context"
     ],
     dependencies: ["@radix-ui/react-hover-card"],
-    radixPrimitive: "@radix-ui/react-hover-card"
+    radixPrimitive: "@radix-ui/react-hover-card",
+    props: {
+      openDelay: { type: "number", default: "700", description: "Delay in ms before opening" },
+      closeDelay: { type: "number", default: "300", description: "Delay in ms before closing" }
+    },
+    subComponents: ["HoverCardTrigger", "HoverCardContent"],
+    example: `<HoverCard>
+  <HoverCardTrigger asChild><Link href="#">@username</Link></HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="flex gap-4">
+      <Avatar />
+      <div><p className="text-sm font-semibold">Username</p><p className="text-sm text-muted-foreground">Bio here.</p></div>
+    </div>
+  </HoverCardContent>
+</HoverCard>`
   },
   popover: {
     name: "Popover",
@@ -426,7 +753,16 @@ var COMPONENT_REGISTRY = {
       "Inline editors"
     ],
     dependencies: ["@radix-ui/react-popover"],
-    radixPrimitive: "@radix-ui/react-popover"
+    radixPrimitive: "@radix-ui/react-popover",
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" }
+    },
+    subComponents: ["PopoverTrigger", "PopoverContent", "PopoverAnchor"],
+    example: `<Popover>
+  <PopoverTrigger asChild><Button variant="outline">Open</Button></PopoverTrigger>
+  <PopoverContent className="w-80">Content here.</PopoverContent>
+</Popover>`
   },
   sheet: {
     name: "Sheet",
@@ -440,7 +776,19 @@ var COMPONENT_REGISTRY = {
       "Detail views"
     ],
     dependencies: ["@radix-ui/react-dialog"],
-    radixPrimitive: "@radix-ui/react-dialog"
+    radixPrimitive: "@radix-ui/react-dialog",
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" }
+    },
+    subComponents: ["SheetTrigger", "SheetContent", "SheetHeader", "SheetTitle", "SheetDescription", "SheetClose"],
+    example: `<Sheet>
+  <SheetTrigger asChild><Button>Open</Button></SheetTrigger>
+  <SheetContent side="right">
+    <SheetHeader><SheetTitle>Settings</SheetTitle></SheetHeader>
+    <div className="p-4">Content here.</div>
+  </SheetContent>
+</Sheet>`
   },
   tooltip: {
     name: "Tooltip",
@@ -454,7 +802,12 @@ var COMPONENT_REGISTRY = {
       "Keyboard shortcuts"
     ],
     dependencies: ["@radix-ui/react-tooltip"],
-    radixPrimitive: "@radix-ui/react-tooltip"
+    radixPrimitive: "@radix-ui/react-tooltip",
+    subComponents: ["TooltipTrigger", "TooltipContent", "TooltipProvider"],
+    example: `<Tooltip>
+  <TooltipTrigger asChild><Button variant="ghost" size="icon"><Info /></Button></TooltipTrigger>
+  <TooltipContent><p>Helpful information</p></TooltipContent>
+</Tooltip>`
   },
   // ============================================================================
   // FEEDBACK (5)
@@ -470,7 +823,15 @@ var COMPONENT_REGISTRY = {
       "Errors",
       "Success confirmations"
     ],
-    dependencies: []
+    dependencies: [],
+    props: {
+      variant: { type: "'default' | 'destructive'", default: "'default'", description: "Visual variant" }
+    },
+    subComponents: ["AlertTitle", "AlertDescription"],
+    example: `<Alert variant="destructive">
+  <AlertTitle>Error</AlertTitle>
+  <AlertDescription>Your session has expired.</AlertDescription>
+</Alert>`
   },
   progress: {
     name: "Progress",
@@ -484,7 +845,12 @@ var COMPONENT_REGISTRY = {
       "Multi-step forms"
     ],
     dependencies: ["@radix-ui/react-progress"],
-    radixPrimitive: "@radix-ui/react-progress"
+    radixPrimitive: "@radix-ui/react-progress",
+    props: {
+      value: { type: "number", default: "0", description: "Progress value (0-100)" },
+      max: { type: "number", default: "100", description: "Maximum value" }
+    },
+    example: `<Progress value={60} />`
   },
   skeleton: {
     name: "Skeleton",
@@ -497,12 +863,22 @@ var COMPONENT_REGISTRY = {
       "Initial load",
       "Lazy loading"
     ],
-    dependencies: []
+    dependencies: [],
+    props: {
+      variant: { type: "'default' | 'circular' | 'rectangular' | 'text'", default: "'default'", description: "Shape variant" },
+      width: { type: "string", default: "'100%'", description: "Width (CSS value)" },
+      height: { type: "string", default: "'20px'", description: "Height (CSS value)" }
+    },
+    example: `<div className="space-y-2">
+  <Skeleton className="h-12 w-12 rounded-full" />
+  <Skeleton className="h-4 w-[250px]" />
+  <Skeleton className="h-4 w-[200px]" />
+</div>`
   },
   sonner: {
     name: "Sonner",
     category: "feedback",
-    description: "Toast notification system with queuing and positioning",
+    description: "Toast notification system with queuing and positioning. Use Toaster component in layout, call toast() to trigger.",
     keywords: ["toast", "notification", "sonner", "message", "alert"],
     useCases: [
       "Success messages",
@@ -510,7 +886,14 @@ var COMPONENT_REGISTRY = {
       "Action feedback",
       "System messages"
     ],
-    dependencies: ["sonner"]
+    dependencies: ["sonner"],
+    subComponents: ["Toaster"],
+    example: `// In layout: <Toaster />
+// To trigger:
+import { toast } from 'sonner'
+toast.success('Saved successfully')
+toast.error('Something went wrong')
+toast('Default notification')`
   },
   toast: {
     name: "Toast",
@@ -524,7 +907,13 @@ var COMPONENT_REGISTRY = {
       "Confirmation messages"
     ],
     dependencies: ["@radix-ui/react-toast"],
-    radixPrimitive: "@radix-ui/react-toast"
+    radixPrimitive: "@radix-ui/react-toast",
+    subComponents: ["ToastAction", "ToastClose", "ToastDescription", "ToastProvider", "ToastTitle", "ToastViewport"],
+    example: `// Prefer using Sonner (Toaster + toast()) for new projects.
+// This is the Radix-based alternative.
+import { useToast } from '@thesage/ui'
+const { toast } = useToast()
+toast({ title: 'Success', description: 'Item saved.' })`
   },
   // ============================================================================
   // DATA DISPLAY (6)
@@ -541,7 +930,12 @@ var COMPONENT_REGISTRY = {
       "Chat participants"
     ],
     dependencies: ["@radix-ui/react-avatar"],
-    radixPrimitive: "@radix-ui/react-avatar"
+    radixPrimitive: "@radix-ui/react-avatar",
+    subComponents: ["AvatarImage", "AvatarFallback"],
+    example: `<Avatar>
+  <AvatarImage src="/avatar.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>`
   },
   badge: {
     name: "Badge",
@@ -554,7 +948,13 @@ var COMPONENT_REGISTRY = {
       "Categories",
       "Notification counts"
     ],
-    dependencies: []
+    dependencies: [],
+    props: {
+      variant: { type: "'default' | 'secondary' | 'destructive' | 'outline' | 'success' | 'warning' | 'error' | 'info'", default: "'default'", description: "Visual variant" },
+      size: { type: "'sm' | 'md' | 'lg'", default: "'md'", description: "Size variant" },
+      dot: { type: "boolean", default: "false", description: "Show animated indicator dot" }
+    },
+    example: `<Badge variant="success" dot>Active</Badge>`
   },
   calendar: {
     name: "Calendar",
@@ -567,7 +967,15 @@ var COMPONENT_REGISTRY = {
       "Booking systems",
       "Date ranges"
     ],
-    dependencies: ["react-day-picker", "date-fns"]
+    dependencies: ["react-day-picker", "date-fns"],
+    props: {
+      mode: { type: "'single' | 'multiple' | 'range'", default: "'single'", description: "Selection mode" },
+      selected: { type: "Date | Date[] | DateRange", description: "Selected date(s)" },
+      onSelect: { type: "(date) => void", description: "Callback on date selection" },
+      showOutsideDays: { type: "boolean", default: "true", description: "Show days from adjacent months" },
+      disabled: { type: "Matcher | Matcher[]", description: "Dates to disable" }
+    },
+    example: `<Calendar mode="single" selected={date} onSelect={setDate} />`
   },
   card: {
     name: "Card",
@@ -580,7 +988,20 @@ var COMPONENT_REGISTRY = {
       "Information panels",
       "Dashboard widgets"
     ],
-    dependencies: []
+    dependencies: [],
+    props: {
+      variant: { type: "'default' | 'glass' | 'outline'", default: "'default'", description: "Visual variant" },
+      hoverEffect: { type: "boolean", default: "false", description: "Enable hover lift and shadow" }
+    },
+    subComponents: ["CardHeader", "CardTitle", "CardDescription", "CardContent", "CardFooter"],
+    example: `<Card>
+  <CardHeader>
+    <CardTitle>Notifications</CardTitle>
+    <CardDescription>You have 3 unread messages.</CardDescription>
+  </CardHeader>
+  <CardContent><p>Content here.</p></CardContent>
+  <CardFooter><Button>View All</Button></CardFooter>
+</Card>`
   },
   "data-table": {
     name: "DataTable",
@@ -593,7 +1014,17 @@ var COMPONENT_REGISTRY = {
       "Reports",
       "List management"
     ],
-    dependencies: ["@tanstack/react-table"]
+    dependencies: ["@tanstack/react-table"],
+    props: {
+      columns: { type: "ColumnDef<TData, TValue>[]", description: "Column definitions from @tanstack/react-table", required: true },
+      data: { type: "TData[]", description: "Array of row data", required: true }
+    },
+    example: `import { DataTable } from '@thesage/ui/tables'
+const columns = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'email', header: 'Email' },
+]
+<DataTable columns={columns} data={users} />`
   },
   table: {
     name: "Table",
@@ -606,7 +1037,132 @@ var COMPONENT_REGISTRY = {
       "Comparison tables",
       "Pricing tables"
     ],
-    dependencies: []
+    dependencies: [],
+    subComponents: ["TableHeader", "TableBody", "TableFooter", "TableRow", "TableHead", "TableCell", "TableCaption"],
+    example: `<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Status</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>John</TableCell>
+      <TableCell>Active</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>`
+  },
+  heading: {
+    name: "Heading",
+    category: "data-display",
+    description: "Semantic heading with automatic token-based styling and responsive sizes",
+    keywords: ["heading", "title", "h1", "h2", "h3", "h4", "h5", "h6", "typography"],
+    useCases: [
+      "Page titles",
+      "Section headings",
+      "Content hierarchy",
+      "Semantic HTML structure"
+    ],
+    dependencies: [],
+    props: {
+      level: { type: "1 | 2 | 3 | 4 | 5 | 6", default: "2", description: "Heading level (renders h1-h6)" },
+      as: { type: "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'", description: "Override rendered HTML element" }
+    },
+    example: `<Heading level={1}>Page Title</Heading>
+<Heading level={2}>Section Title</Heading>`
+  },
+  text: {
+    name: "Text",
+    category: "data-display",
+    description: "Semantic text component with variants for primary, secondary, and muted styles",
+    keywords: ["text", "paragraph", "body", "typography", "content", "p", "span"],
+    useCases: [
+      "Body text",
+      "Descriptions",
+      "Helper text",
+      "Labels and captions"
+    ],
+    dependencies: [],
+    props: {
+      variant: { type: "'default' | 'secondary' | 'muted' | 'lead'", default: "'default'", description: "Text style variant" },
+      as: { type: "'p' | 'span' | 'div'", default: "'p'", description: "HTML element to render" },
+      size: { type: "'sm' | 'base' | 'lg'", default: "'base'", description: "Font size" }
+    },
+    example: `<Text variant="lead">Important introductory text.</Text>
+<Text variant="muted" size="sm">Helper text below an input.</Text>`
+  },
+  code: {
+    name: "Code",
+    category: "data-display",
+    description: "Code display with syntax highlighting for inline and block code",
+    keywords: ["code", "syntax", "highlighting", "programming", "snippet", "pre"],
+    useCases: [
+      "Code snippets",
+      "API documentation",
+      "Technical content",
+      "Inline code references"
+    ],
+    dependencies: [],
+    props: {
+      inline: { type: "boolean", default: "false", description: "Render as inline code (true) or block (false)" },
+      showCopy: { type: "boolean", default: "true", description: "Show copy button for block code" }
+    },
+    example: `// Inline
+<Code inline>npm install @thesage/ui</Code>
+
+// Block
+<Code>{\`const x = 1;
+const y = 2;\`}</Code>`
+  },
+  "collapsible-code-block": {
+    name: "CollapsibleCodeBlock",
+    category: "data-display",
+    description: "Expandable code block with syntax highlighting, preview mode, and copy functionality",
+    keywords: ["code", "collapsible", "expandable", "syntax", "copy", "preview"],
+    useCases: [
+      "Long code examples",
+      "Documentation code blocks",
+      "Tutorial code snippets",
+      "API examples"
+    ],
+    dependencies: ["@thesage/tokens"],
+    props: {
+      code: { type: "string", description: "Source code string", required: true },
+      language: { type: "'tsx' | 'typescript' | 'javascript' | 'jsx' | 'css' | 'html' | 'json' | 'bash'", default: "'tsx'", description: "Language for syntax highlighting" },
+      title: { type: "string", description: "Optional title above the code block" },
+      maxLines: { type: "number", default: "10", description: "Lines to show before collapsing" },
+      defaultExpanded: { type: "boolean", default: "false", description: "Start in expanded state" }
+    },
+    example: `<CollapsibleCodeBlock
+  code="const Button = () => <button>Click</button>"
+  language="tsx"
+  title="Button.tsx"
+  maxLines={5}
+/>`
+  },
+  "description-list": {
+    name: "DescriptionList",
+    category: "data-display",
+    description: "Key-value pair list for displaying labeled data in row or column layout",
+    keywords: ["description", "list", "key-value", "definition", "dl", "dt", "dd"],
+    useCases: [
+      "Product specifications",
+      "User profile details",
+      "Metadata display",
+      "Settings summaries"
+    ],
+    dependencies: [],
+    props: {
+      items: { type: "{ label: string; value: ReactNode }[]", description: "Array of label-value pairs", required: true },
+      layout: { type: "'row' | 'column'", default: "'row'", description: "Layout direction for label/value pairs" }
+    },
+    example: `<DescriptionList items={[
+  { label: 'Name', value: 'John Doe' },
+  { label: 'Email', value: 'john@example.com' },
+  { label: 'Role', value: <Badge>Admin</Badge> },
+]} />`
   },
   // ============================================================================
   // LAYOUT (8)
@@ -623,7 +1179,18 @@ var COMPONENT_REGISTRY = {
       "Information disclosure"
     ],
     dependencies: ["@radix-ui/react-accordion"],
-    radixPrimitive: "@radix-ui/react-accordion"
+    radixPrimitive: "@radix-ui/react-accordion",
+    props: {
+      type: { type: "'single' | 'multiple'", description: "Allow single or multiple open items", required: true },
+      collapsible: { type: "boolean", default: "false", description: 'Allow closing all items (type="single" only)' }
+    },
+    subComponents: ["AccordionItem", "AccordionTrigger", "AccordionContent"],
+    example: `<Accordion type="single" collapsible>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Is it accessible?</AccordionTrigger>
+    <AccordionContent>Yes. It follows WAI-ARIA patterns.</AccordionContent>
+  </AccordionItem>
+</Accordion>`
   },
   "aspect-ratio": {
     name: "AspectRatio",
@@ -637,7 +1204,13 @@ var COMPONENT_REGISTRY = {
       "Card images"
     ],
     dependencies: ["@radix-ui/react-aspect-ratio"],
-    radixPrimitive: "@radix-ui/react-aspect-ratio"
+    radixPrimitive: "@radix-ui/react-aspect-ratio",
+    props: {
+      ratio: { type: "number", default: "1", description: "Aspect ratio as a number (e.g. 16/9)" }
+    },
+    example: `<AspectRatio ratio={16 / 9}>
+  <img src="/image.jpg" alt="Photo" className="rounded-md object-cover w-full h-full" />
+</AspectRatio>`
   },
   carousel: {
     name: "Carousel",
@@ -650,7 +1223,23 @@ var COMPONENT_REGISTRY = {
       "Content sliders",
       "Testimonials"
     ],
-    dependencies: ["embla-carousel-react"]
+    dependencies: ["embla-carousel-react"],
+    props: {
+      orientation: { type: "'horizontal' | 'vertical'", default: "'horizontal'", description: "Scroll direction" },
+      opts: { type: "CarouselOptions", description: "Embla Carousel options (loop, align, etc.)" },
+      plugins: { type: "CarouselPlugin", description: "Embla Carousel plugins (autoplay, etc.)" },
+      setApi: { type: "(api: CarouselApi) => void", description: "Callback to get carousel API ref" }
+    },
+    subComponents: ["CarouselContent", "CarouselItem", "CarouselPrevious", "CarouselNext"],
+    example: `<Carousel>
+  <CarouselContent>
+    <CarouselItem>Slide 1</CarouselItem>
+    <CarouselItem>Slide 2</CarouselItem>
+    <CarouselItem>Slide 3</CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>`
   },
   collapsible: {
     name: "Collapsible",
@@ -664,7 +1253,19 @@ var COMPONENT_REGISTRY = {
       "Details disclosure"
     ],
     dependencies: ["@radix-ui/react-collapsible"],
-    radixPrimitive: "@radix-ui/react-collapsible"
+    radixPrimitive: "@radix-ui/react-collapsible",
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" },
+      defaultOpen: { type: "boolean", default: "false", description: "Default open state" }
+    },
+    subComponents: ["CollapsibleTrigger", "CollapsibleContent"],
+    example: `<Collapsible>
+  <CollapsibleTrigger asChild><Button variant="ghost">Toggle</Button></CollapsibleTrigger>
+  <CollapsibleContent>
+    <p>Hidden content revealed on click.</p>
+  </CollapsibleContent>
+</Collapsible>`
   },
   "date-picker": {
     name: "DatePicker",
@@ -677,7 +1278,14 @@ var COMPONENT_REGISTRY = {
       "Scheduling",
       "Filters"
     ],
-    dependencies: ["react-day-picker", "date-fns", "@radix-ui/react-popover"]
+    dependencies: ["react-day-picker", "date-fns", "@radix-ui/react-popover"],
+    props: {
+      date: { type: "Date", description: "Selected date" },
+      onDateChange: { type: "(date: Date | undefined) => void", description: "Callback on date change" },
+      placeholder: { type: "string", default: "'Pick a date'", description: "Placeholder text" },
+      disabled: { type: "boolean", default: "false", description: "Disable the date picker" }
+    },
+    example: `<DatePicker date={date} onDateChange={setDate} placeholder="Select date" />`
   },
   resizable: {
     name: "Resizable",
@@ -690,7 +1298,16 @@ var COMPONENT_REGISTRY = {
       "Dashboard layouts",
       "Adjustable sidebars"
     ],
-    dependencies: ["react-resizable-panels"]
+    dependencies: ["react-resizable-panels"],
+    props: {
+      direction: { type: "'horizontal' | 'vertical'", default: "'horizontal'", description: "Panel layout direction" }
+    },
+    subComponents: ["ResizablePanelGroup", "ResizablePanel", "ResizableHandle"],
+    example: `<ResizablePanelGroup direction="horizontal">
+  <ResizablePanel defaultSize={50}>Left panel</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={50}>Right panel</ResizablePanel>
+</ResizablePanelGroup>`
   },
   "scroll-area": {
     name: "ScrollArea",
@@ -704,7 +1321,11 @@ var COMPONENT_REGISTRY = {
       "Code displays"
     ],
     dependencies: ["@radix-ui/react-scroll-area"],
-    radixPrimitive: "@radix-ui/react-scroll-area"
+    radixPrimitive: "@radix-ui/react-scroll-area",
+    subComponents: ["ScrollBar"],
+    example: `<ScrollArea className="h-[200px] w-full rounded-md border p-4">
+  <div>Long scrollable content here...</div>
+</ScrollArea>`
   },
   separator: {
     name: "Separator",
@@ -718,7 +1339,837 @@ var COMPONENT_REGISTRY = {
       "Visual hierarchy"
     ],
     dependencies: ["@radix-ui/react-separator"],
-    radixPrimitive: "@radix-ui/react-separator"
+    radixPrimitive: "@radix-ui/react-separator",
+    props: {
+      orientation: { type: "'horizontal' | 'vertical'", default: "'horizontal'", description: "Orientation" }
+    },
+    example: `<Separator orientation="horizontal" />`
+  },
+  grid: {
+    name: "Grid",
+    category: "layout",
+    description: "Responsive CSS grid with column and gap configuration",
+    keywords: ["grid", "layout", "columns", "responsive", "css-grid"],
+    useCases: [
+      "Card grids",
+      "Gallery layouts",
+      "Dashboard layouts",
+      "Responsive content grids"
+    ],
+    dependencies: [],
+    props: {
+      columns: { type: "number | { sm?: number; md?: number; lg?: number }", default: "3", description: "Number of grid columns (responsive object supported)" },
+      gap: { type: "number | string", default: "4", description: "Gap between grid items (Tailwind spacing scale)" }
+    },
+    example: `<Grid columns={{ sm: 1, md: 2, lg: 3 }} gap={4}>
+  <Card>Item 1</Card>
+  <Card>Item 2</Card>
+  <Card>Item 3</Card>
+</Grid>`
+  },
+  container: {
+    name: "Container",
+    category: "layout",
+    description: "Content wrapper with consistent max-width and padding variants",
+    keywords: ["container", "wrapper", "max-width", "centered", "layout"],
+    useCases: [
+      "Page content wrapper",
+      "Centered layouts",
+      "Responsive widths",
+      "Content alignment"
+    ],
+    dependencies: [],
+    props: {
+      size: { type: "'sm' | 'md' | 'lg' | 'xl' | 'full'", default: "'lg'", description: "Max-width variant" },
+      padding: { type: "boolean", default: "true", description: "Apply horizontal padding" }
+    },
+    example: `<Container size="lg">
+  <Heading level={1}>Page Title</Heading>
+  <Text>Content within max-width container.</Text>
+</Container>`
+  },
+  stack: {
+    name: "Stack",
+    category: "layout",
+    description: "Flexbox layout for vertical or horizontal stacking with gap control",
+    keywords: ["stack", "flex", "vertical", "horizontal", "spacing", "layout"],
+    useCases: [
+      "Vertical layouts",
+      "Horizontal layouts",
+      "Form layouts",
+      "Button groups"
+    ],
+    dependencies: [],
+    props: {
+      direction: { type: "'vertical' | 'horizontal'", default: "'vertical'", description: "Stack direction" },
+      gap: { type: "number | string", default: "4", description: "Gap between items (Tailwind spacing scale)" },
+      align: { type: "'start' | 'center' | 'end' | 'stretch'", default: "'stretch'", description: "Cross-axis alignment" },
+      justify: { type: "'start' | 'center' | 'end' | 'between'", description: "Main-axis alignment" }
+    },
+    example: `<Stack direction="horizontal" gap={2} align="center">
+  <Button>Save</Button>
+  <Button variant="outline">Cancel</Button>
+</Stack>`
+  },
+  sidebar: {
+    name: "Sidebar",
+    category: "layout",
+    description: "Navigation sidebar with header, content, footer sections and mobile overlay",
+    keywords: ["sidebar", "navigation", "panel", "drawer", "menu"],
+    useCases: [
+      "App navigation",
+      "Dashboard sidebars",
+      "Settings panels",
+      "Mobile menus"
+    ],
+    dependencies: ["@radix-ui/react-slot"],
+    radixPrimitive: "@radix-ui/react-slot",
+    props: {
+      isOpen: { type: "boolean", default: "true", description: "Whether sidebar is visible/expanded" }
+    },
+    subComponents: ["SidebarHeader", "SidebarContent", "SidebarFooter", "SidebarItem"],
+    example: `<Sidebar>
+  <SidebarHeader><h2>My App</h2></SidebarHeader>
+  <SidebarContent>
+    <SidebarItem icon={<Home />} isActive>Dashboard</SidebarItem>
+    <SidebarItem icon={<Settings />}>Settings</SidebarItem>
+  </SidebarContent>
+  <SidebarFooter>
+    <SidebarItem icon={<LogOut />}>Logout</SidebarItem>
+  </SidebarFooter>
+</Sidebar>`
+  },
+  header: {
+    name: "Header",
+    category: "layout",
+    description: "Page header with sticky positioning, glass morphism, and mobile menu",
+    keywords: ["header", "navbar", "navigation", "sticky", "mobile-menu"],
+    useCases: [
+      "Site headers",
+      "App navigation bars",
+      "Sticky headers",
+      "Mobile-friendly navigation"
+    ],
+    dependencies: ["lucide-react"],
+    props: {
+      logo: { type: "ReactNode", description: "Logo element for header" },
+      links: { type: "{ label: string; href: string }[]", description: "Navigation links" },
+      sticky: { type: "boolean", default: "true", description: "Stick to top on scroll" },
+      transparent: { type: "boolean", default: "false", description: "Transparent background (for hero sections)" }
+    },
+    example: `<Header
+  logo={<Brand />}
+  links={[
+    { label: 'Home', href: '/' },
+    { label: 'About', href: '/about' },
+  ]}
+/>`
+  },
+  footer: {
+    name: "Footer",
+    category: "layout",
+    description: "Page footer with multi-column layout, social links, and copyright",
+    keywords: ["footer", "navigation", "links", "copyright", "social"],
+    useCases: [
+      "Site footers",
+      "Navigation sections",
+      "Contact information",
+      "Copyright notices"
+    ],
+    dependencies: [],
+    props: {
+      columns: { type: "{ title: string; links: { label: string; href: string }[] }[]", description: "Footer navigation columns" },
+      copyright: { type: "string", description: "Copyright text" },
+      socialLinks: { type: "{ icon: ReactNode; href: string }[]", description: "Social media links" }
+    },
+    example: `<Footer
+  columns={[{ title: 'Product', links: [{ label: 'Docs', href: '/docs' }] }]}
+  copyright="\xA9 2026 My Company"
+/>`
+  },
+  "customizer-panel": {
+    name: "CustomizerPanel",
+    category: "layout",
+    description: "Floating panel for theme, mode, and motion customization. Reads from ThemeProvider context.",
+    keywords: ["customizer", "theme", "settings", "preferences", "dark-mode"],
+    useCases: [
+      "Theme selection",
+      "Dark mode toggle",
+      "Motion preferences",
+      "User experience customization"
+    ],
+    dependencies: ["lucide-react", "@thesage/tokens"],
+    example: `// Place in your layout. It reads theme state from ThemeProvider.
+<CustomizerPanel />`
+  },
+  "page-layout": {
+    name: "PageLayout",
+    category: "layout",
+    description: "Flexible page layout with header, nav stacks, breadcrumbs, and footer",
+    keywords: ["layout", "page", "template", "structure", "swiss-grid"],
+    useCases: [
+      "Page structure",
+      "Content layouts",
+      "Documentation pages",
+      "Dashboard layouts"
+    ],
+    dependencies: [],
+    props: {
+      header: { type: "ReactNode", description: "Header element" },
+      footer: { type: "ReactNode", description: "Footer element" },
+      sidebar: { type: "ReactNode", description: "Optional sidebar" },
+      breadcrumbs: { type: "ReactNode", description: "Breadcrumb navigation" }
+    },
+    example: `<PageLayout
+  header={<Header />}
+  footer={<Footer />}
+>
+  <main>Page content</main>
+</PageLayout>`
+  },
+  "page-template": {
+    name: "PageTemplate",
+    category: "layout",
+    description: "Opinionated page template with Swiss Grid design and customizer",
+    keywords: ["template", "page", "swiss-grid", "layout", "documentation"],
+    useCases: [
+      "Blog pages",
+      "Documentation pages",
+      "Standard app pages",
+      "Content-focused layouts"
+    ],
+    dependencies: [],
+    props: {
+      title: { type: "string", description: "Page title" },
+      description: { type: "string", description: "Page description" },
+      showCustomizer: { type: "boolean", default: "true", description: "Show customizer panel" }
+    },
+    example: `<PageTemplate title="Documentation" description="Learn the design system.">
+  <div>Content here.</div>
+</PageTemplate>`
+  },
+  // ============================================================================
+  // ACTIONS - Additional (2 more)
+  // ============================================================================
+  link: {
+    name: "Link",
+    category: "actions",
+    description: "Styled anchor element with theme-aware colors and hover states",
+    keywords: ["link", "anchor", "href", "navigation", "a", "url"],
+    useCases: [
+      "Text links",
+      "Navigation links",
+      "External references",
+      "Inline actions"
+    ],
+    dependencies: [],
+    props: {
+      href: { type: "string", description: "Link URL", required: true },
+      variant: { type: "'default' | 'inline'", default: "'default'", description: "Default for standalone links, inline for text links" },
+      hoverEffect: { type: "boolean", default: "true", description: "Enable hover effect" }
+    },
+    example: `<Link href="/about" variant="inline">Learn More</Link>`
+  },
+  magnetic: {
+    name: "Magnetic",
+    category: "actions",
+    description: "Magnetic hover effect that attracts elements toward cursor",
+    keywords: ["magnetic", "hover", "effect", "cursor", "animation", "interactive"],
+    useCases: [
+      "Interactive buttons",
+      "Hover effects",
+      "Playful interactions",
+      "Cursor attraction"
+    ],
+    dependencies: ["framer-motion"],
+    props: {
+      children: { type: "ReactNode", description: "Element to apply magnetic effect to", required: true },
+      strength: { type: "number", default: "0.5", description: "Magnetic pull strength (0-1)" }
+    },
+    example: `<Magnetic strength={0.5}>
+  <Button>Hover me</Button>
+</Magnetic>`
+  },
+  // ============================================================================
+  // FORMS - Additional (7 more)
+  // ============================================================================
+  "search-bar": {
+    name: "SearchBar",
+    category: "forms",
+    description: "Search input with icon, clear button, and keyboard shortcuts",
+    keywords: ["search", "input", "find", "query", "filter", "bar"],
+    useCases: [
+      "Site search",
+      "Content filtering",
+      "Command palette trigger",
+      "Data filtering"
+    ],
+    dependencies: ["lucide-react"],
+    props: {
+      value: { type: "string", description: "Controlled search value" },
+      onChange: { type: "(value: string) => void", description: "Callback on value change" },
+      placeholder: { type: "string", default: "'Search...'", description: "Placeholder text" },
+      onClear: { type: "() => void", description: "Callback on clear button click" }
+    },
+    example: `<SearchBar value={query} onChange={setQuery} placeholder="Search components..." />`
+  },
+  "filter-button": {
+    name: "FilterButton",
+    category: "forms",
+    description: "Button for filtering content with active/inactive states",
+    keywords: ["filter", "button", "toggle", "category", "selection"],
+    useCases: [
+      "Category filters",
+      "Tag selection",
+      "Content filtering",
+      "Quick filters"
+    ],
+    dependencies: [],
+    props: {
+      active: { type: "boolean", default: "false", description: "Whether filter is active" },
+      onClick: { type: "() => void", description: "Click handler" },
+      children: { type: "ReactNode", description: "Filter label", required: true }
+    },
+    example: `<FilterButton active={category === 'all'} onClick={() => setCategory('all')}>All</FilterButton>`
+  },
+  "theme-switcher": {
+    name: "ThemeSwitcher",
+    category: "forms",
+    description: "Multi-theme selector for switching between Studio, Terra, and Volt. Reads/writes to ThemeProvider context.",
+    keywords: ["theme", "switcher", "selector", "studio", "terra", "volt"],
+    useCases: [
+      "Theme selection",
+      "Brand customization",
+      "User preferences",
+      "Design switching"
+    ],
+    dependencies: [],
+    example: `// Reads from ThemeProvider context, no props needed.
+<ThemeSwitcher />`
+  },
+  "theme-toggle": {
+    name: "ThemeToggle",
+    category: "forms",
+    description: "Light/dark mode toggle with smooth transitions. Reads/writes to ThemeProvider context.",
+    keywords: ["theme", "toggle", "dark-mode", "light-mode", "mode"],
+    useCases: [
+      "Dark mode switch",
+      "Light mode switch",
+      "Theme mode control",
+      "Accessibility preference"
+    ],
+    dependencies: ["lucide-react"],
+    example: `// Reads from ThemeProvider context, no props needed.
+<ThemeToggle />`
+  },
+  "color-picker": {
+    name: "ColorPicker",
+    category: "forms",
+    description: "Color selection input with preset swatches and custom color support",
+    keywords: ["color", "picker", "palette", "swatch", "hex", "customization"],
+    useCases: [
+      "Brand color selection",
+      "Theme customization",
+      "Design tools",
+      "User preferences"
+    ],
+    dependencies: [],
+    props: {
+      value: { type: "string", description: "Selected color (hex string)" },
+      onChange: { type: "(color: string) => void", description: "Callback on color change" },
+      presets: { type: "string[]", description: "Preset color swatches (hex values)" }
+    },
+    example: `<ColorPicker value={color} onChange={setColor} presets={['#ef4444', '#3b82f6', '#22c55e']} />`
+  },
+  "drag-drop": {
+    name: "DragDrop",
+    category: "forms",
+    description: "Drag and drop file upload zone with preview support",
+    keywords: ["drag", "drop", "upload", "file", "dropzone", "input"],
+    useCases: [
+      "File uploads",
+      "Image uploads",
+      "Document uploads",
+      "Bulk imports"
+    ],
+    dependencies: [],
+    props: {
+      onDrop: { type: "(files: File[]) => void", description: "Callback when files are dropped", required: true },
+      accept: { type: "string", description: 'Accepted file types (e.g. "image/*")' },
+      maxSize: { type: "number", description: "Max file size in bytes" },
+      multiple: { type: "boolean", default: "true", description: "Allow multiple files" }
+    },
+    example: `<DragDrop onDrop={(files) => handleUpload(files)} accept="image/*" maxSize={5242880} />`
+  },
+  "text-field": {
+    name: "TextField",
+    category: "forms",
+    description: "Complete text input with label, helper text, and error states",
+    keywords: ["text", "field", "input", "label", "form", "validation"],
+    useCases: [
+      "Form fields",
+      "Labeled inputs",
+      "Validated inputs",
+      "Complete form controls"
+    ],
+    dependencies: [],
+    props: {
+      label: { type: "string", description: "Field label text" },
+      helperText: { type: "string", description: "Helper text below input" },
+      error: { type: "string", description: "Error message (shows error state when set)" },
+      required: { type: "boolean", default: "false", description: "Mark as required" }
+    },
+    example: `<TextField label="Email" helperText="We'll never share your email." error={errors.email} required />`
+  },
+  // ============================================================================
+  // NAVIGATION - Additional (4 more)
+  // ============================================================================
+  "nav-link": {
+    name: "NavLink",
+    category: "navigation",
+    description: "Navigation link with active state indicators and variants",
+    keywords: ["nav", "link", "navigation", "active", "menu", "item"],
+    useCases: [
+      "Navigation menus",
+      "Sidebar links",
+      "Header navigation",
+      "Active page indicators"
+    ],
+    dependencies: [],
+    props: {
+      href: { type: "string", description: "Link URL", required: true },
+      isActive: { type: "boolean", default: "false", description: "Active state indicator" },
+      variant: { type: "'default' | 'subtle'", default: "'default'", description: "Visual variant" }
+    },
+    example: `<NavLink href="/dashboard" isActive>Dashboard</NavLink>`
+  },
+  "secondary-nav": {
+    name: "SecondaryNav",
+    category: "navigation",
+    description: "Horizontal secondary navigation bar for section switching",
+    keywords: ["secondary", "navigation", "tabs", "sections", "subnav"],
+    useCases: [
+      "Section navigation",
+      "Page subsections",
+      "Tab-like navigation",
+      "Category switching"
+    ],
+    dependencies: [],
+    props: {
+      items: { type: "{ label: string; href: string; isActive?: boolean }[]", description: "Navigation items", required: true }
+    },
+    example: `<SecondaryNav items={[
+  { label: 'Overview', href: '/overview', isActive: true },
+  { label: 'Settings', href: '/settings' },
+]} />`
+  },
+  "tertiary-nav": {
+    name: "TertiaryNav",
+    category: "navigation",
+    description: "Third-level navigation for deep content hierarchies",
+    keywords: ["tertiary", "navigation", "deep", "hierarchy", "subnav"],
+    useCases: [
+      "Deep navigation",
+      "Documentation sections",
+      "Multi-level content",
+      "Nested categories"
+    ],
+    dependencies: [],
+    props: {
+      items: { type: "{ label: string; href: string; isActive?: boolean }[]", description: "Navigation items", required: true }
+    },
+    example: `<TertiaryNav items={[
+  { label: 'Props', href: '#props', isActive: true },
+  { label: 'Examples', href: '#examples' },
+]} />`
+  },
+  breadcrumbs: {
+    name: "Breadcrumbs",
+    category: "navigation",
+    description: "Breadcrumb navigation with home icon and variants",
+    keywords: ["breadcrumbs", "navigation", "path", "trail", "hierarchy"],
+    useCases: [
+      "Page location",
+      "Navigation trail",
+      "Hierarchical navigation",
+      "Back navigation"
+    ],
+    dependencies: ["lucide-react"],
+    props: {
+      items: { type: "{ label: string; href?: string }[]", description: "Breadcrumb trail items (last item is current page)", required: true },
+      showHome: { type: "boolean", default: "true", description: "Show home icon as first item" }
+    },
+    example: `<Breadcrumbs items={[
+  { label: 'Home', href: '/' },
+  { label: 'Components', href: '/components' },
+  { label: 'Button' },
+]} />`
+  },
+  // ============================================================================
+  // OVERLAYS - Additional (2 more)
+  // ============================================================================
+  modal: {
+    name: "Modal",
+    category: "overlays",
+    description: "Simple modal wrapper around Dialog with common patterns",
+    keywords: ["modal", "dialog", "popup", "overlay", "window"],
+    useCases: [
+      "Simple modals",
+      "Confirmation dialogs",
+      "Form modals",
+      "Content overlays"
+    ],
+    dependencies: ["@radix-ui/react-dialog"],
+    radixPrimitive: "@radix-ui/react-dialog",
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" },
+      title: { type: "string", description: "Modal title" },
+      description: { type: "string", description: "Modal description" }
+    },
+    example: `<Modal open={isOpen} onOpenChange={setIsOpen} title="Confirm" description="Are you sure?">
+  <div className="flex gap-2 justify-end">
+    <Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
+    <Button onClick={handleConfirm}>Confirm</Button>
+  </div>
+</Modal>`
+  },
+  dropdown: {
+    name: "Dropdown",
+    category: "overlays",
+    description: "Simple dropdown wrapper for common dropdown patterns",
+    keywords: ["dropdown", "menu", "select", "options", "popover"],
+    useCases: [
+      "Action menus",
+      "User menus",
+      "Quick selections",
+      "Option lists"
+    ],
+    dependencies: ["@radix-ui/react-dropdown-menu"],
+    radixPrimitive: "@radix-ui/react-dropdown-menu",
+    props: {
+      open: { type: "boolean", description: "Controlled open state" },
+      onOpenChange: { type: "(open: boolean) => void", description: "Callback on open/close" }
+    },
+    example: `// For most cases, use DropdownMenu directly. This is a simplified wrapper.`
+  },
+  // ============================================================================
+  // FEEDBACK - Additional (2 more)
+  // ============================================================================
+  spinner: {
+    name: "Spinner",
+    category: "feedback",
+    description: "Animated loading spinner with size variants",
+    keywords: ["spinner", "loading", "loader", "progress", "waiting"],
+    useCases: [
+      "Loading states",
+      "Button loading",
+      "Data fetching",
+      "Async operations"
+    ],
+    dependencies: [],
+    props: {
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'", default: "'md'", description: "Spinner size" },
+      variant: { type: "'primary' | 'secondary' | 'inherit'", default: "'primary'", description: "Color variant" }
+    },
+    example: `<Spinner size="md" />
+<Button disabled><Spinner size="xs" variant="inherit" /> Loading...</Button>`
+  },
+  "progress-bar": {
+    name: "ProgressBar",
+    category: "feedback",
+    description: "Horizontal progress bar with percentage display",
+    keywords: ["progress", "bar", "loading", "percentage", "completion"],
+    useCases: [
+      "File uploads",
+      "Task progress",
+      "Loading indicators",
+      "Step completion"
+    ],
+    dependencies: [],
+    props: {
+      value: { type: "number", default: "0", description: "Progress value (0-100)" },
+      variant: { type: "'primary' | 'success' | 'warning' | 'error' | 'info'", default: "'primary'", description: "Color variant" },
+      size: { type: "'sm' | 'md' | 'lg'", default: "'md'", description: "Bar height" },
+      showLabel: { type: "boolean", default: "false", description: "Show percentage label" }
+    },
+    example: `<ProgressBar value={75} variant="success" showLabel />`
+  },
+  // ============================================================================
+  // DATA DISPLAY - Additional (5 more)
+  // ============================================================================
+  brand: {
+    name: "Brand",
+    category: "data-display",
+    description: "Theme-aware brand/logo component with size variants and link support",
+    keywords: ["brand", "logo", "identity", "header", "company"],
+    useCases: [
+      "Site logos",
+      "Header branding",
+      "Footer branding",
+      "App identity"
+    ],
+    dependencies: [],
+    props: {
+      variant: { type: "'default' | 'mark'", default: "'default'", description: "Full logo or mark only" },
+      size: { type: "'sm' | 'md' | 'lg'", default: "'md'", description: "Logo size" },
+      href: { type: "string", description: "Optional link URL (wraps in anchor)" }
+    },
+    example: `<Brand size="md" href="/" />`
+  },
+  "aspect-image": {
+    name: "AspectImage",
+    category: "data-display",
+    description: "Image with configurable aspect ratio, rounded corners, and captions",
+    keywords: ["image", "aspect", "ratio", "figure", "caption", "media"],
+    useCases: [
+      "Gallery images",
+      "Article images",
+      "Product images",
+      "Thumbnails with captions"
+    ],
+    dependencies: [],
+    props: {
+      src: { type: "string", description: "Image source URL", required: true },
+      alt: { type: "string", description: "Alt text for accessibility", required: true },
+      ratio: { type: "number", default: "16/9", description: "Aspect ratio" },
+      rounded: { type: "'none' | 'sm' | 'md' | 'lg' | 'full'", default: "'md'", description: "Border radius" },
+      caption: { type: "string", description: "Optional caption text below image" }
+    },
+    example: `<AspectImage src="/photo.jpg" alt="Team photo" ratio={4/3} caption="Our team" />`
+  },
+  "variable-weight-text": {
+    name: "VariableWeightText",
+    category: "data-display",
+    description: "Animated text with breathing font-weight effect using variable fonts",
+    keywords: ["variable", "font", "weight", "animation", "breathing", "motion"],
+    useCases: [
+      "Hero text",
+      "Emphasis text",
+      "Attention grabbing",
+      "Variable font showcase"
+    ],
+    dependencies: ["framer-motion"],
+    props: {
+      children: { type: "string", description: "Text content", required: true },
+      speed: { type: "number", default: "2", description: "Animation speed in seconds" },
+      minWeight: { type: "number", default: "100", description: "Minimum font weight" },
+      maxWeight: { type: "number", default: "900", description: "Maximum font weight" }
+    },
+    example: `<VariableWeightText speed={2} minWeight={200} maxWeight={800}>Design</VariableWeightText>`
+  },
+  typewriter: {
+    name: "Typewriter",
+    category: "data-display",
+    description: "Typewriter text animation with cursor and loop support",
+    keywords: ["typewriter", "typing", "animation", "cursor", "text", "effect"],
+    useCases: [
+      "Hero taglines",
+      "Terminal effects",
+      "Dynamic headings",
+      "Attention text"
+    ],
+    dependencies: ["framer-motion"],
+    props: {
+      words: { type: "string[]", description: "Words to cycle through", required: true },
+      speed: { type: "number", default: "100", description: "Typing speed in ms per character" },
+      loop: { type: "boolean", default: "true", description: "Loop through words continuously" },
+      cursor: { type: "boolean", default: "true", description: "Show blinking cursor" }
+    },
+    example: `<Typewriter words={['Developer', 'Designer', 'Creator']} speed={80} />`
+  },
+  "github-icon": {
+    name: "GitHubIcon",
+    category: "data-display",
+    description: "GitHub logo icon that inherits text color for theme support",
+    keywords: ["github", "icon", "social", "logo", "svg"],
+    useCases: [
+      "Social links",
+      "Footer icons",
+      "Repository links",
+      "Open source badges"
+    ],
+    dependencies: [],
+    props: {
+      size: { type: "number", default: "24", description: "Icon size in pixels" }
+    },
+    example: `<a href="https://github.com/you"><GitHubIcon size={20} /></a>`
+  },
+  // ============================================================================
+  // SPECIALTY - Backgrounds (3)
+  // ============================================================================
+  "warp-background": {
+    name: "WarpBackground",
+    category: "backgrounds",
+    description: "Animated warp speed star field background effect",
+    keywords: ["warp", "stars", "background", "animation", "space", "effect"],
+    useCases: [
+      "Hero backgrounds",
+      "Landing pages",
+      "Loading screens",
+      "Sci-fi themes"
+    ],
+    dependencies: ["framer-motion"],
+    props: {
+      speed: { type: "number", default: "1", description: "Warp speed multiplier" },
+      density: { type: "number", default: "200", description: "Number of stars" },
+      color: { type: "string", default: "'white'", description: "Star color" }
+    },
+    example: `<WarpBackground speed={1.5} density={300}>
+  <div className="relative z-10">Content over stars</div>
+</WarpBackground>`
+  },
+  "faulty-terminal": {
+    name: "FaultyTerminal",
+    category: "backgrounds",
+    description: "Glitchy terminal background with flickering and scan lines",
+    keywords: ["terminal", "glitch", "background", "retro", "crt", "effect"],
+    useCases: [
+      "Retro themes",
+      "Hacker aesthetics",
+      "Error pages",
+      "Terminal UIs"
+    ],
+    dependencies: [],
+    props: {
+      children: { type: "ReactNode", description: "Content to render inside terminal" }
+    },
+    example: `<FaultyTerminal>
+  <p>$ system initializing...</p>
+</FaultyTerminal>`
+  },
+  "orb-background": {
+    name: "OrbBackground",
+    category: "backgrounds",
+    description: "Animated floating orb with gradient blur effect",
+    keywords: ["orb", "gradient", "background", "animation", "blur", "ambient"],
+    useCases: [
+      "Landing pages",
+      "Hero sections",
+      "Ambient backgrounds",
+      "Modern aesthetics"
+    ],
+    dependencies: ["framer-motion"],
+    props: {
+      color: { type: "string", description: "Primary orb color" },
+      size: { type: "number", default: "400", description: "Orb diameter in pixels" }
+    },
+    example: `<OrbBackground color="var(--color-primary)" size={500}>
+  <div className="relative z-10">Content</div>
+</OrbBackground>`
+  },
+  // ============================================================================
+  // SPECIALTY - Cursor (2)
+  // ============================================================================
+  "splash-cursor": {
+    name: "SplashCursor",
+    category: "cursor",
+    description: "Custom cursor with splash/ripple effect on click. WebGL-based fluid simulation.",
+    keywords: ["cursor", "splash", "ripple", "click", "effect", "interactive"],
+    useCases: [
+      "Interactive experiences",
+      "Creative portfolios",
+      "Playful interfaces",
+      "Click feedback"
+    ],
+    dependencies: [],
+    example: `// Place once in layout. Replaces default cursor globally.
+<SplashCursor />`
+  },
+  "target-cursor": {
+    name: "TargetCursor",
+    category: "cursor",
+    description: "Custom cursor with target/crosshair appearance",
+    keywords: ["cursor", "target", "crosshair", "pointer", "custom"],
+    useCases: [
+      "Gaming interfaces",
+      "Precision tools",
+      "Interactive elements",
+      "Custom pointers"
+    ],
+    dependencies: [],
+    example: `// Place once in layout. Replaces default cursor globally.
+<TargetCursor />`
+  },
+  // ============================================================================
+  // SPECIALTY - Motion (1)
+  // ============================================================================
+  "animated-beam": {
+    name: "AnimatedBeam",
+    category: "motion",
+    description: "Animated beam/line connecting two elements",
+    keywords: ["beam", "animation", "connection", "line", "flow", "motion"],
+    useCases: [
+      "Connecting elements",
+      "Data flow visualization",
+      "Architecture diagrams",
+      "Interactive connections"
+    ],
+    dependencies: ["framer-motion"],
+    props: {
+      fromRef: { type: "RefObject<HTMLElement>", description: "Ref to source element", required: true },
+      toRef: { type: "RefObject<HTMLElement>", description: "Ref to target element", required: true },
+      duration: { type: "number", default: "3", description: "Animation duration in seconds" }
+    },
+    example: `const fromRef = useRef(null)
+const toRef = useRef(null)
+<div ref={fromRef}>Source</div>
+<div ref={toRef}>Target</div>
+<AnimatedBeam fromRef={fromRef} toRef={toRef} />`
+  },
+  // ============================================================================
+  // SPECIALTY - Blocks (2)
+  // ============================================================================
+  hero: {
+    name: "Hero",
+    category: "blocks",
+    description: "Full-width hero section with title, subtitle, and CTA",
+    keywords: ["hero", "banner", "header", "landing", "cta", "section"],
+    useCases: [
+      "Landing pages",
+      "Page headers",
+      "Marketing sections",
+      "Feature highlights"
+    ],
+    dependencies: [],
+    props: {
+      title: { type: "string", description: "Main heading text", required: true },
+      subtitle: { type: "string", description: "Subtitle or tagline" },
+      cta: { type: "ReactNode", description: "Call-to-action element (Button, etc.)" },
+      background: { type: "ReactNode", description: "Optional background element (WarpBackground, OrbBackground, etc.)" }
+    },
+    example: `<Hero
+  title="Build Something Beautiful"
+  subtitle="A design system that brings joy."
+  cta={<Button size="lg">Get Started</Button>}
+/>`
+  },
+  "open-graph-card": {
+    name: "OpenGraphCard",
+    category: "blocks",
+    description: "Social media preview card for Open Graph metadata. Use in opengraph-image.tsx.",
+    keywords: ["open-graph", "social", "preview", "card", "meta", "share"],
+    useCases: [
+      "Social sharing previews",
+      "Link previews",
+      "Meta card generation",
+      "Marketing previews"
+    ],
+    dependencies: [],
+    props: {
+      title: { type: "string", default: "'Sage Design Engine'", description: "Main title text" },
+      description: { type: "string", description: "Subtitle text" },
+      variant: { type: "'primary' | 'secondary' | 'accent' | 'sage' | 'emerald' | 'gradient'", default: "'sage'", description: "Visual style variant" },
+      icon: { type: "ReactNode", description: "Custom logo or icon element" },
+      gradient: { type: "{ type: string; angle: number; colors: string[] }", description: 'Custom gradient config (variant="gradient")' },
+      primaryColor: { type: "string", description: "Override primary color (hex)" },
+      secondaryColor: { type: "string", description: "Override secondary color (hex)" },
+      accentColor: { type: "string", description: "Override accent color (hex)" }
+    },
+    example: `// In opengraph-image.tsx:
+export default function OGImage() {
+  return <OpenGraphCard title="My Page" description="A great description" variant="primary" />
+}`
   }
 };
 function getComponentsByCategory(category) {
@@ -758,13 +2209,13 @@ var server = new Server(
 var TOOLS = [
   {
     name: "list_components",
-    description: "List all available Sage UI components. Optionally filter by category (actions, forms, navigation, overlays, feedback, data-display, layout).",
+    description: "List all available Sage UI components. Optionally filter by category (core: actions, forms, navigation, overlays, feedback, data-display, layout; specialty: backgrounds, cursor, motion, blocks).",
     inputSchema: {
       type: "object",
       properties: {
         category: {
           type: "string",
-          description: "Filter by category: actions, forms, navigation, overlays, feedback, data-display, or layout",
+          description: "Filter by category. Core: actions, forms, navigation, overlays, feedback, data-display, layout. Specialty: backgrounds, cursor, motion, blocks.",
           enum: [
             "actions",
             "forms",
@@ -772,7 +2223,11 @@ var TOOLS = [
             "overlays",
             "feedback",
             "data-display",
-            "layout"
+            "layout",
+            "backgrounds",
+            "cursor",
+            "motion",
+            "blocks"
           ]
         }
       }
@@ -864,6 +2319,47 @@ function formatComponentDetails(component) {
 ${component.description}
 
 `;
+  const importParts = [component.name];
+  if (component.subComponents) {
+    importParts.push(...component.subComponents);
+  }
+  output += `## Import
+`;
+  output += `\`\`\`typescript
+import { ${importParts.join(", ")} } from '@thesage/ui';
+\`\`\`
+
+`;
+  if (component.props && Object.keys(component.props).length > 0) {
+    output += `## Props
+
+`;
+    output += `| Prop | Type | Default | Description |
+`;
+    output += `|------|------|---------|-------------|
+`;
+    Object.entries(component.props).forEach(([name, prop]) => {
+      const required = prop.required ? " **(required)**" : "";
+      const defaultVal = prop.default || "-";
+      output += `| ${name} | \`${prop.type}\` | ${defaultVal} | ${prop.description}${required} |
+`;
+    });
+    output += "\n";
+  }
+  if (component.subComponents && component.subComponents.length > 0) {
+    output += `## Sub-Components
+`;
+    output += component.subComponents.join(", ") + "\n\n";
+  }
+  if (component.example) {
+    output += `## Example
+`;
+    output += `\`\`\`tsx
+${component.example}
+\`\`\`
+
+`;
+  }
   output += `## Use Cases
 `;
   component.useCases.forEach((useCase) => {
@@ -871,9 +2367,6 @@ ${component.description}
 `;
   });
   output += "\n";
-  output += `## Keywords
-`;
-  output += component.keywords.join(", ") + "\n\n";
   if (component.dependencies.length > 0) {
     output += `## Dependencies
 `;
@@ -890,16 +2383,12 @@ ${component.description}
 
 `;
   }
-  output += `## Import
-`;
-  output += `\`\`\`typescript
-import { ${component.name} } from '@thesage/ui';
-\`\`\`
-
-`;
   output += `## Documentation
 `;
-  output += `View full documentation at: https://thesage.dev/#${component.category}/${component.name.toLowerCase().replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()}
+  output += `View full documentation at: https://thesage.dev/docs#${component.category}/${component.name.toLowerCase().replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()}
+`;
+  output += `
+Full API reference: https://thesage.dev/llms-full.txt
 `;
   return output;
 }