@loworbitstudio/visor 0.1.0 → 0.4.0

package/dist/visor-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.3.0",
-  "generated_at": "2026-04-13T18:22:40.356Z",
+  "version": "0.4.0",
+  "generated_at": "2026-04-21T17:12:43.539Z",
   "components": {
     "accessibility-specimen": {
       "category": "specimen",
@@ -220,13 +220,14 @@
           "default",
           "destructive",
           "success",
-          "warning"
+          "warning",
+          "info"
         ]
       },
       "props": [
         {
           "name": "variant",
-          "type": "'default' | 'destructive' | 'success' | 'warning'",
+          "type": "'default' | 'destructive' | 'success' | 'warning' | 'info'",
           "default": "default"
         }
       ],
@@ -334,13 +335,20 @@
           "default",
           "secondary",
           "outline",
-          "destructive"
+          "destructive",
+          "success",
+          "warning",
+          "info",
+          "filled-destructive",
+          "filled-success",
+          "filled-warning",
+          "filled-info"
         ]
       },
       "props": [
         {
           "name": "variant",
-          "type": "\"default\" | \"secondary\" | \"outline\" | \"destructive\"",
+          "type": "\"default\" | \"secondary\" | \"outline\" | \"destructive\" | \"success\" | \"warning\" | \"info\" | \"filled-destructive\" | \"filled-success\" | \"filled-warning\" | \"filled-info\"",
           "default": "\"default\""
         }
       ],
@@ -378,7 +386,7 @@
         "--text-success",
         "--text-warning"
       ],
-      "example": "<Badge variant=\"default\">Active</Badge>\n<Badge variant=\"secondary\">Draft</Badge>\n<Badge variant=\"outline\">v2.1.0</Badge>\n<Badge variant=\"destructive\">Error</Badge>\n"
+      "example": "<Badge variant=\"default\">Active</Badge>\n<Badge variant=\"secondary\">Draft</Badge>\n<Badge variant=\"outline\">v2.1.0</Badge>\n<Badge variant=\"destructive\">Error</Badge>\n<Badge variant=\"success\">Published</Badge>\n<Badge variant=\"warning\">Pending</Badge>\n<Badge variant=\"info\">Beta</Badge>\n<Badge variant=\"filled-destructive\">Critical</Badge>\n"
     },
     "banner": {
       "category": "feedback",
@@ -5908,621 +5916,1834 @@
         "--text-primary"
       ],
       "example": "<TypeSpecimen token=\"--font-size-xl\" label=\"xl\" sizePx={20} sampleText=\"Subsection heading\" />\n"
-    }
-  },
-  "blocks": {
-    "admin-dashboard": {
-      "category": "admin",
-      "description": "Drop-in admin overview composition — PageHeader, responsive stat grid, optional secondary region, and ActivityFeed with empty-state fallback. Composes existing admin compounds, nothing to configure.",
-      "components_used": [
-        "page-header",
-        "stat-card",
-        "activity-feed",
-        "empty-state"
-      ],
+    },
+    "deck-card-grid": {
+      "category": "deck",
+      "description": "CSS grid layout for decks that arranges card children in 2–5 columns with staggered entrance animations.",
       "when_to_use": [
-        "Landing page for an admin or back-office app",
-        "Overview-at-a-glance screens mixing KPIs and recent events",
-        "Any dashboard needing a title, metrics, and a recent-activity feed"
+        "Content slides displaying a grid of feature cards, team members, or value props",
+        "Any slide where multiple items should appear in equal-width columns with staggered animation"
       ],
       "when_not_to_use": [
-        "Data-heavy list or table pages (use admin-list-page)",
-        "Detail / edit screens for a single record (use admin-detail-drawer)",
-        "Settings forms (use admin-settings-page)"
-      ]
-    },
-    "admin-detail-drawer": {
-      "category": "admin",
-      "description": "Right-side slide-out panel for viewing or editing a single record. Composes Sheet with a sticky save/cancel footer, async save handler with pending state, an unsaved-changes guard powered by ConfirmDialog, and sm/md/lg/xl width variants.",
-      "components_used": [
-        "sheet",
-        "button",
-        "confirm-dialog"
+        "Outside of a <Slide> (stagger animation timing won't be synchronized)",
+        "Grids needing unequal column widths or complex alignment"
       ],
-      "when_to_use": [
-        "Inline editing of a single record from a list or dashboard",
-        "Click-a-row, edit-its-details-without-leaving-the-page patterns",
-        "Detail panels where protecting against accidental close is important"
+      "props": [
+        {
+          "name": "columns",
+          "type": "2 | 3 | 4 | 5",
+          "default": 3,
+          "description": "Number of equal-width columns"
+        }
       ],
-      "when_not_to_use": [
-        "Full-page single-record editors (use admin-tabbed-editor)",
-        "Multi-step forms (use admin-wizard)",
-        "Simple confirmation prompts (use ConfirmDialog directly)"
-      ]
-    },
-    "admin-list-page": {
-      "category": "admin",
-      "description": "CRUD list archetype composing PageHeader, FilterBar, DataTable, BulkActionBar, and EmptyState into a single drop-in page. Generic over row data type, supports controlled and uncontrolled search/selection/sorting/pagination, exposes a bulk actions slot that appears only when rows are selected.",
-      "components_used": [
-        "page-header",
-        "filter-bar",
-        "data-table",
-        "bulk-action-bar",
-        "empty-state"
+      "dependencies": [
+        "@loworbitstudio/visor-core"
       ],
+      "tokens_used": [],
+      "example": "<CardGrid columns={3}>\n  <FeatureCard title=\"Speed\" description=\"...\" />\n  <FeatureCard title=\"Quality\" description=\"...\" />\n  <FeatureCard title=\"Scale\" description=\"...\" />\n</CardGrid>\n"
+    },
+    "deck-carousel-gallery": {
+      "category": "deck",
+      "description": "Inline image gallery for slides that opens a full-screen lightbox on click. Renders images in an equal-width horizontal row.",
       "when_to_use": [
-        "List-all pages for users, orders, invoices, or projects",
-        "Any CRUD index view needing search, filters, and sortable/paginated rows",
-        "Pages that need bulk actions (archive, delete, export) on selected rows"
+        "Slides showcasing work samples, screenshots, or photos in a horizontal strip",
+        "Any slide where clicking an image should open it full-screen for closer inspection"
       ],
       "when_not_to_use": [
-        "Overview dashboards with KPIs and activity feeds (use admin-dashboard)",
-        "Single-record detail or edit screens (use admin-detail-drawer)",
-        "Settings or preferences forms (use admin-settings-page)"
-      ]
-    },
-    "admin-settings-page": {
-      "category": "admin",
-      "description": "Long scrollable settings archetype with labeled sections and an optional sticky left-side nav that sync-scrolls via intersection observer. Supports two mutually-exclusive modes — a single global sticky save/cancel footer (default) or per-section save/revert footer rows. Composes PageHeader, Separator, Heading, Text, Button, and ConfirmDialog.",
-      "components_used": [
-        "page-header",
-        "separator",
-        "heading",
-        "text",
-        "button",
-        "confirm-dialog"
+        "Long image sets (more than ~5 images causes the row to become too narrow)",
+        "Slides where images should be decorative only with no lightbox interaction"
+      ],
+      "props": [
+        {
+          "name": "slides",
+          "type": "GallerySlide[]",
+          "description": "Array of { src, alt, caption? } objects"
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core",
+        "lightbox"
       ],
+      "tokens_used": [],
+      "example": "<CarouselGallery\n  slides={[\n    { src: \"/work/a.jpg\", alt: \"Project Alpha\", caption: \"Alpha\" },\n    { src: \"/work/b.jpg\", alt: \"Project Beta\",  caption: \"Beta\" },\n    { src: \"/work/c.jpg\", alt: \"Project Gamma\", caption: \"Gamma\" },\n  ]}\n/>\n"
+    },
+    "deck-closing-slide": {
+      "category": "deck",
+      "description": "Dark closing slide with centered tagline, subtitle, divider, and optional body text. The standard last slide for presentations.",
       "when_to_use": [
-        "Application or workspace settings pages organized into labeled sections",
-        "Profile pages, account pages, billing pages, team pages — anywhere long scrolling form content needs wayfinding",
-        "Pages where some sections commit independently (per-section mode) or where all edits commit together (global mode)"
+        "Final slide of any deck (thank-you, call-to-action, or contact information)",
+        "Any deck that needs a simple, impactful closing screen"
       ],
       "when_not_to_use": [
-        "Editors where each tab replaces the previous panel entirely (use admin-tabbed-editor)",
-        "Inline single-record edits (use admin-detail-drawer)",
-        "Multi-step flows with a linear progression (use admin-wizard)"
-      ]
-    },
-    "admin-shell": {
-      "category": "admin",
-      "description": "Foundational admin layout with sidebar, topbar, and main content area. Slot-driven for logo, navigation, breadcrumbs, user menu, and status indicators.",
-      "components_used": [
-        "breadcrumb",
-        "dropdown-menu",
-        "sidebar"
+        "Mid-deck transitions (use a standard dark Slide instead)",
+        "Closing slides that require complex custom content (build from Slide directly)"
+      ],
+      "props": [
+        {
+          "name": "id",
+          "type": "string",
+          "default": "s-close"
+        },
+        {
+          "name": "tagline",
+          "type": "string",
+          "default": "Thank you."
+        },
+        {
+          "name": "subtitle",
+          "type": "string",
+          "description": "Short line below the tagline"
+        },
+        {
+          "name": "body",
+          "type": "string",
+          "description": "Paragraph below the divider"
+        },
+        {
+          "name": "extra",
+          "type": "ReactNode",
+          "description": "Custom content rendered below body (CTAs, links, etc.)"
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core"
       ],
+      "tokens_used": [],
+      "example": "<ClosingSlide\n  tagline=\"Let's build something.\"\n  subtitle=\"We'd love to hear from you.\"\n  body=\"hello@loworbit.studio\"\n/>\n"
+    },
+    "deck-concept-slide": {
+      "category": "deck",
+      "description": "Slide with a looping background video and overlay, for showcasing concepts, product demos, or motion design. Content is layered above the video.",
       "when_to_use": [
-        "Internal admin tools and back-office apps",
-        "Dashboards with persistent side navigation",
-        "CRUD-heavy applications needing a consistent chrome",
-        "Any multi-page admin area requiring breadcrumbs and a user menu"
+        "Slides where a video loop reinforces the concept being presented",
+        "Product or feature showcases where motion adds context",
+        "Visual storytelling slides where a static image would be insufficient"
       ],
       "when_not_to_use": [
-        "Public marketing pages (use hero-section, cta-section, footer-section)",
-        "Authentication screens (use login-form)",
-        "Full-bleed canvas experiences without chrome"
-      ]
-    },
-    "admin-tabbed-editor": {
-      "category": "admin",
-      "description": "Full-page editor with horizontal tabs, tab-scoped content panels, and a sticky save/cancel footer. Composes PageHeader, Tabs, Button, and ConfirmDialog. Tab switching and cancel are protected by an unsaved-changes guard, save supports async with pending state.",
-      "components_used": [
-        "page-header",
-        "tabs",
-        "button",
-        "confirm-dialog"
+        "Slides where the video is primary content (use Slide with an embedded player)",
+        "Environments where autoplay may be blocked (the video is decorative, content still renders)"
+      ],
+      "props": [
+        {
+          "name": "id",
+          "type": "string",
+          "description": "Unique slide identifier"
+        },
+        {
+          "name": "theme",
+          "type": "'light' | 'dark'",
+          "default": "light"
+        },
+        {
+          "name": "video",
+          "type": "string",
+          "description": "Video source URL (mp4)"
+        },
+        {
+          "name": "poster",
+          "type": "string",
+          "description": "Poster image shown before video loads"
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core"
       ],
+      "tokens_used": [],
+      "example": "<ConceptSlide\n  id=\"s-concept\"\n  theme=\"dark\"\n  video=\"/video/demo.mp4\"\n  poster=\"/video/demo-poster.jpg\"\n>\n  <SlideHeader subtitle=\"Concept\" title=\"Reimagined\" />\n</ConceptSlide>\n"
+    },
+    "deck-context": {
+      "category": "deck",
+      "description": "React context provider that exposes slide navigation methods (goTo, navigateTo) to all descendants within a deck.",
       "when_to_use": [
-        "Full-page record editors where settings span multiple logical sections",
-        "Profile editors, settings pages, resource configuration pages",
-        "Any editor that benefits from a single global save across multiple tab panels"
+        "Building custom deck controls that need to programmatically navigate slides",
+        "Creating slide-aware child components that respond to navigation events",
+        "Any component inside <DeckLayout> that calls useDeck()"
       ],
       "when_not_to_use": [
-        "Inline single-record edits (use admin-detail-drawer)",
-        "Multi-step forms with a linear progression (use admin-wizard)",
-        "Pages without meaningful grouping (use a plain form)"
-      ]
-    },
-    "admin-wizard": {
-      "category": "admin",
-      "description": "Guided multi-step flow composing PageHeader, Stepper, and Button into a drop-in wizard with per-step async validation, final submit handler, horizontal or vertical stepper orientation, optional click-to-jump stepper navigation to completed steps, and a cancel guard via ConfirmDialog. Only the active step's content is mounted.",
-      "components_used": [
-        "page-header",
-        "stepper",
-        "button",
-        "confirm-dialog"
+        "Outside of a <DeckLayout> wrapper (useDeck() will throw)",
+        "Direct consumers of deck state — prefer useDeck() hook instead of referencing the context directly"
       ],
+      "props": [
+        {
+          "name": "value",
+          "type": "DeckContextValue",
+          "description": "{ goTo: (index: number) => void; navigateTo: (id: string) => void }"
+        }
+      ],
+      "dependencies": [
+        "react",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [],
+      "example": "// Consumed via useDeck() inside any child of <DeckLayout>\nfunction MyControl() {\n  const { goTo, navigateTo } = useDeck()\n  return <button onClick={() => navigateTo(\"s-intro\")}>Go to Intro</button>\n}\n"
+    },
+    "deck-footer": {
+      "category": "deck",
+      "description": "Dark closing footer slide with brand lockup, optional link columns, and a copyright bar. Appears as the last scrollable section in a deck.",
       "when_to_use": [
-        "Multi-step create flows — onboarding, account setup, content creation",
-        "Guided configuration where each step depends on decisions made earlier",
-        "Any linear progression where the user should see clear progress and can step back to revise earlier answers"
+        "As the final section of a deck (after the last content slide or ClosingSlide)",
+        "Decks that need categorized navigation links below the closing content",
+        "Branded presentations requiring a footer with company identity and copyright"
       ],
       "when_not_to_use": [
-        "Long scrollable settings pages (use admin-settings-page)",
-        "Editors where each tab is an independent view of the same record (use admin-tabbed-editor)",
-        "Single-record inline edits (use admin-detail-drawer)"
-      ]
-    },
-    "configuration-panel": {
-      "category": "configuration",
-      "description": "A floating, glassmorphic configuration panel for organizing controls into labeled sections. Supports collapse animation, positional anchoring, and responsive stacking. Composed from Visor form components.",
-      "components_used": [
-        "separator"
+        "Decks built with DeckRenderer (showFooter=true handles this automatically)",
+        "Short decks where a full branded footer would feel disproportionate"
+      ],
+      "props": [
+        {
+          "name": "description",
+          "type": "string",
+          "description": "Brand tagline or short company description"
+        },
+        {
+          "name": "columns",
+          "type": "DeckFooterColumn[]",
+          "description": "Optional link columns — each { title, links: { label, slide?, href?, accent? }[] }"
+        },
+        {
+          "name": "brandName",
+          "type": "string",
+          "default": "Low Orbit Studio"
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--color-accent",
+        "--color-primary-900",
+        "--motion-duration-fast",
+        "--motion-easing-standard",
+        "--spacing-1",
+        "--spacing-12",
+        "--spacing-4",
+        "--spacing-6",
+        "--spacing-8",
+        "--text-on-dark",
+        "--text-on-dark-secondary"
       ],
+      "example": "<DeckFooter\n  description=\"Design systems for the modern web.\"\n  brandName=\"Low Orbit Studio\"\n  columns={[\n    {\n      title: \"Sections\",\n      links: [\n        { label: \"Vision\",   slide: \"s-vision\" },\n        { label: \"Services\", slide: \"s-services\" },\n      ],\n    },\n  ]}\n/>\n"
+    },
+    "deck-layout": {
+      "category": "deck",
+      "description": "Full-viewport scroll-snapping container that orchestrates keyboard navigation, wheel navigation, intersection-based animation, and dot-nav rendering for a deck of slides.",
       "when_to_use": [
-        "Building control panels for interactive visualizations",
-        "Settings or configuration UIs that float over content",
-        "Any grouped-controls panel needing glassmorphic styling"
+        "Wrapping all <Slide> and <DeckFooter> components in a presentation",
+        "Building a custom deck layout without using DeckRenderer"
       ],
       "when_not_to_use": [
-        "Static forms that live inline in page flow (use Card instead)",
-        "Simple single-control toggles (use individual form components)"
-      ]
-    },
-    "cta-section": {
-      "category": "marketing",
-      "description": "A centered call-to-action section composing Heading, Text, and Button.",
-      "components_used": [
-        "heading",
-        "text",
-        "button"
+        "When DeckRenderer covers your needs (it wraps DeckLayout automatically)",
+        "Standard page layouts — this component is presentation-only"
+      ],
+      "props": [
+        {
+          "name": "slideTitles",
+          "type": "string[]",
+          "description": "Slide titles passed to DotNav for tooltip labels"
+        },
+        {
+          "name": "controls",
+          "type": "(props: { containerRef, currentIndex, variant }) => ReactNode",
+          "description": "Optional render prop for custom controls (e.g., export button)"
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core"
       ],
+      "tokens_used": [],
+      "example": "<DeckLayout slideTitles={[\"Intro\", \"Problem\", \"Solution\", \"Thank You\"]}>\n  <Slide id=\"s-intro\" theme=\"dark\"><HeroSlide ... /></Slide>\n  <Slide id=\"s-problem\" theme=\"light\"><SlideHeader ... /></Slide>\n  <Slide id=\"s-solution\" theme=\"light\"><SlideHeader ... /></Slide>\n  <ClosingSlide />\n  <DeckFooter description=\"...\" />\n</DeckLayout>\n"
+    },
+    "deck-renderer": {
+      "category": "deck",
+      "description": "High-level declarative deck builder. Accepts a DeckRegistry configuration and renders the full slide stack with optional TOC slide, footer, and fullscreen mode.",
       "when_to_use": [
-        "Marketing landing pages",
-        "Conversion sections",
-        "Upgrade prompts"
+        "Building a complete presentation from a declarative registry config",
+        "Decks that need auto-generated TOC slides or footer sections",
+        "Presentations that should support fullscreen mode with a trigger button"
       ],
       "when_not_to_use": [
-        "Inline CTAs within content (use Button directly)"
-      ]
-    },
-    "design-system-deck": {
-      "category": "documentation",
-      "description": "A complete, registry-driven design system presentation deck. Composes all slide components into a DeckRenderer with TOC, dot navigation, keyboard nav, and fullscreen support. Responds dynamically to the active theme.",
-      "components_used": [
-        "alert",
-        "badge",
-        "button",
-        "card",
-        "checkbox",
-        "deck-renderer",
-        "heading",
-        "input",
-        "label",
-        "progress",
-        "radio-group",
-        "select",
-        "separator",
-        "slide",
-        "slide-header",
-        "switch",
-        "tabs",
-        "text",
-        "toggle-group"
+        "Decks that require fully custom slide ordering or non-registry components (use DeckLayout directly)",
+        "When you need fine-grained control over every slide's position in the sequence"
       ],
-      "when_to_use": [
-        "Presenting a design system as a navigable deck",
-        "Previewing a theme's full token coverage in slide format",
-        "Design system documentation and onboarding"
+      "props": [
+        {
+          "name": "registry",
+          "type": "DeckRegistry",
+          "description": "Declarative slide registry: { description, slides: SlideEntry[], sections: DeckSection[] }"
+        },
+        {
+          "name": "showTOC",
+          "type": "boolean",
+          "default": false,
+          "description": "Insert an auto-generated TOC slide after the first slide"
+        },
+        {
+          "name": "tocImage",
+          "type": "string",
+          "description": "Optional background image for the TOC slide"
+        },
+        {
+          "name": "showFooter",
+          "type": "boolean",
+          "default": true
+        },
+        {
+          "name": "brandName",
+          "type": "string",
+          "description": "Brand name for the footer (default \"Low Orbit Studio\")"
+        },
+        {
+          "name": "fullscreen",
+          "type": "boolean",
+          "default": false,
+          "description": "Wrap the deck in a FullscreenOverlay with a trigger button"
+        },
+        {
+          "name": "fullscreenLabel",
+          "type": "string",
+          "default": "Fullscreen"
+        }
       ],
-      "when_not_to_use": [
-        "Production user-facing pages",
-        "When a flat specimen view is preferred (use design-system-specimen instead)"
-      ]
-    },
-    "design-system-specimen": {
-      "category": "documentation",
-      "description": "Live interactive showcase of the full Visor token system and component library. Responds dynamically to the active theme.",
-      "components_used": [
-        "alert",
-        "badge",
-        "button",
-        "card",
-        "checkbox",
-        "heading",
-        "input",
-        "label",
-        "progress",
-        "radio-group",
-        "select",
-        "separator",
-        "slider",
-        "switch",
-        "tabs",
-        "text",
-        "textarea",
-        "toggle-group"
+      "dependencies": [
+        "@loworbitstudio/visor-core"
       ],
-      "when_to_use": [
-        "Previewing a theme's full token coverage",
-        "Validating design system consistency across components",
-        "Design system documentation and onboarding"
+      "tokens_used": [
+        "--border-default",
+        "--border-hover",
+        "--focus-ring-color",
+        "--focus-ring-offset",
+        "--focus-ring-width",
+        "--font-size-sm",
+        "--motion-duration-fast",
+        "--motion-easing-default",
+        "--radius-md",
+        "--spacing-2",
+        "--spacing-4",
+        "--surface-card",
+        "--surface-card-hover",
+        "--text-primary"
       ],
-      "when_not_to_use": [
-        "Production user-facing pages"
-      ]
+      "example": "const registry: DeckRegistry = {\n  description: \"Low Orbit Studio — 2026 Overview\",\n  slides: [\n    { id: \"s-hero\",     title: \"Intro\",    component: HeroSlide   },\n    { id: \"s-services\", title: \"Services\", component: ServicesSlide },\n  ],\n  sections: [],\n}\n\n<DeckRenderer registry={registry} showTOC showFooter fullscreen />\n"
     },
-    "features-grid": {
-      "category": "marketing",
-      "description": "A responsive grid of feature cards with icons, titles, and descriptions. Demonstrates Card + icon composition in a configurable grid layout.",
-      "components_used": [
-        "card",
-        "heading",
-        "text"
-      ],
+    "deck-dot-nav": {
+      "category": "deck",
+      "description": "Fixed-position dot navigation indicator for decks. Shows one dot per slide with hover tooltips and keyboard-accessible click targets.",
       "when_to_use": [
-        "Product feature showcases",
-        "Service offering grids",
-        "Capability overviews"
+        "Inside <DeckLayout> as the primary slide position indicator",
+        "Any deck that needs visible slide progress with tooltip labels"
       ],
       "when_not_to_use": [
-        "Icon-only grids without descriptions (use icon-grid specimen)",
-        "Single feature highlights"
-      ]
-    },
-    "footer-section": {
-      "category": "marketing",
-      "description": "A multi-column responsive footer with link groups, logo area, and copyright.",
-      "components_used": [
-        "heading",
-        "text",
-        "separator"
-      ],
-      "when_to_use": [
-        "Website footers",
-        "Landing page footers",
-        "App marketing site footers"
+        "Outside of a deck (dots are meaningless without a scroll-snap container)",
+        "Decks with more than ~12 slides (dots become visually crowded)"
       ],
-      "when_not_to_use": [
-        "In-app footers (typically minimal)",
-        "Presentation footers (use deck-footer)"
-      ]
-    },
-    "hero-section": {
-      "category": "marketing",
-      "description": "A full-width hero section with background media support, heading, subheading, and call-to-action button.",
-      "components_used": [
-        "heading",
-        "text",
-        "button"
+      "props": [
+        {
+          "name": "slideCount",
+          "type": "number",
+          "description": "Total number of slides"
+        },
+        {
+          "name": "currentIndex",
+          "type": "number",
+          "description": "Zero-based index of the active slide"
+        },
+        {
+          "name": "onDotClick",
+          "type": "(index: number) => void",
+          "description": "Callback when a dot is clicked"
+        },
+        {
+          "name": "variant",
+          "type": "'light' | 'dark'",
+          "default": "light"
+        },
+        {
+          "name": "titles",
+          "type": "string[]",
+          "description": "Optional slide titles shown as tooltips on hover"
+        }
       ],
-      "when_to_use": [
-        "Marketing landing page hero",
-        "Product launch pages",
-        "App landing pages"
+      "dependencies": [
+        "@loworbitstudio/visor-core"
       ],
-      "when_not_to_use": [
-        "Presentation slides (use deck hero-slide)",
-        "Content sections without full-viewport height"
-      ]
+      "tokens_used": [],
+      "example": "<DotNav\n  slideCount={5}\n  currentIndex={0}\n  onDotClick={(i) => goTo(i)}\n  variant=\"dark\"\n  titles={[\"Intro\", \"Problem\", \"Solution\", \"Roadmap\", \"Thank You\"]}\n/>\n"
     },
-    "login-form": {
-      "category": "authentication",
-      "description": "A login form block using Visor form components (Button, Input, Label, Card).",
-      "components_used": [
-        "button",
-        "input",
-        "field",
-        "card"
-      ],
+    "deck-hero-slide": {
+      "category": "deck",
+      "description": "Full-viewport opening slide with badge, animated title, subtitle, and divider. Supports hero image overlay and split logo layout.",
       "when_to_use": [
-        "Authentication pages",
-        "Sign-in screens",
-        "Demo login flows"
+        "First slide of a presentation deck (title / opening)",
+        "Any slide that functions as a visual cover with a large heading and minimal body text",
+        "Brand presentations where a logo lockup is needed alongside text (split layout)"
       ],
       "when_not_to_use": [
-        "Registration forms (extend with additional fields)",
-        "OAuth-only flows with no email/password fields"
-      ]
-    },
-    "pricing-section": {
-      "category": "marketing",
-      "description": "A responsive pricing tier grid with feature lists, highlighted plan, and per-tier CTAs.",
-      "components_used": [
-        "card",
-        "badge",
-        "button",
-        "separator",
-        "heading",
-        "text"
-      ],
-      "when_to_use": [
-        "SaaS pricing pages",
-        "Product comparison grids",
-        "Subscription tier displays"
+        "Mid-deck content slides (use Slide + SlideHeader instead)",
+        "Slides with more than a short tagline and subtitle"
       ],
-      "when_not_to_use": [
-        "Single product pricing (use Card directly)",
-        "Feature comparison tables without pricing"
-      ]
-    },
-    "sphere-playground": {
-      "category": "visual-elements",
-      "description": "An interactive demo composing the Sphere visualization with a Configuration Panel for real-time parameter control. The signature showcase for Visual Elements.",
-      "components_used": [
-        "sphere",
-        "configuration-panel",
-        "slider-control",
-        "toggle-group"
+      "props": [
+        {
+          "name": "id",
+          "type": "string",
+          "description": "Unique slide identifier"
+        },
+        {
+          "name": "badge",
+          "type": "string",
+          "description": "Short label displayed above the title (e.g. company name or date)"
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "description": "Main heading (mutually exclusive with titleContent)"
+        },
+        {
+          "name": "titleContent",
+          "type": "ReactNode",
+          "description": "Custom JSX heading (overrides title string)"
+        },
+        {
+          "name": "subtitle",
+          "type": "string",
+          "description": "Tagline below the title"
+        },
+        {
+          "name": "heroImage",
+          "type": "string",
+          "description": "URL for a full-bleed background image with overlay"
+        },
+        {
+          "name": "logo",
+          "type": "string",
+          "description": "Logo image URL (activates split layout when heroImage is absent)"
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "description": "Optional short description paragraph"
+        }
       ],
-      "when_to_use": [
-        "Showcasing the Sphere component with interactive controls",
-        "Building immersive GPU-accelerated visual demos",
-        "Demonstrating Visor's visual element capabilities"
+      "dependencies": [
+        "@loworbitstudio/visor-core"
       ],
-      "when_not_to_use": [
-        "Embedding a sphere without controls — use the Sphere component directly",
-        "Building a custom control panel — use ConfigurationPanel independently"
-      ]
+      "tokens_used": [],
+      "example": "<HeroSlide\n  id=\"s-hero\"\n  badge=\"Low Orbit Studio\"\n  title=\"Building the Future\"\n  subtitle=\"Design systems that scale.\"\n  heroImage=\"/images/hero-bg.jpg\"\n/>\n"
     },
-    "steps-section": {
-      "category": "marketing",
-      "description": "A numbered process section with auto-numbered steps and connector lines. Suitable for \"how it works\" sections and onboarding flows.",
-      "components_used": [
-        "heading",
-        "text"
-      ],
+    "slide": {
+      "category": "deck",
+      "description": "Full-viewport slide section with theme, layout mode, hero image, and background image support. The fundamental building block of every deck.",
       "when_to_use": [
-        "How it works sections",
-        "Onboarding flow overviews",
-        "Process explanations"
+        "Every slide in a presentation deck",
+        "Slides with dark or light themes requiring theme-scoped children",
+        "Hero slides with a full-bleed background image and overlay",
+        "Photo-mode slides with a full-bleed image behind content"
       ],
       "when_not_to_use": [
-        "Detailed multi-step wizards (use stepper/form)",
-        "Vertical timelines with dates (use timeline component)"
-      ]
-    },
-    "testimonial-section": {
-      "category": "marketing",
-      "description": "A social proof section with testimonial quotes, avatars, and attribution. Supports single centered layout or responsive grid for multiple testimonials.",
-      "components_used": [
-        "card",
-        "avatar",
-        "text",
-        "heading",
-        "separator"
+        "Outside of a <DeckLayout> (keyboard navigation and scroll snapping won't function)",
+        "Standalone page sections not part of a deck presentation"
+      ],
+      "variants": {
+        "theme": [
+          "light",
+          "dark"
+        ],
+        "layout": [
+          "default",
+          "center",
+          "flush",
+          "hero",
+          "photo",
+          "bgImage"
+        ]
+      },
+      "props": [
+        {
+          "name": "id",
+          "type": "string",
+          "description": "Unique slide identifier used for navigateTo() deep-linking"
+        },
+        {
+          "name": "theme",
+          "type": "'light' | 'dark'",
+          "default": "light"
+        },
+        {
+          "name": "dotNavTheme",
+          "type": "'light' | 'dark'",
+          "description": "Overrides dot-nav color detection independently of slide theme"
+        },
+        {
+          "name": "center",
+          "type": "boolean",
+          "default": false,
+          "description": "Center all content vertically and horizontally"
+        },
+        {
+          "name": "flush",
+          "type": "boolean",
+          "default": false,
+          "description": "Remove default padding"
+        },
+        {
+          "name": "hero",
+          "type": "boolean",
+          "default": false,
+          "description": "Enable hero image mode with content layered above"
+        },
+        {
+          "name": "heroImage",
+          "type": "string",
+          "description": "URL for the hero background image (requires hero=true)"
+        },
+        {
+          "name": "bgImage",
+          "type": "string",
+          "description": "URL for a full-bleed background image"
+        },
+        {
+          "name": "photo",
+          "type": "boolean",
+          "default": false,
+          "description": "Full-bleed photo mode"
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--color-primary-900",
+        "--motion-duration-normal",
+        "--motion-easing-standard",
+        "--surface-page",
+        "--text-on-dark",
+        "--text-primary"
       ],
+      "example": "<Slide id=\"s-intro\" theme=\"dark\" hero heroImage=\"/hero.jpg\">\n  <SlideHeader subtitle=\"Welcome\" title=\"Our Vision\" />\n</Slide>\n"
+    },
+    "deck-slide-header": {
+      "category": "deck",
+      "description": "Slide section header with animated subtitle, title, and optional description. Used at the top of content slides to establish section context.",
       "when_to_use": [
-        "Customer testimonials",
-        "Social proof sections",
-        "Review showcases"
+        "Opening content slides where a section title and subtitle are needed",
+        "Any slide that requires a consistent heading hierarchy with staggered entrance animations"
       ],
       "when_not_to_use": [
-        "Product reviews with ratings (extend with star component)",
-        "User-generated content feeds"
-      ]
-    }
-  },
-  "hooks": {
-    "use-media-query": {
-      "description": "SSR-safe hook that returns whether a CSS media query matches."
-    },
-    "use-debounce": {
-      "description": "Debounces a value by delaying updates until after a specified delay. Useful for search inputs and high-frequency events."
-    },
-    "use-click-outside": {
-      "description": "Fires a callback when a click or touch event occurs outside the referenced element. Useful for closing dropdowns and popovers."
-    },
-    "use-currency": {
-      "description": "Detects user locale and returns currency symbol and price formatter for USD, EUR, and GBP."
-    },
-    "use-local-storage": {
-      "description": "Persists state to localStorage with SSR safety, functional updates, and cross-tab synchronisation."
-    },
-    "use-intersection-observer": {
-      "description": "Tracks whether an element is visible within the viewport using IntersectionObserver. Supports one-shot mode for lazy loading."
-    },
-    "use-keyboard-shortcut": {
-      "description": "Fires a callback when a specific keyboard shortcut is pressed, with support for modifier keys (Meta, Ctrl, Shift, Alt)."
-    },
-    "use-focus-trap": {
-      "description": "Traps keyboard focus within a container element. Used for accessible modals, drawers, and dialogs."
-    },
-    "use-previous": {
-      "description": "Returns the previous value of a variable from the last render. Useful for comparing values across renders."
-    },
-    "use-boolean": {
-      "description": "Manages a boolean state with stable toggle, setTrue, and setFalse helpers. Useful for open/close and show/hide patterns."
-    },
-    "use-intersection-animation": {
-      "description": "Observes section visibility via IntersectionObserver and updates the active index for scroll-driven animations."
+        "Hero slides (use HeroSlide which has its own heading layout)",
+        "Slides where the heading needs custom layout or typography"
+      ],
+      "props": [
+        {
+          "name": "subtitle",
+          "type": "string",
+          "description": "Section label displayed above the title"
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "description": "Main heading text"
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "description": "Optional paragraph below the title"
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [],
+      "example": "<SlideHeader\n  subtitle=\"Phase 1\"\n  title=\"Discovery & Research\"\n  description=\"Understanding the problem space before committing to solutions.\"\n/>\n"
     },
-    "use-keyboard-nav": {
-      "description": "Handles Arrow Up/Down and Home/End keyboard navigation to move between indexed sections or slides."
+    "slide-theme-context": {
+      "category": "deck",
+      "description": "React context provider that propagates the active slide theme (\"light\" | \"dark\") to child components within a slide.",
+      "when_to_use": [
+        "Building slide sub-components that need to adapt styling to the parent slide's theme",
+        "Any component inside a <Slide> that calls useSlideTheme()"
+      ],
+      "when_not_to_use": [
+        "Outside of a <Slide> wrapper (returns \"light\" as default, not an error, but context is meaningless)",
+        "Choosing between light/dark themes — that is controlled by the slide's theme prop"
+      ],
+      "props": [
+        {
+          "name": "theme",
+          "type": "'light' | 'dark'",
+          "description": "Theme variant propagated to all slide descendants"
+        }
+      ],
+      "dependencies": [
+        "react",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [],
+      "example": "// Consumed via useSlideTheme() inside any child of <Slide>\nfunction SlideCard() {\n  const theme = useSlideTheme()\n  return <div data-theme={theme}>...</div>\n}\n"
     },
-    "use-slide-engine": {
-      "description": "Provides smooth programmatic scrolling between indexed sections with a scrolling-lock guard to prevent observer conflicts."
+    "deck-toc-slide": {
+      "category": "deck",
+      "description": "Auto-generated table of contents slide with clickable section + item links for deep navigation. Rendered automatically by DeckRenderer when showTOC is true.",
+      "when_to_use": [
+        "Decks with 3+ sections where an upfront overview helps orientation",
+        "Any deck where users need to jump non-linearly to specific slides"
+      ],
+      "when_not_to_use": [
+        "Short decks (under 6 slides) where a TOC adds noise",
+        "Decks built with DeckRenderer (showTOC=true handles this automatically)"
+      ],
+      "props": [
+        {
+          "name": "sections",
+          "type": "TOCSection[]",
+          "description": "Array of { section: string; items: { id: string; title: string }[] }"
+        },
+        {
+          "name": "backgroundImage",
+          "type": "string",
+          "description": "Optional background image (activates dark theme on the slide)"
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "default": "s-toc"
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [],
+      "example": "<TOCSlide\n  sections={[\n    {\n      section: \"Strategy\",\n      items: [\n        { id: \"s-vision\", title: \"Vision\" },\n        { id: \"s-goals\",  title: \"Goals\" },\n      ],\n    },\n  ]}\n/>\n"
     },
-    "use-wheel-nav": {
-      "description": "Converts vertical wheel events into discrete index-based navigation with debounced throttling."
+    "sphere": {
+      "category": "visual-elements",
+      "description": "GPU-accelerated particle sphere visualization with 256K particles, custom GLSL shaders, 6 geometry modes, 5 color schemes, and think-mode animation effects.",
+      "when_to_use": [
+        "Ambient background visualization (hero sections, landing pages)",
+        "AI thinking/processing indicator",
+        "Decorative visual element on dark backgrounds",
+        "Data visualization with particle-based aesthetics"
+      ],
+      "when_not_to_use": [
+        "Small UI components or icons (too heavy — requires Three.js)",
+        "Pages where bundle size is critical (~150KB gzipped for Three.js)",
+        "Content-heavy pages where animation would distract"
+      ],
+      "props": [
+        {
+          "name": "mode",
+          "type": "'sphere' | 'curl' | 'turing' | 'lorenz' | 'tendrils'",
+          "default": "sphere",
+          "description": "Geometry mode for particle distribution"
+        },
+        {
+          "name": "colorScheme",
+          "type": "'solar' | 'aqua' | 'ember' | 'aurora' | 'ghost'",
+          "default": "solar",
+          "description": "Named color scheme"
+        },
+        {
+          "name": "colors",
+          "type": "GradientColors",
+          "description": "Custom 5-stop gradient (overrides colorScheme)"
+        },
+        {
+          "name": "particleCount",
+          "type": "number",
+          "default": 256000
+        },
+        {
+          "name": "speed",
+          "type": "number",
+          "default": 1,
+          "description": "Animation speed multiplier"
+        },
+        {
+          "name": "waves",
+          "type": "number",
+          "default": 1,
+          "description": "Wave displacement multiplier"
+        },
+        {
+          "name": "dotSize",
+          "type": "number",
+          "default": 1,
+          "description": "Particle dot size multiplier"
+        },
+        {
+          "name": "blur",
+          "type": "number",
+          "default": 0.5,
+          "description": "Softness (0 = hard dots, 1 = full glow)"
+        },
+        {
+          "name": "thinkIntensity",
+          "type": "number",
+          "default": 0,
+          "description": "Think-mode intensity (0-1)"
+        },
+        {
+          "name": "thinkEffects",
+          "type": "SphereThinkEffects",
+          "description": "Which think-mode effects are enabled"
+        },
+        {
+          "name": "orbitControls",
+          "type": "boolean",
+          "default": true,
+          "description": "Enable drag-to-rotate"
+        },
+        {
+          "name": "autoRotate",
+          "type": "boolean",
+          "default": true
+        }
+      ],
+      "dependencies": [
+        "three",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [],
+      "example": "<Sphere\n  mode=\"sphere\"\n  colorScheme=\"solar\"\n  speed={1}\n  style={{ width: \"100%\", height: \"400px\" }}\n/>\n"
     }
   },
-  "patterns": {
-    "auth-flow": {
-      "description": "Login, registration, and password recovery pages sharing a centered card layout.",
+  "blocks": {
+    "admin-dashboard": {
+      "category": "admin",
+      "description": "Drop-in admin overview composition — PageHeader, responsive stat grid, optional secondary region, and ActivityFeed with empty-state fallback. Composes existing admin compounds, nothing to configure.",
       "components_used": [
-        "card",
-        "input",
-        "button",
-        "field",
-        "alert",
-        "tabs"
+        "page-header",
+        "stat-card",
+        "activity-feed",
+        "empty-state"
       ],
       "when_to_use": [
-        "Sign-in and sign-up pages",
-        "Forgot password and reset password flows",
-        "Invitation acceptance screens"
+        "Landing page for an admin or back-office app",
+        "Overview-at-a-glance screens mixing KPIs and recent events",
+        "Any dashboard needing a title, metrics, and a recent-activity feed"
+      ],
+      "when_not_to_use": [
+        "Data-heavy list or table pages (use admin-list-page)",
+        "Detail / edit screens for a single record (use admin-detail-drawer)",
+        "Settings forms (use admin-settings-page)"
       ]
     },
-    "crud-table": {
-      "description": "Data table with row actions, confirmation dialog, and pagination for managing collections of records.",
+    "admin-detail-drawer": {
+      "category": "admin",
+      "description": "Right-side slide-out panel for viewing or editing a single record. Composes Sheet with a sticky save/cancel footer, async save handler with pending state, an unsaved-changes guard powered by ConfirmDialog, and sm/md/lg/xl width variants.",
       "components_used": [
-        "table",
+        "sheet",
         "button",
-        "dropdown-menu",
-        "dialog",
-        "alert",
-        "pagination",
-        "badge"
+        "confirm-dialog"
       ],
       "when_to_use": [
-        "Admin pages listing and managing resources (users, orders, products)",
-        "Any collection view with create, read, update, delete operations",
-        "Data tables needing row-level actions and bulk operations"
+        "Inline editing of a single record from a list or dashboard",
+        "Click-a-row, edit-its-details-without-leaving-the-page patterns",
+        "Detail panels where protecting against accidental close is important"
+      ],
+      "when_not_to_use": [
+        "Full-page single-record editors (use admin-tabbed-editor)",
+        "Multi-step forms (use admin-wizard)",
+        "Simple confirmation prompts (use ConfirmDialog directly)"
       ]
     },
-    "dashboard-layout": {
-      "description": "App shell with collapsible sidebar navigation, top navbar, and content area with cards and tabs.",
+    "admin-list-page": {
+      "category": "admin",
+      "description": "CRUD list archetype composing PageHeader, FilterBar, DataTable, BulkActionBar, and EmptyState into a single drop-in page. Generic over row data type, supports controlled and uncontrolled search/selection/sorting/pagination, exposes a bulk actions slot that appears only when rows are selected.",
       "components_used": [
-        "sidebar",
-        "navbar",
-        "card",
-        "tabs",
-        "separator",
-        "scroll-area"
+        "page-header",
+        "filter-bar",
+        "data-table",
+        "bulk-action-bar",
+        "empty-state"
       ],
       "when_to_use": [
-        "Admin dashboards and internal tools",
-        "Multi-section apps with persistent navigation",
-        "Content-heavy layouts needing sidebar + main area structure"
+        "List-all pages for users, orders, invoices, or projects",
+        "Any CRUD index view needing search, filters, and sortable/paginated rows",
+        "Pages that need bulk actions (archive, delete, export) on selected rows"
+      ],
+      "when_not_to_use": [
+        "Overview dashboards with KPIs and activity feeds (use admin-dashboard)",
+        "Single-record detail or edit screens (use admin-detail-drawer)",
+        "Settings or preferences forms (use admin-settings-page)"
       ]
     },
-    "data-table-with-filters": {
-      "description": "Filterable data table with a toolbar for search, category filters, and column sorting.",
+    "admin-settings-page": {
+      "category": "admin",
+      "description": "Long scrollable settings archetype with labeled sections and an optional sticky left-side nav that sync-scrolls via intersection observer. Supports two mutually-exclusive modes — a single global sticky save/cancel footer (default) or per-section save/revert footer rows. Composes PageHeader, Separator, Heading, Text, Button, and ConfirmDialog.",
       "components_used": [
-        "table",
-        "input",
-        "select",
+        "page-header",
+        "separator",
+        "heading",
+        "text",
         "button",
-        "badge",
+        "confirm-dialog"
+      ],
+      "when_to_use": [
+        "Application or workspace settings pages organized into labeled sections",
+        "Profile pages, account pages, billing pages, team pages — anywhere long scrolling form content needs wayfinding",
+        "Pages where some sections commit independently (per-section mode) or where all edits commit together (global mode)"
+      ],
+      "when_not_to_use": [
+        "Editors where each tab replaces the previous panel entirely (use admin-tabbed-editor)",
+        "Inline single-record edits (use admin-detail-drawer)",
+        "Multi-step flows with a linear progression (use admin-wizard)"
+      ]
+    },
+    "admin-shell": {
+      "category": "admin",
+      "description": "Foundational admin layout with sidebar, topbar, and main content area. Slot-driven for logo, navigation, breadcrumbs, user menu, and status indicators.",
+      "components_used": [
+        "breadcrumb",
         "dropdown-menu",
-        "pagination"
+        "sidebar"
       ],
       "when_to_use": [
-        "Data-heavy pages where users need to find specific records",
-        "Admin dashboards with sortable, filterable lists",
-        "Search result pages with faceted filtering"
+        "Internal admin tools and back-office apps",
+        "Dashboards with persistent side navigation",
+        "CRUD-heavy applications needing a consistent chrome",
+        "Any multi-page admin area requiring breadcrumbs and a user menu"
+      ],
+      "when_not_to_use": [
+        "Public marketing pages (use hero-section, cta-section, footer-section)",
+        "Authentication screens (use login-form)",
+        "Full-bleed canvas experiences without chrome"
       ]
     },
-    "empty-state": {
-      "description": "Placeholder shown when a page, list, or search has no content to display.",
+    "admin-tabbed-editor": {
+      "category": "admin",
+      "description": "Full-page editor with horizontal tabs, tab-scoped content panels, and a sticky save/cancel footer. Composes PageHeader, Tabs, Button, and ConfirmDialog. Tab switching and cancel are protected by an unsaved-changes guard, save supports async with pending state.",
       "components_used": [
-        "card",
+        "page-header",
+        "tabs",
         "button",
-        "heading",
-        "text"
+        "confirm-dialog"
       ],
       "when_to_use": [
-        "Empty lists or tables (no data yet)",
-        "Search results returning zero matches",
-        "First-time user onboarding (no content created yet)",
-        "Error states where content failed to load"
+        "Full-page record editors where settings span multiple logical sections",
+        "Profile editors, settings pages, resource configuration pages",
+        "Any editor that benefits from a single global save across multiple tab panels"
+      ],
+      "when_not_to_use": [
+        "Inline single-record edits (use admin-detail-drawer)",
+        "Multi-step forms with a linear progression (use admin-wizard)",
+        "Pages without meaningful grouping (use a plain form)"
       ]
     },
-    "form-with-validation": {
-      "description": "Standard form layout with field-level validation and submission handling.",
+    "admin-wizard": {
+      "category": "admin",
+      "description": "Guided multi-step flow composing PageHeader, Stepper, and Button into a drop-in wizard with per-step async validation, final submit handler, horizontal or vertical stepper orientation, optional click-to-jump stepper navigation to completed steps, and a cancel guard via ConfirmDialog. Only the active step's content is mounted.",
       "components_used": [
-        "field",
-        "input",
-        "label",
-        "textarea",
+        "page-header",
+        "stepper",
         "button",
-        "alert"
+        "confirm-dialog"
       ],
       "when_to_use": [
-        "Any form collecting user input (settings, profile, onboarding)",
-        "Forms needing inline validation feedback",
-        "Multi-field forms with consistent spacing and error display"
+        "Multi-step create flows — onboarding, account setup, content creation",
+        "Guided configuration where each step depends on decisions made earlier",
+        "Any linear progression where the user should see clear progress and can step back to revise earlier answers"
+      ],
+      "when_not_to_use": [
+        "Long scrollable settings pages (use admin-settings-page)",
+        "Editors where each tab is an independent view of the same record (use admin-tabbed-editor)",
+        "Single-record inline edits (use admin-detail-drawer)"
       ]
     },
-    "settings-page": {
-      "description": "Multi-section settings page with sidebar navigation, grouped form fields, and save actions.",
+    "configuration-panel": {
+      "category": "configuration",
+      "description": "A floating, glassmorphic configuration panel for organizing controls into labeled sections. Supports collapse animation, positional anchoring, and responsive stacking. Composed from Visor form components.",
+      "components_used": [
+        "separator"
+      ],
+      "when_to_use": [
+        "Building control panels for interactive visualizations",
+        "Settings or configuration UIs that float over content",
+        "Any grouped-controls panel needing glassmorphic styling"
+      ],
+      "when_not_to_use": [
+        "Static forms that live inline in page flow (use Card instead)",
+        "Simple single-control toggles (use individual form components)"
+      ]
+    },
+    "cta-section": {
+      "category": "marketing",
+      "description": "A centered call-to-action section composing Heading, Text, and Button.",
+      "components_used": [
+        "heading",
+        "text",
+        "button"
+      ],
+      "when_to_use": [
+        "Marketing landing pages",
+        "Conversion sections",
+        "Upgrade prompts"
+      ],
+      "when_not_to_use": [
+        "Inline CTAs within content (use Button directly)"
+      ]
+    },
+    "design-system-deck": {
+      "category": "documentation",
+      "description": "A complete, registry-driven design system presentation deck. Composes all slide components into a DeckRenderer with TOC, dot navigation, keyboard nav, and fullscreen support. Responds dynamically to the active theme.",
       "components_used": [
+        "alert",
+        "badge",
+        "button",
         "card",
+        "checkbox",
+        "deck-renderer",
+        "heading",
         "input",
-        "textarea",
+        "label",
+        "progress",
+        "radio-group",
         "select",
+        "separator",
+        "slide",
+        "slide-header",
         "switch",
+        "tabs",
+        "text",
+        "toggle-group"
+      ],
+      "when_to_use": [
+        "Presenting a design system as a navigable deck",
+        "Previewing a theme's full token coverage in slide format",
+        "Design system documentation and onboarding"
+      ],
+      "when_not_to_use": [
+        "Production user-facing pages",
+        "When a flat specimen view is preferred (use design-system-specimen instead)"
+      ]
+    },
+    "design-system-specimen": {
+      "category": "documentation",
+      "description": "Live interactive showcase of the full Visor token system and component library. Responds dynamically to the active theme.",
+      "components_used": [
+        "alert",
+        "badge",
         "button",
-        "field",
-        "fieldset",
+        "card",
+        "checkbox",
+        "heading",
+        "input",
+        "label",
+        "progress",
+        "radio-group",
+        "select",
         "separator",
+        "slider",
+        "switch",
         "tabs",
-        "avatar"
+        "text",
+        "textarea",
+        "toggle-group"
       ],
       "when_to_use": [
-        "User profile and account settings",
-        "Application preferences and configuration",
-        "Team or organization settings"
+        "Previewing a theme's full token coverage",
+        "Validating design system consistency across components",
+        "Design system documentation and onboarding"
+      ],
+      "when_not_to_use": [
+        "Production user-facing pages"
       ]
-    }
-  },
-  "categories": {
-    "specimen": [
-      "accessibility-specimen",
-      "color-bar",
-      "color-swatch",
-      "elevation-card",
-      "font-showcase",
-      "icon-grid",
-      "motion-specimen",
-      "opacity-bar",
-      "radius-scale",
-      "spacing-scale",
-      "surface-row",
-      "type-specimen"
-    ],
-    "data-display": [
-      "accordion",
-      "avatar",
-      "badge",
-      "card",
-      "chart",
-      "table",
-      "timeline"
-    ],
-    "admin": [
-      "activity-feed",
-      "bulk-action-bar",
-      "confirm-dialog",
-      "data-table",
-      "empty-state",
-      "filter-bar",
-      "kbd",
-      "stat-card",
-      "status-badge"
-    ],
-    "feedback": [
-      "alert",
-      "banner",
-      "popover",
-      "progress",
-      "skeleton",
-      "toast",
-      "tooltip"
-    ],
-    "navigation": [
-      "breadcrumb",
-      "command",
-      "navbar",
-      "page-header",
-      "pagination",
-      "stepper",
-      "tabs"
-    ],
-    "form": [
-      "button",
-      "calendar",
+    },
+    "features-grid": {
+      "category": "marketing",
+      "description": "A responsive grid of feature cards with icons, titles, and descriptions. Demonstrates Card + icon composition in a configurable grid layout.",
+      "components_used": [
+        "card",
+        "heading",
+        "text"
+      ],
+      "when_to_use": [
+        "Product feature showcases",
+        "Service offering grids",
+        "Capability overviews"
+      ],
+      "when_not_to_use": [
+        "Icon-only grids without descriptions (use icon-grid specimen)",
+        "Single feature highlights"
+      ]
+    },
+    "footer-section": {
+      "category": "marketing",
+      "description": "A multi-column responsive footer with link groups, logo area, and copyright.",
+      "components_used": [
+        "heading",
+        "text",
+        "separator"
+      ],
+      "when_to_use": [
+        "Website footers",
+        "Landing page footers",
+        "App marketing site footers"
+      ],
+      "when_not_to_use": [
+        "In-app footers (typically minimal)",
+        "Presentation footers (use deck-footer)"
+      ]
+    },
+    "hero-section": {
+      "category": "marketing",
+      "description": "A full-width hero section with background media support, heading, subheading, and call-to-action button.",
+      "components_used": [
+        "heading",
+        "text",
+        "button"
+      ],
+      "when_to_use": [
+        "Marketing landing page hero",
+        "Product launch pages",
+        "App landing pages"
+      ],
+      "when_not_to_use": [
+        "Presentation slides (use deck hero-slide)",
+        "Content sections without full-viewport height"
+      ]
+    },
+    "login-form": {
+      "category": "authentication",
+      "description": "A login form block using Visor form components (Button, Input, Label, Card).",
+      "components_used": [
+        "button",
+        "input",
+        "field",
+        "card"
+      ],
+      "when_to_use": [
+        "Authentication pages",
+        "Sign-in screens",
+        "Demo login flows"
+      ],
+      "when_not_to_use": [
+        "Registration forms (extend with additional fields)",
+        "OAuth-only flows with no email/password fields"
+      ]
+    },
+    "pricing-section": {
+      "category": "marketing",
+      "description": "A responsive pricing tier grid with feature lists, highlighted plan, and per-tier CTAs.",
+      "components_used": [
+        "card",
+        "badge",
+        "button",
+        "separator",
+        "heading",
+        "text"
+      ],
+      "when_to_use": [
+        "SaaS pricing pages",
+        "Product comparison grids",
+        "Subscription tier displays"
+      ],
+      "when_not_to_use": [
+        "Single product pricing (use Card directly)",
+        "Feature comparison tables without pricing"
+      ]
+    },
+    "sphere-playground": {
+      "category": "visual-elements",
+      "description": "An interactive demo composing the Sphere visualization with a Configuration Panel for real-time parameter control. The signature showcase for Visual Elements.",
+      "components_used": [
+        "sphere",
+        "configuration-panel",
+        "slider-control",
+        "toggle-group"
+      ],
+      "when_to_use": [
+        "Showcasing the Sphere component with interactive controls",
+        "Building immersive GPU-accelerated visual demos",
+        "Demonstrating Visor's visual element capabilities"
+      ],
+      "when_not_to_use": [
+        "Embedding a sphere without controls — use the Sphere component directly",
+        "Building a custom control panel — use ConfigurationPanel independently"
+      ]
+    },
+    "steps-section": {
+      "category": "marketing",
+      "description": "A numbered process section with auto-numbered steps and connector lines. Suitable for \"how it works\" sections and onboarding flows.",
+      "components_used": [
+        "heading",
+        "text"
+      ],
+      "when_to_use": [
+        "How it works sections",
+        "Onboarding flow overviews",
+        "Process explanations"
+      ],
+      "when_not_to_use": [
+        "Detailed multi-step wizards (use stepper/form)",
+        "Vertical timelines with dates (use timeline component)"
+      ]
+    },
+    "testimonial-section": {
+      "category": "marketing",
+      "description": "A social proof section with testimonial quotes, avatars, and attribution. Supports single centered layout or responsive grid for multiple testimonials.",
+      "components_used": [
+        "card",
+        "avatar",
+        "text",
+        "heading",
+        "separator"
+      ],
+      "when_to_use": [
+        "Customer testimonials",
+        "Social proof sections",
+        "Review showcases"
+      ],
+      "when_not_to_use": [
+        "Product reviews with ratings (extend with star component)",
+        "User-generated content feeds"
+      ]
+    }
+  },
+  "hooks": {
+    "use-media-query": {
+      "description": "SSR-safe hook that returns whether a CSS media query matches.",
+      "params": [
+        {
+          "name": "query",
+          "type": "string",
+          "required": true,
+          "description": "CSS media query string (e.g. \"(min-width: 768px)\")."
+        }
+      ],
+      "returns": [
+        {
+          "name": "matches",
+          "type": "boolean",
+          "description": "Whether the media query currently matches. SSR-safe (defaults to false)."
+        }
+      ]
+    },
+    "use-debounce": {
+      "description": "Debounces a value by delaying updates until after a specified delay. Useful for search inputs and high-frequency events.",
+      "params": [
+        {
+          "name": "value",
+          "type": "T",
+          "required": true,
+          "description": "The value to debounce."
+        },
+        {
+          "name": "delay",
+          "type": "number",
+          "required": true,
+          "description": "Delay in milliseconds before the debounced value updates."
+        }
+      ],
+      "returns": [
+        {
+          "name": "debouncedValue",
+          "type": "T",
+          "description": "The debounced value, updated only after the delay elapses with no new changes."
+        }
+      ]
+    },
+    "use-click-outside": {
+      "description": "Fires a callback when a click or touch event occurs outside the referenced element. Useful for closing dropdowns and popovers.",
+      "params": [
+        {
+          "name": "ref",
+          "type": "RefObject<T extends HTMLElement>",
+          "required": true,
+          "description": "Ref to the element that defines the \"inside\" boundary."
+        },
+        {
+          "name": "handler",
+          "type": "(event: MouseEvent | TouchEvent) => void",
+          "required": true,
+          "description": "Callback invoked when a click/touch lands outside the ref element."
+        }
+      ]
+    },
+    "use-currency": {
+      "description": "Detects user locale and returns currency symbol and price formatter for USD, EUR, and GBP.",
+      "returns": [
+        {
+          "name": "currency",
+          "type": "'usd' | 'eur' | 'gbp'",
+          "description": "Detected currency code based on browser locale."
+        },
+        {
+          "name": "symbol",
+          "type": "string",
+          "description": "Currency symbol ($, EUR, or GBP)."
+        },
+        {
+          "name": "formatPrice",
+          "type": "(prices: Record<Currency, number>) => string",
+          "description": "Formats a price object into a localized string using the detected currency."
+        }
+      ]
+    },
+    "use-local-storage": {
+      "description": "Persists state to localStorage with SSR safety, functional updates, and cross-tab synchronisation.",
+      "params": [
+        {
+          "name": "key",
+          "type": "string",
+          "required": true,
+          "description": "The localStorage key to read from and write to."
+        },
+        {
+          "name": "initialValue",
+          "type": "T",
+          "required": true,
+          "description": "Default value used when no stored value exists or localStorage is unavailable."
+        }
+      ],
+      "returns": [
+        {
+          "name": "storedValue",
+          "type": "T",
+          "description": "Current value from localStorage (or the initial value as fallback)."
+        },
+        {
+          "name": "setValue",
+          "type": "(value: T | ((prev: T) => T)) => void",
+          "description": "Updates the stored value. Accepts a direct value or an updater function."
+        },
+        {
+          "name": "removeValue",
+          "type": "() => void",
+          "description": "Removes the key from localStorage and resets to the initial value."
+        }
+      ]
+    },
+    "use-intersection-observer": {
+      "description": "Tracks whether an element is visible within the viewport using IntersectionObserver. Supports one-shot mode for lazy loading.",
+      "params": [
+        {
+          "name": "once",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "If true, stops observing after the element first intersects."
+        },
+        {
+          "name": "threshold",
+          "type": "number | number[]",
+          "required": false,
+          "default": "0",
+          "description": "IntersectionObserver visibility threshold."
+        },
+        {
+          "name": "root",
+          "type": "Element | null",
+          "required": false,
+          "default": "null",
+          "description": "Scroll container to use as the intersection root."
+        },
+        {
+          "name": "rootMargin",
+          "type": "string",
+          "required": false,
+          "default": "\"0%\"",
+          "description": "Margin around the root for expanding or shrinking the intersection area."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "React.RefObject<Element | null>",
+          "description": "Ref to attach to the element you want to observe."
+        },
+        {
+          "name": "isIntersecting",
+          "type": "boolean",
+          "description": "Whether the observed element is currently intersecting."
+        },
+        {
+          "name": "entry",
+          "type": "IntersectionObserverEntry | null",
+          "description": "The raw IntersectionObserverEntry, or null before first observation."
+        }
+      ]
+    },
+    "use-keyboard-shortcut": {
+      "description": "Fires a callback when a specific keyboard shortcut is pressed, with support for modifier keys (Meta, Ctrl, Shift, Alt).",
+      "params": [
+        {
+          "name": "key",
+          "type": "string",
+          "required": true,
+          "description": "The key to listen for (case-insensitive, e.g. \"k\", \"Escape\")."
+        },
+        {
+          "name": "callback",
+          "type": "(event: KeyboardEvent) => void",
+          "required": true,
+          "description": "Function invoked when the shortcut is triggered."
+        },
+        {
+          "name": "options",
+          "type": "KeyboardShortcutOptions",
+          "required": false,
+          "description": "Modifier and target configuration."
+        },
+        {
+          "name": "options.meta",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether the Meta (Cmd/Win) key must be held."
+        },
+        {
+          "name": "options.ctrl",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether the Ctrl key must be held."
+        },
+        {
+          "name": "options.shift",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether the Shift key must be held."
+        },
+        {
+          "name": "options.alt",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether the Alt/Option key must be held."
+        },
+        {
+          "name": "options.target",
+          "type": "EventTarget | null",
+          "required": false,
+          "default": "document",
+          "description": "Element to attach the listener to."
+        },
+        {
+          "name": "options.preventDefault",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether to prevent the default browser action."
+        }
+      ]
+    },
+    "use-focus-trap": {
+      "description": "Traps keyboard focus within a container element. Used for accessible modals, drawers, and dialogs.",
+      "params": [
+        {
+          "name": "ref",
+          "type": "RefObject<HTMLElement | null>",
+          "required": true,
+          "description": "Ref to the container element that traps focus."
+        },
+        {
+          "name": "enabled",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "Whether the focus trap is active."
+        }
+      ]
+    },
+    "use-previous": {
+      "description": "Returns the previous value of a variable from the last render. Useful for comparing values across renders.",
+      "params": [
+        {
+          "name": "value",
+          "type": "T",
+          "required": true,
+          "description": "The value to track across renders."
+        }
+      ],
+      "returns": [
+        {
+          "name": "previousValue",
+          "type": "T | undefined",
+          "description": "The value from the previous render, or undefined on the first render."
+        }
+      ]
+    },
+    "use-boolean": {
+      "description": "Manages a boolean state with stable toggle, setTrue, and setFalse helpers. Useful for open/close and show/hide patterns.",
+      "params": [
+        {
+          "name": "initialValue",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Initial boolean state value."
+        }
+      ],
+      "returns": [
+        {
+          "name": "value",
+          "type": "boolean",
+          "description": "Current boolean state."
+        },
+        {
+          "name": "setTrue",
+          "type": "() => void",
+          "description": "Sets state to true."
+        },
+        {
+          "name": "setFalse",
+          "type": "() => void",
+          "description": "Sets state to false."
+        },
+        {
+          "name": "toggle",
+          "type": "() => void",
+          "description": "Toggles state between true and false."
+        },
+        {
+          "name": "setValue",
+          "type": "(value: boolean) => void",
+          "description": "Sets state to an explicit boolean value."
+        }
+      ]
+    },
+    "use-intersection-animation": {
+      "description": "Observes section visibility via IntersectionObserver and updates the active index for scroll-driven animations.",
+      "params": [
+        {
+          "name": "sectionsRef",
+          "type": "React.RefObject<HTMLElement[]>",
+          "required": true,
+          "description": "Ref to an array of section elements to observe."
+        },
+        {
+          "name": "currentIndexRef",
+          "type": "React.MutableRefObject<number>",
+          "required": true,
+          "description": "Mutable ref holding the current visible section index."
+        },
+        {
+          "name": "setCurrentIndex",
+          "type": "(index: number) => void",
+          "required": true,
+          "description": "State setter called when the visible section changes."
+        },
+        {
+          "name": "isScrollingRef",
+          "type": "React.MutableRefObject<boolean>",
+          "required": false,
+          "description": "Ref indicating programmatic scrolling is in progress; suppresses index updates when true."
+        },
+        {
+          "name": "threshold",
+          "type": "number",
+          "required": false,
+          "default": "0.4",
+          "description": "IntersectionObserver visibility threshold (0 to 1)."
+        }
+      ]
+    },
+    "use-keyboard-nav": {
+      "description": "Handles Arrow Up/Down and Home/End keyboard navigation to move between indexed sections or slides.",
+      "params": [
+        {
+          "name": "containerRef",
+          "type": "React.RefObject<HTMLElement | null>",
+          "required": false,
+          "description": "Container element to listen on. Falls back to document if not provided."
+        },
+        {
+          "name": "goTo",
+          "type": "(index: number) => void",
+          "required": true,
+          "description": "Navigation function that scrolls to the given section index."
+        },
+        {
+          "name": "currentIndexRef",
+          "type": "React.MutableRefObject<number>",
+          "required": true,
+          "description": "Mutable ref holding the current section index."
+        },
+        {
+          "name": "totalSectionsRef",
+          "type": "React.MutableRefObject<number>",
+          "required": true,
+          "description": "Mutable ref holding the total number of sections."
+        }
+      ]
+    },
+    "use-slide-engine": {
+      "description": "Provides smooth programmatic scrolling between indexed sections with a scrolling-lock guard to prevent observer conflicts.",
+      "params": [
+        {
+          "name": "containerRef",
+          "type": "React.RefObject<HTMLElement | null>",
+          "required": false,
+          "description": "Container element that scrolls. Falls back to scrollIntoView if not provided."
+        },
+        {
+          "name": "sectionsRef",
+          "type": "React.RefObject<HTMLElement[]>",
+          "required": true,
+          "description": "Ref to an array of section elements that can be navigated."
+        },
+        {
+          "name": "currentIndexRef",
+          "type": "React.MutableRefObject<number>",
+          "required": true,
+          "description": "Mutable ref holding the current section index."
+        },
+        {
+          "name": "setCurrentIndex",
+          "type": "(index: number) => void",
+          "required": false,
+          "description": "State setter called when navigation occurs."
+        }
+      ],
+      "returns": [
+        {
+          "name": "goTo",
+          "type": "(index: number) => void",
+          "description": "Scrolls to the section at the given index with smooth animation."
+        },
+        {
+          "name": "navigateTo",
+          "type": "(id: string) => void",
+          "description": "Scrolls to a section by its DOM element id."
+        },
+        {
+          "name": "isScrollingRef",
+          "type": "React.MutableRefObject<boolean>",
+          "description": "Ref indicating whether a programmatic scroll is in progress."
+        }
+      ]
+    },
+    "use-wheel-nav": {
+      "description": "Converts vertical wheel events into discrete index-based navigation with debounced throttling.",
+      "params": [
+        {
+          "name": "containerRef",
+          "type": "React.RefObject<HTMLElement | null>",
+          "required": false,
+          "description": "Container element to listen on. Falls back to document if not provided."
+        },
+        {
+          "name": "goTo",
+          "type": "(index: number) => void",
+          "required": true,
+          "description": "Navigation function that scrolls to the given section index."
+        },
+        {
+          "name": "currentIndexRef",
+          "type": "React.MutableRefObject<number>",
+          "required": true,
+          "description": "Mutable ref holding the current section index."
+        }
+      ]
+    }
+  },
+  "patterns": {
+    "auth-flow": {
+      "description": "Login, registration, and password recovery pages sharing a centered card layout.",
+      "components_used": [
+        "card",
+        "input",
+        "button",
+        "field",
+        "alert",
+        "tabs"
+      ],
+      "when_to_use": [
+        "Sign-in and sign-up pages",
+        "Forgot password and reset password flows",
+        "Invitation acceptance screens"
+      ]
+    },
+    "card-grid": {
+      "description": "A responsive grid of content cards with skeleton loading states, status badges, action buttons, pagination, and an empty-state fallback.",
+      "components_used": [
+        "card",
+        "badge",
+        "button",
+        "skeleton",
+        "empty-state",
+        "pagination"
+      ],
+      "when_to_use": [
+        "Displaying a collection of items as visual tiles (projects, products, team members)",
+        "When a table layout is too data-dense and card previews are more scannable",
+        "Catalog or gallery pages with paginated content"
+      ]
+    },
+    "crud-table": {
+      "description": "Data table with row actions, confirmation dialog, and pagination for managing collections of records.",
+      "components_used": [
+        "table",
+        "button",
+        "dropdown-menu",
+        "dialog",
+        "alert",
+        "pagination",
+        "badge"
+      ],
+      "when_to_use": [
+        "Admin pages listing and managing resources (users, orders, products)",
+        "Any collection view with create, read, update, delete operations",
+        "Data tables needing row-level actions and bulk operations"
+      ]
+    },
+    "dashboard-layout": {
+      "description": "App shell with collapsible sidebar navigation, top navbar, and content area with cards and tabs.",
+      "components_used": [
+        "sidebar",
+        "navbar",
+        "card",
+        "tabs",
+        "separator",
+        "scroll-area"
+      ],
+      "when_to_use": [
+        "Admin dashboards and internal tools",
+        "Multi-section apps with persistent navigation",
+        "Content-heavy layouts needing sidebar + main area structure"
+      ]
+    },
+    "data-table-row-actions": {
+      "description": "A data table with per-row action menus, bulk selection with a bulk action bar, confirmation dialogs, and toast feedback for destructive operations.",
+      "components_used": [
+        "data-table",
+        "dropdown-menu",
+        "dialog",
+        "confirm-dialog",
+        "toast",
+        "bulk-action-bar"
+      ],
+      "when_to_use": [
+        "Admin lists where rows have contextual actions (edit, archive, delete)",
+        "When supporting both single-row and bulk operations on the same table",
+        "Any CRUD interface where destructive actions require confirmation"
+      ]
+    },
+    "data-table-with-filters": {
+      "description": "Filterable data table with a toolbar for search, category filters, and column sorting.",
+      "components_used": [
+        "table",
+        "input",
+        "select",
+        "button",
+        "badge",
+        "dropdown-menu",
+        "pagination"
+      ],
+      "when_to_use": [
+        "Data-heavy pages where users need to find specific records",
+        "Admin dashboards with sortable, filterable lists",
+        "Search result pages with faceted filtering"
+      ]
+    },
+    "empty-state": {
+      "description": "Placeholder shown when a page, list, or search has no content to display.",
+      "components_used": [
+        "card",
+        "button",
+        "heading",
+        "text"
+      ],
+      "when_to_use": [
+        "Empty lists or tables (no data yet)",
+        "Search results returning zero matches",
+        "First-time user onboarding (no content created yet)",
+        "Error states where content failed to load"
+      ]
+    },
+    "form-with-validation": {
+      "description": "Standard form layout with field-level validation and submission handling.",
+      "components_used": [
+        "field",
+        "input",
+        "label",
+        "textarea",
+        "button",
+        "alert"
+      ],
+      "when_to_use": [
+        "Any form collecting user input (settings, profile, onboarding)",
+        "Forms needing inline validation feedback",
+        "Multi-field forms with consistent spacing and error display"
+      ]
+    },
+    "modal-form": {
+      "description": "A dialog-based form pattern for creating or editing entities inline without navigating away.",
+      "components_used": [
+        "dialog",
+        "field",
+        "input",
+        "label",
+        "textarea",
+        "button",
+        "alert"
+      ],
+      "when_to_use": [
+        "Creating or editing a record without leaving the current page",
+        "Collecting a small set of inputs (fewer than 8 fields)",
+        "When the action is contextual to the parent list or table"
+      ]
+    },
+    "notification-center": {
+      "description": "A popover-based notification hub with a command palette for filtering and bulk-managing alerts, toasts, and system messages.",
+      "components_used": [
+        "toast",
+        "command",
+        "button",
+        "badge",
+        "scroll-area"
+      ],
+      "when_to_use": [
+        "Apps with persistent in-app notifications or activity alerts",
+        "When users need to review, dismiss, or act on multiple notifications at once",
+        "Combining real-time toast feedback with a browsable notification history"
+      ]
+    },
+    "onboarding-flow": {
+      "description": "A step-by-step welcome flow that collects user preferences and setup choices using progress tracking, cards, and inline forms with checkbox selections.",
+      "components_used": [
+        "stepper",
+        "progress",
+        "card",
+        "button",
+        "field",
+        "input",
+        "checkbox",
+        "alert"
+      ],
+      "when_to_use": [
+        "First-run experiences after account creation",
+        "Feature setup flows where configuration choices shape the initial workspace",
+        "Product tours that collect preferences before showing the main dashboard"
+      ]
+    },
+    "responsive-sidebar-layout": {
+      "description": "A full-app shell that renders a persistent sidebar on desktop and a Sheet-based drawer on mobile, sharing the same navigation content.",
+      "components_used": [
+        "sidebar",
+        "sheet",
+        "navbar",
+        "button",
+        "separator",
+        "scroll-area"
+      ],
+      "when_to_use": [
+        "Any multi-section app needing sidebar navigation that must work on mobile",
+        "When the desktop sidebar should collapse to a drawer without duplicating nav markup",
+        "Admin tools, dashboards, or SaaS apps requiring a responsive shell"
+      ]
+    },
+    "search-results": {
+      "description": "A search UI combining a type-ahead input, command palette, and filterable result cards with empty-state fallback.",
+      "components_used": [
+        "search-input",
+        "command",
+        "combobox",
+        "card",
+        "badge",
+        "empty-state"
+      ],
+      "when_to_use": [
+        "Search pages where users need to filter and browse a large dataset",
+        "When combining free-text search with faceted category filters",
+        "Directory, catalog, or discovery interfaces with card-based result display"
+      ]
+    },
+    "settings-page": {
+      "description": "Multi-section settings page with sidebar navigation, grouped form fields, and save actions.",
+      "components_used": [
+        "card",
+        "input",
+        "textarea",
+        "select",
+        "switch",
+        "button",
+        "field",
+        "fieldset",
+        "separator",
+        "tabs",
+        "avatar"
+      ],
+      "when_to_use": [
+        "User profile and account settings",
+        "Application preferences and configuration",
+        "Team or organization settings"
+      ]
+    },
+    "wizard-flow": {
+      "description": "A multi-step guided flow with per-step validation, progress tracking, and a linear navigation structure for complex data collection.",
+      "components_used": [
+        "stepper",
+        "field",
+        "input",
+        "button",
+        "alert",
+        "progress",
+        "separator"
+      ],
+      "when_to_use": [
+        "Onboarding flows, setup wizards, or checkout sequences",
+        "When a single long form would overwhelm the user — break into logical steps",
+        "Flows where earlier steps gate or inform later steps"
+      ]
+    }
+  },
+  "categories": {
+    "specimen": [
+      "accessibility-specimen",
+      "color-bar",
+      "color-swatch",
+      "elevation-card",
+      "font-showcase",
+      "icon-grid",
+      "motion-specimen",
+      "opacity-bar",
+      "radius-scale",
+      "spacing-scale",
+      "surface-row",
+      "type-specimen"
+    ],
+    "data-display": [
+      "accordion",
+      "avatar",
+      "badge",
+      "card",
+      "chart",
+      "table",
+      "timeline"
+    ],
+    "admin": [
+      "activity-feed",
+      "bulk-action-bar",
+      "confirm-dialog",
+      "data-table",
+      "empty-state",
+      "filter-bar",
+      "kbd",
+      "stat-card",
+      "status-badge"
+    ],
+    "feedback": [
+      "alert",
+      "banner",
+      "popover",
+      "progress",
+      "skeleton",
+      "toast",
+      "tooltip"
+    ],
+    "navigation": [
+      "breadcrumb",
+      "command",
+      "navbar",
+      "page-header",
+      "pagination",
+      "stepper",
+      "tabs"
+    ],
+    "form": [
+      "button",
+      "calendar",
       "checkbox",
       "combobox",
       "date-picker",
@@ -6551,25 +7772,2141 @@
       "image",
       "lightbox"
     ],
-    "typography": [
-      "code-block",
-      "heading",
-      "text"
+    "typography": [
+      "code-block",
+      "heading",
+      "text"
+    ],
+    "layout": [
+      "collapsible",
+      "scroll-area",
+      "separator",
+      "sidebar"
+    ],
+    "overlay": [
+      "context-menu",
+      "dialog",
+      "dropdown-menu",
+      "fullscreen-overlay",
+      "hover-card",
+      "menubar",
+      "sheet"
+    ],
+    "deck": [
+      "deck-card-grid",
+      "deck-carousel-gallery",
+      "deck-closing-slide",
+      "deck-concept-slide",
+      "deck-context",
+      "deck-dot-nav",
+      "deck-footer",
+      "deck-hero-slide",
+      "deck-layout",
+      "deck-renderer",
+      "deck-slide-header",
+      "deck-toc-slide",
+      "slide",
+      "slide-theme-context"
+    ],
+    "visual-elements": [
+      "sphere"
+    ]
+  },
+  "tokens": {
+    "primitives": [
+      {
+        "name": "--color-neutral-50",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-50",
+        "defaultLight": "#f9fafb",
+        "defaultDark": "#f9fafb"
+      },
+      {
+        "name": "--color-neutral-100",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-100",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#f3f4f6"
+      },
+      {
+        "name": "--color-neutral-200",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-200",
+        "defaultLight": "#e5e7eb",
+        "defaultDark": "#e5e7eb"
+      },
+      {
+        "name": "--color-neutral-300",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-300",
+        "defaultLight": "#d1d5db",
+        "defaultDark": "#d1d5db"
+      },
+      {
+        "name": "--color-neutral-400",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-400",
+        "defaultLight": "#9ca3af",
+        "defaultDark": "#9ca3af"
+      },
+      {
+        "name": "--color-neutral-500",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-500",
+        "defaultLight": "#6b7280",
+        "defaultDark": "#6b7280"
+      },
+      {
+        "name": "--color-neutral-600",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-600",
+        "defaultLight": "#4b5563",
+        "defaultDark": "#4b5563"
+      },
+      {
+        "name": "--color-neutral-700",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-700",
+        "defaultLight": "#374151",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--color-neutral-800",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-800",
+        "defaultLight": "#1f2937",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--color-neutral-900",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-900",
+        "defaultLight": "#111827",
+        "defaultDark": "#111827"
+      },
+      {
+        "name": "--color-neutral-950",
+        "tier": "primitive",
+        "description": "Primitive color: neutral-950",
+        "defaultLight": "#030712",
+        "defaultDark": "#030712"
+      },
+      {
+        "name": "--color-white",
+        "tier": "primitive",
+        "description": "Primitive color: white",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#ffffff"
+      },
+      {
+        "name": "--color-black",
+        "tier": "primitive",
+        "description": "Primitive color: black",
+        "defaultLight": "#000000",
+        "defaultDark": "#000000"
+      },
+      {
+        "name": "--color-primary-50",
+        "tier": "primitive",
+        "description": "Primitive color: primary-50",
+        "defaultLight": "#eff6ff",
+        "defaultDark": "#eff6ff"
+      },
+      {
+        "name": "--color-primary-100",
+        "tier": "primitive",
+        "description": "Primitive color: primary-100",
+        "defaultLight": "#dbeafe",
+        "defaultDark": "#dbeafe"
+      },
+      {
+        "name": "--color-primary-200",
+        "tier": "primitive",
+        "description": "Primitive color: primary-200",
+        "defaultLight": "#bfdbfe",
+        "defaultDark": "#bfdbfe"
+      },
+      {
+        "name": "--color-primary-300",
+        "tier": "primitive",
+        "description": "Primitive color: primary-300",
+        "defaultLight": "#93c5fd",
+        "defaultDark": "#93c5fd"
+      },
+      {
+        "name": "--color-primary-400",
+        "tier": "primitive",
+        "description": "Primitive color: primary-400",
+        "defaultLight": "#60a5fa",
+        "defaultDark": "#60a5fa"
+      },
+      {
+        "name": "--color-primary-500",
+        "tier": "primitive",
+        "description": "Primitive color: primary-500",
+        "defaultLight": "#3b82f6",
+        "defaultDark": "#3b82f6"
+      },
+      {
+        "name": "--color-primary-600",
+        "tier": "primitive",
+        "description": "Primitive color: primary-600",
+        "defaultLight": "#2563eb",
+        "defaultDark": "#2563eb"
+      },
+      {
+        "name": "--color-primary-700",
+        "tier": "primitive",
+        "description": "Primitive color: primary-700",
+        "defaultLight": "#1d4ed8",
+        "defaultDark": "#1d4ed8"
+      },
+      {
+        "name": "--color-primary-800",
+        "tier": "primitive",
+        "description": "Primitive color: primary-800",
+        "defaultLight": "#1e40af",
+        "defaultDark": "#1e40af"
+      },
+      {
+        "name": "--color-primary-900",
+        "tier": "primitive",
+        "description": "Primitive color: primary-900",
+        "defaultLight": "#1e3a8a",
+        "defaultDark": "#1e3a8a"
+      },
+      {
+        "name": "--color-success-50",
+        "tier": "primitive",
+        "description": "Primitive color: success-50",
+        "defaultLight": "#f0fdf4",
+        "defaultDark": "#f0fdf4"
+      },
+      {
+        "name": "--color-success-100",
+        "tier": "primitive",
+        "description": "Primitive color: success-100",
+        "defaultLight": "#dcfce7",
+        "defaultDark": "#dcfce7"
+      },
+      {
+        "name": "--color-success-500",
+        "tier": "primitive",
+        "description": "Primitive color: success-500",
+        "defaultLight": "#22c55e",
+        "defaultDark": "#22c55e"
+      },
+      {
+        "name": "--color-success-600",
+        "tier": "primitive",
+        "description": "Primitive color: success-600",
+        "defaultLight": "#16a34a",
+        "defaultDark": "#16a34a"
+      },
+      {
+        "name": "--color-success-700",
+        "tier": "primitive",
+        "description": "Primitive color: success-700",
+        "defaultLight": "#15803d",
+        "defaultDark": "#15803d"
+      },
+      {
+        "name": "--color-success-900",
+        "tier": "primitive",
+        "description": "Primitive color: success-900",
+        "defaultLight": "#14532d",
+        "defaultDark": "#14532d"
+      },
+      {
+        "name": "--color-warning-50",
+        "tier": "primitive",
+        "description": "Primitive color: warning-50",
+        "defaultLight": "#fffbeb",
+        "defaultDark": "#fffbeb"
+      },
+      {
+        "name": "--color-warning-100",
+        "tier": "primitive",
+        "description": "Primitive color: warning-100",
+        "defaultLight": "#fef3c7",
+        "defaultDark": "#fef3c7"
+      },
+      {
+        "name": "--color-warning-500",
+        "tier": "primitive",
+        "description": "Primitive color: warning-500",
+        "defaultLight": "#f59e0b",
+        "defaultDark": "#f59e0b"
+      },
+      {
+        "name": "--color-warning-600",
+        "tier": "primitive",
+        "description": "Primitive color: warning-600",
+        "defaultLight": "#d97706",
+        "defaultDark": "#d97706"
+      },
+      {
+        "name": "--color-warning-700",
+        "tier": "primitive",
+        "description": "Primitive color: warning-700",
+        "defaultLight": "#b45309",
+        "defaultDark": "#b45309"
+      },
+      {
+        "name": "--color-warning-900",
+        "tier": "primitive",
+        "description": "Primitive color: warning-900",
+        "defaultLight": "#78350f",
+        "defaultDark": "#78350f"
+      },
+      {
+        "name": "--color-error-50",
+        "tier": "primitive",
+        "description": "Primitive color: error-50",
+        "defaultLight": "#fef2f2",
+        "defaultDark": "#fef2f2"
+      },
+      {
+        "name": "--color-error-100",
+        "tier": "primitive",
+        "description": "Primitive color: error-100",
+        "defaultLight": "#fee2e2",
+        "defaultDark": "#fee2e2"
+      },
+      {
+        "name": "--color-error-500",
+        "tier": "primitive",
+        "description": "Primitive color: error-500",
+        "defaultLight": "#ef4444",
+        "defaultDark": "#ef4444"
+      },
+      {
+        "name": "--color-error-600",
+        "tier": "primitive",
+        "description": "Primitive color: error-600",
+        "defaultLight": "#dc2626",
+        "defaultDark": "#dc2626"
+      },
+      {
+        "name": "--color-error-700",
+        "tier": "primitive",
+        "description": "Primitive color: error-700",
+        "defaultLight": "#b91c1c",
+        "defaultDark": "#b91c1c"
+      },
+      {
+        "name": "--color-error-900",
+        "tier": "primitive",
+        "description": "Primitive color: error-900",
+        "defaultLight": "#7f1d1d",
+        "defaultDark": "#7f1d1d"
+      },
+      {
+        "name": "--color-info-50",
+        "tier": "primitive",
+        "description": "Primitive color: info-50",
+        "defaultLight": "#f0f9ff",
+        "defaultDark": "#f0f9ff"
+      },
+      {
+        "name": "--color-info-100",
+        "tier": "primitive",
+        "description": "Primitive color: info-100",
+        "defaultLight": "#e0f2fe",
+        "defaultDark": "#e0f2fe"
+      },
+      {
+        "name": "--color-info-500",
+        "tier": "primitive",
+        "description": "Primitive color: info-500",
+        "defaultLight": "#0ea5e9",
+        "defaultDark": "#0ea5e9"
+      },
+      {
+        "name": "--color-info-600",
+        "tier": "primitive",
+        "description": "Primitive color: info-600",
+        "defaultLight": "#0284c7",
+        "defaultDark": "#0284c7"
+      },
+      {
+        "name": "--color-info-700",
+        "tier": "primitive",
+        "description": "Primitive color: info-700",
+        "defaultLight": "#0369a1",
+        "defaultDark": "#0369a1"
+      },
+      {
+        "name": "--color-info-900",
+        "tier": "primitive",
+        "description": "Primitive color: info-900",
+        "defaultLight": "#0c4a6e",
+        "defaultDark": "#0c4a6e"
+      },
+      {
+        "name": "--spacing-0",
+        "tier": "primitive",
+        "description": "Primitive spacing: 0px",
+        "defaultLight": "0",
+        "defaultDark": "0"
+      },
+      {
+        "name": "--spacing-1",
+        "tier": "primitive",
+        "description": "Primitive spacing: 4px",
+        "defaultLight": "0.25rem",
+        "defaultDark": "0.25rem"
+      },
+      {
+        "name": "--spacing-2",
+        "tier": "primitive",
+        "description": "Primitive spacing: 8px",
+        "defaultLight": "0.5rem",
+        "defaultDark": "0.5rem"
+      },
+      {
+        "name": "--spacing-3",
+        "tier": "primitive",
+        "description": "Primitive spacing: 12px",
+        "defaultLight": "0.75rem",
+        "defaultDark": "0.75rem"
+      },
+      {
+        "name": "--spacing-3_5",
+        "tier": "primitive",
+        "description": "Primitive spacing: 14px",
+        "defaultLight": "0.875rem",
+        "defaultDark": "0.875rem"
+      },
+      {
+        "name": "--spacing-4",
+        "tier": "primitive",
+        "description": "Primitive spacing: 16px",
+        "defaultLight": "1rem",
+        "defaultDark": "1rem"
+      },
+      {
+        "name": "--spacing-4_5",
+        "tier": "primitive",
+        "description": "Primitive spacing: 18px",
+        "defaultLight": "1.125rem",
+        "defaultDark": "1.125rem"
+      },
+      {
+        "name": "--spacing-5",
+        "tier": "primitive",
+        "description": "Primitive spacing: 20px",
+        "defaultLight": "1.25rem",
+        "defaultDark": "1.25rem"
+      },
+      {
+        "name": "--spacing-6",
+        "tier": "primitive",
+        "description": "Primitive spacing: 24px",
+        "defaultLight": "1.5rem",
+        "defaultDark": "1.5rem"
+      },
+      {
+        "name": "--spacing-8",
+        "tier": "primitive",
+        "description": "Primitive spacing: 32px",
+        "defaultLight": "2rem",
+        "defaultDark": "2rem"
+      },
+      {
+        "name": "--spacing-10",
+        "tier": "primitive",
+        "description": "Primitive spacing: 40px",
+        "defaultLight": "2.5rem",
+        "defaultDark": "2.5rem"
+      },
+      {
+        "name": "--spacing-12",
+        "tier": "primitive",
+        "description": "Primitive spacing: 48px",
+        "defaultLight": "3rem",
+        "defaultDark": "3rem"
+      },
+      {
+        "name": "--spacing-16",
+        "tier": "primitive",
+        "description": "Primitive spacing: 64px",
+        "defaultLight": "4rem",
+        "defaultDark": "4rem"
+      },
+      {
+        "name": "--spacing-20",
+        "tier": "primitive",
+        "description": "Primitive spacing: 80px",
+        "defaultLight": "5rem",
+        "defaultDark": "5rem"
+      },
+      {
+        "name": "--spacing-24",
+        "tier": "primitive",
+        "description": "Primitive spacing: 96px",
+        "defaultLight": "6rem",
+        "defaultDark": "6rem"
+      },
+      {
+        "name": "--radius-none",
+        "tier": "primitive",
+        "description": "Primitive border radius: none",
+        "defaultLight": "0",
+        "defaultDark": "0"
+      },
+      {
+        "name": "--radius-sm",
+        "tier": "primitive",
+        "description": "Primitive border radius: sm",
+        "defaultLight": "0.125rem",
+        "defaultDark": "0.125rem"
+      },
+      {
+        "name": "--radius-md",
+        "tier": "primitive",
+        "description": "Primitive border radius: md",
+        "defaultLight": "0.25rem",
+        "defaultDark": "0.25rem"
+      },
+      {
+        "name": "--radius-lg",
+        "tier": "primitive",
+        "description": "Primitive border radius: lg",
+        "defaultLight": "0.5rem",
+        "defaultDark": "0.5rem"
+      },
+      {
+        "name": "--radius-xl",
+        "tier": "primitive",
+        "description": "Primitive border radius: xl",
+        "defaultLight": "0.75rem",
+        "defaultDark": "0.75rem"
+      },
+      {
+        "name": "--radius-2xl",
+        "tier": "primitive",
+        "description": "Primitive border radius: 2xl",
+        "defaultLight": "1rem",
+        "defaultDark": "1rem"
+      },
+      {
+        "name": "--radius-3xl",
+        "tier": "primitive",
+        "description": "Primitive border radius: 3xl",
+        "defaultLight": "1.5rem",
+        "defaultDark": "1.5rem"
+      },
+      {
+        "name": "--radius-full",
+        "tier": "primitive",
+        "description": "Primitive border radius: full",
+        "defaultLight": "9999px",
+        "defaultDark": "9999px"
+      },
+      {
+        "name": "--border-width-1",
+        "tier": "primitive",
+        "description": "Primitive border width: 1px",
+        "defaultLight": "1px",
+        "defaultDark": "1px"
+      },
+      {
+        "name": "--border-width-2",
+        "tier": "primitive",
+        "description": "Primitive border width: 2px",
+        "defaultLight": "2px",
+        "defaultDark": "2px"
+      },
+      {
+        "name": "--border-width-3",
+        "tier": "primitive",
+        "description": "Primitive border width: 3px",
+        "defaultLight": "3px",
+        "defaultDark": "3px"
+      },
+      {
+        "name": "--border-width-4",
+        "tier": "primitive",
+        "description": "Primitive border width: 4px",
+        "defaultLight": "4px",
+        "defaultDark": "4px"
+      },
+      {
+        "name": "--font-size-xs",
+        "tier": "primitive",
+        "description": "Primitive font size: 12px",
+        "defaultLight": "0.75rem",
+        "defaultDark": "0.75rem"
+      },
+      {
+        "name": "--font-size-sm",
+        "tier": "primitive",
+        "description": "Primitive font size: 14px",
+        "defaultLight": "0.875rem",
+        "defaultDark": "0.875rem"
+      },
+      {
+        "name": "--font-size-base",
+        "tier": "primitive",
+        "description": "Primitive font size: 16px",
+        "defaultLight": "1rem",
+        "defaultDark": "1rem"
+      },
+      {
+        "name": "--font-size-lg",
+        "tier": "primitive",
+        "description": "Primitive font size: 18px",
+        "defaultLight": "1.125rem",
+        "defaultDark": "1.125rem"
+      },
+      {
+        "name": "--font-size-xl",
+        "tier": "primitive",
+        "description": "Primitive font size: 20px",
+        "defaultLight": "1.25rem",
+        "defaultDark": "1.25rem"
+      },
+      {
+        "name": "--font-size-2xl",
+        "tier": "primitive",
+        "description": "Primitive font size: 24px",
+        "defaultLight": "1.5rem",
+        "defaultDark": "1.5rem"
+      },
+      {
+        "name": "--font-size-3xl",
+        "tier": "primitive",
+        "description": "Primitive font size: 30px",
+        "defaultLight": "1.875rem",
+        "defaultDark": "1.875rem"
+      },
+      {
+        "name": "--font-size-4xl",
+        "tier": "primitive",
+        "description": "Primitive font size: 36px",
+        "defaultLight": "2.25rem",
+        "defaultDark": "2.25rem"
+      },
+      {
+        "name": "--font-weight-normal",
+        "tier": "primitive",
+        "description": "Primitive font weight: 400",
+        "defaultLight": "400",
+        "defaultDark": "400"
+      },
+      {
+        "name": "--font-weight-medium",
+        "tier": "primitive",
+        "description": "Primitive font weight: 500",
+        "defaultLight": "500",
+        "defaultDark": "500"
+      },
+      {
+        "name": "--font-weight-semibold",
+        "tier": "primitive",
+        "description": "Primitive font weight: 600",
+        "defaultLight": "600",
+        "defaultDark": "600"
+      },
+      {
+        "name": "--font-weight-bold",
+        "tier": "primitive",
+        "description": "Primitive font weight: 700",
+        "defaultLight": "700",
+        "defaultDark": "700"
+      },
+      {
+        "name": "--line-height-none",
+        "tier": "primitive",
+        "description": "Primitive line height: 1",
+        "defaultLight": "1",
+        "defaultDark": "1"
+      },
+      {
+        "name": "--line-height-tight",
+        "tier": "primitive",
+        "description": "Primitive line height: 1.25",
+        "defaultLight": "1.25",
+        "defaultDark": "1.25"
+      },
+      {
+        "name": "--line-height-snug",
+        "tier": "primitive",
+        "description": "Primitive line height: 1.375",
+        "defaultLight": "1.375",
+        "defaultDark": "1.375"
+      },
+      {
+        "name": "--line-height-normal",
+        "tier": "primitive",
+        "description": "Primitive line height: 1.5",
+        "defaultLight": "1.5",
+        "defaultDark": "1.5"
+      },
+      {
+        "name": "--line-height-relaxed",
+        "tier": "primitive",
+        "description": "Primitive line height: 1.625",
+        "defaultLight": "1.625",
+        "defaultDark": "1.625"
+      },
+      {
+        "name": "--line-height-loose",
+        "tier": "primitive",
+        "description": "Primitive line height: 2",
+        "defaultLight": "2",
+        "defaultDark": "2"
+      },
+      {
+        "name": "--shadow-xs",
+        "tier": "primitive",
+        "description": "Primitive shadow: xs",
+        "defaultLight": "inset 0 1px 2px 0 rgba(0, 0, 0, 0.06)",
+        "defaultDark": "inset 0 1px 2px 0 rgba(0, 0, 0, 0.15)"
+      },
+      {
+        "name": "--shadow-sm",
+        "tier": "primitive",
+        "description": "Primitive shadow: sm",
+        "defaultLight": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
+        "defaultDark": "0 1px 2px 0 rgba(0, 0, 0, 0.25)"
+      },
+      {
+        "name": "--shadow-md",
+        "tier": "primitive",
+        "description": "Primitive shadow: md",
+        "defaultLight": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
+        "defaultDark": "0 4px 6px -1px rgba(0, 0, 0, 0.35), 0 2px 4px -2px rgba(0, 0, 0, 0.3)"
+      },
+      {
+        "name": "--shadow-lg",
+        "tier": "primitive",
+        "description": "Primitive shadow: lg",
+        "defaultLight": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
+        "defaultDark": "0 10px 15px -3px rgba(0, 0, 0, 0.4), 0 4px 6px -4px rgba(0, 0, 0, 0.35)"
+      },
+      {
+        "name": "--shadow-xl",
+        "tier": "primitive",
+        "description": "Primitive shadow: xl",
+        "defaultLight": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)",
+        "defaultDark": "0 20px 25px -5px rgba(0, 0, 0, 0.45), 0 8px 10px -6px rgba(0, 0, 0, 0.4)"
+      },
+      {
+        "name": "--z-base",
+        "tier": "primitive",
+        "description": "Primitive z-index: base",
+        "defaultLight": "0",
+        "defaultDark": "0"
+      },
+      {
+        "name": "--z-raised",
+        "tier": "primitive",
+        "description": "Primitive z-index: raised",
+        "defaultLight": "1",
+        "defaultDark": "1"
+      },
+      {
+        "name": "--z-dropdown",
+        "tier": "primitive",
+        "description": "Primitive z-index: dropdown",
+        "defaultLight": "1000",
+        "defaultDark": "1000"
+      },
+      {
+        "name": "--z-sticky",
+        "tier": "primitive",
+        "description": "Primitive z-index: sticky",
+        "defaultLight": "1100",
+        "defaultDark": "1100"
+      },
+      {
+        "name": "--z-modal",
+        "tier": "primitive",
+        "description": "Primitive z-index: modal",
+        "defaultLight": "1300",
+        "defaultDark": "1300"
+      },
+      {
+        "name": "--z-popover",
+        "tier": "primitive",
+        "description": "Primitive z-index: popover",
+        "defaultLight": "1400",
+        "defaultDark": "1400"
+      },
+      {
+        "name": "--z-toast",
+        "tier": "primitive",
+        "description": "Primitive z-index: toast",
+        "defaultLight": "1500",
+        "defaultDark": "1500"
+      },
+      {
+        "name": "--font-sans",
+        "tier": "primitive",
+        "description": "Primitive font family: sans",
+        "defaultLight": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif",
+        "defaultDark": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
+      },
+      {
+        "name": "--font-mono",
+        "tier": "primitive",
+        "description": "Primitive font family: mono",
+        "defaultLight": "\"SF Mono\", \"Fira Code\", \"Fira Mono\", \"Roboto Mono\", monospace",
+        "defaultDark": "\"SF Mono\", \"Fira Code\", \"Fira Mono\", \"Roboto Mono\", monospace"
+      },
+      {
+        "name": "--overlay-bg",
+        "tier": "primitive",
+        "description": "Primitive overlay: bg",
+        "defaultLight": "rgba(0, 0, 0, 0.5)",
+        "defaultDark": "rgba(0, 0, 0, 0.5)"
+      },
+      {
+        "name": "--focus-ring-width",
+        "tier": "primitive",
+        "description": "Primitive focus ring width",
+        "defaultLight": "2px",
+        "defaultDark": "2px"
+      },
+      {
+        "name": "--focus-ring-offset",
+        "tier": "primitive",
+        "description": "Primitive focus ring offset",
+        "defaultLight": "2px",
+        "defaultDark": "2px"
+      },
+      {
+        "name": "--motion-duration-100",
+        "tier": "primitive",
+        "description": "Primitive motion duration: 100ms",
+        "defaultLight": "100ms",
+        "defaultDark": "100ms"
+      },
+      {
+        "name": "--motion-duration-150",
+        "tier": "primitive",
+        "description": "Primitive motion duration: 150ms",
+        "defaultLight": "150ms",
+        "defaultDark": "150ms"
+      },
+      {
+        "name": "--motion-duration-200",
+        "tier": "primitive",
+        "description": "Primitive motion duration: 200ms",
+        "defaultLight": "200ms",
+        "defaultDark": "200ms"
+      },
+      {
+        "name": "--motion-duration-300",
+        "tier": "primitive",
+        "description": "Primitive motion duration: 300ms",
+        "defaultLight": "300ms",
+        "defaultDark": "300ms"
+      },
+      {
+        "name": "--motion-duration-500",
+        "tier": "primitive",
+        "description": "Primitive motion duration: 500ms",
+        "defaultLight": "500ms",
+        "defaultDark": "500ms"
+      },
+      {
+        "name": "--motion-duration-800",
+        "tier": "primitive",
+        "description": "Primitive motion duration: 800ms",
+        "defaultLight": "800ms",
+        "defaultDark": "800ms"
+      },
+      {
+        "name": "--motion-easing-linear",
+        "tier": "primitive",
+        "description": "Primitive motion easing: linear",
+        "defaultLight": "linear",
+        "defaultDark": "linear"
+      },
+      {
+        "name": "--motion-easing-ease-in",
+        "tier": "primitive",
+        "description": "Primitive motion easing: ease-in",
+        "defaultLight": "cubic-bezier(0.4, 0, 1, 1)",
+        "defaultDark": "cubic-bezier(0.4, 0, 1, 1)"
+      },
+      {
+        "name": "--motion-easing-ease-out",
+        "tier": "primitive",
+        "description": "Primitive motion easing: ease-out",
+        "defaultLight": "cubic-bezier(0, 0, 0.2, 1)",
+        "defaultDark": "cubic-bezier(0, 0, 0.2, 1)"
+      },
+      {
+        "name": "--motion-easing-ease-in-out",
+        "tier": "primitive",
+        "description": "Primitive motion easing: ease-in-out",
+        "defaultLight": "cubic-bezier(0.4, 0, 0.2, 1)",
+        "defaultDark": "cubic-bezier(0.4, 0, 0.2, 1)"
+      },
+      {
+        "name": "--motion-easing-spring",
+        "tier": "primitive",
+        "description": "Primitive motion easing: spring",
+        "defaultLight": "cubic-bezier(0.34, 1.56, 0.64, 1)",
+        "defaultDark": "cubic-bezier(0.34, 1.56, 0.64, 1)"
+      }
+    ],
+    "semantic": [
+      {
+        "name": "--text-primary",
+        "tier": "semantic",
+        "description": "Semantic text: primary",
+        "defaultLight": "var(--color-neutral-900)",
+        "defaultDark": "var(--color-neutral-900)"
+      },
+      {
+        "name": "--text-secondary",
+        "tier": "semantic",
+        "description": "Semantic text: secondary",
+        "defaultLight": "var(--color-neutral-600)",
+        "defaultDark": "var(--color-neutral-600)"
+      },
+      {
+        "name": "--text-tertiary",
+        "tier": "semantic",
+        "description": "Semantic text: tertiary",
+        "defaultLight": "var(--color-neutral-400)",
+        "defaultDark": "var(--color-neutral-400)"
+      },
+      {
+        "name": "--text-disabled",
+        "tier": "semantic",
+        "description": "Semantic text: disabled",
+        "defaultLight": "var(--color-neutral-300)",
+        "defaultDark": "var(--color-neutral-300)"
+      },
+      {
+        "name": "--text-inverse",
+        "tier": "semantic",
+        "description": "Semantic text: inverse",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--text-inverse-secondary",
+        "tier": "semantic",
+        "description": "Semantic text: inverse-secondary",
+        "defaultLight": "var(--color-neutral-200)",
+        "defaultDark": "var(--color-neutral-200)"
+      },
+      {
+        "name": "--text-link",
+        "tier": "semantic",
+        "description": "Semantic text: link",
+        "defaultLight": "var(--color-primary-600)",
+        "defaultDark": "var(--color-primary-600)"
+      },
+      {
+        "name": "--text-link-hover",
+        "tier": "semantic",
+        "description": "Semantic text: link-hover",
+        "defaultLight": "var(--color-primary-700)",
+        "defaultDark": "var(--color-primary-700)"
+      },
+      {
+        "name": "--text-success",
+        "tier": "semantic",
+        "description": "Semantic text: success",
+        "defaultLight": "var(--color-success-700)",
+        "defaultDark": "var(--color-success-700)"
+      },
+      {
+        "name": "--text-warning",
+        "tier": "semantic",
+        "description": "Semantic text: warning",
+        "defaultLight": "var(--color-warning-700)",
+        "defaultDark": "var(--color-warning-700)"
+      },
+      {
+        "name": "--text-error",
+        "tier": "semantic",
+        "description": "Semantic text: error",
+        "defaultLight": "var(--color-error-700)",
+        "defaultDark": "var(--color-error-700)"
+      },
+      {
+        "name": "--text-info",
+        "tier": "semantic",
+        "description": "Semantic text: info",
+        "defaultLight": "var(--color-info-700)",
+        "defaultDark": "var(--color-info-700)"
+      },
+      {
+        "name": "--surface-page",
+        "tier": "semantic",
+        "description": "Semantic surface: page",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--surface-card",
+        "tier": "semantic",
+        "description": "Semantic surface: card",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--surface-subtle",
+        "tier": "semantic",
+        "description": "Semantic surface: subtle",
+        "defaultLight": "var(--color-neutral-50)",
+        "defaultDark": "var(--color-neutral-50)"
+      },
+      {
+        "name": "--surface-muted",
+        "tier": "semantic",
+        "description": "Semantic surface: muted",
+        "defaultLight": "var(--color-neutral-100)",
+        "defaultDark": "var(--color-neutral-100)"
+      },
+      {
+        "name": "--surface-overlay",
+        "tier": "semantic",
+        "description": "Semantic surface: overlay",
+        "defaultLight": "var(--color-neutral-900)",
+        "defaultDark": "var(--color-neutral-900)"
+      },
+      {
+        "name": "--surface-popover",
+        "tier": "semantic",
+        "description": "Semantic surface: popover",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--surface-interactive-default",
+        "tier": "semantic",
+        "description": "Semantic surface: interactive-default",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--surface-interactive-hover",
+        "tier": "semantic",
+        "description": "Semantic surface: interactive-hover",
+        "defaultLight": "var(--color-neutral-50)",
+        "defaultDark": "var(--color-neutral-50)"
+      },
+      {
+        "name": "--surface-interactive-active",
+        "tier": "semantic",
+        "description": "Semantic surface: interactive-active",
+        "defaultLight": "var(--color-neutral-100)",
+        "defaultDark": "var(--color-neutral-100)"
+      },
+      {
+        "name": "--surface-interactive-disabled",
+        "tier": "semantic",
+        "description": "Semantic surface: interactive-disabled",
+        "defaultLight": "var(--color-neutral-50)",
+        "defaultDark": "var(--color-neutral-50)"
+      },
+      {
+        "name": "--surface-accent-subtle",
+        "tier": "semantic",
+        "description": "Semantic surface: accent-subtle",
+        "defaultLight": "var(--color-primary-50)",
+        "defaultDark": "var(--color-primary-50)"
+      },
+      {
+        "name": "--surface-accent-default",
+        "tier": "semantic",
+        "description": "Semantic surface: accent-default",
+        "defaultLight": "var(--color-primary-500)",
+        "defaultDark": "var(--color-primary-500)"
+      },
+      {
+        "name": "--surface-accent-strong",
+        "tier": "semantic",
+        "description": "Semantic surface: accent-strong",
+        "defaultLight": "var(--color-primary-600)",
+        "defaultDark": "var(--color-primary-600)"
+      },
+      {
+        "name": "--surface-success-subtle",
+        "tier": "semantic",
+        "description": "Semantic surface: success-subtle",
+        "defaultLight": "var(--color-success-50)",
+        "defaultDark": "var(--color-success-50)"
+      },
+      {
+        "name": "--surface-success-default",
+        "tier": "semantic",
+        "description": "Semantic surface: success-default",
+        "defaultLight": "var(--color-success-500)",
+        "defaultDark": "var(--color-success-500)"
+      },
+      {
+        "name": "--surface-warning-subtle",
+        "tier": "semantic",
+        "description": "Semantic surface: warning-subtle",
+        "defaultLight": "var(--color-warning-50)",
+        "defaultDark": "var(--color-warning-50)"
+      },
+      {
+        "name": "--surface-warning-default",
+        "tier": "semantic",
+        "description": "Semantic surface: warning-default",
+        "defaultLight": "var(--color-warning-500)",
+        "defaultDark": "var(--color-warning-500)"
+      },
+      {
+        "name": "--surface-error-subtle",
+        "tier": "semantic",
+        "description": "Semantic surface: error-subtle",
+        "defaultLight": "var(--color-error-50)",
+        "defaultDark": "var(--color-error-50)"
+      },
+      {
+        "name": "--surface-error-default",
+        "tier": "semantic",
+        "description": "Semantic surface: error-default",
+        "defaultLight": "var(--color-error-500)",
+        "defaultDark": "var(--color-error-500)"
+      },
+      {
+        "name": "--surface-info-subtle",
+        "tier": "semantic",
+        "description": "Semantic surface: info-subtle",
+        "defaultLight": "var(--color-info-50)",
+        "defaultDark": "var(--color-info-50)"
+      },
+      {
+        "name": "--surface-info-default",
+        "tier": "semantic",
+        "description": "Semantic surface: info-default",
+        "defaultLight": "var(--color-info-500)",
+        "defaultDark": "var(--color-info-500)"
+      },
+      {
+        "name": "--border-default",
+        "tier": "semantic",
+        "description": "Semantic border: default",
+        "defaultLight": "var(--color-neutral-200)",
+        "defaultDark": "var(--color-neutral-200)"
+      },
+      {
+        "name": "--border-muted",
+        "tier": "semantic",
+        "description": "Semantic border: muted",
+        "defaultLight": "var(--color-neutral-100)",
+        "defaultDark": "var(--color-neutral-100)"
+      },
+      {
+        "name": "--border-strong",
+        "tier": "semantic",
+        "description": "Semantic border: strong",
+        "defaultLight": "var(--color-neutral-300)",
+        "defaultDark": "var(--color-neutral-300)"
+      },
+      {
+        "name": "--border-focus",
+        "tier": "semantic",
+        "description": "Semantic border: focus",
+        "defaultLight": "var(--color-primary-500)",
+        "defaultDark": "var(--color-primary-500)"
+      },
+      {
+        "name": "--border-disabled",
+        "tier": "semantic",
+        "description": "Semantic border: disabled",
+        "defaultLight": "var(--color-neutral-100)",
+        "defaultDark": "var(--color-neutral-100)"
+      },
+      {
+        "name": "--border-input",
+        "tier": "semantic",
+        "description": "Semantic border: input",
+        "defaultLight": "var(--color-neutral-200)",
+        "defaultDark": "var(--color-neutral-200)"
+      },
+      {
+        "name": "--border-success",
+        "tier": "semantic",
+        "description": "Semantic border: success",
+        "defaultLight": "var(--color-success-500)",
+        "defaultDark": "var(--color-success-500)"
+      },
+      {
+        "name": "--border-warning",
+        "tier": "semantic",
+        "description": "Semantic border: warning",
+        "defaultLight": "var(--color-warning-500)",
+        "defaultDark": "var(--color-warning-500)"
+      },
+      {
+        "name": "--border-error",
+        "tier": "semantic",
+        "description": "Semantic border: error",
+        "defaultLight": "var(--color-error-500)",
+        "defaultDark": "var(--color-error-500)"
+      },
+      {
+        "name": "--border-info",
+        "tier": "semantic",
+        "description": "Semantic border: info",
+        "defaultLight": "var(--color-info-500)",
+        "defaultDark": "var(--color-info-500)"
+      },
+      {
+        "name": "--interactive-primary-bg",
+        "tier": "semantic",
+        "description": "Semantic interactive: primary-bg",
+        "defaultLight": "var(--color-primary-600)",
+        "defaultDark": "var(--color-primary-600)"
+      },
+      {
+        "name": "--interactive-primary-bg-hover",
+        "tier": "semantic",
+        "description": "Semantic interactive: primary-bg-hover",
+        "defaultLight": "var(--color-primary-700)",
+        "defaultDark": "var(--color-primary-700)"
+      },
+      {
+        "name": "--interactive-primary-bg-active",
+        "tier": "semantic",
+        "description": "Semantic interactive: primary-bg-active",
+        "defaultLight": "var(--color-primary-800)",
+        "defaultDark": "var(--color-primary-800)"
+      },
+      {
+        "name": "--interactive-primary-text",
+        "tier": "semantic",
+        "description": "Semantic interactive: primary-text",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--interactive-secondary-bg",
+        "tier": "semantic",
+        "description": "Semantic interactive: secondary-bg",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--interactive-secondary-bg-hover",
+        "tier": "semantic",
+        "description": "Semantic interactive: secondary-bg-hover",
+        "defaultLight": "var(--color-neutral-50)",
+        "defaultDark": "var(--color-neutral-50)"
+      },
+      {
+        "name": "--interactive-secondary-bg-active",
+        "tier": "semantic",
+        "description": "Semantic interactive: secondary-bg-active",
+        "defaultLight": "var(--color-neutral-100)",
+        "defaultDark": "var(--color-neutral-100)"
+      },
+      {
+        "name": "--interactive-secondary-text",
+        "tier": "semantic",
+        "description": "Semantic interactive: secondary-text",
+        "defaultLight": "var(--color-neutral-900)",
+        "defaultDark": "var(--color-neutral-900)"
+      },
+      {
+        "name": "--interactive-secondary-border",
+        "tier": "semantic",
+        "description": "Semantic interactive: secondary-border",
+        "defaultLight": "var(--color-neutral-300)",
+        "defaultDark": "var(--color-neutral-300)"
+      },
+      {
+        "name": "--interactive-destructive-bg",
+        "tier": "semantic",
+        "description": "Semantic interactive: destructive-bg",
+        "defaultLight": "var(--color-error-600)",
+        "defaultDark": "var(--color-error-600)"
+      },
+      {
+        "name": "--interactive-destructive-bg-hover",
+        "tier": "semantic",
+        "description": "Semantic interactive: destructive-bg-hover",
+        "defaultLight": "var(--color-error-700)",
+        "defaultDark": "var(--color-error-700)"
+      },
+      {
+        "name": "--interactive-destructive-text",
+        "tier": "semantic",
+        "description": "Semantic interactive: destructive-text",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--interactive-ghost-bg",
+        "tier": "semantic",
+        "description": "Semantic interactive: ghost-bg",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--interactive-ghost-bg-hover",
+        "tier": "semantic",
+        "description": "Semantic interactive: ghost-bg-hover",
+        "defaultLight": "var(--color-neutral-100)",
+        "defaultDark": "var(--color-neutral-100)"
+      },
+      {
+        "name": "--component-xs",
+        "tier": "semantic",
+        "description": "Semantic spacing: component-xs",
+        "defaultLight": "var(--spacing-1)",
+        "defaultDark": "var(--spacing-1)"
+      },
+      {
+        "name": "--component-sm",
+        "tier": "semantic",
+        "description": "Semantic spacing: component-sm",
+        "defaultLight": "var(--spacing-2)",
+        "defaultDark": "var(--spacing-2)"
+      },
+      {
+        "name": "--component-md",
+        "tier": "semantic",
+        "description": "Semantic spacing: component-md",
+        "defaultLight": "var(--spacing-4)",
+        "defaultDark": "var(--spacing-4)"
+      },
+      {
+        "name": "--component-lg",
+        "tier": "semantic",
+        "description": "Semantic spacing: component-lg",
+        "defaultLight": "var(--spacing-6)",
+        "defaultDark": "var(--spacing-6)"
+      },
+      {
+        "name": "--component-xl",
+        "tier": "semantic",
+        "description": "Semantic spacing: component-xl",
+        "defaultLight": "var(--spacing-8)",
+        "defaultDark": "var(--spacing-8)"
+      },
+      {
+        "name": "--layout-sm",
+        "tier": "semantic",
+        "description": "Semantic spacing: layout-sm",
+        "defaultLight": "var(--spacing-4)",
+        "defaultDark": "var(--spacing-4)"
+      },
+      {
+        "name": "--layout-md",
+        "tier": "semantic",
+        "description": "Semantic spacing: layout-md",
+        "defaultLight": "var(--spacing-8)",
+        "defaultDark": "var(--spacing-8)"
+      },
+      {
+        "name": "--layout-lg",
+        "tier": "semantic",
+        "description": "Semantic spacing: layout-lg",
+        "defaultLight": "var(--spacing-12)",
+        "defaultDark": "var(--spacing-12)"
+      },
+      {
+        "name": "--layout-xl",
+        "tier": "semantic",
+        "description": "Semantic spacing: layout-xl",
+        "defaultLight": "var(--spacing-16)",
+        "defaultDark": "var(--spacing-16)"
+      },
+      {
+        "name": "--layout-2xl",
+        "tier": "semantic",
+        "description": "Semantic spacing: layout-2xl",
+        "defaultLight": "var(--spacing-24)",
+        "defaultDark": "var(--spacing-24)"
+      },
+      {
+        "name": "--motion-duration-fast",
+        "tier": "semantic",
+        "description": "Semantic motion duration: fast",
+        "defaultLight": "var(--motion-duration-100)",
+        "defaultDark": "var(--motion-duration-100)"
+      },
+      {
+        "name": "--motion-duration-normal",
+        "tier": "semantic",
+        "description": "Semantic motion duration: normal",
+        "defaultLight": "var(--motion-duration-200)",
+        "defaultDark": "var(--motion-duration-200)"
+      },
+      {
+        "name": "--motion-duration-slow",
+        "tier": "semantic",
+        "description": "Semantic motion duration: slow",
+        "defaultLight": "var(--motion-duration-500)",
+        "defaultDark": "var(--motion-duration-500)"
+      },
+      {
+        "name": "--motion-easing-default",
+        "tier": "semantic",
+        "description": "Semantic motion easing: default",
+        "defaultLight": "var(--motion-easing-ease-in-out)",
+        "defaultDark": "var(--motion-easing-ease-in-out)"
+      },
+      {
+        "name": "--motion-easing-enter",
+        "tier": "semantic",
+        "description": "Semantic motion easing: enter",
+        "defaultLight": "var(--motion-easing-ease-out)",
+        "defaultDark": "var(--motion-easing-ease-out)"
+      },
+      {
+        "name": "--motion-easing-exit",
+        "tier": "semantic",
+        "description": "Semantic motion easing: exit",
+        "defaultLight": "var(--motion-easing-ease-in)",
+        "defaultDark": "var(--motion-easing-ease-in)"
+      },
+      {
+        "name": "--motion-easing-spring",
+        "tier": "semantic",
+        "description": "Semantic motion easing: spring",
+        "defaultLight": "var(--motion-easing-spring)",
+        "defaultDark": "var(--motion-easing-spring)"
+      },
+      {
+        "name": "--font-body",
+        "tier": "semantic",
+        "description": "Semantic typography: font-body",
+        "defaultLight": "var(--font-sans)",
+        "defaultDark": "var(--font-sans)"
+      },
+      {
+        "name": "--font-heading",
+        "tier": "semantic",
+        "description": "Semantic typography: font-heading",
+        "defaultLight": "var(--font-sans)",
+        "defaultDark": "var(--font-sans)"
+      },
+      {
+        "name": "--font-mono",
+        "tier": "semantic",
+        "description": "Semantic typography: font-mono",
+        "defaultLight": "var(--font-mono)",
+        "defaultDark": "var(--font-mono)"
+      },
+      {
+        "name": "--size-body",
+        "tier": "semantic",
+        "description": "Semantic typography: size-body",
+        "defaultLight": "var(--font-size-base)",
+        "defaultDark": "var(--font-size-base)"
+      },
+      {
+        "name": "--size-body-sm",
+        "tier": "semantic",
+        "description": "Semantic typography: size-body-sm",
+        "defaultLight": "var(--font-size-sm)",
+        "defaultDark": "var(--font-size-sm)"
+      },
+      {
+        "name": "--size-label",
+        "tier": "semantic",
+        "description": "Semantic typography: size-label",
+        "defaultLight": "var(--font-size-sm)",
+        "defaultDark": "var(--font-size-sm)"
+      },
+      {
+        "name": "--size-caption",
+        "tier": "semantic",
+        "description": "Semantic typography: size-caption",
+        "defaultLight": "var(--font-size-xs)",
+        "defaultDark": "var(--font-size-xs)"
+      },
+      {
+        "name": "--size-heading-sm",
+        "tier": "semantic",
+        "description": "Semantic typography: size-heading-sm",
+        "defaultLight": "var(--font-size-lg)",
+        "defaultDark": "var(--font-size-lg)"
+      },
+      {
+        "name": "--size-heading-md",
+        "tier": "semantic",
+        "description": "Semantic typography: size-heading-md",
+        "defaultLight": "var(--font-size-xl)",
+        "defaultDark": "var(--font-size-xl)"
+      },
+      {
+        "name": "--size-heading-lg",
+        "tier": "semantic",
+        "description": "Semantic typography: size-heading-lg",
+        "defaultLight": "var(--font-size-2xl)",
+        "defaultDark": "var(--font-size-2xl)"
+      },
+      {
+        "name": "--size-heading-xl",
+        "tier": "semantic",
+        "description": "Semantic typography: size-heading-xl",
+        "defaultLight": "var(--font-size-3xl)",
+        "defaultDark": "var(--font-size-3xl)"
+      },
+      {
+        "name": "--weight-body",
+        "tier": "semantic",
+        "description": "Semantic typography: weight-body",
+        "defaultLight": "var(--font-weight-normal)",
+        "defaultDark": "var(--font-weight-normal)"
+      },
+      {
+        "name": "--weight-label",
+        "tier": "semantic",
+        "description": "Semantic typography: weight-label",
+        "defaultLight": "var(--font-weight-medium)",
+        "defaultDark": "var(--font-weight-medium)"
+      },
+      {
+        "name": "--weight-heading",
+        "tier": "semantic",
+        "description": "Semantic typography: weight-heading",
+        "defaultLight": "var(--font-weight-semibold)",
+        "defaultDark": "var(--font-weight-semibold)"
+      },
+      {
+        "name": "--weight-strong",
+        "tier": "semantic",
+        "description": "Semantic typography: weight-strong",
+        "defaultLight": "var(--font-weight-bold)",
+        "defaultDark": "var(--font-weight-bold)"
+      },
+      {
+        "name": "--skeleton-from",
+        "tier": "semantic",
+        "description": "Semantic skeleton shimmer: from",
+        "defaultLight": "var(--surface-muted)",
+        "defaultDark": "var(--surface-muted)"
+      },
+      {
+        "name": "--skeleton-to",
+        "tier": "semantic",
+        "description": "Semantic skeleton shimmer: to",
+        "defaultLight": "var(--surface-subtle)",
+        "defaultDark": "var(--surface-subtle)"
+      },
+      {
+        "name": "--chart-1",
+        "tier": "semantic",
+        "description": "Semantic chart color 1",
+        "defaultLight": "var(--color-primary-500)",
+        "defaultDark": "var(--color-primary-500)"
+      },
+      {
+        "name": "--chart-2",
+        "tier": "semantic",
+        "description": "Semantic chart color 2",
+        "defaultLight": "var(--color-success-500)",
+        "defaultDark": "var(--color-success-500)"
+      },
+      {
+        "name": "--chart-3",
+        "tier": "semantic",
+        "description": "Semantic chart color 3",
+        "defaultLight": "var(--color-warning-500)",
+        "defaultDark": "var(--color-warning-500)"
+      },
+      {
+        "name": "--chart-4",
+        "tier": "semantic",
+        "description": "Semantic chart color 4",
+        "defaultLight": "var(--color-info-500)",
+        "defaultDark": "var(--color-info-500)"
+      },
+      {
+        "name": "--chart-5",
+        "tier": "semantic",
+        "description": "Semantic chart color 5",
+        "defaultLight": "var(--color-error-500)",
+        "defaultDark": "var(--color-error-500)"
+      },
+      {
+        "name": "--sidebar-bg",
+        "tier": "semantic",
+        "description": "Semantic sidebar: bg",
+        "defaultLight": "var(--color-neutral-50)",
+        "defaultDark": "var(--color-neutral-50)"
+      },
+      {
+        "name": "--sidebar-text",
+        "tier": "semantic",
+        "description": "Semantic sidebar: text",
+        "defaultLight": "var(--color-neutral-700)",
+        "defaultDark": "var(--color-neutral-700)"
+      },
+      {
+        "name": "--sidebar-primary-bg",
+        "tier": "semantic",
+        "description": "Semantic sidebar: primary-bg",
+        "defaultLight": "var(--color-primary-600)",
+        "defaultDark": "var(--color-primary-600)"
+      },
+      {
+        "name": "--sidebar-primary-text",
+        "tier": "semantic",
+        "description": "Semantic sidebar: primary-text",
+        "defaultLight": "var(--color-white)",
+        "defaultDark": "var(--color-white)"
+      },
+      {
+        "name": "--sidebar-accent-bg",
+        "tier": "semantic",
+        "description": "Semantic sidebar: accent-bg",
+        "defaultLight": "var(--color-neutral-100)",
+        "defaultDark": "var(--color-neutral-100)"
+      },
+      {
+        "name": "--sidebar-accent-text",
+        "tier": "semantic",
+        "description": "Semantic sidebar: accent-text",
+        "defaultLight": "var(--color-neutral-900)",
+        "defaultDark": "var(--color-neutral-900)"
+      },
+      {
+        "name": "--sidebar-border",
+        "tier": "semantic",
+        "description": "Semantic sidebar: border",
+        "defaultLight": "var(--color-neutral-200)",
+        "defaultDark": "var(--color-neutral-200)"
+      },
+      {
+        "name": "--sidebar-ring",
+        "tier": "semantic",
+        "description": "Semantic sidebar: ring",
+        "defaultLight": "var(--color-primary-500)",
+        "defaultDark": "var(--color-primary-500)"
+      },
+      {
+        "name": "--sidebar-text-muted",
+        "tier": "semantic",
+        "description": "Semantic sidebar: text-muted",
+        "defaultLight": "var(--color-neutral-500)",
+        "defaultDark": "var(--color-neutral-500)"
+      }
     ],
-    "layout": [
-      "collapsible",
-      "scroll-area",
-      "separator",
-      "sidebar"
+    "adaptive": [
+      {
+        "name": "--text-primary",
+        "tier": "adaptive",
+        "description": "Adaptive text: primary",
+        "defaultLight": "#111827",
+        "defaultDark": "#f9fafb"
+      },
+      {
+        "name": "--text-secondary",
+        "tier": "adaptive",
+        "description": "Adaptive text: secondary",
+        "defaultLight": "#4b5563",
+        "defaultDark": "#9ca3af"
+      },
+      {
+        "name": "--text-tertiary",
+        "tier": "adaptive",
+        "description": "Adaptive text: tertiary",
+        "defaultLight": "#9ca3af",
+        "defaultDark": "#6b7280"
+      },
+      {
+        "name": "--text-disabled",
+        "tier": "adaptive",
+        "description": "Adaptive text: disabled",
+        "defaultLight": "#d1d5db",
+        "defaultDark": "#4b5563"
+      },
+      {
+        "name": "--text-inverse",
+        "tier": "adaptive",
+        "description": "Adaptive text: inverse",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#111827"
+      },
+      {
+        "name": "--text-inverse-secondary",
+        "tier": "adaptive",
+        "description": "Adaptive text: inverse-secondary",
+        "defaultLight": "#e5e7eb",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--text-link",
+        "tier": "adaptive",
+        "description": "Adaptive text: link",
+        "defaultLight": "#2563eb",
+        "defaultDark": "#60a5fa"
+      },
+      {
+        "name": "--text-link-hover",
+        "tier": "adaptive",
+        "description": "Adaptive text: link-hover",
+        "defaultLight": "#1d4ed8",
+        "defaultDark": "#93c5fd"
+      },
+      {
+        "name": "--text-success",
+        "tier": "adaptive",
+        "description": "Adaptive text: success",
+        "defaultLight": "#15803d",
+        "defaultDark": "#22c55e"
+      },
+      {
+        "name": "--text-warning",
+        "tier": "adaptive",
+        "description": "Adaptive text: warning",
+        "defaultLight": "#b45309",
+        "defaultDark": "#f59e0b"
+      },
+      {
+        "name": "--text-error",
+        "tier": "adaptive",
+        "description": "Adaptive text: error",
+        "defaultLight": "#b91c1c",
+        "defaultDark": "#ef4444"
+      },
+      {
+        "name": "--text-info",
+        "tier": "adaptive",
+        "description": "Adaptive text: info",
+        "defaultLight": "#0369a1",
+        "defaultDark": "#0ea5e9"
+      },
+      {
+        "name": "--surface-page",
+        "tier": "adaptive",
+        "description": "Adaptive surface: page",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#030712"
+      },
+      {
+        "name": "--surface-card",
+        "tier": "adaptive",
+        "description": "Adaptive surface: card",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#111827"
+      },
+      {
+        "name": "--surface-subtle",
+        "tier": "adaptive",
+        "description": "Adaptive surface: subtle",
+        "defaultLight": "#f9fafb",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--surface-muted",
+        "tier": "adaptive",
+        "description": "Adaptive surface: muted",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--surface-overlay",
+        "tier": "adaptive",
+        "description": "Adaptive surface: overlay",
+        "defaultLight": "#111827",
+        "defaultDark": "#030712"
+      },
+      {
+        "name": "--surface-popover",
+        "tier": "adaptive",
+        "description": "Adaptive surface: popover",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#111827"
+      },
+      {
+        "name": "--surface-interactive-default",
+        "tier": "adaptive",
+        "description": "Adaptive surface: interactive-default",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--surface-interactive-hover",
+        "tier": "adaptive",
+        "description": "Adaptive surface: interactive-hover",
+        "defaultLight": "#f9fafb",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--surface-interactive-active",
+        "tier": "adaptive",
+        "description": "Adaptive surface: interactive-active",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#4b5563"
+      },
+      {
+        "name": "--surface-interactive-disabled",
+        "tier": "adaptive",
+        "description": "Adaptive surface: interactive-disabled",
+        "defaultLight": "#f9fafb",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--surface-accent-subtle",
+        "tier": "adaptive",
+        "description": "Adaptive surface: accent-subtle",
+        "defaultLight": "#eff6ff",
+        "defaultDark": "#1e3a8a"
+      },
+      {
+        "name": "--surface-accent-default",
+        "tier": "adaptive",
+        "description": "Adaptive surface: accent-default",
+        "defaultLight": "#3b82f6",
+        "defaultDark": "#3b82f6"
+      },
+      {
+        "name": "--surface-accent-strong",
+        "tier": "adaptive",
+        "description": "Adaptive surface: accent-strong",
+        "defaultLight": "#2563eb",
+        "defaultDark": "#60a5fa"
+      },
+      {
+        "name": "--surface-success-subtle",
+        "tier": "adaptive",
+        "description": "Adaptive surface: success-subtle",
+        "defaultLight": "#f0fdf4",
+        "defaultDark": "#14532d"
+      },
+      {
+        "name": "--surface-success-default",
+        "tier": "adaptive",
+        "description": "Adaptive surface: success-default",
+        "defaultLight": "#22c55e",
+        "defaultDark": "#22c55e"
+      },
+      {
+        "name": "--surface-warning-subtle",
+        "tier": "adaptive",
+        "description": "Adaptive surface: warning-subtle",
+        "defaultLight": "#fffbeb",
+        "defaultDark": "#78350f"
+      },
+      {
+        "name": "--surface-warning-default",
+        "tier": "adaptive",
+        "description": "Adaptive surface: warning-default",
+        "defaultLight": "#f59e0b",
+        "defaultDark": "#f59e0b"
+      },
+      {
+        "name": "--surface-error-subtle",
+        "tier": "adaptive",
+        "description": "Adaptive surface: error-subtle",
+        "defaultLight": "#fef2f2",
+        "defaultDark": "#7f1d1d"
+      },
+      {
+        "name": "--surface-error-default",
+        "tier": "adaptive",
+        "description": "Adaptive surface: error-default",
+        "defaultLight": "#ef4444",
+        "defaultDark": "#ef4444"
+      },
+      {
+        "name": "--surface-info-subtle",
+        "tier": "adaptive",
+        "description": "Adaptive surface: info-subtle",
+        "defaultLight": "#f0f9ff",
+        "defaultDark": "#0c4a6e"
+      },
+      {
+        "name": "--surface-info-default",
+        "tier": "adaptive",
+        "description": "Adaptive surface: info-default",
+        "defaultLight": "#0ea5e9",
+        "defaultDark": "#0ea5e9"
+      },
+      {
+        "name": "--border-default",
+        "tier": "adaptive",
+        "description": "Adaptive border: default",
+        "defaultLight": "#e5e7eb",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--border-muted",
+        "tier": "adaptive",
+        "description": "Adaptive border: muted",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--border-strong",
+        "tier": "adaptive",
+        "description": "Adaptive border: strong",
+        "defaultLight": "#d1d5db",
+        "defaultDark": "#4b5563"
+      },
+      {
+        "name": "--border-focus",
+        "tier": "adaptive",
+        "description": "Adaptive border: focus",
+        "defaultLight": "#3b82f6",
+        "defaultDark": "#60a5fa"
+      },
+      {
+        "name": "--border-disabled",
+        "tier": "adaptive",
+        "description": "Adaptive border: disabled",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--border-input",
+        "tier": "adaptive",
+        "description": "Adaptive border: input",
+        "defaultLight": "#e5e7eb",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--border-success",
+        "tier": "adaptive",
+        "description": "Adaptive border: success",
+        "defaultLight": "#22c55e",
+        "defaultDark": "#22c55e"
+      },
+      {
+        "name": "--border-warning",
+        "tier": "adaptive",
+        "description": "Adaptive border: warning",
+        "defaultLight": "#f59e0b",
+        "defaultDark": "#f59e0b"
+      },
+      {
+        "name": "--border-error",
+        "tier": "adaptive",
+        "description": "Adaptive border: error",
+        "defaultLight": "#ef4444",
+        "defaultDark": "#ef4444"
+      },
+      {
+        "name": "--border-info",
+        "tier": "adaptive",
+        "description": "Adaptive border: info",
+        "defaultLight": "#0ea5e9",
+        "defaultDark": "#0ea5e9"
+      },
+      {
+        "name": "--interactive-primary-bg",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: primary-bg",
+        "defaultLight": "#2563eb",
+        "defaultDark": "#3b82f6"
+      },
+      {
+        "name": "--interactive-primary-bg-hover",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: primary-bg-hover",
+        "defaultLight": "#1d4ed8",
+        "defaultDark": "#60a5fa"
+      },
+      {
+        "name": "--interactive-primary-bg-active",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: primary-bg-active",
+        "defaultLight": "#1e40af",
+        "defaultDark": "#93c5fd"
+      },
+      {
+        "name": "--interactive-primary-text",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: primary-text",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#ffffff"
+      },
+      {
+        "name": "--interactive-secondary-bg",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: secondary-bg",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--interactive-secondary-bg-hover",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: secondary-bg-hover",
+        "defaultLight": "#f9fafb",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--interactive-secondary-bg-active",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: secondary-bg-active",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#4b5563"
+      },
+      {
+        "name": "--interactive-secondary-text",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: secondary-text",
+        "defaultLight": "#111827",
+        "defaultDark": "#f9fafb"
+      },
+      {
+        "name": "--interactive-secondary-border",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: secondary-border",
+        "defaultLight": "#d1d5db",
+        "defaultDark": "#4b5563"
+      },
+      {
+        "name": "--interactive-destructive-bg",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: destructive-bg",
+        "defaultLight": "#dc2626",
+        "defaultDark": "#ef4444"
+      },
+      {
+        "name": "--interactive-destructive-bg-hover",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: destructive-bg-hover",
+        "defaultLight": "#b91c1c",
+        "defaultDark": "#dc2626"
+      },
+      {
+        "name": "--interactive-destructive-text",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: destructive-text",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#ffffff"
+      },
+      {
+        "name": "--interactive-ghost-bg",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: ghost-bg",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--interactive-ghost-bg-hover",
+        "tier": "adaptive",
+        "description": "Adaptive interactive: ghost-bg-hover",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--skeleton-from",
+        "tier": "adaptive",
+        "description": "Adaptive skeleton shimmer: from",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--skeleton-to",
+        "tier": "adaptive",
+        "description": "Adaptive skeleton shimmer: to",
+        "defaultLight": "#e5e7eb",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--chart-1",
+        "tier": "adaptive",
+        "description": "Adaptive chart color 1",
+        "defaultLight": "#3b82f6",
+        "defaultDark": "#60a5fa"
+      },
+      {
+        "name": "--chart-2",
+        "tier": "adaptive",
+        "description": "Adaptive chart color 2",
+        "defaultLight": "#22c55e",
+        "defaultDark": "#22c55e"
+      },
+      {
+        "name": "--chart-3",
+        "tier": "adaptive",
+        "description": "Adaptive chart color 3",
+        "defaultLight": "#f59e0b",
+        "defaultDark": "#f59e0b"
+      },
+      {
+        "name": "--chart-4",
+        "tier": "adaptive",
+        "description": "Adaptive chart color 4",
+        "defaultLight": "#0ea5e9",
+        "defaultDark": "#0ea5e9"
+      },
+      {
+        "name": "--chart-5",
+        "tier": "adaptive",
+        "description": "Adaptive chart color 5",
+        "defaultLight": "#ef4444",
+        "defaultDark": "#ef4444"
+      },
+      {
+        "name": "--sidebar-bg",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: bg",
+        "defaultLight": "#f9fafb",
+        "defaultDark": "#111827"
+      },
+      {
+        "name": "--sidebar-text",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: text",
+        "defaultLight": "#374151",
+        "defaultDark": "#d1d5db"
+      },
+      {
+        "name": "--sidebar-primary-bg",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: primary-bg",
+        "defaultLight": "#2563eb",
+        "defaultDark": "#3b82f6"
+      },
+      {
+        "name": "--sidebar-primary-text",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: primary-text",
+        "defaultLight": "#ffffff",
+        "defaultDark": "#ffffff"
+      },
+      {
+        "name": "--sidebar-accent-bg",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: accent-bg",
+        "defaultLight": "#f3f4f6",
+        "defaultDark": "#1f2937"
+      },
+      {
+        "name": "--sidebar-accent-text",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: accent-text",
+        "defaultLight": "#111827",
+        "defaultDark": "#f9fafb"
+      },
+      {
+        "name": "--sidebar-border",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: border",
+        "defaultLight": "#e5e7eb",
+        "defaultDark": "#374151"
+      },
+      {
+        "name": "--sidebar-ring",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: ring",
+        "defaultLight": "#3b82f6",
+        "defaultDark": "#60a5fa"
+      },
+      {
+        "name": "--sidebar-text-muted",
+        "tier": "adaptive",
+        "description": "Adaptive sidebar: text-muted",
+        "defaultLight": "#6b7280",
+        "defaultDark": "#9ca3af"
+      }
     ],
-    "overlay": [
-      "context-menu",
-      "dialog",
-      "dropdown-menu",
-      "fullscreen-overlay",
-      "hover-card",
-      "menubar",
-      "sheet"
-    ]
+    "summary": {
+      "total": 298
+    }
   }
 }