Communitygithub.com

ux-md-generator

Gera, extrai, audita, pré-visualiza, compara e valida especificações estruturais de UI/UX no formato UX.md v1. Define o esqueleto da aplicação (shell do app, orçamento espacial, propriedade de rolagem e índices z, arquétipos de página, grafo de alcance de rotas, persistência de estado de URL, matriz de decisão de sobreposições, contrato de visualização de 4 estados, ergonomia de formulários e mutações e primitivas de layout obrigatórias) como complemento estrutural de DESIGN.md e AGENTS.md. Use ao inicializar um projeto frontend/UI, extrair padrões de UX de um produto de referência, auditar uma base de código existente para desvios de layout ou adicionar novas rotas e visualizações.

O que é ux-md-generator?

O skill `ux-md-generator` é uma ferramenta especializada para agentes de IA (como Claude Code, Cursor, Codex, etc.) que atua como gerador e auditor estrutural de especificações UX. Ele foi projetado para resolver um problema comum em projetos de frontend: a deriva de sessão entre agentes de IA, que causa inconsistências como variação de larguras de contêineres, mudanças arbitrárias de modais para gavetas, omissão de estados vazios ou de erro e quebra de persistência de estado ao recarregar a página. O skill opera em quatro modos principais — Síntese (greenfield), Extração de referência, Auditoria de base de código existente e Evolução (adição de rotas) — utilizando um pipeline de três fases alimentado por seis scripts Node.js sem dependências externas. Ele gera um arquivo UX.md completo com 12 seções estruturadas, abrangendo desde a topologia do produto até primitivas de layout obrigatórias, e inclui validação automática com 16 regras determinísticas. O skill é ideal para equipes que desejam estabelecer um contrato de UX rigoroso e verificável por máquina, garantindo que agentes de IA mantenham consistência visual e comportamental entre sessões de desenvolvimento.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SolidStateNetwork/ux.md/tree/main/skills/ux-md-generator

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

ScriptPropósitoExemplo de Uso
scripts/extract-ux.mjsEscaneia package.json, AGENTS.md, DESIGN.md e rotas de origem (src/app, src/pages) em JSON estruturadonode .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json
scripts/generate-ux.mjsGera uma UX.md de 12 seções a partir de um arquétipo, preset de produto (--preset linear) ou ux-scan.jsonnode .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md
scripts/validate-ux.mjsExecuta 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.mjsGera propriedades personalizadas CSS ux-contract.css e primitivas de layout React/TypeScript (AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) a partir de UX.mdnode .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux
scripts/preview-ux.mjsGera um simulador de wireframe interativo responsivo autônomo ux-preview.htmlnode .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html
scripts/diff-ux.mjsCompara dois arquivos UX.md para regressões de rota, arquétipo, orçamento ou limitesnode .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json

Modos de Operação

  1. Síntese (greenfield / init): Executa extract-ux.mjs + generate-ux.mjs para gerar a UX.md inicial a partir do contexto do projeto e DESIGN.md, em seguida personaliza as rotas, arquétipos e regras de domínio.
  2. 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).
  3. Auditoria e engenharia reversa (base de código existente): Executa extract-ux.mjs para descobrir rotas existentes (src/app/**, src/pages/**, src/routes/**), detecta desvios estruturais e gera uma UX.md unificada.
  4. 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

  1. Execute node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . (ou inspecione package.json, AGENTS.md e DESIGN.md diretamente) para detectar o runtime alvo, limite de autenticação, rotas existentes e breakpoints de DESIGN.md.
  2. Carregue resources/archetype-taxonomy.md e confirme:
    • platform_profile: web-app | mobile-native | desktop-app | terminal-tui
    • archetype: b2b-saas-workspace | ai-chat-canvas | analytics-dashboard | ecommerce-storefront | developer-tool
  3. Opcionalmente, inicialize UX.md via:
    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 0 a 11 em 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 (Mermaid flowchart 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 em px)
    • ## 6. Estados de Visualização Obrigatórios (Matriz de 4 Estados) (Carregando, Vazio, Erro, Populado)
    • ## 7. Ergonomia de Mutação, Formulário & Permissão (guarda isDirty, 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 >= 44x44px com 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 um Gatilho de Entrada quanto uma Saí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

  1. Audite a UX.md gerada contra resources/quality-checklist.md ([UX-01] a [UX-16]).
  2. Execute o script de lint automatizado:
    node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
    
  3. Resolva quaisquer achados reportados como error ou warning e re-execute até que o validador saia com 0 erros.

Habilidades Relacionadas