---
id: compose-molecule
agent: ux-design-expert
title: Compor uma molécula a partir de átomos existentes
inputs: [nome da molécula, átomos existentes, design tokens, story/spec]
outputs: [molécula + testes + a11y, 'docs/design-system/molecules/{molécula}/']
elicit: false
modes: [interactive, yolo]
---

# Compor uma molécula a partir de átomos existentes

**Objetivo:** combinar átomos já construídos numa molécula de produção (ex.: campo de busca = input +
botão + label) — testada, sobre tokens, com a11y preservada no conjunto — sem reinventar átomo.

**Pré-condições:**
- Os átomos necessários já existem em `docs/design-system/atoms/` e estão prontos (testados,
  WCAG AA). Se um átomo faltar, **pare**: composição não inventa átomo — isso é `build-component`.
- A molécula rastreia a uma story/spec ou a um padrão consolidado. Sem rastro, elicito — não invento
  composição.

## Passos

1. **Identifico os átomos que compõem a molécula** a partir da story/spec e confirmo que cada um já
   existe e está pronto. Falta de átomo → roteio para `build-component`, não improviso aqui.
2. **Componho sobre os átomos**, sem fork: uso os átomos como estão, passando props; não duplico
   nem reescrevo lógica que já vive no átomo. Reaproveitar é o ponto.
3. **Defino a API da molécula** (props, estados do conjunto, eventos) rastreando a uma necessidade
   real. Layout e espaçamento entre átomos vêm de tokens — zero valor hardcoded.
4. **Garanto a acessibilidade do conjunto**, não só dos átomos: ordem de foco coerente, rótulos
   associados (ex.: label ↔ input), agrupamento semântico, anúncio de estado/erro do grupo. WCAG AA
   no conjunto é piso.
5. **Escrevo os testes** que provam a composição: a molécula renderiza com os átomos certos, a
   interação entre eles funciona (ex.: busca dispara), foco e estados do grupo se comportam.
6. **Rodo `accessibility-wcag-checklist`** na molécula. Reprovou em AA → não entrego; corrijo antes.
7. **Rodo lint + typecheck + os testes.** Vermelho não vira entregue.
8. **Documento o uso** da molécula (átomos que a compõem, props, exemplos) para a pattern library e
   salvo em `docs/design-system/molecules/{molécula}/`. Atualizo a File List da story.
9. **Roteio.** Molécula pronta → @dev integra na app, @qa valida. Pronto pra subir → @devops — nunca
   eu.

## Critério de pronto (DoD)

- [ ] Composta só de átomos prontos existentes (sem reinventar átomo, sem fork)
- [ ] API definida e rastreada à story; layout/espaçamento via tokens (zero hardcode)
- [ ] A11y do conjunto garantida (ordem de foco, rótulos, agrupamento) e validada pelo checklist
- [ ] Testes da composição verdes; lint limpo; typecheck 0
- [ ] Documentação de uso escrita; File List atualizada; nada subido por mim

## Falha / recuperação

- **Falta um átomo** → não improviso dentro da molécula; roteio para `build-component` e pauso a
  composição até o átomo estar pronto.
- **Reprova WCAG AA no conjunto** → HALT; corrijo a acessibilidade do grupo antes de entregar.
- **Teste da composição não passa após 3 tentativas no mesmo ponto** → HALT, registro o bloqueio.
- **A story não define a composição o suficiente** → paro e devolvo ao @sm/@po; não invento a
  molécula.