aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/tasks/ds-theme-multi-brand.md

@@ -1,90 +1,90 @@
-# Configure Multi-Brand Token Layers
-
-> Task ID: brad-theme-multi-brand
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `theming`
-
-## Description
-
-Configure multi-brand token architecture enabling multiple brands to share the same component library with different visual identities. Implements token layering (base → semantic → brand overrides) and brand switching mechanism.
-
-## Prerequisites
-
-- Existing design tokens (preferably W3C DTCG format)
-- At least 2 brand identities to support
-- Read data/ds-reference-architectures.md for theming patterns
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - Number of brands to support
-   - Brand identity assets (colors, typography, logos per brand)
-   - Token file location
-   - Shared vs. brand-specific components (if any)
-
-### Steps
-
-1. **Define Token Layer Architecture**
-   - Base layer: shared values (spacing, sizing, border-radius, motion)
-   - Semantic layer: purpose-based aliases (surface, primary, on-primary)
-   - Brand layer: brand-specific overrides (brand-a.primary = #0066CC, brand-b.primary = #CC0066)
-   - Check: base, semantic, and brand layers defined as separate token groups with no cross-contamination — log "3 layers defined: base ({N1} tokens), semantic ({N2}), brand ({N3})"
-
-2. **Create Brand Token Sets**
-   - For each brand: define color palette, typography, and any unique values
-   - Ensure all brands cover the same semantic token surface
-   - Validate no brand has missing tokens (gaps cause runtime errors)
-   - Check: for each brand, missing semantic token count == 0 — abort with "Brand '{name}' missing {N} semantic tokens: {list}"
-
-3. **Implement Brand Switching**
-   - CSS approach: CSS custom properties + [data-brand] attribute
-   - JS approach: theme context provider with brand parameter
-   - Generate brand-specific CSS files or dynamic switching utility
-   - Check: toggling [data-brand] attribute applies all brand tokens without page reload — abort with "Brand switching failed: {error}"
-
-4. **Validate Per-Brand Accessibility**
-   - Run contrast validation for each brand's color palette
-   - Ensure all brands pass WCAG AA minimum
-   - Flag brands with contrast issues
-   - Check: every brand's foreground/background pairs meet WCAG AA (4.5:1 normal, 3:1 large) — abort with "Brand '{name}' fails contrast: {N} pairs below AA"
-
-5. **Generate Brand Preview**
-   - Create side-by-side comparison of key components per brand
-   - Show token differences between brands
-   - Highlight shared vs. divergent values
-   - Update .state.yaml
-
-## Output
-
-- `tokens/base.json` — Shared base tokens
-- `tokens/brand-{name}.json` — Per-brand override tokens
-- `brand-switching.css` or `BrandProvider.tsx` — Switching mechanism
-- `brand-comparison.md` — Side-by-side brand preview
-- `.state.yaml` updated
-
-## Failure Handling
-
-- **Token coverage gap detected:** Halt processing, generate gap report listing missing semantic tokens per brand, require user to provide missing values before continuing
-- **Brand switching causes layout shift:** Rollback to single-brand mode, analyze token value deltas causing reflow (spacing/sizing changes >2px), propose normalized base values
-- **Contrast validation fails for multiple brands:** Generate per-brand remediation plan with specific color adjustments needed to meet WCAG AA, prioritize brands by user impact/traffic
-- **CSS custom property cascade conflicts:** Inspect computed styles, identify specificity issues or duplicate token declarations, recommend layer restructuring or scoped brand containers
-
-## Success Criteria
-
-- All brands share same component library with different visual identity
-- Brand switching is seamless (no page reload, no layout shift)
-- Every brand passes WCAG AA contrast validation
-- Token coverage is 100% for all brands
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+# Configure Multi-Brand Token Layers
+
+> Task ID: brad-theme-multi-brand
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `theming`
+
+## Description
+
+Configure multi-brand token architecture enabling multiple brands to share the same component library with different visual identities. Implements token layering (base → semantic → brand overrides) and brand switching mechanism.
+
+## Prerequisites
+
+- Existing design tokens (preferably W3C DTCG format)
+- At least 2 brand identities to support
+- Read data/ds-reference-architectures.md for theming patterns
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - Number of brands to support
+   - Brand identity assets (colors, typography, logos per brand)
+   - Token file location
+   - Shared vs. brand-specific components (if any)
+
+### Steps
+
+1. **Define Token Layer Architecture**
+   - Base layer: shared values (spacing, sizing, border-radius, motion)
+   - Semantic layer: purpose-based aliases (surface, primary, on-primary)
+   - Brand layer: brand-specific overrides (brand-a.primary = #0066CC, brand-b.primary = #CC0066)
+   - Check: base, semantic, and brand layers defined as separate token groups with no cross-contamination — log "3 layers defined: base ({N1} tokens), semantic ({N2}), brand ({N3})"
+
+2. **Create Brand Token Sets**
+   - For each brand: define color palette, typography, and any unique values
+   - Ensure all brands cover the same semantic token surface
+   - Validate no brand has missing tokens (gaps cause runtime errors)
+   - Check: for each brand, missing semantic token count == 0 — abort with "Brand '{name}' missing {N} semantic tokens: {list}"
+
+3. **Implement Brand Switching**
+   - CSS approach: CSS custom properties + [data-brand] attribute
+   - JS approach: theme context provider with brand parameter
+   - Generate brand-specific CSS files or dynamic switching utility
+   - Check: toggling [data-brand] attribute applies all brand tokens without page reload — abort with "Brand switching failed: {error}"
+
+4. **Validate Per-Brand Accessibility**
+   - Run contrast validation for each brand's color palette
+   - Ensure all brands pass WCAG AA minimum
+   - Flag brands with contrast issues
+   - Check: every brand's foreground/background pairs meet WCAG AA (4.5:1 normal, 3:1 large) — abort with "Brand '{name}' fails contrast: {N} pairs below AA"
+
+5. **Generate Brand Preview**
+   - Create side-by-side comparison of key components per brand
+   - Show token differences between brands
+   - Highlight shared vs. divergent values
+   - Update .state.yaml
+
+## Output
+
+- `tokens/base.json` — Shared base tokens
+- `tokens/brand-{name}.json` — Per-brand override tokens
+- `brand-switching.css` or `BrandProvider.tsx` — Switching mechanism
+- `brand-comparison.md` — Side-by-side brand preview
+- `.state.yaml` updated
+
+## Failure Handling
+
+- **Token coverage gap detected:** Halt processing, generate gap report listing missing semantic tokens per brand, require user to provide missing values before continuing
+- **Brand switching causes layout shift:** Rollback to single-brand mode, analyze token value deltas causing reflow (spacing/sizing changes >2px), propose normalized base values
+- **Contrast validation fails for multiple brands:** Generate per-brand remediation plan with specific color adjustments needed to meet WCAG AA, prioritize brands by user impact/traffic
+- **CSS custom property cascade conflicts:** Inspect computed styles, identify specificity issues or duplicate token declarations, recommend layer restructuring or scoped brand containers
+
+## Success Criteria
+
+- All brands share same component library with different visual identity
+- Brand switching is seamless (no page reload, no layout shift)
+- Every brand passes WCAG AA contrast validation
+- Token coverage is 100% for all brands
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/ds-token-modes.md

@@ -1,108 +1,108 @@
-# Configure Mode Architecture (Light/Dark/High-Contrast)
-
-> Task ID: brad-token-modes
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-> **Execution Type:** `Worker`
-> **Dependencies:** depends_on: `[ds-token-w3c-extract]` · enables: `[]` · workflow: `tokens`
-
-## Description
-
-Configure mode architecture for your design token system. Defines mode structure (light/dark/high-contrast/brand), creates semantic token aliases per mode, validates contrast ratios per mode, and generates mode switching mechanism.
-
-## Input Schema
-- **requires:** Output from `ds-token-w3c-extract`
-- **format:** JSON data (W3C DTCG v1.0)
-- **location:** `outputs/design-system/{project}/tokens/tokens-w3c-dtcg.json`
-
-## Prerequisites
-
-- Existing tokens (preferably in W3C DTCG format from *token-w3c)
-- Color palette defined
-- Read data/w3c-dtcg-spec-reference.md for mode format
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - Token file location
-   - Required modes (light, dark, high-contrast, brand variants)
-   - Current theme switching mechanism (if any)
-
-### Steps
-
-1. **Identify Mode-Sensitive Tokens**
-   - Find tokens that change between modes (colors, shadows, borders)
-   - Separate mode-independent tokens (spacing, typography, sizing)
-   - Check: uncategorized color token count == 0 — log "{N} mode-sensitive tokens, {M} invariant tokens identified"
-
-2. **Define Mode Structure**
-   - Create base mode (typically light)
-   - Define override values for each additional mode
-   - Use DTCG $extensions.mode format:
-     ```json
-     {
-       "color.surface": {
-         "$value": "#FFFFFF",
-         "$type": "color",
-         "$extensions": {
-           "mode": {
-             "dark": "#1A1A1A",
-             "high-contrast": "#000000"
-           }
-         }
-       }
-     }
-     ```
-   - Check: for each mode-sensitive token, value count == mode count — abort with "{N} tokens missing values for modes: {list}"
-
-3. **Create Semantic Token Aliases**
-   - Define semantic layer (surface, on-surface, primary, secondary, etc.)
-   - Map primitives to semantic tokens per mode
-   - Ensure consistent naming across modes
-   - Check: semantic tokens include surface, on-surface, primary, secondary at minimum — abort with "Semantic layer gaps: missing {list}"
-
-4. **Validate Contrast Ratios Per Mode**
-   - Check foreground/background pairs in each mode
-   - WCAG AA: 4.5:1 (normal text), 3:1 (large text)
-   - WCAG AAA: 7:1 (normal text), 4.5:1 (large text)
-   - High-contrast mode: verify enhanced ratios
-   - Check: every mode's foreground/background pairs meet WCAG AA (4.5:1 normal, 3:1 large) — abort with "Mode '{mode}' fails contrast: {N} pairs below AA"
-
-5. **Generate Mode Switching Mechanism**
-   - CSS: Generate @media (prefers-color-scheme) + [data-theme] classes
-   - JS: Generate theme provider/context if React
-   - Provide manual toggle implementation
-   - Test all modes render correctly
-   - Check: CSS contains @media (prefers-color-scheme) rules AND [data-theme] selectors exist AND manual toggle changes applied tokens — abort with "Mode switching incomplete: {missing mechanism}"
-
-## Output
-
-- `tokens-with-modes.json` — DTCG tokens with $extensions.mode
-- `mode-switching.css` — CSS for mode switching
-- `contrast-validation.md` — Per-mode contrast ratio report
-- `.state.yaml` updated
-
-## Failure Handling
-
-- **Contrast ratio failure in critical mode:** If dark mode or high-contrast mode has 5+ AA contrast failures on primary UI pairs (surface/on-surface, primary/on-primary), halt and suggest color adjustments with specific failing pairs listed
-- **Incomplete mode coverage:** If a mode-sensitive token is missing values for one or more declared modes (e.g., light and dark defined but high-contrast missing), fill gaps by cloning nearest mode's value and log "Mode gap filled: {token} in {mode} copied from {source_mode}"
-- **System preference detection fails:** If @media (prefers-color-scheme) does not apply correctly in test environment, fall back to [data-theme] attribute-only switching and note "System preference detection unavailable — using manual toggle only"
-- **Circular semantic alias chain:** If semantic token aliases create infinite loop (surface → primary → secondary → surface), detect cycle, break at weakest link by inlining a primitive value, and document as tech debt
-
-## Success Criteria
-
-- All modes defined with complete token coverage
-- Every mode passes WCAG AA contrast validation
-- Mode switching works via system preference and manual toggle
-- High-contrast mode provides enhanced readability
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+# Configure Mode Architecture (Light/Dark/High-Contrast)
+
+> Task ID: brad-token-modes
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Worker`
+> **Dependencies:** depends_on: `[ds-token-w3c-extract]` · enables: `[]` · workflow: `tokens`
+
+## Description
+
+Configure mode architecture for your design token system. Defines mode structure (light/dark/high-contrast/brand), creates semantic token aliases per mode, validates contrast ratios per mode, and generates mode switching mechanism.
+
+## Input Schema
+- **requires:** Output from `ds-token-w3c-extract`
+- **format:** JSON data (W3C DTCG v1.0)
+- **location:** `outputs/design-system/{project}/tokens/tokens-w3c-dtcg.json`
+
+## Prerequisites
+
+- Existing tokens (preferably in W3C DTCG format from *token-w3c)
+- Color palette defined
+- Read data/w3c-dtcg-spec-reference.md for mode format
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - Token file location
+   - Required modes (light, dark, high-contrast, brand variants)
+   - Current theme switching mechanism (if any)
+
+### Steps
+
+1. **Identify Mode-Sensitive Tokens**
+   - Find tokens that change between modes (colors, shadows, borders)
+   - Separate mode-independent tokens (spacing, typography, sizing)
+   - Check: uncategorized color token count == 0 — log "{N} mode-sensitive tokens, {M} invariant tokens identified"
+
+2. **Define Mode Structure**
+   - Create base mode (typically light)
+   - Define override values for each additional mode
+   - Use DTCG $extensions.mode format:
+     ```json
+     {
+       "color.surface": {
+         "$value": "#FFFFFF",
+         "$type": "color",
+         "$extensions": {
+           "mode": {
+             "dark": "#1A1A1A",
+             "high-contrast": "#000000"
+           }
+         }
+       }
+     }
+     ```
+   - Check: for each mode-sensitive token, value count == mode count — abort with "{N} tokens missing values for modes: {list}"
+
+3. **Create Semantic Token Aliases**
+   - Define semantic layer (surface, on-surface, primary, secondary, etc.)
+   - Map primitives to semantic tokens per mode
+   - Ensure consistent naming across modes
+   - Check: semantic tokens include surface, on-surface, primary, secondary at minimum — abort with "Semantic layer gaps: missing {list}"
+
+4. **Validate Contrast Ratios Per Mode**
+   - Check foreground/background pairs in each mode
+   - WCAG AA: 4.5:1 (normal text), 3:1 (large text)
+   - WCAG AAA: 7:1 (normal text), 4.5:1 (large text)
+   - High-contrast mode: verify enhanced ratios
+   - Check: every mode's foreground/background pairs meet WCAG AA (4.5:1 normal, 3:1 large) — abort with "Mode '{mode}' fails contrast: {N} pairs below AA"
+
+5. **Generate Mode Switching Mechanism**
+   - CSS: Generate @media (prefers-color-scheme) + [data-theme] classes
+   - JS: Generate theme provider/context if React
+   - Provide manual toggle implementation
+   - Test all modes render correctly
+   - Check: CSS contains @media (prefers-color-scheme) rules AND [data-theme] selectors exist AND manual toggle changes applied tokens — abort with "Mode switching incomplete: {missing mechanism}"
+
+## Output
+
+- `tokens-with-modes.json` — DTCG tokens with $extensions.mode
+- `mode-switching.css` — CSS for mode switching
+- `contrast-validation.md` — Per-mode contrast ratio report
+- `.state.yaml` updated
+
+## Failure Handling
+
+- **Contrast ratio failure in critical mode:** If dark mode or high-contrast mode has 5+ AA contrast failures on primary UI pairs (surface/on-surface, primary/on-primary), halt and suggest color adjustments with specific failing pairs listed
+- **Incomplete mode coverage:** If a mode-sensitive token is missing values for one or more declared modes (e.g., light and dark defined but high-contrast missing), fill gaps by cloning nearest mode's value and log "Mode gap filled: {token} in {mode} copied from {source_mode}"
+- **System preference detection fails:** If @media (prefers-color-scheme) does not apply correctly in test environment, fall back to [data-theme] attribute-only switching and note "System preference detection unavailable — using manual toggle only"
+- **Circular semantic alias chain:** If semantic token aliases create infinite loop (surface → primary → secondary → surface), detect cycle, break at weakest link by inlining a primitive value, and document as tech debt
+
+## Success Criteria
+
+- All modes defined with complete token coverage
+- Every mode passes WCAG AA contrast validation
+- Mode switching works via system preference and manual toggle
+- High-contrast mode provides enhanced readability
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/ds-token-w3c-extract.md

@@ -1,105 +1,105 @@
-# Extract Tokens in W3C DTCG v1.0 Format
-
-> Task ID: brad-token-w3c-extract
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-> **Execution Type:** `Worker`
-> **Dependencies:** depends_on: `[]` · enables: `[ds-token-modes]` · workflow: `tokens`
-
-## Description
-
-Scan codebase for design values (colors, spacing, typography, shadows, etc.), normalize them to W3C DTCG v1.0 stable format, organize in semantic groups, validate against spec, and export as tokens.json.
-
-## Output Schema
-- **produces:** `outputs/design-system/{project}/tokens/tokens-w3c-dtcg.json`
-- **format:** JSON data (W3C DTCG v1.0)
-- **consumed_by:** ds-token-modes
-
-## Prerequisites
-
-- Codebase with UI styles (CSS, Tailwind, styled-components, CSS-in-JS)
-- Read data/w3c-dtcg-spec-reference.md for format reference
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - Scan path for styles
-   - Existing token files (if any) to migrate
-   - Color format preference (hex, OKLCH, both)
-   - Output directory
-
-### Steps
-
-1. **Scan Design Values**
-   - Extract colors from CSS/JS (hex, rgb, hsl, oklch, named colors)
-   - Extract spacing values (px, rem, em)
-   - Extract typography (font families, sizes, weights, line heights)
-   - Extract shadows (box-shadow, drop-shadow)
-   - Extract border radii
-   - Extract transitions/durations
-   - Check: extracted value count > 0 AND each has file:line source reference — log "Extracted {N} design values from {F} files"
-
-2. **Normalize to DTCG Types**
-   - Map colors → $type: "color"
-   - Map spacing/sizing → $type: "dimension"
-   - Map font families → $type: "fontFamily"
-   - Map font weights → $type: "fontWeight"
-   - Map durations → $type: "duration"
-   - Map easing curves → $type: "cubicBezier"
-   - Map shadows → $type: "shadow" (composite)
-   - Map typography sets → $type: "typography" (composite)
-   - Check: untyped value count == 0 AND all $type values are among the 13 DTCG types — abort with "{N} values missing or have invalid $type"
-
-3. **Organize in Semantic Groups**
-   - Group by category (color, spacing, typography, etc.)
-   - Create semantic aliases (color.primary, color.surface, etc.)
-   - Add $description to every token explaining purpose
-   - Apply group-level $type where applicable
-   - Check: all tokens belong to a named group AND orphan token count == 0 — abort with "{N} orphan tokens found outside groups"
-
-4. **Validate Against Spec**
-   - Check all $value formats match their $type requirements
-   - Verify alias references resolve correctly ({group.token})
-   - Ensure no circular references
-   - Check $type is one of the 13 supported types
-   - Check: DTCG spec violation count == 0 (valid $value formats, resolved aliases, no circular refs) — abort with "{N} spec violations: {list}"
-
-5. **Export tokens.json**
-   - Write W3C DTCG compliant tokens.json
-   - Generate multi-format exports (CSS custom properties, Tailwind config, SCSS variables)
-   - Create migration mapping (old values → new token references)
-   - Update .state.yaml
-   - Check: `test -f tokens.json` AND JSON parses without errors AND file size > 0 — abort with "tokens.json generation failed: {error}"
-
-## Output
-
-- `tokens.json` — W3C DTCG v1.0 compliant token file
-- `tokens.css` — CSS custom properties export
-- `tokens-tailwind.js` — Tailwind config export
-- `migration-map.md` — Old values → token references
-- `.state.yaml` updated with token extraction results
-
-## Failure Handling
-
-- **No styles found in scan path:** If extraction finds zero CSS files or style declarations, exit with error "No styles detected in {path}. Verify scan path includes UI source files (CSS/JS/styled-components)."
-- **Conflicting color formats:** If same semantic color exists in multiple formats (hex, OKLCH, rgb) with different values, prompt user to choose canonical format or average values, then log conflict resolution in migration-map.md
-- **Unresolvable alias reference:** If token alias points to non-existent token (e.g., {color.primary} but color.primary undefined), exit with error "Broken alias: '{alias}' references undefined token. Fix source tokens before export."
-- **DTCG validation failure:** If tokens.json fails schema validation (invalid $type, malformed $value, or unsupported property), list all violations with line numbers and exit with "DTCG spec violations detected: {count} errors. Review data/w3c-dtcg-spec-reference.md for format requirements."
-
-## Success Criteria
-
-- All design values captured (95%+ coverage)
-- Every token has $value, $type, $description
-- tokens.json passes DTCG schema validation
-- Multi-format exports generated and valid
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+# Extract Tokens in W3C DTCG v1.0 Format
+
+> Task ID: brad-token-w3c-extract
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Worker`
+> **Dependencies:** depends_on: `[]` · enables: `[ds-token-modes]` · workflow: `tokens`
+
+## Description
+
+Scan codebase for design values (colors, spacing, typography, shadows, etc.), normalize them to W3C DTCG v1.0 stable format, organize in semantic groups, validate against spec, and export as tokens.json.
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/tokens/tokens-w3c-dtcg.json`
+- **format:** JSON data (W3C DTCG v1.0)
+- **consumed_by:** ds-token-modes
+
+## Prerequisites
+
+- Codebase with UI styles (CSS, Tailwind, styled-components, CSS-in-JS)
+- Read data/w3c-dtcg-spec-reference.md for format reference
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - Scan path for styles
+   - Existing token files (if any) to migrate
+   - Color format preference (hex, OKLCH, both)
+   - Output directory
+
+### Steps
+
+1. **Scan Design Values**
+   - Extract colors from CSS/JS (hex, rgb, hsl, oklch, named colors)
+   - Extract spacing values (px, rem, em)
+   - Extract typography (font families, sizes, weights, line heights)
+   - Extract shadows (box-shadow, drop-shadow)
+   - Extract border radii
+   - Extract transitions/durations
+   - Check: extracted value count > 0 AND each has file:line source reference — log "Extracted {N} design values from {F} files"
+
+2. **Normalize to DTCG Types**
+   - Map colors → $type: "color"
+   - Map spacing/sizing → $type: "dimension"
+   - Map font families → $type: "fontFamily"
+   - Map font weights → $type: "fontWeight"
+   - Map durations → $type: "duration"
+   - Map easing curves → $type: "cubicBezier"
+   - Map shadows → $type: "shadow" (composite)
+   - Map typography sets → $type: "typography" (composite)
+   - Check: untyped value count == 0 AND all $type values are among the 13 DTCG types — abort with "{N} values missing or have invalid $type"
+
+3. **Organize in Semantic Groups**
+   - Group by category (color, spacing, typography, etc.)
+   - Create semantic aliases (color.primary, color.surface, etc.)
+   - Add $description to every token explaining purpose
+   - Apply group-level $type where applicable
+   - Check: all tokens belong to a named group AND orphan token count == 0 — abort with "{N} orphan tokens found outside groups"
+
+4. **Validate Against Spec**
+   - Check all $value formats match their $type requirements
+   - Verify alias references resolve correctly ({group.token})
+   - Ensure no circular references
+   - Check $type is one of the 13 supported types
+   - Check: DTCG spec violation count == 0 (valid $value formats, resolved aliases, no circular refs) — abort with "{N} spec violations: {list}"
+
+5. **Export tokens.json**
+   - Write W3C DTCG compliant tokens.json
+   - Generate multi-format exports (CSS custom properties, Tailwind config, SCSS variables)
+   - Create migration mapping (old values → new token references)
+   - Update .state.yaml
+   - Check: `test -f tokens.json` AND JSON parses without errors AND file size > 0 — abort with "tokens.json generation failed: {error}"
+
+## Output
+
+- `tokens.json` — W3C DTCG v1.0 compliant token file
+- `tokens.css` — CSS custom properties export
+- `tokens-tailwind.js` — Tailwind config export
+- `migration-map.md` — Old values → token references
+- `.state.yaml` updated with token extraction results
+
+## Failure Handling
+
+- **No styles found in scan path:** If extraction finds zero CSS files or style declarations, exit with error "No styles detected in {path}. Verify scan path includes UI source files (CSS/JS/styled-components)."
+- **Conflicting color formats:** If same semantic color exists in multiple formats (hex, OKLCH, rgb) with different values, prompt user to choose canonical format or average values, then log conflict resolution in migration-map.md
+- **Unresolvable alias reference:** If token alias points to non-existent token (e.g., {color.primary} but color.primary undefined), exit with error "Broken alias: '{alias}' references undefined token. Fix source tokens before export."
+- **DTCG validation failure:** If tokens.json fails schema validation (invalid $type, malformed $value, or unsupported property), list all violations with line numbers and exit with "DTCG spec violations detected: {count} errors. Review data/w3c-dtcg-spec-reference.md for format requirements."
+
+## Success Criteria
+
+- All design values captured (95%+ coverage)
+- Every token has $value, $type, $description
+- tokens.json passes DTCG schema validation
+- Multi-format exports generated and valid
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.