---
id: extend-pattern
agent: ux-design-expert
title: Adicionar variante a um componente existente
inputs: [componente-base, variante-pedida, story]
outputs: [variante implementada, testes, tokens, doc atualizada, File List atualizada]
elicit: false
modes: [interactive, yolo]
---

# Adicionar variante a um componente existente

**Objetivo:** estender um componente atômico já existente com uma nova variante (tamanho, estado,
intent) sem fork e sem quebrar quem já consome — variante nasce com a11y e tokens embutidos.

**Pré-condições:**
- O componente-base existe no design system e está em produção. Se não existe, **pare** — isto é um
  `*build`, não um `*extend`.
- A variante pedida rastreia a uma story/spec/FR-NFR ou achado de pesquisa. Sem rastro, **pare** e
  sinalizo: não invento variante por gosto.
- Os design tokens já cobrem (ou comportam) os valores da nova variante. Se faltar token, rodo
  `*tokenize` antes — nada de hex solto.

## Passos

1. **Leio o componente-base inteiro** — props, variantes existentes, contrato público, testes. Mapeio
   quem consome (busca de usos) para saber o que NÃO posso quebrar.
2. **Confirmo a rastreabilidade da variante** à story/spec. Identifico o eixo da variante (ex.: novo
   `intent="danger"`, novo `size="xs"`) e checo que não duplica uma variante já existente.
3. **Estendo via prop/variante, nunca por fork.** Adiciono o valor ao tipo/enum da prop, sem mudar a
   assinatura existente. Defaults e variantes atuais permanecem idênticos (mudança aditiva, não breaking).
4. **Puxo todos os valores de design token.** Cor, espaçamento, tipografia e raio da nova variante vêm
   dos tokens consolidados — zero hardcoded.
5. **Escrevo o teste da variante** (render + estados) e **rodo a auditoria de a11y** (`*a11y-check`):
   contraste, foco visível, navegação por teclado e semântica da nova variante.
6. **Rodo a suíte completa** do componente para provar que nenhum consumidor quebrou (regressão das
   variantes antigas + a nova verde).
7. **Atualizo a documentação** da pattern library (`*document`) com a nova variante: exemplo, quando
   usar, quando não usar.
8. **Atualizo a File List** da story e faço **commit local** (conventional commit com o id da story).
   **Nunca** `git push` — entrego pronto e delego a subida ao @devops.

## Critério de pronto (DoD)

- [ ] Variante rastreia a uma story/spec/FR-NFR — sem invenção
- [ ] Mudança é aditiva: nenhuma variante/consumidor existente quebrou (regressão verde)
- [ ] Zero valor hardcoded — tudo via design token
- [ ] a11y WCAG AA aprovada para a nova variante (contraste, foco, teclado, semântica)
- [ ] Teste da variante verde + suíte completa verde
- [ ] Doc da pattern library atualizada (uso / não-uso)
- [ ] File List atualizada e commit local feito (sem `git push`)

## Falha / recuperação

- **A variante quebraria um consumidor existente** → não é `*extend`, é refatoração de contrato. HALT,
  escalo para @architect/@dev decidir a migração antes de prosseguir.
- **a11y reprova na nova variante** → bloqueio a entrega, não marco pronto. Acessibilidade é piso, não
  melhoria futura.
- **Falta token para a variante** → paro, rodo `*tokenize` para criar o token, e só então estendo —
  nunca hardcode como atalho.
- **A variante não rastreia a nenhuma story/spec** → paro e sinalizo como hipótese; busco a evidência
  antes de implementar.
- **A mudança exige integrar na app além do design system** → delego ao @dev em vez de invadir a lane.