From 9e57c543ca806f8c8ca7f9824bbaa087cae3036e Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Wed, 18 Mar 2026 15:19:16 +0100 Subject: [PATCH] docs: add COMPONENT_GUIDE.md for Claude reference Co-Authored-By: Claude Opus 4.6 (1M context) --- COMPONENT_GUIDE.md | 218 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 COMPONENT_GUIDE.md diff --git a/COMPONENT_GUIDE.md b/COMPONENT_GUIDE.md new file mode 100644 index 0000000..4424338 --- /dev/null +++ b/COMPONENT_GUIDE.md @@ -0,0 +1,218 @@ +# 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) +- Breadcrumb trail → **Breadcrumb** +- Paginated data → **Pagination** (standalone) or **DataTable** (built-in pagination) +- Hierarchical tree navigation → **TreeView** + +### "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) + +### "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 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 execution 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 +``` + +## 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) | +| 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 | +| 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 | +| FilterPill | primitive | Individual filter chip (active/inactive) | +| 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 execution 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 | App navigation with apps, routes, agents sections | +| TopBar | Header bar with breadcrumb, environment, user info | + +## Import Paths + +```tsx +// Primitives +import { Button, Input, Badge, ... } from './design-system/primitives' + +// Composites +import { DataTable, Modal, Toast, ... } from './design-system/composites' +import type { Column, SearchResult, FeedEvent, ... } from './design-system/composites' + +// Layout +import { AppShell } from './design-system/layout/AppShell' +import { Sidebar } from './design-system/layout/Sidebar' +import { TopBar } from './design-system/layout/TopBar' + +// Theme +import { ThemeProvider, useTheme } from './design-system/providers/ThemeProvider' +``` + +## 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