@ux-design-expert (Uma)

UX/UI Design e Design Systems

16 min de leitura
agenteuxdesign

Sistema UX-Design-Expert AIOX

Versão: 1.0.0 Criado: 2026-02-04 Owner: @ux-design-expert (Uma) Status: Documentação Oficial

Visão Geral

Este documento descreve o sistema completo do agente UX-Design Expert (Uma), incluindo todos os arquivos envolvidos, fluxos de trabalho, comandos disponiveis, integracoes com outros agentes e workflows AIOX.

O UX-Design Expert e um agente hibrido que combina:

  • Sally's UX Principles - Empatia, pesquisa de usuario, design centrado no usuario
  • Brad Frost's System Principles - Atomic Design, design tokens, metricas e ROI

Propósito

O agente e projetado para:

  • Conduzir pesquisa de usuario e criar personas
  • Criar wireframes e fluxos de interacao
  • Auditar codebases existentes para identificar redundancias de UI
  • Extrair e consolidar design tokens
  • Construir componentes atomicos (atoms, molecules, organisms)
  • Garantir acessibilidade (WCAG AA/AAA)
  • Calcular ROI e savings de design systems

Arquitetura de 5 Fases

O UX-Design Expert opera em 5 fases distintas, cada uma com comandos especificos:

flowchart TB
    subgraph PHASE1["Fase 1: UX Research"]
        R1["*research<br/>Pesquisa de Usuario"]
        R2["*wireframe<br/>Criar Wireframes"]
        R3["*generate-ui-prompt<br/>Prompts para v0/Lovable"]
        R4["*create-front-end-spec<br/>Especificacao Frontend"]
    end

    subgraph PHASE2["Fase 2: Design System Audit"]
        A1["*audit {path}<br/>Escanear Redundancias"]
        A2["*consolidate<br/>Clustering Inteligente"]
        A3["*shock-report<br/>Relatorio Visual HTML"]
    end

    subgraph PHASE3["Fase 3: Design Tokens"]
        T1["*tokenize<br/>Extrair Tokens"]
        T2["*setup<br/>Inicializar DS"]
        T3["*migrate<br/>Estrategia de Migracao"]
        T4["*upgrade-tailwind<br/>Upgrade Tailwind v4"]
        T5["*bootstrap-shadcn<br/>Instalar Shadcn/Radix"]
    end

    subgraph PHASE4["Fase 4: Component Building"]
        B1["*build {component}<br/>Construir Atom"]
        B2["*compose {molecule}<br/>Compor Molecule"]
        B3["*extend {component}<br/>Adicionar Variante"]
    end

    subgraph PHASE5["Fase 5: Quality & Documentation"]
        Q1["*document<br/>Pattern Library"]
        Q2["*a11y-check<br/>Auditoria WCAG"]
        Q3["*calculate-roi<br/>Calcular ROI"]
    end

    PHASE1 --> PHASE2
    PHASE2 --> PHASE3
    PHASE3 --> PHASE4
    PHASE4 --> PHASE5

    style PHASE1 fill:#e3f2fd
    style PHASE2 fill:#fff3e0
    style PHASE3 fill:#e8f5e9
    style PHASE4 fill:#fce4ec
    style PHASE5 fill:#f3e5f5

Lista Completa de Arquivos

Arquivo de Definição do Agente

| Arquivo | Propósito | |---------|-----------| | .aiox-core/development/agents/ux-design-expert.md | Definição completa do agente (persona, comandos, workflows) | | .claude/commands/AIOX/agents/ux-design-expert.md | Comando Claude Code para ativar @ux-design-expert |

Tasks por Fase

Fase 1: UX Research & Design (4 tasks)

| Arquivo | Comando | Propósito | |---------|---------|-----------| | .aiox-core/development/tasks/ux-user-research.md | *research | Conduzir pesquisa de usuario, criar personas e jornadas | | .aiox-core/development/tasks/ux-create-wireframe.md | *wireframe | Criar wireframes low/mid/high fidelity | | .aiox-core/development/tasks/generate-ai-frontend-prompt.md | *generate-ui-prompt | Gerar prompts para v0.dev, Lovable.ai | | .aiox-core/development/tasks/create-doc.md | *create-front-end-spec | Criar especificacao frontend detalhada |

Fase 2: Design System Audit (3 tasks)

| Arquivo | Comando | Propósito | |---------|---------|-----------| | .aiox-core/development/tasks/audit-codebase.md | *audit {path} | Escanear codebase para redundancias UI | | .aiox-core/development/tasks/consolidate-patterns.md | *consolidate | Reduzir redundancia com clustering HSL | | .aiox-core/development/tasks/generate-shock-report.md | *shock-report | Gerar relatorio visual HTML |

Fase 3: Design Tokens & Setup (7 tasks)

| Arquivo | Comando | Propósito | |---------|---------|-----------| | .aiox-core/development/tasks/extract-tokens.md | *tokenize | Extrair design tokens (YAML, JSON, CSS, DTCG) | | .aiox-core/development/tasks/setup-design-system.md | *setup | Inicializar estrutura do design system | | .aiox-core/development/tasks/generate-migration-strategy.md | *migrate | Gerar estrategia de migracao em 4 fases | | .aiox-core/development/tasks/tailwind-upgrade.md | *upgrade-tailwind | Upgrade para Tailwind CSS v4 | | .aiox-core/development/tasks/audit-tailwind-config.md | *audit-tailwind-config | Validar configuracao Tailwind | | .aiox-core/development/tasks/export-design-tokens-dtcg.md | *export-dtcg | Exportar tokens W3C DTCG | | .aiox-core/development/tasks/bootstrap-shadcn-library.md | *bootstrap-shadcn | Instalar Shadcn/Radix UI |

Fase 4: Atomic Component Building (3 tasks)

| Arquivo | Comando | Propósito | |---------|---------|-----------| | .aiox-core/development/tasks/build-component.md | *build {component} | Construir componente atomico (React + TypeScript) | | .aiox-core/development/tasks/compose-molecule.md | *compose {molecule} | Compor molecule de atoms existentes | | .aiox-core/development/tasks/extend-pattern.md | *extend {component} | Adicionar variante a componente existente |

Fase 5: Quality & Documentation (3 tasks)

| Arquivo | Comando | Propósito | |---------|---------|-----------| | .aiox-core/development/tasks/generate-documentation.md | *document | Gerar documentacao do pattern library | | .aiox-core/development/tasks/calculate-roi.md | *calculate-roi | Calcular ROI e cost savings | | .aiox-core/development/checklists/accessibility-wcag-checklist.md | *a11y-check | Auditoria de acessibilidade WCAG |

Tasks Universais (2 tasks)

| Arquivo | Comando | Propósito | |---------|---------|-----------| | .aiox-core/development/tasks/ux-ds-scan-artifact.md | *scan {path\|url} | Analisar HTML/React para extrair padroes | | .aiox-core/development/tasks/integrate-Squad.md | *integrate {squad} | Conectar com expansion squad |

Templates

| Arquivo | Propósito | |---------|-----------| | .aiox-core/development/templates/front-end-spec-tmpl.yaml | Template de especificacao frontend | | .aiox-core/development/templates/tokens-schema-tmpl.yaml | Schema de design tokens | | .aiox-core/development/templates/component-react-tmpl.tsx | Template de componente React | | .aiox-core/development/templates/state-persistence-tmpl.yaml | Template de persistencia de estado | | .aiox-core/development/templates/shock-report-tmpl.html | Template de shock report HTML | | .aiox-core/development/templates/migration-strategy-tmpl.md | Template de estrategia de migracao | | .aiox-core/development/templates/token-exports-css-tmpl.css | Template de export CSS | | .aiox-core/development/templates/token-exports-tailwind-tmpl.js | Template de export Tailwind | | .aiox-core/development/templates/ds-artifact-analysis.md | Template de analise de artefato |

Checklists

| Arquivo | Propósito | |---------|-----------| | .aiox-core/development/checklists/pattern-audit-checklist.md | Checklist de auditoria de padroes | | .aiox-core/development/checklists/component-quality-checklist.md | Checklist de qualidade de componente | | .aiox-core/development/checklists/accessibility-wcag-checklist.md | Checklist WCAG AA/AAA | | .aiox-core/development/checklists/migration-readiness-checklist.md | Checklist de readiness para migracao |

Data Files

| Arquivo | Propósito | |---------|-----------| | .aiox-core/development/data/technical-preferences.md | Preferencias tecnicas padrao | | .aiox-core/development/data/atomic-design-principles.md | Principios Atomic Design | | .aiox-core/development/data/design-token-best-practices.md | Best practices de design tokens | | .aiox-core/development/data/consolidation-algorithms.md | Algoritmos de consolidacao | | .aiox-core/development/data/roi-calculation-guide.md | Guia de calculo de ROI | | .aiox-core/development/data/integration-patterns.md | Padroes de integracao | | .aiox-core/development/data/wcag-compliance-guide.md | Guia de conformidade WCAG |

Workflows Relacionados

| Arquivo | Propósito | |---------|-----------| | .aiox-core/development/workflows/design-system-build-quality.yaml | Pipeline pos-migracao (build, docs, a11y, ROI) | | .aiox-core/development/workflows/brownfield-ui.yaml | Workflow para UI brownfield | | .aiox-core/development/workflows/brownfield-discovery.yaml | Discovery para projetos existentes | | .aiox-core/development/workflows/greenfield-ui.yaml | Workflow para UI greenfield |

Arquivos de Output

| Arquivo | Propósito | |---------|-----------| | outputs/ux-research/{project}/ | Outputs de pesquisa UX | | outputs/wireframes/{project}/ | Wireframes e flows | | outputs/design-system/{project}/ | Design system outputs | | outputs/design-system/{project}/.state.yaml | Estado do workflow |

Flowchart: Workflow Completo (UX to Build)

flowchart TB
    subgraph START["Inicio"]
        ACTIVATE["@ux-design-expert"]
    end

    ACTIVATE --> CHECK{"Tipo de<br/>Projeto?"}

    CHECK -->|Greenfield| GF["Workflow Greenfield"]
    CHECK -->|Brownfield| BF["Workflow Brownfield"]
    CHECK -->|Complete| COMPLETE["Workflow Completo"]

    subgraph GF["GREENFIELD (Novo Projeto)"]
        GF1["*research<br/>Pesquisa de Usuario"]
        GF2["*wireframe<br/>Criar Wireframes"]
        GF3["*setup<br/>Inicializar DS"]
        GF4["*build button<br/>Construir Atoms"]
        GF5["*compose form-field<br/>Compor Molecules"]
        GF6["*document<br/>Documentar"]

        GF1 --> GF2 --> GF3 --> GF4 --> GF5 --> GF6
    end

    subgraph BF["BROWNFIELD (Projeto Existente)"]
        BF1["*audit ./src<br/>Escanear Codebase"]
        BF2["*consolidate<br/>Consolidar Padroes"]
        BF3["*tokenize<br/>Extrair Tokens"]
        BF4["*migrate<br/>Estrategia Migracao"]
        BF5["*build button<br/>Construir Componentes"]
        BF6["*document<br/>Documentar"]

        BF1 --> BF2 --> BF3 --> BF4 --> BF5 --> BF6
    end

    subgraph COMPLETE["COMPLETE (5 Fases)"]
        C1["Fase 1: UX Research<br/>*research, *wireframe"]
        C2["Fase 2: Audit<br/>*audit, *consolidate, *shock-report"]
        C3["Fase 3: Tokens<br/>*tokenize, *setup, *migrate"]
        C4["Fase 4: Build<br/>*build, *compose, *extend"]
        C5["Fase 5: Quality<br/>*document, *a11y-check, *calculate-roi"]

        C1 --> C2 --> C3 --> C4 --> C5
    end

    GF --> DONE["Design System Pronto!"]
    BF --> DONE
    COMPLETE --> DONE

    style START fill:#e1f5fe
    style GF fill:#e8f5e9
    style BF fill:#fff3e0
    style COMPLETE fill:#f3e5f5
    style DONE fill:#c8e6c9

Flowchart: Workflow de Auditoria Brownfield

flowchart TB
    A["*audit ./src<br/>Escanear Codebase"] --> B{"Padroes<br/>Encontrados?"}

    B -->|Sim| C["Inventario de Padroes<br/>- 47 button variants<br/>- 89 cores unicas<br/>- 19 spacing values"]
    B -->|Nao| Z["Codebase ja limpo<br/>Pular para *setup"]

    C --> D["*consolidate<br/>Clustering HSL 5%"]

    D --> E{"Reducao<br/>>80%?"}

    E -->|Sim| F["47 buttons → 3 variants<br/>89 colors → 12 tokens<br/>19 spacing → 7 tokens"]
    E -->|Nao| G["Revisar manualmente<br/>Ajustar threshold"]

    G --> D

    F --> H["*shock-report<br/>Gerar Relatorio HTML"]

    H --> I["Visual Chaos Report<br/>- Side-by-side comparisons<br/>- Redundancy metrics<br/>- ROI preview"]

    I --> J["*tokenize<br/>Extrair Tokens"]

    J --> K["tokens.yaml<br/>tokens.json<br/>tokens.css<br/>tokens.tailwind.js"]

    K --> L["*calculate-roi<br/>Calcular Savings"]

    L --> M["ROI Report<br/>- Annual savings: $374k<br/>- ROI: 34.6x<br/>- Breakeven: 10 dias"]

    style A fill:#fff3e0
    style D fill:#e3f2fd
    style H fill:#fce4ec
    style J fill:#e8f5e9
    style L fill:#f3e5f5
    style M fill:#c8e6c9

Flowchart: Build de Componente Atomico

flowchart TB
    A["*build button<br/>Build Component"] --> B["Validar Pre-requisitos<br/>- Tokens carregados<br/>- Componente não existe"]

    B --> C["Carregar Referencias de Token<br/>- color tokens<br/>- spacing tokens<br/>- typography tokens"]

    C --> D["Gerar Componente TSX<br/>- React.forwardRef<br/>- Radix Slot<br/>- cva variants"]

    D --> E["Gerar Variantes cva<br/>- primary, secondary, outline<br/>- sm, md, lg, icon<br/>- loading state"]

    E --> F["Gerar Testes<br/>- RTL + jest-axe<br/>- Snapshot tests<br/>- >85% coverage"]

    F --> G{"Storybook<br/>Habilitado?"}

    G -->|Sim| H["Gerar Stories<br/>- CSF format<br/>- Controls<br/>- Docs tab"]
    G -->|Nao| I["Skip Stories"]

    H --> J["Accessibility Check<br/>- WCAG 2.2 AA<br/>- APCA contrast<br/>- Keyboard navigation"]
    I --> J

    J --> K{"a11y<br/>Aprovado?"}

    K -->|Sim| L["Gerar Documentação<br/>- Props table<br/>- Usage examples<br/>- Theming guide"]
    K -->|Nao| M["Remediar Violacoes<br/>- Add ARIA labels<br/>- Fix contrast<br/>- Add focus styles"]

    M --> J

    L --> N["Atualizar Index<br/>- Export component<br/>- Update barrel"]

    N --> O["Atualizar State<br/>- patterns_built[]<br/>- atomic_level<br/>- test_coverage"]

    O --> P["Componente Pronto!<br/>import { Button } from '@/components/ui/button'"]

    style A fill:#e3f2fd
    style D fill:#e8f5e9
    style F fill:#fff3e0
    style J fill:#fce4ec
    style P fill:#c8e6c9

Mapeamento de Comandos para Tasks

Fase 1: UX Research & Design

| Comando | Task File | Entrada | Saida | |---------|-----------|---------|-------| | *research | ux-user-research.md | Objetivos, metodos | personas.md, user-journeys.md, insights.md | | *wireframe {fidelity} | ux-create-wireframe.md | Screens, use case | wireframes/, flows.md, component-inventory.md | | *generate-ui-prompt | generate-ai-frontend-prompt.md | front-end-spec.md | AI prompts for v0/Lovable | | *create-front-end-spec | create-doc.md | PRD, wireframes | front-end-spec.md |

Fase 2: Design System Audit

| Comando | Task File | Entrada | Saida | |---------|-----------|---------|-------| | *audit {path} | audit-codebase.md | Scan path | pattern-inventory.json, .state.yaml | | *consolidate | consolidate-patterns.md | Audit results | consolidation-report.md, pattern-mapping.json | | *shock-report | generate-shock-report.md | Consolidation | shock-report.html |

Fase 3: Design Tokens & Setup

| Comando | Task File | Entrada | Saida | |---------|-----------|---------|-------| | *tokenize | extract-tokens.md | Consolidation | tokens.yaml, tokens.json, tokens.css | | *setup | setup-design-system.md | Tokens | components/, lib/, docs/ | | *migrate | generate-migration-strategy.md | Tokens | migration-strategy.md (4 phases) | | *upgrade-tailwind | tailwind-upgrade.md | Config | tailwind.config.ts (v4) | | *audit-tailwind-config | audit-tailwind-config.md | Config | audit-report.md | | *export-dtcg | export-design-tokens-dtcg.md | tokens.yaml | tokens.dtcg.json (W3C) | | *bootstrap-shadcn | bootstrap-shadcn-library.md | Project | Shadcn components |

Fase 4: Atomic Component Building

| Comando | Task File | Entrada | Saida | |---------|-----------|---------|-------| | *build {component} | build-component.md | Name, variants | Component.tsx, tests, stories, docs | | *compose {molecule} | compose-molecule.md | Atom deps | Molecule.tsx, tests | | *extend {component} | extend-pattern.md | Component, variant | Updated component + tests |

Fase 5: Quality & Documentation

| Comando | Task File | Entrada | Saida | |---------|-----------|---------|-------| | *document | generate-documentation.md | Components | Pattern library docs | | *a11y-check | accessibility-wcag-checklist.md | Components | a11y-audit-report.md | | *calculate-roi | calculate-roi.md | Consolidation | roi-analysis.md, executive-summary.md |

Comandos Universais

| Comando | Task File | Entrada | Saida | |---------|-----------|---------|-------| | *scan {path\|url} | ux-ds-scan-artifact.md | Artifact | scan-summary.md, design-tokens.yaml | | *integrate {squad} | integrate-Squad.md | Squad name | Integration config | | *help | N/A | N/A | Lista de comandos por fase | | *status | N/A | N/A | Estado atual do workflow | | *guide | N/A | N/A | Guia completo do agente | | *exit | N/A | N/A | Sair do modo UX-Design Expert |

Integracoes entre Agentes

Diagrama de Colaboracao

flowchart TB
    subgraph AGENTS["Colaboracao de Agentes"]
        direction TB

        subgraph UX["UX-Design Expert (Uma)"]
            UX_DESC["Design centrado no usuario<br/>Atomic Design methodology<br/>Design tokens & components"]
        end

        subgraph ARCH["Architect (Aria)"]
            ARCH_DESC["Frontend architecture<br/>Component structure<br/>Tech stack decisions"]
        end

        subgraph DEV["Dev (Dex)"]
            DEV_DESC["Implementa componentes<br/>Integra design system<br/>Code quality"]
        end

        subgraph QA["QA (Quinn)"]
            QA_DESC["Review de componentes<br/>Testes de acessibilidade<br/>Validacao visual"]
        end

        subgraph ANALYST["Analyst (Morgan)"]
            ANALYST_DESC["ROI analysis<br/>Metricas de sucesso<br/>Research support"]
        end
    end

    UX -->|"front-end-spec.md<br/>component-inventory.md"| ARCH
    UX -->|"Component specs<br/>Design tokens"| DEV
    ARCH -->|"Architecture decisions<br/>Frontend guidance"| UX
    DEV -->|"Implementation feedback<br/>Tech constraints"| UX
    QA -->|"A11y review<br/>Visual QA"| UX
    ANALYST -->|"Research support<br/>ROI metrics"| UX

    style UX fill:#e3f2fd
    style ARCH fill:#fff3e0
    style DEV fill:#e8f5e9
    style QA fill:#fce4ec
    style ANALYST fill:#f3e5f5

Quando Usar Cada Agente

| Necessidade | Agente Recomendado | |-------------|-------------------| | Pesquisa de usuario, personas | @ux-design-expert | | Wireframes e prototipos | @ux-design-expert | | Auditoria de design system | @ux-design-expert | | Construcao de componentes | @ux-design-expert ou @dev | | Arquitetura frontend | @architect | | Implementacao de codigo | @dev | | Review de acessibilidade | @ux-design-expert ou @qa | | Analise de ROI | @ux-design-expert ou @analyst |

Handoffs Tipicos

| De | Para | Artefato | Propósito | |----|------|----------|-----------| | @ux-design-expert | @architect | front-end-spec.md | Especificacao para arquitetura | | @architect | @ux-design-expert | architecture.md | Constrains tecnicas | | @ux-design-expert | @dev | Component specs + tokens | Implementacao | | @dev | @ux-design-expert | Feedback de implementacao | Ajustes de design | | @qa | @ux-design-expert | A11y report | Remediacoes |

Gestao de Estado

Arquivo de Estado (.state.yaml)

# Localizacao: outputs/ux-design/{project}/.state.yaml
metadata:
  version: "1.0.0"
  generated_by: "Uma (UX-Design Expert)"
  generated_at: "2026-02-04T12:00:00Z"

# UX Phase (Phase 1)
ux_research:
  complete: true
  personas: ["Developer Dave", "Designer Dana", "Manager Mike"]
  key_insights: ["Users need faster workflows", "Accessibility is priority"]
  research_date: "2026-02-04"

wireframes:
  created: ["dashboard", "settings", "profile"]
  fidelity_level: "mid"
  component_inventory: ["Button", "Input", "Card", "Modal"]

# Audit Phase (Phase 2)
audit:
  complete: true
  scan_path: "./src"
  patterns:
    buttons:
      unique: 47
      instances: 327
      redundancy_factor: 6.96
    colors:
      unique_hex: 82
      total_instances: 1247
      redundancy_factor: 14.01
    spacing:
      unique_values: 19

# Consolidation Phase
consolidation:
  complete: true
  patterns_consolidated:
    colors:
      before: 89
      after: 12
      reduction: "86.5%"
    buttons:
      before: 47
      after: 3
      reduction: "93.6%"
  overall_reduction: "81.8%"
  target_met: true

# Tokenization Phase (Phase 3)
tokens:
  extracted: true
  categories:
    colors: 12
    spacing: 7
    typography: 10
    radius: 4
    shadows: 3
  total: 36
  exports: ["yaml", "json", "css", "tailwind", "dtcg"]
  coverage: "96.3%"

# Build Phase (Phase 4)
components:
  built: ["Button", "Input", "Label", "Badge"]
  atomic_levels:
    atoms: ["Button", "Input", "Label", "Icon", "Badge"]
    molecules: ["FormField", "SearchBar", "Card"]
    organisms: ["Header", "Form", "Modal"]
  test_coverage: "92.4%"

# Quality Phase (Phase 5)
quality:
  accessibility:
    score: 98
    wcag_level: "AA"
    violations: 0
  documentation:
    complete: true
    components_documented: 15
  roi:
    annual_savings: "$374,400"
    roi_ratio: 34.6
    breakeven_months: 0.38

# Workflow tracking
workflow:
  current_phase: "quality"
  workflow_type: "brownfield"
  phases_completed: [1, 2, 3, 4, 5]

Workflows Relacionados

design-system-build-quality.yaml

Pipeline pos-migracao que encadeia:

  1. Build - Compilar componentes atomicos
  2. Document - Gerar documentacao pattern library
  3. A11y Check - Auditoria WCAG AA
  4. ROI - Calcular savings e metricas
graph TD
    A["Start: Design System Quality Pipeline"] --> B["ux-design-expert: Build componentes atomicos"]
    B --> C{Build OK?}
    C -->|Sim| D["ux-design-expert: Gerar documentacao"]
    C -->|Nao| E["Corrigir erros"]
    E --> B

    D --> F{Docs completas?}
    F -->|Sim| G["ux-design-expert: Auditoria a11y WCAG AA"]
    F -->|Nao| H["Completar docs"]
    H --> D

    G --> I{a11y aprovado?}
    I -->|Sim| J["ux-design-expert: Calcular ROI"]
    I -->|Nao| K["Remediar violacoes"]
    K --> G

    J --> L["Pipeline Completo"]

    style L fill:#90EE90
    style B fill:#E6E6FA
    style D fill:#E6E6FA
    style G fill:#E6E6FA
    style J fill:#E6E6FA

brownfield-ui.yaml

Workflow completo para projetos UI existentes:

  1. Analyze - @architect analisa projeto
  2. PRD - @pm cria PRD
  3. Spec - @ux-design-expert cria front-end-spec
  4. Architecture - @architect cria arquitetura
  5. Validate - @po valida artefatos
  6. Development Cycle - @sm, @dev, @qa

Principios de Design (Atomic Design)

Hierarquia de Componentes

flowchart BT
    subgraph ATOMS["Atoms (Building Blocks)"]
        A1["Button"]
        A2["Input"]
        A3["Label"]
        A4["Icon"]
        A5["Badge"]
    end

    subgraph MOLECULES["Molecules (Simple Combinations)"]
        M1["FormField<br/>(Label + Input)"]
        M2["SearchBar<br/>(Input + Icon + Button)"]
        M3["Card<br/>(Image + Title + Text)"]
    end

    subgraph ORGANISMS["Organisms (Complex Sections)"]
        O1["Header<br/>(Logo + Nav + Search + Profile)"]
        O2["Form<br/>(Multiple Fields + Button)"]
        O3["DataTable<br/>(Headers + Rows + Pagination)"]
    end

    subgraph TEMPLATES["Templates (Page Layouts)"]
        T1["Dashboard Template"]
        T2["Form Page Template"]
        T3["Detail Page Template"]
    end

    subgraph PAGES["Pages (Specific Instances)"]
        P1["Dashboard Page"]
        P2["Settings Page"]
        P3["Profile Page"]
    end

    ATOMS --> MOLECULES --> ORGANISMS --> TEMPLATES --> PAGES

    style ATOMS fill:#e3f2fd
    style MOLECULES fill:#e8f5e9
    style ORGANISMS fill:#fff3e0
    style TEMPLATES fill:#fce4ec
    style PAGES fill:#f3e5f5

Best Practices

1. UX Research

  • Sempre comece com pesquisa de usuario antes de design
  • Conduza 5-10 entrevistas para insights qualitativos
  • Crie personas baseadas em evidencias, não suposicoes
  • Documente user journeys com pain points e oportunidades

2. Design System Audit

  • Execute *audit antes de qualquer consolidacao
  • Meta: >80% de reducao de redundancia
  • Use clustering HSL 5% para cores (perceptual similarity)
  • Documente overrides manuais quando necessario

3. Design Tokens

  • tokens.yaml e source of truth - todos exports derivam dele
  • Use naming semantico (primary, not blue-500)
  • OKLCH para cores modernas com fallback hex
  • Valide com DTCG CLI antes de finalizar

4. Component Building

  • Componentes devem usar APENAS tokens (zero hardcoded values)
  • Use cva para variants (class-variance-authority)
  • Implemente loading state em todos os componentes interativos
  • Testes com >85% coverage + jest-axe para acessibilidade

5. Acessibilidade

  • WCAG AA e minimo, AAA e ideal
  • Contraste: 4.5:1 para texto, 3:1 para UI
  • Foco visivel em todos os elementos interativos
  • Navegacao por teclado (Tab/Shift+Tab/Space/Enter)

6. ROI Calculation

  • Use estimativas conservadoras (2 hrs/mes por padrao)
  • Inclua todos os custos: implementacao, migracao, treinamento
  • Calcule breakeven point antes de apresentar stakeholders
  • ROI >2x e minimo para aprovacao

Troubleshooting

*audit não encontra padroes

Causa: Path incorreto ou arquivos não-UI Solucao:

# Verificar path
*audit ./src/components

# Verificar extensoes
# Suporta: .jsx, .tsx, .vue, .html, .css, .scss

*consolidate não atinge 80%

Causa: Padroes muito distintos ou threshold muito baixo Solucao:

  • Revisar padroes manualmente
  • Ajustar HSL threshold (padrao 5%)
  • Aceitar reducao menor com justificativa

*tokenize gera tokens incompletos

Causa: Consolidacao incompleta Solucao:

# Re-executar consolidacao
*consolidate

# Verificar coverage
# Target: >95%

*build falha com token não encontrado

Causa: Token referenciado não existe em tokens.yaml Solucao:

  • Verificar nome do token
  • Adicionar token faltante em tokens.yaml
  • Re-executar *tokenize se necessario

Testes de acessibilidade falham

Causa: Violacoes WCAG Solucao:

  • Revisar a11y-audit-report.md
  • Corrigir violacoes mais criticas primeiro
  • Re-executar *a11y-check apos correcoes

State file corrompido

Causa: Execucao interrompida Solucao:

# Backup existe em .state.yaml.bak
# Restaurar ou re-executar comandos desde ultimo estado valido

Referencias

Arquivos de Task

Arquivos de Workflow

Definição do Agente

Recursos Externos

Resumo

| Aspecto | Detalhes | |---------|----------| | Total de Tasks | 22 tasks (4 + 3 + 7 + 3 + 3 + 2) | | Total de Templates | 9 templates | | Total de Checklists | 4 checklists | | Total de Data Files | 7 data files | | Total de Comandos | 19 comandos + 4 universais | | Fases do Workflow | 5 (Research, Audit, Tokens, Build, Quality) | | Workflows Relacionados | 4 (design-system-build-quality, brownfield-ui, brownfield-discovery, greenfield-ui) | | Agentes Colaboradores | 4 (@architect, @dev, @qa, @analyst) | | Metodologia Central | Atomic Design (Brad Frost) | | Nivel de Acessibilidade | WCAG AA minimo, AAA ideal |

Changelog

| Data | Autor | Descrição | |------|-------|-----------| | 2026-02-04 | @ux-design-expert | Documento inicial criado |

-- Uma, desenhando com empatia

Falar com o Time