@vadimcomanescu/nadicode-design-system 2.0.0

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

@@ -0,0 +1,270 @@
+# Component Inventory
+
+All components live under `src/components/`. Import via `@/components/ui/...` or `@/components/blocks/...`.
+
+Tiers: **1**=Core (3+ recipes), **2**=Domain (1-2 recipes), **3**=Decorative (marketing only), **4**=Deprecation candidate.
+
+---
+
+## Form Controls
+
+| 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 |
+| 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 |
+| 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 |
+| 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) |
+| 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 |
+
+---
+
+## Display
+
+| Component | Path | Tier | Radix/Lib | Notes |
+|-----------|------|------|-----------|-------|
+| Card | `ui/Card` | 1 | - | Card, Header, Title, Description, Content, Footer |
+| 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 |
+| DataTable | `ui/DataTable` | 1 | `@tanstack/react-table` | Full-featured with sorting/filtering |
+| 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 |
+| Tabs | `ui/Tabs` | 1 | `react-tabs` | Tabs, TabsList, TabsTrigger, TabsContent |
+| AnimatedTabs | `ui/AnimatedTabs` | 3 | - | Tabs with sliding indicator (layoutId) |
+| 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` |
+| Typography | `ui/Typography` | 1 | - | Body, small, and muted text only |
+| Carousel | `ui/Carousel` | 1 | `embla-carousel-react` | Content, Item, Previous, Next |
+
+---
+
+## Navigation
+
+| 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 |
+| ContextMenu | `ui/ContextMenu` | 4 | `react-context-menu` | Rarely needed |
+| Pagination | `ui/Pagination` | 1 | - | Content, Item, Previous, Next |
+| FloatingDock | `ui/FloatingDock` | 4 | - | macOS-style floating dock |
+| SearchCommand | `ui/SearchCommand` | 1 | `cmdk` | Cmd+K search dialog |
+| Command | `ui/Command` | 1 | `cmdk` | Command palette primitive |
+| TreeView | `ui/TreeView` | 1 | - | Recursive collapsible tree with keyboard nav |
+
+---
+
+## Layout and Overlays
+
+| 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 |
+| 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 |
+| 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 |
+
+---
+
+## Decorative Effects
+
+| Component | Path | Tier | Notes |
+|-----------|------|------|-------|
+| AmbientGrid | `ui/AmbientGrid` | 3 | CSS grid overlay (24px cells, 0.06 opacity) |
+| AuroraEffect | `ui/AuroraEffect` | 3 | Animated gradient aurora background |
+| 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 |
+| TiltCard | `ui/TiltCard` | 3 | 3D perspective tilt on hover |
+| MagneticElement | `ui/MagneticElement` | 3 | Magnetic cursor attraction |
+| InfiniteSlider | `ui/InfiniteSlider` | 3 | Auto-scrolling content slider |
+
+---
+
+## Text Effects
+
+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 |
+| HighlightText | `ui/text-effects/HighlightText` | 3 | Animated highlight marker |
+| SlidingNumber | `ui/text-effects/SlidingNumber` | 3 | Digit-by-digit sliding animation |
+
+---
+
+## Animation Utilities
+
+| Component | Path | Tier | Notes |
+|-----------|------|------|-------|
+| ScrollFadeIn | `ui/ScrollFadeIn` | 1 | Fade in on scroll intersection |
+| 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 |
+
+---
+
+## Charts
+
+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 |
+| 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 |
+
+---
+
+## AI / Voice
+
+| 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 |
+| ConversationThread | `ui/ConversationThread` | 2 | Chat message thread |
+
+---
+
+## Agentic UI
+
+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 |
+|-----------|------|------|-------|
+| AgentTeamPanel | `ui/AgentTeamPanel` | 2 | Agent team members and statuses |
+| 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 |
+|-----------|------|------|-------|
+| 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 |
+
+---
+
+## Multi-Step / Stepper
+
+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 |
+
+---
+
+## Miscellaneous
+
+| 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) |
+
+---
+
+## Tier Summary
+
+| Tier | Count | Usage |
+|------|-------|-------|
+| 1 (Core) | ~48 | 3+ recipes, always available |
+| 2 (Domain) | ~30 | Agentic, charts, AI/voice, checkout |
+| 3 (Decorative) | ~27 | Marketing/showcase only |
+| 4 (Deprecation) | ~14 | Evaluate for removal/consolidation |
+
+Use `npm run docs:inventory` for filesystem-backed inventory output.

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

@@ -0,0 +1,258 @@
+# Composition
+
+Page layout algebra, shell selection, content widths, vertical rhythm, glass tiers, and grid patterns.
+
+---
+
+## 3-Layer Model
+
+Every Seed page is composed of exactly three layers:
+
+```
+Shell           -- persistent frame (sidebar, header, footer)
+  Section       -- vertical content band (hero, KPI row, chart grid)
+    Component   -- UI primitive or block from the DS
+```
+
+**Rules:**
+- A page has exactly 1 shell
+- A page has 2-8 sections (vertical stacking, no nesting)
+- Each section contains 1-6 components arranged via CSS grid or flex
+- Sections never nest inside other sections
+
+---
+
+## Shell Selection
+
+| Intent | Shell | Components |
+|--------|-------|------------|
+| App pages (dashboard, settings, CRUD, analytics, agents) | `app-shell` | `Sidebar` + top bar + `SearchCommand` |
+| Marketing (landing, pricing, blog) | `marketing-shell` | `HeaderBlock` + `FooterBlock` |
+| Auth (login, signup, reset) | `auth-shell` | `AuthLayout` (split-screen or centered) |
+| Onboarding | `onboarding-shell` | Minimal header + progress bar, no nav |
+| Error (404, 500) | `fallback-shell` | Logo + minimal nav back |
+
+### Decision Tree
+
+```
+Does the user have a session? --> Yes --> app-shell
+                              --> No  --> Is it auth? --> auth-shell
+                                     --> Is it onboarding? --> onboarding-shell
+                                     --> marketing-shell or fallback-shell
+```
+
+### Shell Diagrams
+
+```
+APP SHELL                          MARKETING SHELL
++--+---------------------------+   +-----------------------------+
+|  |  Top bar / Breadcrumb     |   | HeaderBlock                 |
+|S |                           |   +-----------------------------+
+|I |  Section 1                |   | Section 1                   |
+|D |                           |   |                             |
+|E |  Section 2                |   | Section 2                   |
+|B |                           |   |                             |
+|A |  Section 3                |   | Section 3                   |
+|R |                           |   +-----------------------------+
+|  |                           |   | FooterBlock                 |
++--+---------------------------+   +-----------------------------+
+
+AUTH SHELL                         ONBOARDING SHELL
++-----------------------------+    +-----------------------------+
+| Logo        (minimal)       |    | Logo    Step 2/5  [Skip]    |
++-----------------------------+    +-----------------------------+
+|                             |    |                             |
+|    +-------------------+    |    |    +-------------------+    |
+|    | Auth Card         |    |    |    | Step Content      |    |
+|    | (glass-floating)  |    |    |    |                   |    |
+|    +-------------------+    |    |    +-------------------+    |
+|                             |    | [Back]           [Next]    |
++-----------------------------+    +-----------------------------+
+```
+
+---
+
+## Content Width Contract
+
+| Page Type | Max Width | Padding |
+|-----------|-----------|---------|
+| Marketing sections | `max-w-7xl` (1280px) | `px-4 sm:px-6 lg:px-8` |
+| App content | `max-w-screen-2xl` (1536px) | `px-4 lg:px-6` |
+| Centered forms (auth, onboarding) | `max-w-md` (448px) | `px-4` |
+| Split-screen auth | `max-w-6xl` (1152px) | full-bleed |
+| Reading content (blog, changelog) | `max-w-3xl` (768px) | `px-4 sm:px-6` |
+
+### Decision Tree
+
+```
+Is it marketing / public?
+  Yes -> max-w-7xl mx-auto px-4 sm:px-6 lg:px-8
+  No  -> Is it a form / auth?
+           Yes -> Is it centered?
+                    Yes -> max-w-md mx-auto px-4
+                    No  -> max-w-2xl mx-auto px-4
+           No  -> Is it reading content (blog)?
+                    Yes -> max-w-3xl mx-auto px-4 sm:px-6
+                    No  -> App layout (full width within sidebar)
+                           -> max-w-screen-2xl mx-auto px-4 lg:px-6
+```
+
+---
+
+## Vertical Rhythm
+
+| Context | Section gap | Inner element gap |
+|---------|-------------|-------------------|
+| Marketing | `py-16 md:py-24` | `space-y-6` / `gap-8` |
+| App | `py-6 md:py-8` | `space-y-4` / `gap-4 lg:gap-6` |
+| Forms | `py-6` | `space-y-6` (between groups), `space-y-4` (between fields) |
+| Cards in grid | `gap-4 lg:gap-6` | `p-6` internal |
+
+### Section Template
+
+```tsx
+{/* App section */}
+<section className="py-6 md:py-8">
+  <div className="flex items-center justify-between mb-4">
+    <Heading level={3} size="subsection" >Section Title</Heading>
+    <Button variant="outline" size="sm">Action</Button>
+  </div>
+  {/* Section content */}
+</section>
+
+{/* Marketing section */}
+<section className="py-16 md:py-24">
+  <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 text-center">
+    <Heading level={2} size="section"  className="mb-4">Section Title</Heading>
+    <Typography variant="lead" className="mb-12 text-text-secondary">
+      Section description
+    </Typography>
+    {/* Section content */}
+  </div>
+</section>
+```
+
+---
+
+## Spacing Scale
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `gap-1` | 4px | Inline icon + text |
+| `gap-2` | 8px | Related controls (button group) |
+| `gap-3` | 12px | Form field internal |
+| `gap-4` | 16px | Default card/section inner gap |
+| `gap-6` | 24px | Section inner spacing, card padding |
+| `gap-8` | 32px | Between major content groups |
+| `gap-12` | 48px | Marketing section inner spacing |
+| `gap-16` | 64px | Marketing between-section gap (mobile) |
+| `gap-24` | 96px | Marketing between-section gap (desktop) |
+
+---
+
+## Glass Tier Selection
+
+| Page Type | Glass Class | Rationale |
+|-----------|-------------|-----------|
+| Dashboard cards | `glass-panel` | Data containers, low elevation |
+| Settings sections | `glass-panel` | Grouped content areas |
+| Auth forms | `glass-floating` | Elevated, centered focus |
+| Marketing hero | `glass-floating` | High-impact visual |
+| Marketing sections | `glass-panel` | Structural containers |
+| Modals/dialogs | N/A (use Dialog component) | Radix handles backdrop |
+| Sidebar | none (use `bg-sidebar`) | Dedicated sidebar tokens |
+| Toasts | `glass-overlay` | Transient, floating |
+
+---
+
+## Grid Patterns
+
+### KPI / Stats Row
+
+```
+Mobile (1 col):        Tablet (2 col):       Desktop (4 col):
++------------------+   +--------+--------+   +----+----+----+----+
+| KPI 1            |   | KPI 1  | KPI 2  |   |KPI1|KPI2|KPI3|KPI4|
++------------------+   +--------+--------+   +----+----+----+----+
+| KPI 2            |   | KPI 3  | KPI 4  |
++------------------+   +--------+--------+
+
+grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 lg:gap-6
+```
+
+### Chart Grid
+
+```
+Mobile (stacked):      Desktop (2 col):
++------------------+   +-----------+-----------+
+| Chart 1 (full)   |   | Chart 1   | Chart 2   |
++------------------+   +-----------+-----------+
+| Chart 2 (full)   |   | Chart 3 (full width)  |
++------------------+   +-----------------------+
+
+grid grid-cols-1 lg:grid-cols-2 gap-4 lg:gap-6
+// Full-width chart: className="lg:col-span-2"
+```
+
+### Feature Grid (Marketing)
+
+```
+Mobile (1 col):        Tablet (2 col):       Desktop (3 col):
++------------------+   +--------+--------+   +------+------+------+
+| Feature 1        |   | Feat 1 | Feat 2 |   |Feat 1|Feat 2|Feat 3|
++------------------+   +--------+--------+   +------+------+------+
+
+grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6 lg:gap-8
+```
+
+### Settings Layout
+
+```
+Mobile (stacked):           Desktop (sidebar + content):
++----------------------+    +----------+------------------+
+| [Tab nav scrollable] |    | Sidebar  | Content area     |
++----------------------+    | nav      |                  |
+| Section Card 1       |    |          | Section Card 1   |
++----------------------+    |          +------------------+
+| Section Card 2       |    |          | Section Card 2   |
++----------------------+    +----------+------------------+
+```
+
+### 3-Panel Agent Workbench
+
+```
+Mobile (stacked):    Tablet (2 col):         Desktop (3 col):
++--------------+     +--------+---------+    +------+----------+------+
+| Conversation |     | Team   | Conver- |    | Team | Conver-  | Work |
++--------------+     | Panel  | sation  |    | &    | sation   | &    |
+| Composer     |     |        +---------+    |Status|          | Logs |
++--------------+     |        | Composer|    |      +----------+      |
+| Team Panel   |     +--------+---------+    |      | Composer |      |
++--------------+                             +------+----------+------+
+
+// Desktop: grid grid-cols-[280px_1fr_320px] h-dvh
+// Tablet:  grid grid-cols-[240px_1fr]
+// Mobile:  flex flex-col
+```
+
+---
+
+## Section Ordering Principles
+
+1. **Information hierarchy**: Most important content first (KPIs above charts, hero above features)
+2. **Action proximity**: Primary CTAs near the decision context
+3. **Progressive disclosure**: Overview -> detail -> action
+4. **Consistent chrome**: Shell and navigation are always visible/accessible
+
+### Standard Orders by Page Type
+
+- **Dashboard**: Header -> KPI row -> Primary chart -> Secondary charts -> Activity feed
+- **Marketing**: Hero -> Logo cloud -> Features -> Social proof -> Pricing teaser -> Testimonials -> FAQ -> CTA -> Footer
+- **Agency Home**: Hero -> Logo cloud -> Services grid -> ProcessFlowBlock -> Outcome stats -> Testimonials -> FAQ -> CTA
+- **Digital Workers**: Hero -> AgentProfileGridBlock -> Per-agent deep dives -> WorkflowGraph -> Integrations -> FAQ -> CTA
+- **Service Detail**: Hero -> SolutionShowcaseBlock -> Features -> ProcessFlowBlock -> Stats -> Testimonials -> CTA
+- **About/Team**: Mission hero -> Values (FeatureGridBlock) -> Team (TeamBlock) -> Company stats -> Partners -> CTA
+- **Contact**: Heading -> ContactBlock -> Company info cards -> FAQ
+- **Settings**: Settings nav -> Profile -> Preferences -> Notifications -> Integrations -> Danger zone
+- **CRUD List**: Header + search -> Filter bar -> Data table -> Pagination
+- **Auth**: Brand/illustration panel + Auth card (login/signup form)

package/.agents/skills/seed/references/dashboard-patterns.md

@@ -0,0 +1,101 @@
+# Dashboard Patterns Reference
+
+What makes Seed dashboards different from stock shadcn/ui and how to apply the design system's opinionated layer.
+
+---
+
+## Seed vs. Stock shadcn: 10 Techniques
+
+| # | Technique | Stock shadcn | Seed Dashboard |
+|---|-----------|-------------|----------------|
+| 1 | **Surface treatment** | `bg-card` solid fill | `glass-panel` with backdrop-blur, noise texture, emboss border |
+| 2 | **KPI typography** | `text-2xl font-bold` | `.metric-value` class + `text-3xl font-bold tracking-tight tabular-nums` |
+| 3 | **Number animation** | Static render | `SlidingNumber` (digit roll) or `CountingNumber` (count up) |
+| 4 | **Entrance motion** | None (instant mount) | `StaggerChildren` 80ms stagger on KPI row, `ScrollFadeIn` on chart sections |
+| 5 | **Trend context** | Badge with +/- text | `TrendIndicator` component + `Sparkline` mini chart in every KPI card |
+| 6 | **Chart theming** | Hardcoded hex colors | Semantic tokens `chart-1` through `chart-8` via `ChartContainer` config |
+| 7 | **Data freshness** | None | `DataFreshness` component showing last-updated timestamp, optional live pulse |
+| 8 | **Loading states** | Spinner or nothing | Skeleton grid matching exact card dimensions, `Skeleton` components for each element |
+| 9 | **Glass budget** | N/A (no glass) | Max 5 glass-panel per page. Overflow uses `bg-surface` solid fill |
+
+---
+
+## Typography Enhancement
+
+Seed dashboards use enhanced metric typography that stock shadcn does not provide.
+
+### The `.metric-value` class
+
+Defined in `src/index.css`, this class applies:
+- `font-feature-settings: "tnum" 1` (tabular numbers for column alignment)
+- `letter-spacing: -0.025em` (tighter tracking for large numbers)
+- `-webkit-font-smoothing: antialiased` (crisp rendering)
+
+### Recommended metric stack
+
+```tsx
+<SlidingNumber
+  value={kpi.value}
+  className="metric-value text-3xl font-bold tracking-tight tabular-nums"
+/>
+```
+
+Key properties:
+- `text-3xl` (1.875rem): large enough to be a focal point, small enough to fit 4 across
+- `font-bold` (700): strong weight separation from labels
+- `tracking-tight` (-0.025em): tighter than body text for number density
+- `tabular-nums`: fixed-width digits so values don't shift when animating
+
+### Label hierarchy
+
+| Element | Classes | Size |
+|---------|---------|------|
+| KPI label | `text-text-secondary text-sm` | 14px |
+| KPI value | `metric-value text-3xl font-bold tracking-tight tabular-nums` | 30px |
+| KPI trend | `text-sm` (via TrendIndicator) | 14px |
+| Comparison text | `text-text-tertiary text-xs` | 12px |
+| Chart title | Heading `level={4} size="title"` | 18px |
+| Chart axis labels | Recharts default | 12px |
+
+---
+
+## Color Expansion
+
+The base chart palette provides 6 tokens. Seed extends to 8 for dashboards that need more series.
+
+| Token | Role | Hex (arctic dark) | Typical Use |
+|-------|------|-------------------|-------------|
+| `chart-1` | Primary | `#E8B931` (gold) | Revenue, throughput, primary metric |
+| `chart-2` | Secondary | `#3B82F6` (blue) | Users, latency, secondary metric |
+| `chart-3` | Tertiary | `#22C55E` (green) | Growth, conversions, positive |
+| `chart-4` | Quaternary | `#14B8A6` (teal) | Enterprise, high-value segments |
+| `chart-5` | Quinary | `#EF4444` (red) | Churn, errors, negative |
+| `chart-6` | Senary | `#A855F7` (violet) | Auxiliary series |
+| `chart-7` | Septenary | `#A78BFA` (lavender) | Secondary auxiliary, comparison overlays |
+| `chart-8` | Octonary | `#FB923C` (peach) | Warm accent, seasonal data, promotions |
+
+### Color assignment rules
+
+1. Assign colors by semantic meaning, not by series order
+2. Keep assignments consistent within a dashboard variant (e.g., SaaS always maps `chart-1` to MRR)
+3. Never reuse a color for two different metrics on the same page
+4. Red (`chart-5`) is reserved for negative/error metrics
+5. If you need 9+ colors, the dashboard has too many series. Split into tabs or sub-pages
+
+---
+
+## What is Deliberately NOT Included
+
+These patterns were evaluated and rejected for Seed dashboards.
+
+| Pattern | Why Not |
+|---------|---------|
+| Cursor parallax on cards | Distracting in a data-focused context. Dashboards are scanned, not explored. Motion budget is better spent on entrance animation and number transitions. |
+| `@nivo` charts | Adds 200KB+ bundle weight with marginal visual improvement over Recharts. Seed's ChartContainer + semantic tokens achieve the same themed result with the existing Recharts dependency. |
+| `rough-notation` underlines | Whimsical hand-drawn style conflicts with the precision aesthetic of monitoring and analytics dashboards. Acceptable in marketing pages, not in data surfaces. |
+| Gradient fills on area charts | Solid `fillOpacity={0.15}` reads cleaner at small sizes and prints better. Gradients also interact poorly with glass-panel backdrop-blur, creating visual noise. |
+| Auto-refreshing charts (polling) | Not a DS concern. The dashboard recipe provides `DataFreshness` UI. Polling/websocket logic belongs in the consumer app's data layer, not in UI components. |
+| Drag-to-reorder widgets | Grid layout is intentional and opinionated. Draggable dashboards create visual entropy and break the glass budget contract. If users need customization, use a saved-views pattern with predefined layouts. |
+| Tooltip on every data point | Only chart tooltips via `ChartTooltip` + `ChartTooltipContent`. No hover tooltips on KPI cards, badges, or static text. Tooltips are for charts and truncated content only. |
+| Dark-only dashboard theme | Dashboards must work in both light and dark mode. Never hardcode dark backgrounds (`bg-zinc-950`, `bg-[#0F1114]`). Use semantic tokens (`bg-background`, `bg-surface`). |
+| Tab-per-chart navigation | Tabs hide data. Prefer a scrollable single-page layout with `ScrollFadeIn` for progressive disclosure. Use tabs only for fundamentally different views (Overview vs. Detail). |