# Plano 09 — Design System (Tailwind 4 + daisyUI + Lucide)

> **Milestone:** M3 · **Depende de:** 08 · **Habilita:** 10–14
> **Objetivo:** criar a base visual única, acessível e tematizável, com tokens
> governados pelo `wiki/DESIGN.md` e consumíveis pelo portal e pelo CMS.

---

## 1. Decisões

- **Tailwind 4 CSS-first**: `@import "tailwindcss";` + `@plugin "daisyui";` no CSS.
- **daisyUI** fornece componentes com semântica (button, modal, tabs, alert…) e temas.
- **Lucide vendorizado**: SVGs locais (npm `lucide-static` ou subset curado) renderizados por
  um componente Blade `<x-ui::icon>`; **sem wrapper composer**. Todo ícone decorativo
  `aria-hidden`, todo ícone com significado recebe `aria-label`/texto.
- **Tokens do tenant** (ADR-016) sobrepõem o tema daisyUI por CSS variables.
- **Modo alto contraste** e **prefers-reduced-motion** como estados de primeira classe.
- **CSS moderno** (ADR-010): Grid/Subgrid, **container queries**, `clamp()` para tipografia
  fluida, `:has()`/`:is()`/`:where()`, `light-dark()`, **`@layer`** (precedência) e
  **`@property`** (custom props tipadas), propriedades lógicas, `oklch()` com fallback e
  View Transitions degradáveis. Recurso novo entra atrás de `@supports`.
- **Vite 8** (Rolldown/Oxc + Lightning CSS): Tailwind 4 CSS-first; só `VITE_*` chega ao
  cliente; code-splitting por rota (`import()`) e `manualChunks` de vendor; assets com
  hash imutável e precompressão brotli/gzip.
- **Tipografia de conteúdo** (ADR-011): default **Atkinson Hyperlegible Next** (legibilidade),
  self-hosted WOFF2 variable, `font-display: swap` + preload + subset e fallback com
  `size-adjust`; **ajustável pelo usuário** na configuração global (token `--font-content`);
  nada de CDN.
- **Semântica primeiro** (ADR-010): usar elementos nativos (`<dialog>`, `<details>`,
  `<button>`, popover) antes de componentes JS; ARIA só quando o nativo não basta.
- **Mínimo JS**: o componente funciona sem JavaScript sempre que possível; JS é
  progressive enhancement.
- **Editor de texto rico** (ADR-028): toolbar e modais seguem os **mesmos tokens/componentes**
  (daisyUI), com botões acessíveis (ícone Lucide + `aria-label` + tooltip) e modais centralizados.
- Proibido `style` inline arbitrário e `z-index` mágico (só tokens de overlay documentados).

### 1.1. Camadas da cascata (`@layer`)

Tailwind 4 já declara `@layer theme, base, components, utilities;`. O projeto **não inventa**
ordem: alinha-se a ela e, quando necessário, adiciona uma camada final explícita:

```css
@layer theme, base, components, utilities, overrides;
```

- Resets/globais → `@layer base` (com `:where()` para especificidade zero).
- CSS de componentes do projeto → `@layer components`.
- Overrides de tema/tenant e exceções → `@layer overrides` (vence `utilities` de forma
  determinística, **sem `!important`**).
- CSS de terceiros via `@import url(...) layer(...)`.
- **Evitar CSS fora de `@layer`** (vence tudo e reintroduz imprevisibilidade); `!important`
  **inverte** a ordem das camadas — só com justificativa. `revert-layer` para voltar à anterior.
- daisyUI encaixa nos layers do Tailwind; customização de componente vai em `overrides`.

## 2. Estrutura

```
src/layout/
├── Assets/
│   ├── css/app.css          # tailwind + daisyui + tokens
│   └── js/app.js
├── Design/
│   ├── Tokens.php           # leitura/exportação de tokens (→ CSS vars)
│   └── Design.php           # API de acesso a tokens
├── Components/              # <x-ui::button>, <x-ui::alert>, <x-ui::icon>...
└── LayoutServiceProvider.php
config/design.php            # defaults + validação de tokens
```

## 3. Tokens (exemplo)

```
--color-primary, --color-secondary, --color-accent, --color-base-100 ... (daisyUI)
--color-link, --color-text-muted, --color-focus, --color-danger
--radius-*, --space-*, --font-content, --font-display, --shadow-*
--color-a11y-highlight (modo alto contraste)
```

Estado canônico: `wiki/DESIGN.md` define o token; só depois ele entra no `Tokens.php`/
`app.css`. Cor sempre em `oklch(... / alpha)` com **fallback hex** em `@supports`;
`color-mix(in oklch, …)` para tons derivados.

**Unidades modernas** (skill `css-moderno`): `clamp()` para tipografia/espaço fluidos —
min/max **sempre em `rem`** e nunca só `vw` (respeita zoom/WCAG 1.4.4); `dvh`/`svh`/`lvh`
no lugar de `100vh`; unidades de container (`cqi`/`cqw`) dentro de container queries;
`ch` para largura legível e `lh` para ritmo vertical. Tailwind 4 cobre via utilitários
(`min-h-dvh`, `text-[clamp(...)]`).

## 4. Atividades

- [ ] `app.css` com tailwind 4 + daisyUI + tema base + tokens do tenant.
- [ ] `wiki/DESIGN.md` com paleta, tipografia, espaçamento, foco, estados, grid e z-index.
- [ ] Vendorizar a fonte de conteúdo (**Atkinson Hyperlegible Next**, WOFF2 variable + licença
      OFL) e expor `--font-content` ajustável na config global (ADR-011).
- [ ] Componentes base (botão, input, label, erro de formulário, alerta, modal,
      tabela, paginação, breadcrumb, skip-link) — todos com teste de a11y.
- [ ] `Design/Tokens.php`: tokens default + merge do tenant + export para `<style>`.
- [ ] Ícones Lucide vendorizados (SVG local) padronizados (tamanho, `aria-hidden`, cor herdada).
- [ ] Pipeline Vite 8 (Tailwind 4 CSS-first + Lightning CSS) + `make check`; fontes
      com `font-display: swap`, preload e subset.
- [ ] Documentar contraste mínimo AA e alvos de toque ≥44px.
- [ ] Ordem de camadas fixada (`@layer theme, base, components, utilities, overrides;`) e
      documentada no `wiki/DESIGN.md`; overrides sem `!important`.
- [ ] Definir o **baseline de browsers** e o uso de `@supports` para recursos modernos
      (container queries, View Transitions, `light-dark()`, `@property`).

## 5. Testes e evidências

- [ ] Snapshot de CSS computado (sniffCSS) para os componentes base.
- [ ] axe: cada componente base passa sem violações (isolado em fixture Blade).
- [ ] Teste: token ausente cai no default e **avisa** (nunca quebra a tela).
- [ ] Teste: override de componente vence `utilities` via `@layer overrides`, sem `!important`.
- [ ] Teste: trocar o tema do tenant muda as CSS vars sem deploy.
- [ ] Teste: alto contraste e `prefers-reduced-motion` ativos por preferência.
- [ ] Teste: zoom de texto a 200% sem quebra (clamp com `rem`; WCAG 1.4.4).

## 6. Definition of Done

- [ ] Componentes base acessíveis, tematizáveis e testados.
- [ ] `wiki/DESIGN.md` é a única fonte de tokens.
- [ ] Nenhum hex/classe mágica fora do design system.

## 7. Riscos

| Risco | Mitigação |
|---|---|
| daisyUI limitar algum padrão | Componente próprio estende, sem quebrar convenção |
| Divergência visual CMS × portal | Mesmos tokens/componentes; isolate de contexto de stacking |
| Geração de CSS grande | Tailwind 4 só emite o usado; auditar no CI |