aiox-core 5.0.1 → 5.0.3

package/pro/squads/design/tasks/ds-sync-registry.md

@@ -0,0 +1,287 @@
+# Sync Registry After Component Changes
+
+> Task ID: ds-sync-registry
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> Source: Meeting Insights 2026-02-16 (#7)
+
+## Description
+
+Task obrigatória após qualquer mudança em componentes do design system.
+Garante que todos os artefatos dependentes permanecem sincronizados.
+
+**Princípio:** "Qualquer mudança estrutural requer sync de tudo que ficou ligado."
+
+---
+
+## AI-First Governance Gate (Obrigatório)
+
+Antes de finalizar, executar protocolo:
+- `squads/design/protocols/ai-first-governance.md`
+
+Checklist mínimo:
+- [ ] Validou fontes canônicas (`workspace/system/*`, `workspace/ui/registry.json`, `workspace/domains/design-system/*`)
+- [ ] Classificou cada claim como `Implemented`, `Partially implemented` ou `Concept only`
+- [ ] Não há contradição entre relatório e artefatos reais
+- [ ] Itens não resolvidos foram explicitados
+
+---
+
+## Trigger Conditions
+
+Execute esta task quando:
+
+- [ ] Componente novo criado
+- [ ] Componente existente modificado (props, variants, styles)
+- [ ] Token alterado em `design-tokens-spec.yaml`
+- [ ] Theme modificado
+- [ ] Dependência de componente alterada
+
+---
+
+## Artefatos para Sincronizar
+
+### 1. Registry (Obrigatório)
+
+**Arquivo:** `workspace/ui/registry.json`
+
+```json
+{
+  "name": "[component-name]",
+  "type": "registry:ui",
+  "files": ["path/to/component.tsx"],
+  "dependencies": ["@radix-ui/...", "class-variance-authority"],
+  "registryDependencies": ["button", "..."]
+}
+```
+
+**Ações:**
+- [ ] Adicionar entrada se componente novo
+- [ ] Atualizar `files` se path mudou
+- [ ] Atualizar `dependencies` se imports mudaram
+- [ ] Atualizar `registryDependencies` se composição mudou
+
+### 2. AI Metadata (Obrigatório)
+
+**Arquivo:** `workspace/domains/design-system/metadata/components/[name].json`
+
+```json
+{
+  "name": "Button",
+  "description": "Interactive button component",
+  "props": [...],
+  "variants": [...],
+  "accessibility": {...},
+  "examples": [...]
+}
+```
+
+**Ações:**
+- [ ] Criar metadata se componente novo
+- [ ] Atualizar props se interface mudou
+- [ ] Atualizar variants se adicionou/removeu
+- [ ] Atualizar examples se comportamento mudou
+
+### 3. Storybook (Se existir)
+
+**Arquivo:** `[component].stories.tsx`
+
+**Ações:**
+- [ ] Adicionar story se componente novo
+- [ ] Atualizar stories se props mudaram
+- [ ] Adicionar stories para novas variants
+
+### 4. Documentação (Obrigatório)
+
+**Ações:**
+- [ ] Atualizar CHANGELOG.md com mudança
+- [ ] Atualizar docs se API mudou
+- [ ] Atualizar migration guide se breaking change
+
+### 5. Type Exports (Se TypeScript)
+
+**Arquivo:** `index.ts` do módulo
+
+**Ações:**
+- [ ] Adicionar export se componente novo
+- [ ] Verificar que types são exportados
+
+---
+
+## Workflow
+
+```
+1. IDENTIFICAR MUDANÇA
+   └── Qual componente? Qual tipo de mudança?
+
+2. LISTAR DEPENDENTES
+   └── Quem usa este componente?
+   └── Quais artefatos referenciam?
+
+3. ATUALIZAR ARTEFATOS
+   └── registry.json
+   └── metadata/components/*.json
+   └── *.stories.tsx (se existir)
+   └── CHANGELOG.md
+   └── index.ts exports
+
+4. VALIDAR SYNC
+   └── TypeScript compila?
+   └── Imports resolvem?
+   └── Registry schema válido?
+
+5. DOCUMENTAR
+   └── O que mudou?
+   └── Breaking changes?
+   └── Migration necessária?
+```
+
+---
+
+## Checklist de Validação
+
+### Pre-Sync
+- [ ] Mudança está completa (não parcial)
+- [ ] Testes passam localmente
+- [ ] Sem erros de TypeScript
+
+### Post-Sync
+- [ ] `registry.json` válido (JSON parse OK)
+- [ ] Metadata tem todos campos obrigatórios
+- [ ] Imports funcionam de todos entry points
+- [ ] Changelog atualizado com data e descrição
+
+### Quality Gate
+- [ ] `npm run typecheck` passa
+- [ ] `npm run lint` passa
+- [ ] Nenhum `// @ts-ignore` adicionado
+- [ ] Nenhum hardcoded value (cores, spacing)
+
+---
+
+## Exemplo de Execução
+
+### Cenário: Adicionou variant "loading" ao Button
+
+```markdown
+## Mudança
+- Componente: Button
+- Tipo: Nova variant
+- Arquivos alterados: button.tsx, button.variants.ts
+
+## Sync Executado
+
+### 1. registry.json
+Sem mudança (mesmos files e deps)
+
+### 2. metadata/components/button.json
+```json
+{
+  "variants": [
+    ...existing,
+    {
+      "name": "loading",
+      "description": "Shows spinner, disables interaction",
+      "props": { "isLoading": true }
+    }
+  ]
+}
+```
+
+### 3. button.stories.tsx
+Adicionada story "Loading State"
+
+### 4. CHANGELOG.md
+```
+## [Unreleased]
+### Added
+- Button: variant `loading` com spinner integrado
+```
+
+### 5. Validação
+- [x] typecheck passa
+- [x] lint passa
+- [x] registry válido
+```
+
+---
+
+## Automação Futura
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/design-system-sync.yml
+on:
+  push:
+    paths:
+      - 'workspace/ui/components/**'
+      - 'workspace/system/**'
+
+jobs:
+  validate-sync:
+    steps:
+      - name: Validate registry.json
+        run: npm run validate:registry
+
+      - name: Validate metadata
+        run: npm run validate:metadata
+
+      - name: Check changelog updated
+        run: |
+          if ! git diff --name-only | grep -q "CHANGELOG.md"; then
+            echo "CHANGELOG.md not updated!"
+            exit 1
+          fi
+```
+
+### Pre-commit Hook
+
+```bash
+# .husky/pre-commit
+#!/bin/sh
+npm run validate:registry
+npm run validate:metadata
+```
+
+---
+
+## Deliverables
+
+- [ ] Todos artefatos sincronizados
+- [ ] Changelog atualizado
+- [ ] Validação passou
+- [ ] Commit inclui todos arquivos alterados
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+- `squads/design/checklists/ds-migration-readiness-checklist.md`
+
+## Success Criteria
+
+- [ ] Zero drift entre código e registry
+- [ ] Zero drift entre código e metadata
+- [ ] Changelog reflete todas mudanças
+- [ ] CI/CD passa (quando implementado)
+
+---
+
+## Referências
+
+- Meeting Insights: `docs/research/2026-02-16-ux-writing-governance-ds-ai/meeting-insights-2026-02-16.md`
+- Registry Schema: Shadcn UI registry format
+- Metadata Schema: `squads/design/templates/ds-ai-component-metadata-schema-tmpl.json`
+
+---
+
+*Task criada: 2026-02-16*
+*Squad: Design*
+*Insight Source: #7 Sync Obrigatório Após Mudanças Estruturais*
+
+
+## Process Guards
+- **Execution Type:** `Hybrid`
+- **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `design-system`
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

package/pro/squads/design/tasks/ds-validate-ai-readiness.md

@@ -0,0 +1,69 @@
+# Validate AI-Readiness of Design System
+
+> Task ID: brad-ds-validate-ai-readiness
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+
+## Description
+
+Validate that the design system has all required artifacts for AI agent consumption: metadata, tokens, guidelines, MCP server, and registry.
+
+## Prerequisites
+
+- MCP server exists at `workspace/domains/design-system/mcp/`
+- Metadata exists at `workspace/domains/design-system/metadata/`
+
+## Workflow
+
+1. **Check Metadata Coverage**
+   - Read `metadata/components.json` — verify all registry items have metadata
+   - Read individual component JSONs in `metadata/components/`
+   - Verify each has: id, name, status, a11y contract, variants, tokens
+
+2. **Check Token Registry**
+   - Read `metadata/tokens/index.json`
+   - Verify integrity counts match actual token count
+   - Verify all 3 tiers present (primitive, semantic, component)
+
+3. **Check Guidelines**
+   - Read `metadata/guidelines/usage.json`
+   - Verify each component in metadata has a guideline entry
+   - Verify each guideline has: when_to_use, best_practices, common_mistakes
+
+4. **Check MCP Server**
+   - Verify all handler files exist (components, registry, tokens, guidelines)
+   - Verify config.json lists all tools
+   - Run `node squads/design/scripts/design-system/validate_mcp_skeleton.cjs`
+
+5. **Check Registry**
+   - Run `node squads/design/scripts/design-system/validate_registry.cjs`
+   - Verify registryDependencies resolve
+   - Verify cssVars reference valid tokens
+
+6. **Generate Report**
+   - Score: percentage of checks passing
+   - List gaps with severity (CRITICAL / MEDIUM / LOW)
+   - Recommend next actions
+
+## Deliverables
+
+- AI-Readiness report with score and gap analysis
+- Actionable list of fixes ordered by priority
+
+## Success Criteria
+
+- [ ] 100% of components have metadata, tokens, and guidelines
+- [ ] MCP server passes healthcheck with all 8 tools
+- [ ] Registry validates against Shadcn schema
+- [ ] Overall readiness score >= 90%
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **Execution Type:** `Hybrid`
+- **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `design-system`
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.