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**
- Destructive action needing typed confirmation → **ConfirmDialog**
- 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**
- Select multiple from a list → **MultiSelect**
- Edit text inline without a form → **InlineEdit**
- 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)
- Inline colored status value → **StatusText** (success, warning, error, running, muted — with optional bold)
- 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 (Gantt view) → **ProcessorTimeline**
- Processing pipeline (flow diagram) → **RouteFlow**
- Row of summary KPIs → **KpiStrip** (horizontal strip with colored borders, trends, sparklines)
- Scrollable log output → **LogViewer** (timestamped, severity-colored monospace entries)
- Searchable, selectable entity list → **EntityList** (search header, selection highlighting, pairs with SplitPane)

### "I need to organize content"
- Collapsible sections (standalone) → **Collapsible**
- Multiple collapsible sections (one/many open) → **Accordion**
- Tabbed content → **Tabs**
- Tab switching with pill/segment style → **SegmentedTabs**
- Side panel inspector → **DetailPanel**
- Master/detail split layout → **SplitPane** (list on left, detail on right, configurable ratio)
- Section with title + action → **SectionHeader**
- Empty content placeholder → **EmptyState**
- Grouped content box → **Card** (with optional accent and title)
- 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**
- Colored inline status text → **StatusText** (semantic color + optional bold, see also "I need to show status")

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

### "I need to group buttons or toggle selections"
- Multi-select toggle group with colored indicators → **ButtonGroup** (e.g., status filters)
- Tab switching with pill/segment style → **SegmentedTabs**

### "I need filtering"
- Multi-select status/category filter → **ButtonGroup** (toggle items on/off)
- Filter pill/chip → **FilterPill** (individual toggleable pills)
- Full filter bar with search → **FilterBar**
- Select multiple from a list → **MultiSelect**

## 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)
```

### Master/detail management pattern
```
SplitPane + EntityList for CRUD list/detail screens (users, groups, roles)
  EntityList provides: search header, add button, selectable list
  SplitPane provides: responsive two-column layout with empty state
```

### Detail/inspector pattern
```
DetailPanel (right slide) with Tabs for sections OR children for scrollable content
  Tabbed: use tabs prop for multiple panels
  Scrollable: use children for stacked sections (overview, errors, route flow, timeline)
  Each section: Cards with data, CodeBlock for payloads,
  ProcessorTimeline or RouteFlow 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 | Multi-select toggle group with optional colored dot indicators. Props: items (value, label, color?), value (Set), onChange |
| Card | primitive | Content container with optional accent border and title header |
| 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 |
| ConfirmDialog | composite | Type-to-confirm destructive action dialog built on Modal. Props: open, onClose, onConfirm, title, message, confirmText, confirmLabel, cancelLabel, variant, loading, className |
| 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 or children for scrollable content |
| Dropdown | composite | Action menu triggered by any element |
| EmptyState | primitive | Placeholder for empty content areas |
| EntityList | composite | Searchable, selectable entity list with add button. Pair with SplitPane for CRUD management screens |
| 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 |
| InlineEdit | primitive | Click-to-edit text field. Enter saves, Escape/blur cancels. Props: value, onSave, placeholder, disabled, className |
| Input | primitive | Single-line text input with optional icon |
| KeyboardHint | primitive | Keyboard shortcut display |
| KpiStrip | composite | Horizontal row of KPI cards with colored left border, trend, subtitle, optional sparkline |
| Label | primitive | Form label with optional required asterisk |
| LineChart | composite | Time series line visualization |
| LogViewer | composite | Scrollable log output with timestamped, severity-colored monospace entries |
| MenuItem | composite | Sidebar navigation item with health/count |
| Modal | composite | Generic dialog overlay with backdrop |
| MultiSelect | composite | Dropdown with searchable checkbox list and Apply action. Props: options, value, onChange, placeholder, searchable, disabled, className |
| MonoText | primitive | Inline monospace text (xs, sm, md) |
| Pagination | primitive | Page navigation controls |
| Popover | composite | Click-triggered floating panel with arrow |
| ProcessorTimeline | composite | Gantt-style pipeline visualization with selectable rows and optional action menus. Props: processors, totalMs, onProcessorClick?, selectedIndex?, actions?, getActions?. Use `actions` for static menus or `getActions` for per-processor dynamic actions. |
| RouteFlow | composite | Vertical processor node flow diagram with status coloring, connectors, click support, and optional action menus. Props: nodes, onNodeClick?, selectedIndex?, actions?, getActions?. Same action pattern as ProcessorTimeline. |
| 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 |
| SegmentedTabs | composite | Pill-style segmented tab bar with sliding animated indicator. Same API as Tabs but with elevated active state. Props: tabs, active, onChange, trailing, trailingValue, className |
| 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 |
| SplitPane | composite | Two-column master/detail layout with configurable ratio and empty state |
| Spinner | primitive | Animated loading indicator |
| StatCard | primitive | KPI card with value, trend, optional sparkline |
| StatusDot | primitive | Colored dot for status indication |
| StatusText | primitive | Inline colored status span (success, warning, error, running, muted) with optional bold |
| 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/Routes trees, starring, search filter, bottom links. Props: `apps: SidebarApp[]` (hierarchical — apps contain routes and agents) |
| TopBar | Header bar with breadcrumb, search trigger, ButtonGroup status filters, time range selector, theme toggle, environment badge, user avatar |

## 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