Gerador de UX.md e Auditor Estrutural (v1)
Visão Geral
Enquanto DESIGN.md especifica tokens visuais (cores, tipografia, raios, sombras, escala de espaçamento), UX.md especifica o esqueleto estrutural e as regras de interação de uma aplicação.
Sem UX.md, agentes de IA de codificação derivam entre sessões: misturam larguras de contêineres, movem CTAs primários, alternam arbitrariamente entre modais e gavetas, omitem estados vazios ou de erro, perdem estado de filtro ao recarregar (F5) e introduzem rotas sem saída.
Este skill opera em quatro modos usando um pipeline de três fases alimentado por seis scripts Node.js sem dependências em scripts/.
Scripts CLI Empacotados
| Script | Propósito | Exemplo de Uso |
|---|---|---|
scripts/extract-ux.mjs | Escaneia package.json, AGENTS.md, DESIGN.md e rotas de origem (src/app, src/pages) em JSON estruturado | node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json |
scripts/generate-ux.mjs | Gera uma UX.md de 12 seções a partir de um arquétipo, preset de produto (--preset linear) ou ux-scan.json | node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md |
scripts/validate-ux.mjs | Executa 16 regras determinísticas de lint estrutural e --check-code (paridade de rotas, primitivas, handlers mortos, índices z errantes) | node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code |
scripts/scaffold-ux.mjs | Gera propriedades personalizadas CSS ux-contract.css e primitivas de layout React/TypeScript (AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) a partir de UX.md | node .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux |
scripts/preview-ux.mjs | Gera um simulador de wireframe interativo responsivo autônomo ux-preview.html | node .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html |
scripts/diff-ux.mjs | Compara dois arquivos UX.md para regressões de rota, arquétipo, orçamento ou limites | node .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json |
Modos de Operação
- Síntese (greenfield /
init): Executaextract-ux.mjs+generate-ux.mjspara gerar aUX.mdinicial a partir do contexto do projeto eDESIGN.md, em seguida personaliza as rotas, arquétipos e regras de domínio. - Extração a partir de referência (produto de referência ou URL): Extrai o shell espacial, regras de interação, atalhos de teclado e arquétipos de página de um produto de referência nomeado (por exemplo Linear, ChatGPT Canvas, Stripe Dashboard, Shopify ou Supabase).
- Auditoria e engenharia reversa (base de código existente):
Executa
extract-ux.mjspara descobrir rotas existentes (src/app/**,src/pages/**,src/routes/**), detecta desvios estruturais e gera umaUX.mdunificada. - Evolução (adição de funcionalidade / sincronização de rotas):
Atualiza a Seção 3 (Arquétipos de Página) e a Seção 4 (Navegação, Grafo de Rotas e Persistência de URL) sempre que novas páginas ou fluxos de trabalho são adicionados, verificando paridade com
validate-ux.mjs UX.md --check-code.
Pipeline de Geração em Três Fases
Fase 1: Extração determinística e classificação de arquétipos
- Execute
node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .(ou inspecionepackage.json,AGENTS.mdeDESIGN.mddiretamente) para detectar o runtime alvo, limite de autenticação, rotas existentes e breakpoints deDESIGN.md. - Carregue resources/archetype-taxonomy.md e confirme:
platform_profile:web-app|mobile-native|desktop-app|terminal-tuiarchetype:b2b-saas-workspace|ai-chat-canvas|analytics-dashboard|ecommerce-storefront|developer-tool
- Opcionalmente, inicialize
UX.mdvia:node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --archetype <archetype> --project "<Project Name>" --output UX.md
Fase 2: Síntese específica de domínio em 12 seções
Carregue resources/ux-md-format.md, resources/layout-primitives.md e resources/writing-style-guide.md. Personalize UX.md na raiz do repositório com:
- Fronte YAML: Configuração completa (
spec_version: "1.0",shell_budget,z_index_scale,thresholds,layout_primitives). - Seções
0a11em ordem sequencial:## 0. Topologia de Produto & Domínio## 1. Arquitetura Espacial & Shell do App(wireframe ASCII e tabela de orçamento de viewport)## 2. Contrato de Rolagem, Viewport e Índice Z## 3. Arquétipos Centrais de Página (Blueprints)(usando cabeçalhos### Arquétipo: <ArchetypeID>)## 4. Navegação, Grafo de Rotas e Persistência de URL(Mermaidflowchart LR, tabela de alcançabilidade de rotas e matriz de persistência de estado)## 5. Matriz de Decisão de Sobreposições & Feedback(contagem de campos e limites empx)## 6. Estados de Visualização Obrigatórios (Matriz de 4 Estados)(Carregando,Vazio,Erro,Populado)## 7. Ergonomia de Mutação, Formulário & Permissão(guardaisDirty, regras destrutivas de 2 níveis, portões de permissão de 3 vias)## 8. Estresse de Dados Reais, Densidade & Truncamento(modo único de escala de lista,min-w-0 truncate, token placeholder-para células vazias,tabular-nums)## 9. Refluxo Responsivo & Coreografia de Entrada(ordem de colapso, alvos de toque>= 44x44pxcom gap>= 8px, equivalentes de toque para interações hover, padding de rolagem seguro para área)## 10. Primitivas de Layout Obrigatórias (Contrato de Código)(<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>)## 11. Diretrizes de Projeto: Faça, Não Faça & Guia de Prompt para Agentes
Restrições de escrita:
- Zero adjetivos vagos: Não escreva "formulário pequeno", "layout limpo", "requisição lenta" ou "navegação intuitiva" sem números explícitos (
<= 4 campos,1280px,>= 150ms). Veja resources/anti-patterns.md. - Zero becos sem saída: Cada rota na Seção 4 referencia um
<ArchetypeID>válido da Seção 3 e define tanto umGatilho de Entradaquanto umaSaída / Cancela Fallback. - Imponha primitivas de layout: Garanta que todas as rotas componham as 4 primitivas de layout obrigatórias (
<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>) definidas na Seção 10.
Fase 3: Auditoria cruzada e validação por máquina
- Audite a
UX.mdgerada contra resources/quality-checklist.md ([UX-01]a[UX-16]). - Execute o script de lint automatizado:
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - Resolva quaisquer achados reportados como
errorouwarninge re-execute até que o validador saia com0 erros.