zark-design 3.0.4 → 3.2.0

package/README.md

@@ -1,60 +1,135 @@
-# zark-design
+# 🎨 zark-design — Design System anti-cara-de-IA (gerador agnóstico de marca)
 
-> ZARK SAAS Design System — instale via `npx zark-design init` em qualquer projeto.
+> **`npx zark-design init` em qualquer pasta cria um design system completo (HTML + JSX side-by-side) com a sua cor primária e regras explícitas pra IA não gerar UI "cara de IA": sem pill, sem rounded extremo, sem travessão em copy, sem brand color dominante, sem glassmorphism.**
 
-O design system fica como **REFERÊNCIA pra IA**, não como dependência runtime. A IA lê os arquivos JSX + tokens + screenshots e adapta pra qualquer stack (React, Vue, Svelte, Blade, Django templates, HTML puro com Tailwind, etc.).
-
-## Uso
+[![npm version](https://img.shields.io/npm/v/zark-design.svg?style=flat-square&color=f56f10)](https://www.npmjs.com/package/zark-design)
+[![weekly downloads](https://img.shields.io/npm/dw/zark-design.svg?style=flat-square&color=f56f10)](https://www.npmjs.com/package/zark-design)
+[![license](https://img.shields.io/npm/l/zark-design.svg?style=flat-square)](./LICENSE)
 
 ```bash
-# Em qualquer pasta de projeto
-npx zark-design init
-
-# Cria ./design-system/ com:
-#   REFERENCE.md       (cérebro: tokens + primitivos + patterns documentados)
-#   tokens.css         (light + dark themes)
-#   primitives.jsx     (Button, Input, Tag, etc. — referência visual)
-#   components.jsx
-#   layouts.jsx
-#   patterns.jsx
-#   icons.jsx
-#   brand.jsx
-#   foundations.jsx
-#   SHOWCASE.html      (preview offline)
-#   visual-references/ (15 screenshots — ground truth visual)
-#   assets/            (logo + ícone)
+# Custom (recomendado — sua cor de marca + paleta 50→900 gerada automaticamente)
+npx zark-design@latest init --name "MinhaEmpresa" --primary "#3B82F6" --yes
+
+# Preset ZARK de referência (cor #F56F10 + logos ZARK)
+npx zark-design@latest init --preset zark --yes
 ```
 
-Depois, abra a IA na pasta:
+---
+
+## O que é
+
+`zark-design` é um **scaffolder de design system híbrido** parte do ecossistema [ZARK](https://github.com/mayconjordanr/zark-dev). Em modo `preset zark` ele entrega o design system ZARK pronto pra usar (paleta ember, logos, tipografia). Em modo `custom` ele **gera** um design system completo a partir de **1 cor hex** (escala 50→900 calculada via HSL) ou de uma paleta JSON pronta.
+
+A IA (Claude Code, Cursor, Codex) lê os arquivos como **referência visual e estrutural** — não como dependência runtime — e adapta os componentes pra qualquer stack: React, Vue, Svelte, Solid, Blade (Laravel), Django templates, ERB (Rails), HTML puro com Tailwind, CSS modules, styled-components.
+
+### O que vem instalado
 
-```bash
-claude   # ou cursor . / codex / aider
 ```
+design-system/
+├── README.md                  # cérebro pra IA
+├── html/
+│   ├── tokens.css             # light + dark themes
+│   ├── components.css         # 50+ classes utilitárias (.btn, .tag-dot, .stat...)
+│   ├── index.html             # exemplo mínimo
+│   └── showcase.html          # galeria completa (light/dark toggle)
+├── jsx/
+│   ├── tokens.css/.js
+│   ├── components.css
+│   ├── icons.jsx              # 35 ícones outline
+│   ├── App.example.jsx        # exemplo completo
+│   └── components/            # 24 componentes individuais
+└── assets/                    # logos (preset = ZARK; custom = SVG dinâmico com sua cor)
+```
+
+24 componentes individuais: `Button` · `Input` · `Tag` · `TagDot` · `Badge` · `Toggle` · `Segmented` · `Chip` · `Avatar` · `Kbd` · `Spec` · `Panel` · `Section` · `Modal` · `Toast` · `Banner` · `CodeBlock` · `StatCard` · `AlertCritical` · `Funnel` · `KanbanColumn` · `LeadCard` · `EmptyState` · `TableActions` · `Sidebar`. **App Patterns derivados do CRM real ZARK** — não componentes genéricos de portfólio.
 
-A IA detecta `design-system/REFERENCE.md` e usa como fonte de verdade pra qualquer trabalho de UI/frontend.
+---
 
-## Pasta customizada
+## 🚀 Quick start
+
+### Modo preset (ZARK pronto)
+
+```bash
+mkdir meu-projeto && cd meu-projeto
+npx zark-design@latest init --preset zark --yes
+open design-system/html/showcase.html   # vê tudo renderizado no browser
+```
+
+### Modo custom (sua marca)
 
 ```bash
-npx zark-design init ./ui                 # instala em ./ui em vez de ./design-system
-npx zark-design init ./src/zark           # instala em src/zark
+mkdir meu-projeto && cd meu-projeto
+
+# Interativo
+npx zark-design@latest init
+
+# Ou com flags
+npx zark-design@latest init --name "MinhaEmpresa" --primary "#3B82F6" --yes
 ```
 
-## Sobrescrever instalação existente
+A paleta `--brand-50` até `--brand-900` é gerada automaticamente via HSL manipulation a partir da cor primária. Ring focus, tons dark mode e variações suaves também são derivados.
+
+### Listar presets disponíveis
 
 ```bash
-npx zark-design init --force
+npx zark-design@latest presets
 ```
 
-## Integração com `.ai-context/CONTEXT.md` ou `CLAUDE.md`
+---
+
+## Filosofia visual (anti-cara-de-IA)
+
+A paleta é sua. O padrão visual é universal: foge das assinaturas óbvias de UI gerada por IA.
+
+**Visual**
+- Warm + neutral + brand-on-paper. Fundo cremoso quente (`#fafaf8`), nunca branco puro.
+- Cor da marca usada com moderação. Só CTA primário, focus ring, ícone-acento. Nunca background dominante.
+- Sem pill. Raio máx 6px em tags/chips/toggles; 8-12px em cards; 16px em modal. Avatares 50% (círculo geométrico).
+- Hairlines de 1px em `--line-200`. Borders grossos banidos.
+- Sombras warm (`rgba(20, 17, 12, ...)`), nunca frias.
+- Sem glassmorphism, gradiente colorido, neon, blur exagerado.
+
+**Copy**
+- Sem travessão (—) nem en-dash (–) em qualquer texto da UI. Vírgula, ponto, dois-pontos.
+- Sem emoji em label de botão, título de campo, título de página.
+- Frase ≤ 12 palavras em UI. Voz ativa.
+- Sem vocabulário marketing-IA: "transforme", "potencialize", "descubra", "experimente".
+
+**Tipografia**
+- Editorial: Inter (UI) + JetBrains Mono (código) + Space Grotesk (display).
+- Dark mode nativo via `[data-theme="dark"]` ou `prefers-color-scheme`.
+
+---
+
+## Integração com `CLAUDE.md`
+
+Se o projeto já tem ZARK acoplado (via `npx zark-dev start`), o `init` detecta e adiciona automaticamente uma nota em `.ai-context/CONTEXT.md` ou `CLAUDE.md` instruindo a IA a ler `design-system/README.md` antes de qualquer trabalho de UI.
+
+---
+
+## O Ecossistema ZARK
+
+`zark-design` é uma das 4 peças do método [ZARK](https://github.com/mayconjordanr/zark-dev):
+
+- [**`zark-dev`**](https://www.npmjs.com/package/zark-dev) — metodologia + contexto pra IA (orquestra todo o método)
+- **`zark-design`** ← você está aqui
+- [**`zark-seo`**](https://www.npmjs.com/package/zark-seo) — 17 skills SEO/GEO especialistas, foco BR
+- [**`zark-skills`**](https://www.npmjs.com/package/zark-skills) — 5 skills Claude Code user-level
+
+---
+
+## Quem está por trás
+
+[**Maycon Jordan**](https://github.com/mayconjordanr) — fundador da [ZARK](https://grupozark.com.br). Design system derivado do CRM real da ZARK + clientes (Limppetec, AllSec, VipCar, VipSeg, MixShop), refinado em produção.
+
+---
 
-Se o projeto já tem ZARK acoplado (via `zark-dev start` ou `audit`), o `init` adiciona automaticamente uma nota em `CLAUDE.md` ou `.ai-context/CONTEXT.md` instruindo a IA a ler o `REFERENCE.md` antes de qualquer UI.
+## Tags
 
-## Filosofia
+`zark` `design-system` `zark-design-system` `react-design-system` `html-design-system` `dual-implementation` `dark-mode` `design-tokens` `tailwind-alternative` `palette-generator` `app-patterns` `crm-ui` `brazil` `pt-br` `metodologia-zark`
 
-ZARK é warm + neutral + ember-on-paper. Cor de marca: Liquid Lava (`#f56f10`).
-Os primitivos JSX são **referência estrutural** — adapte pra stack alvo, nunca copie literal.
+---
 
 ## Licença
 
-MIT — Maycon Jordan
+[MIT](./LICENSE) — Maycon Jordan / ZARK · 2026

package/bin/cli.js

@@ -202,15 +202,18 @@ function printHelp(version) {
   console.log(`    ${c.green('help')}             mostra esta ajuda`);
   console.log(`    ${c.green('version')}          mostra a versão\n`);
   console.log(`  ${c.bold('Modos:')}`);
-  console.log(`    ${c.green('preset ZARK')}       paleta + logos ZARK prontos (Liquid Lava #F56F10)`);
-  console.log(`    ${c.green('custom')}            sua cor primária + suas logos\n`);
-  console.log(`  ${c.bold('Uso interativo:')}`);
-  console.log(`    npx zark-design init                       ${c.dim('# pergunta tudo')}`);
+  console.log(`    ${c.green('custom')} ${c.dim('(padrão)')}    sua cor primária → paleta 50→900 gerada via HSL`);
+  console.log(`    ${c.green('preset ZARK')}       configuração pronta de referência (Liquid Lava #F56F10)\n`);
+  console.log(`  ${c.bold('Uso custom (recomendado — sua marca):')}`);
+  console.log(`    npx zark-design init                                           ${c.dim('# pergunta tudo')}`);
+  console.log(`    npx zark-design init --name "MinhaEmpresa" --primary "#3B82F6" --yes`);
+  console.log(`    npx zark-design init --palette ./minha-paleta.json --yes\n`);
+  console.log(`  ${c.bold('Uso preset ZARK:')}`);
   console.log(`    npx zark-design init --preset zark         ${c.dim('# usa ZARK direto')}`);
   console.log(`    npx zark-design init --preset zark --yes   ${c.dim('# sem confirms')}\n`);
-  console.log(`  ${c.bold('Uso custom (flags):')}`);
-  console.log(`    npx zark-design init --name "ALLSEC" --primary "#E74C3C" --yes`);
-  console.log(`    npx zark-design init --palette ./minha-paleta.json --yes\n`);
+  console.log(`  ${c.bold('Filosofia:')}`);
+  console.log(`    Anti "cara de IA": sem pill, sem rounded extremo, sem travessão em copy, sem`);
+  console.log(`    brand color dominante, sem glassmorphism. App patterns derivados de CRM real.\n`);
   console.log(`  ${c.bold('Output:')}`);
   console.log(`    design-system/                  ${c.dim('# default; mude com [pasta]')}`);
   console.log(`      ├── README.md`);
@@ -298,15 +301,15 @@ async function buildCtx({ flags, prompt }) {
       fonts: { ui: 'Inter', mono: 'JetBrains Mono', display: 'Space Grotesk' },
     };
   }
-  // 4) Interativo
+  // 4) Interativo — modo custom é o padrão (sua marca, sua cor)
   if (!prompt) throw new Error('Modo interativo precisa de TTY. Use --preset zark ou --primary <hex>.');
   console.log(c.dim('  Pressione Enter pra usar o default em parênteses.\n'));
-  const usePreset = await prompt.yn('Usar preset ZARK pronto?', true);
-  if (usePreset) return await loadPreset('zark');
+  const useCustom = await prompt.yn('Customizar com sua cor de marca?', true);
+  if (!useCustom) return await loadPreset('zark');
 
   const name = await prompt.ask('Nome do projeto/empresa:', 'Custom');
   const slug = await prompt.ask('Slug (lowercase, sem espaços):', slugify(name));
-  const primary = await prompt.ask('Cor primária (hex, ex: #E74C3C):');
+  const primary = await prompt.ask('Cor primária (hex, ex: #3B82F6):');
   if (!primary) throw new Error('Cor primária é obrigatória.');
   const palette = generatePalette(primary);
   return {
@@ -425,7 +428,7 @@ async function runInit(args) {
 }
 
 async function appendNoteToContextFiles(targetRoot, designDirName, ctx) {
-  const note = `\n\n## Design system\nEste projeto usa o **${ctx.name} Design System** (gerado por \`zark-design\`${ctx.preset ? `, preset ${ctx.preset}` : ', modo custom'}). Antes de qualquer trabalho de UI/frontend, leia \`${designDirName}/README.md\`.\n\n2 implementações lado a lado consumindo \`tokens.css\` + \`components.css\` idênticos:\n- \`${designDirName}/html/\` — HTML puro (Blade/Django/Rails/HTML)\n- \`${designDirName}/jsx/\` — React (24 componentes individuais)\n\nVue/Svelte/Solid: use \`tokens.css\` + \`components.css\` direto, adapte os JSX mantendo as classes.\n\nCor de marca: \`var(--brand-500)\` = ${ctx.brand['500']}. Abra \`${designDirName}/html/showcase.html\` no browser pra inspeção visual.\n`;
+  const note = `\n\n## Design system\nEste projeto usa o **${ctx.name} Design System** (gerado por \`zark-design\`${ctx.preset ? `, preset ${ctx.preset}` : ', modo custom'}). Antes de qualquer trabalho de UI/frontend, leia \`${designDirName}/README.md\` — em especial o bloco "LEIA ANTES DE GERAR UI (regras anti-IA-genérica)".\n\n**Regras críticas resumidas (detalhes no README):**\n- Sem pill (border-radius 999px / --r-pill). Tag/chip/toggle: raio máx 6px. Avatar 50%.\n- Sem rounded extremo. Card 8-12px, modal 16px máx. Botão 6px.\n- Sem travessão (—) nem en-dash (–) em copy/UI/labels. Use vírgula, ponto, dois-pontos.\n- Sem emoji em label de botão, título de campo, título de página.\n- Sem brand color como background dominante. Use \`var(--paper)\` / \`var(--canvas)\`.\n- Sem hex hardcoded. SEMPRE \`var(--brand-500)\` (= ${ctx.brand['500']}) ou tokens.\n- Sem sombra fria. Use as warm \`rgba(20,17,12,...)\` dos tokens.\n\n2 implementações lado a lado consumindo \`tokens.css\` + \`components.css\` idênticos:\n- \`${designDirName}/html/\` — HTML puro (Blade/Django/Rails/HTML)\n- \`${designDirName}/jsx/\` — React (24 componentes individuais)\n\nVue/Svelte/Solid: use \`tokens.css\` + \`components.css\` direto, adapte os JSX mantendo as classes.\n\nReceitas prontas (botão, card, KPI, formulário, status, empty state, alerta, toast) na seção "Receitas prontas" do README. Comece daí em vez de inventar do zero.\n\nAbra \`${designDirName}/html/showcase.html\` no browser pra inspeção visual.\n`;
   const candidates = [
     path.join(targetRoot, '.ai-context', 'CONTEXT.md'),
     path.join(targetRoot, 'CLAUDE.md'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zark-design",
-  "version": "3.0.4",
-  "description": "Design system scaffolder seguindo método ZARK — `npx zark-design init` em modo preset (ZARK pronto) ou custom (cor e logos suas, paleta 50→900 gerada). HTML + JSX side-by-side. Dark mode nativo. Sem dependência runtime.",
+  "version": "3.2.0",
+  "description": "Design system scaffolder anti-cara-de-IA. `npx zark-design init` gera um DS completo a partir da sua cor primária (paleta 50→900 via HSL) ou usa o preset ZARK. Regras explícitas pra IA: sem pill, sem rounded extremo, sem travessão em copy, sem brand color dominante, sem glow/shine/gradiente, botões fiéis aos padrões canônicos. Inclui paleta validada de data viz (8 slots categoricos CVD-safe, sequential, diverging, status) + receitas de estados (skeleton, tooltip, tabela, meter, sparkline). HTML + JSX side-by-side. Dark mode nativo. Sem dependência runtime.",
   "type": "module",
   "bin": {
     "zark-design": "bin/cli.js"
@@ -20,7 +20,16 @@
     "ai-context",
     "scaffold",
     "tokens",
-    "ui"
+    "ui",
+    "anti-ai-look",
+    "palette-generator",
+    "dark-mode",
+    "brand-agnostic",
+    "data-viz",
+    "dataviz",
+    "charts",
+    "cvd-safe",
+    "categorical-palette"
   ],
   "author": "Maycon Jordan",
   "license": "MIT",

package/templates/README.md.hbs

@@ -6,6 +6,41 @@ Versão: **v3 · {{date}}** · gerado por `npx zark-design init{{#if preset}} --
 
 ---
 
+## ⚠️ LEIA ANTES DE GERAR UI (regras anti-IA-genérica)
+
+Este design system existe pra **fugir do "cara de IA"**. Se você é uma IA gerando UI ou copy pra este projeto, siga estas regras SEM EXCEÇÃO:
+
+### Visual
+- ❌ **Nada de pill como indicador.** Tag, badge, chip, toggle: raio máximo `var(--r-md)` (6px). Pill (`border-radius: 999px`, `9999px`, `--r-pill`) está banido. Único uso de raio 50%: **avatar circular** e **status dot** (8px).
+- ❌ **Nada de bordas extremamente arredondadas.** Cards, panels, modals: raio máximo `var(--r-2xl)` (16px) pra modal, `var(--r-xl)` (12px) pra card grande, `var(--r-lg)` (8px) pra card padrão. Botões: `var(--r-md)` (6px), nunca mais. Se você está pensando em `border-radius: 24px+`, **pare**.
+- ❌ **Nada de glow, shine, drop-shadow colorido, gradiente colorido, glassmorphism, neon, blur exagerado.** Assinaturas óbvias de UI gerada por IA. Sombra é warm (`rgba(20, 17, 12, ...)`), 1 camada, discreta. Sem `filter: drop-shadow(0 0 12px brand-500)`. Sem `text-shadow` colorido. Sem `backdrop-filter: blur()` como decoração.
+- ❌ **Brand color dominante.** A cor de marca (`var(--brand-500)`) só aparece em: CTA primário, focus ring, link, ícone-acento. Nunca como background de tela inteira, hero, card. Use neutros warm pro grosso (`--paper`, `--canvas`, `--surface`).
+- ❌ **Hex hardcoded** (`#f56f10`, `#3B82F6`). SEMPRE `var(--brand-500)` ou variável do token.
+- ❌ **Border-radius percentual aleatório** (`30%`, `40%`). Só `50%` pra círculos geométricos.
+- ❌ **Botão inflado, botão gigante, botão com gradiente ou brilho.** Botão é `.btn` + variante + tamanho. Ponto. Ver seção "Fidelidade aos padrões de botão" abaixo.
+- ❌ **Container arredondado grande com padding grande e sombra pesada.** Esse combo é o "cara de landing page gerada por IA". Card ZARK tem hairline 1px + `--shadow-sm` + raio ≤ 12px.
+
+### Copy / texto gerado
+- ❌ **NUNCA use travessão (—) ou en-dash (–) em texto da UI ou copy gerada.** É a assinatura mais óbvia de texto de IA. Use:
+  - **vírgula** quando a pausa for curta
+  - **dois-pontos** quando o que vem depois explica o anterior
+  - **ponto final** quando o pensamento acabou
+  - **parênteses** ou nova linha pra aposto/extensão
+- ❌ Nada de "Não apenas X, mas também Y" / "It's not just A — it's B".
+- ❌ Nada de bullet com travessão na frente. Use traço simples `-` ou ponto `•`.
+- ❌ Frases longas com 3 vírgulas + travessão + "ou seja". Texto direto: sujeito, verbo, complemento.
+- ✅ Exemplo ruim: "Esta plataforma oferece — além da automação — recursos avançados de análise, que permitem decisões mais estratégicas."
+- ✅ Exemplo bom: "Plataforma com automação e análise. Decisões mais rápidas."
+
+### Layout
+- Hairlines de 1px em `var(--line-200)`. Nunca borders grossos (2px+) em componentes de UI.
+- Espaçamento múltiplo de 4px (use os tokens `--sp-*`).
+- Animação ≤ 280ms. Microinterações ≤ 180ms. Nada de `bounce` exagerado.
+
+> Estas regras estão refletidas em `tokens.css` (não há `--r-pill`) e `components.css` (todos os componentes seguem). Se você sentir necessidade de quebrar alguma, **fale com o humano antes**.
+
+---
+
 ## Estrutura
 
 ```
@@ -63,13 +98,14 @@ design-system-apps/
 
 ## Filosofia
 
-**Warm, neutral, ember-on-paper.**
-- `--paper` (#fafaf8) cremoso, NÃO branco puro.
-- `--brand-500` (#f56f10 — Liquid Lava) é a única cor de marca. Use com **moderação** em CTAs, focus, brand moments.
+**Warm, neutral, brand-on-paper.**
+- `--paper` (#fafaf8) cremoso, NÃO branco puro. Fundo dominante é sempre neutro warm.
+- `--brand-500` ({{brand.500}}) é a sua cor de marca, gerada da paleta 50→900 a partir da primária. **A paleta é sua** — o sistema é agnóstico: troque a cor primária via `npx zark-design init --primary "#SUACOR"` e tudo se recalcula (50→900 + ring + dark mode). O preset ZARK é só uma das infinitas configurações.
+- Cor de marca usada com **moderação**: CTA primário, focus ring, link, ícone-acento. Nunca background dominante.
 - Hairlines de 1px em `--line-200`. Nunca borders grossos.
 - Sombras warm (`rgba(20,17,12,...)`), nunca azuis-frias.
-- Tipografia editorial: **Inter** pra UI e números · **JetBrains Mono** pra código e labels · **Space Grotesk** pra títulos.
-- **Sem pill.** Tags, chips, toggles, badges usam raio sm/md (4-6px). Avatares usam 50% (são círculos geométricos, não pills).
+- Tipografia editorial: **{{fonts.ui}}** pra UI e números · **{{fonts.mono}}** pra código e labels · **{{fonts.display}}** pra títulos.
+- **Sem pill, sem rounded extremo.** Tags, chips, toggles, badges usam raio sm/md (4-6px). Avatares usam 50% (círculos geométricos, não pills). Veja o bloco anti-IA no topo.
 
 ---
 
@@ -224,6 +260,460 @@ function Dashboard() {
 
 ---
 
+## Fidelidade aos padrões de botão
+
+> Botão é o componente mais copiado errado. Aqui a IA usa **o que existe**, não inventa variante nova.
+
+### Variantes canônicas (as únicas permitidas)
+
+| Classe | Uso |
+|---|---|
+| `.btn-primary` | **UMA** ação principal do bloco/modal/página. Brand color no bg. |
+| `.btn-secondary` | Ação alternativa lado a lado do primary. Surface + hairline. |
+| `.btn-soft` | Ação secundária sem competir visualmente. `--brand-50` bg, `--brand-700` texto. |
+| `.btn-ghost` | Ação terciária, discreta. Sem bg, sem borda até hover. |
+| `.btn-danger` | Ação destrutiva. Texto vermelho em fundo branco, hover vermelho suave. |
+
+### Tamanhos canônicos (as únicas permitidas)
+
+| Classe | Altura | Uso |
+|---|---|---|
+| `.btn-xs` | 22px | Dentro de tabela, chip menu, breadcrumb. |
+| `.btn-sm` | 28px | Botão dentro de card compacto. |
+| `.btn-md` | 32px | **Padrão.** 95% dos casos. |
+| `.btn-lg` | 40px | Formulário grande, modal principal. |
+
+Sem `xl`, `2xl`, `huge`. Sem `w-full` gigante. Sem `py-6`, `py-8`.
+
+### Regras rígidas
+- ❌ **Nunca invente uma variante nova** (`btn-gradient`, `btn-glow`, `btn-outline-primary`, `btn-3d`, `btn-hero`). Se você acha que precisa, você não precisa.
+- ❌ **Nunca 2 primários no mesmo bloco.** UM primário. Outros são secondary, soft, ghost.
+- ❌ **Nunca botão com gradiente colorido**, glow, box-shadow colorido, `text-shadow`, `filter: drop-shadow`.
+- ❌ **Nunca botão com ícone gigante ou emoji-hero**. Ícone de botão é 14px `.btn-md`, 12px `.btn-sm`.
+- ❌ **Nunca botão com raio > `var(--r-lg)` (8px)**. `.btn-md` é 6px, `.btn-lg` é 8px. Chega.
+- ❌ **Nunca botão sem uma das classes de tamanho** (`.btn-xs/sm/md/lg`). Isso não é opção; é obrigatório.
+- ✅ Ícone à esquerda ou direita: `<button class="btn btn-primary btn-md"><svg>…</svg> Salvar</button>`. Gap padrão 6px vem da classe.
+- ✅ Loading: `<button class="btn btn-primary btn-md" disabled><span class="spinner"></span> Salvando…</button>`. Spinner CSS já existe.
+
+### Exemplo do que NÃO fazer
+
+```html
+<!-- ❌ HORROR: variante inventada, gigante, gradiente, glow -->
+<button style="background: linear-gradient(90deg, #f56f10, #ff8f30);
+               color: white; padding: 16px 32px; border-radius: 999px;
+               font-size: 20px; box-shadow: 0 0 24px #f56f10;
+               font-weight: 800; text-transform: uppercase;
+               letter-spacing: 0.1em;">
+   ✨ COMEÇAR AGORA
+</button>
+```
+
+Cara-de-IA em 8 sinais: gradient, pill (999px), padding inflado, fonte grande, glow shadow, uppercase, letter-spacing marketing, emoji de foguete/estrela em CTA.
+
+```html
+<!-- ✅ CERTO -->
+<button class="btn btn-primary btn-md">Começar</button>
+```
+
+---
+
+## Receitas prontas (copy-paste, HTML)
+
+> Padrões testados em produção. Comece daqui em vez de inventar do zero.
+
+### Botão primário + secundário (ação padrão)
+
+```html
+<div style="display:flex; gap:8px;">
+  <button class="btn btn-primary btn-md">Salvar</button>
+  <button class="btn btn-secondary btn-md">Cancelar</button>
+</div>
+```
+
+Regra: **um** primário por bloco/modal. Outros viram secondary, soft ou ghost.
+
+### Botão de perigo (ação destrutiva)
+
+```html
+<button class="btn btn-danger btn-md">Excluir conta</button>
+```
+
+Não é vermelho dominante; é texto vermelho em fundo branco com hover suave (`--danger-50`). Vermelho cheio só em `.alert-critical` (banner de erro imediato).
+
+### Card básico (panel)
+
+```html
+<div class="panel">
+  <div class="panel-head">
+    <div class="panel-title">Resumo do mês</div>
+    <div class="panel-kicker">Atualizado agora</div>
+  </div>
+  <div class="panel-body">
+    Conteúdo do card. Texto direto, sem travessão.
+  </div>
+</div>
+```
+
+Raio `var(--r-lg)` (8px). Hairline 1px em `--line-200`. Sombra `--shadow-sm`. Sem gradiente, sem glassmorphism.
+
+### Card KPI (StatCard)
+
+```html
+<div class="stat">
+  <div class="stat-head">
+    <span class="stat-label">CONCLUÍDAS · SEMANA</span>
+    <span class="stat-icon green">✓</span>
+  </div>
+  <div class="stat-value">8</div>
+  <div class="stat-sub">+18% vs anterior</div>
+</div>
+```
+
+Label em uppercase `--ls-widest`. Valor em display font. Sub-texto pequeno, com cor neutra.
+
+### Formulário (campo + label + erro)
+
+Use o primitivo `.input` com HTML semântico. Label acima do input, help text abaixo. Sem classes inventadas — o sistema é minimalista, você compõe com flex/grid e tokens:
+
+```html
+<label style="display:flex; flex-direction:column; gap:6px; max-width:360px;">
+  <span style="font-size:var(--fs-sm); font-weight:500; color:var(--ink-700);">Email</span>
+  <span class="input input-md">
+    <input type="email" placeholder="voce@exemplo.com"/>
+  </span>
+  <span style="font-size:var(--fs-xs); color:var(--ink-400);">Usaremos pra notificações importantes.</span>
+</label>
+
+<label style="display:flex; flex-direction:column; gap:6px; max-width:360px; margin-top:16px;">
+  <span style="font-size:var(--fs-sm); font-weight:500; color:var(--ink-700);">Senha</span>
+  <span class="input input-md invalid">
+    <input type="password"/>
+  </span>
+  <span style="font-size:var(--fs-xs); color:var(--danger-700);">Mínimo 8 caracteres.</span>
+</label>
+```
+
+Erro = `.input` com classe `.invalid` (borda vermelha) + help em `var(--danger-700)`. Help text curto, direto, sem travessão.
+
+### Status (TagDot) — quando há fluxo
+
+```html
+<span class="tag-dot s-todo">A FAZER</span>
+<span class="tag-dot s-progress">EM ANDAMENTO</span>
+<span class="tag-dot s-review">EM REVISÃO</span>
+<span class="tag-dot s-done">CONCLUÍDO</span>
+<span class="tag-dot s-canceled">CANCELADO</span>
+```
+
+Use `tag-dot` (raio 4px) **NUNCA** `border-radius: 999px`. Texto sempre uppercase, weight 600.
+
+### Empty state (quando lista vazia)
+
+```html
+<div class="empty-state">
+  <div class="ico">📭</div>
+  <div class="text">Nenhum lead ainda.</div>
+  <button class="btn btn-primary btn-sm">Adicionar primeiro lead</button>
+</div>
+```
+
+Sem ilustração 3D, sem gradiente. Ícone simples + CTA único.
+
+### Alerta crítico (ação imediata)
+
+```html
+<div class="alert-critical">
+  <div class="alert-critical-head">⚠ Atenção necessária</div>
+  <div class="alert-critical-list">
+    <div class="alert-critical-row">
+      <span>3 leads sem follow-up há mais de 7 dias.</span>
+      <span class="src">crm/pipeline</span>
+    </div>
+    <div class="alert-critical-row">
+      <span>Limite de envios próximo do teto mensal.</span>
+      <span class="src">billing</span>
+    </div>
+  </div>
+  <div class="alert-critical-foot">2 itens · revisar agora</div>
+</div>
+```
+
+Único componente onde vermelho é background dominante. Use SÓ pra coisa que precisa ação humana imediata.
+
+### Toast (feedback rápido)
+
+```html
+<div class="toast toast-success">Salvo.</div>
+<div class="toast toast-danger">Falhou ao salvar.</div>
+```
+
+Texto curto. **Uma frase.** Sem "Operação realizada com êxito! 🎉" — direto.
+
+---
+
+## Regras de copy (texto da UI)
+
+Quando a IA gera **labels de botão, mensagens, placeholders, títulos**:
+
+| Faça | Não faça |
+|------|----------|
+| "Salvar" | "Salvar alterações no sistema agora" |
+| "Email inválido." | "O endereço de email fornecido não atende — é inválido." |
+| "Adicionar lead" | "✨ Crie seu próximo lead com nossa IA! 🚀" |
+| "Limite atingido." | "Você atingiu o limite — entre em contato com nosso time" |
+| "8 concluídas hoje" | "Olha só — você concluiu 8 tarefas hoje, parabéns!" |
+
+**Princípios:**
+1. Sem travessão (—) nem en-dash (–). Use vírgula, ponto ou dois-pontos.
+2. Sem emoji em label de botão / título de campo. Emoji só em empty state, toast informativo, ou banner.
+3. Frases ≤ 12 palavras em UI. Se passou, quebra ou corta.
+4. Voz ativa. Sujeito + verbo + complemento. "Você concluiu 8" não "Foram concluídas 8 por você".
+5. Sem "experimente", "descubra", "transforme", "potencialize" — vocabulário de landing page de IA, não app real.
+
+---
+
+## Data viz (gráficos, KPIs, tabelas)
+
+> Regras derivadas de método validado. Se você é IA gerando dashboard, siga na ordem abaixo. Cor vem por último.
+
+### 1. Decida a forma ANTES de escolher cor
+
+| Os dados são… | Use | NÃO use |
+|---|---|---|
+| Um número atual (+ trend) | `.stat` (StatCard: value + delta + sparkline) | Um bar chart de 1 barra |
+| 3 a 6 KPIs em fila | KPI row de `.stat` | Grouped bar |
+| A one number que o dashboard lidera | Hero figure (≥48px, mesma fonte do resto) | — |
+| Uma razão contra limite | Meter (barra com progresso, mesma cor) | Pie de 2 fatias |
+| Mais de ~7 categorias com significado | Tabela (ou tabela + chart) | Mais cores |
+
+Se um chart *é* certo, escolha por trabalho:
+
+| Trabalho | Forma default | Cor |
+|---|---|---|
+| Comparar magnitude (low→high) | bar / column (heatmap pra grid) | sequential (1 hue) |
+| Trend ao longo do tempo | line (area pra 1 série) | sequential ou 1 categorical |
+| Distinguir séries distintas | grouped/stacked bar, multi-line | **categorical** |
+| Uma série é o ponto, resto é contexto | **emphasis** (1 destacada, resto cinza) | 1 hue + cinza |
+| Acima/abaixo de baseline; delta a target | diverging bar, line vs baseline | diverging |
+| Part-to-whole | stacked bar (horizontal se muitas categorias) | categorical |
+
+### 2. Aplique as regras não-negociáveis
+
+- **Uma escala Y só.** Nunca dual-axis (dois eixos Y na mesma view). Duas medidas de escalas diferentes = 2 charts, small multiples, ou index 100 na origem.
+- **Cor segue a entidade, não o rank.** Filtrar remove série; sobrevivente mantém sua cor. Nunca recolor-on-filter.
+- **8 slots categóricos, ordenados por CVD-safety.** O 9º nunca é gerado; vira "Outros" ou small multiples.
+- **Sequential = 1 hue, mais-é-escuro.** Nunca rainbow. Nunca ramp em categoria nominal.
+- **Diverging = 2 hues opostos + neutro cinza no meio.** blue↔red, blue↔orange (nunca blue↔aqua: ambos frios).
+- **Status colors são reservados.** Sucess/warning/critical nunca viram "série 4". Sempre ícone + label, cor nunca sozinha.
+
+### 3. Paleta ZARK de data viz (tokens novos)
+
+Categorical — os 8 slots, na ordem obrigatória. Slot 1 é o default pra 1 série; nunca cicla:
+
+| Slot | Hue | Light (`--paper`) | Dark (`--bg-void`) |
+|---|---|---|---|
+| 1 | blue | `#2a78d6` | `#3987e5` |
+| 2 | aqua | `#1baf7a` | `#199e70` |
+| 3 | yellow | `#eda100` | `#c98500` |
+| 4 | green | `#008300` | `#008300` |
+| 5 | violet | `#4a3aa7` | `#9085e9` |
+| 6 | red | `#e34948` | `#e66767` |
+| 7 | magenta | `#e87ba4` | `#d55181` |
+| 8 | orange (viz) | `#eb6834` | `#d95926` |
+
+Tokens: `--viz-cat-1` até `--viz-cat-8` (definidos em `tokens.css`).
+
+> **Importante.** O laranja do slot 8 (`--viz-cat-8`) NÃO é o brand ember `--brand-500` (#f56f10). São cores diferentes. A ember é *reservada* pra CTA/focus/link e **nunca é cor de série**. Se você renderiza um chart com uma série ember, você confunde a marca.
+
+Sequential (blue, light→dark) — pra magnitude contínua (heatmap, choropleth, ordinal ramp):
+
+| Step | Hex | Uso |
+|---|---|---|
+| 100 | `#cde2fb` | valor perto de zero (recessivo) |
+| 200 | `#9ec5f4` | |
+| 300 | `#6da7ec` | |
+| 400 | `#3987e5` | |
+| 500 | `#256abf` | valor médio |
+| 600 | `#184f95` | |
+| 700 | `#0d366b` | valor alto |
+
+Tokens: `--viz-seq-100` … `--viz-seq-700`.
+
+Diverging: usa slots `--viz-cat-1` (blue = positivo) ↔ `--viz-cat-6` (red = negativo) + `--line-100` (neutro do próprio ZARK) no meio.
+
+Status: reusa os tokens semânticos ZARK (`--success-500`, `--warning-500`, `--danger-500`, `--info-500`). **Sempre com ícone + label.** Nunca cor sozinha.
+
+### 4. Marcas (specs de renderização)
+
+- **Traços finos.** Line 2px, marker ≥8px, bar-end com raio 4px arredondado só no topo (ancorado à baseline).
+- **2px de gap surface entre fills.** Stacked bar segments E adjacent bars. Nunca border escuro pra separar.
+- **Grid/eixos = hairlines sólidos.** 1px, cor `--line-200` (light) / `--line-300` (dark). Nunca tracejado (parece "projeção").
+- **Labels seletivos.** Direct label o endpoint / o extremo / a série que importa. **Legenda sempre presente pra ≥ 2 séries** (nenhuma pra 1 — o título nomeia a série). Nunca número em todo ponto.
+- **Texto usa tokens de ink**, nunca a cor da série. Valor/label/legenda ficam em `--ink-700` / `--ink-500` / `--ink-400`. A cor identifica; o texto não repete.
+- **Sem dual-axis.** (Anti-pattern #1.)
+- **Sem `overflow: hidden` cortando label dentro de bar.** Se label não cabe, joga fora do bar ou pra tooltip.
+
+### 5. Interação padrão
+
+- Line/area → **crosshair + tooltip** ao passar o mouse.
+- Bar/dot/cell → tooltip per-mark.
+- Hit area ≥ 24px (não o tamanho visual do mark).
+- Filters ficam em UMA linha acima de TODOS os charts. Nunca dentro do card do chart.
+- Skeleton flash em refetch: NÃO. Mantém o render anterior a 60% opacity até o novo chegar.
+
+### 6. Anti-patterns (checar TODO chart contra)
+
+- ❌ **Dual-axis** (2 escalas Y). Corrige com 2 charts ou index 100.
+- ❌ **Recolor-on-filter.** Cor segue entidade.
+- ❌ **9ª cor gerada.** Vira "Outros".
+- ❌ **Ramp de valor em categoria nominal.** 1 série = 1 cor (slot 1).
+- ❌ **Rainbow sequential.** 1 hue, light→dark.
+- ❌ **Hue no meio do diverging** ou 2 hues frios como polos.
+- ❌ **Status color como série 4** ou série color como status.
+- ❌ **1-bar bar chart** ou **2-slice pie**. Use stat tile.
+- ❌ **Donut/pie pra comparar valores próximos.** Use bar.
+- ❌ **Grid pesado, bar grosso, sem breathing room.** Reads loud.
+- ❌ **Tracejado** em grid ou axis. Solid hairline.
+- ❌ **Número em cada ponto.** Direct label seletivo + tooltip.
+- ❌ **Display font ou serif no hero figure.** Usa a mesma sans do sistema.
+- ❌ **`tabular-nums` em número grande.** Só em coluna de tabela e ticks de eixo.
+- ❌ **Texture on by default.** Só opt-in (a11y, print, forced-colors), 45°/135° apenas.
+- ❌ **Tooltip como único jeito de ler valor.** Tem que ter label OU tabela.
+
+### 7. Bibliotecas recomendadas
+
+Sem preferência dogmática — a IA escolhe conforme stack:
+
+- **React (recomendado):** `recharts` (leve, declarativo, defaults sanos) ou `visx` (mais controle, low-level).
+- **HTML/vanilla:** `chart.js` (aceitável se cuidar da config) ou D3 direto pra controle total.
+- **Se stack é Blade/Django/Rails:** renderize server-side um SVG, ou use `chart.js` via CDN.
+- **Nunca:** Highcharts (licença), ApexCharts (defaults barulhentos), qualquer lib que renderiza 3D por default.
+
+Configuração obrigatória em qualquer lib:
+- Grid: hairline `--line-200`, sem dash.
+- Fonte: mesma do sistema (`var(--font-sans)`).
+- Cores: sempre via CSS custom properties (`--viz-cat-*`), nunca hex hardcoded no config.
+- Sem animação > 400ms na entrada. Sem "bounce" ou "elastic".
+
+---
+
+## Estados que faltavam (loading, skeleton, tooltip, tabela)
+
+### Loading state (skeleton, warm)
+
+Skeleton usa cor de fundo `--line-100` com animação sutil (shimmer 1200ms, contida). Sem gradiente colorido.
+
+```html
+<div class="panel">
+  <div class="panel-head">
+    <div class="panel-title" style="background:var(--line-100); color:transparent; border-radius:var(--r-sm); width:180px;">···</div>
+  </div>
+  <div class="panel-body">
+    <div style="height:12px; background:var(--line-100); border-radius:var(--r-xs); margin-bottom:8px;"></div>
+    <div style="height:12px; background:var(--line-100); border-radius:var(--r-xs); width:80%;"></div>
+  </div>
+</div>
+```
+
+**Regra:** skeleton só em first-load. Refetch de dados mantém render anterior a `opacity: 0.6`. Nunca "skeleton flash" no meio da sessão.
+
+### Tooltip (hover simples)
+
+Sem lib. Sem framework. `title` HTML nativo pra tooltips secos. Pra tooltips ricos (chart, KPI com detalhamento), use um `div` absoluto com estas specs:
+
+```css
+.zk-tooltip {
+  position: absolute;
+  background: var(--surface);
+  border: 1px solid var(--line-300);
+  border-radius: var(--r-sm);
+  padding: 8px 12px;
+  font-size: var(--fs-sm);
+  color: var(--ink-700);
+  box-shadow: var(--shadow-md);
+  pointer-events: none;
+  max-width: 280px;
+  line-height: 1.4;
+}
+```
+
+**Regra:** tooltip enhance, nunca gate. Toda informação em tooltip tem que estar OU visível OU na tabela.
+
+### Tabela (companion do chart)
+
+Todo chart tem uma tabela-view equivalente. Padrão:
+
+```html
+<table class="zk-table">
+  <thead>
+    <tr>
+      <th>Período</th>
+      <th class="num">Concluídas</th>
+      <th class="num">Meta</th>
+      <th class="num">Δ</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr><td>Jun/26</td><td class="num">128</td><td class="num">120</td><td class="num pos">+8</td></tr>
+    <tr><td>Jul/26</td><td class="num">142</td><td class="num">130</td><td class="num pos">+12</td></tr>
+  </tbody>
+</table>
+```
+
+Specs (adicione ao `components.css` se ainda não tem):
+
+- Fonte tabular apenas em coluna numérica (`.num { font-variant-numeric: tabular-nums; text-align: right; }`).
+- Hairline `--line-200` entre linhas (sem zebra, sem grid vertical).
+- Header em `--ink-500`, uppercase, `--fs-xs`, `--ls-widest`.
+- Delta positivo em `--success-700`, negativo em `--danger-700`. Nunca cor sozinha, sempre com sinal (+/-).
+- Densidade: `.zk-table-dense` (linha 32px) vs default (linha 44px).
+
+### Meter (barra de ratio contra limite)
+
+Pra "12 de 20 usada", "3.2GB de 5GB". Progresso é sempre **1 hue**, light track + dark fill:
+
+```html
+<div style="display:flex; flex-direction:column; gap:6px; max-width:320px;">
+  <div style="display:flex; justify-content:space-between; font-size:var(--fs-sm);">
+    <span>Uso de storage</span>
+    <span style="color:var(--ink-500);"><b>3.2 GB</b> de 5 GB</span>
+  </div>
+  <div style="height:6px; background:var(--line-100); border-radius:var(--r-xs); overflow:hidden;">
+    <div style="height:100%; width:64%; background:var(--brand-500); border-radius:var(--r-xs);"></div>
+  </div>
+</div>
+```
+
+Cor do fill:
+- Uso normal (< 80%): `--brand-500` ou `--info-500`.
+- Perto do limite (80–95%): `--warning-500`.
+- Estourou / crítico (≥ 95%): `--danger-500`.
+
+Cor troca só quando cruza threshold. Nunca gradiente.
+
+### Sparkline (dentro de StatCard)
+
+Sparkline é a única exceção onde chart entra dentro de card. Inline SVG, linha 1.5px, sem eixos, sem grid, sem legenda. Só a curva.
+
+```html
+<div class="stat">
+  <div class="stat-head">
+    <span class="stat-label">CONCLUÍDAS · SEMANA</span>
+  </div>
+  <div class="stat-value">142</div>
+  <div class="stat-sub">+12 vs anterior</div>
+  <svg viewBox="0 0 100 30" style="width:100%; height:24px; margin-top:8px;">
+    <polyline points="0,25 15,20 30,22 45,15 60,10 75,12 90,6 100,4"
+              fill="none" stroke="var(--brand-500)" stroke-width="1.5"
+              stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>
+</div>
+```
+
+Regra: sparkline usa 1 cor (`--brand-500` OU `--viz-cat-1` se está em contexto de chart section), nunca área preenchida colorida, nunca marcador em cada ponto.
+
+---
+
 ## Dark mode
 
 Toggle automático via OS, ou manual:
@@ -239,14 +729,57 @@ A cor de marca (`--brand-500`) **NUNCA muda no dark mode** — é assinatura da
 
 ## Regras importantes (NÃO fazer)
 
-- ❌ Trocar `--brand-500` por outra cor.
-- ❌ Hardcode de hex (`#f56f10` no código). SEMPRE use `var(--brand-500)`.
-- ❌ Sombras frias (`rgba(0,0,0,...)`). Use as warm `rgba(20,17,12,...)`.
-- ❌ `border-radius: 999px` ou `--r-pill`. Pill foi removido v3.
-- ❌ Display font (Space Grotesk) em UI body — só títulos h1/h2/h3, modal titles, brand.
-- ❌ Inter em títulos — display font é Space Grotesk.
+> Resumo prático. Detalhes no bloco "anti-IA-genérica" no topo deste README.
+
+**Cor**
+- ❌ Trocar `--brand-500` no meio do projeto (regenere o DS com nova primária).
+- ❌ Hex hardcoded. SEMPRE `var(--brand-500)` ou token.
+- ❌ Sombras frias `rgba(0,0,0,...)`. Use warm `rgba(20,17,12,...)`.
+- ❌ Brand color como bg dominante.
+
+**Geometria**
+- ❌ `border-radius: 999px` / `9999px` / `--r-pill`. Pill banido.
+- ❌ Raio > `var(--r-2xl)` (16px) em qualquer componente.
+- ❌ Borda > 1px em UI normal.
+
+**Efeitos (anti-cara-de-IA)**
+- ❌ Glow / halo (`box-shadow: 0 0 Xpx <cor>`, `filter: drop-shadow(0 0 X <cor>)`).
+- ❌ Shine / brilho decorativo (linhas brilhantes, sparkle, "glass reflection").
+- ❌ Gradiente colorido em botão, card, hero, background.
+- ❌ `text-shadow` colorido.
+- ❌ `backdrop-filter: blur()` como decoração (só em modal overlay leve, ≤ 8px).
+- ❌ Sombras frias `rgba(0,0,0,...)`. Use warm `rgba(20,17,12,...)`.
+
+**Botão (regra própria)**
+- ❌ Variante inventada (`btn-gradient`, `btn-glow`, `btn-hero`, `btn-3d`). Só as 5 canônicas.
+- ❌ Tamanho fora de xs/sm/md/lg. Sem `xl`, `w-full` inflado, `py-8`.
+- ❌ 2 botões `primary` no mesmo bloco. UM primário.
+- ❌ Emoji ou ícone gigante como CTA principal.
+
+**Texto / copy**
+- ❌ Travessão (—) ou en-dash (–) em qualquer texto da UI/copy.
+- ❌ Emoji em label de botão, título de campo, título de página.
+- ❌ Frase > 12 palavras em UI.
+- ❌ Vocabulário de marketing IA: "transforme", "potencialize", "descubra", "experimente".
+
+**Data viz**
+- ❌ Dual-axis (duas escalas Y).
+- ❌ Recolor-on-filter. Cor segue entidade.
+- ❌ 9ª cor gerada além dos 8 slots categóricos.
+- ❌ Rainbow em sequential. 1 hue, light→dark.
+- ❌ Status color como série de dado. Reservados.
+- ❌ Brand ember `--brand-500` como cor de série. É acento, não categoria.
+- ❌ Chart 3D, animação bounce, tooltip pesado com sombra colorida.
+
+**Tipografia**
+- ❌ {{fonts.display}} em UI body. Só títulos h1/h2/h3, modal titles, brand.
+- ❌ {{fonts.ui}} em h1 grande de página — display font é {{fonts.display}}.
+- ❌ Display/serif no hero figure de chart. Mesma sans do resto.
+
+**Motion**
 - ❌ Animação > 280ms em microinterações.
-- ❌ Brand color como bg dominante de tela inteira.
+- ❌ Animação > 400ms em entrada de chart.
+- ❌ Bounce/elastic em UI — só `--ease-spring` em entradas de modal.
 
 ---
 

package/templates/_shared/tokens.css.hbs

@@ -66,6 +66,41 @@
   --code-bg:   var(--brand-50);
   --code-fg:   var(--brand-700);
 
+  /* ---------- DATA VIZ (charts, KPIs, dashboards) ----------
+     Paleta validada (CVD safe, adjacent ΔE ≥ 12 no light surface).
+     8 slots categoricos ordenados; nunca cicle, nunca gere o 9o.
+     O brand ember (--brand-500) NAO eh cor de serie: fica reservada
+     pra CTA/focus/link. */
+  --viz-cat-1: #2a78d6;  /* blue    */
+  --viz-cat-2: #1baf7a;  /* aqua    */
+  --viz-cat-3: #eda100;  /* yellow  */
+  --viz-cat-4: #008300;  /* green   */
+  --viz-cat-5: #4a3aa7;  /* violet  */
+  --viz-cat-6: #e34948;  /* red     */
+  --viz-cat-7: #e87ba4;  /* magenta */
+  --viz-cat-8: #eb6834;  /* orange (viz-only, distinto do brand) */
+
+  /* Sequential (blue, light -> dark) — magnitude, heatmap, ordinal */
+  --viz-seq-100: #cde2fb;
+  --viz-seq-200: #9ec5f4;
+  --viz-seq-300: #6da7ec;
+  --viz-seq-400: #3987e5;
+  --viz-seq-500: #256abf;
+  --viz-seq-600: #184f95;
+  --viz-seq-700: #0d366b;
+
+  /* Diverging (blue <-> red, warm/cool poles) + neutro no meio */
+  --viz-div-pos: var(--viz-cat-1);
+  --viz-div-neg: var(--viz-cat-6);
+  --viz-div-mid: var(--line-100);
+
+  /* Chart chrome */
+  --viz-surface:   var(--surface);
+  --viz-grid:      var(--line-200);
+  --viz-axis:      var(--line-300);
+  --viz-ink:       var(--ink-700);
+  --viz-ink-muted: var(--ink-400);
+
   /* ---------- TYPOGRAPHY ---------- */
   --font-sans:    "{{fonts.ui}}", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
   --font-mono:    "{{fonts.mono}}", "SF Mono", Menlo, Consolas, monospace;
@@ -178,6 +213,18 @@ button { font-family: inherit; }
 
   --ring-focus:      0 0 0 3px {{brand.ringDark}};
   --ring-focus-soft: 0 0 0 3px {{brand.ringSoftDark}};
+
+  /* DATA VIZ — mesmos 8 hues, steppados pra dark surface */
+  --viz-cat-1: #3987e5;
+  --viz-cat-2: #199e70;
+  --viz-cat-3: #c98500;
+  --viz-cat-4: #008300;
+  --viz-cat-5: #9085e9;
+  --viz-cat-6: #e66767;
+  --viz-cat-7: #d55181;
+  --viz-cat-8: #d95926;
+  /* sequential steps ficam iguais (blue funciona no dark); os steps proximos do surface recuam */
+  --viz-div-mid: var(--line-200);
 }
 
 @media (prefers-color-scheme: dark) {
@@ -198,5 +245,11 @@ button { font-family: inherit; }
 
     --tag-bg:  var(--brand-800); --tag-fg:  var(--brand-200);
     --code-bg: var(--brand-900); --code-fg: var(--brand-300);
+
+    --viz-cat-1: #3987e5;  --viz-cat-2: #199e70;
+    --viz-cat-3: #c98500;  --viz-cat-4: #008300;
+    --viz-cat-5: #9085e9;  --viz-cat-6: #e66767;
+    --viz-cat-7: #d55181;  --viz-cat-8: #d95926;
+    --viz-div-mid: var(--line-200);
   }
 }