---
id: build-component
agent: ux-design-expert
title: Construir um componente atômico de produção
inputs: [nome do componente, design tokens, story/spec]
outputs: [componente atômico + testes + a11y, 'docs/design-system/atoms/{componente}/']
elicit: false
modes: [interactive, yolo]
---

# Construir um componente atômico de produção

**Objetivo:** entregar um átomo de produção — componente tipado, testado, construído só sobre design
tokens e com acessibilidade WCAG AA embutida — pronto para compor moléculas e ser integrado na app.

**Pré-condições:**
- O design system está inicializado (`setup-design-system`) e os tokens existem (`extract-tokens`).
  Sem isso, **pare**: átomo sem tokens vira hardcode.
- O componente rastreia a uma story/spec ou a um cluster consolidado. Sem rastro, elicito — não
  invento componente que ninguém pediu.

## Passos

1. **Procuro o átomo antes de criar** (REUSE > ADAPT > CREATE). Se já existe um átomo que resolve,
   reaproveito; se quase resolve, é caso de `extend-pattern` (variante), não de criar do zero. Só
   crio quando nada serve — e registro o porquê.
2. **Defino a API do componente** a partir da story/spec: props, variantes, estados (default, hover,
   focus, disabled, loading, erro) — todos rastreando a uma necessidade real, não a um achismo.
3. **Construo só com tokens.** Cor, espaçamento, tipografia, raio e sombra vêm de
   `docs/design-system/tokens/` — zero hex/px solto. Hardcode aqui é bug de design esperando para
   divergir.
4. **Embuto acessibilidade WCAG AA desde o nascimento:** semântica correta (role/elemento),
   navegação por teclado, foco visível, contraste validado, alt/aria onde aplicável. Não é "a11y
   depois"; sem ela o componente não está pronto.
5. **Escrevo os testes** que provam: cada variante/estado renderiza, o teclado navega, o foco é
   visível, e os estados de erro/disabled se comportam. Não declaro pronto sem teste verde.
6. **Rodo `accessibility-wcag-checklist`** no componente. Reprovou em AA → não entrego; corrijo
   antes. Acessibilidade reprovada bloqueia a entrega.
7. **Rodo lint + typecheck + os testes** do componente. Vermelho não vira entregue.
8. **Documento o uso** (props, variantes, exemplos) para a pattern library e salvo tudo em
   `docs/design-system/atoms/{componente}/`. Atualizo a File List da story.
9. **Roteio.** Átomo pronto → @dev integra na app, @qa valida no fluxo. Pronto pra subir → @devops.
   Eu construo o componente; quem publica é o Gage — nunca eu.

## Critério de pronto (DoD)

- [ ] Reuso checado antes de criar (REUSE > ADAPT > CREATE), com justificativa se criou do zero
- [ ] Componente tipado, com todas as variantes/estados que a story pede
- [ ] Zero valor hardcoded — tudo de design tokens
- [ ] WCAG AA embutida (semântica, teclado, foco, contraste) e validada pelo checklist
- [ ] Testes verdes; lint limpo; typecheck 0
- [ ] Documentação de uso escrita; File List atualizada; nada subido por mim

## Falha / recuperação

- **Reprova WCAG AA** → HALT; não entrego. Corrijo a acessibilidade antes de qualquer coisa.
- **Teste não passa após 3 tentativas no mesmo ponto** → HALT, registro o bloqueio, não empurro
  gambiarra.
- **A story não define a API o suficiente** → paro e devolvo ao @sm/@po; não invento props/variantes.
- **Precisaria de valor fora dos tokens** → não hardcodo; volto à `extract-tokens` para o token
  faltante (ou sinalizo a lacuna), e só então construo.