aiox-core 5.0.2 → 5.0.3

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

@@ -0,0 +1,202 @@
+# 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

@@ -0,0 +1,142 @@
+# 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

@@ -0,0 +1,213 @@
+# 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

@@ -0,0 +1,149 @@
+# 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