aiox-core 5.0.4 → 5.0.5

package/pro/squads/design/data/motion-tokens-guide.md

@@ -1,202 +0,0 @@
-# Motion Tokens — Duration, Easing & Accessibility Guide
-
-**Source:** Industry best practices, Razorpay Blade DS reference implementation, Val Head (Tier 2 DNA)
-**Purpose:** Standard for defining motion tokens and ensuring accessibility
-**v4.1:** Enriched with Val Head's 5-purpose framework and UI choreography principles
-
----
-
-## Motion Token Categories
-
-### 1. Duration
-
-How long an animation takes.
-
-| Token | Value | Use Case |
-|-------|-------|----------|
-| `duration.instant` | `0ms` | Immediate state changes (checkbox toggle) |
-| `duration.fast` | `100ms` | Micro-interactions (hover, focus ring) |
-| `duration.normal` | `200ms` | Standard transitions (color, opacity) |
-| `duration.moderate` | `300ms` | Medium transitions (expand, slide) |
-| `duration.slow` | `400ms` | Larger animations (modal enter, drawer) |
-| `duration.deliberate` | `600ms` | Full-page transitions, complex orchestration |
-
-**Rule of thumb:** The bigger the element, the longer the duration. A button hover = fast. A page transition = deliberate.
-
-### 2. Easing
-
-How an animation accelerates/decelerates.
-
-| Token | Cubic Bezier | Use Case |
-|-------|-------------|----------|
-| `easing.standard` | `[0.4, 0, 0.2, 1]` | Default for most transitions |
-| `easing.entrance` | `[0, 0, 0.2, 1]` | Elements entering the viewport |
-| `easing.exit` | `[0.4, 0, 1, 1]` | Elements leaving the viewport |
-| `easing.emphasized` | `[0.2, 0, 0, 1]` | Attention-grabbing, primary actions |
-| `easing.linear` | `[0, 0, 1, 1]` | Progress bars, continuous motion |
-
-**W3C DTCG format:**
-```json
-{
-  "easing": {
-    "standard": {
-      "$value": [0.4, 0, 0.2, 1],
-      "$type": "cubicBezier",
-      "$description": "Default easing for standard UI transitions"
-    }
-  }
-}
-```
-
-### 3. Motion Actions
-
-Semantic motion patterns combining duration + easing.
-
-| Action | Duration | Easing | Description |
-|--------|----------|--------|-------------|
-| `enter` | moderate | entrance | Element appears in view |
-| `exit` | normal | exit | Element leaves view |
-| `expand` | moderate | standard | Container grows (accordion, dropdown) |
-| `collapse` | normal | standard | Container shrinks |
-| `fade-in` | normal | entrance | Opacity 0 → 1 |
-| `fade-out` | fast | exit | Opacity 1 → 0 |
-| `slide-in` | moderate | entrance | Element slides into position |
-| `slide-out` | normal | exit | Element slides out |
-| `scale-up` | normal | emphasized | Element scales from small to full |
-| `scale-down` | fast | exit | Element scales from full to small |
-
----
-
-## CSS Custom Properties Pattern
-
-```css
-:root {
-  /* Duration */
-  --motion-duration-instant: 0ms;
-  --motion-duration-fast: 100ms;
-  --motion-duration-normal: 200ms;
-  --motion-duration-moderate: 300ms;
-  --motion-duration-slow: 400ms;
-  --motion-duration-deliberate: 600ms;
-
-  /* Easing */
-  --motion-easing-standard: cubic-bezier(0.4, 0, 0.2, 1);
-  --motion-easing-entrance: cubic-bezier(0, 0, 0.2, 1);
-  --motion-easing-exit: cubic-bezier(0.4, 0, 1, 1);
-  --motion-easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
-}
-
-/* Usage */
-.modal-enter {
-  transition: opacity var(--motion-duration-moderate) var(--motion-easing-entrance),
-              transform var(--motion-duration-moderate) var(--motion-easing-entrance);
-}
-```
-
----
-
-## prefers-reduced-motion — Mandatory Handling
-
-### The Rule
-
-**Never disable animation entirely. Reduce, don't remove.**
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-    scroll-behavior: auto !important;
-  }
-}
-```
-
-### Better Approach — Preserve Meaning
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  .modal-enter {
-    /* Keep opacity (low-motion), remove transform (high-motion) */
-    transition: opacity var(--motion-duration-fast) var(--motion-easing-standard);
-    transform: none;
-  }
-}
-```
-
-### What to Reduce vs. Remove
-
-| Keep (reduced) | Remove |
-|----------------|--------|
-| Opacity transitions | Bouncing/spring animations |
-| Color changes | Parallax scrolling |
-| Simple fades | Auto-playing animations |
-| State indicators | Decorative motion |
-
----
-
-## Testing Motion
-
-### Visual Regression
-- Capture before/after states (not mid-animation)
-- Test both motion-enabled and reduced-motion states
-- Validate duration tokens match implementation
-
-### Accessibility Audit
-- [ ] prefers-reduced-motion respected on ALL animated elements
-- [ ] No animation causes seizure risk (3 flashes/second max)
-- [ ] Motion is not the only way to convey information
-- [ ] Autoplay content has pause/stop controls
-- [ ] Animation does not block interaction
-
-### Reference: Razorpay Blade DS
-Blade DS provides a production-grade reference implementation with:
-- Consistent duration/easing token scale
-- Shared motion primitives across components
-- prefers-reduced-motion handling on every animated component
-- Storybook stories showing motion in isolation
-
----
-
-## Val Head's 5-Purpose Framework (v4.1)
-
-Every animation MUST serve at least one of these purposes. If it serves none, remove it.
-
-| Purpose | Definition | Example |
-|---------|-----------|---------|
-| **Orient** | Help users understand spatial relationships | Page transitions showing view hierarchy |
-| **Direct Attention** | Guide focus to important elements | Notification badge animating in |
-| **Show Causality** | Demonstrate cause-and-effect | Button press triggering visible action |
-| **Provide Feedback** | Confirm user actions and system state | Loading spinner, success checkmark |
-| **Express Brand** | Communicate brand personality through motion | Custom easing curves, signature transitions |
-
-### UI Choreography (Val Head)
-
-> "Animations should feel like siblings who move similarly but are different people"
-
-- All animations in a product should have **coherent motion character**
-- Never design animations in isolation — consider the full motion vocabulary
-- Start with brand **voice and tone documents** as motion character input
-- Custom easing curves per brand — **never use CSS defaults** (ease, ease-in-out)
-
-### CSS vs JavaScript Decision (Val Head)
-
-| Use CSS | Use JavaScript |
-|---------|---------------|
-| Simple state transitions (hover, focus) | Chaining 3+ animations |
-| Single property changes | Runtime-dynamic values |
-| Performance-critical (compositor thread) | Physics-based / spring easing |
-| Declarative, predictable | Complex orchestration (staggered lists) |
-
-### Motion Audit Process (Val Head)
-
-1. **Inventory** — Catalogue ALL existing animations (CSS + JS)
-2. **Evaluate UX** — Does each animation pass the 5-purpose test?
-3. **Evaluate Brand** — Does motion character match brand personality?
-4. **Identify Redundancy** — Similar animations with different values?
-5. **Extract Tokens** — Normalize to duration/easing token scale
-6. **Create System** — Define motion token system from audit findings
-
-> "Motion has brand personality just like color and typography" — Val Head

package/pro/squads/design/data/roi-calculation-guide.md

@@ -1,142 +0,0 @@
-# ROI Calculation Guide
-
-**Purpose:** How to calculate real cost savings from design system
-**Agent:** Brad / Design System
-**Method:** Pattern-weighted cost analysis
-
----
-
-## Formula Base
-
-```python
-monthly_cost = patterns × hours_per_pattern × hourly_rate
-
-annual_savings = (cost_before - cost_after) × 12
-
-roi_ratio = annual_savings / implementation_cost
-```
-
----
-
-## Pattern Weights (Critical!)
-
-**Problem:** Not all patterns cost the same to maintain.
-
-**Solution:** Weight by complexity and change frequency.
-
-```python
-pattern_weights = {
-    'button': 1.0,        # Baseline (2h/month)
-    'input': 1.5,         # Validation logic
-    'form': 4.0,          # Complex state, validation
-    'modal': 2.0,         # Overlay logic, accessibility
-    'dropdown': 2.5,      # Complex interactions
-    'card': 0.8,          # Mostly layout
-    'color': 0.2,         # Trivial (just CSS)
-    'spacing': 0.3,       # Low complexity
-    'typography': 0.5,    # Medium complexity
-}
-
-weighted_hours = sum(
-    pattern_count × weight × base_hours
-    for pattern, count in patterns.items()
-)
-```
-
----
-
-## Example Calculation
-
-### Before Consolidation
-
-```yaml
-patterns:
-  buttons: 47 × 1.0 = 47 units
-  inputs: 23 × 1.5 = 34.5 units
-  forms: 12 × 4.0 = 48 units
-  colors: 89 × 0.2 = 17.8 units
-  spacing: 19 × 0.3 = 5.7 units
-
-total_units: 153 units
-hours_per_unit: 2h/month
-monthly_hours: 306h
-hourly_rate: $150/h
-monthly_cost: $45,900
-annual_cost: $550,800
-```
-
-### After Consolidation
-
-```yaml
-patterns:
-  buttons: 3 × 1.0 = 3 units
-  inputs: 5 × 1.5 = 7.5 units
-  forms: 3 × 4.0 = 12 units
-  colors: 12 × 0.2 = 2.4 units
-  spacing: 7 × 0.3 = 2.1 units
-
-total_units: 27 units
-monthly_hours: 54h
-monthly_cost: $8,100
-annual_cost: $97,200
-```
-
-### Savings
-
-```yaml
-monthly_savings: $37,800
-annual_savings: $453,600
-
-implementation_cost: $15,000
-
-roi_ratio: 30.2x
-breakeven: 0.4 months (12 days)
-```
-
----
-
-## Conservative vs Aggressive Estimates
-
-### Conservative (Recommended)
-
-- Base hours: 2h/month
-- Hourly rate: $150/h
-- Include only direct maintenance (bugs, updates)
-
-### Aggressive
-
-- Base hours: 3h/month
-- Include code reviews, discussions, decision time
-- Include opportunity cost of inconsistency
-
-**Brad recommends:** Use conservative numbers for stakeholders.
-
----
-
-## Beyond Direct Cost
-
-### Velocity Impact
-
-```python
-feature_velocity_multiplier = 3-6x
-
-# Conservative estimate: 4x
-time_saved_per_feature = 75%  # 16h → 4h
-
-features_per_sprint = baseline_features × 4
-```
-
-### Quality Improvements
-
-- Fewer bugs (consistent patterns)
-- Better accessibility (system enforces WCAG)
-- Easier onboarding (single source of truth)
-
-**Hard to quantify but real value.**
-
----
-
-## Brad says:
-
-"Conservative ROI = credible ROI.
-Underpromise, overdeliver."

package/pro/squads/design/data/token-mapping-reference.md

@@ -1,213 +0,0 @@
-# Token Mapping Reference
-
-> Mapeamento completo: Figma Token → CSS Variable → Tailwind Utility
-> Gerado pela task `f1-map-tokens-to-shadcn`. Atualizado a cada execucao do pipeline.
-
-## Status
-
-**Completo** — Mapeamento gerado a partir dos tokens em `figma-tokens-raw.md`.
-
-## Design Decisions
-
-| Decisao | Valor |
-|---|---|
-| **Tema base** | Dark-first |
-| **Primary** | Monocromatico (branco/preto — sem brand color) |
-| **Destructive** | brand/Khewra (#DC625E) |
-| **Success** | brand/Midori (#3A913F) |
-| **Warning** | brand/Sahara (#D6A461) |
-| **Info** | brand/Atmos (#77C5D5) |
-| **Base radius** | radius/xxs = 6px (0.375rem) |
-| **Font primary** | Outfit (headings) |
-| **Font secondary** | Inter (body) |
-| **Font tertiary** | JetBrains Mono (code) |
-
----
-
-## Core Tokens
-
-| Figma Token | CSS Variable | Tailwind Utility | Light Value (OKLch) | Dark Value (OKLch) |
-|---|---|---|---|---|
-| surface/white | `--background` | `bg-background` | oklch(1 0 0) | oklch(0.173 0 0) |
-| surface/950 | `--foreground` | `text-foreground` | oklch(0.173 0 0) | oklch(0.961 0 0) |
-| surface/white | `--card` | `bg-card` | oklch(1 0 0) | oklch(0.244 0 0) |
-| surface/950 | `--card-foreground` | `text-card-foreground` | oklch(0.173 0 0) | oklch(0.961 0 0) |
-| surface/white | `--popover` | `bg-popover` | oklch(1 0 0) | oklch(0.244 0 0) |
-| surface/950 | `--popover-foreground` | `text-popover-foreground` | oklch(0.173 0 0) | oklch(0.961 0 0) |
-| surface/950 → surface/white | `--primary` | `bg-primary` | oklch(0.173 0 0) | oklch(1 0 0) |
-| surface/white → surface/950 | `--primary-foreground` | `text-primary-foreground` | oklch(1 0 0) | oklch(0.173 0 0) |
-| surface/100 → surface/800 | `--secondary` | `bg-secondary` | oklch(0.961 0 0) | oklch(0.309 0 0) |
-| surface/950 → surface/100 | `--secondary-foreground` | `text-secondary-foreground` | oklch(0.173 0 0) | oklch(0.961 0 0) |
-| surface/100 → surface/800 | `--muted` | `bg-muted` | oklch(0.961 0 0) | oklch(0.309 0 0) |
-| surface/600 → surface/500 | `--muted-foreground` | `text-muted-foreground` | oklch(0.482 0 0) | oklch(0.719 0 0) |
-| surface/100 → surface/800 | `--accent` | `bg-accent` | oklch(0.961 0 0) | oklch(0.309 0 0) |
-| surface/950 → surface/100 | `--accent-foreground` | `text-accent-foreground` | oklch(0.173 0 0) | oklch(0.961 0 0) |
-| brand/Khewra | `--destructive` | `bg-destructive` | oklch(0.646 0.154 24.222) | oklch(0.646 0.154 24.222) |
-| surface/200 → white/10% | `--border` | `border-border` | oklch(0.928 0 0) | oklch(1 0 0 / 10%) |
-| surface/200 → white/15% | `--input` | `border-input` | oklch(0.928 0 0) | oklch(1 0 0 / 15%) |
-| surface/500 → surface/600 | `--ring` | `ring-ring` | oklch(0.719 0 0) | oklch(0.482 0 0) |
-| radius/xxs (6px) | `--radius` | `rounded-*` | 0.375rem | 0.375rem |
-
-## Chart Tokens
-
-| Figma Token | CSS Variable | Light Value | Dark Value |
-|---|---|---|---|
-| brand/Kobold → brand/Atmos | `--chart-1` | oklch(0.477 0.116 243.133) | oklch(0.779 0.08 212.201) |
-| brand/Midori | `--chart-2` | oklch(0.585 0.145 144.414) | oklch(0.585 0.145 144.414) |
-| brand/Sahara → brand/Nubia | `--chart-3` | oklch(0.751 0.103 73.232) | oklch(0.902 0.123 92.922) |
-| brand/Khewra → brand/Carota | `--chart-4` | oklch(0.646 0.154 24.222) | oklch(0.722 0.161 37.732) |
-| brand/Boreal → brand/Calla | `--chart-5` | oklch(0.462 0.126 352.763) | oklch(0.863 0.057 6.005) |
-
-## Sidebar Tokens
-
-| Figma Token | CSS Variable | Light Value | Dark Value |
-|---|---|---|---|
-| surface/100 → surface/900 | `--sidebar` | oklch(0.961 0 0) | oklch(0.244 0 0) |
-| surface/950 → surface/100 | `--sidebar-foreground` | oklch(0.173 0 0) | oklch(0.961 0 0) |
-| surface/950 → surface/white | `--sidebar-primary` | oklch(0.173 0 0) | oklch(1 0 0) |
-| surface/white → surface/950 | `--sidebar-primary-foreground` | oklch(1 0 0) | oklch(0.173 0 0) |
-| surface/200 → surface/800 | `--sidebar-accent` | oklch(0.928 0 0) | oklch(0.309 0 0) |
-| surface/950 → surface/100 | `--sidebar-accent-foreground` | oklch(0.173 0 0) | oklch(0.961 0 0) |
-| surface/200 → white/10% | `--sidebar-border` | oklch(0.928 0 0) | oklch(1 0 0 / 10%) |
-| surface/500 → surface/600 | `--sidebar-ring` | oklch(0.719 0 0) | oklch(0.482 0 0) |
-
-## Extension Tokens
-
-| Figma Token | CSS Variable | Tailwind Utility | Light Value | Dark Value | Nota |
-|---|---|---|---|---|---|
-| brand/Midori | `--success` | `bg-success` | oklch(0.585 0.145 144.414) | oklch(0.585 0.145 144.414) | Extensao |
-| surface/white | `--success-foreground` | `text-success-foreground` | oklch(1 0 0) | oklch(1 0 0) | Extensao |
-| brand/Sahara | `--warning` | `bg-warning` | oklch(0.751 0.103 73.232) | oklch(0.751 0.103 73.232) | Extensao |
-| surface/950 | `--warning-foreground` | `text-warning-foreground` | oklch(0.173 0 0) | oklch(0.173 0 0) | Extensao |
-| brand/Atmos | `--info` | `bg-info` | oklch(0.779 0.08 212.201) | oklch(0.779 0.08 212.201) | Extensao |
-| surface/950 | `--info-foreground` | `text-info-foreground` | oklch(0.173 0 0) | oklch(0.173 0 0) | Extensao |
-
-## Primitive Tokens (Figma → CSS Custom Properties)
-
-### Surface Scale
-
-| Figma Token | CSS Variable | Hex | OKLch |
-|---|---|---|---|
-| surface/white | `--surface-white` | #FFFFFF | oklch(1 0 0) |
-| surface/100 | `--surface-100` | #F2F2F2 | oklch(0.961 0 0) |
-| surface/200 | `--surface-200` | #E7E7E7 | oklch(0.928 0 0) |
-| surface/300 | `--surface-300` | #D4D4D4 | oklch(0.87 0 0) |
-| surface/400 | `--surface-400` | #BCBCBC | oklch(0.795 0 0) |
-| surface/500 | `--surface-500` | #A4A4A4 | oklch(0.719 0 0) |
-| surface/600 | `--surface-600` | #5E5E5E | oklch(0.482 0 0) |
-| surface/700 | `--surface-700` | #484848 | oklch(0.402 0 0) |
-| surface/800 | `--surface-800` | #303030 | oklch(0.309 0 0) |
-| surface/900 | `--surface-900` | #202020 | oklch(0.244 0 0) |
-| surface/950 | `--surface-950` | #101010 | oklch(0.173 0 0) |
-| surface/black | `--surface-black` | #000000 | oklch(0 0 0) |
-
-### Brand Palette
-
-| Figma Token | CSS Variable | Hex | OKLch |
-|---|---|---|---|
-| brand/Atmos | `--brand-atmos` | #77C5D5 | oklch(0.779 0.08 212.201) |
-| brand/Kobold | `--brand-kobold` | #006298 | oklch(0.477 0.116 243.133) |
-| brand/Bleu | `--brand-bleu` | #5691A1 | oklch(0.622 0.066 217.111) |
-| brand/Midori | `--brand-midori` | #3A913F | oklch(0.585 0.145 144.414) |
-| brand/Sahara | `--brand-sahara` | #D6A461 | oklch(0.751 0.103 73.232) |
-| brand/Boreal | `--brand-boreal` | #8B355F | oklch(0.462 0.126 352.763) |
-| brand/Cotta | `--brand-cotta` | #872526 | oklch(0.42 0.133 24.432) |
-| brand/Antar | `--brand-antar` | #BFE3ED | oklch(0.893 0.04 216.4) |
-| brand/Azzay | `--brand-azzay` | #79876D | oklch(0.605 0.042 130.689) |
-| brand/Cloro | `--brand-cloro` | #E2E99C | oklch(0.911 0.098 112.581) |
-| brand/Arena | `--brand-arena` | #FAEDBC | oklch(0.944 0.065 94.953) |
-| brand/Carota | `--brand-carota` | #F87C56 | oklch(0.722 0.161 37.732) |
-| brand/Khewra | `--brand-khewra` | #DC625E | oklch(0.646 0.154 24.222) |
-| brand/Nubia | `--brand-nubia` | #FBDD7A | oklch(0.902 0.123 92.922) |
-| brand/Calla | `--brand-calla` | #F4C3CC | oklch(0.863 0.057 6.005) |
-
-### Typography
-
-| Figma Token | CSS Variable | Value |
-|---|---|---|
-| font.family.primary | `--font-heading` | Outfit |
-| font.family.secondary | `--font-body` | Inter |
-| font.family.tertiary | `--font-mono` | JetBrains Mono |
-
-### Spacing Scale (px)
-
-| Token | Value |
-|---|---|
-| spacing/0 | 0px |
-| spacing/2 | 2px |
-| spacing/4 | 4px |
-| spacing/8 | 8px |
-| spacing/12 | 12px |
-| spacing/14 | 14px |
-| spacing/16 | 16px |
-| spacing/20 | 20px |
-| spacing/24 | 24px |
-| spacing/28 | 28px |
-| spacing/32 | 32px |
-| spacing/36 | 36px |
-| spacing/40 | 40px |
-| spacing/48 | 48px |
-| spacing/56 | 56px |
-| spacing/64 | 64px |
-| spacing/72 | 72px |
-| spacing/80 | 80px |
-| spacing/88 | 88px |
-| spacing/96 | 96px |
-| spacing/112 | 112px |
-| spacing/128 | 128px |
-| spacing/160 | 160px |
-| spacing/192 | 192px |
-
-### Radius Scale
-
-| Figma Token | CSS Variable | Value |
-|---|---|---|
-| radius/min | `--radius-sm` | 4px |
-| radius/xxs | `--radius` (base) | 6px |
-| radius/xs | `--radius-lg` | 8px |
-| radius/sm | — | 12px |
-| radius/md | — | 16px |
-| radius/lg | — | 24px |
-| radius/xl | — | 32px |
-| radius/xxl | — | 48px |
-| radius/max | — | 9999px |
-
-### Line Height
-
-| Token | Value |
-|---|---|
-| --line-height-xs | 100% |
-| --line-height-sm | 120% |
-| --line-height-md | 130% |
-| --line-height-lg | 150% |
-| --line-height-xl | 200% |
-
-### Letter Spacing
-
-| Token | Value |
-|---|---|
-| --letter-spacing-xxxs | -8% |
-| --letter-spacing-xxs | -6% |
-| --letter-spacing-xs | -4% |
-| --letter-spacing-sm | -2% |
-| --letter-spacing-md | 0% |
-| --letter-spacing-lg | 2% |
-| --letter-spacing-xl | 4% |
-| --letter-spacing-xxl | 6% |
-| --letter-spacing-xxxl | 8% |
-
-## Contraste WCAG AA
-
-| Par | Light Ratio | Dark Ratio | Status |
-|---|---|---|---|
-| foreground / background | 17.4:1 (#101010 on #FFFFFF) | 15.3:1 (#F2F2F2 on #101010) | PASS |
-| primary-foreground / primary | 17.4:1 (#FFFFFF on #101010) | 17.4:1 (#101010 on #FFFFFF) | PASS |
-| secondary-foreground / secondary | 14.8:1 (#101010 on #F2F2F2) | 10.3:1 (#F2F2F2 on #303030) | PASS |
-| muted-foreground / muted | 5.9:1 (#5E5E5E on #F2F2F2) | 5.5:1 (#A4A4A4 on #303030) | PASS |
-| accent-foreground / accent | 14.8:1 (#101010 on #F2F2F2) | 10.3:1 (#F2F2F2 on #303030) | PASS |
-| card-foreground / card | 17.4:1 (#101010 on #FFFFFF) | 12.5:1 (#F2F2F2 on #202020) | PASS |
-
----
-
-*Gerado por: Foundations Pipeline — Phase 1*
-*Ultima atualizacao: 2026-02-21*

package/pro/squads/design/data/w3c-dtcg-spec-reference.md

@@ -1,149 +0,0 @@
-# W3C Design Tokens (DTCG) v1.0 — Operational Reference
-
-**Source:** W3C Design Tokens Community Group stable spec (October 28, 2025)
-**Purpose:** Quick reference for implementing tokens in DTCG format
-
----
-
-## Format Structure
-
-Every token has three required properties:
-
-```json
-{
-  "token-name": {
-    "$value": "<the value>",
-    "$type": "<type identifier>",
-    "$description": "What this token is for"
-  }
-}
-```
-
-- `$value` — The actual design value
-- `$type` — One of the supported types (see below)
-- `$description` — Human/AI-readable purpose explanation
-
----
-
-## Supported Types
-
-| Type | Example $value | Notes |
-|------|---------------|-------|
-| `color` | `"#0066CC"` or `"oklch(0.65 0.15 250)"` | Hex, RGB, HSL, OKLCH |
-| `dimension` | `"16px"` or `"1rem"` | Spacing, sizing, radius |
-| `fontFamily` | `"Inter, sans-serif"` | Font stack |
-| `fontWeight` | `400` or `"bold"` | Numeric or named |
-| `duration` | `"200ms"` | Animation timing |
-| `cubicBezier` | `[0.4, 0, 0.2, 1]` | Easing curve (4 numbers) |
-| `number` | `1.5` | Unitless numbers (line-height, opacity) |
-| `strokeStyle` | `"solid"` or object | Border style |
-| `border` | `{"color": "...", "width": "...", "style": "..."}` | Composite |
-| `transition` | `{"duration": "...", "delay": "...", "timingFunction": [...]}` | Composite |
-| `shadow` | `{"color": "...", "offsetX": "...", "offsetY": "...", "blur": "...", "spread": "..."}` | Composite |
-| `gradient` | Array of stops | Linear/radial |
-| `typography` | `{"fontFamily": "...", "fontSize": "...", "fontWeight": ..., "lineHeight": ...}` | Composite |
-
----
-
-## Group Nesting
-
-Tokens are organized in groups using nesting:
-
-```json
-{
-  "color": {
-    "$type": "color",
-    "primary": {
-      "$value": "#0066CC",
-      "$description": "Primary brand color"
-    },
-    "secondary": {
-      "$value": "#6B7280",
-      "$description": "Secondary/muted color"
-    }
-  },
-  "spacing": {
-    "$type": "dimension",
-    "xs": { "$value": "4px" },
-    "sm": { "$value": "8px" },
-    "md": { "$value": "16px" },
-    "lg": { "$value": "24px" },
-    "xl": { "$value": "32px" }
-  }
-}
-```
-
-Setting `$type` on a group applies it to all children.
-
----
-
-## Mode Architecture
-
-Modes (light/dark/high-contrast) use token aliases:
-
-```json
-{
-  "color": {
-    "surface": {
-      "$type": "color",
-      "$value": "{color.white}",
-      "$extensions": {
-        "mode": {
-          "dark": "{color.gray-900}",
-          "high-contrast": "{color.black}"
-        }
-      }
-    }
-  }
-}
-```
-
-**Pattern:** Base value = light mode. Extensions define overrides per mode.
-
----
-
-## Aliases (References)
-
-Tokens can reference other tokens using `{}` syntax:
-
-```json
-{
-  "color": {
-    "brand": { "$value": "#0066CC", "$type": "color" },
-    "action-primary": { "$value": "{color.brand}", "$type": "color" }
-  }
-}
-```
-
-This creates semantic layers: primitive → semantic → component tokens.
-
----
-
-## Tooling Ecosystem
-
-| Tool | Role | DTCG Support |
-|------|------|-------------|
-| **Style Dictionary 4.x** | Token transformation/export | Full v1.0 |
-| **Tokens Studio** | Figma plugin for token management | Full v1.0 |
-| **Terrazzo** | CLI token compiler | Full v1.0 |
-| **Figma Variables** | Design tool native tokens | Partial (export via plugin) |
-| **Penpot** | Open-source design tool | Full v1.0 |
-
----
-
-## Migration from Proprietary Formats
-
-### From Style Dictionary v3 format
-- Add `$` prefix to `value` → `$value`
-- Add `$type` to each token or group
-- Move `type` from nested `attributes` to top-level `$type`
-
-### From Figma Variables
-- Export via Tokens Studio plugin in DTCG format
-- Map Figma collections to DTCG groups
-- Map Figma modes to `$extensions.mode`
-
-### From custom JSON/YAML
-- Restructure to `$value`/`$type`/`$description` format
-- Normalize types to DTCG supported types
-- Add group hierarchy