zark-design 3.2.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zark-design",
-  "version": "3.2.0",
+  "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": {

package/templates/README.md.hbs

@@ -472,6 +472,246 @@ 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.

package/templates/_shared/tokens.css.hbs

@@ -164,7 +164,8 @@ html, body {
   text-rendering: optimizeLegibility;
 }
 ::selection { background: var(--brand-200); color: var(--ink-700); }
-a { color: inherit; }
+a { color: inherit; text-decoration: none; }
+a:hover { text-decoration: none; }
 button { font-family: inherit; }
 
 /* ============================================================