@goliapkg/gds 0.1.0

package/llms-full.txt

@@ -0,0 +1,770 @@
+# @goliapkg/gds — Full AI Reference
+
+> GOLIA Design System — 370+ React components across 8 architectural layers.
+> Built by GOLIA for all company React web applications.
+> This file contains everything an AI needs to learn and use GDS correctly.
+
+---
+
+## Installation
+
+```bash
+bun add @goliapkg/gds
+```
+
+```tsx
+import { Button, Card } from '@goliapkg/gds'
+import '@goliapkg/gds/tokens.css'
+```
+
+---
+
+## Architecture: 8-Layer System
+
+Dependencies flow upward only. Higher layers import from lower layers, never reverse.
+
+```
+L7 Patterns    ← page-level layouts (Dashboard, Admin, Settings...)
+L6 Charts      ← data visualization (Recharts-based)
+L5 Organisms   ← complex features (DataTable, Calendar, Kanban...)
+L4 Molecules   ← multi-part components (Card, Dialog, Tabs...)
+L3 Atoms       ← simple composed elements (Avatar, Checkbox, Tooltip...)
+L2 Primitives  ← stateless visual blocks (Button, Input, Badge...)
+L1 Systems     ← theme engine (Jotai atoms, hooks)
+L0 Tokens      ← CSS variables, color math, sizing, motion, glass
+Utils          ← anti-corruption layer (cx, a11y, types, dom, glass, motion)
+```
+
+### Layer Dependency Constraints (enforced by ESLint)
+
+| Layer | Allowed External Dependencies |
+|-------|-------------------------------|
+| L0 Tokens | tailwindcss only |
+| L1 Systems | react, jotai |
+| L2 Primitives | react, clsx, tailwind-merge (via cx wrapper) |
+| L3 Atoms | + class-variance-authority, lucide-react |
+| L4 Molecules | same as L3 |
+| L5 Organisms | + react-dom |
+| L6 Charts | recharts (no cva) |
+| L7 Patterns | react, clsx, tailwind-merge only |
+
+---
+
+## Canonical Component Pattern
+
+Every GDS component follows the same structure. Learn this once, apply everywhere.
+
+```tsx
+import { cva } from 'class-variance-authority'
+import { forwardRef } from 'react'
+
+import { focusCls } from '../utils/a11y'
+import { cx } from '../utils/cx'
+import { glassClass } from '../utils/glass'
+import { motionClass } from '../utils/motion'
+import type { VariantProps } from '../utils/types'
+
+// 1. CVA variants — all visual variants defined here
+const buttonVariants = cva(
+  'inline-flex select-none items-center justify-center font-medium transition-colors ' + focusCls,
+  {
+    variants: {
+      variant: {
+        primary: 'bg-accent text-accent-fg hover:bg-accent-hover',
+        secondary: 'border border-border bg-transparent text-fg hover:bg-bg-tertiary',
+        ghost: 'bg-transparent text-fg-muted hover:bg-bg-tertiary hover:text-fg',
+        danger: 'bg-danger text-accent-fg hover:bg-danger/90',
+      },
+      size: {
+        sm: 'gds-h-sm gds-gap-xs gds-radius-button gds-pad-x-sm gds-text-label',
+        default: 'gds-h gds-gap-sm gds-radius-button gds-pad-x gds-text-body',
+        lg: 'gds-h-lg gds-gap gds-radius-button gds-pad-x-lg gds-text-body',
+      },
+    },
+    defaultVariants: { variant: 'primary', size: 'default' },
+  },
+)
+
+// 2. Props type — extends HTML attributes + CVA variants + custom props
+type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
+  VariantProps<typeof buttonVariants> & {
+    fullWidth?: boolean
+    glass?: boolean
+    icon?: ReactNode
+    iconRight?: ReactNode
+    loading?: boolean
+    motion?: string
+  }
+
+// 3. forwardRef component with data-* attributes for AI parsing
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button({ children, className, glass, motion: m, size, variant, ...props }, ref) {
+    return (
+      <button
+        className={cx(
+          buttonVariants({ size, variant }),
+          glassClass(glass),
+          motionClass(m),
+          className,
+        )}
+        data-component="button"
+        data-variant={variant ?? 'primary'}
+        ref={ref}
+        {...props}
+      >
+        {children}
+      </button>
+    )
+  },
+)
+
+// 4. Export variants object + props type for consumer introspection
+export { buttonVariants }
+export type { ButtonProps }
+```
+
+### Key Rules
+
+- `type` only — never `interface` or `enum`
+- `cx()` for class merging — never import clsx/tailwind-merge directly
+- `focusCls` on all interactive elements
+- `glassClass(glass)` for glass material support
+- `motionClass(motion)` for animation support
+- `data-component` and `data-variant` attributes on root element
+- Named exports only — no default exports
+- Semantic tokens only — never raw Tailwind colors (no `bg-blue-500`)
+- No ternary — use `if/else` or `&&` for JSX conditional rendering
+- `??` over `||` — always nullish coalescing
+
+---
+
+## Utility Layer (Anti-Corruption Boundary)
+
+### cx() — class merging
+```tsx
+import { cx } from '@goliapkg/gds'
+// merges classes with tailwind-merge conflict resolution
+cx('p-4 text-sm', condition && 'bg-accent', className)
+```
+
+### focusCls — focus ring
+```tsx
+import { focusCls } from '@goliapkg/gds'
+// standard focus-visible ring for all interactive elements
+// value: 'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-bg outline-none'
+```
+
+### srOnly — screen reader only
+```tsx
+import { srOnly } from '@goliapkg/gds'
+// visually hidden but accessible to screen readers
+```
+
+### glassClass() — glass material
+```tsx
+import { glassClass } from '../utils/glass'
+// returns backdrop-blur + semi-transparent bg classes when glass=true
+glassClass(true)  // → 'backdrop-blur-md bg-bg/80'
+glassClass(false) // → ''
+```
+
+### motionClass() — animation
+```tsx
+import { motionClass } from '../utils/motion'
+// returns animation classes for the given motion preset
+motionClass('fade')   // → fade animation classes
+motionClass('scale')  // → scale animation classes
+motionClass('slide')  // → slide animation classes
+motionClass('spring') // → spring physics animation
+```
+
+### DOM utilities
+```tsx
+import { clamp, isActivationKey, mergeRefs, uid } from '@goliapkg/gds'
+clamp(value, min, max)     // number clamping
+isActivationKey(event)      // Enter or Space key check
+mergeRefs(ref1, ref2)       // combine multiple refs
+uid()                       // unique ID generation
+```
+
+### Type utilities
+```tsx
+import type { VariantProps, AsProps, MergeProps, DataRecord } from '@goliapkg/gds'
+// VariantProps<typeof xxxVariants> — extract variant prop types from CVA
+// AsProps — polymorphic "as" prop support
+// MergeProps — merge two prop types with override
+// DataRecord — generic data row type for tables
+```
+
+---
+
+## Contextual Depth System
+
+Container components add `gds-ctx` CSS class. Each nesting level auto-reduces spacing, radius, shadow, and text size. Zero configuration — just compose.
+
+| Depth | gap | padding | radius | shadow | text | heading |
+|-------|-----|---------|--------|--------|------|---------|
+| root | 24px | 20px | 12px | md | 13px | 16px |
+| 0 (.gds-ctx) | 16px | 16px | 10px | sm | 12px | 14px |
+| 1 (nested) | 12px | 12px | 8px | none | 11px | 13px |
+| 2 | 8px | 8px | 6px | none | 10px | 12px |
+| 3+ | 6px | 6px | 4px | none | 10px | 11px |
+
+### Depth-Aware CSS Utilities
+
+Use these instead of fixed Tailwind classes in container components:
+
+- `gds-pad`, `gds-pad-x`, `gds-pad-y` — depth-aware padding
+- `gds-gap`, `gds-gap-sm`, `gds-gap-xs` — depth-aware gap
+- `gds-radius`, `gds-radius-button` — depth-aware border-radius
+- `gds-shadow` — depth-aware box-shadow
+- `gds-text-body`, `gds-text-label` — depth-aware font size
+- `gds-heading` — depth-aware heading size
+- `gds-h`, `gds-h-sm`, `gds-h-lg` — depth-aware component height
+- `gds-sq` — depth-aware square size (for avatars, icons)
+
+### Container vs Leaf Components
+
+- **Containers** (Card, Dialog, Panel, Sheet, Accordion) → add `gds-ctx` to root className
+- **Leaves** (Button, Input, Badge) → do NOT add `gds-ctx`, just consume current depth values
+
+---
+
+## Theme System
+
+5-axis dimensional theming via Jotai atoms:
+
+```tsx
+import {
+  useTheme,
+  useSetThemeMode,
+  useSetThemeDensity,
+  useSetThemeElevation,
+  useSetThemeGlass,
+  useSetThemeMotion,
+  useSetThemeShape,
+  useSetThemeColors,
+  useResetTheme,
+  configureTheme,
+} from '@goliapkg/gds'
+
+// read current theme
+const theme = useTheme()
+// theme.mode: 'light' | 'dark' | 'system'
+// theme.density: 'compact' | 'default' | 'comfortable'
+// theme.elevation: 'flat' | 'default' | 'raised'
+// theme.glass: 'off' | 'subtle' | 'default' | 'heavy'
+// theme.motion: 'none' | 'reduced' | 'default' | 'playful'
+// theme.shape: 'sharp' | 'default' | 'round' | 'pill'
+
+// set individual axes
+const setMode = useSetThemeMode()
+setMode('dark')
+
+const setDensity = useSetThemeDensity()
+setDensity('compact')
+
+// reset to defaults
+const reset = useResetTheme()
+reset()
+
+// configure programmatically (outside React)
+configureTheme({ mode: 'dark', density: 'compact' })
+```
+
+---
+
+## Semantic Color Tokens
+
+Always use these — never raw Tailwind colors:
+
+### Backgrounds
+- `bg-bg` — primary background
+- `bg-bg-secondary` — secondary background
+- `bg-bg-tertiary` — tertiary/hover background
+
+### Foreground / Text
+- `text-fg` — primary text
+- `text-fg-muted` — secondary/muted text
+- `text-accent-fg` — text on accent background
+
+### Accent
+- `bg-accent` — primary accent
+- `bg-accent-hover` — accent hover state
+- `text-accent` — accent-colored text
+
+### Semantic
+- `bg-success` / `text-success` — success state
+- `bg-warning` / `text-warning` — warning state
+- `bg-danger` / `text-danger` — danger/error state
+- `bg-info` / `text-info` — informational state
+
+### Borders
+- `border-border` — default border
+- `border-border-muted` — subtle border
+
+### Palette (for data visualization / avatar colors)
+- `bg-palette-0` through `bg-palette-9` — 10 distinct colors
+
+---
+
+## Complete Component Catalog
+
+### L2 Primitives (~30 components)
+
+Stateless visual blocks. No internal state, no useEffect.
+
+| Component | Props Highlights | Usage |
+|-----------|-----------------|-------|
+| `Button` | variant: primary/secondary/ghost/danger, size: sm/default/lg, glass, motion, loading, icon, iconRight, fullWidth | `<Button variant="primary">Click</Button>` |
+| `IconButton` | variant, size, glass, icon, label (aria) | `<IconButton icon={<X />} label="Close" />` |
+| `Input` | variant, size, glass, invalid | `<Input placeholder="Email" />` |
+| `NumberInput` | min, max, step, value, onChange | `<NumberInput min={0} max={100} />` |
+| `Textarea` | resize, rows, invalid | `<Textarea rows={4} />` |
+| `Badge` | variant: default/success/warning/danger/info, size | `<Badge variant="success">Active</Badge>` |
+| `BadgeDot` | color, pulse | `<BadgeDot color="success" />` |
+| `Kbd` | — | `<Kbd>⌘K</Kbd>` |
+| `Label` | htmlFor, required | `<Label htmlFor="email">Email</Label>` |
+| `Progress` | value (0-100), variant, size | `<Progress value={75} />` |
+| `Spinner` | size | `<Spinner size="sm" />` |
+| `Skeleton` | width, height, rounded | `<Skeleton className="h-8 w-32" />` |
+| `Separator` | orientation: horizontal/vertical | `<Separator />` |
+| `Divider` | label | `<Divider label="or" />` |
+| `Dot` | color, size | `<Dot color="success" />` |
+| `Anchor` | href, external | `<Anchor href="/docs">Docs</Anchor>` |
+| `ScrollArea` | orientation, maxHeight | `<ScrollArea maxHeight={400}>...</ScrollArea>` |
+| `Truncate` | lines | `<Truncate lines={2}>Long text...</Truncate>` |
+| `Highlight` | query | `<Highlight query="search">Text with search term</Highlight>` |
+| `AspectRatio` | ratio | `<AspectRatio ratio={16/9}>...</AspectRatio>` |
+| `VisuallyHidden` | — | `<VisuallyHidden>Screen reader text</VisuallyHidden>` |
+| `SkipNav` | href | `<SkipNav href="#main" />` |
+| `FocusRing` | — | Focus indicator wrapper |
+| `ScreenOverlay` | visible, onClick | Modal backdrop |
+| `GlowEffect` | color, intensity | Glow visual effect |
+| `GradientBorder` | from, to, via | Gradient border wrapper |
+
+### L3 Atoms (~60 components)
+
+Simple composed elements. May use useState.
+
+| Component | Props Highlights | Usage |
+|-----------|-----------------|-------|
+| `Avatar` | src, name, size: xs/sm/default/lg, status: online/away/busy/offline, glass | `<Avatar name="John" size="lg" />` |
+| `AvatarGroup` | max | `<AvatarGroup max={3}>...</AvatarGroup>` |
+| `Checkbox` | checked, onChange, indeterminate, label | `<Checkbox label="Agree" />` |
+| `CheckboxGroup` | value, onChange, options | Group of checkboxes |
+| `RadioGroup` | value, onChange, options | `<RadioGroup options={[...]} />` |
+| `Switch` | checked, onChange, label | `<Switch label="Dark mode" />` |
+| `SwitchGroup` | value, onChange, options | Group of switches |
+| `Tooltip` | content, side, delay | `<Tooltip content="Help text"><Button>?</Button></Tooltip>` |
+| `Popover` | content, trigger, side | `<Popover content={...}>Trigger</Popover>` |
+| `Chip` | variant, onRemove, icon | `<Chip onRemove={fn}>Tag</Chip>` |
+| `Rating` | value, onChange, max | `<Rating value={4} max={5} />` |
+| `StarRating` | value, onChange, max | Star-based rating |
+| `SegmentedControl` | value, onChange, options | `<SegmentedControl options={[...]} />` |
+| `ToggleGroup` | value, onChange, options, multiple | Toggle button group |
+| `TagInput` | value, onChange, placeholder | `<TagInput value={tags} onChange={setTags} />` |
+| `StatusBadge` | status, label | `<StatusBadge status="active" />` |
+| `StatusDot` | status, pulse | Status indicator dot |
+| `CountBadge` | count, max | `<CountBadge count={99} max={99} />` |
+| `OnlineIndicator` | online | Online/offline dot |
+| `LiveDot` | — | Animated live indicator |
+| `PulseIndicator` | color | Pulsing dot |
+| `QRCode` | value, size | `<QRCode value="https://..." />` |
+| `Barcode` | value, format | `<Barcode value="123456" />` |
+| `Price` | amount, currency | `<Price amount={29.99} currency="USD" />` |
+| `Percentage` | value | `<Percentage value={0.85} />` |
+| `TimeSince` | date | `<TimeSince date={timestamp} />` |
+| `TrendArrow` | direction: up/down, value | Trend indicator |
+| `CountUp` | end, duration | Animated counter |
+| `Countdown` | target | Countdown timer |
+| `Marquee` | speed, direction | `<Marquee>Scrolling text</Marquee>` |
+| `Typewriter` | text, speed | Typewriter animation |
+| `CopyButton` | text | `<CopyButton text="copy this" />` |
+| `ScrollToTop` | threshold | Scroll-to-top button |
+| `ThemeToggle` | — | Dark/light mode toggle |
+| `KeyboardShortcut` | keys | `<KeyboardShortcut keys={['⌘', 'K']} />` |
+| `ProgressCircle` | value, size | Circular progress |
+| `Meter` | value, min, max, thresholds | `<Meter value={75} />` |
+| `RangeSlider` | min, max, value, onChange | Range input |
+| `Editable` | value, onChange | Click-to-edit text |
+| `InfoTip` | content | Info icon with tooltip |
+| `KeyValue` | label, value | Key-value display pair |
+| `MagneticButton` | strength | Button with magnetic hover effect |
+| `RippleEffect` | — | Click ripple effect wrapper |
+| `CursorFollow` | — | Element that follows cursor |
+| `Sparkle` | — | Sparkle animation effect |
+| `Blinking` | interval | Blinking wrapper |
+| `TextEffect` | effect | Text animation effect |
+| `DiffIndicator` | oldValue, newValue | Value change indicator |
+| `HeatCell` | value, min, max | Heat-colored cell |
+| `Ribbon` | label, position | Corner ribbon |
+| `SplitButton` | options, onSelect | Button with dropdown |
+| `QuickAction` | icon, label, onClick | Quick action button |
+| `OverflowMenu` | items | "..." overflow menu |
+| `ResizeHandle` | direction | Draggable resize handle |
+| `SkeletonGroup` | count, layout | Multiple skeleton placeholders |
+| `TruncatedList` | max, items | List with "show more" |
+| `LoadingDots` | — | Animated loading dots |
+| `VerifiedBadge` | — | Verified checkmark badge |
+| `TextBadge` | — | Text-based badge |
+| `GlowDot` | color | Glowing dot |
+
+### L4 Molecules (~70 components)
+
+Multi-part compound components with internal state and interaction logic.
+
+| Component | Props Highlights | Usage |
+|-----------|-----------------|-------|
+| `Card` | glass, padding: none/sm/default/lg, loading | `<Card glass><CardHeader title="..." /><CardContent>...</CardContent></Card>` |
+| `CardHeader` | title, subtitle, action | Card header composition slot |
+| `CardContent` | — | Card body composition slot |
+| `CardFooter` | — | Card footer composition slot |
+| `Dialog` | open, onClose, title, size | `<Dialog open={open} onClose={close} title="Confirm">...</Dialog>` |
+| `Sheet` | open, onClose, side: left/right/top/bottom | `<Sheet open={open} side="right">...</Sheet>` |
+| `Drawer` | open, onClose, side | Drawer overlay |
+| `Tabs` | value, onChange, items | `<Tabs items={[{ label: 'Tab 1', content: ... }]} />` |
+| `TabGroup` | — | Uncontrolled tab group |
+| `Select` | value, onChange, options, placeholder | `<Select options={[...]} placeholder="Choose..." />` |
+| `MultiSelect` | value, onChange, options | Multi-value select |
+| `Combobox` | value, onChange, options, searchable | Searchable select |
+| `Dropdown` | trigger, items | `<Dropdown trigger={<Button>Menu</Button>} items={[...]} />` |
+| `ContextMenu` | items | Right-click context menu |
+| `ActionMenu` | items | Action dropdown |
+| `CommandMenu` | commands, open, onClose | Command palette (⌘K style) |
+| `Accordion` | items, multiple | `<Accordion items={[{ title: '...', content: ... }]} />` |
+| `Collapsible` | open, title | Collapsible section |
+| `Alert` | variant: info/success/warning/danger, title | `<Alert variant="warning" title="Warning">Message</Alert>` |
+| `Toast` | variant, title, message, action | Toast notification |
+| `Notification` | title, message, timestamp, read | Notification item |
+| `Breadcrumb` | items | `<Breadcrumb items={[{ label: 'Home', href: '/' }]} />` |
+| `Stepper` | steps, current | `<Stepper steps={[...]} current={1} />` |
+| `ProgressSteps` | steps, current | Step progress indicator |
+| `Panel` | title, collapsible, glass | Content panel |
+| `CodeBlock` | code, language, showLineNumbers | `<CodeBlock code="..." language="tsx" />` |
+| `KvTable` | data | `<KvTable data={{ Name: 'John', Age: 30 }} />` |
+| `FilterBar` | filters, onChange | Filter controls bar |
+| `SearchInput` | value, onChange, loading | Search with icon |
+| `InputGroup` | — | Grouped input layout |
+| `InputWithButton` | buttonLabel, onSubmit | Input + action button |
+| `PasswordInput` | show/hide toggle built-in | Password with visibility |
+| `OtpInput` | length, value, onChange | OTP code input |
+| `PhoneInput` | value, onChange | Phone number input |
+| `CurrencyInput` | value, onChange, currency | Currency input |
+| `DateRangeInput` | start, end, onChange | Date range picker |
+| `ColorPicker` | value, onChange | Color selection |
+| `SliderField` | label, min, max, value | Labeled slider |
+| `FileUpload` | accept, multiple, onUpload | File upload zone |
+| `InlineEdit` | value, onSave | Inline editing |
+| `FieldWrapper` | label, error, hint, required | Form field wrapper |
+| `FormActions` | onSubmit, onCancel, loading | Form action buttons |
+| `RadioCard` | options, value, onChange | Card-style radio group |
+| `ListItem` | title, description, icon, action | List item |
+| `HoverCard` | trigger, content | Hover-activated card |
+| `LoadingOverlay` | visible | Loading overlay |
+| `MetricTile` | label, value, trend | Metric display tile |
+| `MetricRow` | items | Row of metrics |
+| `QuickStat` | label, value, icon | Quick stat display |
+| `UserInfo` | name, avatar, role | User info display |
+| `UserMenu` | user, menuItems | User dropdown menu |
+| `NavItem` | href, icon, label, active | Navigation item |
+| `PageNav` | items | Page navigation |
+| `StatusBarComponent` | items | Status bar |
+| `ActionCard` | title, description, action | Card with action |
+| `CertBadge` | label, variant | Certificate badge |
+| `EnvironmentBadge` | env: dev/staging/prod | Environment indicator |
+| `VersionBadge` | version | Version display |
+| `CurrencyDisplay` | amount, currency | Formatted currency |
+| `DateDisplay` | date, format | Formatted date |
+| `CategoryTag` | label, color | Category tag |
+| `ToolbarGroup` | items | Toolbar button group |
+| `EmojiPicker` | onSelect | Emoji selection |
+| `CallOut` | variant, title | Callout box |
+| `CopyField` | value | Copyable field |
+| `SortableTable` | columns, data | Simple sortable table |
+| `TaskItem` | title, status, priority | Task list item |
+| `TimePicker` | value, onChange | Time selection |
+| `ToggleField` | label, checked, onChange | Toggle with label |
+| `Wizard` | steps, current | Multi-step wizard |
+
+### L5 Organisms (~60 components)
+
+Complex features composed from multiple lower-layer components.
+
+| Component | Props Highlights | Usage |
+|-----------|-----------------|-------|
+| `DataTable` | columns, data, sortable, filterable, pagination, selectable | `<DataTable columns={[...]} data={rows} />` |
+| `Calendar` | value, onChange, events | `<Calendar events={[...]} />` |
+| `DatePicker` | value, onChange, minDate, maxDate | `<DatePicker value={date} onChange={setDate} />` |
+| `Kanban` | columns, onMove | Kanban board |
+| `TaskBoard` | tasks, columns | Task management board |
+| `Tree` | data, onSelect, expandable | `<Tree data={treeData} />` |
+| `FileBrowser` | files, onNavigate, onSelect | File system browser |
+| `Timeline` | items | `<Timeline items={[...]} />` |
+| `CommandPalette` | commands, open, onClose | Global command palette |
+| `DiffViewer` | oldValue, newValue, language | Side-by-side diff |
+| `JsonViewer` | data, expandLevel | `<JsonViewer data={obj} />` |
+| `MarkdownPreview` | content | `<MarkdownPreview content="# Hello" />` |
+| `MarkdownEditor` | value, onChange | Markdown editor |
+| `CodeBlock` | code, language | Syntax-highlighted code |
+| `FormBuilder` | schema, onSubmit | Dynamic form from schema |
+| `CommentThread` | comments, onReply | Comment thread |
+| `DataList` | items, renderItem | Generic data list |
+| `VirtualList` | items, itemHeight, renderItem | Virtualized list |
+| `InfiniteScroll` | loadMore, hasMore | Infinite scroll wrapper |
+| `SortableList` | items, onReorder | Drag-and-drop reorder |
+| `AnimatedList` | items | Animated list with enter/exit |
+| `ResponsiveTable` | columns, data | Mobile-responsive table |
+| `HeatmapTable` | data, colorScale | Table with heatmap cells |
+| `SearchResults` | results, query | Search results display |
+| `Carousel` | items, autoPlay | Image/content carousel |
+| `ImagePreview` | src, zoom, rotate | Image viewer with controls |
+| `VideoPlayer` | src, controls | Video player |
+| `AudioPlayer` | src, waveform | Audio player |
+| `SignaturePad` | onSave | Signature drawing pad |
+| `AuditLog` | entries | Audit log display |
+| `ActivityFeed` | items | Activity feed |
+| `TransactionList` | transactions | Transaction history |
+| `NotificationCenter` | notifications | Notification panel |
+| `NotificationToast` | message, variant | Toast notification |
+| `ErrorBoundary` | fallback | Error boundary wrapper |
+| `Spotlight` | active, target | Spotlight/tour highlight |
+| `Embed` | url, type | Embed external content |
+| `ContactCard` | contact | Contact info card |
+| `EmployeeCard` | employee | Employee info card |
+| `PayslipCard` | payslip | Payslip display |
+| `ServiceCard` | service | Service status card |
+| `FileCard` | file | File preview card |
+| `DeployLog` | entries | Deployment log |
+| `SystemHealth` | services | System health overview |
+| `CookieBanner` | onAccept, onReject | Cookie consent |
+| `TagCloud` | tags | Tag cloud visualization |
+| `Changelog` | entries | Changelog display |
+| `PropertyEditor` | properties, onChange | Property key-value editor |
+| `RichSelect` | options, renderOption | Custom-rendered select |
+| `Parallax` | speed | Parallax scroll effect |
+| `Confetti` | active | Confetti celebration |
+| `DescriptionList` | items | DL-style key-value list |
+
+### L6 Charts (31 components)
+
+All charts are Recharts-based and accept `data`, `width`, `height`, and chart-specific props.
+
+| Component | Usage |
+|-----------|-------|
+| `AreaChart` | `<AreaChart data={data} xKey="date" yKey="value" />` |
+| `BarChart` | `<BarChart data={data} xKey="name" yKey="count" />` |
+| `LineChart` | `<LineChart data={data} xKey="date" yKeys={['a','b']} />` |
+| `PieChart` | `<PieChart data={data} nameKey="label" valueKey="amount" />` |
+| `ScatterChart` | Scatter/bubble plot |
+| `RadarChart` | Radar/spider chart |
+| `Treemap` | Hierarchical treemap |
+| `Heatmap` | Heat map grid |
+| `Gauge` | Single-value gauge |
+| `Sparkline` | Inline mini chart |
+| `FunnelChart` | Conversion funnel |
+| `SankeyChart` | Flow diagram |
+| `NetworkGraph` | Node-link graph |
+| `FlowChart` | Flow diagram |
+| `CandlestickChart` | OHLC candlestick |
+| `OrderBookChart` | Order book depth |
+| `CalendarHeatmap` | GitHub-style calendar heatmap |
+| `BubbleChart` | Sized bubble chart |
+| `BoxPlot` | Statistical box plot |
+| `ViolinPlot` | Violin distribution plot |
+| `Histogram` | Frequency histogram |
+| `WaffleChart` | Waffle/grid chart |
+| `RadialBarChart` | Radial bar |
+| `ComboChart` | Mixed chart types |
+| `SunburstChart` | Hierarchical sunburst |
+| `TimelineChart` | Time-based events |
+| `StreamChart` | Stacked stream |
+| `ChordDiagram` | Relationship chord |
+| `BumpChart` | Ranking bump chart |
+| `WaveformDisplay` | Audio waveform |
+| `WordCloud` | Word frequency cloud |
+
+### L7 Patterns (~55 components)
+
+Page-level layouts and composition patterns.
+
+| Component | Usage |
+|-----------|-------|
+| `DashboardLayout` | Full dashboard with sidebar + header + content |
+| `AdminLayout` | Admin panel layout |
+| `SettingsLayout` | Settings page with sidebar navigation |
+| `InboxLayout` | Email-style inbox layout |
+| `DevOpsLayout` | DevOps monitoring layout |
+| `FormLayout` | Form page layout |
+| `GridLayout` | Responsive grid |
+| `BentoGrid` | Bento-style grid layout |
+| `Masonry` | Masonry grid layout |
+| `SplitView` | Two-pane split view |
+| `Sidebar` | Collapsible sidebar navigation |
+| `NavBar` | Top navigation bar |
+| `StickyHeader` | Sticky page header |
+| `PageHeader` | Page title + breadcrumb + actions |
+| `Footer` | Page footer |
+| `Toolbar` | Action toolbar |
+| `ActionBar` | Contextual action bar |
+| `Hero` | Landing page hero section |
+| `CTABanner` | Call-to-action banner |
+| `EmptyState` | Empty state placeholder |
+| `LoadingStates` | Loading state patterns |
+| `SkeletonPattern` | Page-level skeleton |
+| `SplashScreen` | App splash/loading screen |
+| `LoginForm` | Login form pattern |
+| `StepperForm` | Multi-step form |
+| `WizardLayout` | Wizard layout |
+| `MetricCard` | Metric display card |
+| `StatsCard` | Statistics card |
+| `StatGrid` | Grid of stats |
+| `MiniDashboard` | Compact dashboard widget |
+| `GlassPanel` | Glass-effect panel |
+| `ProfileCard` | User profile card |
+| `PricingCard` | Pricing tier card |
+| `FeatureCard` | Feature showcase card |
+| `OnboardingCard` | Onboarding step card |
+| `DataExportCard` | Data export card |
+| `Testimonial` | Testimonial quote |
+| `FAQ` | FAQ accordion |
+| `ComparisonTable` | Feature comparison table |
+| `TimelineSteps` | Timeline step display |
+| `NotificationList` | Notification list page |
+| `MailComposer` | Email composer |
+| `CalendarView` | Full calendar page |
+| `ResponsiveContainer` | Responsive width container |
+| `MediaGrid` | Media/image grid |
+| `MonitorGrid` | Monitoring dashboard grid |
+| `ServerOverview` | Server status overview |
+| `StatusPage` | Public status page |
+| `KPIDashboard` | KPI metrics dashboard |
+| `AnalyticsDashboard` | Analytics dashboard |
+| `PayrollDashboard` | Payroll management dashboard |
+| `HRDashboard` | HR management dashboard |
+| `ProjectDashboard` | Project management dashboard |
+
+---
+
+## Common Usage Patterns
+
+### Composition Pattern (Card)
+
+```tsx
+<Card glass padding="default">
+  <CardHeader title="User Profile" subtitle="Account details" />
+  <CardContent>
+    <div className="flex flex-col gds-gap">
+      <Avatar name="Jane Doe" size="lg" status="online" />
+      <KeyValue label="Email" value="jane@example.com" />
+      <KeyValue label="Role" value="Admin" />
+    </div>
+  </CardContent>
+  <CardFooter>
+    <Button variant="secondary">Cancel</Button>
+    <Button variant="primary">Save</Button>
+  </CardFooter>
+</Card>
+```
+
+### Data Table
+
+```tsx
+<DataTable
+  columns={[
+    { key: 'name', header: 'Name', sortable: true },
+    { key: 'email', header: 'Email' },
+    { key: 'role', header: 'Role', filterable: true },
+    { key: 'status', header: 'Status', render: (row) => <StatusBadge status={row.status} /> },
+  ]}
+  data={users}
+  selectable
+  pagination={{ pageSize: 20 }}
+/>
+```
+
+### Form Pattern
+
+```tsx
+<FormLayout>
+  <FieldWrapper label="Name" required error={errors.name}>
+    <Input value={name} onChange={setName} />
+  </FieldWrapper>
+  <FieldWrapper label="Email" required error={errors.email}>
+    <Input type="email" value={email} onChange={setEmail} />
+  </FieldWrapper>
+  <FieldWrapper label="Role">
+    <Select options={roleOptions} value={role} onChange={setRole} />
+  </FieldWrapper>
+  <FormActions onSubmit={handleSubmit} onCancel={handleCancel} loading={submitting} />
+</FormLayout>
+```
+
+### Dashboard Pattern
+
+```tsx
+<DashboardLayout
+  sidebar={<Sidebar items={navItems} />}
+  header={<NavBar title="Admin" user={currentUser} />}
+>
+  <PageHeader title="Overview" actions={<Button>Export</Button>} />
+  <StatGrid>
+    <MetricCard label="Users" value={1234} trend={+12} />
+    <MetricCard label="Revenue" value="$45,678" trend={+8} />
+    <MetricCard label="Orders" value={567} trend={-3} />
+  </StatGrid>
+  <Card>
+    <CardHeader title="Recent Activity" />
+    <CardContent>
+      <DataTable columns={columns} data={recentData} />
+    </CardContent>
+  </Card>
+</DashboardLayout>
+```
+
+### Glass + Motion
+
+```tsx
+<GlassPanel>
+  <Card glass>
+    <CardContent>
+      <Button variant="primary" glass motion="scale">
+        Glass Button with Scale Animation
+      </Button>
+    </CardContent>
+  </Card>
+</GlassPanel>
+```
+
+---
+
+## Design Principles (ranked by priority)
+
+1. **Clarity over decoration** — data is the product, minimize chrome
+2. **Consistency breeds trust** — same action, same appearance, everywhere
+3. **Keyboard-first** — every action reachable by keyboard
+4. **Dark-native** — design for dark mode first
+5. **Immediate feedback** — visible response within 100ms
+6. **Motion as expression** — animation communicates, not decorates
+7. **AI-native** — semantic structure for both humans and AI agents
+8. **Glass as material** — frosted translucency as first-class material
+9. **Mobile-native** — parallel design target, not afterthought
+10. **Contextual depth** — auto-scaling based on nesting depth
+
+---
+
+## Tech Stack
+
+| Tool | Version | Role |
+|------|---------|------|
+| React | >=19.0.0 | UI framework (peer dep) |
+| TypeScript | 5.x | Type system (strict mode) |
+| Tailwind CSS | 4.x | Utility-first CSS |
+| CVA | 0.7.x | Variant management |
+| Jotai | 2.x | Theme state management |
+| Recharts | 3.x | Chart visualization |
+| Lucide | 0.577.x | Icon library |
+| Shiki | 4.x | Syntax highlighting |
+| Vite | 8.x | Build tool |
+| Vitest | 4.x | Test framework |
+| Bun | latest | Runtime & package manager |