@hegemonart/get-design-done 1.14.8 → 1.16.0

package/reference/components/tooltip.md

@@ -0,0 +1,201 @@
+# Tooltip — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Radix UI, Material 3, Carbon, Mantine, Fluent 2, Atlassian, Apple HIG
+**Wave**: 2 · **Category**: Containers
+
+---
+
+## Purpose
+
+A tooltip is a small, non-interactive label that appears on hover or keyboard focus to provide supplemental context for an element (typically an icon button or truncated text). It disappears on mouse-out, blur, or Escape. Tooltips MUST NOT contain interactive content (buttons, links, form elements). For interactive overlay content, use Popover. *(WAI-ARIA APG, Radix, Carbon all enforce this boundary)*
+
+---
+
+## Anatomy
+
+```
+[Icon button]  ← hover or focus triggers tooltip
+      │
+      ▼  (after 300ms delay)
+┌────────────┐
+│  Label     │  ← role="tooltip"; 12px; no interactive content
+└────────────┘
+     ▲  (optional 6px arrow caret)
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Trigger | Yes | Usually a button or interactive element |
+| Tooltip container | Yes | `role="tooltip"` + unique `id` |
+| Label text | Yes | Short (≤60 chars), descriptive |
+| Arrow | No | 6–8px caret indicating anchor |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Hover + focus triggered | All |
+| Delayed | 300ms show delay; 0ms hide | All (WAI-ARIA APG recommended) |
+| Instant | No delay (icon toolbars, dense UIs) | Material 3, Carbon |
+| Dark | Dark background regardless of theme | Most systems |
+| Light | Light background | Mantine (inverted) |
+
+**Norm** (≥7/18): 300ms show delay, 0ms hide; max-width 240px; never interactive content.
+**Diverge**: delay duration — Carbon recommends 100ms for toolbars; WAI-ARIA APG recommends ≤500ms. 300ms is the safe default.
+
+---
+
+## States
+
+| State | Trigger | ARIA |
+|-------|---------|------|
+| hidden | default | `role="tooltip"` hidden (not in tab order) |
+| visible (hover) | `mouseenter` (after delay) | `aria-describedby` on trigger points to tooltip id |
+| visible (focus) | `focusin` on trigger | same |
+| dismissed | `mouseleave`, `blur`, Escape | Tooltip hidden |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Max width | 240px | *(Material 3: 200px, Carbon: 288px, Fluent: 240px)* |
+| Padding | 6px 12px | |
+| Font size | 12px/400 | Smaller than body to signal supplemental role |
+| Border radius | 4–6px | Tight radius vs. card; feels like label |
+| Offset from trigger | 6–8px | |
+
+---
+
+## Typography
+
+- 12px/400 — tooltip text is supplemental; smaller weight and size distinguish it from primary content
+- No bold, no headings inside tooltip — it is a single line of text (≤60 chars preferred)
+- Multi-line: allowed if content genuinely requires it; still no interactive elements
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `tooltip`
+> **Trigger attributes**: `aria-describedby="tooltip-id"` — links the supplemental label
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | (on trigger) Shows tooltip when trigger receives focus |
+| Escape | Hides the tooltip |
+| Tab / Shift+Tab | Hides tooltip when focus leaves the trigger |
+
+Tooltip does NOT receive focus. It is purely a visual label attached to the trigger.
+
+### Accessibility Rules
+
+- Trigger MUST have `aria-describedby` pointing to the tooltip's `id` — screen readers read tooltip content as supplemental description
+- Tooltip is `role="tooltip"` — NOT `role="dialog"` (no interactivity, no focus trap)
+- Tooltip MUST appear on keyboard focus, not only on hover — keyboard-only users need access too *(WCAG 1.3.3, 2.1.1)*
+- Do NOT put interactive content inside a tooltip — use Popover (`reference/components/popover.md`)
+- Do NOT use tooltip as the only accessible name for a control — use `aria-label` on the trigger instead; tooltip supplements, not replaces, the accessible name
+- Escape MUST dismiss the tooltip without removing focus from the trigger *(WAI-ARIA APG)*
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Show | 100ms | ease-out | Fade only; no scale (too flashy for a label) |
+| Hide | 80ms | ease | Fade only; immediate on Escape |
+| Delay | 300ms | — | CSS `transition-delay` or JS timeout |
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip fade, instant show/hide
+
+---
+
+## Do / Don't
+
+### Do
+- Show on keyboard focus AND hover — not hover-only *(WAI-ARIA APG, WCAG 2.1.1)*
+- Use `aria-describedby` to link trigger to tooltip *(WAI-ARIA APG)*
+- Limit tooltip content to ≤60 chars — longer content belongs in a popover *(Carbon, Material 3)*
+- Apply 300ms show delay to prevent accidental triggers while cursor passes *(WAI-ARIA APG, Carbon)*
+
+### Don't
+- Don't put interactive elements inside a tooltip *(WAI-ARIA APG — this makes it a popover)*
+- Don't use tooltip as the only accessible name — `aria-describedby` supplements, not replaces, `aria-label` *(WAI-ARIA APG)*
+- Don't trigger tooltip on click — use a popover *(Radix, WAI-ARIA APG)*
+- Don't use tooltip for critical information — it's supplemental; users on touch devices may miss it *(Material 3, Polaris)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Interactive content inside tooltip | `reference/anti-patterns.md` |
+| Hover-only tooltip (not focus-triggered) | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="tooltip" not role="dialog" | WAI-ARIA APG |
+| Show on focus AND hover | WAI-ARIA APG, WCAG 2.1.1 |
+| Escape dismisses without removing focus | WAI-ARIA APG §3.2 |
+| 300ms delay | WAI-ARIA APG, Carbon |
+| 240px max-width | Material 3, Fluent 2 |
+| No interactive content | WAI-ARIA APG (all systems agree) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Tooltip triggered only on hover (not focus) — missing focusin handler
+grep -rn 'tooltip\|Tooltip' src/ | grep 'mouseenter\|onHover' | grep -v 'focus\|onFocus'
+
+# Interactive content inside tooltip
+grep -rn 'role="tooltip"' src/ | xargs grep -l 'button\|<a \|input' 2>/dev/null
+
+# Trigger missing aria-describedby
+grep -rn 'role="tooltip"' src/ | grep -v 'aria-describedby'
+
+# Tooltip without id (aria-describedby target requires id)
+grep -rn 'role="tooltip"' src/ | grep -v ' id='
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: tooltip shows on hover only, no focus trigger, no ARIA linkage -->
+<button class="icon-btn" onmouseenter="showTooltip()" onmouseleave="hideTooltip()">
+  <svg><!-- settings icon --></svg>
+</button>
+<div class="tooltip">Settings</div>
+```
+
+**Why it fails**: Keyboard users never see the tooltip. Screen readers receive no supplemental description. The `<div>` has no `role="tooltip"` and no `id`, so `aria-describedby` cannot link to it.
+**Grep detection**: `grep -rn 'mouseenter\|onHover' src/ | grep -i 'tooltip' | grep -v 'focus'`
+**Fix**:
+```html
+<button aria-describedby="settings-tip"
+        onmouseenter="show()" onmouseleave="hide()"
+        onfocusin="show()" onfocusout="hide()"
+        onkeydown="e.key==='Escape'&&hide()">
+  <svg aria-hidden="true"><!-- icon --></svg>
+  <span class="sr-only">Settings</span>
+</button>
+<div role="tooltip" id="settings-tip">Manage account settings</div>
+```

package/reference/data/google-fonts.csv

@@ -0,0 +1,51 @@
+family,category,variants,popularity_rank,best_for,pairing_suggestion
+Inter,sans-serif,"100 200 300 400 500 600 700 800 900",1,UI interfaces,JetBrains Mono
+Roboto,sans-serif,"100 300 400 500 700 900",2,Android apps,Roboto Mono
+Open Sans,sans-serif,"300 400 500 600 700 800",3,Content sites,Source Code Pro
+Lato,sans-serif,"100 300 400 700 900",4,Corporate,Inconsolata
+Montserrat,sans-serif,"100 200 300 400 500 600 700 800 900",5,Headers/Fashion,Raleway
+Poppins,sans-serif,"100 200 300 400 500 600 700 800 900",6,Modern UI,Space Mono
+Nunito,sans-serif,"200 300 400 500 600 700 800 900",7,Friendly apps,Nunito Sans
+Raleway,sans-serif,"100 200 300 400 500 600 700 800 900",8,Luxury/Editorial,Lato
+Oswald,sans-serif,"200 300 400 500 600 700",9,Impact headlines,Source Sans 3
+Source Sans 3,sans-serif,"200 300 400 500 600 700 900",10,Content/Enterprise,Source Serif 4
+Playfair Display,serif,"400 500 600 700 800 900",11,Editorial headers,Source Sans 3
+Merriweather,serif,"300 400 700 900",12,Long-form reading,Open Sans
+PT Sans,sans-serif,"400 700",13,CIS region apps,PT Serif
+Ubuntu,sans-serif,"300 400 500 700",14,Linux/tech apps,Ubuntu Mono
+Noto Sans,sans-serif,"100 200 300 400 500 600 700 800 900",15,Multilingual,Noto Serif
+Work Sans,sans-serif,"100 200 300 400 500 600 700 800 900",16,Modern websites,Space Mono
+Quicksand,sans-serif,"300 400 500 600 700",17,Playful/Wellness,Nunito
+Mulish,sans-serif,"200 300 400 500 600 700 800 900",18,Clean UI,Courier Prime
+DM Sans,sans-serif,"100 200 300 400 500 600 700 800 900",19,Tech/Modern,DM Mono
+DM Serif Display,serif,"400",20,Display headers,DM Sans
+IBM Plex Sans,sans-serif,"100 200 300 400 500 600 700",21,Enterprise/IBM,IBM Plex Mono
+IBM Plex Mono,monospace,"100 200 300 400 500 600 700",22,Code/Tech,IBM Plex Sans
+JetBrains Mono,monospace,"100 200 300 400 500 600 700 800",23,Developer tools,Inter
+Fira Code,monospace,"300 400 500 600 700",24,Developer tools,Fira Sans
+Space Mono,monospace,"400 700",25,Retro/Tech,Space Grotesk
+Space Grotesk,sans-serif,"300 400 500 600 700",26,Modern tech,Space Mono
+Plus Jakarta Sans,sans-serif,"200 300 400 500 600 700 800",27,Consumer apps,Syne
+Syne,sans-serif,"400 500 600 700 800",28,Creative headers,DM Sans
+Cabinet Grotesk,sans-serif,"100 200 300 400 500 600 700 800 900",29,Consumer branding,Satoshi
+Geist,sans-serif,"100 200 300 400 500 600 700 800 900",30,Vercel ecosystem,Geist Mono
+Geist Mono,monospace,"100 200 300 400 500 600 700 800 900",31,Code display,Geist
+Outfit,sans-serif,"100 200 300 400 500 600 700 800 900",32,Friendly SaaS,DM Mono
+Cormorant Garamond,serif,"300 400 500 600 700",33,Luxury editorial,Proza Libre
+EB Garamond,serif,"400 500 600 700 800",34,Classical print,Lato
+Libre Baskerville,serif,"400 700",35,Classic editorial,Libre Franklin
+Libre Franklin,sans-serif,"100 200 300 400 500 600 700 800 900",36,Editorial body,Libre Baskerville
+Crimson Pro,serif,"200 300 400 500 600 700 800 900",37,Long-form reading,Raleway
+Lora,serif,"400 500 600 700",38,Blog/editorial,Source Sans 3
+Bodoni Moda,serif,"400 500 600 700 800 900",39,Fashion/luxury,Jost
+Jost,sans-serif,"100 200 300 400 500 600 700 800 900",40,Modern sans,Bodoni Moda
+Exo 2,sans-serif,"100 200 300 400 500 600 700 800 900",41,Futuristic/Gaming,Roboto
+Bebas Neue,sans-serif,"400",42,Impact display,Open Sans
+Anton,sans-serif,"400",43,Bold headlines,Open Sans
+Archivo,sans-serif,"100 200 300 400 500 600 700 800 900",44,Neutral content,Archivo Black
+Cabin,sans-serif,"400 500 600 700",45,Humanist UI,Cabin Condensed
+Rubik,sans-serif,"300 400 500 600 700 800 900",46,Rounded UI,Fira Code
+Barlow,sans-serif,"100 200 300 400 500 600 700 800 900",47,Wide screens,Barlow Condensed
+Hind,sans-serif,"300 400 500 600 700",48,Devanagari+Latin,Roboto
+Manrope,sans-serif,"200 300 400 500 600 700 800",49,Modern rounded,JetBrains Mono
+Noto Serif,serif,"100 200 300 400 500 600 700 800 900",50,Multilingual body,Noto Sans

package/reference/data/palettes.csv

@@ -0,0 +1,41 @@
+Vertical,Primary,On-Primary,Secondary,On-Secondary,Accent,Background,Foreground,Card,Muted,Border,Destructive,Notes
+FinTech/Banking,#1A56DB,#FFFFFF,#0E9F6E,#FFFFFF,#F05252,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#E5E7EB,#E02424,Authoritative navy-blue signals trust; green secondary for positive states; red destructive for transfers/deletions. WCAG verified.
+Healthcare/Medical,#0E9F6E,#FFFFFF,#1A56DB,#FFFFFF,#FF8A4C,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#E5E7EB,#E02424,Clinical green primary communicates health and safety; blue secondary for informational states; amber accent for caution alerts. WCAG verified.
+SaaS/B2B Tools,#6875F5,#FFFFFF,#0E9F6E,#FFFFFF,#F05252,#FFFFFF,#111928,#F9FAFB,#F3F4F6,#E5E7EB,#E02424,Periwinkle-purple primary is the contemporary B2B SaaS signal; green secondary for success states; cards slightly off-white for depth. WCAG verified.
+E-commerce/Retail,#D97706,#FFFFFF,#1A56DB,#FFFFFF,#E02424,#FFFFFF,#111928,#F9FAFB,#FEF3C7,#E5E7EB,#DC2626,Amber primary drives purchase urgency; blue secondary for trust (payments); warm-yellow muted for promotional surfaces. WCAG verified.
+Gaming/Entertainment,#7E3AF2,#FFFFFF,#FF8A4C,#111928,#F05252,#111928,#F9FAFB,#1F2937,#374151,#4B5563,#EF4444,Deep violet on dark; amber accent for XP/reward moments; dark card creates depth. Light on dark meets 4.5:1. WCAG verified.
+Social/Community,#3F83F8,#FFFFFF,#0E9F6E,#FFFFFF,#F05252,#FFFFFF,#111928,#F9FAFB,#EFF6FF,#E5E7EB,#DC2626,Friendly blue; green for connection/online states; sky-tinted muted for feed separation. WCAG verified.
+Developer Tools,#0F172A,#F8FAFC,#6875F5,#FFFFFF,#22D3EE,#F8FAFC,#0F172A,#FFFFFF,#F1F5F9,#CBD5E1,#EF4444,Near-black on white for precision; purple secondary for interactive elements; cyan accent for syntax-highlight pops. WCAG verified.
+EdTech/Learning,#FF8A4C,#FFFFFF,#6875F5,#FFFFFF,#0E9F6E,#FFFBEB,#111928,#FFFFFF,#FEF3C7,#FDE68A,#DC2626,Warm amber primary energizes motivation; violet secondary for quiz elements; warm background avoids clinical white. WCAG verified.
+Legal/Compliance,#1E3A5F,#FFFFFF,#374151,#FFFFFF,#B45309,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#D1D5DB,#DC2626,Deep navy signals authority and precision; slate secondary for neutral chrome; amber for deadlines. WCAG verified.
+HR/People Ops,#7E3AF2,#FFFFFF,#FF8A4C,#FFFFFF,#0E9F6E,#FAF5FF,#111928,#FFFFFF,#F3F4F6,#E9D5FF,#DC2626,Violet balances authority and empathy; amber secondary for recognition; lavender muted for soft separation. WCAG verified.
+Real Estate/Property,#065F46,#FFFFFF,#1A56DB,#FFFFFF,#B45309,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#E5E7EB,#DC2626,Deep forest green signals land and stability; blue secondary for financing; amber for premium listings. WCAG verified.
+Travel/Hospitality,#1A56DB,#FFFFFF,#0E9F6E,#FFFFFF,#FF8A4C,#EFF6FF,#111928,#FFFFFF,#DBEAFE,#BFDBFE,#DC2626,Sky blue evokes open skies; green for confirmed bookings; amber for discovery warmth; sky-tinted muted distinctive. WCAG verified.
+Food/Delivery,#D97706,#FFFFFF,#E02424,#FFFFFF,#0E9F6E,#FFFBEB,#111928,#FFFFFF,#FEF3C7,#FDE68A,#B91C1C,Amber stimulates appetite and speed; red secondary for urgency; warm background mirrors food photography. WCAG verified.
+Fitness/Wellness,#047857,#FFFFFF,#1A56DB,#FFFFFF,#F05252,#F0FDF4,#111928,#FFFFFF,#DCFCE7,#BBF7D0,#DC2626,Saturated green signals vitality; blue secondary for calm recovery; red for max-effort moments; green-tinted background. WCAG verified.
+Non-profit/NGO,#065F46,#FFFFFF,#D97706,#111928,#1A56DB,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#E5E7EB,#DC2626,Deep green signals mission; amber secondary for warmth; blue accent for impact data reporting. WCAG verified.
+Government/Civic,#1E3A5F,#FFFFFF,#374151,#FFFFFF,#D97706,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#D1D5DB,#DC2626,Deep navy is the global government convention (GOV.UK/USWDS); slate for dense information; amber for notices. WCAG verified.
+Luxury/Fashion,#111928,#F9FAFB,#374151,#F9FAFB,#B45309,#FFFFFF,#111928,#F9FAFB,#F9FAFB,#E5E7EB,#DC2626,Near-black on white is the international luxury language; gold-amber accent for price points. WCAG verified.
+Media/Publishing,#111928,#F9FAFB,#E02424,#FFFFFF,#D97706,#FFFFFF,#111928,#F9FAFB,#F3F4F6,#E5E7EB,#B91C1C,Near-black mirrors newspaper conventions; red secondary for breaking news and editorial accents. WCAG verified.
+Analytics/BI,#1A56DB,#FFFFFF,#0E9F6E,#FFFFFF,#FF8A4C,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#E5E7EB,#DC2626,Blue primary anchors sequential chart palettes; green for positive delta; amber for cautionary thresholds. WCAG verified.
+AI/ML Platform,#4F46E5,#FFFFFF,#7E3AF2,#FFFFFF,#22D3EE,#0F172A,#F8FAFC,#1E293B,#334155,#475569,#EF4444,Indigo on dark — the established AI product visual language; violet secondary; cyan for streaming states. WCAG verified.
+Cybersecurity,#1E3A5F,#FFFFFF,#0E9F6E,#FFFFFF,#22D3EE,#0A0A0A,#F8FAFC,#111827,#1F2937,#374151,#EF4444,Deep navy on near-black for monitoring environment; green for all-clear; cyan for network visualization. WCAG verified.
+Logistics/Supply Chain,#D97706,#111928,#1A56DB,#FFFFFF,#0E9F6E,#FFFBEB,#111928,#FFFFFF,#FEF3C7,#FDE68A,#DC2626,Amber mirrors high-vis safety conventions; blue secondary for digital tracking; warm background differentiates. WCAG verified.
+Insurance,#1E3A5F,#FFFFFF,#0E9F6E,#FFFFFF,#D97706,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#D1D5DB,#DC2626,Navy signals protection and reliability; green for claims approved; amber for upcoming renewals. WCAG verified.
+Automotive,#111928,#F9FAFB,#374151,#F9FAFB,#E02424,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#D1D5DB,#B91C1C,Near-black matches premium automotive convention; red accent for performance/sport; silver-gray for chrome surfaces. WCAG verified.
+Agriculture/AgriTech,#065F46,#FFFFFF,#D97706,#111928,#1A56DB,#F0FDF4,#111928,#FFFFFF,#DCFCE7,#A7F3D0,#DC2626,Deep green is literal and honest; amber secondary for harvest richness; blue for water management data. WCAG verified.
+CleanTech/Sustainability,#047857,#FFFFFF,#1A56DB,#FFFFFF,#D97706,#F0FDF4,#111928,#FFFFFF,#DCFCE7,#BBF7D0,#DC2626,Rich emerald signals genuine environmental commitment; blue for resource tracking; amber for carbon metrics. WCAG verified.
+Pharmaceutical,#1E3A5F,#FFFFFF,#0E9F6E,#FFFFFF,#FF8A4C,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#D1D5DB,#DC2626,Regulated navy for clinical authority; green for health-positive states; amber for warnings. WCAG verified.
+Architecture/AEC,#374151,#FFFFFF,#D97706,#111928,#1A56DB,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#E5E7EB,#DC2626,Slate evokes material neutrality; amber for material warmth; blue for technical drawing layers. WCAG verified.
+Interior Design,#92400E,#FFFFFF,#065F46,#FFFFFF,#1E3A5F,#FFFBEB,#111928,#FFFFFF,#FEF3C7,#FDE68A,#DC2626,Warm terracotta evokes timber and clay; deep green for biophilic moments; warm cream background. WCAG verified.
+Music/Audio,#111928,#F9FAFB,#7E3AF2,#FFFFFF,#F05252,#0A0A0A,#F9FAFB,#1F2937,#374151,#4B5563,#EF4444,Near-black dark primary — music is dark-mode-first; violet for discovery; red for recording/live states. WCAG verified.
+Photography/Video,#111928,#F9FAFB,#374151,#F9FAFB,#FF8A4C,#0A0A0A,#F9FAFB,#1F2937,#374151,#4B5563,#EF4444,Near-black canvas lets content take center stage; amber accent for active tool states. WCAG verified.
+Crypto/Web3,#4F46E5,#FFFFFF,#0E9F6E,#FFFFFF,#F59E0B,#0F172A,#F8FAFC,#1E293B,#334155,#475569,#EF4444,Indigo on dark signals crypto-native aesthetic; green for confirmed transactions; gold for high-value events. WCAG verified.
+Marketing/AdTech,#D97706,#111928,#E02424,#FFFFFF,#7E3AF2,#FFFFFF,#111928,#F9FAFB,#FEF3C7,#FDE68A,#B91C1C,Amber signals campaign energy; red for CTAs and limited-offer badges; violet for creative moments. WCAG verified.
+Recruitment/HR Tech,#7E3AF2,#FFFFFF,#1A56DB,#FFFFFF,#0E9F6E,#FAF5FF,#111928,#FFFFFF,#F3E8FF,#E9D5FF,#DC2626,Violet signals human potential; navy secondary for employer trust; green for offer extended. WCAG verified.
+Customer Support/CX,#0E9F6E,#FFFFFF,#3F83F8,#FFFFFF,#FF8A4C,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#E5E7EB,#DC2626,Green signals resolution; blue for informational knowledge base; amber for escalation alerts. WCAG verified.
+E-learning/MOOC,#6875F5,#FFFFFF,#FF8A4C,#FFFFFF,#0E9F6E,#F9FAFB,#111928,#FFFFFF,#EFF6FF,#E0E7FF,#DC2626,Periwinkle primary bridges EdTech energy and SaaS discipline; amber for deadlines; green for completion. WCAG verified.
+Telemedicine,#1A56DB,#FFFFFF,#0E9F6E,#FFFFFF,#FF8A4C,#EFF6FF,#111928,#FFFFFF,#DBEAFE,#BFDBFE,#DC2626,Blue signals clinical authority on video calls; green for patient-status OK; sky-blue creates clinical calm. WCAG verified.
+Smart Home/IoT,#1E3A5F,#FFFFFF,#0E9F6E,#FFFFFF,#F59E0B,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#E5E7EB,#DC2626,Deep navy signals reliable connectivity; green for device-online states; amber for warnings and energy peaks. WCAG verified.
+Manufacturing/Industrial,#374151,#FFFFFF,#D97706,#111928,#1A56DB,#F9FAFB,#111928,#FFFFFF,#F3F4F6,#D1D5DB,#DC2626,Slate mirrors industrial material honesty; amber mirrors high-vis safety conventions; blue for OEE dashboards. WCAG verified.
+Construction,#D97706,#111928,#374151,#FFFFFF,#1A56DB,#FFFBEB,#111928,#FFFFFF,#FEF3C7,#FDE68A,#B91C1C,Amber is literal high-vis construction signaling; slate for technical plan review; blue for BIM and site tracking. WCAG verified.

package/reference/data/styles.csv

@@ -0,0 +1,39 @@
+Style,Keywords,Signature Effects,Best For,Avoid For,Light/Dark,Performance,Era
+Glassmorphism,"frosted glass, translucency, blur, layered depth","backdrop-filter: blur(20px); semi-transparent cards; rgba border; subtle inner glow","Dashboards, media apps, modern SaaS, AI/ML surfaces","Data-dense tables, accessibility-critical flows, low-end devices",Both (dark base preferred),High — compositor layer cost,2019–present
+Brutalism,"raw layout, stark contrast, intentional roughness, exposed grid","Hard pixel borders 2–4px solid; no border-radius; flat color fills; oversized type","Creative portfolios, challenger brands, indie products, arts organizations","Healthcare, regulated finance, government, e-commerce",Light mode primary,Lowest,2016–present
+Neumorphism,"extruded shadows, raised/inset UI, monochromatic, bilateral shadows","box-shadow: bilateral soft shadow; near-identical fg/bg hue; no hard borders","Personal finance concept dashboards, design prototypes","Accessibility-critical (fails WCAG), mobile, production apps",Light only,Low — but WCAG caution,2019–2021
+Flat Design 2.0,"minimal decoration, subtle shadows, vibrant palette, geometric icons","Single drop-shadow at low blur; bold sans-serif; 8pt spacing grid; no gradients","Productivity apps, documentation, enterprise SaaS, developer tools","Luxury/fashion, entertainment",Both,Lowest,2014–present
+Material Design 3,"dynamic color, tonal surfaces, M3 components, elevation via color","Tonal surface colors from brand seed; container/on-container pairs; state layers","Android-first apps, cross-platform Google-adjacent products","Apple HIG contexts, luxury brands, editorial-first experiences",Both,Low,2021–present
+Bento Grid,"card-grid layout, variable card sizes, grid gaps as design element","CSS Grid with named areas; card size 1×1 to 3×2; 8–16px gap; rounded cards","Marketing pages, dashboard home screens, portfolio showcases","Linear narrative content, long-form reading, checkout flows",Both,Low,2022–present
+AI-Native,"gradient meshes, dark base, glowing accents, particle effects","Gradient mesh background; particle canvas overlay; glowing border via box-shadow","AI/ML products, futuristic SaaS, developer platform landing pages","Traditional enterprise, regulated industries, healthcare",Dark primary,High — particle canvas/WebGL,2022–present
+Swiss Modernism 2.0 / International Style,"strict grid, functional typography, red-black-white, structure as beauty","Baseline 12-column grid; Helvetica/Neue Haas/Inter; red accent only; type as layout element","Editorial platforms, design agencies, cultural institutions","Consumer apps, gaming, children's products",Both,Lowest,1950–present (revival 2018–)
+Claymorphism,"3D inflated shapes, soft clay surfaces, pastel palette, inner shadows","border-radius: 30–50px; layered box-shadow (inner highlight + outer soft); pastel fills","Consumer apps, children's products, lifestyle, wellness, gifting","Enterprise, financial tools, anything requiring precision",Both,Medium,2021–present
+Dark Mode First,"deep backgrounds, elevation via surface color, low-saturation palette","Background #0A0A0A–#121212; surface gray ladder; text #F5F5F5; color desaturated 20%","Developer tools, code editors, media players, gaming","Healthcare in clinical settings, high-ambient-light kiosks",Dark primary,Low,2018–present
+Vaporwave/Retrowave,"neon gradients, dark base, grid lines, retro typography, CRT aesthetic","Hot pink to cyan gradient; background grid lines; scanline overlay; glow via text-shadow","Gaming, entertainment, nostalgia brands, Gen-Z consumer, music","Trust-critical verticals, healthcare, finance, government",Dark,High — glow filters and gradient overlays,1980s origin; revival 2016–present
+Editorial Grid,"overlapping text and image, asymmetric layout, strong typographic hierarchy","Text over image with mix-blend-mode; column-spanning type; headline 80–120px; serif display","Media platforms, publishing, editorial brands, portfolios","Functional SaaS, data-dense dashboards, e-commerce PDP",Both,Low,Print tradition; revival 2018–present
+HUD/Sci-Fi FUI,"monochrome on dark, thin lines, technical readout vocabulary, blinking cursors","Background #000; primary green or cyan on black; 1px rule lines; monospace; corner bracket elements","Technology/aerospace dashboards, game UI overlays, cybersecurity monitoring","Consumer products, non-technical users requiring instant clarity",Dark,High — continuous animations,Science fiction tradition; real-world FUI since 2010
+Minimal/Zen,"maximum whitespace, single accent, natural textures, typography-first","70%+ whitespace ratio; single color accent; thin-weight serif or geometric sans; optional paper texture 5%","Wellness apps, meditation products, luxury minimal brands, author portfolios","Feature-dense apps, complex navigation, high-information-density dashboards",Both,Lowest,2010–present
+Skeuomorphism 2.0,"realistic textures, modern execution, material-specific rendering","Leather/wood/metal textures via CSS or SVG; specular highlights; physical affordances","Premium music instruments, luxury hardware apps, high-end lifestyle products","Modern SaaS, productivity tools, frequent-update products",Both,Medium — texture assets and layered pseudo-elements,Original 2007–2013; revival 2021–present
+Neubrutalism,"visible borders, flat colors, stark contrast, browser-default-inspired","2–3px solid dark border on all interactive elements; flat fill; color-flip hover; no border-radius","Indie SaaS, creative tools, challenger brands, hackathon projects","Enterprise, regulated industries, anything requiring perceived polish",Both,Lowest,2021–present
+Memphis Design Revival,"geometric shapes, primary colors, patterns, 80s-inspired, maximalist","Bold geometric pattern fills; primary + secondary color blocking; pattern borders; mixed type weights","Consumer brands targeting Gen Z, playful e-commerce, lifestyle, pop culture","Professional services, enterprise, financial products",Both,Low,1980s origin; digital revival 2022–present
+Glassmorphism Dark,"frosted glass on dark base, darker frost panels, subtle neon borders","backdrop-filter: blur(24px) on near-black; card at rgba(255,255,255,0.05); neon border at 30% opacity","Gaming UI, media players, nightclub/event apps, AI product dark surfaces","Products requiring readable body text at scale",Dark,High — same as Glassmorphism,2020–present
+Aurora/Gradient Mesh,"flowing color gradients, no hard borders, dreamlike, organic forms","CSS mesh gradient 4–6 color stops at 40–70% opacity; no hard-edge borders; sections dissolve","AI/ML landing pages, creative platform hero sections, generative art tools","Data-dense apps, form-heavy flows, contexts requiring clear section boundaries",Both,Medium-High — large gradient repaint,2021–present
+Monochromatic Minimal,"single hue across full lightness range, typography-first, restraint","All elements share one hue; lightness 5%–97%; no accent color; type weight as only contrast variation","Portfolios, luxury brand identity, photography showcases, editorial","Multi-action apps, e-commerce, gaming",Both,Lowest,2015–present
+Conversion-First,"CTA-dominant layout, social proof, urgency mechanics, trust signals","Primary CTA above fold; social proof within 2 scroll steps; urgency timer; benefit bullets; sticky CTA bar","Lead-gen landing pages, SaaS trial pages, product launch pages","Brand storytelling, editorial, informational docs",Both,Low,2010–present
+Story-Scroll,"parallax narrative, scroll-triggered animations, cinematic pacing","IntersectionObserver fade-in sequences; horizontal scroll segments; full-bleed imagery; chapter breaks","Brand launches, product storytelling, annual reports, agency showreels","High-conversion pages, dashboard apps, utility tools",Both,Medium-High — JS animation and asset loading,2014–present
+Product Demo,"embedded interactive preview, annotated feature callouts, tooltip overlays","Inline iframe/video demo above fold; numbered callout dots; feature spotlight; interactive hotspot map","SaaS product landing pages, browser extension pages, design tool showcases","Services businesses, content sites, physical product e-commerce",Both,Medium — video autoplay and interactives,2016–present
+Trust-Builder,"certification display, testimonial photography, risk-reduction copy, authority signals","Client logo strip; testimonial cards with real photos; certification badges; security copy near forms","B2B SaaS sales pages, fintech onboarding, legal/compliance, high-ticket e-commerce","Consumer social apps, entertainment, developer tools",Both,Low,2012–present
+Playful Consumer,"rounded UI, emoji integration, micro-animations, confetti moments","border-radius 24–32px everywhere; emoji in headings; Lottie animation; confetti on conversion; bouncy spring","Consumer apps, gifting platforms, children's products, food delivery","Enterprise, financial products, healthcare, government",Both,Medium — Lottie/animation assets,2018–present
+Dark Premium,"full dark canvas, gold or silver accents, whitespace-heavy, editorial hierarchy","Background #0A0A0A; gold or silver accent; large display serif 80–120px; section-level vertical rhythm","Luxury SaaS, high-end services, premium membership, whiskey/watch brands","Mass-market consumer apps, anything needing color variety for hierarchy",Dark,Low,2018–present
+Typography-Led,"large type as hero, minimal imagery, type as design","Display type 100–200px; type positioned absolutely; tight leading 0.9–1.1; type color inverted from background","Editorial brands, design agencies, type foundries, artist/creative portfolios","Functional apps, e-commerce needing imagery",Both,Lowest,Print tradition; digital 2015–present
+Data-Driven,"charts and stats as hero visual, number-forward design","Large KPI numbers 80–120px in hero; inline sparkline; data annotation typography; tabular numerals","Analytics tools, investor relations, research organizations, fintech reporting","Lifestyle brands, emotional products, services without clear metrics",Both,Low — static SVG charts,2019–present
+Data Dense,"information-maximized layout, minimal chrome, small type","12–13px body in tables; 4–8px row padding; no card containers; tooltips over labels; condensed font","Bloomberg-style terminals, trading desks, operations centers, medical records","Consumer apps, mobile-primary, accessibility-critical",Both (dark preferred),Low,1990s terminal origin; modern SaaS 2012–present
+Executive Dashboard,"large KPIs, traffic-light status, minimal labels, decision-oriented","KPI cards at 48–64px; 3-color status system; sparkline per KPI; max 6 KPIs above fold","C-suite reporting, board packs, PE portfolio monitoring, business reviews","Operational monitoring, self-serve analytics",Both,Low,2010–present
+Operational Monitor,"real-time status indicators, alert color system, live data feel, dense timeline","WebSocket refresh indicator; color-coded service dots; rolling log window; alert banner; incident timeline","DevOps dashboards, NOC, cloud infrastructure monitoring, on-call tools","Executive reporting, consumer apps",Dark primary,Medium — live data updates,2012–present
+Data Storytelling,"prose plus inline charts, guided narrative, progressive disclosure","Section header states finding; chart supports; annotation layer; reading-width column 640–720px; chapter progress","Insight reports, analytics 'stories', investor updates, data journalism","Self-serve exploration dashboards, real-time ops",Both,Low,2017–present
+Grid/Matrix,"dense tabular layout, frozen headers, column sorting, comparison-ready","CSS sticky headers; zebra-stripe rows; column resize; monospace numbers; sort indicators; heatmap cells","Financial data apps, CRM list views, ERP, spreadsheet-replacement tools","Dashboards with narrative focus, mobile primary",Both,Low — virtualize beyond 500 rows,2000–present
+Graph/Network,"node-edge visualization, force-directed layout, interactive topology","SVG/Canvas force-directed graph; node size encodes metric; edge color encodes relationship; zoom/pan","Dependency maps, org charts, knowledge graphs, security blast-radius visualization","Static reports, mobile primary",Both,High — use WebGL for >1000 nodes,2012–present
+Geospatial,"map-first layout, choropleth overlays, geographic filter","Full-bleed map primary content area; choropleth scale legend; point clusters; polygon selection; sidebar detail","Logistics route analytics, retail location, real estate maps, public health dashboards","Products without geographic data, mobile with small screen",Both,High — map tile loading and vector layers,2010–present
+Timeline-First,"chronological layout, Gantt-inspired, temporal density","Horizontal scroll timeline; date-stamped lane per entity; milestone markers; dependency lines; zoom year→day","Project management, roadmap views, history visualization, editorial production","Real-time monitoring, KPI dashboards",Both,Medium — virtualized timeline required for long ranges,2015–present
+Comparison View,"side-by-side panels, diff highlighting, symmetrical layout","Two-column 50/50; synchronized scroll; diff highlights green/red; overlay mode toggle; summary diff in header","A/B test dashboards, design diff tools, version comparison, benchmark analysis","Single-subject dashboards, mobile primary",Both,Low,2015–present
+Mobile Analytics,"touch-optimized charts, swipe navigation, bottom-sheet detail","Horizontal bar charts; swipe between metric cards; bottom-sheet drill-down; 48px tap targets; pinch-zoom charts","Field sales apps, retail staff dashboards, on-the-go executive views, mobile-first ops","Desktop-primary tools, data-dense tables",Both,Low — chart library must support touch events,2018–present

package/reference/design-system-guidance.md

@@ -0,0 +1,177 @@
+# Design System Guidance
+
+A design system is not a component library. A component library is a collection of UI building blocks. A design system is the governing architecture that makes those components consistent, maintainable, and scalable across teams, products, and time. The difference matters because design systems require governance, versioning, and documentation infrastructure that component libraries do not. This file provides the principles and practices for building, evolving, and governing a design system at any maturity level.
+
+---
+
+## Token Versioning and Deprecation Policy
+
+Design tokens are an API. Like any API, they must be versioned, because the components and applications that consume them will break if tokens are renamed or removed without notice. Treating tokens as implementation details — things that can be changed quietly — is the single most common cause of unexpected visual regressions in design systems.
+
+**Semantic versioning for token APIs:** Token changes should follow SemVer semantics. Adding a new token is a minor release. Changing a token's value (e.g., updating `--color-brand-primary` from `#1a73e8` to `#1557b0`) is a minor release if the semantic meaning is preserved, or a major release if it changes the intent. Renaming or removing a token is always a major release.
+
+**Deprecation warnings before removal:** A token should never be removed without a deprecation period of at least one major version. During the deprecation period, the old token continues to work but emits a warning in development mode (or in Figma via variable mode annotation). The deprecation notice must include the replacement token and a migration date. Consumers who are warned well in advance can migrate on their own timeline; consumers who are surprised by breakage lose trust in the system.
+
+**Migration guides required:** Every major release that removes or renames tokens must include a migration guide. The guide must list every changed token, its old name, its new name, and a search-and-replace pattern that can be applied programmatically. A migration that requires consumers to manually discover what changed is not a migration — it is a breakage.
+
+**Never rename without aliasing:** When a token must be renamed — because the original name violated naming conventions, was ambiguous, or referred to a value rather than a purpose — the old name must be preserved as an alias pointing to the new name. The alias is deprecated and removed in the next major release after a documented migration window. This rule exists because token names propagate into codebases at scale: a rename without aliasing breaks every downstream consumer simultaneously.
+
+---
+
+## Multi-Brand Token Architecture
+
+A multi-brand token architecture allows a single component library to support multiple brand expressions — different color palettes, typography scales, and spacing densities — without forking the component code. The architecture achieves this through three distinct token layers, each with a specific responsibility.
+
+### Base Layer (Primitives)
+
+The base layer contains raw values with no semantic meaning. These are the atoms from which all other tokens are composed. A primitive token describes what the value is, not what it means or where it is used.
+
+Examples:
+- `--color-blue-500: #1a73e8`
+- `--color-blue-600: #1557b0`
+- `--space-4: 4px`
+- `--space-8: 8px`
+- `--font-size-16: 16px`
+
+Primitive tokens should never be used directly in component code. They exist only to feed the semantic layer. This constraint is essential: if components reference primitive tokens directly, you lose the ability to theme them without modifying component code.
+
+### Semantic Layer (Roles)
+
+The semantic layer maps primitive values to design roles. These tokens describe what a value is *for*, not what it *is*. The semantic layer is the theming boundary: swapping this layer changes the brand without touching components.
+
+Examples:
+- `--color-brand-primary: var(--color-blue-500)`
+- `--color-interactive-default: var(--color-brand-primary)`
+- `--color-surface-default: var(--color-white)`
+- `--color-text-primary: var(--color-grey-900)`
+
+Theme switching works by replacing the semantic layer. In practice, each brand defines its own semantic-layer token file that references its own base-layer primitives. Components import only semantic tokens; they have no knowledge of which primitive values are currently active.
+
+### Component Layer (Scoped Tokens)
+
+The component layer scopes semantic tokens to specific component contexts. Component-layer tokens exist because some components need values that differ from their semantic parents in specific states, variants, or sizes — but those differences should still be expressed as token relationships, not hardcoded values.
+
+Examples:
+- `--button-bg-primary: var(--color-interactive-default)`
+- `--button-bg-primary-hover: var(--color-interactive-hover)`
+- `--button-radius: var(--radius-md)`
+- `--card-shadow: var(--shadow-sm)`
+
+The component layer allows per-component overrides without polluting the semantic layer. It also makes the relationship between a component's visual properties and the broader token system explicit and auditable.
+
+---
+
+## Platform Translation
+
+The token architecture is only valuable if it can be consumed by all the platforms where the design system is deployed. Token translation tools convert the source-of-truth token definitions into platform-native formats.
+
+**Style Dictionary** is the standard open-source tool for token transformation. It reads a JSON or YAML token definition and transforms it into CSS custom properties, iOS Swift constants, Android XML resources, or any other format through a configurable pipeline. Style Dictionary is the right choice for most organizations because it is well-documented, widely adopted, and extensible. The transform pipeline should be version-controlled alongside the token definitions.
+
+**Tokens Studio (Figma plugin)** enables the design-to-code handoff by syncing Figma variables and styles to a JSON format that Style Dictionary can consume. When Tokens Studio is integrated with the CI pipeline — so that token changes in Figma trigger a transform and publish cycle — the design-to-code gap closes. Designers change tokens in Figma; engineers receive the updated CSS variables in the next publish. Without this integration, token values diverge between design and code, which is the root cause of most "the design says one thing but the code does another" defects.
+
+**Terrazzo** provides advanced token transform capabilities for organizations with complex multi-platform, multi-brand requirements. It handles cases that Style Dictionary handles awkwardly: mathematically derived scales (e.g., a spacing scale generated from a base value), conditional token resolution (different values for different contexts), and schema validation at the token definition level.
+
+---
+
+## Semantic-Layer Design
+
+The semantic layer is the design system's most consequential architectural decision. Naming tokens by value — `--color-red`, `--color-blue-700`, `--font-size-14` — produces a token API that is fragile under theming and misleading to consumers. Naming tokens by purpose produces an API that survives brand evolution, makes component intent explicit, and is safe to search and audit.
+
+**The cardinal rule:** Name tokens by PURPOSE, not by VALUE.
+
+Wrong: `--color-red` (a value name — breaks if the brand switches to orange for danger)  
+Right: `--color-surface-danger` (a purpose name — survives any palette change)
+
+Wrong: `--font-size-14` (a value name — breaks if the scale changes)  
+Right: `--font-size-caption` (a purpose name — survives a scale adjustment)
+
+**Tokens should survive theme changes without rename.** A token that must be renamed every time the palette changes is not a semantic token — it is a named value. The test: if you change the value of `--color-surface-danger` from red to orange, does the name still accurately describe its purpose? If yes, the name is semantic. If no, the name was value-based.
+
+**Hierarchical naming:** Semantic tokens should follow a consistent naming convention that expresses category, role, and variant:
+
+```
+--[category]-[role]-[variant]
+
+--color-surface-default
+--color-surface-subtle
+--color-surface-danger
+--color-text-primary
+--color-text-secondary
+--color-text-on-danger
+--shadow-elevation-sm
+--shadow-elevation-md
+```
+
+This convention makes the token vocabulary predictable: anyone who knows the convention can guess token names without consulting the documentation.
+
+---
+
+## Component API Conventions
+
+Component APIs are the contract between the design system and its consumers. An inconsistent or poorly designed API creates confusion, increases adoption friction, and makes migration painful. These conventions should be enforced in code review and documented in every component's API reference.
+
+**The `size` prop:** Always use named sizes — `sm`, `md`, `lg` — never raw pixel values. Pixel values expose implementation details and break the abstraction. Named sizes allow the design system to change the underlying pixel values across a version without requiring component consumers to update their code. `xs` and `xl` are acceptable additions when genuinely needed; avoid open-ended numeric scales that invite inconsistency.
+
+**The `variant` prop:** Use a fixed vocabulary: `primary`, `secondary`, `ghost`, `destructive`. Additional variants should be exceptional and documented with rationale. Never create variants that duplicate semantic roles (e.g., `danger` alongside `destructive`) — this fragments the vocabulary and creates consumer confusion about which to use.
+
+**Never expose internal implementation details as props.** A component whose API includes `backgroundColor`, `borderRadius`, or `fontWeight` props is not a component — it is a styled div. Internal visual properties should be determined by the component's variant and size, expressed through tokens. If a consumer needs visual customization beyond the declared variants, the appropriate tool is either a new variant (with a contribution RFC) or composition, not an escape hatch prop.
+
+---
+
+## Governance and Contribution Model
+
+A design system without governance is a suggestion library. Governance is what transforms a collection of shared components into a system with a consistent, predictable trajectory that teams can plan around.
+
+**RFC process for new tokens:** Any new semantic token must go through a Request for Comment process before being added to the system. The RFC must specify the token's name, its value, its purpose, which components will consume it, and whether it can be derived from existing tokens. The RFC process exists because new tokens are permanent: removing them requires a deprecation cycle, and adding unnecessary tokens pollutes the vocabulary.
+
+**Voting quorum for breaking changes:** Changes that remove or rename tokens, alter component API signatures, or change default visual behavior require a minimum quorum of token stakeholders (typically design leads and engineering leads from all consuming products) to review and approve. The quorum threshold and voting period should be documented and consistent. This prevents one team's urgency from creating breakage for other teams.
+
+**Single-owner per component:** Every component must have a named owner — a person who is responsible for its API, its documentation, its accessibility compliance, and its migration support. Ownerless components decay: they accumulate inconsistencies, miss accessibility regressions, and fall behind the token system evolution. Ownership should transfer explicitly when team members change roles.
+
+**Design and engineering sign-off both required:** No component ships without explicit sign-off from both the design lead (verifying that it matches the designed spec and has appropriate variant coverage) and the engineering lead (verifying that the API is correct, the implementation is idiomatic, and the tests cover the declared states). This dual sign-off is not bureaucracy — it is the minimal process that prevents the design-code gap from re-opening on every release.
+
+---
+
+## Documentation Standard
+
+A design system component that lacks complete documentation is not ready to ship. "Work in progress" documentation creates more confusion than no documentation at all, because it implies incomplete information without flagging what is missing. Every component must meet the documentation standard before it is published.
+
+The documentation standard for every component requires all of the following:
+
+**Purpose:** One or two sentences explaining what problem the component solves and when to use it rather than a different component. This is the most important section because it guides correct component selection.
+
+**Anatomy:** A labeled diagram or description of every visual element within the component: the container, the label, the icon, the state indicator. Anatomy documentation prevents implementers from modifying internal structure and creating visual inconsistencies.
+
+**Variants:** A complete catalog of all `variant` prop values with rendered examples and usage guidance. This section should answer "which variant should I use for X?" explicitly, not by inference.
+
+**States:** All interactive and conditional states the component can occupy: default, hover, active, focus, disabled, loading, error. Each state must be documented with a rendered example. Missing state documentation is the primary cause of inconsistent state implementation across consuming applications.
+
+**Do/Don't:** Paired examples showing correct and incorrect usage. Do/Don't documentation makes best practices concrete and prevents the most common misuse patterns.
+
+**Code example:** A minimal, copy-paste-ready code example for the most common usage. Consumers should be able to get to a correct implementation in under two minutes.
+
+**Accessibility notes:** The ARIA role, relevant ARIA attributes, keyboard interaction pattern, and focus management behavior. This section is not optional — every interactive component has accessibility requirements that cannot be inferred from the visual design alone.
+
+---
+
+## Design System Maturity Rubric
+
+Design systems evolve through recognizable maturity stages. Understanding where a system currently sits determines what investments are most impactful, and prevents organizations from attempting Level 4 governance without first establishing Level 3 token infrastructure.
+
+### Level 0: Ad-Hoc
+Components are built per project with no shared library. Each application makes its own visual decisions about color, typography, and spacing. There is no coordination mechanism, no shared vocabulary, and no reuse. Visual inconsistency across products is structural, not accidental. The cost of this level is paid in designer and engineer time spent rediscovering the same decisions on every project.
+
+### Level 1: Shared UI Kit
+A Figma component library exists and is used by designers. Components have documented variants and states in Figma. There is no code counterpart — developers implement from designs directly. The design-to-code gap is the defining problem at this level: the Figma library and the code diverge over time because there is no synchronization mechanism.
+
+### Level 2: Component Library
+Coded components exist and are shared across applications as a package. The library has basic documentation. There are no design tokens — visual values are hardcoded in component styles. Theming is not possible without forking the library. The code-to-design gap is still present because Figma and code are not synchronized.
+
+### Level 3: Token-Driven
+Design tokens exist in both Figma and code, synchronized through an automated pipeline (Tokens Studio + Style Dictionary). A semantic layer separates component implementations from raw values. Basic theming is possible by swapping the semantic layer. This is the first level where multi-brand support becomes practical. Most organizations that have invested in a design system are at Level 2 or approaching Level 3.
+
+### Level 4: Governed
+The system has a documented contribution process, semantic versioning, a deprecation policy, and migration guides. Every component has a named owner and complete documentation meeting the standard described in this file. Design and engineering sign-off is required for all releases. The system is reliable enough that consuming teams plan roadmaps around it rather than working around it.
+
+### Level 5: Platform
+The system supports multiple brands, multiple platforms (web, iOS, Android, potentially desktop), and automated quality enforcement. Accessibility compliance is verified in CI (automated contrast checking, ARIA validation). Visual regression testing catches unintended changes before release. Token transforms produce platform-native output. The system is itself a product with a roadmap, a changelog, a support channel, and a measured adoption rate across consuming products.