---
id: create-front-end-spec
agent: ux-design-expert
title: Escrever a especificação de frontend detalhada
inputs: [personas, wireframes, story/spec, design tokens disponíveis]
outputs: [front-end-spec.md, mapeamento componente→AC]
elicit: false
modes: [interactive, yolo]
---

# Escrever a especificação de frontend detalhada

**Objetivo:** consolidar pesquisa, wireframes e tokens numa spec de frontend precisa e rastreável,
que diga ao @dev exatamente o que construir — comportamento, estados, a11y e tokens — sem ambiguidade
e sem escopo inventado.

**Pré-condições:**
- Existem wireframes (`ux-create-wireframe`) e, idealmente, pesquisa de usuário. Sem wireframe,
  **pare** — a spec não nasce de nada.
- A story/spec define os ACs no escopo. Toda seção da front-end spec vai rastrear a um AC/FR/NFR.

## Passos

1. **Liste os componentes e telas** da spec a partir dos wireframes, classificando por nível Atomic
   Design (átomo → molécula → organismo → template → página). Reuso vem antes de criação.
2. **Para cada componente, especifique:** anatomia, variantes, estados (default, hover, foco,
   desabilitado, carregando, erro), comportamento de interação e responsividade.
3. **Amarre os design tokens:** cor, espaçamento, tipografia e raio referenciam tokens nomeados —
   **zero valor hardcoded** na spec. Token ausente vira pendência para `extract-tokens`.
4. **Especifique a acessibilidade por componente:** papel/semântica ARIA quando aplicável, ordem de
   foco, contraste AA, alvo de toque, alternativa textual, comportamento com teclado e leitor de
   tela. A11y é seção obrigatória, não apêndice.
5. **Defina os critérios de UX testáveis** (ex.: "foco visível em todo controle", "estado de erro
   anuncia mensagem ao leitor de tela") para o @qa conseguir verificar.
6. **Mapeie cada seção da spec a um AC/FR/NFR** da story. Seção órfã sai — é invenção.
7. **Registre a spec** em `docs/stories/{epic}/front-end-spec.md` e roteie: vai para o @dev
   implementar e alimenta `generate-ai-frontend-prompt` / `build-component`.

## Critério de pronto (DoD)

- [ ] Componentes classificados por nível Atomic Design, reuso priorizado
- [ ] Cada componente com anatomia, variantes, estados e comportamento
- [ ] Tokens nomeados em todo valor visual — nenhum hardcoded
- [ ] Seção de acessibilidade WCAG AA por componente
- [ ] Critérios de UX testáveis definidos para o @qa
- [ ] Cada seção rastreia a um AC/FR/NFR; spec registrada em `docs/stories/`

## Falha / recuperação

- **Faltam wireframes** → volto para `ux-create-wireframe` antes de especificar.
- **Não há design tokens** → escrevo a spec referenciando tokens-alvo e registro a pendência de
  `extract-tokens`/`setup-design-system`; não hardcodo para "destravar".
- **Decisão de stack/arquitetura de frontend surge** → delego à Aria (@architect); a spec descreve
  o comportamento de UX, não escolhe a tecnologia.
- **A story não cobre um comportamento que a spec exigiria** → paro, registro a lacuna e devolvo ao
  @sm/@po.