# F3.I1.T2 — Tokens em @layer, @property, oklch, clamp (sem !important)

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

## O que foi implementado

- Camadas de tokens: `tokens.css` (base, `@property`, `oklch`, `clamp`), `base.css`, `layout.css`, `fonts.css`, `icons.css`; `@layer a11y` declarado por último.
- Unidades modernas (`rem`/`%`/`fr`/`dvh`/`clamp`); `px` como último recurso.
- Gate `tests/Feature/DesignTokensTest.php` (proíbe `px`/hex/`!important`, exige camadas).

## Arquivos para revisar

- `src/layout/Assets/css/tokens.css`
- `src/layout/Assets/css/base.css`
- `src/layout/Assets/css/layout.css`
- `src/layout/Assets/css/fonts.css`
- `src/layout/Assets/css/icons.css`
- `src/layout/Assets/css/a11y.css`
- `src/layout/Portal/Assets/css/app.css`
- `src/layout/Portal/Assets/css/typography.css`
- `src/layout/Portal/Assets/css/animations.css`
- `src/layout/Portal/Assets/css/print.css`
- `src/layout/Cms/Assets/css/app.css`
- `src/layout/Cms/Assets/css/shell.css`
- `tests/Feature/DesignTokensTest.php`

## 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

- [ ] `@layer` na ordem correta (a11y por último); `@property` só com tipos válidos.
- [ ] daisyUI tematizado pelos tokens (`--tenant-*`, `data-theme="concordia"`, `--border: 0.0625rem`).
- [ ] `DesignTokensTest` cobre também `shell.css` e `editor.css`.

## 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) | 🔧 | 1 alto corrigido (A); 1 médio (B) e 2 observações (C/D) registrados no `kd` |

### Evidência
- **Pint** PASS (489) · **PHPStan max** `No errors` · **PHPUnit** `401/401` · **`make quality-2x`** EXIT=0 (401×2).
- **`make e2e`** 77/77 · **`SNIFF_A11Y_STRICT=1 make a11y`** OK (`fail=0`, 61 warn todos na ledger).

### Achados

| ID | Sev. | Dimensão | Descrição | Disposição |
|---|---|---|---|---|
| **A** | Alto | D6 | `--text-body`/`--text-h1`/`--text-h2` (canônicos no `DESIGN.md` §3) **usados** em `typography.css` mas **nunca definidos** → `var()` sem fallback cai em `inherit` (headings colapsavam). | **Corrigido**: tokens adicionados em `tokens.css` (`@layer theme`) + teste de regressão `DesignTokensTest::every_referenced_token_resolves_or_declares_a_fallback` (vermelho→verde). `kd`: `fact_00r61m2o`. |
| **B** | Médio | D6 | `Cms/Assets/css/shell.css` usa `z-index` cru (30/35/40/45) fora da allowlist `--z-*` (`DESIGN.md` §5); 35/45 sem token. | Abrir **task** no `kd` (`risk_01dxalee`). |
| **C** | Médio | D13 | Lacuna de gate: `DesignTokensTest` não validava resolução de `var()` (por isso A passou). | **Endereçado** pelo teste novo (A). A allowlist de `z-index` (B) segue sem teste. |
| **D** | Baixo | D7 | Alto contraste: `--color-*-content` branco sobre `--tenant-primary/accent` amarelo (~1,2:1) em botões daisyUI. | Observação no `kd` (`risk_00b2hslm`). |

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