dev-workflows/skills/wf-frontend/SKILL.md

name, description, license, metadata

name	description	license	metadata
wf-frontend	Use para trabalho de frontend e UI - componentes, páginas, layouts, estilos, design system, animação, acessibilidade, redesign de tela existente, e geração de PDF ou documento visual a partir de HTML. Fluxo DESIGN, BUILD, REVIEW com profundidade definida pelo nível do dev-router. Não use para backend ou API (wf-backend), para bug sem mudança visual (wf-bugfix) nem para refactor sem mudança de comportamento (wf-refactor).	MIT	dev-workflows uses external design-taste-frontend redesign-existing-projects lean-code dev-router frontend-design web-design vercel-react-best-practices vercel-composition-patterns animate impeccable avoid-ai-writing

Workflow Frontend

A profundidade vem do nível que o dev-router definiu. Cada fase diz a partir de qual nível roda.

Nível	O que roda
0	só o gate (--tier 0)
1	ajuste de UI: siga o design system que já existe; sem DESIGN.md, sem aprovação; BUILD enxuto + gate --tier 1
2	tela ou componente novo: DESIGN curto, BUILD, REVIEW com ui-critic e reviewer
3	fluxo ou design system novo: DESIGN com aprovação do usuário, BUILD por tarefas, REVIEW completo

Skills (carregar só na fase que usa)

• Tela nova: design-taste-frontend (~35 mil tokens; só para tela nova, nunca para ajuste) e, se instalada, frontend-design.
• Tela existente: redesign-existing-projects (audita antes de mudar).
• Auditoria anti "UI de IA": impeccable (/impeccable audit, externa).
• React/Next: vercel-react-best-practices (performance), vercel-composition-patterns (composição).
• Motion: animate. Microcopy: avoid-ai-writing.
• Sempre: lean-code.

Externas são opcionais: se não estiverem instaladas, siga as regras desta página. Instalação em docs/SKILLS.md.

Fase 1, DESIGN (nível 2+, tela ou componente novo)

Nível 1 pula esta fase e usa os tokens, componentes e padrões que o projeto já tem.

1. explorer mapeia o design system existente: tokens (cor, tipografia, espaçamento), componentes reutilizáveis, biblioteca de UI. Reaproveitar vem antes de criar.
2. Defina a direção: paleta, tipografia, densidade, claro/escuro. Tela nova usa design-taste-frontend; redesign usa redesign-existing-projects.
3. Registre as decisões em DESIGN.md (curto: tokens e o porquê).
4. Nível 3, ou decisão que é do usuário (identidade visual, troca de stack): pare e peça aprovação antes de codar. Nível 2 segue sem parar se a direção vem do design system existente.

Evite: gradiente roxo genérico, glassmorphism sem motivo, cards idênticos em grade, ícone decorativo sem função, dois design systems na mesma tela.

Fase 2, BUILD (nível 1+)

1. implementer (ou você, em mudança pequena) implementa com lean-code: componente e hook existentes antes de novos; CSS e HTML nativos antes de JS.
2. Estados em todo fluxo com dados: carregando, vazio, erro, sucesso.
3. Acessibilidade por padrão: HTML semântico, foco visível e em ordem, rótulos, contraste de texto >= 4.5:1. ARIA só quando o HTML não resolve.
4. Responsivo mobile-first, testado em 375 px e 1280 px.
5. Composição: compound components em vez de explosão de props booleanas (isX, showY).
6. Motion com propósito (estado, entrada, feedback) e prefers-reduced-motion respeitado.
7. React/Next: sem waterfall de dados, sem re-render em cascata, imagem com dimensões, código dividido por rota.
8. TypeScript sem any nem cast forçado para "passar".
9. Rode o gate a cada componente relevante, não só no fim.

Entrada de usuário renderizada como HTML, dangerouslySetInnerHTML, eval, postMessage ou mudança de CSP disparam security-auditor (XSS/CSP).

Fase 3, REVIEW (nível 2+)

1. ui-critic: screenshot em 375 e 1280, estados, a11y, padrões genéricos. Se impeccable estiver instalada, /impeccable audit.
2. reviewer: correção e simplicidade do diff.
3. avoid-ai-writing nos textos entregues ao usuário (labels, vazios, erros), se instalada.
4. Corrija o que for bloqueante ou importante e rode os dois de novo só no que mudou.

Gate

"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N

Lint, typecheck, testes, segredos e build rodam sozinhos. O que depende do app de pé (Lighthouse, axe, bundle, regressão visual) entra como [[check]] no .dev-workflows.toml do projeto: modelos em references/checks.md. Lista completa de checagens: skills/dev-router/references/quality-gate.md.

Metas de referência (nível 2+): LCP <= 2,5 s, INP <= 200 ms (TBT como proxy em laboratório), CLS <= 0,1; axe sem violação serious ou critical; bundle dentro do limite do size-limit.

O verifier roda o gate e devolve a evidência. Ferramenta ausente aparece como "não verificado": diga isso ao usuário, nunca chame de testado.

PDF e documento visual

Sempre HTML + CSS renderizado pelo Playwright (page.pdf()), depois cada página convertida em PNG e inspecionada com Read: nada cortado na margem, tabela longa quebrando entre páginas. Nunca reportlab platypus direto para tabelas longas. Método completo: references/pdf.md.

Aceite

• Nível declarado; fases puladas coerentes com ele.
• Nível 2+: direção registrada em DESIGN.md (aprovada pelo usuário no nível 3).
• Estados carregando, vazio, erro e sucesso em todo fluxo com dados.
• Acessível: semântica, foco, rótulos, contraste >= 4.5:1; axe sem serious/critical se configurado.
• Responsivo em 375 px e 1280 px, sem corte ou sobreposição.
• prefers-reduced-motion respeitado; animação só com propósito.
• Sem explosão de props booleanas; composição com compound components.
• Gate pass, ou falhas explicadas; "não verificado" listado ao usuário.
• PDF: páginas renderizadas e inspecionadas, nada cortado.