---
id: front-end-spec-tmpl
kind: template
agent: ux-design-expert
produces: docs/design/{feature-ou-produto}-front-end-spec.md
---

# Especificação de Front-End — {nome da feature/produto}

**Status:** Draft
**Origem:** {PRD/spec/story que esta UX serve — ex.: docs/prd/...}
**Plataformas-alvo:** {web / mobile web / app / desktop}

> Esta spec traduz necessidade de usuário em estrutura de interface — fluxos, telas, componentes,
> estados e regras de acessibilidade. Cada decisão aqui rastreia a um FR/NFR/CON ou a um achado de
> pesquisa. Nada de UX inventada: sem fonte, não entra (No Invention).

## Visão Geral de UX

- **Problema do usuário:** {a dor real que esta interface resolve — fonte de pesquisa/PRD}
- **Resultado esperado:** {o que a pessoa consegue fazer ao final — métrica de sucesso se houver}
- **Princípios de design aplicados:** {ex.: clareza > densidade, mobile-first — cada um justificado}

## Personas & Necessidades

> Quem usa, o que precisa, em que contexto. Sem persona validada, marque como hipótese.

| Persona | Necessidade-chave | Contexto de uso | Fonte |
|---|---|---|---|
| {persona} | {o que precisa fazer} | {dispositivo/ambiente/restrição} | {pesquisa/PRD} |

## Fluxos de Usuário

> Cada fluxo é uma jornada com começo, decisões e fim. Liste passos e os pontos onde algo pode falhar.

### Fluxo: {nome do fluxo}
- **Entrada (trigger):** {de onde o usuário chega}
- **Passos:** {1 → 2 → 3, com decisões}
- **Sucesso:** {estado final desejado}
- **Caminhos de erro:** {o que dá errado e como a interface responde}
- **Rastreabilidade:** {AC/FR que este fluxo satisfaz}

## Arquitetura de Informação

- **Mapa de navegação:** {hierarquia de telas/seções e como se conectam}
- **Entradas principais:** {pontos de partida — menu, deep link, dashboard}
- **Agrupamento de conteúdo:** {como a informação é organizada e por quê}

## Inventário de Telas

> Cada tela com seu propósito e o que ela precisa mostrar. O wireframe detalha; aqui é o índice.

| Tela | Propósito | Elementos-chave | Fluxos que a usam |
|---|---|---|---|
| {tela} | {o que resolve} | {componentes/dados essenciais} | {fluxo(s)} |

## Componentes (Atomic Design)

> Mapeie cada elemento de UI ao nível atômico. Reaproveite o design system antes de propor novo.
> Nada de valor hardcoded — cor/espaço/tipografia/raio vêm de design tokens.

| Componente | Nível (átomo/molécula/organismo) | Novo ou existente | Tokens/variantes | Estados |
|---|---|---|---|---|
| {componente} | {nível} | {existente: ref / novo: justificar} | {tokens usados} | {default/hover/focus/disabled/loading/error} |

## Estados & Feedback

> Toda tela tem mais que o estado "feliz". Defina como a interface se comporta em cada situação.

- **Vazio (empty):** {o que mostrar quando não há dados}
- **Carregando (loading):** {skeleton/spinner — sem layout shift}
- **Erro:** {mensagem acionável, não código cru}
- **Sucesso/confirmação:** {feedback claro de que a ação funcionou}

## Acessibilidade (WCAG AA — piso inegociável)

> A11y não é etapa final, é critério de pronto. Estes pontos entram desde o desenho.

- **Contraste:** {alvo AA — 4.5:1 texto normal, 3:1 texto grande/ícones}
- **Foco visível:** {indicador de foco em todo elemento interativo}
- **Navegação por teclado:** {ordem de tab lógica, sem armadilhas de foco}
- **Semântica & leitores de tela:** {roles, labels, alt text, hierarquia de headings}
- **Alvos de toque:** {tamanho mínimo para mobile}
- **Movimento:** {respeitar prefers-reduced-motion quando houver animação}

## Responsividade

- **Breakpoints:** {mobile / tablet / desktop e o que muda em cada um}
- **Estratégia:** {mobile-first / adaptação de layout / conteúdo prioritário por viewport}

## Identidade Visual & Tokens

> Referencie o design system. Se algum token novo for necessário, justifique e marque para extração.

- **Tipografia:** {famílias/escala — via token}
- **Paleta:** {cores semânticas — via token}
- **Espaçamento & raio:** {escala — via token}
- **Iconografia:** {set de ícones e regra de uso}

## Rastreabilidade

> Cada decisão de UX liga à sua origem. Linha sem fonte é UX inventada e não passa no gate.

| Decisão de design | Origem (FR/NFR/CON/pesquisa) |
|---|---|
| {decisão} | {fonte} |

## Itens em Aberto

- {pergunta de design não resolvida, hipótese a validar, dependência de @architect/@dev}