---
fonte: 01-canonicos/seed-dataviz.md
versao_da_fonte: v0.22
secao: 02
titulo: "Decisões de fundamento — DF1–DF7 (consolidado aprovado em 2026-08-09)"
sequencia: 4 de 12
bytes_do_corpo: 6638
md5_do_corpo: 34f9f1b1c5cfad0de10f54beacec4319
gerado_por: 06-validacao/geradores/gen-camada-ia.py
nota: fatia GERADA — o corpo abaixo é byte a byte o trecho do canônico; edite o canônico, nunca esta fatia. Canônico inteiro em https://ds.seed.eng.br/01-canonicos/seed-dataviz.md
---
## 2. Decisões de fundamento — DF1–DF7 (consolidado aprovado em 2026-08-09)

### DF1 — Por que arquivo canônico próprio

**Decisão:** a dataviz vive em `seed-dataviz.md`, 9º arquivo canônico. O PK passa de 8
para 9 arquivos.

**Racional:** cor de dado não é cor de UI (§1) — regra-mãe própria em conflito direto com
a do `seed-componentes.md`, que além disso já tem 341 KB. Precedente duplo do projeto:
EM0 (e-mail virou canônico próprio pela mesma classe de conflito) e NM5 (iconografia
declarou que expansão de domínio gera arquivo próprio por supersede formal).

**Alternativas descartadas:**
- *Seções novas no `seed-componentes.md`* — contamina a regra-mãe "componente consome
  semântico"; todo leitor futuro passaria a duvidar dela.
- *Fatiar entre `seed-tokens.md` e `seed-componentes.md`* — fragmenta a fonte de verdade
  do domínio; ninguém saberia onde a lei mora.

### DF2 — Canônico agnóstico; consumidor canônico web = shadcn Chart sobre Recharts v3

**Decisão:** este arquivo especifica **anatomia e regras** de forma agnóstica de
biblioteca. O consumidor canônico web é o componente **Chart do shadcn/ui**, construído
sobre **Recharts v3**, consumindo a cadeia `--seed-chart-*` → aliases `--chart-N` do
shadcn — o mesmo padrão GI1 que o Bloco 6 formalizou para os componentes.

**Racional (fatos da rodada de mercado, 2026-08-09):** o shadcn/ui mantém componente
Chart oficial sobre Recharts, com theming nativo por CSS variables, e declara
explicitamente que não embrulha o Recharts — sem lock-in de abstração; upgrade segue o
caminho oficial da lib. Detalhe técnico que o guia de integração (DI) deve gravar: na
migração para Recharts v3, a referência de token mudou para `var(--chart-N)` direto,
**sem** o wrapper `hsl()` antigo. A stack real dos produtos (Lovable = Vite + React +
Tailwind + shadcn) já contém tudo isso.

**Alternativas descartadas:**
- *Especificar EM Recharts* — acopla o canônico à biblioteca; o canônico deve sobreviver
  à troca de lib.
- *D3 puro* — poder máximo que os tipos core não exigem; custo de manutenção real.
- *Chart.js* — fora da stack shadcn/Lovable; obrigaria ponte de theming paralela.

### DF3 — Régua de acessibilidade da fase (4 pisos, todos medidos)

**Decisão:** todo entregável da F5 passa por quatro pisos:

1. **1.4.1 (uso de cor):** cor nunca é o único portador — série se distingue também por
   forma de marcador, espessura ou tracejado; estado (positivo/negativo) também por
   posição, seta ou rótulo. É a escada de mecanismos do §1.12 aplicada ao dado.
2. **1.4.11 (contraste não-textual):** **3:1 medido por script** para elemento de dado
   contra o fundo e para séries/fatias adjacentes entre si (ou borda separadora).
   **Isenção declarada para a escala sequencial/heatmap** — a própria norma isenta
   situações onde mudar a cor muda o significado, com heatmap como exemplo nomeado.
   A isenção tem condições de acompanhamento e gatilho de revisão registrados no
   `seed-tokens.md` v1.4 §3c.
3. **1.4.3 (texto):** rótulo, eixo e legenda ≥4.5:1 — pares aprovados na §3c.
4. **1.1.1 (alternativa):** todo gráfico tem fallback textual — tabela de dados
   semântica (herda EC3 do e-mail e o §40 da web) ou sumário textual do achado.

**Alternativas descartadas:** confiar na percepção sem medir (a errata do rodapé do
e-mail provou o perigo: 4.37 parecia bom e reprovava) · exigir 3:1 dentro da rampa
sequencial (impossível numa escala contínua — a norma mesma isenta).

### DF4 — Grayscale é gate estrutural, não só teste

**Decisão:** todo gráfico canônico deve permanecer **legível em preto-e-branco**. O
preview de cada sub-bloco carrega um modo grayscale acionável, e o gate visual do Rafael
inclui a prova P&B.

**Racional:** serve dois senhores de uma vez — o "aperto de olhos" do método §1.12 e o
impresso da F7 (laudo e relatório de O&M saem em P&B); o sub-bloco DI herda gráficos que
já degradam bem em vez de retrofitar.

**Alternativa descartada:** tratar impresso como retrofit no DI — produziria uma fase
inteira de gráficos web que não degradam.

### DF5 — Régua de validação: 4 camadas

| Camada | O que mede aqui |
|---|---|
| **Estática/jsdom** | Estrutura do SVG, ARIA (role, título/descrição acessível), presença do fallback textual, tokens fantasma |
| **Render (Chrome headless)** | **Volta a protagonista**: geometria real — colisão de rótulos, overflow de legenda a 360px, recorte, cor renderizada |
| **Contraste por script** | `contraste-dataviz.py` sobre as escalas v1.3 e os pares de cada gráfico |
| **Gate visual (Rafael)** | Percepção: grayscale, zoom, "isso conta a história certa?" — não-opcional |

**Racional:** diferente da F4 (Chrome headless não provava nada sobre o motor Word),
gráfico é SVG no navegador — exatamente o território da `suite-render.mjs`, a camada que
pegou os 2 bugs reais do Bloco 6 antes do gate. A lição permanente do projeto se mantém:
suite valida comportamento, geometria é render, percepção é o olho humano.

**Alternativas descartadas:** herdar a régua da F4 (alvo errado) · pular a camada de
render (histórico contra).

### DF6 — Fronteiras declaradas

- **Dashboard/layout de painel = F6.** O shell consome os gráficos daqui; a F5 entrega a
  peça, não o painel.
- **Tempo real, websocket, persistência = produto** (Lovable/Supabase), fora do DS.
- **BI exploratório ad-hoc = fora de escopo** (revisável).
- **Gráfico em e-mail = PNG @2x gerado e hospedado no R2** — o runtime de e-mail não roda
  JS; herda EM5 (SVG proibido) e EM11 (caminho imutável). É assim que o slot do alerta de
  geração (ET5) será servido quando o DM o preencher.

**Racional:** fronteira não-declarada vira expectativa quebrada — lição de todas as fases.
**Alternativas descartadas:** incluir dashboard na F5 (duplicaria o shell da F6) · SVG no
e-mail (proibido pela EM5).

### DF7 — Tokens de dado têm UMA fonte

**Decisão:** os valores das escalas vivem no `seed-tokens.md` (v1.4, §3c) — que é editado
na F5 e, pela regra GI2, fechou na mesma edição a errata aberta do §5 (par info). Este
arquivo **referencia** a §3c e registra as **regras de consumo**; nunca duplica hex.

**Racional:** paleta duplicada = deriva garantida (mesmo racional do EM1 do e-mail — que
resolve por *resolução* porque aquele runtime não tem variável; aqui o runtime tem, então
a resposta é *referência*).

**Alternativa descartada:** tabela espelhada aqui — o problema que o DS existe para matar.

---