zark-design 1.0.0 → 2.0.0

package/bin/cli.js

@@ -49,7 +49,7 @@ async function copyDir(src, dest) {
 }
 
 async function appendNoteToContextFiles(targetRoot, designDirName) {
-  const note = `\n\n## Design system\nEste projeto usa o **ZARK Design System**. Antes de qualquer trabalho de UI/frontend, leia \`${designDirName}/REFERENCE.md\` (descreve tokens, primitivos, layouts e patterns). Os arquivos \`.jsx\` em \`${designDirName}/\` são REFERÊNCIA visual e estrutural — adapte pra stack atual do projeto (React/Vue/Svelte/Blade/Django templates/etc.), não copie literal. Os PNGs em \`${designDirName}/visual-references/\` são ground truth visual.\n`;
+  const note = `\n\n## Design system\nEste projeto usa o **ZARK Design System (Apps)**. Antes de qualquer trabalho de UI/frontend, leia \`${designDirName}/README.md\` — descreve tokens, primitivos, App Patterns (StatCard, Funnel, KanbanColumn, LeadCard, AlertCritical, EmptyState, TableActions), 35 ícones e regras de uso.\n\nDuas implementações lado a lado consumindo os MESMOS \`tokens.css\` + \`components.css\`:\n- \`${designDirName}/html/\` — HTML puro com classes (\`.btn\`, \`.tag-dot\`, \`.stat\` …). Use em projetos Blade/Django/Rails/HTML.\n- \`${designDirName}/jsx/\` — React (24 componentes individuais em \`components/\`). Use em projetos React/Next.\n\nPara Vue/Svelte/Solid, use \`tokens.css\` + \`components.css\` direto e adapte os componentes JSX mantendo as classes CSS.\n\nAbra \`${designDirName}/html/showcase.html\` no browser pra ver tudo renderizado (light/dark toggle).\n`;
 
   const candidates = [
     path.join(targetRoot, '.ai-context', 'CONTEXT.md'),
@@ -87,9 +87,10 @@ function printHelp(version) {
   console.log(`    npx zark-design init ./ui               ${c.dim('# instala em ./ui')}`);
   console.log(`    npx zark-design init --force            ${c.dim('# sobrescreve se já existe')}\n`);
   console.log(`  ${c.bold('Filosofia:')}`);
-  console.log(`    Os arquivos JSX são ${c.bold('REFERÊNCIA')} pra IA, não pra runtime.`);
-  console.log(`    A IA lê REFERENCE.md + visual-references/ e adapta pra stack atual`);
-  console.log(`    do projeto (React, Vue, Svelte, Blade, Django, HTML puro, etc.).\n`);
+  console.log(`    Cria pasta com 2 implementações lado a lado: ${c.bold('html/')} e ${c.bold('jsx/')}.`);
+  console.log(`    Ambas consomem os MESMOS tokens.css + components.css.`);
+  console.log(`    A IA lê README.md, escolhe a versão certa pra stack do projeto`);
+  console.log(`    (React→jsx · Blade/Django/HTML→html · Vue/Svelte→adapta classes).\n`);
 }
 
 async function runInit(args) {
@@ -142,8 +143,8 @@ async function runInit(args) {
   console.log(c.green(`✓ Design system instalado em ${designDirName}/`));
   console.log('');
   console.log(c.bold('Próximo passo:'));
-  console.log(`  Diga pra IA: ${c.dim(`"use o design system em ${designDirName}/ como referência exata pra UI"`)}`);
-  console.log(`  Ou abra ${designDirName}/SHOWCASE.html no browser pra ver o sistema.`);
+  console.log(`  ${c.dim('•')} Diga pra IA: "use o design system em ${designDirName}/ como referência (leia README.md)"`);
+  console.log(`  ${c.dim('•')} Ou abra ${designDirName}/html/showcase.html no browser pra ver tudo renderizado.`);
 }
 
 async function main() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zark-design",
-  "version": "1.0.0",
-  "description": "ZARK SAAS Design System — install via `npx zark-design init` to drop the design system as REFERENCE for AI in any project (any stack).",
+  "version": "2.0.0",
+  "description": "ZARK SAAS Design System (Apps) — install via `npx zark-design init` to drop the design system in any project. Ships HTML + JSX side-by-side, both consuming the same tokens.css + components.css, with App Patterns derived from the ZARK CRM.",
   "type": "module",
   "bin": {
     "zark-design": "bin/cli.js"

package/templates/README.md

@@ -0,0 +1,264 @@
+# ZARK Design System — Apps
+
+Sistema de design para apps e sistemas internos da ZARK. Disponível em **HTML puro** e **React (JSX)**, ambos consumindo as mesmas folhas de estilo (`tokens.css` + `components.css`).
+
+Versão: **v3 · 2026** · App Patterns derivados do CRM real.
+
+---
+
+## Estrutura
+
+```
+design-system-apps/
+├── README.md                          ← você está aqui
+│
+├── html/                              ← versão HTML pura
+│   ├── tokens.css                     ← variáveis CSS (cores, tipografia, espaçamento)
+│   ├── components.css                 ← classes de componente (.btn, .tag-dot, .stat...)
+│   ├── index.html                     ← exemplo mínimo de uso
+│   ├── showcase.html                  ← galeria completa interativa
+│   └── assets/
+│       ├── logo-zark-laranja.png
+│       └── zark-icon.png
+│
+└── jsx/                               ← versão React
+    ├── tokens.css                     ← (idêntico ao html/tokens.css)
+    ├── components.css                 ← (idêntico ao html/components.css)
+    ├── tokens.js                      ← tokens em JS para inline styles / charts
+    ├── icons.jsx                      ← 35 ícones outline
+    ├── index.js                       ← barrel export
+    ├── App.example.jsx                ← exemplo completo de uso
+    ├── components/
+    │   ├── Button.jsx
+    │   ├── Input.jsx                  ← + UrlInputFull
+    │   ├── Tag.jsx
+    │   ├── TagDot.jsx                 ← status, priority, space
+    │   ├── Badge.jsx
+    │   ├── Toggle.jsx
+    │   ├── Segmented.jsx
+    │   ├── Chip.jsx                   ← filter chips
+    │   ├── StatCard.jsx               ← KPI card unificado
+    │   ├── AlertCritical.jsx          ← banner vermelho de ação imediata
+    │   ├── Funnel.jsx                 ← + ProgressBar
+    │   ├── EmptyState.jsx
+    │   ├── KanbanColumn.jsx           ← + KanbanBoard
+    │   ├── LeadCard.jsx               ← Pipeline
+    │   ├── TableActions.jsx           ← check / edit / delete
+    │   ├── Sidebar.jsx                ← + SidebarLink, SidebarSection
+    │   ├── Panel.jsx                  ← card padrão
+    │   ├── Section.jsx                ← bloco de página
+    │   ├── Modal.jsx
+    │   ├── Toast.jsx
+    │   ├── Banner.jsx                 ← Announce + Tip
+    │   ├── CodeBlock.jsx
+    │   ├── Avatar.jsx                 ← + AvatarSpace
+    │   ├── Kbd.jsx
+    │   └── Spec.jsx
+    └── assets/
+        ├── logo-zark-laranja.png
+        └── zark-icon.png
+```
+
+---
+
+## Filosofia
+
+**Warm, neutral, ember-on-paper.**
+- `--paper` (#fafaf8) cremoso, NÃO branco puro.
+- `--ember-500` (#f56f10 — Liquid Lava) é a única cor de marca. Use com **moderação** em CTAs, focus, brand moments.
+- 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).
+
+---
+
+## Como usar — HTML puro
+
+1. Importe os 2 CSS no `<head>`:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com"/>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=Space+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet"/>
+
+<link rel="stylesheet" href="/path/to/tokens.css"/>
+<link rel="stylesheet" href="/path/to/components.css"/>
+```
+
+2. Use as classes diretamente:
+
+```html
+<button class="btn btn-primary btn-md">Nova Tarefa</button>
+
+<span class="tag-dot s-todo">A FAZER</span>
+<span class="tag-dot p-urgent">URGENTE</span>
+<span class="tag-dot sp sp-vipcar">VIPCAR</span>
+
+<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>
+```
+
+3. Veja `html/index.html` (exemplo prático) e `html/showcase.html` (galeria completa).
+
+---
+
+## Como usar — React (JSX)
+
+1. Copie a pasta `jsx/` pro seu projeto OU configure como pacote local.
+
+2. No entry-point (`main.jsx` / `App.jsx`):
+
+```jsx
+import './path/to/jsx/tokens.css';
+import './path/to/jsx/components.css';
+```
+
+3. Carregue as fontes (uma vez no `index.html` ou via `@import` no CSS).
+
+4. Importe componentes:
+
+```jsx
+import { Button, TagDot, StatCard, Icons } from './path/to/jsx';
+
+function Dashboard() {
+  return (
+    <>
+      <Button variant="primary" icon={<Icons.Plus size={14}/>}>
+        Nova Tarefa
+      </Button>
+
+      <TagDot kind="status"   value="todo">A FAZER</TagDot>
+      <TagDot kind="priority" value="urgent">URGENTE</TagDot>
+      <TagDot kind="space"    value="vipcar">VIPCAR</TagDot>
+
+      <StatCard
+        label="CONCLUÍDAS · SEMANA"
+        value="8"
+        sub="+18% vs anterior"
+        iconColor="green"
+        icon={<Icons.Check size={14}/>}
+      />
+    </>
+  );
+}
+```
+
+5. Veja `jsx/App.example.jsx` para o exemplo completo (sidebar + dashboard + kanban + modal).
+
+---
+
+## Catálogo de componentes
+
+### Primitivos
+| Componente | HTML class | JSX |
+|------------|-----------|-----|
+| Button     | `.btn .btn-{variant} .btn-{size}` | `<Button variant size icon iconRight loading>` |
+| Input      | `.input .input-{size}` | `<Input size icon suffix mono invalid/>` |
+| UrlInputFull | `.url-input-full` | `<UrlInputFull scheme placeholder/>` |
+| Tag        | `.tag .tag-{tone} .tag-{size}` | `<Tag tone size square>` |
+| TagDot     | `.tag-dot .{prefix}-{value}` | `<TagDot kind value>` |
+| Badge      | `.badge` | `<Badge count tone/>` |
+| Toggle     | `.toggle .toggle-sm .on` | `<Toggle on onChange size/>` |
+| Segmented  | `.segmented` | `<Segmented items value onChange/>` |
+| Chips      | `.chips .chip .active` | `<Chips items value onChange/>` |
+| Avatar     | `.avatar .avatar-sq` | `<Avatar name size color square src/>` |
+| AvatarSpace| `.av-space` | `<AvatarSpace name spaceKey size/>` |
+| Kbd        | `.kbd` | `<Kbd>⌘K</Kbd>` |
+
+### App Patterns (derivados do CRM)
+| Componente | HTML class | JSX |
+|------------|-----------|-----|
+| StatCard       | `.stat .is-critical` | `<StatCard label value sub icon iconColor progress critical/>` |
+| AlertCritical  | `.alert-critical` | `<AlertCritical title items footer onItemClick/>` |
+| Funnel         | `.funnel .funnel-stages` | `<Funnel stages={[]}/>` |
+| ProgressBar    | `.stat-progress` | `<ProgressBar value tone/>` |
+| KanbanColumn   | `.k-col .k-col-head .k-add` | `<KanbanColumn title count dotColor onAddClick/>` |
+| LeadCard       | `.lead-card .is-paused .is-overdue` | `<LeadCard name company status hot channels time followUp indicator paused overdue/>` |
+| EmptyState     | `.empty-state` | `<EmptyState icon text action/>` |
+| TableActions   | `.t-actions .t-act` | `<TableActions onConfirm onEdit onDelete/>` |
+
+### Layout
+| Componente | HTML class | JSX |
+|------------|-----------|-----|
+| Sidebar     | `.zk-sidebar .zk-sidebar-link` | `<Sidebar logo footer/>` + `<SidebarLink active icon shortcut/>` + `<SidebarSection/>` |
+| Panel       | `.panel .panel-head .panel-body` | `<Panel title kicker flush/>` |
+| Section     | `.section .eyebrow` + h2 | `<Section eyebrow title description id/>` |
+| Modal       | `.modal-overlay .modal` | `<Modal open onClose title description footer/>` |
+| Toast       | `.toast .toast-success .toast-danger` | `<Toast tone icon/>` |
+| Announce    | `.announce` | `<Announce/>` |
+| Tip         | `.tip` | `<Tip eyebrow title desc icon onClose/>` |
+| CodeBlock   | `.code-block` | `<CodeBlock code onCopy onPreview/>` |
+| Spec        | `.spec` | `<Spec label value/>` |
+
+### Ícones (35)
+35 ícones outline em `Icons.{Name}`. Veja `jsx/icons.jsx` ou abra `html/showcase.html` (seção 26) para a galeria visual.
+
+---
+
+## Tokens essenciais
+
+### Status (tag-dot prefixo `s-`)
+- `s-todo`, `s-progress`, `s-review`, `s-done`, `s-canceled`
+- Modificadores: `s-overdue`, `s-paused`, `s-followup`
+
+### Prioridade (`p-`)
+- `p-urgent`, `p-high`, `p-med`, `p-low`
+
+### Espaços/Clientes (`sp sp-{key}`)
+- `sp-zark`, `sp-allsec`, `sp-vipcar`, `sp-limppe`, `sp-gerais`, `sp-mixshop`, `sp-vipseg`
+
+### Cores semânticas
+- `--success-500` (verde), `--warning-500` (amarelo), `--danger-500` (vermelho), `--info-500` (azul)
+
+### Espaçamento (4px base)
+- `--sp-4` (8px), `--sp-8` (16px), `--sp-12` (24px), `--sp-16` (32px), `--sp-20` (40px)
+
+### Raios (sem pill — Jordan-approved)
+- `--r-xs` (3px), `--r-sm` (4px), `--r-md` (6px), `--r-lg` (8px), `--r-xl` (12px), `--r-2xl` (16px), `--r-3xl` (20px)
+
+---
+
+## Dark mode
+
+Toggle automático via OS, ou manual:
+```js
+document.documentElement.dataset.theme = 'dark';   // força dark
+document.documentElement.dataset.theme = 'light';  // força light
+delete document.documentElement.dataset.theme;     // segue OS
+```
+
+A cor de marca (`--ember-500`) **NUNCA muda no dark mode** — é assinatura ZARK. Apenas neutros, semânticos suaves e sombras ajustam.
+
+---
+
+## Regras importantes (NÃO fazer)
+
+- ❌ Trocar `--ember-500` por outra cor.
+- ❌ Hardcode de hex (`#f56f10` no código). SEMPRE use `var(--ember-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.
+- ❌ Animação > 280ms em microinterações.
+- ❌ Brand color como bg dominante de tela inteira.
+
+---
+
+## Showcase
+
+Para ver TUDO renderizado em uma página interativa, abra:
+```
+html/showcase.html
+```
+
+Tem light/dark toggle, todos os componentes, toda a paleta, todos os ícones — pronto pra inspecionar e copiar.
+
+---
+
+*Mantido por @renankennedy · ZARK · 2026*