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)

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)

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