Modelo — Design System (.specs/design/)

Esqueleto da documentação de Design System do projeto. Como toda pasta de .specs/, ela nasce quando uma ADR a cria — tipicamente a ADR que funda o Design System (tokens + tema), seguida da ADR da biblioteca de componentes. A fonte executável dos tokens é o CSS do tema; esta pasta é o espelho legível e o catálogo. Regras em Design System e tokens e padrões em Design (UI/UX).

.specs/design/
├── tokens.md          ← tabela dos tokens (cor, tipografia, espaçamento, raio, sombra)
├── components.md      ← catálogo: cada componente → equivalente shadcn + customização
├── screens.md         ← inventário de telas + referências visuais
└── flows.md           ← fluxos de usuário em Mermaid

Comece por um arquivo por tipo; vire pasta (components/, screens/…) só quando o arquivo crescer a ponto de atrapalhar.

---

.specs/design/tokens.md

# Design tokens

Espelho legível do tema (globals.css). O tema e os componentes derivam dos tokens; não se escreve
cor ou medida direto na UI.

## Cores semânticas
| Token | CSS var | Claro | Escuro | Uso |
|-------|---------|-------|--------|-----|
| Background | `--background` | oklch(…) | oklch(…) | fundo da tela |
| Foreground | `--foreground` | … | … | texto |
| Primary | `--primary` | … | … | ação primária / marca |
| Secondary | `--secondary` | … | … | ação secundária |
| Destructive | `--destructive` | … | … | erro / exclusão |
| Success* | `--success` | … | … | sucesso (extensão) |
| Warning* | `--warning` | … | … | atenção (extensão) |
| Muted | `--muted` | … | … | fundo sutil / desabilitado |
| Accent | `--accent` | … | … | hover / variante tonal |
| Border / Input / Ring | `--border` / `--input` / `--ring` | … | … | bordas, campos, foco |

(*) extensões além do shadcn — entram também no `cva` dos componentes.

## Tipografia
| Token | Fonte | Tamanho | Altura de linha | Peso | Uso |
|-------|-------|---------|-----------------|------|-----|
| heading-1 | … | … | … | … | título de tela |
| body | … | … | … | … | texto padrão |
| label | … | … | … | … | botões, chips, abas |
| caption | … | … | … | … | metadados |

## Espaçamento, raio e sombras
- **Espaçamento:** a escala do Tailwind (base 4).
- **Raio:** `--radius` = … (lg/md/sm derivados).
- **Sombras:** `--shadow-1..4` (E-1 cartões · E-2 cartões elevados · E-3 menus e painéis · E-4 diálogos).

## Ícones
- Biblioteca: `lucide-react` (ou a família decidida na ADR ___).

---

.specs/design/components.md

# Catálogo de componentes

| Componente | Nível | Equivalente shadcn | Customização |
|------------|-------|--------------------|--------------|
| Button | Átomo | `Button` | variante `tonal`, estado `loading`, ícone |
| Badge | Átomo | `Badge` | cores `success`/`warning`, tamanhos |
| Input / Textarea | Átomo | `Input` / `Textarea` | estado de erro |
| … | … | … | … |

Para cada componente próprio, documentar variantes, estados (desabilitado, hover, focus-visible, ativo) e a ligação com os tokens.

---

.specs/design/screens.md

# Inventário de telas

| Tela | Área | Propósito | Estados (vazio / carregando / erro) | Referência |
|------|------|-----------|-------------------------------------|------------|
| Login | Acesso | entrar | … | ../adr/NNN-…/resources/login.png |
| … | … | … | … | … |

---

.specs/design/flows.md

# Fluxos de usuário

## Fluxo: [nome]
```mermaid
flowchart TD
    A[Tela inicial] --> B{Condição?}
    B -->|Sim| C[Próxima tela]
    B -->|Não| D[Tela alternativa]
```

---

Checklist de entrega de tela (na ADR de UI)

Toda ADR que entrega interface declara este checklist como critério de aceite no 003-plan.md e mostra a evidência no 005-relatorio-tecnico.md:

• Tokens existem antes das telas (nada de cor ou medida escrita na UI).
• Estados de tela: vazio, carregando, erro.
• Estados de componente: desabilitado, hover, focus-visible, ativo.
• Responsividade (celular primeiro; larguras conferidas).
• Acessibilidade: contraste, foco visível, teclado, ARIA, prefers-reduced-motion.
• Revisão humana do visual registrada na ADR (capturas em resources/).