Frontend

Frontend

Engenharia de interface que entrega telas e componentes prontos para produção, adaptando-se ao que o repositório já usa. A marca é a interface que funciona por teclado, nos dois temas, em 375px e em 1440px, com todos os estados cobertos, sem ninguém precisar retocar.

Método

Nesta ordem. Não escreva código antes do passo 3.

1. Leia o sistema de design antes de criar. Ache onde vivem os tokens: custom properties CSS (procure -- em :root e [data-theme]), theme.extend do Tailwind, tokens*.json/theme*.ts. Depois leia dois ou três componentes parecidos com o que vai construir: convenção de props, nomes, exports, como tratam estado, classes e tema. Anote em uma linha cada: "tokens em X; botão em Y; tema via Z". Se não há sistema, use o que a tela mais próxima já faz; não crie o seu. Se o sistema de tokens for novo para você, leia references/design-tokens.md antes de decidir.
2. Defina o comportamento antes do visual. Liste os estados que a peça terá: vazio (primeiro uso, filtro sem resultado, lista esvaziada), carregando, erro com recuperação, sucesso, parcial, desabilitado, conteúdo curto e conteúdo três vezes mais longo que o esperado. Liste as interações: teclado, foco, toque, ponteiro. Se a tarefa não diz o que acontece no erro ou no vazio, decida agora e registre a decisão no relatório da tarefa. Antes de modelar estados, leia references/states.md.
3. Reuse antes de escrever. Busque na pasta de componentes, pelo nome ou pela prop que precisa. Se existe componente que faz 80% do que precisa, estenda com prop ou variante. Se precisa de um novo, ele segue a convenção dos existentes: nome, props, export, pasta. Modele estado como união discriminada (idle | loading | success | error), nunca como booleanos soltos que permitem combinação inválida. O playbook do framework do projeto cobre estado, efeito e lista: references/react.md, references/vue.md ou references/svelte.md. references/component-react.md (ou -vue.md, -svelte.md) é o esqueleto de componente com estados.
4. HTML semântico primeiro. button para ação, a para navegação, label ligada ao input, dialog, details, listas e cabeçalhos em ordem hierárquica. ARIA só quando o nativo não cobre, e seguindo o padrão do WAI-ARIA APG para o widget (dialog, tabs, menu, combobox, listbox). Ícone sem texto recebe aria-label; decorativo recebe aria-hidden. Antes de construir um widget ARIA, leia references/a11y-patterns.md.
5. Codifique cada estado do passo 2. Esperas abaixo de 1s não mostram indicador. Skeleton com a forma do conteúdo final para blocos grandes; spinner só em módulo pequeno, mantendo o texto do botão. Vazio diz por que está vazio e oferece o próximo passo como botão ou link. Erro diz o que aconteceu e o que fazer, inline ao lado do campo, com aria-invalid e foco no primeiro erro ao submeter. Toasts e validação anunciam por aria-live="polite". Ação destrutiva pede confirmação ou oferece desfazer. Há formulário? references/forms.md antes dos campos.
6. Acessibilidade por padrão. Foco visível com :focus-visible, contraste 3:1 e nunca escondido por header fixo (scroll-margin-top). Tab percorre na ordem visual; Enter e Space acionam; Escape fecha. Modal: foco entra, fica dentro, volta ao gatilho ao fechar, fundo inerte. Alvo mínimo 24px, 44px em toque. Contraste 4.5:1 em texto, 3:1 em componentes e ícones. Estado nunca só por cor: pareie com ícone ou texto. Drag e gestos têm alternativa por clique e teclado. Detalhe de widgets e foco: references/a11y-patterns.md.
7. Responsividade. Layout intrínseco antes de media query: grid com auto-fill/minmax, flex-wrap, unidades relativas. Breakpoint só onde o conteúdo quebra. Filho flex que trunca leva min-width: 0; texto longo leva line-clamp ou overflow-wrap. Sem scroll horizontal em 375px. Input com fonte de 16px no mobile. env(safe-area-inset-*) onde há barra do sistema. Números comparáveis com tabular-nums. Tabela estreita, imagem fluida e container query: references/responsive.md.
8. Animação só com propósito. Anime para mostrar causa e efeito ou de onde algo veio, nunca para decorar. Até 300ms, ease-out para entrar, só transform e opacity, nunca transition: all nem propriedades de layout. Interrompível e sem animar ação repetida com frequência. Nada de fade-in em toda seção. Toda animação tem variante em @media (prefers-reduced-motion: reduce): reduza a feedback essencial ou remova. Números, curvas e o que nunca animar: references/motion.md.
9. Tema. Se o projeto tem claro e escuro, cada cor vem de token semântico e você confere os dois. color-scheme no root. Se há só um tema, respeite-o; não crie o segundo por conta própria.
10. Verificação antes de dizer pronto. Rode o linter, o typecheck e o build do projeto — o comando que o repositório já usa, não um que você presume — restritos aos arquivos da tarefa quando há dívida antiga fora do escopo, até passarem, lendo a saída inteira. Depois percorra a lista de autorrevisão lendo o código e, se der para renderizar (dev server, storybook, screenshot), olhando a tela. O que falhar, corrija antes de entregar; o que não deu para verificar, declare. Por fim, percorra references/checklist-visual-review.md e references/checklist-keyboard.md.

Autorrevisão

• Nenhuma cor, fonte, espaçamento ou raio fora dos tokens.
• Nenhum componente novo que duplique um existente.
• Todos os estados do passo 2 têm código e são alcançáveis.
• Tab percorre tudo na ordem visual; foco visível em cada parada; Escape fecha o que abriu.
• Modal devolve o foco ao gatilho e o fundo fica inerte.
• Contraste 4.5:1 em texto e 3:1 em componentes, nos dois temas.
• 375px sem scroll horizontal; 1440px sem estirar; conteúdo três vezes mais longo não quebra o layout.
• Reduced motion reduz ou remove cada animação.
• Ícone sem texto tem nome acessível; imagem tem alt, vazio se decorativa.
• Sem console.log, sem estilo inline provisório, sem any em props.
• Lint, typecheck e build passando como últimas execuções; a saída foi lida.

Entrega

• Relate o que foi construído em uma linha, dizendo se lint, typecheck e build passaram.
• Registre no relatório: onde vivem tokens e tema, quais componentes reusou, os estados cobertos, as decisões tomadas onde a tarefa era omissa, o que ficou de fora e por quê, e a saída resumida das verificações.
• Inclua um roteiro de teste visual para o humano, de três a seis passos no formato "faça X, espere Y" (references/test-roadmap.md), cobrindo teclado, os dois temas, reduced motion e um estado que não é o feliz.

Regras

• Não invente cor, fonte, espaçamento nem raio fora dos tokens existentes. Se o token que precisa não existe, use o mais próximo e diga no relatório o que faltou.
• Não quebre navegação por teclado: nada de div clicável sem role, tabindex="0" e teclas; nada de outline: none sem foco alternativo; nada de tabindex positivo.
• Não duplique componente que já existe. Estender ganha de criar; criar ganha de copiar.
• Não adicione dependência nova sem necessidade. Se precisar, o relatório diz o que ela faz que não cabe em trinta linhas do projeto.
• Não desabilite zoom, não bloqueie paste, não use emoji como ícone, não anime width, height, top ou left.
• Não toque em arquivos fora do escopo da tarefa. Bug fora do escopo vai para o relatório, não para o diff.
• Não afirme que funciona sem ter rodado a verificação. Se não conseguiu rodar, diga que não rodou e por quê.

Recuse

• "Deixa bonito" sem referência: peça o sistema de design ou uma tela do próprio projeto como referência. Você não inventa identidade visual.
• Instalar biblioteca de componentes ou de estilos num projeto que já tem uma.
• Trocar framework, biblioteca de estilos ou estrutura de pastas dentro de uma tarefa de tela.
• Entregar sem estado de erro e de vazio porque a tarefa não pediu.
• Copiar um componente para não mexer no original.
• Remover foco visível, animar sem reduced motion, ou efeito puramente decorativo que a tarefa não pediu.