---
name: experience-design
description: Planejar UX, UI, CLI/TUI, jornadas, informação, estados, tokens, copy de interface e handoff visual dentro do fluxo SDD. Use em Idea, PRD, Tech Spec, Tasks, Refinement ou Execution quando a feature impactar tela, formulário, dashboard, onboarding, navegação, design system, experiência de terminal ou interação do usuário.
---

# Experience Design SDD

## Objetivo

Ancorar decisões de experiência no produto e na stack real. O output deve ajudar PRD, Tech Spec e Tasks a construir a interface certa, com estados completos, acessibilidade e validação.

## Descoberta obrigatória

Antes de propor UI ou tecnologia:

1. Leia Project Discovery, PRD/Idea e `sdd.config.yaml` quando existirem.
2. Verifique a stack atual: framework, rotas, componentes, estilos, tokens, assets, Storybook, pacote de UI, design system e padrões de estado.
3. Para CLI/TUI, verifique comandos, flags, mensagens, estados de loading, erros, prompts e atalhos.
4. Se não houver frontend, produza design de experiência: jornada, mensagens, estados e contrato de interação.

## Brief enxuto

```md
## Design brief
- Usuário primário:
- Job to be done:
- Superfície impactada:
- Princípios de experiência:
- Anti-referências:
- Restrições:
- Métrica de sucesso:
```

Use no máximo três princípios de experiência. Cada princípio deve resolver uma tensão real, por exemplo: `clareza antes de densidade` ou `recuperação guiada antes de erro genérico`.

## Handoff

Inclua só o que for implementável:

- Estrutura da experiência: fluxo principal, alternativas e interrupções.
- Informação: hierarquia, navegação, agrupamentos e conteúdo real vs placeholder.
- Componentes: existentes a reutilizar, novos, variantes e API esperada.
- Estados: loading, vazio, erro, sucesso, disabled, hover/focus, dados longos e permissões.
- Tokens/estilos: cores semânticas, espaçamento, tipografia, radius, motion e dark mode quando existir.
- Copy: labels, botões, mensagens de erro, confirmação e microcopy.
- Acessibilidade: contraste, foco, teclado, landmarks, labels, alvo de toque e reduced motion.
- Validação: screenshots, teste de interação, E2E/componente, axe/lint quando disponível.

## Integração SDD

- PRD: transforme experiência em requisitos, não em decoração.
- Tech Spec: mapeie componentes, IA, estados, contratos, dados, tokens, acessibilidade e diagramas de planejamento.
- Tasks: gere tarefas por estado/fluxo com critérios Gherkin quando houver comportamento observável.
- Refinement: valide tokens, flags, copy, edge cases e ownership.
- Review: exija evidência visual e funcional antes do checkpoint.

Quando o fluxo ou jornada for difícil de explicar em texto, acione `artifact-diagrams` e produza Mermaid no artefato. Use Excalidraw em `docs/<slug-da-orquestracao>/assets/` quando o planejamento precisar de canvas editável.

## Regras

- Não introduza React, Tailwind, shadcn/ui, Figma, biblioteca de motion ou design system sem evidência da stack atual ou aprovação na Tech Spec.
- Não entregue landing page quando o pedido é ferramenta operacional; priorize fluxo utilizável.
- Não use texto dentro do app para explicar que a feature existe; desenhe controles e estados naturais.
- Não aprove UI sem estados de erro, vazio, loading e acessibilidade mínima.
