zark-design 2.0.0 → 3.0.0

package/bin/cli.js

@@ -3,10 +3,13 @@
 import { promises as fs } from 'node:fs';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.resolve(__dirname, '../templates');
+const PRESETS_DIR = path.join(TEMPLATES_DIR, 'presets');
+const SHARED_DIR = path.join(TEMPLATES_DIR, '_shared');
 const PKG_PATH = path.resolve(__dirname, '../package.json');
 
 const c = {
@@ -27,147 +30,417 @@ function banner(title) {
 
 async function getVersion() {
   try {
-    const pkg = JSON.parse(await fs.readFile(PKG_PATH, 'utf-8'));
-    return pkg.version;
-  } catch {
-    return 'unknown';
+    return JSON.parse(await fs.readFile(PKG_PATH, 'utf-8')).version;
+  } catch { return 'unknown'; }
+}
+
+// ─── Color utils: hex ↔ HSL, palette generation ──────────────────────────
+
+function hexToRgb(hex) {
+  const h = hex.replace('#', '').trim();
+  const s = h.length === 3 ? h.split('').map(x => x + x).join('') : h;
+  if (s.length !== 6 || !/^[0-9a-f]{6}$/i.test(s)) {
+    throw new Error(`Hex inválido: "${hex}" (esperado #RRGGBB ou #RGB)`);
   }
+  return [parseInt(s.slice(0, 2), 16), parseInt(s.slice(2, 4), 16), parseInt(s.slice(4, 6), 16)];
 }
 
-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);
+function rgbToHex(r, g, b) {
+  const cl = (v) => Math.max(0, Math.min(255, Math.round(v)));
+  return '#' + [cl(r), cl(g), cl(b)].map(v => v.toString(16).padStart(2, '0')).join('');
+}
+
+function rgbToHsl(r, g, b) {
+  r /= 255; g /= 255; b /= 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  let h = 0, s = 0; const l = (max + min) / 2;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r: h = (g - b) / d + (g < b ? 6 : 0); break;
+      case g: h = (b - r) / d + 2; break;
+      case b: h = (r - g) / d + 4; break;
     }
+    h /= 6;
   }
+  return [h * 360, s * 100, l * 100];
 }
 
-async function appendNoteToContextFiles(targetRoot, designDirName) {
-  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`;
+function hslToRgb(h, s, l) {
+  h /= 360; s /= 100; l /= 100;
+  if (s === 0) { const v = l * 255; return [v, v, v]; }
+  const hue2rgb = (p, q, t) => {
+    if (t < 0) t += 1; if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  return [hue2rgb(p, q, h + 1 / 3) * 255, hue2rgb(p, q, h) * 255, hue2rgb(p, q, h - 1 / 3) * 255];
+}
 
-  const candidates = [
-    path.join(targetRoot, '.ai-context', 'CONTEXT.md'),
-    path.join(targetRoot, 'CLAUDE.md'),
+// Gera escala 50→900 a partir de uma cor base (assumida como 500/primary).
+// Mantém o matiz, varia luminosidade e ajusta saturação por tier.
+function generatePalette(baseHex) {
+  const [h, s, l] = rgbToHsl(...hexToRgb(baseHex));
+  // Tabela de target lightness por tier; saturação ajustada nos extremos
+  const tiers = [
+    { k: 50,  L: 95, sScale: 0.55 },
+    { k: 100, L: 88, sScale: 0.70 },
+    { k: 200, L: 78, sScale: 0.85 },
+    { k: 300, L: 68, sScale: 0.95 },
+    { k: 400, L: 58, sScale: 1.00 },
+    { k: 500, L: Math.round(l), sScale: 1.00 }, // mantém a cor base
+    { k: 600, L: Math.max(l - 8, 38), sScale: 1.00 },
+    { k: 700, L: Math.max(l - 18, 28), sScale: 1.00 },
+    { k: 800, L: Math.max(l - 28, 20), sScale: 0.95 },
+    { k: 900, L: Math.max(l - 38, 12), sScale: 0.85 },
   ];
+  const out = {};
+  for (const t of tiers) {
+    if (t.k === 500) { out[500] = baseHex.toLowerCase(); continue; }
+    const tS = Math.min(100, s * t.sScale);
+    const [r, g, b] = hslToRgb(h, tS, t.L);
+    out[t.k] = rgbToHex(r, g, b);
+  }
+  // Rings (rgba)
+  const [r5, g5, b5] = hexToRgb(out[500]);
+  const [r4, g4, b4] = hexToRgb(out[400]);
+  out.ring         = `rgba(${r5}, ${g5}, ${b5}, 0.20)`;
+  out.ringSoft     = `rgba(${r5}, ${g5}, ${b5}, 0.12)`;
+  out.ringDark     = `rgba(${r4}, ${g4}, ${b4}, 0.30)`;
+  out.ringSoftDark = `rgba(${r4}, ${g4}, ${b4}, 0.16)`;
+  return out;
+}
 
-  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)';
+// ─── Template engine: tiny Handlebars subset ─────────────────────────────
+// Suporta {{var}}, {{var.nested}}, {{#if x}}...{{/if}}, {{#if x}}A{{else}}B{{/if}}
+
+function renderTemplate(src, ctx) {
+  const get = (path) => path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), ctx);
+  // Process {{#if cond}}...{{else}}...{{/if}} blocks (no nesting needed for our cases)
+  let out = src;
+  let prev;
+  do {
+    prev = out;
+    out = out.replace(
+      /\{\{#if\s+([\w.]+)\s*\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if\}\}/g,
+      (_, cond, a, b) => {
+        const v = get(cond);
+        return v ? a : (b || '');
+      }
+    );
+  } while (out !== prev);
+  // Replace {{var}}
+  out = out.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => {
+    const v = get(key);
+    return v == null ? '' : String(v);
+  });
+  return out;
+}
+
+// ─── FS helpers ──────────────────────────────────────────────────────────
+
+async function copyDir(src, dest, ctx, opts = {}) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const e of entries) {
+    const sp = path.join(src, e.name);
+    const dp = path.join(dest, e.name);
+    if (e.isDirectory()) await copyDir(sp, dp, ctx, opts);
+    else if (e.isFile()) {
+      if (sp.endsWith('.hbs')) {
+        const content = await fs.readFile(sp, 'utf-8');
+        const rendered = renderTemplate(content, ctx);
+        const finalPath = dp.replace(/\.hbs$/, '');
+        await fs.writeFile(finalPath, rendered, 'utf-8');
+        opts.written?.push(path.relative(opts.targetRoot, finalPath));
+      } else {
+        await fs.copyFile(sp, dp);
+        opts.written?.push(path.relative(opts.targetRoot, dp));
       }
-      await fs.writeFile(realFile, current + note, 'utf-8');
-      return realFile + ' (nota adicionada)';
-    } catch {
-      // continue
     }
   }
-  return null;
 }
 
+// ─── Prompts (readline nativo) ───────────────────────────────────────────
+
+function makePrompt() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return {
+    ask: (q, def) => new Promise(resolve => {
+      const prompt = def ? `  ${q} ${c.dim(`(${def})`)} ` : `  ${q} `;
+      rl.question(prompt, (a) => resolve(a.trim() || def || ''));
+    }),
+    yn: (q, def = true) => new Promise(resolve => {
+      const d = def ? 'S/n' : 's/N';
+      rl.question(`  ${q} ${c.dim(`(${d})`)} `, (a) => {
+        const v = a.trim().toLowerCase();
+        if (v === '') return resolve(def);
+        resolve(v.startsWith('s') || v.startsWith('y'));
+      });
+    }),
+    close: () => rl.close(),
+  };
+}
+
+function slugify(s) {
+  return s.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+// ─── Help + List ─────────────────────────────────────────────────────────
+
 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(`    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`);
+  console.log(`    ${c.green('init')} ${c.dim('[flags]')}    cria design system (preset ou custom)`);
+  console.log(`    ${c.green('presets')}          lista presets disponíveis`);
+  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(`    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('Output:')}`);
+  console.log(`    design-system/                  ${c.dim('# default; mude com [pasta]')}`);
+  console.log(`      ├── README.md`);
+  console.log(`      ├── html/  (HTML puro)`);
+  console.log(`      ├── jsx/   (React)`);
+  console.log(`      └── assets/ (logos)\n`);
+}
+
+async function listPresets() {
+  banner('Presets disponíveis');
+  const entries = await fs.readdir(PRESETS_DIR, { withFileTypes: true });
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const cfgPath = path.join(PRESETS_DIR, e.name, 'preset.json');
+    if (existsSync(cfgPath)) {
+      const cfg = JSON.parse(await fs.readFile(cfgPath, 'utf-8'));
+      console.log(`  ${c.green('•')} ${c.bold(e.name.padEnd(10))} ${c.dim(`${cfg.name} · brand ${cfg.brand['500']}`)}`);
+    }
+  }
+  console.log('');
+  console.log(c.dim('  Uso: npx zark-design init --preset <nome>'));
+}
+
+// ─── Init logic ──────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const flags = {}; const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) { flags[key] = true; }
+      else { flags[key] = next; i++; }
+    } else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+async function loadPreset(name) {
+  const cfgPath = path.join(PRESETS_DIR, name, 'preset.json');
+  if (!existsSync(cfgPath)) {
+    const available = (await fs.readdir(PRESETS_DIR)).filter(x => !x.startsWith('.'));
+    throw new Error(`Preset "${name}" não existe. Disponíveis: ${available.join(', ')}`);
+  }
+  return JSON.parse(await fs.readFile(cfgPath, 'utf-8'));
+}
+
+async function loadCustomPalette(jsonPath) {
+  const data = JSON.parse(await fs.readFile(jsonPath, 'utf-8'));
+  if (!data.brand || !data.brand['500']) {
+    throw new Error('Paleta JSON precisa ter pelo menos { "name": ..., "brand": { "500": "#..." } }');
+  }
+  // Se faltam tiers, gera os ausentes a partir do 500
+  const filled = generatePalette(data.brand['500']);
+  data.brand = { ...filled, ...data.brand };
+  data.name = data.name || 'Custom';
+  data.slug = data.slug || slugify(data.name);
+  data.fonts = data.fonts || { ui: 'Inter', mono: 'JetBrains Mono', display: 'Space Grotesk' };
+  return data;
+}
+
+async function buildCtx({ flags, prompt }) {
+  // 1) Preset path
+  if (flags.preset) {
+    const preset = await loadPreset(flags.preset);
+    if (!flags.yes && !prompt) return preset;
+    return preset;
+  }
+  // 2) Palette JSON path
+  if (flags.palette) {
+    const data = await loadCustomPalette(path.resolve(flags.palette));
+    data.preset = null;
+    return data;
+  }
+  // 3) Flags directos (custom não-interativo)
+  if (flags.name || flags.primary) {
+    const name = flags.name || 'Custom';
+    const slug = flags.slug || slugify(name);
+    const primary = flags.primary;
+    if (!primary) throw new Error('--primary <hex> é obrigatório quando usa --name sem --palette');
+    return {
+      name, slug, preset: null,
+      brand: generatePalette(primary),
+      fonts: { ui: 'Inter', mono: 'JetBrains Mono', display: 'Space Grotesk' },
+    };
+  }
+  // 4) Interativo
+  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 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):');
+  if (!primary) throw new Error('Cor primária é obrigatória.');
+  const palette = generatePalette(primary);
+  return {
+    name, slug, preset: null,
+    brand: palette,
+    fonts: { ui: 'Inter', mono: 'JetBrains Mono', display: 'Space Grotesk' },
+  };
 }
 
 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 { flags, positional } = parseArgs(args);
+  const target = path.resolve(positional[0] || './design-system');
   const designDirName = path.basename(target);
-  const projectRoot = path.dirname(target);
+  const force = !!flags.force;
+  const yes = !!flags.yes;
 
   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.`));
+      console.error(c.red(`✗ Pasta '${target}' já existe. Use --force pra sobrescrever.`));
       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`));
+  // Build context (preset OR custom)
+  const interactive = !yes && !flags.preset && !flags.palette && !flags.name && process.stdin.isTTY;
+  const prompt = interactive ? makePrompt() : null;
+  let ctx;
+  try {
+    ctx = await buildCtx({ flags, prompt });
+  } finally { prompt?.close(); }
 
-  await copyDir(TEMPLATES_DIR, target);
+  // Defaults
+  ctx.date = new Date().toISOString().slice(0, 10);
+  ctx.nameDesc = ctx.preset === 'zark'
+    ? 'Sistema de design para apps e sistemas internos da ZARK'
+    : `Sistema de design para apps e sistemas do(a) **${ctx.name}**`;
 
-  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);
+  console.log(c.dim('  Contexto:'));
+  console.log(c.dim(`    Nome:    ${ctx.name} (slug: ${ctx.slug})`));
+  console.log(c.dim(`    Modo:    ${ctx.preset ? 'preset ' + ctx.preset : 'custom'}`));
+  console.log(c.dim(`    Brand:   ${ctx.brand['500']} (paleta 50→900 gerada)`));
+  console.log(c.dim(`    Fontes:  ${ctx.fonts.ui} / ${ctx.fonts.mono} / ${ctx.fonts.display}`));
+  console.log(c.dim(`    Destino: ${target}\n`));
 
-  for (const f of fileList) {
-    console.log(`  ${c.green('✓')}  ${f}`);
-  }
+  const written = [];
+  const copyOpts = { targetRoot: target, written };
 
-  console.log('');
-  const noteResult = await appendNoteToContextFiles(projectRoot, designDirName);
-  if (noteResult) {
-    console.log(`  ${c.green('✓')}  ${noteResult}`);
+  // 1. Copia html/ e jsx/ (estáticos, com substituição de .hbs)
+  await copyDir(path.join(TEMPLATES_DIR, 'html'), path.join(target, 'html'), ctx, copyOpts);
+  await copyDir(path.join(TEMPLATES_DIR, 'jsx'),  path.join(target, 'jsx'),  ctx, copyOpts);
+
+  // 2. Renderiza tokens.css.hbs e tokens.js.hbs em html/ e jsx/
+  const tokensCss = renderTemplate(await fs.readFile(path.join(SHARED_DIR, 'tokens.css.hbs'), 'utf-8'), ctx);
+  await fs.writeFile(path.join(target, 'html/tokens.css'), tokensCss);
+  await fs.writeFile(path.join(target, 'jsx/tokens.css'),  tokensCss);
+  written.push('html/tokens.css', 'jsx/tokens.css');
+  const tokensJs = renderTemplate(await fs.readFile(path.join(SHARED_DIR, 'tokens.js.hbs'), 'utf-8'), ctx);
+  await fs.writeFile(path.join(target, 'jsx/tokens.js'), tokensJs);
+  written.push('jsx/tokens.js');
+
+  // 3. README.md
+  const readme = renderTemplate(await fs.readFile(path.join(TEMPLATES_DIR, 'README.md.hbs'), 'utf-8'), ctx);
+  await fs.writeFile(path.join(target, 'README.md'), readme);
+  written.push('README.md');
+
+  // 4. Assets
+  await fs.mkdir(path.join(target, 'assets'), { recursive: true });
+  if (ctx.preset && existsSync(path.join(PRESETS_DIR, ctx.preset, 'assets'))) {
+    // Preset traz assets prontos
+    await copyDir(path.join(PRESETS_DIR, ctx.preset, 'assets'), path.join(target, 'assets'), ctx, copyOpts);
   } else {
-    console.log(c.dim(`  (sem .ai-context/CONTEXT.md ou CLAUDE.md no projeto — sem auto-nota)`));
+    // Custom: pasta vazia + README instrutivo
+    const assetsReadme = renderTemplate(await fs.readFile(path.join(SHARED_DIR, 'ASSETS-README.md.hbs'), 'utf-8'), ctx);
+    await fs.writeFile(path.join(target, 'assets/README.md'), assetsReadme);
+    written.push('assets/README.md (pasta pra você colar seus logos)');
   }
 
+  // Log
+  for (const f of written.sort()) console.log(`  ${c.green('✓')}  ${f}`);
+
+  // Auto-note em CLAUDE.md / .ai-context/CONTEXT.md se existir
   console.log('');
-  console.log(c.green(`✓ Design system instalado em ${designDirName}/`));
+  const noteResult = await appendNoteToContextFiles(path.dirname(target), designDirName, ctx);
+  if (noteResult) console.log(`  ${c.green('✓')}  ${noteResult}`);
+  else console.log(c.dim(`  (sem CLAUDE.md ou .ai-context/CONTEXT.md no projeto — sem auto-nota)`));
+
+  console.log('');
+  console.log(c.green(`✓ Design system "${ctx.name}" instalado em ${designDirName}/`));
   console.log('');
   console.log(c.bold('Próximo passo:'));
+  if (!ctx.preset) {
+    console.log(`  ${c.yellow('•')} Cole seus logos em ${designDirName}/assets/ (veja assets/README.md)`);
+  }
   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.`);
+  console.log(`  ${c.dim('•')} Abra ${designDirName}/html/showcase.html no browser pra ver tudo renderizado.`);
 }
 
+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 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('Design System') && current.includes('design-system')) return realFile + ' (já tem nota — pulando)';
+      await fs.writeFile(realFile, current + note, 'utf-8');
+      return realFile + ' (nota adicionada)';
+    } catch { /* continue */ }
+  }
+  return null;
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────
+
 async function main() {
   const argv = process.argv.slice(2);
-  const cmd = argv[0] ?? 'help';
+  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;
+      case 'init':     return await runInit(argv.slice(1));
+      case 'presets':  return await listPresets();
+      case 'version': case '--version': case '-v': return console.log(version);
+      case 'help': case '--help': case '-h': default: return printHelp(version);
     }
   } catch (e) {
     console.error(c.red(`✗ ${e.message ?? e}`));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zark-design",
-  "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.",
+  "version": "3.0.0",
+  "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.",
   "type": "module",
   "bin": {
     "zark-design": "bin/cli.js"

package/templates/{README.md → README.md.hbs}

@@ -1,8 +1,8 @@
-# ZARK Design System — Apps
+# {{name}} 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`).
+{{nameDesc}}. 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.
+Versão: **v3 · {{date}}** · gerado por `npx zark-design init{{#if preset}} --preset {{preset}}{{/if}}` · App Patterns derivados do CRM real.
 
 ---
 
@@ -65,7 +65,7 @@ design-system-apps/
 
 **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.
+- `--brand-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.
@@ -233,14 +233,14 @@ 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.
+A cor de marca (`--brand-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)`.
+- ❌ 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.

package/templates/_shared/ASSETS-README.md.hbs

@@ -0,0 +1,39 @@
+# assets/ — Logos e ícones do {{name}}
+
+Esta pasta está vazia porque você usou o modo **custom** do `zark-design init`. Cole aqui as imagens da marca do seu sistema.
+
+## Arquivos recomendados
+
+```
+assets/
+├── logo-primary.png        ← logo horizontal completo (cor, fundo claro)
+├── logo-primary-dark.png   ← logo horizontal completo (fundo escuro)
+├── logo-mark.png           ← só o símbolo/mark (sem texto)
+├── icon.png                ← ícone quadrado (favicon, app icon)
+└── (opcional) logo.svg     ← versão vetorial pra escalabilidade
+```
+
+## Tamanhos sugeridos
+
+| Arquivo | Tamanho | Uso |
+|---|---|---|
+| `logo-primary.png` | ~600×180px | Sidebar, topbar, marketing |
+| `logo-mark.png` | ~256×256px | Avatares, badges, espaço apertado |
+| `icon.png` | 512×512px | Favicon, PWA manifest, app store |
+
+## Convenção de nomenclatura nos componentes
+
+Os JSX usam paths relativos. Exemplo em `jsx/components/Sidebar.jsx`:
+
+```jsx
+<img src="../assets/logo-primary.png" alt="{{name}}" />
+```
+
+Mantenha os nomes acima ou ajuste as referências em:
+- `jsx/components/Sidebar.jsx`
+- `html/showcase.html`
+- `html/index.html`
+
+## Logos do {{name}}
+
+> **Nota:** se você não tem os arquivos finais ainda, use placeholders temporários. O design system funciona sem as imagens (o JSX vai mostrar alt-text), mas a sidebar fica esquisita.