@vadimcomanescu/nadicode-design-system 2.0.0 → 2.0.2

package/.agents/skills/seed/SKILL.md

@@ -18,14 +18,25 @@ In consumer apps, Seed runtime normally comes from an exact released `@vadimcoma
 
 Consumer scaffold contract: brand customization stays palette-only unless the task is explicitly DS development. In seeded apps, edit seed-palette.css in the app src/ root for brand colors. Do not tell consumers to edit the package tokens stylesheet, `src/lib/tokens.config.js`, or font/layout wiring as part of normal branding.
 
+## Component Discovery
+
+For exact component names, variant values, props, and tiers, read the machine-readable catalog:
+
+```
+cat node_modules/@vadimcomanescu/nadicode-design-system/dist/catalog.json
+```
+
+The catalog is auto-generated from source and always accurate. Use exact variant names from the catalog. Do not guess.
+
 ## Read Order
 
 1. **This file** -- router, quick references, forbidden patterns
 2. **`contract.md`** -- binary rules, package integration contract
-3. **`intent-map.md`** -- intent decision tree + recipe index
-4. **`recipes/<page-type>.md`** -- matching recipe for your page
-5. **`references/`** -- deep dives as needed
-6. **`references/brand-override.md`** -- palette-only brand customization guide for seeded apps
+3. **catalog.json** (in dist/) -- machine-readable component metadata (variants, props, tiers)
+4. **`intent-map.md`** -- intent decision tree + recipe index
+5. **`recipes/<page-type>.md`** -- matching recipe for your page
+6. **`references/`** -- deep dives as needed
+7. **`references/brand-override.md`** -- palette-only brand customization guide for seeded apps
 
 ---
 

package/.agents/skills/seed/contract.md

@@ -7,6 +7,10 @@ Binary rules for consumer apps using the Seed Design System. Every rule is non-n
 - Apply only to the explicit migration scope you were given.
 - Do not edit files outside scope unless the build is blocked by a required wiring step.
 
+## Component Catalog
+
+Read catalog.json (shipped in the package under dist/) for the authoritative list of components, variant names, props, and tiers. Verify component names and variant values against the catalog. Do not guess variant names or prop values.
+
 ## Import Rules
 
 1. Import Seed primitives, blocks, charts, icons, and text effects from `@vadimcomanescu/nadicode-design-system/*` subpaths. Do not vendor or recreate DS runtime files inside the scaffold.

package/.agents/skills/seed/references/blocks.md

@@ -8,101 +8,103 @@ Run `npm run docs:inventory` for the current filesystem-backed list.
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| LoginBlock | Email/password login with social OAuth | `type`, `variant`, `showSocial`, `title`, `description`, `onLogin`, `googleAction`, `forgotPasswordHref`, `signUpHref`, `signInHref` |
-| SignUpBlock | Registration form | `onSubmit`, `showSocial` |
-| PasswordRecoveryBlock | Password reset request | `onSubmit` |
-| ResetPasswordBlock | New password entry (from email link) | `onSubmit` |
-| TwoFactorChallengeBlock | 2FA code entry challenge | `onVerify` |
-| TwoFactorSetupBlock | 2FA setup with QR code | `qrCodeUrl`, `secret` |
-| AccountLockedBlock | Account locked notification | `onContact`, `reason` |
-| AuthSuccessBlock | Generic auth success state | `title`, `description`, `onContinue` |
-| AuthLayout | Split-screen auth layout wrapper | `children` |
+| AccountLockedBlock | Account locked notification | `reason`, `unlockMinutes`, `onContactSupport`, `onBackToLogin`, `title`, `description` |
+| AuthLayout | Split-screen auth layout wrapper | `mode`, `action`, `error`, `googleAction`, `labels` |
+| AuthSuccessBlock | Generic auth success state | `icon`, `title`, `description`, `buttonText`, `onContinue`, `autoRedirectSeconds` |
+| LoginBlock | Email/password login with social OAuth | `type`, `showSocial`, `labels`, `action`, `error`, `onLogin`, `googleAction`, `forgotPasswordHref`, `signUpHref`, `signInHref` |
+| PasswordRecoveryBlock | Password reset request | `mode`, `onSubmit`, `onBackToLogin`, `title`, `description`, `buttonText`, `successTitle` |
+| ResetPasswordBlock | New password entry (from email link) | `onSubmit`, `onBackToLogin`, `title`, `description` |
+| SignUpBlock | Registration form | `title`, `description`, `showSocial`, `signInHref`, `onSubmit` |
+| TwoFactorChallengeBlock | 2FA code entry challenge | `onVerify`, `onUseBackupCode`, `onBackToLogin`, `error`, `title`, `description`, `backupCodeLabel` |
+| TwoFactorSetupBlock | 2FA setup with QR code | `qrCodeUrl`, `secret`, `backupCodes`, `onVerify`, `onComplete`, `title`, `description` |
 
 ## Marketing
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| HeroBlock | Full hero with gradient text | `title`, `subtitle`, `cta` |
-| HeroSectionBlock | Alternate hero layout | `title`, `description`, `actions` |
-| FeatureBlock | Single feature showcase | `title`, `description`, `icon` |
-| FeatureGridBlock | Multi-feature grid layout | `features: Array<{title, description, icon}>` |
-| PricingBlock | Pricing cards comparison | `plans: Array<Plan>` |
-| TestimonialsBlock | Customer testimonial carousel/grid | `testimonials: Array<Testimonial>` |
-| CallToActionBlock | Call-to-action section | `title`, `description`, `action` |
-| FAQBlock | FAQ accordion | `items: Array<{question, answer}>` |
-| ComparisonBlock | Side-by-side feature comparison | `items` |
-| SocialProofBlock | Social proof metrics/logos | `metrics`, `logos` |
-| StatsMarketingBlock | Marketing statistics display | `stats: Array<{label, value}>` |
-| LogoCloud | Partner/client logo grid | `logos: Array<{src, alt}>` |
-| ProcessFlowBlock | "How it works" numbered step sequence | `steps: Array<{title, description, icon?}>`, `badge?` |
-| AgentProfileGridBlock | Agent/worker profile card grid ("Meet your AI team") | `agents: Array<{name, role, description, avatar, capabilities?, status?}>`, `columns?` |
-| SolutionShowcaseBlock | Problem → Solution → Output narrative with color-coded arc | `sections: Array<{label, title, description, bullets}>`, `badge?` |
+| AgentProfileGridBlock | Agent/worker profile card grid ("Meet your AI team") | `title`, `description`, `agents`, `columns` |
+| CallToActionBlock | Call-to-action section | - |
+| ComparisonBlock | Side-by-side feature comparison | `plans`, `title`, `description` |
+| FAQBlock | FAQ accordion | `items`, `title`, `description` |
+| FeatureBlock | Single feature showcase | - |
+| FeatureGridBlock | Multi-feature grid layout | - |
+| HeroBlock | Full hero with gradient text | - |
+| HeroSectionBlock | Alternate hero layout | - |
+| LogoCloud | Partner/client logo grid | `title`, `logos` |
+| PricingBlock | Pricing cards comparison | - |
+| ProcessFlowBlock | "How it works" numbered step sequence | `title`, `description`, `badge`, `steps` |
+| SocialProofBlock | Social proof metrics/logos | - |
+| SolutionShowcaseBlock | Problem -> Solution -> Output narrative with color-coded arc | `title`, `description`, `badge`, `sections` |
+| StatsMarketingBlock | Marketing statistics display | - |
+| TestimonialsBlock | Customer testimonial carousel/grid | - |
 
 ## Navigation
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| HeaderBlock | Site header with nav links | `logo`, `links`, `actions` |
-| FooterBlock | Site footer with link columns | `columns`, `social`, `legal` |
-| BannerBlock | Top-of-page promotional banner | `message`, `action`, `dismissible` |
-| NotFoundBlock | 404 page content | `title`, `description`, `action` |
-| NavUser | Sidebar user menu with dropdown | `user: {name, email, avatar?}`, `items?`, `footer?` |
+| BannerBlock | Top-of-page promotional banner | `variant`, `dismissible`, `onDismiss` |
+| FooterBlock | Site footer with link columns | - |
+| HeaderBlock | Site header with nav links | - |
+| NavUser | Sidebar user menu with dropdown | `user`, `name`, `email`, `avatar`, `items`, `footer` |
+| NotFoundBlock | 404 page content | `title`, `description`, `backHref`, `backLabel` |
 
 ## Dashboard & Data
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| StatsBlock | KPI statistics cards | `stats: Array<{label, value, change}>` |
-| ChartBlock | Single chart container | `title`, `chart`, `description` |
-| ChartCollectionBlock | Multiple chart grid | `charts: Array<ChartConfig>` |
-| BarChartBlock | Pre-configured bar chart | `data`, `title` |
-| InteractiveAreaChartBlock | Zoomable/interactive area chart | `data`, `title` |
-| HeatmapChartBlock | Heatmap visualization | `data`, `title` |
-| UsageDonutBlock | Usage/quota donut chart | `used`, `total`, `label` |
-| DataGridBlock | Data grid/table block | `columns`, `data` |
-| ActivityFeedBlock | Activity/event timeline | `activities: Array<Activity>` |
-| CodeBlock | Syntax-highlighted code display | `code`, `language`, `title` |
+| ActivityFeedBlock | Activity/event timeline | `activities`, `title` |
+| BarChartBlock | Pre-configured bar chart | - |
+| ChartBlock | Single chart container | `data`, `config`, `title`, `description` |
+| ChartCollectionBlock | Multiple chart grid | - |
+| CodeBlock | Syntax-highlighted code display | - |
+| DataGridBlock | Data grid/table block | `data`, `columns`, `title`, `description` |
+| HeatmapChartBlock | Heatmap visualization | - |
+| InteractiveAreaChartBlock | Zoomable/interactive area chart | - |
+| StatsBlock | KPI statistics cards | - |
+| UsageDonutBlock | Usage/quota donut chart | - |
 
 ## Application
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| SettingsLayout | Settings page with nav sidebar | `sections`, `children` |
-| ChatLayout | Chat application layout | `messages`, `onSend` |
-| OnboardingBlock | Multi-step onboarding wizard | `steps: Array<Step>` |
-| WizardBlock | Generic step-by-step wizard | `steps`, `onComplete` |
-| CreateBlock | Entity creation form | `fields`, `onSubmit` |
-| DirectoryBlock | User/item directory with search | `items`, `onSearch` |
-| ChangelogBlock | Version changelog display | `entries: Array<ChangelogEntry>` |
-| IntegrationsBlock | Integration marketplace grid | `integrations: Array<Integration>` |
-| ContactBlock | Contact form | `onSubmit` |
+| ChangelogBlock | Version changelog display | `entries`, `title` |
+| ChatLayout | Chat application layout | `initialMessages`, `assistantName`, `assistantStatus`, `placeholder` |
+| ContactBlock | Contact form | `onSubmit`, `title`, `description`, `namePlaceholder`, `emailPlaceholder`, `messagePlaceholder`, `successTitle`, `submitLabel` |
+| CreateBlock | Entity creation form | `title`, `description`, `submitLabel`, `onSubmit` |
+| DirectoryBlock | User/item directory with search | `navItems`, `projects` |
+| IntegrationsBlock | Integration marketplace grid | - |
+| KanbanDemoBlock | Kanban board demo with sample data | - |
+| OnboardingBlock | Multi-step onboarding wizard | `steps`, `title`, `onToggle` |
+| SettingsLayout | Settings page with nav sidebar | `links`, `title`, `subtitle`, `defaultActive`, `renderContent` |
+| WizardBlock | Generic step-by-step wizard | `title`, `description`, `steps`, `onFinish` |
 
 ## Content & Media
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| GalleryBlock | Image/media gallery grid | `items: Array<GalleryItem>` |
-| AudioVisualizerBlock | Audio visualization display | `audioSrc` |
-| NewsletterBlock | Email newsletter signup | `onSubscribe` |
+| AudioVisualizerBlock | Audio visualization display | - |
+| GalleryBlock | Image/media gallery grid | `images`, `columns`, `title` |
+| NewsletterBlock | Email newsletter signup | `onSubscribe`, `title`, `description` |
 
 ## User
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| TeamBlock | Team members grid with roles/avatars | `members: Array<Member>` |
-| InviteUserModal | Invite user flow modal | `onInvite?`, `onInvited?` |
+| TeamBlock | Team members grid with roles/avatars | - |
 
 ## AI/Voice
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| VoiceAgentCard | AI voice agent interface card | `agent`, `state`, `selected?`, `onSelect?` |
+| VoiceAgentCard | AI voice agent interface card | `agent`, `state`, `selected`, `onSelect` |
 
 ## Agentic
 
 | Block | Purpose | Key Props |
 | --- | --- | --- |
-| AgentConversationBlock | Agent conversation UI (messages, tool calls, thinking) | `messages: ConversationMessage[]` |
+| AgentConversationBlock | Agent conversation UI (messages, tool calls, thinking) | - |
+| AgentRunOverviewBlock | Agent run summary with status, duration, and output | - |
+| AgentWorkbenchBlock | Agent workbench layout with tool panels and conversation | - |
 
 ## Usage Pattern
 

package/.agents/skills/seed/references/components.md

@@ -11,29 +11,29 @@ Tiers: **1**=Core (3+ recipes), **2**=Domain (1-2 recipes), **3**=Decorative (ma
 | Component | Path | Tier | Radix/Lib | Notes |
 |-----------|------|------|-----------|-------|
 | Button | `ui/Button` | 1 | `react-slot` | 8 variants (primary, secondary, outline, ghost, link, destructive, accent, glass), 4 sizes |
-| Input | `ui/Input` | 1 | - | size: sm/default/lg, props: label, error, startIcon, endIcon |
-| PasswordInput | `ui/PasswordInput` | 1 | - | Input with show/hide toggle |
-| Textarea | `ui/Textarea` | 1 | - | Auto-grow text area |
-| Select | `ui/Select` | 1 | `react-select` | Compound: Trigger, Content, Item, Group, Separator |
-| NativeSelect | `ui/NativeSelect` | 4 | - | Browser-native `<select>` styled |
+| Calendar | `ui/Calendar` | 1 | `react-day-picker` | Calendar grid primitive |
 | Checkbox | `ui/Checkbox` | 1 | `react-checkbox` | With optional label |
-| Switch | `ui/Switch` | 1 | `react-switch` | Toggle switch |
-| RadioGroup | `ui/RadioGroup` | 1 | `react-radio-group` | RadioGroup + RadioGroupItem |
-| Slider | `ui/Slider` | 1 | `react-slider` | Range slider |
+| CheckoutForm | `ui/CheckoutForm` | 2 | `@stripe/react-stripe-js` | Stripe Elements checkout form |
+| CheckoutFormDemo | `ui/CheckoutFormDemo` | 2 | `@stripe/react-stripe-js` | Demo checkout with pre-wired state |
 | Combobox | `ui/Combobox` | 1 | `cmdk` | Searchable select |
-| TagInput | `ui/TagInput` | 1 | - | Multi-value tag input |
 | DatePicker | `ui/DatePicker` | 1 | `react-day-picker` | Single date picker |
 | DateRangePicker | `ui/DateRangePicker` | 1 | `react-day-picker` | Date range selection |
-| Calendar | `ui/Calendar` | 1 | `react-day-picker` | Calendar grid primitive |
-| InputOTP | `ui/InputOTP` | 1 | `input-otp` | OTP input with groups, slots, separators |
-| InputGroup | `ui/InputGroup` | 1 | - | Input + addon composition |
+| Field | `ui/Field` | 1 | - | Generic field wrapper (label + error) |
+| FileUpload | `ui/FileUpload` | 1 | - | Drag-and-drop file upload zone |
 | Form | `ui/Form` | 1 | `react-hook-form` | FormField, FormItem, FormLabel, FormControl, FormMessage |
 | FormWizard | `ui/FormWizard` | 1 | - | Multi-step form wizard |
-| Field | `ui/Field` | 1 | - | Generic field wrapper (label + error) |
+| Input | `ui/Input` | 1 | - | size: sm/default/lg, props: label, error, startIcon, endIcon |
+| InputGroup | `ui/InputGroup` | 1 | - | Input + addon composition |
+| InputOTP | `ui/InputOTP` | 1 | `input-otp` | OTP input with groups, slots, separators |
 | Label | `ui/Label` | 1 | `react-label` | Accessible label |
-| FileUpload | `ui/FileUpload` | 1 | - | Drag-and-drop file upload zone |
-| CheckoutForm | `ui/CheckoutForm` | 2 | `@stripe/react-stripe-js` | Stripe Elements checkout form |
-| CheckoutFormDemo | `ui/CheckoutFormDemo` | 2 | `@stripe/react-stripe-js` | Demo checkout with pre-wired state |
+| NativeSelect | `ui/NativeSelect` | 4 | - | Browser-native <select> styled |
+| PasswordInput | `ui/PasswordInput` | 1 | - | Input with show/hide toggle |
+| RadioGroup | `ui/RadioGroup` | 1 | `react-radio-group` | RadioGroup + RadioGroupItem |
+| Select | `ui/Select` | 1 | `react-select` | Compound: Trigger, Content, Item, Group, Separator |
+| Slider | `ui/Slider` | 1 | `react-slider` | Range slider |
+| Switch | `ui/Switch` | 1 | `react-switch` | Toggle switch |
+| TagInput | `ui/TagInput` | 1 | - | Multi-value tag input |
+| Textarea | `ui/Textarea` | 1 | - | Auto-grow text area |
 
 ---
 
@@ -41,34 +41,40 @@ Tiers: **1**=Core (3+ recipes), **2**=Domain (1-2 recipes), **3**=Decorative (ma
 
 | Component | Path | Tier | Radix/Lib | Notes |
 |-----------|------|------|-----------|-------|
-| Card | `ui/Card` | 1 | - | Card, Header, Title, Description, Content, Footer |
+| Accordion | `ui/Accordion` | 1 | `react-accordion` | Accordion, Item, Trigger, Content |
+| Alert | `ui/Alert` | 1 | - | variant: default, destructive |
+| AlertDialog | `ui/AlertDialog` | 1 | `react-alert-dialog` | Full compound set with actions |
+| AnimatedTabs | `ui/AnimatedTabs` | 3 | - | Tabs with sliding indicator (layoutId) |
+| AnnouncementBanner | `ui/AnnouncementBanner` | 1 | - | Top-of-page announcement |
 | Avatar | `ui/Avatar` | 1 | `react-avatar` | Avatar, AvatarImage, AvatarFallback |
 | AvatarUpload | `ui/AvatarUpload` | 1 | - | Avatar with upload functionality |
-| Badge | `ui/Badge` | 1 | - | variant: default, secondary, outline, destructive, success, warning |
-| RoleBadge | `ui/RoleBadge` | 4 | - | Role-specific badge styling (merge into Badge) |
-| Table | `ui/Table` | 1 | - | Table, Header, Body, Row, Head, Cell |
+| Badge | `ui/Badge` | 1 | - | variant: primary, secondary, destructive, outline, accent |
+| Breadcrumb | `ui/Breadcrumb` | 1 | - | Breadcrumb, List, Item, Link, Separator |
+| Card | `ui/Card` | 1 | - | Card, Header, Title, Description, Content, Footer |
+| Carousel | `ui/Carousel` | 1 | `embla-carousel-react` | Content, Item, Previous, Next |
+| CheckStatus | `ui/CheckStatus` | 2 | - | Status check indicator component |
+| DataFreshness | `ui/DataFreshness` | 2 | - | Data freshness/staleness indicator |
 | DataTable | `ui/DataTable` | 1 | `@tanstack/react-table` | Full-featured with sorting/filtering |
+| Empty | `ui/Empty` | 1 | - | Empty state placeholder |
+| Heading | `ui/Heading` | 1 | - | Semantic headings with explicit level + visual size |
+| HoverCard | `ui/HoverCard` | 4 | `react-hover-card` | HoverCard, Trigger, Content |
+| KanbanBoard | `ui/KanbanBoard` | 2 | - | Drag-and-drop kanban board component |
+| Kbd | `ui/Kbd` | 1 | - | Keyboard shortcut display |
+| MetricCard | `ui/MetricCard` | 2 | - | Single metric display card with label, value, and trend |
+| Popover | `ui/Popover` | 1 | `react-popover` | Popover, Trigger, Content |
+| Progress | `ui/Progress` | 1 | `react-progress` | Progress bar |
+| ProgressRing | `ui/ProgressRing` | 2 | - | Circular progress ring indicator |
+| PromoCard | `ui/PromoCard` | 4 | - | Promotional card (Card + glass-floating may replace) |
+| RoleBadge | `ui/RoleBadge` | 4 | - | Role-specific badge styling (merge into Badge) |
 | Skeleton | `ui/Skeleton` | 1 | - | Loading placeholder |
 | Spinner | `ui/Spinner` | 1 | - | Loading spinner |
-| Progress | `ui/Progress` | 1 | `react-progress` | Progress bar |
-| Empty | `ui/Empty` | 1 | - | Empty state placeholder |
-| Timeline | `ui/Timeline` | 1 | - | Vertical timeline |
 | StatusDot | `ui/StatusDot` | 4 | - | Status indicator dot (can be CSS utility) |
-| Accordion | `ui/Accordion` | 1 | `react-accordion` | Accordion, Item, Trigger, Content |
+| Table | `ui/Table` | 1 | - | Table, Header, Body, Row, Head, Cell |
 | Tabs | `ui/Tabs` | 1 | `react-tabs` | Tabs, TabsList, TabsTrigger, TabsContent |
-| AnimatedTabs | `ui/AnimatedTabs` | 3 | - | Tabs with sliding indicator (layoutId) |
+| Timeline | `ui/Timeline` | 1 | - | Vertical timeline |
 | Tooltip | `ui/Tooltip` | 1 | `react-tooltip` | Provider, Tooltip, Trigger, Content |
-| HoverCard | `ui/HoverCard` | 4 | `react-hover-card` | HoverCard, Trigger, Content |
-| Popover | `ui/Popover` | 1 | `react-popover` | Popover, Trigger, Content |
-| Alert | `ui/Alert` | 1 | - | variant: default, destructive |
-| AlertDialog | `ui/AlertDialog` | 1 | `react-alert-dialog` | Full compound set with actions |
-| Breadcrumb | `ui/Breadcrumb` | 1 | - | Breadcrumb, List, Item, Link, Separator |
-| Kbd | `ui/Kbd` | 1 | - | Keyboard shortcut display |
-| PromoCard | `ui/PromoCard` | 4 | - | Promotional card (Card + glass-floating may replace) |
-| AnnouncementBanner | `ui/AnnouncementBanner` | 1 | - | Top-of-page announcement |
-| Heading | `ui/Heading` | 1 | - | Semantic headings with explicit `level` + visual `size` |
+| TrendIndicator | `ui/TrendIndicator` | 2 | - | Trend direction indicator (up/down/neutral) |
 | Typography | `ui/Typography` | 1 | - | Body, small, and muted text only |
-| Carousel | `ui/Carousel` | 1 | `embla-carousel-react` | Content, Item, Previous, Next |
 
 ---
 
@@ -76,15 +82,16 @@ Tiers: **1**=Core (3+ recipes), **2**=Domain (1-2 recipes), **3**=Decorative (ma
 
 | Component | Path | Tier | Radix/Lib | Notes |
 |-----------|------|------|-----------|-------|
-| Sidebar | `ui/Sidebar` | 1 | - | Full system: Provider, Trigger, Content, Group, Menu |
-| NavigationMenu | `ui/NavigationMenu` | 1 | `react-navigation-menu` | Menu, List, Item, Trigger, Content |
-| Menubar | `ui/Menubar` | 4 | `react-menubar` | Rare in modern SaaS |
-| DropdownMenu | `ui/DropdownMenu` | 1 | `react-dropdown-menu` | Full compound set |
+| Command | `ui/Command` | 1 | `cmdk` | Command palette primitive |
 | ContextMenu | `ui/ContextMenu` | 4 | `react-context-menu` | Rarely needed |
-| Pagination | `ui/Pagination` | 1 | - | Content, Item, Previous, Next |
+| DropdownMenu | `ui/DropdownMenu` | 1 | `react-dropdown-menu` | Full compound set |
 | FloatingDock | `ui/FloatingDock` | 4 | - | macOS-style floating dock |
+| LanguageSwitcher | `ui/LanguageSwitcher` | 2 | - | Locale/language selection switcher |
+| Menubar | `ui/Menubar` | 4 | `react-menubar` | Rare in modern SaaS |
+| NavigationMenu | `ui/NavigationMenu` | 1 | `react-navigation-menu` | Menu, List, Item, Trigger, Content |
+| Pagination | `ui/Pagination` | 1 | - | Content, Item, Previous, Next |
 | SearchCommand | `ui/SearchCommand` | 1 | `cmdk` | Cmd+K search dialog |
-| Command | `ui/Command` | 1 | `cmdk` | Command palette primitive |
+| Sidebar | `ui/Sidebar` | 1 | - | Full system: Provider, Trigger, Content, Group, Menu |
 | TreeView | `ui/TreeView` | 1 | - | Recursive collapsible tree with keyboard nav |
 
 ---
@@ -93,20 +100,22 @@ Tiers: **1**=Core (3+ recipes), **2**=Domain (1-2 recipes), **3**=Decorative (ma
 
 | Component | Path | Tier | Radix/Lib | Notes |
 |-----------|------|------|-----------|-------|
-| Dialog | `ui/Dialog` | 1 | `react-dialog` | Full compound set with close button |
 | AnimatedDialog | `ui/AnimatedDialog` | 3 | `react-dialog` | Dialog with motion spring animations |
-| Drawer | `ui/Drawer` | 1 | `vaul` | Mobile-friendly bottom drawer |
-| Sheet | `ui/Sheet` | 1 | `react-dialog` | Slide-in side panel |
 | AnimatedSheet | `ui/AnimatedSheet` | 3 | `react-dialog` | Sheet with motion animations |
+| AspectRatio | `ui/AspectRatio` | 1 | `react-aspect-ratio` | Fixed aspect ratio container |
+| BentoGrid | `ui/BentoGrid` | 1 | - | CSS grid layout system |
+| Collapsible | `ui/Collapsible` | 4 | `react-collapsible` | Used by Sidebar internally |
+| Dialog | `ui/Dialog` | 1 | `react-dialog` | Full compound set with close button |
+| Drawer | `ui/Drawer` | 1 | `vaul` | Mobile-friendly bottom drawer |
+| Grid | `layout/Grid` | 1 | - | CSS Grid wrapper |
+| GridSystem | `layout/GridSystem` | 2 | - | Extended grid system with responsive column and gap utilities |
 | Resizable | `ui/Resizable` | 1 | `react-resizable-panels` | PanelGroup, Panel, Handle |
 | ScrollArea | `ui/ScrollArea` | 1 | `react-scroll-area` | Custom scrollbar |
-| Collapsible | `ui/Collapsible` | 4 | `react-collapsible` | Used by Sidebar internally |
-| BentoGrid | `ui/BentoGrid` | 1 | - | CSS grid layout system |
-| AspectRatio | `ui/AspectRatio` | 1 | `react-aspect-ratio` | Fixed aspect ratio container |
 | Separator | `ui/Separator` | 1 | `react-separator` | Horizontal/vertical divider |
+| SettingsModal | `ui/SettingsModal` | 2 | - | Modal dialog for application settings |
+| Sheet | `ui/Sheet` | 1 | `react-dialog` | Slide-in side panel |
 | Toggle | `ui/Toggle` | 4 | `react-toggle` | variant: default, outline |
 | ToggleGroup | `ui/ToggleGroup` | 4 | `react-toggle-group` | Group of toggles |
-| Grid | `layout/Grid` | 1 | - | CSS Grid wrapper |
 
 ---
 
@@ -115,15 +124,16 @@ Tiers: **1**=Core (3+ recipes), **2**=Domain (1-2 recipes), **3**=Decorative (ma
 | Component | Path | Tier | Notes |
 |-----------|------|------|-------|
 | AmbientGrid | `ui/AmbientGrid` | 3 | CSS grid overlay (24px cells, 0.06 opacity) |
+| AnimatedBackground | `ui/AnimatedBackground` | 3 | CSS animated gradient background |
 | AuroraEffect | `ui/AuroraEffect` | 3 | Animated gradient aurora background |
+| InfiniteSlider | `ui/InfiniteSlider` | 3 | Auto-scrolling content slider |
+| MagneticElement | `ui/MagneticElement` | 3 | Magnetic cursor attraction |
 | MeteorShower | `ui/MeteorShower` | 3 | Falling meteor particles |
-| AnimatedBackground | `ui/AnimatedBackground` | 3 | CSS animated gradient background |
 | MouseEffect | `ui/MouseEffect` | 3 | Mouse-tracking effects (MouseGlow, MouseSpotlight) |
 | MovingBorder | `ui/MovingBorder` | 3 | Animated border rotation |
 | ProgressiveBlur | `ui/ProgressiveBlur` | 3 | Gradient blur effect |
+| ShaderBackground | `ui/ShaderBackground` | 2 | 21 shader types with intent-based presets (hero, section, ambient, card) |
 | TiltCard | `ui/TiltCard` | 3 | 3D perspective tilt on hover |
-| MagneticElement | `ui/MagneticElement` | 3 | Magnetic cursor attraction |
-| InfiniteSlider | `ui/InfiniteSlider` | 3 | Auto-scrolling content slider |
 
 ---
 
@@ -133,15 +143,15 @@ All in `@vadimcomanescu/nadicode-design-system/text-effects/`.
 
 | Component | Path | Tier | Notes |
 |-----------|------|------|-------|
-| TextReveal | `ui/text-effects/TextReveal` | 3 | Scroll-triggered text reveal |
 | AnimatedGradientText | `ui/text-effects/AnimatedGradientText` | 3 | Animated gradient sweep on text |
-| FlipWords | `ui/text-effects/FlipWords` | 3 | Word cycling with flip animation |
-| StreamingText | `ui/text-effects/StreamingText` | 3 | ChatGPT-style streaming output |
-| ShimmeringText | `ui/text-effects/ShimmeringText` | 3 | Shimmer highlight sweep |
 | CountingNumber | `ui/text-effects/CountingNumber` | 3 | Animated number counter (also used in dashboard) |
-| MorphingText | `ui/text-effects/MorphingText` | 3 | SVG text morphing transitions |
+| FlipWords | `ui/text-effects/FlipWords` | 3 | Word cycling with flip animation |
 | HighlightText | `ui/text-effects/HighlightText` | 3 | Animated highlight marker |
+| MorphingText | `ui/text-effects/MorphingText` | 3 | SVG text morphing transitions |
+| ShimmeringText | `ui/text-effects/ShimmeringText` | 3 | Shimmer highlight sweep |
 | SlidingNumber | `ui/text-effects/SlidingNumber` | 3 | Digit-by-digit sliding animation |
+| StreamingText | `ui/text-effects/StreamingText` | 3 | ChatGPT-style streaming output |
+| TextReveal | `ui/text-effects/TextReveal` | 3 | Scroll-triggered text reveal |
 
 ---
 
@@ -149,12 +159,12 @@ All in `@vadimcomanescu/nadicode-design-system/text-effects/`.
 
 | Component | Path | Tier | Notes |
 |-----------|------|------|-------|
+| ConfettiBurst | `ui/ConfettiBurst` | 1 | Celebratory confetti animation |
+| PageTransition | `ui/PageTransition` | 1 | Route transition wrapper (keyed on pathname) |
 | ScrollFadeIn | `ui/ScrollFadeIn` | 1 | Fade in on scroll intersection |
+| SpringHover | `ui/SpringHover` | 3 | Spring-based hover effect wrapper |
 | StaggerChildren | `ui/StaggerChildren` | 1 | Stagger child element entrances |
 | StaggeredEntrance | `ui/StaggeredEntrance` | 3 | Sequential entrance animation |
-| PageTransition | `ui/PageTransition` | 1 | Route transition wrapper (keyed on pathname) |
-| ConfettiBurst | `ui/ConfettiBurst` | 1 | Celebratory confetti animation |
-| SpringHover | `ui/SpringHover` | 3 | Spring-based hover effect wrapper |
 | SuccessCheck | `ui/SuccessCheck` | 1 | Animated success checkmark |
 
 ---
@@ -165,14 +175,16 @@ Base `Chart.tsx` in `ui/` (not `ui/charts/`). The 7 chart variants in `ui/charts
 
 | Component | Path | Tier | Notes |
 |-----------|------|------|-------|
-| Chart | `ui/Chart` | 2 | Base config: ChartContainer, ChartTooltip, ChartLegend |
 | AreaChart | `ui/charts/AreaChart` | 2 | Recharts area chart |
 | BarChart | `ui/charts/BarChart` | 2 | Recharts bar chart |
+| Chart | `ui/Chart` | 2 | Base config: ChartContainer, ChartTooltip, ChartLegend |
+| ChartCard | `ui/ChartCard` | 2 | Card wrapper for chart display with title and description |
+| HeatmapChart | `ui/charts/HeatmapChart` | 2 | Custom heatmap visualization |
 | LineChart | `ui/charts/LineChart` | 2 | Recharts line chart |
 | PieChart | `ui/charts/PieChart` | 2 | Recharts pie/donut chart |
 | RadarChart | `ui/charts/RadarChart` | 2 | Recharts radar chart |
 | RadialBarChart | `ui/charts/RadialBarChart` | 2 | Recharts radial bar chart |
-| HeatmapChart | `ui/charts/HeatmapChart` | 2 | Custom heatmap visualization |
+| Sparkline | `ui/charts/Sparkline` | 2 | Inline sparkline chart for compact trend display |
 
 ---
 
@@ -181,9 +193,9 @@ Base `Chart.tsx` in `ui/` (not `ui/charts/`). The 7 chart variants in `ui/charts
 | Component | Path | Tier | Notes |
 |-----------|------|------|-------|
 | AgentAvatar | `ui/AgentAvatar` | 2 | AI agent avatar with idle/listening/speaking states |
-| Avatar3D | `ui/Avatar3D` | 2 | 3D avatar with Three.js |
 | AgentStatus | `ui/AgentStatus` | 2 | Agent connection status indicator |
 | AudioWaveform | `ui/AudioWaveform` | 2 | Real-time audio visualization |
+| Avatar3D | `ui/Avatar3D` | 2 | 3D avatar with Three.js |
 | ConversationThread | `ui/ConversationThread` | 2 | Chat message thread |
 
 ---
@@ -192,40 +204,24 @@ Base `Chart.tsx` in `ui/` (not `ui/charts/`). The 7 chart variants in `ui/charts
 
 Components for AI agent interfaces, tool-use visualization, and multi-agent workflows.
 
-### Core
-
 | Component | Path | Tier | Notes |
 |-----------|------|------|-------|
-| ToolCallCard | `ui/ToolCallCard` | 2 | Tool invocation with name, args, status, result |
-| ThinkingIndicator | `ui/ThinkingIndicator` | 2 | Animated "thinking..." for agent reasoning |
 | AgentMessageBubble | `ui/AgentMessageBubble` | 2 | Chat bubble with role-based styling |
-| ApprovalCard | `ui/ApprovalCard` | 2 | Human-in-the-loop approval/reject |
-
-### Multi-Agent
-
-| Component | Path | Tier | Notes |
-|-----------|------|------|-------|
+| AgentMetricsCard | `ui/AgentMetricsCard` | 2 | Agent performance metrics dashboard |
 | AgentTeamPanel | `ui/AgentTeamPanel` | 2 | Agent team members and statuses |
+| AgentTerminal | `ui/AgentTerminal` | 2 | Terminal-style command output |
 | AgentTimeline | `ui/AgentTimeline` | 2 | Timeline of agent actions |
-| WorkflowGraph | `ui/WorkflowGraph` | 2 | Visual graph of workflow steps |
-| HandoffIndicator | `ui/HandoffIndicator` | 2 | Agent-to-agent task handoff |
-
-### Observability
-
-| Component | Path | Tier | Notes |
-|-----------|------|------|-------|
-| ContextMeter | `ui/ContextMeter` | 2 | Context window usage visualization |
-| SourceCitation | `ui/SourceCitation` | 2 | Cited sources with links |
-| AgentMetricsCard | `ui/AgentMetricsCard` | 2 | Agent performance metrics dashboard |
-| MemoryInspector | `ui/MemoryInspector` | 2 | Agent memory/state inspector |
-
-### Artifacts
-
-| Component | Path | Tier | Notes |
-|-----------|------|------|-------|
+| ApprovalCard | `ui/ApprovalCard` | 2 | Human-in-the-loop approval/reject |
 | ArtifactCard | `ui/ArtifactCard` | 2 | Generated artifacts display |
 | CodeDiffViewer | `ui/CodeDiffViewer` | 2 | Side-by-side or unified diff view |
-| AgentTerminal | `ui/AgentTerminal` | 2 | Terminal-style command output |
+| ContextMeter | `ui/ContextMeter` | 2 | Context window usage visualization |
+| DiffStat | `ui/DiffStat` | 2 | Diff statistics display (additions/deletions) |
+| HandoffIndicator | `ui/HandoffIndicator` | 2 | Agent-to-agent task handoff |
+| MemoryInspector | `ui/MemoryInspector` | 2 | Agent memory/state inspector |
+| SourceCitation | `ui/SourceCitation` | 2 | Cited sources with links |
+| ThinkingIndicator | `ui/ThinkingIndicator` | 2 | Animated "thinking..." for agent reasoning |
+| ToolCallCard | `ui/ToolCallCard` | 2 | Tool invocation with name, args, status, result |
+| WorkflowGraph | `ui/WorkflowGraph` | 2 | Visual graph of workflow steps |
 
 ---
 
@@ -235,8 +231,8 @@ All in `src/components/ui/stepper/`. Distinct from FormWizard.
 
 | Component | Path | Tier | Notes |
 |-----------|------|------|-------|
-| Stepper | `ui/stepper/stepper` | 1 | Root stepper, exports `useStepper` hook |
 | Step | `ui/stepper/step` | 1 | Individual step |
+| Stepper | `ui/stepper/stepper` | 1 | Root stepper, exports useStepper hook |
 
 ---
 
@@ -244,17 +240,18 @@ All in `src/components/ui/stepper/`. Distinct from FormWizard.
 
 | Component | Path | Tier | Notes |
 |-----------|------|------|-------|
-| ThemeToggle | `ui/ThemeToggle` | 1 | Light/dark/system theme switcher |
-| StyleToggle | `ui/StyleToggle` | 1 | Arctic/bloom style switcher |
-| Toast / Toaster | `ui/Toast`, `ui/Toaster` | 1 | `react-toast` based |
-| Sonner | `ui/Sonner` | 1 | Sonner toast integration |
-| NotificationCenter | `ui/NotificationCenter` | 4 | Overlaps with Sonner/Toast |
-| Logo | `ui/Logo` | 1 | Brand logo component |
 | BrandIcons | `ui/BrandIcons` | 1 | Google, GitHub brand SVGs |
-| SkipNav | `ui/SkipNav` | 1 | Accessibility skip navigation |
-| VisuallyHidden | `ui/VisuallyHidden` | 1 | Screen-reader-only content |
 | ButtonGroup | `ui/ButtonGroup` | 4 | Grouped button layout (use flex+gap) |
 | Item | `ui/Item` | 4 | Generic list item (too generic) |
+| Logo | `ui/Logo` | 1 | Brand logo component |
+| NotificationCenter | `ui/NotificationCenter` | 4 | Overlaps with Sonner/Toast |
+| SkipNav | `ui/SkipNav` | 1 | Accessibility skip navigation |
+| Sonner | `ui/Sonner` | 1 | Sonner toast integration |
+| StyleToggle | `ui/StyleToggle` | 1 | Arctic/bloom style switcher |
+| ThemeToggle | `ui/ThemeToggle` | 1 | Light/dark/system theme switcher |
+| Toast | `ui/Toast` | 1 | Toast notification primitive |
+| Toaster | `ui/Toaster` | 1 | Toast container and renderer |
+| VisuallyHidden | `ui/VisuallyHidden` | 1 | Screen-reader-only content |
 
 ---
 
@@ -262,9 +259,9 @@ All in `src/components/ui/stepper/`. Distinct from FormWizard.
 
 | Tier | Count | Usage |
 |------|-------|-------|
-| 1 (Core) | ~48 | 3+ recipes, always available |
-| 2 (Domain) | ~30 | Agentic, charts, AI/voice, checkout |
-| 3 (Decorative) | ~27 | Marketing/showcase only |
+| 1 (Core) | ~76 | 3+ recipes, always available |
+| 2 (Domain) | ~43 | Agentic, charts, AI/voice, checkout |
+| 3 (Decorative) | ~24 | Marketing/showcase only |
 | 4 (Deprecation) | ~14 | Evaluate for removal/consolidation |
 
 Use `npm run docs:inventory` for filesystem-backed inventory output.