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)

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