@vadimcomanescu/nadicode-design-system 2.0.0

package/.agents/skills/seed/recipes/dashboard.md

@@ -0,0 +1,354 @@
+# Recipe: Dashboard
+
+Overview/summary surface with KPIs, trends, charts, and quick actions. The primary authenticated landing page for data-driven apps.
+
+## Route Pattern
+
+`/dashboard`
+
+## Shell
+
+`app-shell` (Sidebar + top bar + SearchCommand)
+
+## Layout Blueprint (Desktop)
+
+```
++--+------------------------------------------------+
+|S | Breadcrumb: Home > Dashboard                    |
+|I | Dashboard          [DateRange] [+ Action]       |
+|D |                                                  |
+|E | +----------+ +----------+ +----------+ +------+ |
+|B | | KPI 1    | | KPI 2    | | KPI 3    | | KPI 4| |
+|A | | value    | | value    | | value    | | val  | |
+|R | | [spark]  | | [spark]  | | [spark]  | | [sp] | |
+|  | +----------+ +----------+ +----------+ +------+ |
+|  |                                                  |
+|  | +-------------------------------+ +-----------+  |
+|  | | Primary Chart (AreaChart)     | | Secondary |  |
+|  | | span-2                        | | (BarChart)|  |
+|  | +-------------------------------+ +-----------+  |
+|  |                                                  |
+|  | +--------------------------------------------+  |
+|  | | Activity Feed / Recent Items               |  |
+|  | +--------------------------------------------+  |
++--+------------------------------------------------+
+```
+
+---
+
+## Section Sequence
+
+### 1. Page Header
+
+```tsx
+<div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+  <div>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem><BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink></BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+    <Heading level={2} size="section" >Dashboard</Heading>
+  </div>
+  <div className="flex items-center gap-3">
+    <DataFreshness lastUpdated={lastUpdated} isLive={false} />
+    <DatePickerWithRange value={dateRange} onChange={setDateRange} />
+    <Button>
+      <PlusIcon size={16} />
+      New Report
+    </Button>
+  </div>
+</div>
+```
+
+### 2. KPI Row
+
+Wrap in `StaggerChildren` for entrance animation. Each card includes a `Sparkline` for trend context and a `TrendIndicator` for directional change.
+
+```tsx
+<StaggerChildren staggerMs={80} className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 lg:gap-6">
+  {kpis.map(kpi => (
+    <Card key={kpi.id} className="glass-panel p-6">
+      <div className="flex items-center justify-between">
+        <Typography variant="small" className="text-text-secondary">
+          {kpi.label}
+        </Typography>
+        <TrendIndicator value={kpi.trend} />
+      </div>
+      <div className="mt-2">
+        <SlidingNumber
+          value={kpi.value}
+          className="metric-value text-3xl font-bold tracking-tight tabular-nums"
+        />
+      </div>
+      <div className="mt-3 h-10">
+        <Sparkline data={kpi.sparkData} color={`var(--color-${kpi.chartColor})`} />
+      </div>
+    </Card>
+  ))}
+</StaggerChildren>
+```
+
+**Key details:**
+- `metric-value` CSS class provides enhanced typography (defined in `index.css`)
+- `tabular-nums` and `tracking-tight` keep numbers aligned across cards
+- `SlidingNumber` for smooth digit transitions (preferred over `CountingNumber` for live dashboards)
+- `Sparkline` height fixed at `h-10` (40px) for visual consistency
+- `TrendIndicator` renders a colored arrow + percentage, auto-styles green/red
+
+### 3. Charts Section
+
+Use asymmetric grid (`lg:grid-cols-3`) with the primary chart spanning 2 columns.
+
+```tsx
+<ScrollFadeIn threshold={0.2} spring="gentle">
+  <div className="grid grid-cols-1 lg:grid-cols-3 gap-4 lg:gap-6">
+    {/* Primary chart: 2/3 width */}
+    <Card className="glass-panel p-6 lg:col-span-2">
+      <div className="flex items-center justify-between mb-4">
+        <Heading level={4} size="title" >Revenue Trend</Heading>
+        <Select value={chartMetric} onValueChange={setChartMetric}>
+          <SelectTrigger className="w-36">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="revenue">Revenue</SelectItem>
+            <SelectItem value="orders">Orders</SelectItem>
+          </SelectContent>
+        </Select>
+      </div>
+      <ChartContainer config={revenueChartConfig} className="h-[300px]">
+        <AreaChart data={revenueData}>
+          <CartesianGrid strokeDasharray="3 3" />
+          <XAxis dataKey="date" />
+          <YAxis />
+          <ChartTooltip content={<ChartTooltipContent />} />
+          <Area
+            type="monotone"
+            dataKey="value"
+            fill="var(--color-chart-1)"
+            stroke="var(--color-chart-1)"
+            fillOpacity={0.15}
+          />
+        </AreaChart>
+      </ChartContainer>
+    </Card>
+
+    {/* Secondary chart: 1/3 width */}
+    <Card className="glass-panel p-6">
+      <Heading level={4} size="title"  className="mb-4">By Category</Heading>
+      <ChartContainer config={categoryChartConfig} className="h-[300px]">
+        <BarChart data={categoryData}>
+          <CartesianGrid strokeDasharray="3 3" />
+          <XAxis dataKey="name" />
+          <YAxis />
+          <ChartTooltip content={<ChartTooltipContent />} />
+          <Bar dataKey="value" fill="var(--color-chart-2)" radius={[4, 4, 0, 0]} />
+        </BarChart>
+      </ChartContainer>
+    </Card>
+  </div>
+</ScrollFadeIn>
+```
+
+**Key details:**
+- Always use `ChartContainer` with a `config` object (provides aria-label and theme-aware colors)
+- Always use `ChartTooltip` + `ChartTooltipContent` (never custom tooltip divs)
+- Chart colors reference tokens only: `var(--color-chart-1)` through `var(--color-chart-8)`
+- `fillOpacity={0.15}` for area charts (premium transparency, not solid fills)
+
+### 4. Activity Section
+
+```tsx
+<ScrollFadeIn threshold={0.2} spring="gentle">
+  <Card className="glass-panel p-6">
+    <div className="flex items-center justify-between mb-4">
+      <Heading level={4} size="title" >Recent Activity</Heading>
+      <Button variant="ghost" size="sm">View All</Button>
+    </div>
+    <Timeline
+      items={activityItems.map(item => ({
+        id: item.id,
+        title: item.title,
+        description: item.description,
+        timestamp: item.timestamp,
+        icon: item.icon,
+        variant: item.variant,
+      }))}
+    />
+  </Card>
+</ScrollFadeIn>
+```
+
+---
+
+## Animation Storyboard
+
+```
+ANIMATION STORYBOARD
+====================
+BUDGET: 550ms | SPRING: snappy | REDUCED: opacity-only
+
+T+0ms     [shell]     Sidebar + top bar visible         instant
+T+50ms    [header]    Page title + breadcrumb            {fadeInUp, snappy}
+T+130ms   [kpi-1]     First KPI + SlidingNumber          {StaggerChildren 80ms}
+T+210ms   [kpi-2]     Second KPI                         {StaggerChildren}
+T+290ms   [kpi-3]     Third KPI                          {StaggerChildren}
+T+370ms   [kpi-4]     Fourth KPI                         {StaggerChildren}
+T+450ms   [charts]    ChartCard section                  {ScrollFadeIn, gentle}
+T+550ms   [activity]  Activity section                   {ScrollFadeIn, gentle}
+
+DATE FILTER CHANGE:
+[kpis]     SlidingNumber digits roll to new values       built-in
+[sparklines] Sparkline data transitions                  recharts built-in
+[charts]   Chart data transitions smoothly               recharts built-in
+
+REDUCED MOTION: All items visible immediately, opacity 0->1 in 10ms
+```
+
+---
+
+## Required Components
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| `Card` | `@vadimcomanescu/nadicode-design-system/card` | KPI cards, chart containers, activity container |
+| `Sparkline` | `@vadimcomanescu/nadicode-design-system/charts/sparkline` | Mini trend line in KPI cards |
+| `TrendIndicator` | `@vadimcomanescu/nadicode-design-system/trend-indicator` | Directional change arrow + percentage |
+| `Badge` | `@vadimcomanescu/nadicode-design-system/badge` | Status badges, trend labels |
+| `Typography` | `@vadimcomanescu/nadicode-design-system/typography` | Page title, section headers, labels |
+| `Breadcrumb` | `@vadimcomanescu/nadicode-design-system/breadcrumb` | Navigation context |
+| `Button` | `@vadimcomanescu/nadicode-design-system/button` | Primary action, view-all links |
+| `AreaChart` | `@vadimcomanescu/nadicode-design-system/charts/area-chart` | Primary trend chart |
+| `BarChart` | `@vadimcomanescu/nadicode-design-system/charts/bar-chart` | Category breakdown |
+| `ChartContainer` | `@vadimcomanescu/nadicode-design-system/chart` | Wraps all charts with config + aria |
+| `ChartTooltip` | `@vadimcomanescu/nadicode-design-system/chart` | Theme-aware tooltip |
+| `Timeline` | `@vadimcomanescu/nadicode-design-system/timeline` | Activity feed |
+| `SlidingNumber` | `@vadimcomanescu/nadicode-design-system/text-effects/sliding-number` | Animated KPI values (digit roll) |
+| `CountingNumber` | `@vadimcomanescu/nadicode-design-system/text-effects/counting-number` | Animated KPI values (count up) |
+| `DatePickerWithRange` | `@vadimcomanescu/nadicode-design-system/date-range-picker` | Time filter |
+| `DataFreshness` | `@vadimcomanescu/nadicode-design-system/data-freshness` | Last-updated timestamp indicator |
+| `Skeleton` | `@vadimcomanescu/nadicode-design-system/skeleton` | Loading state placeholders |
+| `Empty` | `@vadimcomanescu/nadicode-design-system/empty` | No-data state |
+| `StaggerChildren` | `@vadimcomanescu/nadicode-design-system/stagger-children` | KPI row entrance stagger |
+| `ScrollFadeIn` | `@vadimcomanescu/nadicode-design-system/scroll-fade-in` | Below-fold entrance animation |
+| `Select` | `@vadimcomanescu/nadicode-design-system/select` | Chart metric selector |
+
+### Allowed (optional)
+
+`Tabs`, `Progress`, `ProgressRing`, `LineChart`, `PieChart`, `AgentMetricsCard`, `DataTable`, `Tooltip`, `StatusDot`, `HeatmapChart`
+
+### Forbidden
+
+`HeroBlock`, `PricingBlock`, `FormWizard`, `AuthLayout`, `TextReveal`, `AnimatedGradientText`, `AuroraEffect`, `MeteorShower`
+
+---
+
+## Required States
+
+| State | Trigger | Visual |
+|-------|---------|--------|
+| `loading` | Initial page load, date filter change | Skeleton grid: 4 skeleton cards (match KPI card height) + 2 skeleton chart containers + skeleton timeline rows |
+| `empty` | Zero data (first-time user) | `Empty` with chart icon, "No data yet" title, "Connect your first integration to start seeing metrics" description, primary CTA button |
+| `has-data` | Data loaded | Full layout as described above |
+| `error` | API failure | `Alert` variant="destructive" at top of content, with retry button. KPI cards show `--` values. Charts show empty state |
+
+### Loading Skeleton Pattern
+
+```tsx
+{/* KPI skeleton row */}
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 lg:gap-6">
+  {Array.from({ length: 4 }).map((_, i) => (
+    <Card key={i} className="glass-panel p-6">
+      <Skeleton className="h-4 w-24 mb-2" />
+      <Skeleton className="h-8 w-32 mb-3" />
+      <Skeleton className="h-10 w-full" />
+    </Card>
+  ))}
+</div>
+
+{/* Chart skeleton row */}
+<div className="grid grid-cols-1 lg:grid-cols-3 gap-4 lg:gap-6 mt-6">
+  <Card className="glass-panel p-6 lg:col-span-2">
+    <Skeleton className="h-6 w-40 mb-4" />
+    <Skeleton className="h-[300px] w-full rounded-lg" />
+  </Card>
+  <Card className="glass-panel p-6">
+    <Skeleton className="h-6 w-32 mb-4" />
+    <Skeleton className="h-[300px] w-full rounded-lg" />
+  </Card>
+</div>
+```
+
+---
+
+## Responsive Contract
+
+| Breakpoint | KPI Grid | Chart Grid | Activity | Sparklines |
+|------------|----------|------------|----------|------------|
+| Mobile | 1 col, stacked | 1 col, stacked | Full width | Hidden (`hidden sm:block`) |
+| `sm:` | 2 col | 1 col | Full width | Visible |
+| `lg:` | 4 col | 3 col (2+1 asymmetric) | Full width | Visible |
+
+---
+
+## Styling Rules
+
+- KPI cards: `glass-panel` class (max 4 glass cards in KPI row)
+- Chart containers: `glass-panel` class (max 1 additional glass card for activity = **5 total glass budget**)
+- Chart colors: `chart-1` through `chart-8` tokens only, via `var(--color-chart-N)`
+- Metric values: `metric-value` CSS class + `text-3xl font-bold tracking-tight tabular-nums`
+- Labels: `text-text-secondary` for KPI labels, `text-text-tertiary` for comparison text
+- Values: `text-text-primary` for metric numbers
+- No raw palette colors (`bg-zinc-*`, `text-gray-*`, hardcoded hex)
+- Grid gaps: `gap-4 lg:gap-6` consistently across all grid sections
+- Section spacing: `mt-6` between major sections (header, KPIs, charts, activity)
+
+### Glass Budget
+
+Dashboard pages have a **max 5 glass-panel** budget:
+- 4x KPI cards
+- 1x grouped chart/activity section (or split: 2 chart cards + 1 activity card if needed)
+
+If you need more containers, use `bg-surface` (solid) instead of `glass-panel`.
+
+---
+
+## Accessibility
+
+- KPI cards: each has `aria-label` describing metric name, value, and trend direction (e.g., `aria-label="Revenue: $45,231, up 12.5% from last period"`)
+- Charts: all wrapped in `ChartContainer` which provides `aria-label` describing the chart type and data summary
+- Date filter: fully keyboard accessible, announces selected range to screen readers
+- Activity timeline: rendered as semantic `<ol>` list markup with `role="feed"` or `aria-label="Recent activity"`
+- Trend indicators: include screen-reader text (e.g., `<span className="sr-only">increased by</span>`)
+- Color contrast: all text meets WCAG AA (4.5:1 body, 3:1 large text)
+
+---
+
+## Reference Implementations
+
+- `src/app/dashboard/page.tsx`
+- `src/components/blocks/StatsBlock.tsx` (KPI pattern)
+- `src/components/blocks/ChartBlock.tsx` (chart container)
+- `src/components/blocks/ChartCollectionBlock.tsx` (multi-chart grid)
+- `src/components/blocks/ActivityFeedBlock.tsx` (activity feed)
+
+---
+
+## Verification
+
+```bash
+npx tsc --noEmit
+npm run lint
+npm run test
+npx vitest run src/test/css-variable-usage.test.ts
+```
+
+Visual verification (mandatory): navigate to `/dashboard` in both light and dark mode. Check:
+- KPI values are readable (not washed out in light mode)
+- Glass panels have visible blur effect in dark mode
+- Sparklines render with correct chart-token colors
+- Skeleton loading state matches card dimensions
+- Date picker opens and is keyboard navigable

package/.agents/skills/seed/recipes/digital-workers.md

@@ -0,0 +1,314 @@
+# Recipe: Digital Workers
+
+"Meet your AI team" showcase page presenting AI agent profiles, capabilities, and workflow integration.
+
+## Route Pattern
+
+`/digital-workers`, `/agents`, or `/platform`
+
+## Shell
+
+`marketing-shell` (HeaderBlock + FooterBlock)
+
+---
+
+## Layout Blueprint (Desktop)
+
+```
++------------------------------------------------+
+| HeaderBlock: Logo  [Nav links]  [CTA Button]   |
++------------------------------------------------+
+|                                                 |
+|              HERO SECTION                       |
+|    "Meet Your AI Team"                          |
+|    Subtitle: digital workers intro              |
+|    [Primary CTA]  [Secondary CTA]              |
+|                                                 |
++------------------------------------------------+
+|                                                 |
+|         AGENT PROFILE GRID (BentoGrid)          |
+|  +----------------+ +----------+ +----------+   |
+|  |                 | | Agent 2  | | Agent 3  |   |
+|  |    Agent 1      | +----------+ +----------+   |
+|  |   (featured)    | +----------+ +----------+   |
+|  |                 | | Agent 4  | | Agent 5  |   |
+|  +----------------+ +----------+ +----------+   |
+|                                                 |
++------------------------------------------------+
+|                                                 |
+|   AGENT DEEP DIVE #1 (alternating)              |
+|   +-------------------+ +------------------+    |
+|   | Visual / Demo     | | Features list    |    |
+|   +-------------------+ +------------------+    |
+|                                                 |
++------------------------------------------------+
+|                                                 |
+|   AGENT DEEP DIVE #2 (reversed)                 |
+|   +------------------+ +-------------------+    |
+|   | Features list    | | Visual / Demo     |    |
+|   +------------------+ +-------------------+    |
+|                                                 |
++------------------------------------------------+
+|                                                 |
+|         WORKFLOW GRAPH                           |
+|   How agents collaborate on tasks               |
+|   [Agent A] → [Agent B] → [Agent C]            |
+|                                                 |
++------------------------------------------------+
+|         INTEGRATIONS                            |
+|   Logo grid of supported platforms              |
++------------------------------------------------+
+|                                                 |
+|         FAQ (Accordion)                         |
+|                                                 |
++------------------------------------------------+
+|         FINAL CTA SECTION                       |
+|    Headline + [CTA Button]                      |
++------------------------------------------------+
+| FooterBlock: columns + social + legal           |
++------------------------------------------------+
+```
+
+---
+
+## Section Sequence
+
+### 1. Header
+
+```tsx
+<HeaderBlock logo={<Logo />} links={navLinks} actions={<Button>Get Started</Button>} />
+```
+
+### 2. Hero Section
+
+```tsx
+<section className="relative py-24 md:py-32 overflow-hidden">
+  <ShaderBackground shader="meshGradient" intent="hero" opacity={0.2} />
+  <div className="relative z-10 max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 text-center">
+    <motion.div variants={heroStagger.container} initial="hidden" animate="visible">
+      <motion.div variants={heroStagger.child}>
+        <Badge variant="outline" className="mb-4">AI-Powered Team</Badge>
+      </motion.div>
+      <motion.h1 variants={heroStagger.child} className="text-4xl md:text-6xl font-bold tracking-tight">
+        Meet Your Digital Workers
+      </motion.h1>
+      <motion.p variants={heroStagger.child} className="mt-6 text-lg md:text-xl text-text-secondary max-w-2xl mx-auto">
+        Autonomous AI agents that work alongside your team, 24/7.
+      </motion.p>
+      <motion.div variants={heroStagger.child} className="mt-8 flex flex-col sm:flex-row gap-4 justify-center">
+        <Button size="lg">Deploy Your Team</Button>
+        <Button size="lg" variant="outline">See Them in Action</Button>
+      </motion.div>
+    </motion.div>
+  </div>
+</section>
+```
+
+### 3. Agent Profile Grid
+
+```tsx
+<ScrollFadeIn>
+  <section className="py-16 md:py-24">
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+      <div className="text-center mb-12">
+        <Heading level={2} size="section" >Your AI Team</Heading>
+        <Typography variant="lead" className="mt-4 text-text-secondary">
+          Specialized agents for every business function
+        </Typography>
+      </div>
+      <AgentProfileGridBlock agents={agents} />
+    </div>
+  </section>
+</ScrollFadeIn>
+```
+
+### 4. Agent Deep Dives (alternating FeatureBlocks)
+
+```tsx
+<ScrollFadeIn>
+  <section className="py-16 md:py-24 bg-muted">
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 space-y-24">
+      {agentDetails.map((agent, i) => (
+        <ScrollFadeIn key={agent.id}>
+          <FeatureBlock
+            title={agent.name}
+            description={agent.description}
+            features={agent.capabilities}
+            media={agent.visual}
+            reversed={i % 2 === 1}
+          />
+        </ScrollFadeIn>
+      ))}
+    </div>
+  </section>
+</ScrollFadeIn>
+```
+
+### 5. Workflow Graph
+
+```tsx
+<ScrollFadeIn>
+  <section className="py-16 md:py-24">
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+      <div className="text-center mb-12">
+        <Heading level={2} size="section" >How They Collaborate</Heading>
+        <Typography variant="lead" className="mt-4 text-text-secondary">
+          Agents work together seamlessly on complex workflows
+        </Typography>
+      </div>
+      <WorkflowGraph nodes={workflowNodes} edges={workflowEdges} />
+    </div>
+  </section>
+</ScrollFadeIn>
+```
+
+### 6. Integrations
+
+```tsx
+<ScrollFadeIn>
+  <section className="py-16 md:py-24 bg-muted">
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+      <IntegrationsBlock integrations={integrations} />
+    </div>
+  </section>
+</ScrollFadeIn>
+```
+
+### 7. FAQ
+
+```tsx
+<ScrollFadeIn>
+  <section className="py-16 md:py-24">
+    <FAQBlock items={faqItems} />
+  </section>
+</ScrollFadeIn>
+```
+
+### 8. Final CTA
+
+```tsx
+<ScrollFadeIn>
+  <section className="py-16 md:py-24">
+    <CallToActionBlock
+      title="Ready to build your AI team?"
+      description="Deploy your first digital worker in minutes."
+      action={<Button size="lg">Get Started</Button>}
+    />
+  </section>
+</ScrollFadeIn>
+```
+
+### 9. Footer
+
+```tsx
+<FooterBlock columns={footerColumns} social={socialLinks} legal={legalLinks} />
+```
+
+---
+
+## Animation Storyboard
+
+```
+ANIMATION STORYBOARD
+====================
+BUDGET: 1000ms (above-fold) | SPRING: dramatic (hero), snappy (rest) | REDUCED: opacity-only
+
+T+0ms     [nav]        Header visible                  (instant)
+T+100ms   [badge]      Badge appears                   {fadeIn, snappy}
+T+200ms   [headline]   Hero headline                   {fadeInUp, dramatic}
+T+350ms   [subtitle]   Hero subtitle                   {fadeInUp, dramatic}
+T+500ms   [ctas]       CTA buttons                     {fadeInUp, dramatic}
+T+700ms   [shader]     Hero shader appears             {fadeIn, gentle}
+
+SCROLL-TRIGGERED (below fold):
+[profiles]     ScrollFadeIn at 20% visible    {fadeInUp, snappy, stagger 100ms}
+[deep-dives]   ScrollFadeIn at 20% visible    {fadeInUp, snappy}
+[workflow]     ScrollFadeIn at 20% visible    {fadeIn, gentle, nodes stagger 200ms}
+[integrations] ScrollFadeIn at 20% visible    {fadeInUp, snappy}
+[faq]          ScrollFadeIn at 20% visible    {fadeInUp, snappy}
+[cta]          ScrollFadeIn at 20% visible    {scaleIn, gentle}
+
+REDUCED MOTION: All items visible immediately, opacity 0->1 in 10ms
+```
+
+---
+
+## Required Components
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| `HeaderBlock` | `@vadimcomanescu/nadicode-design-system/header-block` | Site navigation |
+| `FooterBlock` | `@vadimcomanescu/nadicode-design-system/footer-block` | Site footer |
+| `Button` | `@vadimcomanescu/nadicode-design-system/button` | CTAs |
+| `Badge` | `@vadimcomanescu/nadicode-design-system/badge` | Hero tag |
+| `Typography` | `@vadimcomanescu/nadicode-design-system/typography` | Headings, body text |
+| `ScrollFadeIn` | `@vadimcomanescu/nadicode-design-system/scroll-fade-in` | Below-fold animations |
+| `AgentProfileGridBlock` | `@vadimcomanescu/nadicode-design-system/agent-profile-grid-block` | Agent profile cards grid |
+
+### Allowed (optional)
+
+`HeroBlock`, `HeroSectionBlock`, `FeatureBlock`, `FeatureGridBlock`, `WorkflowGraph`, `IntegrationsBlock`, `FAQBlock`, `CallToActionBlock`, `StatsMarketingBlock`, `Card`, `BentoGrid`, `ShaderBackground`
+
+### Forbidden
+
+`Sidebar`, `DataTable`, `Form`, `FormWizard`, `SettingsLayout`, `ChatLayout`
+
+---
+
+## Required States
+
+| State | Trigger | Visual |
+|-------|---------|--------|
+| `default` | Page loaded | Full showcase content |
+| `mobile-navigation` | Hamburger tap | Mobile nav drawer/sheet |
+
+---
+
+## Responsive Contract
+
+| Breakpoint | Hero | Agent Grid | Deep Dives | Workflow | Content Width |
+|------------|------|------------|------------|----------|---------------|
+| Mobile | Stacked, text-center | 1 col | Stacked (image above) | Vertical | px-4 |
+| `sm:` | Stacked, text-center | 2 col | Stacked (image above) | Vertical | px-6, max-w-7xl |
+| `lg:` | Centered | 3 col bento | Side-by-side alternating | Horizontal | px-8, max-w-7xl |
+
+---
+
+## Styling Rules
+
+- Agent cards use `glass-panel` with hover elevation to `glass-floating`
+- Deep dive sections alternate `bg-background` and `bg-muted`
+- Workflow graph uses `border-accent` for active connections
+- Integration logos are grayscale with hover color reveal
+- No raw palette colors; semantic tokens only
+
+---
+
+## Accessibility
+
+- Hero heading is `<h1>`, section headings are `<h2>`
+- Agent cards are focusable with descriptive labels
+- Workflow graph has `aria-label` describing the flow
+- Skip-nav link to main content
+- All agent avatars/icons have alt text
+- Mobile nav is keyboard accessible with focus trap
+
+---
+
+## Reference Implementations
+
+- `src/components/blocks/AgentProfileGridBlock.tsx`
+- `src/components/ui/WorkflowGraph.tsx`
+- `src/components/blocks/FeatureBlock.tsx`
+- `src/components/blocks/IntegrationsBlock.tsx`
+
+---
+
+## Verification
+
+```bash
+npx tsc --noEmit
+npm run lint
+npm run test
+npx vitest run src/test/css-variable-usage.test.ts
+```