| name | frontend-design |
| description | Padrões de design e qualidade pra entregas de interface: semântica HTML, acessibilidade, performance percebida e consistência com tokens do repo. Ativa quando stack detectada inclui frontend (React/Vue/Next/SPA). |
Você (Thiago, Artesão) está mexendo em interface. Antes de marcar a task como pronta, passa por essas checagens. Nem todas se aplicam toda vez — use como filtro mental.
1. Semântica primeiro, ARIA quando precisa
- Usa o elemento HTML certo:
<button> pra ação (não <div onClick>), <a> pra navegação, <form> quando submete.
- Cabeçalhos hierárquicos:
h1 único por tela, h2/h3 em ordem; não pula níveis pra "ficar bonito".
<label for> em todo input (ou <label> envolvendo).- ARIA só quando HTML semântico não cobre (ex: tooltip, modal não-nativo). Não inventa
role redundante.
2. Acessibilidade básica (AA)
- Contraste de texto: ≥4.5:1 pra body, ≥3:1 pra texto grande. Ferramentas como axe ou Lighthouse caçam isso — se você tem como rodar, rode.
- Foco visível: nunca
outline: none sem substituir por algo visível. :focus-visible é seu amigo.
- Toque ≥44×44px em mobile/touch (botões e links).
alt em <img>: descritivo quando informativo, alt="" quando decorativo. Nunca omitir.- Navegação por teclado: tudo acionável via mouse deve funcionar com Tab/Enter/Space.
3. Responsivo first
- Mobile primeiro, breakpoints adicionando complexidade pra cima — não o contrário.
- Use
clamp() ou min()/max() em vez de média queries quando dá pra evitar.
- Imagens com
width/height (CLS), ou aspect-ratio em CSS.
- Toque vs hover: estado
:hover extra não pode ser a única affordance (pinta também :focus).
4. Performance percebida
- Lazy load: imagens abaixo da fold com
loading="lazy", components pesados com React.lazy/dynamic import.
- CLS: reserva espaço (skeleton, aspect-ratio, height fixa) pra elemento que carrega async.
- LCP: hero image otimizada (WebP/AVIF,
priority em Next/img), sem bloquear render por JS.
- Bundle: evite importar lib gigante por 1 helper (
import { debounce } from 'lodash-es' em vez do pacote inteiro).
- No fetch waterfall: paraleliza chamadas onde dá; usa
Promise.all/server components quando aplicável.
5. Microinterações (não tudo estático)
Interface viva tem feedback:
- Botão:
hover, active, disabled, loading distintos. Não só cor — também cursor, opacidade, ícone.
- Loading state: nunca tela em branco esperando. Skeleton, spinner ou progress.
- Empty state: mensagem com voz e CTA, nunca só "Nada por aqui".
- Erro: mensagem do que dá pra fazer (retry, reportar), não só código.
- Transições:
transition: all 150ms ease em mudanças de estado óbvias. Animação sem propósito é ruído.
6. Consistência com o repo
Antes de inventar:
- Tokens existem? Procure por
theme.ts, tailwind.config, CSS vars (--color-*). Use os existentes em vez de cor solta hex.
- Componente já existe?
Button, Card, Modal, Input no projeto antes de criar novo. Reusa, estende, NÃO duplica.
- Padrão de spacing do projeto: se vizinhos usam
gap-3, não meta gap-[13px].
- Naming: arquivo de componente segue padrão do projeto (
PascalCase.tsx vs kebab-case.tsx).
7. Não-óbvio que sempre passa batido
- Dark mode: se o projeto tem, sua entrega tem que funcionar nele. Cores hardcoded quebram.
- i18n: se há
useT()/i18n, novo copy entra na cadeia, não inline hardcoded.
- Scroll: tem
overflow óbvio que precisa de max-height? Modal/drawer abre e segura scroll do body?
- Form: validação client-side + erro inline +
aria-invalid + aria-describedby no input quebrado.
Quando NÃO aplicar
- Brief é trivial (mudar 1 string, ajustar 1 cor).
keep-it-simple toma a frente.
- Não inventa componente novo se já existe versão razoável — o pior frontend é o que recria Button toda task.
