design-system/COMPONENT_GUIDE.md

# Cameleer3 Component Guide

> This file is for Claude Code to reference when building UI features.
> Keep it up to date when components are added or changed.

## Quick Decision Trees

### "I need to show a message to the user"
- Inline contextual note → **InfoCallout**
- Page-level attention banner → **Alert**
- Temporary non-blocking feedback → **Toast** (via `useToast`)
- Destructive action confirmation → **AlertDialog**
- Generic dialog with custom content → **Modal**

### "I need a form input"
- Single line text → **Input**
- Multiline text → **Textarea**
- On/off toggle → **Toggle**
- Yes/no with label → **Checkbox**
- One of N options (≤5) → **RadioGroup** + **RadioItem**
- One of N options (>5) → **Select**
- Date/time → **DateTimePicker**
- Date range → **DateRangePicker**
- Wrap any input with label/error/hint → **FormField**

### "I need to show loading state"
- Full component placeholder → **Skeleton** (text, circular, or rectangular)
- Inline spinner → **Spinner** (sm, md, lg)
- Operation progress → **ProgressBar** (determinate or indeterminate)

### "I need to show status"
- Dot indicator → **StatusDot** (live, stale, dead, success, warning, error, running)
- Labeled status → **Badge** with semantic color
- Removable label → **Tag**

### "I need navigation"
- App-level sidebar nav → **Sidebar** (via AppShell) — hierarchical trees with starring
- Breadcrumb trail → **Breadcrumb**
- Paginated data → **Pagination** (standalone) or **DataTable** (built-in pagination)
- Hierarchical tree navigation → **TreeView** (generic) or **SidebarTree** (sidebar-specific, internal)

### "I need floating content"
- Tooltip on hover → **Tooltip**
- Click-triggered panel → **Popover**
- Action menu → **Dropdown**
- Full-screen search/command → **CommandPalette**

### "I need to display data"
- Key metrics → **StatCard** (with optional sparkline/trend)
- Tabular data → **DataTable** (sortable, paginated)
- Time series → **LineChart**, **AreaChart**
- Categorical comparison → **BarChart**
- Inline trend → **Sparkline**
- Event log → **EventFeed**
- Processing pipeline → **ProcessorTimeline**

### "I need to organize content"
- Collapsible sections (standalone) → **Collapsible**
- Multiple collapsible sections (one/many open) → **Accordion**
- Tabbed content → **Tabs**
- Side panel inspector → **DetailPanel**
- Section with title + action → **SectionHeader**
- Empty content placeholder → **EmptyState**
- Grouped content box → **Card** (with optional accent)
- Grouped items with header + meta + footer → **GroupCard** (e.g., app instances)

### "I need to display text"
- Code/JSON payload → **CodeBlock** (with line numbers, copy button)
- Monospace inline text → **MonoText**
- Keyboard shortcut hint → **KeyboardHint**

### "I need to show people/users"
- Single user avatar → **Avatar**
- Stacked user avatars → **AvatarGroup**

### "I need to group buttons"
- Connected button strip (toggle group, segmented control) → **ButtonGroup** (horizontal or vertical)

### "I need filtering"
- Filter pill/chip → **FilterPill**
- Full filter bar with search → **FilterBar**

## Composition Patterns

### Standard page layout
```
AppShell → Sidebar + TopBar + main content + optional DetailPanel
```

### Data page pattern
```
FilterBar (top)
  → DataTable (center, with built-in sorting + pagination)
  → optional DetailPanel (right slide, on row click)
```

### Form layout
```
FormField wraps any input (Input, Textarea, Select, RadioGroup, etc.)
  provides: label, required indicator, hint text, error message
  gap: 6px between label and input, 4px to hint/error
```

### KPI dashboard
```
Row of StatCard components (each with optional Sparkline and trend)
Below: charts (AreaChart, LineChart, BarChart)
```

### Detail/inspector pattern
```
DetailPanel (right slide) with Tabs for sections
  Each tab: Cards with data, CodeBlock for payloads,
  ProcessorTimeline for exchange flow
```

### Feedback flow
```
User action → Toast (success/error feedback)
Destructive action → AlertDialog (confirmation) → Toast (result)
```

### Tree navigation pattern
```
TreeView for hierarchical data (Application → Routes → Processors)
  onSelect navigates or opens DetailPanel
```

### Agent/instance health pattern
```
StatCard strip (top, recalculates per scope)
  → GroupCard grid (2-col for all, full-width for single app)
    Each GroupCard: header (app name + count) + meta (TPS, routes) + instance rows
    Instance rows: StatusDot + name + Badge + metrics
    Single instance: expanded with LineChart panels
  → EventFeed (bottom, filtered by scope)
URL-driven progressive filtering: /agents → /agents/:appId → /agents/:appId/:instanceId
```

## Component Index

| Component | Layer | When to use |
|-----------|-------|-------------|
| Accordion | composite | Multiple collapsible sections, single or multi-open mode |
| Alert | primitive | Page-level attention banner with variant colors |
| AlertDialog | composite | Confirmation dialog for destructive/important actions |
| AreaChart | composite | Time series visualization with filled area |
| Avatar | primitive | User representation with initials and color |
| AvatarGroup | composite | Stacked overlapping avatars with overflow count |
| Badge | primitive | Labeled status indicator with semantic colors |
| BarChart | composite | Categorical data comparison, optional stacking |
| Breadcrumb | composite | Navigation path showing current location |
| Button | primitive | Action trigger (primary, secondary, danger, ghost) |
| ButtonGroup | primitive | Groups buttons into a connected strip with shared borders (horizontal/vertical) |
| Card | primitive | Content container with optional accent border |
| Checkbox | primitive | Boolean input with label |
| CodeBlock | primitive | Syntax-highlighted code/JSON display |
| Collapsible | primitive | Single expand/collapse section |
| CommandPalette | composite | Full-screen search and command interface |
| DataTable | composite | Sortable, paginated data table with row actions. Use `flush` prop when embedded inside a container that provides its own border/radius |
| DateRangePicker | primitive | Date range selection with presets |
| DateTimePicker | primitive | Single date/time input |
| DetailPanel | composite | Slide-in side panel with tabs |
| Dropdown | composite | Action menu triggered by any element |
| EmptyState | primitive | Placeholder for empty content areas |
| EventFeed | composite | Chronological event log with severity |
| FilterBar | composite | Search + filter controls for data views |
| GroupCard | composite | Card with header, meta row, children, and optional footer/alert. Used for grouping instances by application. |
| FilterPill | primitive | Individual filter chip (active/inactive), supports forwardRef |
| FormField | primitive | Wrapper adding label, hint, error to any input |
| InfoCallout | primitive | Inline contextual note with variant colors |
| Input | primitive | Single-line text input with optional icon |
| KeyboardHint | primitive | Keyboard shortcut display |
| Label | primitive | Form label with optional required asterisk |
| LineChart | composite | Time series line visualization |
| MenuItem | composite | Sidebar navigation item with health/count |
| Modal | composite | Generic dialog overlay with backdrop |
| MonoText | primitive | Inline monospace text (xs, sm, md) |
| Pagination | primitive | Page navigation controls |
| Popover | composite | Click-triggered floating panel with arrow |
| ProcessorTimeline | composite | Pipeline exchange visualization |
| ProgressBar | primitive | Determinate/indeterminate progress indicator |
| RadioGroup | primitive | Single-select option group (use with RadioItem) |
| RadioItem | primitive | Individual radio option within RadioGroup |
| SectionHeader | primitive | Section title with optional action button |
| Select | primitive | Dropdown select input |
| ShortcutsBar | composite | Keyboard shortcuts reference bar |
| Skeleton | primitive | Loading placeholder (text, circular, rectangular) |
| Sparkline | primitive | Inline mini chart for trends |
| Spinner | primitive | Animated loading indicator |
| StatCard | primitive | KPI card with value, trend, optional sparkline |
| StatusDot | primitive | Colored dot for status indication |
| Tabs | composite | Tabbed content switcher with optional counts |
| Tag | primitive | Removable colored label |
| Textarea | primitive | Multi-line text input with resize control |
| Toast | composite | Temporary notification (via ToastProvider + useToast) |
| Toggle | primitive | On/off switch input |
| Tooltip | primitive | Hover-triggered text tooltip |
| TreeView | composite | Hierarchical tree with keyboard navigation |

### Layout Components

| Component | Purpose |
|-----------|---------|
| AppShell | Page shell: sidebar + topbar + main + optional detail panel |
| Sidebar | Hierarchical navigation with Applications/Agents trees, starring, search filter, bottom links. Props: `apps: SidebarApp[]` (hierarchical — apps contain routes and agents) |
| TopBar | Header bar with breadcrumb, environment, user info |

## Import Paths

### Within this repo (design system development)

```tsx
import { Button, Input, Badge } from './design-system/primitives'
import { DataTable, Modal, Toast } from './design-system/composites'
import type { Column, SearchResult, FeedEvent } from './design-system/composites'
import { AppShell } from './design-system/layout/AppShell'
import { ThemeProvider, useTheme } from './design-system/providers/ThemeProvider'
```

### From consuming apps (via npm package)

```tsx
import '@cameleer/design-system/style.css'  // once at app root
import { Button, Input, Modal, DataTable, AppShell, ThemeProvider } from '@cameleer/design-system'
import type { Column, DataTableProps, SearchResult } from '@cameleer/design-system'
```

See `CLAUDE.md` "Using This Design System in Other Apps" for full setup instructions.

## Styling Rules

- **CSS Modules only** — no inline styles except dynamic values (width, color from props)
- **Use existing tokens** from `tokens.css` — never hardcode hex colors
- **Theme support** — all colors via CSS custom properties, never hardcode light/dark
- **forwardRef** on all form controls (Input, Textarea, Select, Checkbox, Toggle, Label)
- **className prop** on every component for style overrides
- **Semantic color variants** — use `'success' | 'warning' | 'error'` pattern consistently