zark-design 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# zark-design
+
+> ZARK SAAS Design System — instale via `npx zark-design init` em qualquer projeto.
+
+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
+
+```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)
+```
+
+Depois, abra a IA na pasta:
+
+```bash
+claude   # ou cursor . / codex / aider
+```
+
+A IA detecta `design-system/REFERENCE.md` e usa como fonte de verdade pra qualquer trabalho de UI/frontend.
+
+## Pasta customizada
+
+```bash
+npx zark-design init ./ui                 # instala em ./ui em vez de ./design-system
+npx zark-design init ./src/zark           # instala em src/zark
+```
+
+## Sobrescrever instalação existente
+
+```bash
+npx zark-design init --force
+```
+
+## Integração com `.ai-context/CONTEXT.md` ou `CLAUDE.md`
+
+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.
+
+## Filosofia
+
+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

package/bin/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import { promises as fs } from 'node:fs';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, '../templates');
+const PKG_PATH = path.resolve(__dirname, '../package.json');
+
+const c = {
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+};
+
+function banner(title) {
+  const line = '═'.repeat(Math.max(title.length + 4, 50));
+  console.log(c.cyan(`\n╔${line}╗`));
+  console.log(c.cyan(`║  ${c.bold(title)}${' '.repeat(line.length - title.length - 2)}║`));
+  console.log(c.cyan(`╚${line}╝\n`));
+}
+
+async function getVersion() {
+  try {
+    const pkg = JSON.parse(await fs.readFile(PKG_PATH, 'utf-8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const sp = path.join(src, entry.name);
+    const dp = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(sp, dp);
+    } else if (entry.isFile()) {
+      await fs.copyFile(sp, dp);
+    }
+  }
+}
+
+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 candidates = [
+    path.join(targetRoot, '.ai-context', 'CONTEXT.md'),
+    path.join(targetRoot, 'CLAUDE.md'),
+  ];
+
+  for (const file of candidates) {
+    if (!existsSync(file)) continue;
+    try {
+      const stat = await fs.lstat(file);
+      const realFile = stat.isSymbolicLink()
+        ? path.resolve(path.dirname(file), await fs.readlink(file))
+        : file;
+      const current = await fs.readFile(realFile, 'utf-8');
+      if (current.includes('ZARK Design System')) {
+        return realFile + ' (já tem nota — pulando)';
+      }
+      await fs.writeFile(realFile, current + note, 'utf-8');
+      return realFile + ' (nota adicionada)';
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}
+
+function printHelp(version) {
+  banner(`zark-design v${version}`);
+  console.log(`  ${c.bold('Comandos:')}\n`);
+  console.log(`    ${c.green('init')} ${c.dim('[pasta]')}   instala o design system (default: ./design-system)`);
+  console.log(`    ${c.green('help')}            mostra esta ajuda`);
+  console.log(`    ${c.green('version')}         mostra a versão\n`);
+  console.log(`  ${c.bold('Uso:')}`);
+  console.log(`    npx zark-design init                    ${c.dim('# instala em ./design-system')}`);
+  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`);
+}
+
+async function runInit(args) {
+  const force = args.includes('--force');
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const target = path.resolve(positional[0] ?? './design-system');
+  const designDirName = path.basename(target);
+  const projectRoot = path.dirname(target);
+
+  banner('🎨 zark-design — install');
+
+  if (existsSync(target)) {
+    if (!force) {
+      console.error(c.red(`✗ Pasta '${target}' já existe.`));
+      console.error(c.dim(`  Use --force pra sobrescrever, ou escolha outro nome.`));
+      process.exit(1);
+    }
+    console.log(c.yellow(`⚠ Sobrescrevendo ${target} (--force)`));
+    await fs.rm(target, { recursive: true, force: true });
+  }
+
+  console.log(c.dim(`  origem: ${TEMPLATES_DIR}`));
+  console.log(c.dim(`  destino: ${target}\n`));
+
+  await copyDir(TEMPLATES_DIR, target);
+
+  const fileList = [];
+  async function walk(dir, base = '') {
+    for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+      const sub = path.join(base, e.name);
+      if (e.isDirectory()) await walk(path.join(dir, e.name), sub);
+      else fileList.push(sub);
+    }
+  }
+  await walk(target);
+
+  for (const f of fileList) {
+    console.log(`  ${c.green('✓')}  ${f}`);
+  }
+
+  console.log('');
+  const noteResult = await appendNoteToContextFiles(projectRoot, designDirName);
+  if (noteResult) {
+    console.log(`  ${c.green('✓')}  ${noteResult}`);
+  } else {
+    console.log(c.dim(`  (sem .ai-context/CONTEXT.md ou CLAUDE.md no projeto — sem auto-nota)`));
+  }
+
+  console.log('');
+  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.`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0] ?? 'help';
+  const version = await getVersion();
+
+  try {
+    switch (cmd) {
+      case 'init':
+        await runInit(argv.slice(1));
+        return;
+      case 'version':
+      case '--version':
+      case '-v':
+        console.log(version);
+        return;
+      case 'help':
+      case '--help':
+      case '-h':
+      default:
+        printHelp(version);
+        return;
+    }
+  } catch (e) {
+    console.error(c.red(`✗ ${e.message ?? e}`));
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "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).",
+  "type": "module",
+  "bin": {
+    "zark-design": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "design-system",
+    "zark",
+    "saas",
+    "ai-context",
+    "scaffold",
+    "tokens",
+    "ui"
+  ],
+  "author": "Maycon Jordan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mayconjordanr/zark-design.git"
+  }
+}

package/templates/REFERENCE.md

@@ -0,0 +1,376 @@
+# ZARK Design System — Referência para IA
+
+> **Para a IA**: este documento é a fonte de verdade do design system ZARK.
+> Os arquivos `.jsx` deste diretório são **REFERÊNCIA visual e estrutural**, não código pra rodar.
+> Adapte os componentes pra stack atual do projeto — React, Vue, Svelte, Solid, Qwik, Blade (Laravel), Django templates, ERB (Rails), HTML puro com Tailwind, CSS modules, styled-components — qualquer uma.
+> Os PNGs em `visual-references/` são **ground truth visual** — quando dúvida sobre aparência, abra e olhe.
+
+---
+
+## 1. Filosofia visual
+
+ZARK é um sistema **warm, neutral, ember-on-paper**. Pense em:
+- **Paper** (fundo cremoso quente, não branco puro) com **ink** (texto preto-quente, não preto puro)
+- **Liquid Lava** (`#F56F10`, ember-500) é a única cor de marca — usar **com moderação** em CTAs primários, focus rings, brand moments. Nunca como background dominante de telas inteiras.
+- **Hairlines** finas (1px) em `--line-200` para separação de superfícies — não usar `border` grosso ou caixas duras
+- **Shadows curtas e quentes**, não shadows azuis frios — sombras são `rgba(20, 17, 12, ...)` (warm-black), não `rgba(0,0,0,...)`
+- **Sem gradient** salvo casos pontuais (botão primário ember pode ter mini-gradient interno; nada de big hero gradients)
+- **Tipografia editorial**: Inter pra UI, JetBrains Mono pra código, Darker Grotesque pra moments de display (hero numbers, eyebrows de marketing) — usar com parcimônia
+
+A vibe-alvo: **Linear meets Vercel meets Things 3** — superfície limpa, densidade alta de informação por unidade de tela, hierarquia tipográfica clara, microinterações rápidas (120-180ms ease-out).
+
+---
+
+## 2. Tokens (`tokens.css`)
+
+Importe `tokens.css` no entry-point do projeto. Todos os componentes referenciam variáveis CSS.
+
+### 2.1 Brand / Ember
+
+| Token | Valor light | Uso |
+|-------|------|-----|
+| `--ember-500` (`--liquid-lava`) | `#f56f10` | Cor de marca. CTAs primários, focus, brand. **Inalterado no dark mode.** |
+| `--ember-600` (`--liquid-lava-dark`) | `#d45e0d` | Hover/active de CTA primário (no light) |
+| `--ember-50/100/200` | tons claros | Bg de tag, code, success-states leves |
+| `--ember-700/800/900` | tons escuros | Texto sobre fundos ember claros |
+| `--dark-void` | `#151419` | Fundo dark mode (canvas) |
+| `--glucon-grey` | `#1b1a1e` | Surface dark mode |
+
+### 2.2 Neutros (paper → ink)
+
+| Token | Light | Dark | Uso |
+|-------|-------|------|-----|
+| `--paper` | `#fafaf8` | `#0e0d11` | App background |
+| `--canvas` | `#f5f4f1` | `#151419` | Sidebar, painel secundário |
+| `--surface` | `#ffffff` | `#1b1a1e` | Cards, modais, dropdown |
+| `--line-100` | `#f0eeea` | `#232227` | Hairlines em fundos tintados |
+| `--line-200` | `#e8e6e1` | `#2c2b32` | Border padrão |
+| `--line-300` | `#d8d5cf` | `#3a383f` | Divider mais forte |
+| `--ink-700` | `#1a1916` | `#f0ede5` | Texto primary |
+| `--ink-500` | `#4a4741` | `#c8c5bf` | Texto body |
+| `--ink-400` | `#6f6b64` | `#a09c95` | Texto secondary, labels |
+| `--ink-300` | `#a09c95` | `#6f6b64` | Texto disabled, placeholder |
+
+### 2.3 Semânticos
+
+| Token | Valor | Uso |
+|-------|-------|-----|
+| `--success-500` | `#10a960` | Ícones, badges OK. NUNCA texto sobre fundo claro sem contraste |
+| `--warning-500` | `#d99000` | Avisos não-críticos |
+| `--danger-500` | `#dc3545` | Erros, destrutivo. Em botões: bg + white text |
+| `--info-500` | `#2f7adc` | Info neutra |
+
+Sempre acompanha um par `*-50` (bg suave) e `*-700` (texto sobre `*-50`).
+
+### 2.4 Tipografia
+
+| Token | Valor | Uso |
+|-------|-------|-----|
+| `--font-sans` (`--font-ui`) | Inter | UI texto, botões, labels |
+| `--font-mono` | JetBrains Mono | Código, keyboard shortcuts (`<kbd>`), specs |
+| `--font-display` | Darker Grotesque | Hero numbers, marketing display, eyebrows raros |
+
+Escala (px): 10, 11, 12, 13, **14 (base UI)**, 16, 18, 22, 28, 36, 48, 64, 88. Use `--fs-base` (14) como padrão de UI; `--fs-md` (13) pra denso; `--fs-2xl+` pra display.
+
+Line-heights: `--lh-tight` (1.1, hero/display), `--lh-snug` (1.25, headings), `--lh-base` (1.45, body), `--lh-loose` (1.6, longform).
+
+Letter-spacing: use `--ls-tight` (-0.02em) em headings grandes; `--ls-widest` (0.14em uppercase) em eyebrows e tags.
+
+Pesos: 400 regular, 500 medium (UI label/btn), 600 semibold (heading médio), 700 bold (display, ênfase).
+
+### 2.5 Espaçamento (4px base)
+
+`--sp-1` (2px) → `--sp-48` (96px). Default de stack vertical: `--sp-12` (24px). Default de gap em flex: `--sp-8` (16px). Padding interno de card: `--sp-16` ou `--sp-20`.
+
+### 2.6 Raios
+
+`--r-xs` (3px) inputs/tags densos · `--r-sm` (4px) inputs/buttons · `--r-md` (6px) padrão · `--r-lg` (8px) cards · `--r-xl` (12px) modals · `--r-2xl` (16px) hero panels · `--r-pill` (999px) avatars/pills.
+
+### 2.7 Sombras
+
+`--shadow-xs` hairline · `--shadow-sm` card neutro · `--shadow-md` card elevated/hover · `--shadow-lg` popover · `--shadow-xl` modal/sheet · `--shadow-modal` modal full · `--shadow-inset` highlight no topo de elementos.
+
+Focus ring: sempre `--ring-focus` em qualquer elemento interativo recebendo foco via teclado.
+
+### 2.8 Motion
+
+`--t-fast` (120ms) hover de botão · `--t-base` (180ms) padrão · `--t-slow` (280ms) sheets/modals abrindo · `--t-slower` (420ms) transições maiores.
+
+Easings: `--ease-out` (saída natural, default), `--ease-in-out` (transitions complexas), `--ease-spring` (microinteractions playful, evite em UI sério).
+
+### 2.9 Layout
+
+`--sidebar-w` 240px · `--topbar-h` 56px · `--container-max` 1280px.
+
+---
+
+## 3. Tema dark/light
+
+`tokens.css` define light por padrão. Dark mode ativado de duas formas:
+
+1. **Manual / opt-in:** `<html data-theme="dark">` — controla via JS/setting do user
+2. **Automático via OS:** `@media (prefers-color-scheme: dark)` aplica se `data-theme` não estiver setado pra `light`
+
+**Implemente sempre o toggle**. Recomendação UX: salvar preferência em `localStorage` + respeitar OS por padrão.
+
+```js
+// Exemplo de toggle (adapte pra stack)
+const setTheme = (mode) => {
+  document.documentElement.dataset.theme = mode;
+  localStorage.setItem('zark-theme', mode);
+};
+const initTheme = () => {
+  const saved = localStorage.getItem('zark-theme');
+  if (saved) setTheme(saved);
+  // sem saved → respeita OS via @media query (não precisa setar)
+};
+```
+
+**Brand:** `--ember-500` (`#f56f10`) é **inalterado** no dark — é assinatura ZARK. Os tons claros `--ember-50/100/200/300` invertem (viram escuros) pra servir de bg suave em cards dark.
+
+---
+
+## 4. Primitivos (`primitives.jsx`)
+
+Componentes atômicos. Adapte pra stack atual.
+
+### 4.1 `Section` — bloco temático com eyebrow + título + descrição
+Props: `eyebrow` (uppercase tracking-wide, font-display), `title`, `description`, `columns` (grid columns).
+Padding vertical generoso (`--sp-32` top, `--sp-16` bottom).
+
+### 4.2 `Panel` — card padrão
+Props: `title`, `kicker` (uppercase pequena), `padded` (default true), `children`. Surface bg, hairline border, raio `--r-lg`, sombra `--shadow-sm`. Hover (em variante interativa): eleva pra `--shadow-md`.
+
+### 4.3 `Spec` — linha label/value
+Display flex space-between. Label em `--ink-400` `--fs-sm`. Value em `--ink-700` `--fw-medium`. Quando `mono` true, value usa `--font-mono` `--fs-md`. Use em painéis técnicos (config, specs, metadata).
+
+### 4.4 `Button`
+**Variantes:**
+- `primary` — bg `--ember-500`, texto `--surface`, sombra leve. Hover: `--ember-600`.
+- `secondary` (default) — bg `--surface`, texto `--ink-700`, border `--line-200`. Hover: bg `--canvas`.
+- `ghost` — sem bg, sem border, texto `--ink-500`. Hover: bg `--canvas`.
+- `danger` — bg `--danger-500`, texto white. Hover escurece.
+- `link` — texto-only, ember underline no hover.
+
+**Sizes:** `sm` (h 28px, px 10px, fs 12px) · `md` (h 32px, padrão) · `lg` (h 40px).
+
+**Props extras:** `icon` (esquerda), `iconRight`, `full` (width 100%), `disabled` (opacity 0.5, cursor not-allowed).
+
+**Focus:** sempre `--ring-focus` no foco via teclado. Nunca remover outline sem oferecer ring custom.
+
+### 4.5 `Input`
+Container com `icon` (esquerda) e `suffix` (direita opcional). Border `--line-200`, raio `--r-sm`, padding interno `--sp-8 --sp-10`. Focus: border `--ember-400` + `--ring-focus`. State `invalid`: border `--danger-500` + `--ring` em rgba danger. Mono via prop `mono` (font-mono).
+
+### 4.6 `Tag`
+Pill compacto. Tons: `default` (canvas/ink-500), `ember` (ember-100/ember-700), `success`, `warning`, `danger`, `info` (todos usando `--*-50` bg + `--*-700` fg). Sizes `sm`/`md`. Prop `square` muda raio pra `--r-xs`.
+
+### 4.7 `Badge`
+Contador pequeno (notificação). Pill, fs `--fs-2xs`, bg `--ember-500`, fg white. Variants tonais via `tone`.
+
+### 4.8 `Toggle` (switch)
+Container 40×24 (md), 32×20 (sm). Off: bg `--ink-200`. On: bg `--ember-500`. Knob bg white com sombra-xs. Animação: `--t-base ease-out` no knob translateX.
+
+### 4.9 `Segmented`
+Grupo de botões em pill (radio horizontal). Bg `--canvas`, item ativo: bg `--surface` + sombra-xs. Item inativo: text `--ink-400`. Transição `--t-fast`.
+
+### 4.10 `Avatar`
+Quadrado/círculo com inicial. Default 24px, bg `--ember-500`, fg white, fw 600. Prop `square` true → `--r-sm`, false → `--r-pill`.
+
+### 4.11 `Kbd`
+Tecla. `<kbd>` styled: bg `--canvas`, border `--line-200`, raio `--r-xs`, font-mono, fs `--fs-2xs`, padding `2px 6px`, sombra-inset.
+
+---
+
+## 5. Componentes (`components.jsx`)
+
+Mais complexos, compostos de primitivos.
+
+### 5.1 Cards / Endpoint cards
+Layout: ícone à esquerda, label heading + tag à direita, descrição abaixo. Use em listagens (API endpoints, integrações, plans).
+
+### 5.2 Showcases (Buttons / Inputs / Tags)
+Padrão de organização visual: linha (`ComponentRow`) com label sticky à esquerda + variantes lado a lado à direita. Use pra documentação interna do design system.
+
+### 5.3 Sidebar item
+Linha com ícone (16px), label, opcional `sub` (descrição menor cinza), opcional `kbd` (atalho). Estado active: bg `--canvas` + barra `--ember-500` à esquerda (3px width). Hover: bg `--line-100`.
+
+### 5.4 Nav showcase
+Demo de top nav: brand logo à esquerda, items centrais, ações à direita (search, avatar). Altura `--topbar-h`, border-bottom `--line-200`.
+
+---
+
+## 6. Layouts (`layouts.jsx`)
+
+### 6.1 `HeaderBar`
+Topo fixo, altura 56px, bg `--surface`, border-bottom `--line-200`. Contém: brand (esquerda), nav (centro), search + avatar (direita).
+
+### 6.2 `Sidebar`
+Lateral 240px, bg `--canvas`, border-right `--line-200`. Contém: brand, search input, list de items agrupados por section (uppercase eyebrow `--ink-400` `--fs-2xs` tracking-wider).
+
+### 6.3 `DashboardLayout`
+Composição: HeaderBar + Sidebar + main content area. Main: padding `--sp-24`, max-width opcional `--container-max`.
+
+### 6.4 `HeroLayout`
+Marketing/landing. Centered text (max-width 720px), título font-display `--fs-5xl/6xl`, kicker em ember pequeno uppercase, CTA primary + secondary side-by-side abaixo.
+
+### 6.5 `PlaygroundLayout`
+Demo interativo. Painel esquerdo (controls/inputs), painel direito (preview). Divisor vertical hairline.
+
+### 6.6 `FooterShowcase`
+Footer mínimo: 4 colunas de links com headings + brand+copy à esquerda. bg `--canvas`, border-top `--line-200`.
+
+---
+
+## 7. Patterns (`patterns.jsx`)
+
+### 7.1 Modal
+Overlay `rgba(20,17,12,0.6)` (light) ou `rgba(0,0,0,0.7)` (dark). Modal: max-width 480px, raio `--r-xl`, sombra `--shadow-modal`. Header: título + close icon. Body. Footer: botões à direita.
+
+### 7.2 CodeBlock
+Bg `--code-bg`, fg `--code-fg`, raio `--r-md`, padding `--sp-12`, font-mono `--fs-md`. Copy button no canto top-right (ghost size sm). Use `<pre><code>`.
+
+### 7.3 DataTable
+Header: bg `--canvas`, fs `--fs-sm`, fw `--fw-medium`, uppercase letter-spacing-wide, padding `--sp-8 --sp-12`. Row: hover bg `--line-100`. Cell: fs `--fs-md`, padding `--sp-10 --sp-12`. Border-bottom `--line-200` em todas as rows. Selected row: bg `--ember-50` + border-left 2px `--ember-500`.
+
+### 7.4 DatePicker
+Calendar grid 7×6, dias 32px square. Today: dot ember abaixo. Selected: bg `--ember-500` text white. Hover: bg `--canvas`. Range: bg `--ember-50` (entre datas), endpoints bg `--ember-500`.
+
+### 7.5 Banner
+Tons: `info` (info-50 bg, info-700 fg), `success`, `warning`, `danger`. Layout: ícone + texto + close X opcional + CTA opcional à direita. Padding `--sp-12 --sp-16`. Border-left 3px na cor do tom.
+
+---
+
+## 8. Brand (`brand.jsx`)
+
+### 8.1 ZarkLogo
+Variants: `full` (icon + wordmark) · `mark` (só ícone) · `wordmark` (só texto). Default size 28px. Usa font-display Darker Grotesque para wordmark.
+
+### 8.2 AsciiBackdrop / AsciiCurve
+Background decorativo retro. ASCII chars em `--ink-200` opacity 0.55 num grid. Use em hero sections, login screens, brand moments. Não usar em UI funcional.
+
+---
+
+## 9. Iconografia (`icons.jsx`)
+
+**Padrão**: outline, stroke 1.5px, viewBox 18×18, `currentColor`. Tamanhos: 14 (denso), 16 (default), 18 (botão), 20 (header), 24 (display).
+
+Evite ícones preenchidos (filled) salvo em badge/notificação. Mantenha consistência: se um ícone é outline, todos os outros na mesma linha visual também são.
+
+Quando precisar de ícone que não existe: criar seguindo as mesmas regras (1.5px stroke, 18 viewBox), ou usar lucide-icons (que segue padrão similar).
+
+---
+
+## 10. Como aplicar em qualquer stack
+
+### Workflow recomendado pra IA
+
+1. **Importar tokens.css** no entry-point do projeto (ex: `src/styles/global.css` em Next, `app.css` em Laravel, `static/css/zark.css` em Django).
+2. **Identificar a unidade equivalente na stack alvo** — em React: componente .jsx; em Vue: .vue; em Blade: partial `.blade.php`; em Django: `{% include %}` template; em HTML/Tailwind: classe utility.
+3. **Reler a definição do primitivo no JSX** + olhar o PNG correspondente em `visual-references/`.
+4. **Implementar usando vars CSS** — `var(--ember-500)`, `var(--paper)` etc. Nunca hardcode `#f56f10` no código stack-side.
+5. **Variantes via prop ou data-attribute** (`data-variant="primary"`), nunca via classe utility crua sem semântica.
+6. **Testar light + dark** com `<html data-theme="dark">`.
+7. **Ajustar tipografia/spacing** seguindo escala dos tokens (`--sp-*`, `--fs-*`).
+
+### Exemplos de tradução
+
+**JSX (referência)**:
+```jsx
+<button style={{
+  background: 'var(--ember-500)',
+  color: 'var(--surface)',
+  height: 32, padding: '0 14px',
+  borderRadius: 'var(--r-sm)',
+  fontWeight: 500
+}}>Save</button>
+```
+
+**Tailwind + CSS vars** (recomendado):
+```html
+<button class="h-8 px-3.5 rounded font-medium" style="background: var(--ember-500); color: var(--surface);">Save</button>
+```
+
+**Vue 3**:
+```vue
+<template>
+  <button :class="['btn', `btn-${variant}`]"><slot /></button>
+</template>
+<style scoped>
+.btn-primary { background: var(--ember-500); color: var(--surface); }
+</style>
+```
+
+**Laravel Blade**:
+```php
+<button {{ $attributes->merge(['class' => 'zk-btn zk-btn-primary']) }}>
+  {{ $slot }}
+</button>
+```
++ `zk-btn-primary` no CSS global usando vars.
+
+**Django template**:
+```django
+{% include "components/button.html" with variant="primary" label="Save" %}
+```
+
+**HTML puro**:
+```html
+<button style="background: var(--ember-500); color: var(--surface); height: 32px; padding: 0 14px; border-radius: var(--r-sm); font-weight: 500;">
+  Save
+</button>
+```
+
+### Checklist quando implementar uma tela
+
+- [ ] `tokens.css` importado no entry-point
+- [ ] Toggle de tema (light/dark) implementado
+- [ ] Tipografia: Inter carregado (Google Fonts ou self-hosted), fallback `-apple-system`
+- [ ] Cores: nenhum hex hardcoded — tudo via `var(--...)`
+- [ ] Spacing: usando escala `--sp-*`, sem números mágicos
+- [ ] Hairlines (1px) em vez de borders grossos
+- [ ] Focus visível em todo elemento interativo (`--ring-focus`)
+- [ ] Microinterações em `--t-fast` (120ms) ou `--t-base` (180ms)
+- [ ] Brand `--ember-500` usado com moderação (CTAs, focus, brand moments)
+- [ ] Conferiu visualmente contra `visual-references/*.png` correspondente
+
+---
+
+## 11. O que NÃO fazer
+
+- ❌ Trocar a cor de marca por outra. Ember `#f56f10` é assinatura.
+- ❌ Usar `border: 1px solid black` quando o token é `--line-200`.
+- ❌ Hardcode de cor (`#fafaf8` etc) — sempre use vars.
+- ❌ Sombras frias `rgba(0,0,0,...)` — use as warm `rgba(20,17,12,...)`.
+- ❌ Border-radius inconsistente — use a escala (`--r-sm` em forms, `--r-lg` em cards).
+- ❌ Tipografia fora da escala (`13.5px` etc).
+- ❌ Display font (Darker Grotesque) em UI texto — só hero/marketing.
+- ❌ Animação > 280ms em microinterações.
+- ❌ Brand color como bg dominante de tela inteira.
+- ❌ Substituir Inter por outra fonte sans sem justificativa documentada.
+
+---
+
+## 12. Arquivos neste diretório
+
+| Arquivo | Conteúdo |
+|---|---|
+| `REFERENCE.md` | Este documento (cérebro do sistema) |
+| `tokens.css` | Todas as variáveis CSS (light + dark) |
+| `primitives.jsx` | Section, Panel, Spec, Button, Input, Tag, Badge, Toggle, Segmented, Avatar, Kbd |
+| `components.jsx` | Cards, Showcases, SidebarItem, NavShowcase |
+| `layouts.jsx` | HeaderBar, Sidebar, DashboardLayout, HeroLayout, PlaygroundLayout, FooterShowcase |
+| `patterns.jsx` | Modal, CodeBlock, DataTable, DatePicker, Banner |
+| `brand.jsx` | ZarkLogo, AsciiBackdrop, AsciiCurve |
+| `foundations.jsx` | Tipografia/escala/cores em formato visual |
+| `icons.jsx` | Set de ícones outline 18px |
+| `design-canvas.jsx` | Figma-like canvas wrapper (referência de organização interna do design) |
+| `SHOWCASE.html` | Renderização offline do design system (abra no browser) |
+| `visual-references/*.png` | Screenshots originais da composição — ground truth visual |
+| `assets/` | Logo + ícone ZARK |
+
+**Quando dúvida sobre aparência exata** → abra `SHOWCASE.html` no browser ou os PNGs em `visual-references/`.
+**Quando dúvida sobre comportamento** → reler o componente correspondente em `.jsx` (estrutura) + esta referência (semântica).
+
+---
+
+*Versão deste documento: 1.0 — gerado por `npx zark-design init`. Mantido em <https://github.com/mayconjordanr/zark-design>.*