zark-design 3.1.0 → 3.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zark-design",
-  "version": "3.1.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. HTML + JSX side-by-side. Dark mode nativo. Sem dependência runtime.",
+  "version": "3.3.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"
@@ -24,7 +24,12 @@
     "anti-ai-look",
     "palette-generator",
     "dark-mode",
-    "brand-agnostic"
+    "brand-agnostic",
+    "data-viz",
+    "dataviz",
+    "charts",
+    "cvd-safe",
+    "categorical-palette"
   ],
   "author": "Maycon Jordan",
   "license": "MIT",

package/templates/README.md.hbs

@@ -13,10 +13,12 @@ Este design system existe pra **fugir do "cara de IA"**. Se você é uma IA gera
 ### 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 glassmorphism, gradiente colorido, neon, blur exagerado.** Sombra é warm (`rgba(20, 17, 12, ...)`), nunca azul-fria.
+- ❌ **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:
@@ -258,6 +260,63 @@ 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.
@@ -413,6 +472,488 @@ Quando a IA gera **labels de botão, mensagens, placeholders, títulos**:
 
 ---
 
+## Componentes avançados (v3.3)
+
+> Padrões maiores, derivados de referências externas de qualidade e adaptados pra identidade ZARK. Todos ficam em `components.css` e podem ser usados direto em HTML puro.
+
+### 1. UserDropdown (`.zk-user-menu`)
+
+Menu de usuário rico com avatar trigger, header (avatar + nome + username + status badge), grupos separados por hairline, itens com ícone + label + right-content (badge, avatar, ícone).
+
+```html
+<div class="zk-user-menu">
+  <button class="zk-user-menu-trigger">
+    <img src="avatar.jpg" alt="Voce"/>
+  </button>
+
+  <div class="zk-user-menu-panel">
+    <div class="head">
+      <div class="avatar"><img src="avatar.jpg" alt=""/></div>
+      <div class="who">
+        <div class="name">Maycon Jordan</div>
+        <div class="handle">@mayconj</div>
+      </div>
+      <span class="status-badge online">Online</span>
+    </div>
+
+    <div class="zk-user-menu-sep"></div>
+
+    <div class="zk-user-menu-group">
+      <button class="zk-user-menu-item">
+        <span class="icon"><svg viewBox="0 0 24 24"><circle cx="12" cy="8" r="4"/><path d="M4 20c0-4 4-6 8-6s8 2 8 6"/></svg></span>
+        <span class="label">Seu perfil</span>
+      </button>
+      <button class="zk-user-menu-item">
+        <span class="icon"><svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="3"/><path d="M12 3v3M12 18v3M3 12h3M18 12h3"/></svg></span>
+        <span class="label">Preferências</span>
+      </button>
+    </div>
+
+    <div class="zk-user-menu-sep"></div>
+
+    <div class="zk-user-menu-group">
+      <button class="zk-user-menu-item is-brand">
+        <span class="icon"><svg viewBox="0 0 24 24"><polygon points="12 2 15 9 22 9 17 14 19 21 12 17 5 21 7 14 2 9 9 9 12 2"/></svg></span>
+        <span class="label">Upgrade Pro</span>
+        <span class="badge-off">20% off</span>
+      </button>
+    </div>
+
+    <div class="zk-user-menu-sep"></div>
+
+    <div class="zk-user-menu-group">
+      <button class="zk-user-menu-item is-danger">
+        <span class="icon"><svg viewBox="0 0 24 24"><path d="M9 3v18M15 3v18M3 9h18M3 15h18"/></svg></span>
+        <span class="label">Sair</span>
+      </button>
+    </div>
+  </div>
+</div>
+```
+
+**Regras:** avatar circular sempre (50%). Status badge mono uppercase raio-xs. Sem backdrop-blur, sem drop-shadow-xl. Grupos separados por hairline `--line-100`.
+
+**Interação:** abre no click do trigger via JS (toggle da classe `.is-open` na panel, ou lib de headless UI se em React). CSS já cobre estados hover + focus.
+
+### 2. ToolbarDock (`.zk-dock`)
+
+Dock flutuante estilo Vercel-inspired: pill horizontal com ícones circulares, badges de notificação, botões de toggle. Versão light (default) e dark (`.zk-dock.dark`).
+
+```html
+<!-- Dock light -->
+<div class="zk-dock">
+  <button class="zk-dock-btn" aria-label="Comentar">
+    <svg viewBox="0 0 24 24"><path d="M4 6h16v10H8l-4 4V6z"/></svg>
+  </button>
+  <button class="zk-dock-btn" aria-label="Inbox">
+    <svg viewBox="0 0 24 24"><path d="M4 4h16v10l-4 4H8l-4-4V4z"/></svg>
+    <span class="dot"></span>
+  </button>
+  <div class="zk-dock-sep"></div>
+  <button class="zk-dock-btn" aria-label="Compartilhar">
+    <svg viewBox="0 0 24 24"><circle cx="18" cy="5" r="3"/><circle cx="6" cy="12" r="3"/><circle cx="18" cy="19" r="3"/><line x1="8.5" y1="10.5" x2="15.5" y2="6.5"/><line x1="8.5" y1="13.5" x2="15.5" y2="17.5"/></svg>
+  </button>
+  <button class="zk-dock-btn" aria-label="Menu">
+    <svg viewBox="0 0 24 24"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="20" y2="18"/></svg>
+  </button>
+</div>
+
+<!-- Dock dark (mesmo layout, adiciona .dark) -->
+<div class="zk-dock dark">
+  <!-- mesmos botões -->
+</div>
+```
+
+**Regras:** container `--r-lg` (8px), **nunca pill 999px**. Ícones 18px em botão 32x32 com `--r-md`. Notification dot 6px em brand-500 com border do surface. Separador vertical hairline. Sem backdrop-blur decorativo.
+
+**Extensão:** pra ter collapse animado + tooltip rail que desliza (como o Vercel-style original), embrulhe o dock num React Motion. Comportamento é opcional; visual estático já dá o benefício.
+
+### 3. ChartCard (`.zk-chart-card`)
+
+Card 356px com viz area de 180px em cima + body embaixo. Barras SVG mudam de altura no hover (CSS transitions). Grid sutil hairline com radial mask.
+
+```html
+<div class="zk-chart-card">
+  <div class="zk-chart-card-viz">
+    <div class="tags">
+      <span class="tag"><span class="dot" style="background:var(--viz-cat-1)"></span>+15,2%</span>
+      <span class="tag"><span class="dot" style="background:var(--viz-cat-8)"></span>+18,7%</span>
+    </div>
+    <svg viewBox="0 0 356 180">
+      <!-- barras: on hover expandem via CSS transition (defina y/height diferentes em .zk-chart-card:hover rect) -->
+      <rect x="40" y="110" width="15" height="20" fill="var(--viz-cat-8)" rx="2"/>
+      <rect x="60" y="90"  width="15" height="20" fill="var(--viz-cat-1)" rx="2"/>
+      <rect x="80" y="70"  width="15" height="40" fill="var(--viz-cat-1)" rx="2"/>
+      <rect x="100" y="80" width="15" height="30" fill="var(--viz-cat-1)" rx="2"/>
+      <rect x="120" y="110" width="15" height="30" fill="var(--viz-cat-8)" rx="2"/>
+      <rect x="140" y="60" width="15" height="50" fill="var(--viz-cat-1)" rx="2"/>
+      <rect x="160" y="80" width="15" height="30" fill="var(--viz-cat-1)" rx="2"/>
+      <rect x="180" y="110" width="15" height="20" fill="var(--viz-cat-8)" rx="2"/>
+    </svg>
+  </div>
+  <div class="zk-chart-card-body">
+    <div class="title">Novos leads</div>
+    <div class="desc">Últimos 7 dias · 142 no total</div>
+  </div>
+</div>
+```
+
+**Regras:** raio `--r-xl` (12px), hairline, shadow-sm. Cores das barras SEMPRE via `--viz-cat-*` (nunca hardcode). Grid pattern sutil (`--line-100`) com radial mask. Transition ≤ 400ms.
+
+**Anti-pattern (o que a referência tinha e não copiamos):** gradient radial colorido de background, `backdrop-blur-sm` decorativo nos tags. Removidos: warm/hairline resolve.
+
+### 4. OrbitCard (`.zk-orbit-card`)
+
+Card KPI com órbita de dots concêntricos, valor total no centro, breakdown de 2 métricas embaixo. Fade gradient neutro pra transitar viz → body.
+
+```html
+<div class="zk-orbit-card">
+  <div class="zk-orbit-card-viz">
+    <svg viewBox="0 0 320 272">
+      <!-- Anel externo: 32 dots em raio 130 -->
+      <!-- Anel interno: 24 dots em raio 100 -->
+      <!-- (na prática você gera com JS ou pré-calcula os cx/cy) -->
+      <circle cx="160" cy="6" r="4" fill="var(--viz-cat-1)"/>
+      <circle cx="185.4" cy="9.1" r="4" fill="var(--viz-cat-1)"/>
+      <!-- ...restante dos dots... -->
+      <circle cx="160" cy="36" r="4" fill="var(--viz-cat-4)"/>
+      <!-- ...anel interno... -->
+    </svg>
+    <div class="center">
+      <div class="kicker">Total</div>
+      <div class="value">R$ 2.125</div>
+    </div>
+    <div class="fade"></div>
+  </div>
+  <div class="zk-orbit-card-body">
+    <div class="zk-orbit-card-metrics">
+      <div class="zk-orbit-card-metric">
+        <div class="head">
+          <div class="bar" style="background:var(--viz-cat-1)"></div>
+          <div class="label">Bônus</div>
+        </div>
+        <div class="value">R$ 1.250</div>
+        <div class="delta">+15,2%</div>
+      </div>
+      <div class="zk-orbit-card-metric">
+        <div class="head">
+          <div class="bar" style="background:var(--viz-cat-4)"></div>
+          <div class="label">Incentivos</div>
+        </div>
+        <div class="value">R$ 875</div>
+        <div class="delta">+8,7%</div>
+      </div>
+    </div>
+    <button class="btn btn-secondary btn-md" style="width:100%">Ver detalhes</button>
+  </div>
+</div>
+```
+
+**Regras:** dots via `--viz-cat-*` (blue + green por padrão). Valor central em display font (Space Grotesk), `--fs-4xl`. Fade usa gradient neutro (`transparent → var(--surface)`), **nunca cor colorida**. Botão inferior é `.btn-secondary` (não inflado, não gigante).
+
+**Anti-pattern:** a referência usava `backdrop-blur-[2px]`, `bg-blue-400/10`, `bg-green-400/10` como decoração. Substituímos por dots com `opacity: 0.6` e fade gradient neutro. Efeito visual similar, cara-de-IA removido.
+
+### 5. WheelPicker (`.zk-wheel-picker`)
+
+Radial time picker: input central redondo + wheel de 8 wedges com atalhos de +/- tempo. Wheel aparece no hover, some quando o input ganha foco (deixa você digitar).
+
+```html
+<div class="zk-wheel-picker">
+  <!-- Wheel de wedges (aparece no hover) -->
+  <div class="zk-wheel-picker-wheel">
+    <svg viewBox="0 0 360 360">
+      <!-- 4 wedges positivos (top) -->
+      <g class="wedge-group">
+        <path class="wedge pos" d="M180 180 L180 20 A160 160 0 0 1 293 67 Z"/>
+        <text class="wedge-label pos" x="235" y="45">+2h</text>
+      </g>
+      <g class="wedge-group">
+        <path class="wedge pos" d="M180 180 L293 67 A160 160 0 0 1 340 180 Z"/>
+        <text class="wedge-label pos" x="315" y="115">+1h</text>
+      </g>
+      <g class="wedge-group">
+        <path class="wedge pos" d="M180 180 L340 180 A160 160 0 0 1 293 293 Z"/>
+        <text class="wedge-label pos" x="315" y="245">+30m</text>
+      </g>
+      <g class="wedge-group">
+        <path class="wedge pos" d="M180 180 L293 293 A160 160 0 0 1 180 340 Z"/>
+        <text class="wedge-label pos" x="235" y="315">+15m</text>
+      </g>
+      <!-- 4 wedges negativos (bottom) -->
+      <g class="wedge-group">
+        <path class="wedge" d="M180 180 L180 340 A160 160 0 0 1 67 293 Z"/>
+        <text class="wedge-label" x="125" y="315">-15m</text>
+      </g>
+      <g class="wedge-group">
+        <path class="wedge" d="M180 180 L67 293 A160 160 0 0 1 20 180 Z"/>
+        <text class="wedge-label" x="45" y="245">-30m</text>
+      </g>
+      <g class="wedge-group">
+        <path class="wedge" d="M180 180 L20 180 A160 160 0 0 1 67 67 Z"/>
+        <text class="wedge-label" x="45" y="115">-1h</text>
+      </g>
+      <g class="wedge-group">
+        <path class="wedge" d="M180 180 L67 67 A160 160 0 0 1 180 20 Z"/>
+        <text class="wedge-label" x="125" y="45">-2h</text>
+      </g>
+    </svg>
+  </div>
+
+  <!-- Input central -->
+  <div class="zk-wheel-picker-input">
+    <input type="text" value="09:00" placeholder="HH:MM"/>
+  </div>
+</div>
+```
+
+**Regras:** input central em `--r-md` (**nunca pill 999px** como a referência tinha). Wheel wedges com stroke da cor `--paper` pra criar gaps visuais. `.wedge.pos` usa `--brand-*`, `.wedge` neutra usa `--ink-*`. Font do valor em display font (Space Grotesk), `--fs-2xl`. Sem drop-shadow-xl.
+
+**Interação:** wheel aparece via CSS `.zk-wheel-picker:hover` (opacity + scale + rotate). Sem lib. Pra ligar o click de cada wedge ao valor do input, adicione JS handler que ajusta minutos.
+
+---
+
+## 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:
@@ -441,18 +982,43 @@ A cor de marca (`--brand-500`) **NUNCA muda no dark mode** — é assinatura da
 - ❌ 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.
+- ❌ Animação > 400ms em entrada de chart.
 - ❌ Bounce/elastic em UI — só `--ease-spring` em entradas de modal.
 
 ---