aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/tasks/ds-visual-regression.md

@@ -0,0 +1,130 @@
+# Setup Visual Regression Testing Pipeline
+
+> Task ID: brad-visual-regression
+> Agent: Brad (Design System Architect)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `testing`
+
+## Description
+
+Setup visual regression testing for your design system component library. Compares tooling options (Chromatic, Percy, Playwright, BackstopJS), configures the selected tool, creates baseline screenshots, and integrates with CI. **v4.1: Enriched with Steve Kinney's sustainability-first testing philosophy. Chromatic recommended as primary tool (built by Storybook maintainers). Storybook stories treated as test specs.**
+
+## Prerequisites
+
+- Component library with Storybook (recommended) or standalone demo pages
+- CI/CD pipeline (GitHub Actions, GitLab CI, etc.)
+- Steve Kinney DNA: "DS components ARE the visual contract — visual regression is non-negotiable"
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Collect CI Platform, Budget, and Component Count**
+   - Current CI/CD platform
+   - Budget preference (free/open-source vs. SaaS)
+   - Component count (affects baseline creation time)
+   - Storybook available? (recommended)
+
+2. **Tool Selection**
+   Compare tools using structured trade-off matrix (cost, integration, cross-browser):
+   - **Chromatic** — SaaS, Storybook-native, snapshot diffing (paid, free tier available)
+   - **Percy** — SaaS, framework-agnostic, cross-browser (paid)
+   - **Playwright Screenshots** — Free, code-based, self-hosted
+   - **BackstopJS** — Free, config-based, Docker support
+   - Recommend based on budget and infrastructure
+
+### Steps
+
+1. **Configure Selected Tool**
+   - Install dependencies
+   - Create configuration file
+   - Connect to Storybook (if applicable)
+   - Set viewport sizes (mobile: 375px, tablet: 768px, desktop: 1280px)
+   - Check: tool executes test run with exit code 0 — abort with "Tool configuration failed: {error}"
+
+2. **Create Baseline Screenshots**
+   - Capture all component variants at all viewports
+   - Capture light mode and dark mode (if supported)
+   - Capture interactive states (hover, focus, active, disabled)
+   - Check: screenshot count >= component count AND all files size > 0 — abort with "Missing baselines: {list of components without screenshots}"
+
+3. **Set Threshold Tolerances**
+   - Anti-aliasing tolerance: 0.1% pixel difference
+   - Layout tolerance: 0px (strict)
+   - Color tolerance: 0.5% (account for rendering differences)
+   - Configure per-component overrides if needed
+   - Check: threshold config values set (anti-aliasing <= 0.1%, layout = 0px, color <= 0.5%) — log "Thresholds configured: aa={aa}%, layout={layout}px, color={color}%"
+
+4. **Integrate with CI Pipeline**
+   - Add visual test step to PR pipeline
+   - Configure to run on component file changes only
+   - Set up approval workflow (visual diff review before merge)
+   - Configure artifact storage for screenshots
+   - Check: CI config file contains visual test step AND blocking rule exists — abort with "CI integration incomplete: {missing step or rule}"
+
+5. **Document Workflow**
+   - How to update baselines after intentional changes
+   - How to review visual diffs
+   - How to handle false positives
+   - Update .state.yaml
+
+## Output
+
+- Visual regression tool configured and running
+- Baseline screenshots for all components
+- CI integration with PR blocking on regression
+- `visual-regression-guide.md` — Team workflow documentation
+- `.state.yaml` updated
+
+## Steve Kinney Testing Philosophy (v4.1)
+
+### Sustainability Filter
+For every visual test, ask: "Would a busy developer maintain this test?"
+- If test breaks on every refactor → scope too broad
+- If nobody reviews diffs → test is noise, not signal
+
+### Storybook-as-Testing-Platform
+Each Storybook story serves 5 purposes simultaneously:
+1. **Documentation** — Shows component state
+2. **Development** — Isolated dev environment
+3. **Visual Testing** — Chromatic screenshot baseline
+4. **Interaction Testing** — Play functions simulate user actions
+5. **Accessibility Testing** — a11y addon runs axe-core
+
+### Tool Recommendation Priority (Steve Kinney)
+1. **Chromatic** (recommended) — Built by Storybook maintainers, best integration, human review UI
+2. **Playwright Screenshots** — Free, good for non-Storybook or cross-page testing
+3. **Percy/BackstopJS** — Alternatives with different trade-offs
+
+### Visual Diff Review Process
+- **NEVER auto-approve visual changes** — humans must review
+- Intentional change → approve new baseline
+- Unintentional change → fix the regression
+- Batch-approving without reviewing defeats the purpose
+
+## Failure Handling
+
+- **Selected tool installation fails:** Try alternate package manager (npm/yarn/pnpm). If all fail, recommend manual installation with error log
+- **Baseline screenshot capture fails:** Check Storybook is running and accessible. Retry with increased timeout. If persistent, capture subset and document failures
+- **CI pipeline configuration file not found:** Detect CI platform from repo files (.github/, .gitlab-ci.yml). If none found, generate standalone config for GitHub Actions as default
+- **Visual diff threshold too sensitive (>20% false positives):** Increase anti-aliasing tolerance to 0.2%, add per-component overrides for animated components
+
+## Success Criteria
+
+- All component variants have baseline screenshots
+- CI blocks PRs with unreviewed visual changes
+- False positive rate < 5%
+- Baseline update process documented
+- Storybook stories cover all visual states (each story = test spec)
+- Play functions added for interactive components
+- Sustainability filter applied: no tests a busy developer wouldn't maintain
+
+
+## Related Checklists
+
+- `squads/design/checklists/design-fidelity-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/execute-checklist.md

@@ -0,0 +1,141 @@
+# Checklist Validation Task
+
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `standalone`
+
+This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
+
+## Available Checklists
+
+If the user asks or does not specify a specific checklist, list the checklists available in `squads/design/checklists/`.
+
+## Local Checklist Catalog (`squads/design/checklists/`)
+
+- `atomic-refactor-checklist.md`
+- `design-fidelity-checklist.md`
+- `design-handoff-checklist.md`
+- `design-team-health-checklist.md`
+- `designops-maturity-checklist.md`
+- `ds-a11y-release-gate-checklist.md`
+- `ds-accessibility-wcag-checklist.md`
+- `ds-component-quality-checklist.md`
+- `ds-migration-readiness-checklist.md`
+- `ds-pattern-audit-checklist.md`
+- `reading-accessibility-checklist.md`
+
+## Instructions
+
+1. **Initial Assessment**
+
+   - If user or the task being run provides a checklist name:
+     - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
+     - If multiple matches found, ask user to clarify
+     - Load the appropriate checklist from `squads/design/checklists/`
+   - If no checklist specified:
+     - Ask the user which checklist they want to use
+     - Present the available options from `squads/design/checklists/`
+   - Confirm if they want to work through the checklist:
+     - Section by section (interactive mode - very time consuming)
+     - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
+
+2. **Document and Artifact Gathering**
+
+   - Each checklist will specify its required documents/artifacts at the beginning
+   - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
+
+3. **Checklist Processing**
+
+   If in interactive mode:
+
+   - Work through each section of the checklist one at a time
+   - For each section:
+     - Review all items in the section following instructions for that section embedded in the checklist
+     - Check each item against the relevant documentation or artifacts as appropriate
+     - Present summary of findings for that section, highlighting warnings, errors and non applicable items (rationale for non-applicability).
+     - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
+
+   If in YOLO mode:
+
+   - Process all sections at once
+   - Create a comprehensive report of all findings
+   - Present the complete analysis to the user
+
+4. **Validation Approach**
+
+   For each checklist item:
+
+   - Read and understand the requirement
+   - Look for evidence in the documentation that satisfies the requirement
+   - Consider both explicit mentions and implicit coverage
+   - Aside from this, follow all checklist llm instructions
+   - Mark items as:
+     - ✅ PASS: Requirement clearly met
+     - ❌ FAIL: Requirement not met or insufficient coverage
+     - ⚠️ PARTIAL: Some aspects covered but needs improvement
+     - N/A: Not applicable to this case
+
+5. **Section Analysis**
+
+   For each section:
+
+   - think step by step to calculate pass rate
+   - Identify common themes in failed items
+   - Provide specific recommendations for improvement
+   - In interactive mode, discuss findings with user
+   - Document any user decisions or explanations
+
+6. **Final Report**
+
+   Prepare a summary that includes:
+
+   - Overall checklist completion status
+   - Pass rates by section
+   - List of failed items with context
+   - Specific recommendations for improvement
+   - Any sections or items marked as N/A with justification
+
+## Checklist Execution Methodology
+
+Each checklist now contains embedded LLM prompts and instructions that will:
+
+1. **Guide thorough thinking** - Prompts ensure deep analysis of each section
+2. **Request specific artifacts** - Clear instructions on what documents/access is needed
+3. **Provide contextual guidance** - Section-specific prompts for better validation
+4. **Generate comprehensive reports** - Final summary with detailed findings
+
+The LLM will:
+
+- Execute the complete checklist validation
+- Present a final report with pass/fail rates and key findings
+- Offer to provide detailed analysis of any section, especially those with warnings or failures
+
+## Failure Handling
+
+- **Multiple checklists match user query:** Present disambiguation list with each checklist's primary purpose, ask user to select by number or refine query
+- **Required documentation artifacts missing or inaccessible:** Flag missing items, proceed with partial validation marking dependent checklist items as BLOCKED, document gaps in final report
+- **Checklist scoring results in ambiguous pass/fail boundary:** Calculate confidence intervals, highlight borderline items, recommend manual review for items within 10% of threshold
+- **User disagrees with automated verdict for specific items:** Document user override with justification, recalculate section scores excluding overridden items, append dissenting analysis to report
+
+## Success Criteria
+
+- [ ] Correct checklist identified and loaded (exact or fuzzy match)
+- [ ] All required documents/artifacts gathered before validation
+- [ ] Every checklist item evaluated with PASS/FAIL/N-A verdict
+- [ ] Non-applicable items include rationale for exclusion
+- [ ] Summary report generated with section-by-section breakdown
+- [ ] Scoring calculated per checklist's scoring system
+- [ ] Critical failures flagged for immediate attention
+
+## Output
+
+- Checklist execution report with section pass rates
+- List of failed/partial items with evidence
+- Remediation list prioritized by severity
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/export-design-tokens-dtcg.md

@@ -0,0 +1,97 @@
+# Export Design Tokens to W3C DTCG
+
+> Task ID: brad-export-design-tokens-dtcg
+> Agent: Brad (Design System Architect)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Worker`
+> **Dependencies:** depends_on: `[]` · enables: `[ds-token-w3c-extract]` · workflow: `tokens`
+
+## Description
+
+Produce W3C Design Tokens (DTCG v1.0.0 stable) exports from the canonical YAML tokens file. Validates schema compliance, OKLCH color usage, and publishes artifacts for downstream platforms (web, iOS, Android, Flutter). **v4.0: References w3c-dtcg-spec-reference.md for spec compliance. Uses $value, $type, $description format per W3C DTCG v1.0 stable (October 2025).**
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/tokens/dtcg-exports/`
+- **format:** JSON data (W3C DTCG v1.0 multi-platform)
+- **consumed_by:** ds-token-w3c-extract
+
+## Prerequisites
+
+- tokens.yaml generated via *tokenize (core/semantic/component layers present)
+- Node.js ≥ 18 / Python ≥ 3.10 (for validation tools)
+- DTCG CLI or schema validator installed (`npm install -g @designtokens/cli` recommended)
+- Reference: Read data/w3c-dtcg-spec-reference.md for W3C DTCG v1.0 stable format
+
+## Workflow
+
+1. **Load Source Tokens**
+   - Read `tokens.yaml` and confirm metadata (dtcg_spec, color_space)
+   - Ensure layers exist: `core`, `semantic`, `component`
+   - Verify coverage >95% stored in `.state.yaml`
+
+2. **Generate DTCG JSON**
+   - Transform YAML into DTCG JSON structure
+   - Ensure each token includes `$type`, `$value`, optional `$description`
+   - Map references using `{layers.semantic.color.primary}` style
+   - Save as `tokens.dtcg.json`
+
+3. **Produce Platform Bundles (Optional)**
+   - Run Style Dictionary / custom scripts for platform-specific outputs
+   - Targets: web (CSS), Android (XML), iOS (Swift), Flutter (Dart)
+   - Store under `tokens/exports/{platform}/`
+
+4. **Validate**
+   - `dtcg validate tokens.dtcg.json`
+   - Lint OKLCH values (ensure `oklch()` format, fallback to hex flagged)
+   - Confirm references resolve (no missing paths)
+
+5. **Document & Publish**
+   - Update `docs/tokens/README.md` with export details, version, changelog
+   - Attach validator output and coverage metrics
+   - Update `.state.yaml` (tokens.dtcg path, validator status, timestamp)
+
+## Output
+
+- `tokens.dtcg.json` (W3C compliant)
+- Optional platform bundles (CSS, Android XML, Swift, Flutter)
+- Validation report (`tokens/validation/dtcg-report.json`)
+- Updated `.state.yaml` tokens section
+
+## Failure Handling
+
+- **W3C validator fails with schema errors:** Isolate offending tokens, generate compliant subset for immediate use, quarantine invalid tokens to separate file with validation error annotations
+- **Token reference resolution breaks due to circular dependencies:** Detect cycle path, break loop by inlining deepest reference, log resolution strategy and affected tokens in validation report
+- **Platform export tool crashes on unsupported token types:** Skip incompatible token types for that platform, document exclusions in platform-specific README, generate warning manifest listing unsupported features
+- **OKLCH color conversion produces out-of-gamut RGB values:** Clamp to sRGB gamut with perceptual lightness preservation, append fallback hex values as `$extensions`, flag colors requiring manual adjustment
+
+## Success Criteria
+
+- [ ] tokens.dtcg.json passes W3C validator with zero errors
+- [ ] OKLCH color space used; fallbacks documented
+- [ ] References (`$value`) resolve across layers
+- [ ] Platform exports updated (if enabled) and smoke-tested
+- [ ] Documentation + changelog refreshed with version/date
+- [ ] `.state.yaml` reflects dtcg export path and status
+
+## Error Handling
+
+- **Invalid schema**: Capture validator output, fix offending tokens, rerun export
+- **Missing reference**: Trace YAML source, ensure token exists or adjust alias
+- **Unsupported color format**: Convert to OKLCH or fallback with explanation
+- **Platform export failure**: Roll back platform-specific step, flag follow-up action
+
+## Notes
+
+- Keep token versions semantically versioned (e.g., 1.1.0 for new tokens)
+- Coordinate with platform teams before breaking changes (e.g., renaming tokens)
+- Store validation reports alongside artifacts for audit/compliance
+
+
+## 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/f1-apply-foundations.md

@@ -0,0 +1,154 @@
+# f1-apply-foundations
+
+> **Phase 1, Step 3** — Aplicar tokens mapeados no globals.css e @theme inline.
+
+## Metadata
+
+```yaml
+task:
+  id: f1-apply-foundations
+  phase: 1
+  step: 3
+  agent: ds-foundations-lead
+  depends_on: f1-map-tokens-to-shadcn
+  blocking: false
+  next: f1-qa-foundations
+```
+
+## Objetivo
+
+Editar `app/app/globals.css` para substituir os tokens default do shadcn pelos tokens mapeados do Figma, mantendo a estrutura do arquivo intacta.
+
+## Target File
+
+`app/app/globals.css`
+
+## Estrutura Atual do globals.css
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  /* Tailwind bridge: --color-{name}: var(--{name}) */
+  /* Radius scale: --radius-{size}: calc(var(--radius) ± offset) */
+}
+
+:root {
+  /* Light mode tokens in OKLch */
+}
+
+.dark {
+  /* Dark mode tokens in OKLch */
+}
+
+@layer base {
+  * { @apply border-border outline-ring/50; }
+  body { @apply bg-background text-foreground; }
+}
+```
+
+## Execution Steps
+
+### Step 1: Substituir Valores em `:root`
+
+Para cada token mapeado, substituir o valor OKLch:
+
+```css
+:root {
+  --radius: 0.625rem;          /* Usar valor do Figma se fornecido */
+  --background: oklch(...);     /* Novo valor do Figma */
+  --foreground: oklch(...);     /* Novo valor do Figma */
+  /* ... todos os 18 core tokens ... */
+  /* ... 5 chart tokens ... */
+  /* ... 8 sidebar tokens ... */
+}
+```
+
+### Step 2: Substituir Valores em `.dark`
+
+Para cada token mapeado com valor dark:
+
+```css
+.dark {
+  --background: oklch(...);     /* Novo valor dark do Figma */
+  --foreground: oklch(...);     /* Novo valor dark do Figma */
+  /* ... todos os tokens com valores dark ... */
+}
+```
+
+### Step 3: Adicionar Extensoes no @theme inline
+
+Se o Figma define tokens extras (warning, info, success, etc.):
+
+```css
+@theme inline {
+  /* Existing bridges */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  /* ... existentes ... */
+
+  /* Extensions from Figma DS */
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+}
+```
+
+E adicionar os valores em `:root` e `.dark`:
+
+```css
+:root {
+  /* ... core tokens ... */
+  --warning: oklch(...);
+  --warning-foreground: oklch(...);
+  --info: oklch(...);
+  --info-foreground: oklch(...);
+  --success: oklch(...);
+  --success-foreground: oklch(...);
+}
+```
+
+### Step 4: Preservar Estrutura
+
+**NAO alterar:**
+- Imports (`@import`)
+- `@custom-variant dark`
+- `@layer base` block
+- Ordem das sections
+
+**Manter se Figma nao fornecer:**
+- Chart tokens (--chart-1 through --chart-5) — usar defaults
+- Sidebar tokens — derivar de core tokens se nao fornecido:
+  - `--sidebar: var(--background)` pattern
+
+### Step 5: Validar Sintaxe
+
+Verificar que o CSS resultante e valido:
+- Todos os valores OKLch tem formato correto: `oklch(L C H)` ou `oklch(L C H / alpha)`
+- Todas as variaveis referenciadas existem
+- Nenhuma variavel duplicada
+- Nenhuma variavel do shadcn original foi removida sem substituto
+
+## Regras Criticas
+
+1. **NUNCA remover uma variavel** que os 56 componentes shadcn possam referenciar
+2. **SEMPRE usar OKLch** para valores de cor
+3. **MANTER a ordem** das sections no arquivo
+4. **NAO adicionar** CSS custom (classes, resets, etc.) — apenas variaveis
+5. **Extensoes** devem ter bridge em `@theme inline` para funcionar com Tailwind
+
+## Output
+
+- `app/app/globals.css` modificado com novos tokens
+- Log de mudancas: quais tokens foram substituidos, quais adicionados, quais mantidos
+
+## Related Checklists
+
+- `squads/design/checklists/token-mapping-checklist.md`

package/pro/squads/design/tasks/f1-ingest-figma-tokens.md

@@ -0,0 +1,130 @@
+# f1-ingest-figma-tokens
+
+> **Phase 1, Step 1** — Receber e normalizar tokens do Figma para estrutura intermediaria.
+
+## Metadata
+
+```yaml
+task:
+  id: f1-ingest-figma-tokens
+  phase: 1
+  step: 1
+  agent: ds-foundations-lead
+  delegates_to: ds-token-architect
+  blocking: false
+  next: f1-map-tokens-to-shadcn
+```
+
+## Objetivo
+
+Receber tokens do usuario em qualquer formato suportado e normalizar para uma estrutura JSON intermediaria categorizada.
+
+## Formatos de Input Aceitos
+
+1. **CSS do Dev Mode** — Copy-paste de variaveis CSS do Figma Dev Mode
+2. **JSON export** — Tokens Studio ou Figma Variables API export
+3. **Texto manual** — Lista `nome: valor` fornecida pelo usuario
+4. **Screenshots** — Com validacao humana obrigatoria (marcar valores incertos como `NEEDS_CONFIRMATION`)
+
+## Execution Steps
+
+### Step 1: Solicitar Input
+
+Pergunte ao usuario:
+
+```
+Qual formato voce vai usar para os tokens?
+1. CSS do Figma Dev Mode (copy-paste)
+2. JSON export (Tokens Studio / Variables API)
+3. Lista manual (nome: valor)
+4. Screenshot (precisa validacao manual)
+
+Cole os tokens aqui:
+```
+
+### Step 2: Parse Input
+
+Para cada formato:
+
+- **CSS**: Extrair pares `--nome: valor` de blocos `:root` e `.dark`/`[data-theme]`
+- **JSON**: Extrair tokens respeitando hierarquia de grupos
+- **Manual**: Parsear linhas `nome: valor` ou `nome = valor`
+- **Screenshot**: Solicitar que o usuario confirme cada valor extraido
+
+### Step 3: Categorizar
+
+Organizar tokens nas categorias:
+
+| Categoria | Exemplos |
+|-----------|----------|
+| `color` | Paletas, semanticos, brand colors |
+| `spacing` | Gaps, paddings, margins |
+| `typography` | Font family, size, weight, line-height, letter-spacing |
+| `radius` | Border radius values |
+| `shadow` | Box shadows, drop shadows |
+| `opacity` | Alpha values |
+| `motion` | Duration, easing (se fornecido) |
+
+### Step 4: Identificar Modos
+
+- Detectar se existem modos (light/dark, brand themes)
+- Se apenas um conjunto de valores: assumir `default` mode
+- Se dois conjuntos (claro/escuro): mapear como `default` e `dark`
+
+### Step 5: Normalizar Output
+
+Gerar JSON intermediario:
+
+```json
+{
+  "meta": {
+    "source": "figma-dev-mode",
+    "inputFormat": "css",
+    "timestamp": "2026-02-21T...",
+    "modes": ["default", "dark"]
+  },
+  "tokens": {
+    "color": {
+      "primitives": {
+        "blue-500": { "value": "#3B82F6", "type": "color" }
+      },
+      "semantic": {
+        "primary": { "value": "{color.primitives.blue-500}", "type": "color" },
+        "primary-foreground": { "value": "#FFFFFF", "type": "color" }
+      }
+    },
+    "spacing": {},
+    "typography": {},
+    "radius": {},
+    "shadow": {}
+  },
+  "dark": {
+    "color": {
+      "semantic": {
+        "primary": { "value": "{color.primitives.blue-400}", "type": "color" }
+      }
+    }
+  }
+}
+```
+
+## Validacao
+
+- [ ] Pelo menos uma categoria de token tem valores
+- [ ] Valores de cor sao validos (hex, rgb, hsl, oklch)
+- [ ] Nenhum valor vazio ou placeholder
+- [ ] Modos identificados corretamente
+- [ ] Screenshots tem confirmacao humana
+
+## Output
+
+- Estrutura JSON normalizada (em memoria ou `squads/design/data/tokens-normalized.json`)
+- Report de tokens recebidos por categoria
+
+## Referencia
+
+- IO contract de `@ds-token-architect`: `squads/design/agents/ds-token-architect.md` → `io_contract.inputs.accepted_formats`
+
+## Related Checklists
+
+- `squads/design/checklists/token-mapping-checklist.md`