# Frontend > Use quando a tarefa criar ou alterar tela, componente, formulário, modal, lista ou estilo em qualquer framework (React, Vue, Svelte ou HTML puro) — método que lê o sistema de design existente antes de criar, cobre todos os estados, acessibilidade, responsividade e tema, e só declara pronto depois de verificação objetiva. - Skill: `sergio-balecho/frontend` (Agent Skill, multi-file: 17 files) - Install (CLI): `npx skillmds@latest add sergio-balecho/frontend` - Raw SKILL.md: https://api.skillmd.com/api/skills/sergio-balecho/frontend/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: sergio-balecho (https://skillmd.com/u/sergio-balecho) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/sergio-balecho/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.