From 2e78655179494651af3c55fc92d1fa610d466e46 Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Wed, 18 Mar 2026 15:22:48 +0100 Subject: [PATCH] docs: update design spec with 14 new components Co-Authored-By: Claude Opus 4.6 (1M context) --- .../specs/2026-03-18-design-system-design.md | 115 +++++++++++++++++- 1 file changed, 114 insertions(+), 1 deletion(-) diff --git a/docs/superpowers/specs/2026-03-18-design-system-design.md b/docs/superpowers/specs/2026-03-18-design-system-design.md index ada892c..b82872a 100644 --- a/docs/superpowers/specs/2026-03-18-design-system-design.md +++ b/docs/superpowers/specs/2026-03-18-design-system-design.md @@ -126,6 +126,7 @@ src/ │ ├── utils/ │ │ └── hashColor.ts # Name → HSL deterministic color │ ├── primitives/ +│ │ ├── Alert/ │ │ ├── Avatar/ │ │ │ ├── Avatar.tsx │ │ │ └── Avatar.module.css @@ -139,22 +140,32 @@ src/ │ │ ├── DateRangePicker/ │ │ ├── EmptyState/ │ │ ├── FilterPill/ +│ │ ├── FormField/ │ │ ├── InfoCallout/ │ │ ├── Input/ │ │ ├── KeyboardHint/ +│ │ ├── Label/ │ │ ├── MonoText/ +│ │ ├── Pagination/ +│ │ ├── ProgressBar/ +│ │ ├── Radio/ │ │ ├── Select/ │ │ ├── SectionHeader/ +│ │ ├── Skeleton/ │ │ ├── Sparkline/ │ │ ├── Spinner/ │ │ ├── StatCard/ │ │ ├── StatusDot/ │ │ ├── Tag/ +│ │ ├── Textarea/ │ │ ├── Toggle/ │ │ ├── Tooltip/ │ │ └── index.ts # Barrel export │ ├── composites/ +│ │ ├── Accordion/ +│ │ ├── AlertDialog/ │ │ ├── AreaChart/ +│ │ ├── AvatarGroup/ │ │ ├── BarChart/ │ │ ├── Breadcrumb/ │ │ ├── CommandPalette/ @@ -166,9 +177,12 @@ src/ │ │ ├── LineChart/ │ │ ├── MenuItem/ │ │ ├── Modal/ +│ │ ├── Popover/ │ │ ├── ProcessorTimeline/ │ │ ├── ShortcutsBar/ │ │ ├── Tabs/ +│ │ ├── Toast/ +│ │ ├── TreeView/ │ │ └── index.ts │ ├── layout/ │ │ ├── AppShell/ @@ -182,7 +196,8 @@ src/ │ ├── Metrics/ │ ├── RouteDetail/ │ ├── ExchangeDetail/ -│ └── AgentHealth/ +│ ├── AgentHealth/ +│ └── Inventory/ # Component showcase at /inventory ├── mocks/ # Static TypeScript mock data │ ├── executions.ts │ ├── routes.ts @@ -351,6 +366,57 @@ All CSS custom properties for both themes. Light values sourced from `mock-v2-li - Color inherits from parent or explicit prop - Props: `data: number[]`, `color?: string`, `width?: number`, `height?: number`, `strokeWidth?: number` +#### Alert +- Inline page-level attention banner with variant colors +- Left accent border (4px), variant background color, default icon per variant +- Variants: `info`, `success`, `warning`, `error` +- ARIA: `role="alert"` for error/warning, `role="status"` for info/success +- Props: `variant?: 'info' | 'success' | 'warning' | 'error'`, `title?: string`, `children`, `dismissible?: boolean`, `onDismiss?`, `icon?: ReactNode` + +#### FormField +- Wrapper component: Label + children slot + hint text + error text +- Error replaces hint when both present; adds `.error` class to wrapper +- Props: `label?: string`, `htmlFor?: string`, `required?: boolean`, `error?: string`, `hint?: string`, `children: ReactNode` + +#### Label +- Form label with optional required asterisk (red `*`) +- Font: `--font-body`, 12px, `--text-primary`, `font-weight: 500` +- Uses `forwardRef` +- Props: extends `LabelHTMLAttributes` + `required?: boolean` + +#### Pagination +- Page navigation: `< 1 ... 4 [5] 6 ... 20 >` +- Always shows first, last, and siblingCount pages around current +- Active page: `--amber` background, white text +- Props: `page: number`, `totalPages: number`, `onPageChange`, `siblingCount?: number` + +#### ProgressBar +- Track with animated fill bar +- Determinate (value 0-100) or indeterminate (shimmer animation) +- Variants: primary, success, warning, error, running +- Sizes: sm (4px height), md (8px height) +- ARIA: `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax` +- Props: `value?: number`, `variant?`, `size?: 'sm' | 'md'`, `indeterminate?: boolean`, `label?: string` + +#### Radio (RadioGroup + RadioItem) +- Single-select option group using React Context +- Visual pattern matches Checkbox: hidden native input, custom circle with amber fill +- Circle: 15px, `border-radius: 50%`, checked inner dot 7px +- RadioGroup: `name`, `value`, `onChange`, `orientation?: 'vertical' | 'horizontal'` +- RadioItem: `value`, `label: ReactNode`, `disabled?: boolean` + +#### Skeleton +- Loading placeholder with shimmer animation +- Variants: `text` (12px bars), `circular` (50% radius, 40x40 default), `rectangular` (full width, 80px default) +- Multi-line text: `lines` prop, last line at 70% width +- Props: `variant?`, `width?`, `height?`, `lines?: number` + +#### Textarea +- Multi-line text input matching Input visual styling +- Focus ring: amber border + amber-bg box-shadow +- Uses `forwardRef` +- Props: extends `TextareaHTMLAttributes` + `resize?: 'vertical' | 'horizontal' | 'none' | 'both'` + ### 5.3 Composites #### Breadcrumb @@ -469,6 +535,52 @@ All CSS custom properties for both themes. Light values sourced from `mock-v2-li - Each hint: `KeyboardHint` + description text - Props: `shortcuts: { keys: string; label: string }[]` +#### Accordion +- Multiple collapsible sections managed as a group +- Uses Collapsible internally in controlled mode +- Single mode (default): opening one closes others. Multiple mode: independent. +- Container: `--border-subtle` border, `--radius-md`, sections separated by dividers +- Props: `items: AccordionItem[]`, `multiple?: boolean` +- `AccordionItem`: `{ id: string, title: ReactNode, content: ReactNode, defaultOpen?: boolean }` + +#### AlertDialog +- Confirmation dialog for destructive/important actions, built on Modal +- Fixed layout: icon area + title + description + button row +- Variant-colored icon circle (danger=✕, warning=⚠, info=ℹ) +- Auto-focuses Cancel button (safe default for destructive dialogs) +- Props: `open`, `onClose`, `onConfirm`, `title`, `description`, `variant?: 'danger' | 'warning' | 'info'`, `loading?` + +#### AvatarGroup +- Renders overlapping Avatar components with overflow count +- Overlap: negative margin-left per size. Ring: 2px solid `--bg-surface` +- Overflow circle: `--bg-inset` background, `--font-mono` 10px, `+N` text +- Props: `names: string[]`, `max?: number`, `size?: 'sm' | 'md' | 'lg'` + +#### Popover +- Click-triggered floating panel with CSS triangle arrow +- Positions: top, bottom, left, right. Alignment: start, center, end +- Closes on outside click or Esc. Uses `createPortal`. +- Animation: opacity + scale, 150ms ease-out +- Props: `trigger: ReactNode`, `content: ReactNode`, `position?`, `align?` + +#### Toast (ToastProvider + useToast) +- App-level toast notification system via React Context +- `ToastProvider` wraps the app; `useToast()` returns `{ toast, dismiss }` +- `toast({ title, description?, variant?, duration? })` → returns id +- Container: fixed bottom-right, z-index 1100, max 5 visible +- Each toast: left accent border, variant icon, auto-dismiss (default 5000ms) +- Slide-in animation from right, fade-out on dismiss + +#### TreeView +- Hierarchical tree with recursive rendering and keyboard navigation +- Controlled or uncontrolled expand state +- Selected node: amber background + left border +- Keyboard: arrows (navigate), left/right (collapse/expand), Enter (select), Home/End +- Connector lines for visual hierarchy +- ARIA: `role="tree"`, `role="treeitem"`, `aria-expanded` +- Props: `nodes: TreeNode[]`, `onSelect?`, `selectedId?`, `expandedIds?`, `onToggle?` +- `TreeNode`: `{ id, label, icon?, children?, meta? }` + ### 5.4 Layout #### AppShell @@ -509,6 +621,7 @@ Pages compose design system components with mock data. Each page is a route. | `/routes/:id` | RouteDetail | Per-route stats from `mock-v3-route-detail` | | `/exchanges/:id` | ExchangeDetail | Message inspector from `mock-v3-exchange-detail` | | `/agents` | AgentHealth | Agent monitoring from `mock-v3-agent-health` | +| `/inventory` | Inventory | Component showcase with live interactive demos | Pages are built after the design system layer is complete.