# F3.I1.T4 — wiki/DESIGN.md como fonte única visual

| Campo | Valor |
|---|---|
| **Fase** | F3 — Layout & UX |
| **Issue** | F3.I1 — Design system (plano 09) |
| **kd task** | `task_005re7yt` (`closed`) |
| **Âncora** | `wiki/implementation/03-layout-ux.md` |
| **Status da revisão** | 🔧 com correções — A (médio) corrigido; B/C corrigidos; D observação |

## O que foi implementado

- `wiki/DESIGN.md`: fonte única visual (tokens, tipografia, alvos, camadas, componentes, a11y).

## Arquivos para revisar

- `wiki/DESIGN.md`
- `AGENTS.md` (referência de design)
- `wiki/specs/04-acessibilidade-ux.md`

## Pontos de revisão

### PHP 8.4
- [ ] `declare(strict_types=1)`; tipos nativos (union/enum/`readonly`); sem `mixed` desnecessário.
- [ ] Dependências **injetadas** (nenhum `new`/`app()`/`resolve()` no corpo); sem traits/abstract/generics.
- [ ] `match` em vez de cadeias de `if`; `?->`/`??`; sem código morto; PHPStan `max` limpo.

### Laravel 12
- [ ] Nativo primeiro (Eloquent casts/scopes, `FormRequest`, `Gate`, scheduler, events) — sem reimplementar.
- [ ] Sem closure em rota; resources/rotas nomeadas; `config()` só lê, `env()` só em `config/`.
- [ ] Migração **idempotente**; `down()` → `backup_*` (nunca `DROP`); sem `orderBy` cru quando `latest/oldest` serve.

### HTML semântico + a11y (eMAG/WCAG 2.2 AA)
- [ ] Um `<main>`, headings em nível correto, landmarks; só ARIA quando necessário.
- [ ] Alvos ≥ 24 px (≥ 44 px em ponteiro grosso); foco visível; rótulos em todos os campos; contraste (axe).
- [ ] Funciona **sem JS**; `sniffCSS` sem `fail`/`warn` fora do ledger.

### CSS moderno
- [ ] `oklch`, `clamp`, `rem`/`fr`/`dvh`/`%`; `@layer` (a11y por último); `@property`; subgrid com fallback.
- [ ] Sem `!important`, sem `style="…"` inline, sem hex/rgb (exceto justificado); sem CDN.

### Decisões do projeto (ADRs)
- [ ] Respeita a ADR do escopo (ver cabeçalho) e não escapa das demais (001, 002, 004, 013, 015…).
- [ ] Determinismo: relógio/id injetados, ordem explícita, dados idempotentes (ADR-001).

### i18n (ADR-012)
- [ ] Nenhuma string visível fixa; 4 locales com paridade de chaves; `route()`/`localized_url()` (nunca path literal).

### Observabilidade/segurança/testes
- [ ] Span + `log_event('{module}.{action}')` com atributos `scalar|null`, **sem PII** (ADR-024).
- [ ] Teste que falha sem a mudança (vermelho→verde) + evidência no `kd`; `make quality` 2×.

### Específicos desta task

- [ ] O doc reflete o código (tokens/camadas); sem divergência após F4/F5.

## Comandos úteis

```bash
make quality            # lint + PHPStan max + gates + testes
make e2e                # Playwright + axe (se a task toca UI)
make check-boundaries   # fronteiras core/services/layout/modules
```

---

> Revisar contra `AGENTS.md`, `wiki/adr/` e o plano citado. Registrar achados no `kd` (`kd write --anchor`) e, se houver correção, teste de regressão.

## Notas da revisão

| Data | Revisor | Resultado | Observações |
|---|---|---|---|
| 2026-10-17 | agente (protocolo v2.0) | 🔧 | Doc × código cruzado; 1 médio + 2 baixos corrigidos com evidência; 1 baixo no `kd` |

### Evidência
- **Gates (§10):** `make quality-2x` EXIT=0 (402×2) · `make e2e` **79/79** · `SNIFF_A11Y_STRICT=1 make a11y` OK (`fail=0`) · `check-boundaries`/`docs-check` OK.
- **Cruzamento doc×código:** 35 tokens citados no `DESIGN.md` — **nenhum** ausente do CSS (só `--cms-*` são intencionalmente "virtuais", §10). Camadas, daisyUI bridge, z-index, alvos, componentes `cms::*`, `config/design.php` e rotas `theme.css`/`cms-theme.css` **conferem**.

### Achados

| ID | Sev. | Dimensão | Descrição | Disposição |
|---|---|---|---|---|
| **A** | Médio | D14/D6 | §3 promete "medida de leitura **60–75ch**", mas **não havia `ch`** em CSS algum e `typography.css` fixava `.prose { max-inline-size: none }` → medida **não imposta** (medido: **75,5ch** em 1366px e crescendo em telas maiores). | **Corrigido**: `.prose { max-inline-size: 65ch }` + teste `DesignTokensTest::the_prose_reading_measure_stays_within_the_documented_range` (vermelho→verde; 65,0ch). `kd`: `fact_017v23uk`. |
| **B** | Baixo | D14 | §6 dizia `prefers-reduced-motion` "em `@layer overrides`"; o código está em `@layer a11y` (`a11y.css:6`) e o §2 já apontava para `a11y`. | Corrigido o texto. `kd`: `fact_00q61mgq`. |
| **C** | Baixo | D14 | §9 dizia "Alvos ≥ 44px" (sem a nuance), divergindo do §6 e da spec 04 (≥24px sempre; ≥44px em ponteiro grosso). | Corrigido o checklist. `kd`: `fact_00jyknig`. |
| **D** | Baixo | D14 | §10 diz "o tenant só sobrepõe tokens (`--tenant-*`)", mas o schema aceita `font_content` (→ `--font-content`), que não é `--tenant-*`. | Observação (`kd`: `risk_00vh5oe7`). |

> Resultado: `✅ revisado` · `🔧 com correções` · `⏭️ delegado` (com justificativa).