@stacklist-app/brandkit 1.1.1 → 1.2.1

package/lib/export.js

@@ -0,0 +1,356 @@
+/**
+ * Agent-native exports — project a render-shaped config.json into machine-first
+ * views an AI agent or design-token tool can consume without scraping the HTML.
+ *
+ *   buildBrandJson(config)     → normalized, semantic brand (roles, usage, contrast, asset paths)
+ *   buildTokensJson(config)    → W3C Design Tokens (DTCG) format for token tooling
+ *   buildBrandMarkdown(config) → an LLM brief ("how to be on-brand") a.k.a. llms.txt
+ *
+ * Pure functions, Node builtins only. Contrast is computed via generate-helpers.
+ */
+var fs = require('fs');
+var path = require('path');
+var helpers = require('./generate-helpers');
+
+var HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+// Map format aliases to the canonical set.
+function normalizeFormats(formats) {
+  if (!formats || formats === 'all') return ['json', 'dtcg', 'md'];
+  var list = Array.isArray(formats) ? formats : [formats];
+  var canon = [];
+  list.forEach(function (f) {
+    f = String(f).toLowerCase();
+    if (f === 'all') { canon = ['json', 'dtcg', 'md']; }
+    else if (f === 'json' || f === 'brand') { if (canon.indexOf('json') === -1) canon.push('json'); }
+    else if (f === 'dtcg' || f === 'tokens') { if (canon.indexOf('dtcg') === -1) canon.push('dtcg'); }
+    else if (f === 'md' || f === 'markdown' || f === 'llms') { if (canon.indexOf('md') === -1) canon.push('md'); }
+  });
+  // Return canon as-is (possibly empty) so an unknown format surfaces as
+  // "nothing written" rather than silently writing every file.
+  return canon;
+}
+
+/**
+ * Write the requested export files into targetDir. Returns the written
+ * filenames and the brand.json object (so callers can also embed it).
+ */
+function writeExports(config, targetDir, formats) {
+  var want = normalizeFormats(formats);
+  var written = [];
+  var brandJson = null;
+  if (want.indexOf('json') !== -1) {
+    brandJson = buildBrandJson(config);
+    fs.writeFileSync(path.join(targetDir, 'brand.json'), JSON.stringify(brandJson, null, 2) + '\n');
+    written.push('brand.json');
+  }
+  if (want.indexOf('dtcg') !== -1) {
+    fs.writeFileSync(path.join(targetDir, 'tokens.json'), JSON.stringify(buildTokensJson(config), null, 2) + '\n');
+    written.push('tokens.json');
+  }
+  if (want.indexOf('md') !== -1) {
+    fs.writeFileSync(path.join(targetDir, 'brand.md'), buildBrandMarkdown(config));
+    written.push('brand.md');
+  }
+  return { written: written, brandJson: brandJson };
+}
+
+function isHex(v) {
+  return typeof v === 'string' && HEX_RE.test(v);
+}
+
+// "#4338CA on #FFFFFF" → { ratio: "7.9:1", rating: "AAA" }
+function contrast(fg, bg) {
+  if (!isHex(fg) || !isHex(bg)) return null;
+  var ratio = helpers.contrastRatio(fg, bg);
+  return { ratio: ratio, rating: helpers.rateContrast(ratio) };
+}
+
+function themeVal(config, key) {
+  return config.theme && config.theme[key];
+}
+
+/**
+ * Normalized, agent-first brand. Encodes roles + usage + contrast, not layout.
+ */
+function buildBrandJson(config) {
+  config = config || {};
+  var brand = config.brand || {};
+  var theme = config.theme || {};
+  var fonts = config.fonts || {};
+  var colors = config.colors || {};
+
+  var accentFill = theme['--accent'];
+  var accentOnFill = theme['--accent-foreground'];
+  var accentText = theme['--accent-text'];
+
+  var out = {
+    name: brand.name || null,
+    displayName: brand.displayName || brand.name || null,
+    tagline: brand.tagline || null,
+    description: brand.description || null,
+    url: brand.url || null,
+    version: brand.version || null,
+    generatedBy: 'brandkit',
+    voice: config.voice ? {
+      summary: config.voice.description || null,
+      do: config.voice.do || [],
+      dont: config.voice.dont || []
+    } : null,
+    color: {
+      accent: accentFill ? {
+        fill: accentFill,
+        onFill: accentOnFill || null,
+        asText: accentText || null,
+        contrast: {
+          onFill: accentOnFill ? contrast(accentOnFill, accentFill) : null,
+          asTextOnWhite: accentText ? contrast(accentText, theme['--white'] || '#FFFFFF') : null
+        }
+      } : null,
+      // Only surfaced when a brand separates its primary action from the accent.
+      primary: theme['--primary'] ? {
+        fill: theme['--primary'],
+        onFill: theme['--primary-foreground'] || null,
+        contrast: {
+          onFill: theme['--primary-foreground'] ? contrast(theme['--primary-foreground'], theme['--primary']) : null
+        }
+      } : null,
+      brand: projectColorGroup(colors.brand),
+      neutral: projectColorGroup(colors.neutrals),
+      semantic: projectColorGroup(colors.semantic)
+    },
+    gradient: (theme['--gradient-brand'] || config.gradientUsage) ? {
+      brand: theme['--gradient-brand'] || null,
+      subtle: theme['--gradient-brand-subtle'] || null,
+      usage: config.gradientUsage ? {
+        do: config.gradientUsage.do || [],
+        dont: config.gradientUsage.dont || []
+      } : null
+    } : null,
+    type: {
+      display: projectFont(fonts.display),
+      body: projectFont(fonts.body),
+      scale: (config.typography || []).map(function (t) {
+        return { name: t.name, size: t.size, weight: t.weight, font: t.font };
+      })
+    },
+    spacing: (config.spacing || []).map(function (s) {
+      return { token: s.token, px: s.px };
+    }),
+    logos: (config.logos || []).map(function (l) {
+      var variants = l.variants || {};
+      var formats = Object.keys(variants);
+      return {
+        name: l.name,
+        description: l.description || null,
+        use: backgroundToUse(l.background),
+        formats: formats,
+        src: variants.svg || variants.png || variants.jpg || (formats.length ? variants[formats[0]] : null),
+        variants: variants
+      };
+    }),
+    accessibility: (config.accessibility || []).map(function (a) {
+      return {
+        pair: (a.fgName || a.fg || '') + ' on ' + (a.bgName || a.bg || ''),
+        fg: a.fg, bg: a.bg, ratio: a.ratio, rating: a.rating
+      };
+    })
+  };
+
+  return prune(out);
+}
+
+function projectColorGroup(group) {
+  if (!group) return [];
+  var items = group.items || group;
+  if (!Array.isArray(items)) return [];
+  return items.map(function (c) {
+    return prune({
+      name: c.name || c.label || null,
+      hex: c.hex || null,
+      oklch: c.oklch || null,
+      role: c.role || c.usage || null,
+      token: c.cssVar || c.token || null
+    });
+  });
+}
+
+function projectFont(f) {
+  if (!f) return null;
+  return prune({ family: f.family || null, googleImport: f.googleImport || null, description: f.description || null });
+}
+
+// "Space Grotesk — Space Grotesk — a geometric sans" → "Space Grotesk — a geometric sans"
+function fontLine(f) {
+  var family = f.family || '';
+  var desc = f.description || '';
+  if (desc) {
+    var stripped = desc.replace(new RegExp('^' + family.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*[—:-]\\s*'), '');
+    return family + (stripped ? ' — ' + stripped : '');
+  }
+  return family;
+}
+
+function backgroundToUse(bg) {
+  if (bg === 'light') return 'light backgrounds';
+  if (bg === 'dark') return 'dark backgrounds';
+  if (bg === 'gradient') return 'the brand gradient';
+  return null;
+}
+
+/**
+ * W3C Design Tokens (DTCG) — color / fontFamily / dimension groups.
+ * Strict-ish so Style Dictionary, Tokens Studio, and Figma can read it.
+ */
+function buildTokensJson(config) {
+  config = config || {};
+  var theme = config.theme || {};
+  var fonts = config.fonts || {};
+  var brand = config.brand || {};
+
+  var color = {};
+  Object.keys(theme).forEach(function (key) {
+    var val = theme[key];
+    if (isHex(val)) {
+      color[key.replace(/^--/, '')] = { $type: 'color', $value: val };
+    }
+  });
+
+  var fontFamily = {};
+  if (fonts.display && fonts.display.family) fontFamily.display = { $type: 'fontFamily', $value: fonts.display.family };
+  if (fonts.body && fonts.body.family) fontFamily.body = { $type: 'fontFamily', $value: fonts.body.family };
+
+  var dimension = {};
+  (config.spacing || []).forEach(function (s) {
+    if (s.token && (s.px || s.px === 0)) dimension[s.token] = { $type: 'dimension', $value: s.px + 'px' };
+  });
+
+  var out = {
+    $description: 'Design tokens for ' + (brand.displayName || brand.name || 'brand') + ' — W3C DTCG format, generated by brandkit'
+  };
+  if (Object.keys(color).length) out.color = color;
+  if (Object.keys(fontFamily).length) out.fontFamily = fontFamily;
+  if (Object.keys(dimension).length) out.dimension = dimension;
+  return out;
+}
+
+/**
+ * LLM brief — drop into an agent's context to write/design on-brand.
+ */
+function buildBrandMarkdown(config) {
+  config = config || {};
+  var brand = config.brand || {};
+  var theme = config.theme || {};
+  var fonts = config.fonts || {};
+  var name = brand.displayName || brand.name || 'Brand';
+  var L = [];
+
+  L.push('# ' + name + ' — Brand Brief');
+  L.push('');
+  L.push('> Machine-readable brand guidance generated by brandkit from `config.json`.');
+  L.push('> Companion files: `brand.json` (full structured brand), `tokens.json` (W3C design tokens).');
+  if (brand.description) { L.push(''); L.push(brand.description); }
+
+  if (config.voice) {
+    L.push(''); L.push('## Voice & Tone');
+    if (config.voice.description) L.push(config.voice.description);
+    if (config.voice.do && config.voice.do.length) {
+      L.push(''); L.push('**Do:**');
+      config.voice.do.forEach(function (d) { L.push('- ' + d); });
+    }
+    if (config.voice.dont && config.voice.dont.length) {
+      L.push(''); L.push("**Don't:**");
+      config.voice.dont.forEach(function (d) { L.push('- ' + d); });
+    }
+  }
+
+  L.push(''); L.push('## Color');
+  var accent = theme['--accent'];
+  if (accent) {
+    var onFill = theme['--accent-foreground'];
+    var asText = theme['--accent-text'];
+    var c1 = onFill ? contrast(onFill, accent) : null;
+    var c2 = asText ? contrast(asText, theme['--white'] || '#FFFFFF') : null;
+    L.push('- **Accent (fill):** `' + accent + '`' + (onFill ? ' — put `' + onFill + '` text/icons on it' + (c1 ? ' (' + c1.ratio + ' ' + c1.rating + ')' : '') : '') + '.');
+    if (asText) L.push('- **Accent as text/links on light:** `' + asText + '`' + (c2 ? ' (' + c2.ratio + ' ' + c2.rating + ' on white)' : '') + '.');
+  }
+  var primary = theme['--primary'];
+  if (primary && primary !== accent) {
+    var pOn = theme['--primary-foreground'];
+    var pc = pOn ? contrast(pOn, primary) : null;
+    L.push('- **Primary action (CTA fill):** `' + primary + '`' + (pOn ? ' with `' + pOn + '` text' + (pc ? ' (' + pc.ratio + ' ' + pc.rating + ')' : '') : '') + '.');
+  }
+  var sem = [];
+  ['--success', '--warning', '--error'].forEach(function (k) {
+    if (theme[k]) sem.push(k.replace('--', '') + ' `' + theme[k] + '`');
+  });
+  if (sem.length) L.push('- **Semantic:** ' + sem.join(', ') + '.');
+  var neutralBits = [];
+  if (theme['--ink']) neutralBits.push('Ink `' + theme['--ink'] + '` (primary text)');
+  if (theme['--slate']) neutralBits.push('Slate `' + theme['--slate'] + '` (muted)');
+  if (theme['--cloud']) neutralBits.push('Cloud `' + theme['--cloud'] + '` (page bg)');
+  if (neutralBits.length) L.push('- **Neutrals:** ' + neutralBits.join(', ') + '.');
+
+  // Surface any low-contrast pairs as explicit warnings
+  var warns = (config.accessibility || []).filter(function (a) {
+    return a.rating && a.rating !== 'AAA' && a.rating !== 'AA';
+  });
+  if (warns.length) {
+    L.push(''); L.push('**Contrast cautions:**');
+    warns.forEach(function (a) {
+      var note = a.rating === 'AA Large' ? ' — large text only.' : ' — fails AA; do not use this pair for text.';
+      L.push('- ' + (a.fgName || a.fg) + ' on ' + (a.bgName || a.bg) + ' is ' + a.ratio + ' (' + a.rating + ')' + note);
+    });
+  }
+
+  if (fonts.display || fonts.body) {
+    L.push(''); L.push('## Typography');
+    if (fonts.display) L.push('- **Display:** ' + fontLine(fonts.display));
+    if (fonts.body) L.push('- **Body:** ' + fontLine(fonts.body));
+  }
+
+  if (config.logos && config.logos.length) {
+    L.push(''); L.push('## Logos');
+    config.logos.forEach(function (l) {
+      var use = backgroundToUse(l.background);
+      var variants = l.variants || {};
+      var src = variants.svg || variants.png || variants.jpg || '';
+      L.push('- **' + l.name + '**' + (use ? ' — use on ' + use : '') + (src ? ' — `' + src + '`' : ''));
+    });
+  }
+
+  if (theme['--gradient-brand']) {
+    L.push(''); L.push('## Gradient');
+    L.push('- **Brand gradient:** `' + theme['--gradient-brand'] + '`');
+    if (config.gradientUsage) {
+      if (config.gradientUsage.do && config.gradientUsage.do.length) L.push('- Use for: ' + config.gradientUsage.do.join('; ') + '.');
+      if (config.gradientUsage.dont && config.gradientUsage.dont.length) L.push("- Don't use for: " + config.gradientUsage.dont.join('; ') + '.');
+    }
+  }
+
+  L.push('');
+  return L.join('\n');
+}
+
+// Recursively drop null / empty-array / empty-object keys for a clean export.
+function prune(obj) {
+  if (Array.isArray(obj)) return obj.map(prune);
+  if (obj === null || typeof obj !== 'object') return obj;
+  var out = {};
+  Object.keys(obj).forEach(function (k) {
+    var v = prune(obj[k]);
+    if (v === null || v === undefined) return;
+    if (Array.isArray(v) && v.length === 0) return;
+    if (typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0) return;
+    out[k] = v;
+  });
+  return out;
+}
+
+module.exports = {
+  buildBrandJson: buildBrandJson,
+  buildTokensJson: buildTokensJson,
+  buildBrandMarkdown: buildBrandMarkdown,
+  writeExports: writeExports,
+  normalizeFormats: normalizeFormats
+};

package/lib/extract-css.js

@@ -94,7 +94,7 @@ function mapToTheme(cssVars) {
   var mapping = {
     '--background': '--cloud',
     '--foreground': '--ink',
-    '--primary': '--purple',
+    '--primary': '--accent',
     '--secondary': '--mist',
     '--muted': '--mist',
     '--muted-foreground': '--slate',

package/lib/generate-helpers.js

@@ -226,7 +226,7 @@ function buildHierarchyFromTheme(theme) {
   var fg = resolve('--ink', ['--foreground'], '#111827');
   var secondary = resolve('--graphite', ['--slate', '--muted-foreground'], '#374151');
   var tertiary = resolve('--slate', ['--haze', '--muted-foreground'], '#6B7280');
-  var accent = resolve('--purple', ['--coral', '--primary'], '#6366F1');
+  var accent = resolve('--accent-text', ['--accent', '--purple', '--coral', '--primary'], '#6366F1');
 
   function keyToName(key) {
     return key.replace(/^--/, '').replace(/-/g, ' ').replace(/\b\w/g, function (c) { return c.toUpperCase(); });

package/lib/template.js

@@ -1,5 +1,6 @@
 var fs = require('fs');
 var path = require('path');
+var exporter = require('./export');
 
 /**
  * Generate a :root CSS block from config.theme + config.fonts.
@@ -46,21 +47,27 @@ function generateFontsLink(config) {
  * Writes index.html and styles.css into the target directory.
  */
 function build(distDir, targetDir, config) {
-  // Build styles.css: prepend :root block
+  // Build styles.css: append the config :root AFTER the stylesheet's default
+  // tokens so brand overrides win the cascade (styles.css ships a baseline
+  // :root; an earlier block would be overridden by it).
   var cssTemplate = fs.readFileSync(path.join(distDir, 'styles.css'), 'utf8');
   var rootCSS = generateRootCSS(config);
-  var builtCSS = '/* Generated by brandkit build */\n' + rootCSS + '\n\n' + cssTemplate;
+  var builtCSS = cssTemplate + '\n\n/* Generated by brandkit build — brand overrides */\n' + rootCSS + '\n';
   fs.writeFileSync(path.join(targetDir, 'styles.css'), builtCSS);
 
-  // Build index.html: inject fonts link + title
+  // Agent-native exports: brand.json (semantic), tokens.json (W3C DTCG),
+  // brand.md (LLM brief). brandJson is reused to embed the data in the page.
+  var exported = exporter.writeExports(config, targetDir, 'all');
+
+  // Build index.html: inject fonts link + title + agent-discoverable brand data
   var htmlTemplate = fs.readFileSync(path.join(distDir, 'index.html'), 'utf8');
   var fontsLink = generateFontsLink(config);
   var brandName = (config.brand && config.brand.displayName) || 'Brand';
 
-  // Inject fonts link before </head>
-  if (fontsLink) {
-    htmlTemplate = htmlTemplate.replace('</head>', fontsLink + '\n</head>');
-  }
+  // Inject fonts link + a discovery <link> for the structured brand data
+  var headInject = (fontsLink ? fontsLink + '\n' : '') +
+    '<link rel="alternate" type="application/json" href="brand.json" title="Brand data">\n';
+  htmlTemplate = htmlTemplate.replace('</head>', headInject + '</head>');
 
   // Set title
   htmlTemplate = htmlTemplate.replace(
@@ -68,6 +75,16 @@ function build(distDir, targetDir, config) {
     '<title>' + brandName + ' \u2014 Brand Guide</title>'
   );
 
+  // Embed brand.json inline so an agent that fetches the page gets structured
+  // brand data with zero extra requests or scraping. Every "<" is escaped to
+  // its JSON unicode form (<, which JSON.parse restores to "<"), so no
+  // config value can produce a "</script" sequence and break out of the block.
+  if (exported.brandJson) {
+    var embedded = JSON.stringify(exported.brandJson).replace(/</g, '\\u003C');
+    var embed = '<script type="application/json" id="brandkit-brand">' + embedded + '</script>\n';
+    htmlTemplate = htmlTemplate.replace('</body>', embed + '</body>');
+  }
+
   fs.writeFileSync(path.join(targetDir, 'index.html'), htmlTemplate);
 
   // Copy engine.js as-is
@@ -75,6 +92,8 @@ function build(distDir, targetDir, config) {
     path.join(distDir, 'engine.js'),
     path.join(targetDir, 'engine.js')
   );
+
+  return exported;
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacklist-app/brandkit",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Config-driven brand guide that bolts onto any website. Zero dependencies.",
   "main": "lib/resolve.js",
   "bin": {
@@ -11,7 +11,8 @@
     "cli/",
     "lib/",
     "dist/",
-    "integrations/"
+    "integrations/",
+    "config.schema.json"
   ],
   "scripts": {
     "dev": "node bin/brandkit.js dev example",