aiox-core 5.0.4 → 5.0.5

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

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

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

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