@vadimcomanescu/nadicode-design-system 2.0.0

package/.agents/skills/seed/recipes/agents-chat.md

@@ -0,0 +1,281 @@
+# Recipe: Agent Chat
+
+3-region agent workbench for AI agent interaction, tool monitoring, and artifact inspection.
+
+## Route Patterns
+
+- `/agents`
+- `/voice-agents`
+
+## Shell
+
+`app-shell` (Sidebar + top bar + SearchCommand)
+
+---
+
+## Layout Blueprint (Desktop)
+
+```
++--+------+---------------------------+---------+
+|  | Team | Conversation              | Work    |
+|S | Panel|                           | Panel   |
+|I |      | [AgentMessageBubble]      |         |
+|D | Agent| [ToolCallCard]            | [Tabs]  |
+|E | list | [ThinkingIndicator]       | Work    |
+|B | with | [AgentMessageBubble]      | Logs    |
+|A | status| [ApprovalCard]           | Files   |
+|R |      |                           |         |
+|  | Team | [AgentMessageBubble]      | Code    |
+|  | metrics|                         | Diff    |
+|  |      |                           |         |
+|  |      +---------------------------+ Artifact|
+|  |      | Composer                  | Card    |
+|  |      | [Textarea] [Send]         |         |
++--+------+---------------------------+---------+
+
+Mobile: Conversation + Composer only.
+        Team panel: left Sheet. Work panel: right Sheet.
+```
+
+---
+
+## Section Sequence
+
+### 1. Team & Status Panel (left, 280px)
+
+```tsx
+<aside className="hidden xl:flex flex-col w-[280px] border-r border-border bg-surface/50">
+  <div className="p-4 border-b border-border">
+    <Heading level={4} size="title" >Team</Heading>
+  </div>
+  <ScrollArea className="flex-1">
+    <AgentTeamPanel agents={agents} activeAgent={active} onSelect={setActive} />
+    <div className="p-4 border-t border-border">
+      <WorkflowGraph nodes={workflowNodes} edges={workflowEdges} />
+    </div>
+    <div className="p-4 mt-auto">
+      <AgentMetricsCard metrics={runMetrics} />
+    </div>
+  </ScrollArea>
+  <div className="p-4 border-t border-border">
+    <ContextMeter used={contextUsed} total={contextTotal} />
+  </div>
+</aside>
+```
+
+### 2. Conversation Region (center, flex-1)
+
+```tsx
+<main className="flex-1 flex flex-col min-w-0">
+  {/* Mobile header with panel triggers */}
+  <header className="xl:hidden flex items-center gap-2 p-3 border-b border-border">
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button variant="ghost" size="icon"><UsersIcon size={16} /></Button>
+      </SheetTrigger>
+      <SheetContent side="left"><AgentTeamPanel ... /></SheetContent>
+    </Sheet>
+    <Heading level={4} size="title"  className="flex-1 text-center truncate">
+      {runTitle}
+    </Heading>
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button variant="ghost" size="icon"><FileTextIcon size={16} /></Button>
+      </SheetTrigger>
+      <SheetContent side="right"><WorkPanel ... /></SheetContent>
+    </Sheet>
+  </header>
+
+  {/* Message thread */}
+  <ScrollArea className="flex-1 p-4" aria-live="polite">
+    {messages.map(msg => {
+      if (msg.type === "thinking") return <ThinkingIndicator key={msg.id} />
+      if (msg.type === "tool") return (
+        <ToolCallCard key={msg.id} name={msg.tool} args={msg.args}
+          status={msg.status} result={msg.result} />
+      )
+      if (msg.type === "approval") return (
+        <ApprovalCard key={msg.id} action={msg.action}
+          onApprove={() => approve(msg.id)} onReject={() => reject(msg.id)} />
+      )
+      return (
+        <AgentMessageBubble key={msg.id} role={msg.role}
+          content={msg.content} isStreaming={msg.isStreaming} />
+      )
+    })}
+  </ScrollArea>
+
+  {/* Composer */}
+  <div className="p-4 border-t border-border">
+    <div className="flex items-end gap-2">
+      <Textarea
+        placeholder="Type a message..."
+        className="flex-1 min-h-[44px] max-h-[200px]"
+        value={input}
+        onChange={e => setInput(e.target.value)}
+        onKeyDown={handleKeyDown}
+      />
+      <Button onClick={handleSend} disabled={!input.trim() || isSending}>
+        <SendIcon size={16} />
+      </Button>
+    </div>
+  </div>
+</main>
+```
+
+### 3. Work Panel (right, 320px)
+
+```tsx
+<aside className="hidden xl:flex flex-col w-[320px] border-l border-border">
+  <Tabs value={workTab} onValueChange={setWorkTab} className="flex flex-col h-full">
+    <TabsList className="mx-4 mt-4">
+      <TabsTrigger value="work">Work</TabsTrigger>
+      <TabsTrigger value="logs">Logs</TabsTrigger>
+      <TabsTrigger value="files">Files</TabsTrigger>
+    </TabsList>
+    <ScrollArea className="flex-1">
+      <TabsContent value="work" className="p-4 space-y-4">
+        {artifacts.map(a => <ArtifactCard key={a.id} {...a} />)}
+      </TabsContent>
+      <TabsContent value="logs" className="p-4">
+        <AgentTerminal lines={logLines} />
+      </TabsContent>
+      <TabsContent value="files" className="p-4 space-y-4">
+        {diffs.map(d => <CodeDiffViewer key={d.file} {...d} />)}
+      </TabsContent>
+    </ScrollArea>
+  </Tabs>
+</aside>
+```
+
+---
+
+## Animation Storyboard
+
+```
+ANIMATION STORYBOARD
+====================
+BUDGET: 300ms (shell) | STREAMING: continuous | REDUCED: opacity-only
+
+T+0ms     [shell]     All panels visible           (instant)
+T+50ms    [team]      Team panel content fades in    {fadeIn, snappy}
+T+100ms   [messages]  Message history fades in       {fadeIn, snappy}
+T+200ms   [work]      Work panel content fades in    {fadeIn, snappy}
+
+NEW MESSAGE (runtime):
+T+0ms     [bubble]    Message slides up from bottom  {slideInUp, snappy, y: 16px}
+
+TOOL CALL (runtime):
+T+0ms     [toolcard]  Card expands in-place          {scaleIn, snappy}
+T+0ms     [status]    Status badge animates           {fadeIn, micro}
+
+THINKING (runtime):
+T+0ms     [dots]      Pulsing dot animation           (continuous CSS)
+
+APPROVAL (runtime):
+T+0ms     [card]      ApprovalCard scales in          {scaleIn, gentle}
+
+REDUCED MOTION: Items appear instantly, no slide/scale
+```
+
+---
+
+## Required Components
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| `AgentTeamPanel` | `@vadimcomanescu/nadicode-design-system/agent-team-panel` | Team member list |
+| `AgentStatus` | `@vadimcomanescu/nadicode-design-system/agent-status` | Connection status |
+| `AgentTimeline` | `@vadimcomanescu/nadicode-design-system/agent-timeline` | Action timeline |
+| `AgentMetricsCard` | `@vadimcomanescu/nadicode-design-system/agent-metrics-card` | Run metrics |
+| `ConversationThread` | `@vadimcomanescu/nadicode-design-system/conversation-thread` | Message rendering |
+| `AgentMessageBubble` | `@vadimcomanescu/nadicode-design-system/agent-message-bubble` | Individual messages |
+| `ThinkingIndicator` | `@vadimcomanescu/nadicode-design-system/thinking-indicator` | Processing state |
+| `ToolCallCard` | `@vadimcomanescu/nadicode-design-system/tool-call-card` | Tool invocations |
+| `ApprovalCard` | `@vadimcomanescu/nadicode-design-system/approval-card` | Human approval flow |
+| `CodeDiffViewer` | `@vadimcomanescu/nadicode-design-system/code-diff-viewer` | Code changes |
+| `ArtifactCard` | `@vadimcomanescu/nadicode-design-system/artifact-card` | Generated outputs |
+| `AgentTerminal` | `@vadimcomanescu/nadicode-design-system/agent-terminal` | Command output |
+| `WorkflowGraph` | `@vadimcomanescu/nadicode-design-system/workflow-graph` | DAG execution flow |
+| `ContextMeter` | `@vadimcomanescu/nadicode-design-system/context-meter` | Context window usage |
+| `SourceCitation` | `@vadimcomanescu/nadicode-design-system/source-citation` | Referenced sources |
+| `Tabs` | `@vadimcomanescu/nadicode-design-system/tabs` | Work panel tabs |
+| `Textarea` | `@vadimcomanescu/nadicode-design-system/textarea` | Composer input |
+| `Button` | `@vadimcomanescu/nadicode-design-system/button` | Send, panel triggers |
+| `ScrollArea` | `@vadimcomanescu/nadicode-design-system/scroll-area` | Scrollable regions |
+| `Sheet` | `@vadimcomanescu/nadicode-design-system/sheet` | Mobile panel drawers |
+
+### Allowed (optional)
+
+`HandoffIndicator`, `MemoryInspector`, `StreamingText`, `Badge`, `Avatar`, `AgentAvatar`, `Resizable`
+
+### Forbidden
+
+`HeroBlock`, `PricingBlock`, `FormWizard`, `DataTable`, marketing blocks, decorative effects
+
+---
+
+## Required States
+
+| State | Trigger | Visual |
+|-------|---------|--------|
+| `empty` | No active run | `Empty` with "Start a conversation" message |
+| `loading` | History loading | Skeleton message bubbles |
+| `running` | Agent(s) active | Live conversation with streaming |
+| `thinking` | Agent processing | `ThinkingIndicator` in message thread |
+| `blocked-approval` | Awaiting user action | `ApprovalCard` prominent in thread |
+| `failed` | Run or tool error | Error message in thread + retry option |
+| `complete` | Run finished | Final message with artifacts summary |
+| `over-budget` | Cost/token threshold exceeded | Warning badge on metrics, pause prompt |
+
+---
+
+## Responsive Contract
+
+| Breakpoint | Team Panel | Conversation | Work Panel |
+|------------|------------|-------------|------------|
+| Mobile | Hidden (Sheet, left) | Full width + composer | Hidden (Sheet, right) |
+| `lg:` | Sidebar 280px | Flex-1 | Hidden (Sheet) |
+| `xl:` | Sidebar 280px | Flex-1 | Panel 320px |
+
+---
+
+## Styling Rules
+
+- Panel backgrounds: `bg-surface/50` or `bg-background`
+- Panel borders: `border-border`
+- Message bubbles: styled by `AgentMessageBubble` (role-based)
+- Tool call cards: `glass-panel` with status color
+- Composer: `border-t border-border` with `p-4`
+- No raw palette colors
+
+---
+
+## Accessibility
+
+- Message thread uses `aria-live="polite"` for streaming updates
+- All interactive controls have visible focus rings
+- Panel toggles on mobile have `aria-label`
+- Composer textarea has `aria-label="Message input"`
+- Approval buttons are clearly labeled (approve/reject)
+- Tab navigation for work panel is keyboard accessible
+
+---
+
+## Reference Implementations
+
+- `src/app/voice-agents/page.tsx`
+- `src/components/pages/VoiceAgentsPage.tsx`
+- `src/components/blocks/AgentConversationBlock.tsx`
+- `src/components/blocks/ChatLayout.tsx`
+
+---
+
+## Verification
+
+```bash
+npx tsc --noEmit
+npm run lint
+npm run test
+npx vitest run src/test/css-variable-usage.test.ts
+```

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

@@ -0,0 +1,253 @@
+# Recipe: Analytics
+
+Trend analysis page with date filters, KPI summary, chart grid, and data breakdowns.
+
+## Route Pattern
+
+`/analytics`
+
+## Shell
+
+`app-shell` (Sidebar + top bar + SearchCommand)
+
+---
+
+## Layout Blueprint (Desktop)
+
+```
++--+---------------------------------------------+
+|  | Breadcrumb: Home > Analytics                 |
+|S | Analytics          [DateRange] [Export] [Tab] |
+|I |                                               |
+|D | +--------+ +--------+ +--------+ +--------+  |
+|E | | KPI 1  | | KPI 2  | | KPI 3  | | KPI 4  | |
+|B | +--------+ +--------+ +--------+ +--------+  |
+|A |                                               |
+|R | +------------------------------------------+  |
+|  | | Primary Chart (AreaChart, full width)    |  |
+|  | |                                          |  |
+|  | +------------------------------------------+  |
+|  |                                               |
+|  | +-------------------+ +--------------------+  |
+|  | | Breakdown Chart   | | Distribution Chart |  |
+|  | | (BarChart)        | | (PieChart)         |  |
+|  | +-------------------+ +--------------------+  |
+|  |                                               |
+|  | +------------------------------------------+  |
+|  | | Data Table (detailed breakdown)          |  |
+|  | +------------------------------------------+  |
++--+---------------------------------------------+
+```
+
+---
+
+## Section Sequence
+
+### 1. Page Header + Controls
+
+```tsx
+<div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+  <div>
+    <Breadcrumb>...</Breadcrumb>
+    <Heading level={2} size="section" >Analytics</Heading>
+  </div>
+  <div className="flex items-center gap-3">
+    <DateRangePicker value={dateRange} onChange={setDateRange} />
+    <Button variant="outline"><DownloadIcon size={16} /> Export</Button>
+  </div>
+</div>
+```
+
+### 2. View Tabs (optional)
+
+```tsx
+<Tabs value={view} onValueChange={setView} className="mt-4">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="engagement">Engagement</TabsTrigger>
+    <TabsTrigger value="revenue">Revenue</TabsTrigger>
+  </TabsList>
+</Tabs>
+```
+
+### 3. KPI Summary Row
+
+```tsx
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 mt-6">
+  {kpis.map(kpi => (
+    <Card key={kpi.id} className="glass-panel p-6">
+      <Typography variant="small" className="text-text-secondary">{kpi.label}</Typography>
+      <div className="flex items-baseline gap-2 mt-1">
+        <CountingNumber value={kpi.value} className="text-2xl font-bold" />
+        <Badge variant={kpi.trend > 0 ? "success" : "destructive"}>
+          {kpi.trend > 0 ? "+" : ""}{kpi.trend}%
+        </Badge>
+      </div>
+      <Typography variant="small" className="text-text-tertiary mt-1">
+        vs. previous period
+      </Typography>
+    </Card>
+  ))}
+</div>
+```
+
+### 4. Primary Chart (full width)
+
+```tsx
+<Card className="glass-panel p-6 mt-6">
+  <div className="flex items-center justify-between mb-4">
+    <Heading level={4} size="title" >Trend Over Time</Heading>
+    <Select value={metric} onValueChange={setMetric}>
+      <SelectTrigger className="w-40"><SelectValue /></SelectTrigger>
+      <SelectContent>
+        <SelectItem value="visitors">Visitors</SelectItem>
+        <SelectItem value="revenue">Revenue</SelectItem>
+      </SelectContent>
+    </Select>
+  </div>
+  <AreaChart data={trendData} height={300} />
+</Card>
+```
+
+### 5. Secondary Charts (2 column)
+
+```tsx
+<div className="grid grid-cols-1 lg:grid-cols-2 gap-4 lg:gap-6 mt-6">
+  <Card className="glass-panel p-6">
+    <Heading level={4} size="title"  className="mb-4">By Category</Heading>
+    <BarChart data={breakdownData} />
+  </Card>
+  <Card className="glass-panel p-6">
+    <Heading level={4} size="title"  className="mb-4">Distribution</Heading>
+    <PieChart data={distributionData} />
+  </Card>
+</div>
+```
+
+### 6. Detailed Breakdown Table (optional)
+
+```tsx
+<Card className="glass-panel mt-6">
+  <div className="flex items-center justify-between p-6 pb-0">
+    <Heading level={4} size="title" >Detailed Breakdown</Heading>
+    <Input placeholder="Search..." className="w-48" />
+  </div>
+  <DataTable columns={breakdownColumns} data={breakdownRows} />
+</Card>
+```
+
+---
+
+## Animation Storyboard
+
+```
+ANIMATION STORYBOARD
+====================
+BUDGET: 550ms | SPRING: snappy | REDUCED: opacity-only
+
+T+0ms     [shell]     Sidebar + top bar visible    (instant)
+T+50ms    [header]    Title + date filter           {fadeInUp, snappy}
+T+100ms   [tabs]      View tabs                    {fadeIn, snappy}
+T+150ms   [kpi-1..4]  KPI cards stagger            {blockStagger, 80ms apart}
+T+470ms   [chart-1]   Primary chart fades in        {fadeIn, gentle}
+T+550ms   [chart-2]   Secondary charts fade in      {fadeIn, gentle}
+
+SCROLL-TRIGGERED:
+[table]    DataTable ScrollFadeIn at 20%            {fadeIn, snappy}
+
+DATE FILTER CHANGE:
+[kpis]     CountingNumber animate to new values
+[charts]   Chart data transitions smoothly (recharts built-in)
+
+REDUCED MOTION: All items visible immediately
+```
+
+---
+
+## Required Components
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| `Card` | `@vadimcomanescu/nadicode-design-system/card` | KPI cards, chart containers |
+| `Badge` | `@vadimcomanescu/nadicode-design-system/badge` | Trend indicators |
+| `Typography` | `@vadimcomanescu/nadicode-design-system/typography` | Titles, labels |
+| `Breadcrumb` | `@vadimcomanescu/nadicode-design-system/breadcrumb` | Navigation |
+| `Button` | `@vadimcomanescu/nadicode-design-system/button` | Export, actions |
+| `DateRangePicker` | `@vadimcomanescu/nadicode-design-system/date-range-picker` | Date filter |
+| `Tabs` | `@vadimcomanescu/nadicode-design-system/tabs` | View switching |
+| `Select` | `@vadimcomanescu/nadicode-design-system/select` | Metric selector |
+| `AreaChart` | `@vadimcomanescu/nadicode-design-system/charts/area-chart` | Primary trend |
+| `BarChart` | `@vadimcomanescu/nadicode-design-system/charts/bar-chart` | Category breakdown |
+| `PieChart` | `@vadimcomanescu/nadicode-design-system/charts/pie-chart` | Distribution |
+| `CountingNumber` | `@vadimcomanescu/nadicode-design-system/text-effects/counting-number` | Animated KPIs |
+| `Skeleton` | `@vadimcomanescu/nadicode-design-system/skeleton` | Loading state |
+| `Empty` | `@vadimcomanescu/nadicode-design-system/empty` | No-data state |
+
+### Allowed (optional)
+
+`LineChart`, `RadarChart`, `RadialBarChart`, `HeatmapChart`, `DataTable`, `Tooltip`, `Progress`
+
+### Forbidden
+
+`HeroBlock`, `FormWizard`, `AuthLayout`, decorative effects, agentic components
+
+---
+
+## Required States
+
+| State | Trigger | Visual |
+|-------|---------|--------|
+| `loading` | Initial data fetch or filter change | Skeleton KPIs + skeleton chart areas |
+| `empty` | No data for selected range | `Empty` with chart icon, "No data for this period" |
+| `has-data` | Data loaded | Full charts and KPIs |
+| `error` | API failure | `Alert` variant="destructive" with retry |
+| `date-filtered` | User changes date range | KPIs animate, charts re-render with new data |
+
+---
+
+## Responsive Contract
+
+| Breakpoint | KPIs | Charts | Table |
+|------------|------|--------|-------|
+| Mobile | 1 col | 1 col, stacked | Horizontal scroll |
+| `sm:` | 2 col | 1 col | Horizontal scroll |
+| `lg:` | 4 col | Primary full, secondary 2-col | Full table |
+
+---
+
+## Styling Rules
+
+- Chart containers: `glass-panel p-6`
+- Chart colors: only `chart-1` through `chart-6` tokens
+- KPI cards: `glass-panel p-6`
+- No raw palette colors
+- Grid gaps: `gap-4 lg:gap-6`
+
+---
+
+## Accessibility
+
+- Charts use `ChartContainer` with `aria-label`
+- Date range picker is keyboard accessible
+- KPI trend badges include direction in text ("up 12%")
+- Tab navigation is keyboard-navigable
+- Export button has `aria-label="Export analytics data"`
+
+---
+
+## Reference Implementations
+
+- `src/components/blocks/ChartCollectionBlock.tsx`
+- `src/components/blocks/StatsBlock.tsx`
+- `src/components/blocks/InteractiveAreaChartBlock.tsx`
+
+---
+
+## Verification
+
+```bash
+npx tsc --noEmit
+npm run lint
+npm run test
+npx vitest run src/test/css-variable-usage.test.ts
+```