aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/tasks/ds-critical-eye-score.md

@@ -0,0 +1,109 @@
+# Critical Eye — Score Variants Using 5 Dimensions
+
+> Task ID: ds-critical-eye-score
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[ds-critical-eye-inventory]` · enables: `[ds-critical-eye-compare]` · workflow: `critical-eye`
+
+## Description
+
+Apply the Critical Eye scoring engine to every variant in the inventory. The engine evaluates 5 dimensions totaling 100 points: Breadth (25), Quality (30), Consistency (20), Maturity (15), Simplicity (10). Includes the absolute blocker: accessibility score = 0 triggers automatic REJECT regardless of total.
+
+Authority: Nathan Curtis/EightShapes, GOV.UK Contribution Criteria, USWDS Lifecycle, Brad Frost — Death to Complexity.
+
+## Output Schema
+- **produces:** `outputs/design-system/critical-eye/cycle-{N}/scored.json`
+- **format:** JSON — each variant with detailed per-dimension scores
+- **consumed_by:** ds-critical-eye-compare
+
+## Prerequisites
+
+- Inventory output from `ds-critical-eye-inventory` available
+- `squads/design/data/critical-eye-scoring-rules.yaml` loaded
+- Component source files accessible for quality evaluation
+- Component metadata JSONs accessible for enrichment
+
+## Workflow
+
+### Steps
+
+1. **Load Inputs**
+   - Read inventory JSON from previous step
+   - Read `critical-eye-scoring-rules.yaml` — full scoring configuration
+   - Check: both files valid and compatible (same cycle number)
+
+2. **Score Breadth (25 pts) — Nathan Curtis Breadth Scale**
+   - For each variant:
+     - Count `variant.sources.length`
+     - Apply rule: 1 source = 0pts (snowflake), 2 = 10pts (discuss), 3 = 15pts (probable), 4 = 20pts (strong), 5+ = 25pts (confirmed)
+   - Check: breadth score assigned to every variant
+
+3. **Score Quality (30 pts) — EightShapes Component QA**
+   - For each variant, evaluate 6 sub-dimensions:
+     - **token_compliance** (5pts): Count hardcoded values in source files (`#hex`, `Npx` except 0px). 0 hardcoded = 5pts, <5 = 3pts, 5-10 = 1pt, >10 = 0pts
+     - **states_coverage** (5pts): Count states implemented vs reference [default, hover, focus, disabled, error, loading]. Prorated: (implemented / 6) * 5
+     - **accessibility** (5pts, BLOCKER): Check WCAG AA contrast, ARIA attributes, keyboard nav, focus-visible. Score 0 = AUTOMATIC REJECT
+     - **responsiveness** (5pts): Check breakpoints coverage (mobile/tablet/desktop). All 3 = 5pts, 2 = 3pts, 1 = 1pt, fixed = 0pts
+     - **composability** (5pts): Evaluate how well it composes with other catalog variants. 3+ canonicals = 5pts, 1-2 = 3pts, requires adaptation = 1pt, incompatible = 0pts
+     - **resilience** (5pts): Test edge cases [empty content, long text, overflow, missing image, RTL]. All = 5pts, 3+ = 3pts, 1-2 = 1pt, none = 0pts
+   - Sum sub-dimensions for quality total
+   - Check: quality.accessibility evaluated — if 0, immediately flag variant for REJECT
+
+4. **Score Consistency (20 pts) — GOV.UK Contribution Criteria**
+   - For each variant, evaluate 3 sub-dimensions:
+     - **naming** (5pts): Check naming conventions (kebab-case, semantic prefixes). 100% = 5pts, minor desvios = 3pts, inconsistent = 0pts
+     - **api_patterns** (5pts): Check CVA + variant pattern + slot pattern usage. Full = 5pts, partial = 3pts, different API = 0pts
+     - **visual_harmony** (10pts): Evaluate visual coherence with DS. Indistinguishable = 10pts, small differences = 7pts, recognizably different = 4pts, conflicts = 0pts
+   - Check: consistency total calculated for all variants
+
+5. **Score Maturity (15 pts) — USWDS Component Lifecycle**
+   - For each variant, evaluate 3 sub-dimensions:
+     - **stability** (5pts): Check lifecycleHistory for breaking changes. No changes in 3+ cycles = 5pts, minor in last = 3pts, major recent = 1pt, new = 0pts
+     - **documentation** (5pts): Check for guidelines + API + examples + do/dont. Full = 5pts, partial = 3pts, JSDoc only = 1pt, none = 0pts
+     - **tests** (5pts): Check for unit + visual regression + a11y tests. All = 5pts, unit only = 3pts, smoke = 1pt, none = 0pts
+   - Check: maturity total calculated
+
+6. **Score Simplicity (10 pts) — Brad Frost Death to Complexity**
+   - For each variant, evaluate 2 sub-dimensions:
+     - **complexity** (5pts): Count LOC of main component file. <50 = 5pts, 50-150 = 3pts, 150-300 = 1pt, >300 = 0pts
+     - **dependencies** (5pts): Count external deps (excluding React + CVA). 0 = 5pts, 1-2 = 3pts, 3-5 = 1pt, 6+ = 0pts
+   - Check: simplicity total calculated
+
+7. **Calculate Total Score**
+   - Sum all 5 dimension totals: breadth + quality + consistency + maturity + simplicity
+   - Maximum possible: 25 + 30 + 20 + 15 + 10 = 100
+   - Check: total is between 0 and 100 for all variants
+
+8. **Apply Accessibility Blocker**
+   - For any variant where `quality.accessibility == 0`:
+     - Override lifecycle to `REJECT`
+     - Flag with `blocker: "accessibility_zero"`
+     - Log: "Variant {id} REJECTED — accessibility score 0 is absolute blocker"
+   - Check: all a11y-zero variants flagged
+
+9. **Generate Scored Output**
+   - Create `scored.json` with each variant's complete score breakdown
+   - Include dimension totals, sub-dimension details, and any blocker flags
+   - Check: output valid JSON, all variants scored
+
+## Failure Handling
+
+- **Inventory not found:** Abort with "Run ds-critical-eye-inventory first."
+- **Source files missing:** Score quality dimensions as 0 with note "source files not found"
+- **Scoring rules invalid:** Abort with YAML parsing error details
+
+## Success Criteria
+
+- [ ] All 5 dimensions scored for every variant
+- [ ] Breadth based on actual source counts
+- [ ] Quality evaluated against real component source code
+- [ ] Accessibility blocker applied (score=0 → REJECT)
+- [ ] Total scores between 0-100
+- [ ] Scored JSON output complete and valid
+- [ ] No dimension left as null after evaluation
+
+## Related Checklists
+
+- `squads/design/checklists/ds-critical-eye-review-checklist.md`

package/pro/squads/design/tasks/ds-designops.md

@@ -0,0 +1,99 @@
+# Setup DesignOps Workflow
+
+> Task ID: brad-ds-designops
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Hybrid`
+> **Human Checkpoint:** Review and approve the operational playbook and metrics dashboard configuration before rollout to the team
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `governance`
+
+## Description
+
+Setup DesignOps workflow for your design system team. Maps current operations, identifies bottlenecks, defines metrics, creates operational playbook, and configures dashboards.
+
+## Prerequisites
+
+- Active design system with at least 1 dedicated team member
+- Understanding of current DS workflow (even if informal)
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - DS team size and roles
+   - Current workflow (how components go from idea to production)
+   - Known bottlenecks or pain points
+   - Tools in use (Figma, Storybook, CI/CD, docs)
+
+### Steps
+
+1. **Map Current Operations**
+   - Document current component lifecycle (request → design → build → test → release)
+   - Identify handoff points between design and development
+   - Map review and approval cycles
+   - Document release process
+   - Check: workflow map has >= 1 stage AND each stage has owner + timeline — abort with "Workflow map incomplete: {N} stages missing owners or timelines"
+
+2. **Identify Bottlenecks**
+   - Design-to-dev handoff delays
+   - Review cycle length
+   - Release cadence gaps
+   - Documentation lag
+   - Consumer adoption barriers
+   - Check: bottleneck count >= 0 AND each has estimated impact (hours/sprint or cost) — log "Found {N} bottlenecks with total estimated impact of {hours} hours/sprint"
+
+3. **Define DesignOps Metrics**
+   - **Adoption rate:** % of product teams using DS components
+   - **Contribution velocity:** Components contributed per sprint/month
+   - **Time-to-component:** Days from request to production release
+   - **Coverage:** % of UI built with DS components vs. custom
+   - **Satisfaction:** Consumer team satisfaction score (survey)
+   - Check: each metric has data source identified AND collection method defined — abort with "Unmeasurable metrics: {list of metrics without data sources}"
+
+4. **Create Operational Playbook**
+   - Component request process
+   - Design review checklist
+   - Code review checklist
+   - Release checklist
+   - Onboarding guide for new DS team members
+   - Check: playbook contains sections for request, design review, code review, release, and onboarding — abort with "Playbook missing lifecycle stages: {list}"
+
+5. **Configure Metrics Dashboard**
+   - Define data sources for each metric
+   - Recommend dashboard tool (GitHub insights, custom, Notion)
+   - Create dashboard template with metric calculations
+   - Define review cadence (weekly/monthly)
+   - Update .state.yaml
+
+## Output
+
+- `designops-playbook.md` — Complete operational playbook
+- `designops-metrics.md` — Metric definitions and targets
+- `dashboard-config.md` — Dashboard setup and data sources
+- `.state.yaml` updated
+
+## Related Checklists
+
+- `squads/design/checklists/designops-maturity-checklist.md`
+- `squads/design/checklists/design-handoff-checklist.md`
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
+
+## Failure Handling
+
+- **Workflow mapping incomplete:** Request stakeholder interviews, document known stages with confidence scores, flag gaps requiring additional discovery, defer playbook creation until >=80% coverage achieved
+- **Metrics lack measurable data sources:** For each unmeasurable metric, propose proxy metrics with available data or recommend instrumentation additions, prioritize metrics by business impact
+- **Bottleneck impact cannot be quantified:** Run time-tracking pilot (1 sprint), instrument handoff points with timestamps, calculate actual vs. theoretical cycle time to establish baseline
+- **Dashboard tool integration fails:** Fallback to spreadsheet-based dashboard template, provide manual update instructions, estimate effort for custom dashboard implementation with available resources
+
+## Success Criteria
+
+- Complete workflow mapped with bottlenecks identified
+- Metrics are defined, measurable, and have targets
+- Playbook covers entire component lifecycle
+- Dashboard can be implemented with available tools
+
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/ds-extend-pattern.md

@@ -0,0 +1,91 @@
+# Extend Existing Pattern
+
+> Task ID: atlas-extend-pattern
+> Agent: Merovingian (Design System Builder)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[ds-build-component]` · enables: `[]` · workflow: `greenfield`
+
+## Description
+
+Add new variant, size, or feature to existing component without breaking compatibility. Maintains consistency with design system patterns.
+
+## Input Schema
+- **requires:** Output from `ds-build-component`
+- **format:** TypeScript source (existing component)
+- **location:** `outputs/design-system/{project}/components/{Component}/`
+
+## Prerequisites
+
+- Component exists
+- Design system setup complete
+- Tokens available for new variant
+
+## Workflow
+
+### Steps
+
+1. **Load Existing Component** - Read component file and structure
+2. **Validate Extension Request** - Check compatibility with existing API
+3. **Add New Variant/Size** - Extend props and implementation
+4. **Update Styles** - Add new variant styles using tokens
+5. **Update Tests** - Add tests for new variant
+6. **Update Stories** - Add story for new variant
+7. **Update Documentation** - Document new variant
+8. **Validate Backward Compatibility** - Ensure existing usage still works
+
+## Output
+
+- Updated component file
+- Updated styles
+- Updated tests
+- Updated documentation
+
+## Failure Handling
+
+- **Component not found:** If target component file does not exist at expected path, abort with "Component {ComponentName} not found at {path}. Verify component name and run *build first if component does not exist."
+- **Breaking API change detected:** If new variant requires changing existing prop types (e.g., string to union), abort with "Proposed change breaks backward compatibility: {change}. Add new prop instead of modifying existing."
+- **Token missing for new variant:** If new variant requires design token that does not exist in tokens file, abort with "Token {tokenName} not found for {variantName} variant. Add token to tokens.yaml before extending component."
+- **Existing variant tests failing:** If adding new variant causes existing tests to fail, abort with "{N} existing tests failing after extension: {list}. Fix regressions before proceeding—new variant must not break existing functionality."
+
+## Success Criteria
+
+- [ ] New variant implemented correctly
+- [ ] Backward compatible (existing code works)
+- [ ] Tests updated and passing
+- [ ] Documentation reflects changes
+- [ ] No breaking changes
+
+## Example
+
+```bash
+*extend button --variant warning
+
+Merovingian: "Adding 'warning' variant to Button..."
+✓ Updated Button.tsx (new variant prop)
+✓ Updated Button.module.css (warning styles)
+✓ Updated Button.test.tsx (warning tests)
+✓ Updated Button.stories.tsx (warning story)
+✓ Backward compatibility: ✓
+
+Warning variant uses:
+  - color: var(--color-warning)
+  - color (hover): var(--color-warning-dark)
+```
+
+## Notes
+
+- Maintain prop interface compatibility
+- Add, don't replace
+- Test existing variants still work
+- Document migration if API changes
+
+
+## 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-extract-tokens.md

@@ -0,0 +1,312 @@
+# Extract Design Tokens from Consolidated Patterns
+
+> Task ID: brad-extract-tokens
+> Agent: Brad (Design System Architect)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Worker`
+> **Dependencies:** depends_on: `[ds-consolidate-patterns]` · enables: `[ds-generate-migration-strategy, export-design-tokens-dtcg]` · workflow: `brownfield-audit`
+> **On Fail:** If token schema validation fails → check YAML syntax and W3C DTCG format compliance. If consolidation files missing → re-run `*consolidate`. If token coverage <80% → review consolidation output for missed patterns, add manual overrides. Do NOT proceed to migration with invalid tokens.
+
+## Description
+
+Generate design token system from consolidated patterns. Exports to multiple formats (YAML, JSON, CSS custom properties, Tailwind config, SCSS variables) with semantic naming conventions. **v4.0: Outputs W3C DTCG v1.0 format by default ($value, $type, $description).**
+
+## Input Schema
+- **requires:** Output from `ds-consolidate-patterns`
+- **format:** Text data (color-clusters.txt, spacing-consolidation.txt, button-consolidation.txt)
+- **location:** `outputs/design-system/{project}/consolidation/`
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/tokens/tokens.yaml`
+- **format:** YAML data (with JSON, CSS, Tailwind, SCSS exports)
+- **consumed_by:** ds-generate-migration-strategy, export-design-tokens-dtcg
+
+## Prerequisites
+
+- Consolidation completed (*consolidate command run successfully)
+- .state.yaml contains consolidation data
+- Consolidated pattern files exist (color-clusters.txt, spacing-consolidation.txt, etc)
+- Reference: Read data/w3c-dtcg-spec-reference.md for DTCG v1.0 token format
+- Reference: Read data/motion-tokens-guide.md for motion token extraction (duration, easing)
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to configure token generation.
+
+1. **Review Consolidation Results**
+   - Display consolidation summary (colors, buttons, spacing, typography)
+   - Confirm token generation from these patterns
+   - Ask for naming preferences (kebab-case default)
+
+2. **Select Export Formats**
+   - Ask which formats to export (DTCG JSON, CSS, Tailwind, SCSS, all)
+   - **Default: W3C DTCG v1.0 JSON** ($value, $type, $description)
+   - Confirm output directory
+   - Check for existing token files (overwrite warning)
+   - Ask about motion tokens (duration, easing) — extract from animations if present
+
+3. **Validate Token Coverage**
+   - Show coverage percentage (tokens cover X% of original usage)
+   - Target: >95% coverage
+   - Ask for approval before generating
+
+### Steps
+
+1. **Load Consolidation Data**
+   - Read .state.yaml consolidation section
+   - Load consolidated pattern files
+   - Confirm .state.yaml contains `phase: "consolidation_complete"` string; abort if missing
+   - Check: .state.yaml contains `phase: "consolidation_complete"` AND consolidated pattern files exist — abort with "Consolidation not completed: run *consolidate first"
+
+2. **Extract Color Tokens**
+   - Read color-clusters.txt
+   - Generate semantic names (primary, primary-dark, error, success, etc)
+   - Detect relationships (hover states, light/dark variants)
+   - Create color token structure
+   - Check: unnamed color count == 0 AND each token has semantic name — log "{N} color tokens created from {clusters} clusters"
+
+3. **Extract Spacing Tokens**
+   - Read spacing-consolidation.txt
+   - Map spacing values to semantic scale (xs, sm, md, lg, xl, 2xl, 3xl)
+   - Generate both padding and margin tokens
+   - Check: spacing scale has xs through xl values AND uses consistent base unit — log "Spacing scale: {N} tokens, base unit: {unit}"
+
+4. **Extract Typography Tokens**
+   - Read typography-consolidation.txt
+   - Create font-family tokens
+   - Create font-size tokens with semantic names
+   - Create font-weight tokens
+   - Create line-height tokens (calculated from sizes)
+   - Check: typography tokens include families + sizes + weights + line-heights — abort with "Typography incomplete: missing {category}"
+
+5. **Extract Button Tokens**
+   - Read button-consolidation.txt
+   - Generate button variant tokens (primary, secondary, destructive)
+   - Generate button size tokens (sm, md, lg)
+   - Map colors and spacing to button tokens
+   - Check: button tokens use color + spacing token references (not hardcoded values) — abort with "Button tokens contain {N} hardcoded values"
+
+6. **Generate tokens.yaml (Source of Truth)**
+   - Create structured YAML with all token categories
+   - Include metadata (version, generated timestamp, Brad signature)
+   - Add comments explaining token usage
+   - Check: `test -f tokens.yaml` AND YAML parses without errors — abort with "tokens.yaml generation failed: {parse error}"
+
+7. **Export to JSON**
+   - Convert tokens.yaml to tokens.json
+   - Flat structure for JavaScript imports
+   - Check: `test -f tokens.json` AND JSON parses without errors — abort with "tokens.json generation failed: {parse error}"
+
+8. **Export to CSS Custom Properties**
+   - Generate tokens.css with :root {} block
+   - Convert token names to --token-name format
+   - Add CSS comments for organization
+   - Check: `test -f tokens.css` AND contains :root block with var declarations — abort with "tokens.css generation failed"
+
+9. **Export to Tailwind Config**
+   - Generate tokens.tailwind.js
+   - Map tokens to Tailwind theme.extend structure
+   - Preserve Tailwind conventions
+   - Check: `test -f tokens.tailwind.js` AND file exports theme.extend object — abort with "Tailwind config generation failed"
+
+10. **Export to SCSS Variables**
+    - Generate tokens.scss
+    - Convert to $token-name format
+    - Add SCSS comments
+    - Check: `test -f tokens.scss` AND file contains $variable declarations — abort with "SCSS generation failed"
+
+11. **Validate Token Coverage**
+    - Count original patterns from consolidation output and count tokens that map to them; compute coverage = mapped/total * 100
+    - Target: >95% coverage
+    - List each uncovered pattern by name with its source file
+    - Check: token coverage >= 95% of original patterns — if below, list uncovered patterns and log "Coverage: {pct}% ({covered}/{total})"
+
+12. **Update State File**
+    - Add tokens section to .state.yaml
+    - Record token counts, locations, exports
+    - Update phase to "tokenize_complete"
+    - Check: .state.yaml contains `phase: "tokenize_complete"` AND token counts + file locations recorded — abort with "State update failed: {missing field}"
+
+## Output
+
+- **tokens.yaml**: Source of truth with all design tokens
+- **tokens.json**: JavaScript/TypeScript import format
+- **tokens.css**: CSS custom properties (:root)
+- **tokens.tailwind.js**: Tailwind config format
+- **tokens.scss**: SCSS variables format
+- **token-coverage-report.txt**: Coverage analysis
+- **.state.yaml**: Updated with token metadata
+
+### Output Format
+
+```yaml
+# tokens.yaml
+version: "1.0.0"
+generated_by: "Brad (Design System Architect)"
+generated_at: "2025-10-27T13:00:00Z"
+
+color:
+  primary: "#0066CC"
+  primary-dark: "#0052A3"
+  secondary: "#6B7280"
+  error: "#DC2626"
+  error-light: "#FEE2E2"
+  success: "#059669"
+  success-light: "#D1FAE5"
+  warning: "#F59E0B"
+  neutral-50: "#F9FAFB"
+  neutral-100: "#F3F4F6"
+  neutral-900: "#111827"
+
+spacing:
+  xs: "4px"
+  sm: "8px"
+  md: "16px"
+  lg: "24px"
+  xl: "32px"
+  2xl: "48px"
+  3xl: "64px"
+
+typography:
+  font-base: "Inter, system-ui, sans-serif"
+  font-mono: "JetBrains Mono, monospace"
+  size-xs: "12px"
+  size-sm: "14px"
+  size-base: "16px"
+  size-lg: "20px"
+  size-xl: "24px"
+  size-2xl: "32px"
+  weight-light: 300
+  weight-normal: 400
+  weight-semibold: 600
+  weight-bold: 700
+  line-tight: 1.25
+  line-normal: 1.5
+  line-relaxed: 1.75
+
+radius:
+  sm: "4px"
+  base: "8px"
+  lg: "12px"
+  full: "9999px"
+
+shadow:
+  sm: "0 1px 2px 0 rgb(0 0 0 / 0.05)"
+  base: "0 1px 3px 0 rgb(0 0 0 / 0.1)"
+  lg: "0 10px 15px -3px rgb(0 0 0 / 0.1)"
+```
+
+## Failure Handling
+
+- **Token coverage <95%:** Identify uncovered patterns. Add manual token definitions for edge cases. Re-calculate coverage
+- **Naming conflicts:** Use prefix strategy (e.g., `--color-primary-legacy` vs `--color-primary`). Document conflicts in migration notes
+- **Invalid token values:** Validate against CSS spec. Convert non-standard values (e.g., named colors → hex → OKLCH)
+- **Consolidation data missing:** Re-run *consolidate before proceeding. Do not generate partial token sets
+
+## Success Criteria
+
+- [ ] All consolidated patterns converted to tokens
+- [ ] Semantic naming follows conventions (kebab-case)
+- [ ] Hover states and variants detected automatically
+- [ ] All 5 export formats generated successfully
+- [ ] Token coverage >95% of original patterns
+- [ ] Valid syntax in all export formats
+- [ ] State file updated with token locations
+
+## Quality Gate
+
+> **GATE: Token Completeness Review** — Verify token coverage before migration planning
+
+| Metric | Threshold | Action if FAIL |
+|--------|-----------|----------------|
+| Token coverage | >= 95% of consolidated patterns | Add manual token definitions for uncovered patterns, re-calculate |
+| Naming conflicts | 0 | Resolve with prefix strategy (`--legacy-` prefix), re-validate |
+| W3C DTCG compliance | 100% of generated tokens | Fix non-compliant token structures, re-export |
+| Token file valid | Parseable JSON/YAML | Fix syntax errors, validate with JSON Schema |
+
+**Rework rule:** If coverage stuck below 90% after adding manual tokens, review consolidation output — some patterns may have been incorrectly merged.
+
+## Error Handling
+
+- **No consolidation data**: Exit with message to run *consolidate first
+- **Invalid consolidated patterns**: Log which patterns failed, continue with valid ones
+- **Export format error**: Validate syntax, report errors, fix or skip format
+- **Low coverage (<95%)**: Warn user, suggest additional consolidation
+
+## Security Considerations
+
+- Validate color values (hex, rgb, hsl formats only)
+- Sanitize token names (alphanumeric, hyphens, underscores only)
+- Prevent code injection in exported files
+- Validate YAML/JSON syntax before writing
+
+## Examples
+
+### Example 1: Full Token Generation
+
+```bash
+*tokenize
+```
+
+Output:
+```
+🔍 Brad: Extracting tokens from consolidated patterns...
+
+🎨 Color tokens: 12 created
+📏 Spacing tokens: 7 created
+📝 Typography tokens: 10 created
+🔘 Button variant tokens: 3 created
+
+📊 Token Coverage: 96.3% of original patterns
+
+✅ Exported to 5 formats:
+  - tokens.yaml (source of truth)
+  - tokens.json (JavaScript)
+  - tokens.css (CSS custom properties)
+  - tokens.tailwind.js (Tailwind config)
+  - tokens.scss (SCSS variables)
+
+✅ State updated: outputs/design-system/my-app/.state.yaml
+
+Ready for Merovingian to build components or generate migration strategy.
+```
+
+### Example 2: CSS Output Preview
+
+```css
+/* tokens.css */
+:root {
+  /* Colors */
+  --color-primary: #0066CC;
+  --color-primary-dark: #0052A3;
+  --color-error: #DC2626;
+
+  /* Spacing */
+  --space-xs: 4px;
+  --space-sm: 8px;
+  --space-md: 16px;
+
+  /* Typography */
+  --font-base: Inter, system-ui, sans-serif;
+  --font-size-base: 16px;
+  --font-weight-normal: 400;
+}
+```
+
+## Notes
+
+- tokens.yaml is the single source of truth - all exports generated from it
+- Semantic naming > descriptive naming (use "primary" not "blue-500")
+- Hover states auto-detected by "-dark" suffix
+- Coverage <95% means some patterns weren't consolidated
+- Export formats stay in sync - update tokens.yaml and regenerate all
+- Brad recommends: Run *migrate next to create migration strategy
+- For component generation, hand off to Merovingian: *agent atlas
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+