@stacklist-app/brandkit 1.1.2 → 1.2.2

package/README.md

@@ -7,9 +7,7 @@ Swap the config and assets to generate a brand guide for any project. An optiona
 ## Install
 
 ```bash
-npm install github:The-Stack-Lab/brandkit
-# or pin to a tag
-npm install github:The-Stack-Lab/brandkit#v1.1.2
+npm install @stacklist-app/brandkit
 ```
 
 Requires Node.js 18+.
@@ -32,7 +30,20 @@ npx brandkit build brand       # bake into static files for production
 | `brandkit init [dir]` | Scaffold a new brand guide with a starter `config.json` |
 | `brandkit generate [dir]` | Extract colors, fonts, spacing, and logos from the host codebase and merge into `config.json`. Manual fields (voice, accessibility, components) are preserved. |
 | `brandkit dev [dir]` | Local dev server on `:4800` with SSE live reload |
-| `brandkit build [dir]` | Produce static `index.html` + `styles.css` + `engine.js` with the theme baked in |
+| `brandkit build [dir]` | Produce static `index.html` + `styles.css` + `engine.js` (theme baked in) **plus** the agent-native exports below |
+| `brandkit export [dir]` | Emit just the agent-native brand data (`--format json\|dtcg\|md\|all`, `--out <dir>`) |
+
+## Agent-readable brand data
+
+A brandkit guide isn't just a page for people — `build` (and the standalone `export` command) emit machine-native views of the brand so an AI agent or design-token tool can consume it without scraping HTML:
+
+- **`brand.json`** — normalized, semantic brand: colors with **roles + contrast pairings**, the accent fill/text split, voice do/don'ts, typography, logos with usage, spacing. The agent-first view.
+- **`tokens.json`** — the same colors, fonts, and spacing in **W3C Design Tokens (DTCG)** format (`{ "$type", "$value" }`), readable by Style Dictionary, Tokens Studio, and Figma.
+- **`brand.md`** — an LLM brief ("how to write/design on-brand") you can drop straight into an agent's context.
+
+`build` also makes the data **discoverable from the deployed page**: it injects `<link rel="alternate" type="application/json" href="brand.json">` and embeds the brand inline as `<script type="application/json" id="brandkit-brand">`, so an agent that fetches the URL gets structured brand data with zero extra requests.
+
+A JSON Schema for `config.json` ships at [`config.schema.json`](config.schema.json) — point your editor's `$schema` at it for validation and autocomplete.
 
 ## Framework integrations
 
@@ -65,7 +76,7 @@ export default {
 `config.json` is the single source of truth. Top-level keys:
 
 - `brand` — name, tagline, description, version, date; optional `guideLabel` (renames the "Web Style Guide" header/footer label), `headerLogo` and `sidebarLogo` (logo image paths that replace the text wordmark in the header and left menu)
-- `fonts` — display + body with Google Fonts import
+- `fonts` — display + body with Google Fonts import; each font takes an optional `fallback` web stand-in for brands whose official typeface isn't web-available (the rendered font stack becomes `'family', 'fallback', sans-serif`, while labels keep the clean family name)
 - `theme` — CSS variable map (colors, gradients, font vars)
 - `nav` — sidebar structure
 - `colors` — brand / neutrals / semantic palettes
@@ -93,6 +104,13 @@ The accent uses a fill/text split (the same convention as Material and shadcn/ui
 
 This lets a low-contrast fill (say a bright orange) stay accessible: set `--accent-foreground: #000000` and `--accent-text` to a darker shade. Pre-1.1.2 configs that set `--purple` / `--purple-rgb` still work — those feed `--accent`.
 
+By default the **primary button** and the **header** carry the accent. Brands that separate a brand role from the accent — e.g. a black primary CTA and a black hero, with orange kept as the accent — override:
+
+- `--primary` / `--primary-foreground` — primary-button fill and the text on it (default to `--accent` / `--accent-foreground`)
+- `--header-bg` — the header/hero background behind the wordmark or logo (defaults to `--gradient-brand`)
+
+The fallbacks mean single-accent brands need set none of these.
+
 - **Dev**: the engine reads `config.theme` and injects a `<style data-brandkit-theme>` block at runtime, which cascades over the defaults.
 - **Build**: `brandkit build` appends the generated `:root` after the stylesheet's defaults and injects the Google Fonts `<link>` and page title into `index.html`.
 

package/bin/brandkit.js

@@ -16,6 +16,9 @@ switch (command) {
   case 'generate':
     require('../cli/generate')(args.slice(1));
     break;
+  case 'export':
+    require('../cli/export')(args.slice(1));
+    break;
   case 'help':
   case '--help':
   case '-h':
@@ -41,6 +44,7 @@ function printHelp() {
   console.log('    brandkit generate [dir]    Auto-generate config from codebase');
   console.log('    brandkit dev [dir]         Start dev server with live reload');
   console.log('    brandkit build [dir]       Build static files for production');
+  console.log('    brandkit export [dir]      Emit agent-native brand data (brand.json, tokens.json, brand.md)');
   console.log('');
   console.log('  Options:');
   console.log('    --help, -h     Show this help message');

package/cli/build.js

@@ -23,12 +23,17 @@ module.exports = function build(args) {
 
   var config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
 
-  template.build(distDir, targetDir, config);
+  var exported = template.build(distDir, targetDir, config);
 
   var brandName = (config.brand && config.brand.displayName) || 'Brand';
-  console.log('    built   index.html   (' + brandName + ' title + fonts baked in)');
+  console.log('    built   index.html   (' + brandName + ' title + fonts + embedded brand data)');
   console.log('    built   styles.css   (:root variables generated)');
   console.log('    copied  engine.js');
+  if (exported && exported.written) {
+    exported.written.forEach(function (f) {
+      console.log('    wrote   ' + f + '   (agent-native export)');
+    });
+  }
   console.log('');
   console.log('  Ready to deploy. Serve ' + path.relative(process.cwd(), targetDir) + '/ as static files.');
   console.log('');

package/cli/export.js

@@ -0,0 +1,64 @@
+var fs = require('fs');
+var path = require('path');
+var exporter = require('../lib/export');
+
+/**
+ * brandkit export [dir] [--format json|dtcg|md|all] [--out <dir>]
+ *
+ * Emit agent-native views of a brand from its config.json:
+ *   brand.json   — normalized, semantic brand (roles, usage, contrast, assets)
+ *   tokens.json  — W3C Design Tokens (DTCG) format
+ *   brand.md     — an LLM brief ("how to be on-brand"), a.k.a. llms.txt
+ */
+module.exports = function exportCmd(args) {
+  args = args || [];
+  var positional = [];
+  var format = 'all';
+  var outDir = null;
+
+  for (var i = 0; i < args.length; i++) {
+    var a = args[i];
+    if (a === '--format' && args[i + 1]) { format = args[++i]; }
+    else if (a.indexOf('--format=') === 0) { format = a.slice('--format='.length); }
+    else if (a === '--out' && args[i + 1]) { outDir = args[++i]; }
+    else if (a.indexOf('--out=') === 0) { outDir = a.slice('--out='.length); }
+    else if (a.charAt(0) !== '-') { positional.push(a); }
+  }
+
+  var targetDir = path.resolve(positional[0] || '.');
+  var configPath = path.join(targetDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    console.error('');
+    console.error('  No config.json found in ' + targetDir);
+    console.error('  Run: brandkit init ' + path.relative(process.cwd(), targetDir));
+    console.error('');
+    process.exit(1);
+  }
+
+  var config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    console.error('');
+    console.error('  Could not parse ' + path.relative(process.cwd(), configPath) + ': ' + e.message);
+    console.error('');
+    process.exit(1);
+  }
+
+  var dest = outDir ? path.resolve(outDir) : targetDir;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+
+  var result = exporter.writeExports(config, dest, format.split(','));
+
+  console.log('');
+  console.log('  brandkit export');
+  console.log('');
+  if (!result.written.length) {
+    console.log('  Nothing written — unknown --format "' + format + '" (use json|dtcg|md|all).');
+  } else {
+    result.written.forEach(function (f) {
+      console.log('    wrote   ' + path.join(path.relative(process.cwd(), dest) || '.', f));
+    });
+  }
+  console.log('');
+};

package/config.schema.json

@@ -0,0 +1,254 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/The-Stack-Lab/brandkit/config.schema.json",
+  "title": "brandkit config",
+  "description": "Configuration for a brandkit brand guide. The single source of truth — drives the rendered guide and the agent-native exports (brand.json, tokens.json, brand.md).",
+  "type": "object",
+  "required": ["brand", "fonts", "theme"],
+  "additionalProperties": true,
+  "definitions": {
+    "font": {
+      "type": "object",
+      "required": ["family"],
+      "properties": {
+        "family": { "type": "string", "minLength": 1, "description": "Font family name (matches the Google Fonts family)." },
+        "fallback": { "type": "string", "minLength": 1, "description": "Optional web-available stand-in for brands whose official typeface isn't on the web. When set, the rendered CSS font stack becomes 'family', 'fallback', sans-serif everywhere the font renders; labels still show 'family' alone." },
+        "googleImport": { "type": "string", "description": "Google Fonts css2 query segment, e.g. 'Inter:wght@300;400;700'." },
+        "description": { "type": "string" }
+      }
+    },
+    "colorItem": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "hex": { "type": "string", "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" },
+        "oklch": { "type": "string" },
+        "cssVar": { "type": "string" },
+        "role": { "type": "string" },
+        "light": { "type": "boolean", "description": "Hint that the swatch needs a border on light backgrounds." }
+      }
+    },
+    "colorGroup": {
+      "type": "object",
+      "properties": {
+        "label": { "type": "string" },
+        "items": { "type": "array", "items": { "$ref": "#/definitions/colorItem" } }
+      }
+    }
+  },
+  "properties": {
+    "brand": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "description": "Short brand/slug name; shown as the header wordmark when no headerLogo is set." },
+        "displayName": { "type": "string" },
+        "tagline": { "type": "string" },
+        "description": { "type": "string" },
+        "url": { "type": "string" },
+        "byline": { "type": "string" },
+        "version": { "type": "string", "description": "The brand guide's own revision (shown in the banner/footer) — not the brandkit package version." },
+        "date": { "type": "string" },
+        "guideLabel": { "type": "string", "description": "Renames the 'Web Style Guide' label in the header and footer." },
+        "headerLogo": { "type": "string", "description": "Path to a logo image shown in the header instead of the text wordmark (use a light/reversed logo)." },
+        "sidebarLogo": { "type": "string", "description": "Path to a logo image shown at the top of the left menu instead of the brand name (use a dark logo)." }
+      }
+    },
+    "fonts": {
+      "type": "object",
+      "properties": {
+        "display": { "$ref": "#/definitions/font" },
+        "body": { "$ref": "#/definitions/font" }
+      }
+    },
+    "theme": {
+      "type": "object",
+      "description": "CSS custom property map. Keys are token names (e.g. '--accent'). The engine only needs to OVERRIDE the baseline defaults shipped in styles.css.",
+      "additionalProperties": { "type": "string" },
+      "properties": {
+        "--accent": { "type": "string", "description": "Accent fill color (buttons, active states)." },
+        "--accent-foreground": { "type": "string", "description": "Text/icon color ON the accent fill (must meet contrast against --accent)." },
+        "--accent-text": { "type": "string", "description": "Accent used AS text/links on a light surface (must meet AA)." },
+        "--primary": { "type": "string", "description": "Primary action fill (primary buttons / CTAs). Defaults to --accent; override to separate the primary action from the accent (e.g. a black CTA with an orange accent)." },
+        "--primary-foreground": { "type": "string", "description": "Text/icon color ON the primary fill (must meet contrast against --primary). Defaults to --accent-foreground." },
+        "--header-bg": { "type": "string", "description": "Header/hero background behind the wordmark or logo. Defaults to --gradient-brand; override (e.g. a flat dark color) for a hero that shouldn't carry the accent." }
+      }
+    },
+    "nav": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "group": { "type": "string" },
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": { "label": { "type": "string" }, "id": { "type": "string" } }
+            }
+          }
+        }
+      }
+    },
+    "colors": {
+      "type": "object",
+      "properties": {
+        "brand": { "$ref": "#/definitions/colorGroup" },
+        "neutrals": { "$ref": "#/definitions/colorGroup" },
+        "semantic": { "$ref": "#/definitions/colorGroup" }
+      }
+    },
+    "gradients": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "css": { "type": "string" },
+          "description": { "type": "string" },
+          "stops": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "color": { "type": "string" },
+                "position": { "type": "string" },
+                "name": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "gradientUsage": {
+      "type": "object",
+      "properties": {
+        "do": { "type": "array", "items": { "type": "string" } },
+        "dont": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "sections": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "hierarchy": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "class": { "type": "string" },
+          "label": { "type": "string" },
+          "colorVar": { "type": "string" },
+          "colorName": { "type": "string" },
+          "hex": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "logos": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "variants"],
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "variants": {
+            "type": "object",
+            "description": "Map of format → file path, e.g. { \"svg\": \"logos/mark.svg\" }.",
+            "additionalProperties": { "type": "string" }
+          },
+          "background": { "type": "string", "enum": ["light", "dark", "gradient"] }
+        }
+      }
+    },
+    "logoSizes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "label": { "type": "string" },
+          "width": { "type": ["integer", "null"] }
+        }
+      }
+    },
+    "typography": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "font": { "type": "string", "enum": ["display", "body"] },
+          "size": { "type": "string" },
+          "weight": { "type": ["integer", "string"] },
+          "tracking": { "type": "string" },
+          "leading": { "type": "string" },
+          "sample": { "type": "string" },
+          "uppercase": { "type": "boolean" }
+        }
+      }
+    },
+    "voice": {
+      "type": "object",
+      "properties": {
+        "description": { "type": "string" },
+        "do": { "type": "array", "items": { "type": "string" } },
+        "dont": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "accessibility": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "fg": { "type": "string" },
+          "bg": { "type": "string" },
+          "fgName": { "type": "string" },
+          "bgName": { "type": "string" },
+          "ratio": { "type": "string" },
+          "rating": { "type": "string", "enum": ["AAA", "AA", "AA Large", "Fail"] },
+          "border": { "type": "boolean" },
+          "largeText": { "type": "boolean" }
+        }
+      }
+    },
+    "cssVariables": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "section": { "type": "string" },
+          "vars": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "prop": { "type": "string" },
+                "value": { "type": "string" },
+                "comment": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "spacing": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "px": { "type": "number" },
+          "token": { "type": "string" }
+        }
+      }
+    },
+    "components": {
+      "type": "object",
+      "properties": {
+        "buttons": { "type": "array" },
+        "cards": { "type": "array" },
+        "stats": { "type": "array" }
+      }
+    }
+  }
+}

package/dist/engine.js

@@ -21,6 +21,23 @@
         .replace(/>/g, '>').replace(/"/g, '"');
     }
 
+    /* ==============================================================
+       Font stack helper — weaves in an optional `fallback` web stand-in
+       for brands whose official typeface isn't web-available:
+         'Family', 'Fallback', sans-serif
+       No fallback → 'Family', sans-serif (backward-compatible).
+       ============================================================== */
+    function fontStack(f) {
+      if (!f || !f.family) return 'sans-serif';
+      // Strip control chars (a raw newline ends a CSS string) then escape
+      // backslash + single-quote, so a config value can't break out of the
+      // quoted CSS string and inject rules into the injected :root block.
+      function q(s) { return String(s).replace(/[\u0000-\u001F\u007F]/g, '').replace(/[\\']/g, '\\$&'); }
+      var stack = "'" + q(f.family) + "'";
+      if (f.fallback) stack += ", '" + q(f.fallback) + "'";
+      return stack + ', sans-serif';
+    }
+
     /* ==============================================================
        BOOTSTRAP — inject fonts + CSS variables before any rendering
        ============================================================== */
@@ -47,8 +64,8 @@
         }
         // Add font variables from config
         if (cfg.fonts) {
-          if (cfg.fonts.display) vars.push("  --font-display: '" + cfg.fonts.display.family + "', sans-serif;");
-          if (cfg.fonts.body) vars.push("  --font-body: '" + cfg.fonts.body.family + "', sans-serif;");
+          if (cfg.fonts.display) vars.push('  --font-display: ' + fontStack(cfg.fonts.display) + ';');
+          if (cfg.fonts.body) vars.push('  --font-body: ' + fontStack(cfg.fonts.body) + ';');
         }
         var style = document.createElement('style');
         style.setAttribute('data-brandkit-theme', '');
@@ -734,7 +751,8 @@
       if (!testerFont || !testerInput) return;
 
       testerFont.addEventListener('change', function () {
-        testerInput.style.fontFamily = "'" + testerFont.value + "', sans-serif";
+        // The option value is already a complete font stack (incl. fallback).
+        testerInput.style.fontFamily = testerFont.value;
       });
     }
 
@@ -790,21 +808,26 @@
       var testerFont = document.getElementById('type-tester-font');
       var testerInput = document.getElementById('type-tester-input');
       if (testerFont && cfg.fonts) {
-        // De-duplicate families so a brand using one typeface for both
+        // De-duplicate by family so a brand using one typeface for both
         // display and body shows a single option, not the same one twice.
-        var famList = [];
-        if (cfg.fonts.display && cfg.fonts.display.family) famList.push(cfg.fonts.display.family);
-        if (cfg.fonts.body && cfg.fonts.body.family) famList.push(cfg.fonts.body.family);
-        var seenFam = {};
-        var uniqueFams = [];
-        famList.forEach(function (f) {
-          if (!seenFam[f]) { seenFam[f] = true; uniqueFams.push(f); }
+        // The option value carries the full font stack (incl. any fallback)
+        // so the tester renders in the web stand-in when one is configured;
+        // the label stays the clean family name.
+        var fontList = [];
+        if (cfg.fonts.display && cfg.fonts.display.family) fontList.push(cfg.fonts.display);
+        if (cfg.fonts.body && cfg.fonts.body.family) fontList.push(cfg.fonts.body);
+        // null-proto map so a family literally named "__proto__"/"toString"
+        // isn't mistaken for already-seen via an inherited Object property.
+        var seenFam = Object.create(null);
+        var uniqueFonts = [];
+        fontList.forEach(function (f) {
+          if (!seenFam[f.family]) { seenFam[f.family] = true; uniqueFonts.push(f); }
         });
-        testerFont.innerHTML = uniqueFams.map(function (f) {
-          return '<option value="' + esc(f) + '">' + esc(f) + '</option>';
+        testerFont.innerHTML = uniqueFonts.map(function (f) {
+          return '<option value="' + esc(fontStack(f)) + '">' + esc(f.family) + '</option>';
         }).join('');
-        if (testerInput && uniqueFams.length) {
-          testerInput.style.fontFamily = "'" + uniqueFams[0] + "', sans-serif";
+        if (testerInput && uniqueFonts.length) {
+          testerInput.style.fontFamily = fontStack(uniqueFonts[0]);
         }
       }
 

package/dist/styles.css

@@ -41,10 +41,22 @@
   --accent-foreground: #FFFFFF;
   --accent-text: var(--accent);
 
+  /* Primary action — the fill for primary buttons / CTAs.
+       Defaults to the accent, so single-accent brands are unchanged. Brands that
+       separate the primary action from the accent (e.g. a black CTA with an orange
+       accent) override --primary / --primary-foreground. */
+  --primary: var(--accent);
+  --primary-foreground: var(--accent-foreground);
+
   /* Gradients */
   --gradient-brand: linear-gradient(135deg, #4338CA 0%, #6366F1 50%, #EC4899 100%);
   --gradient-brand-subtle: linear-gradient(135deg, rgba(99, 102, 241, 0.06) 0%, rgba(236, 72, 153, 0.06) 100%);
 
+  /* Header background — the hero block behind the wordmark/logo.
+       Defaults to the brand gradient; override (e.g. a flat dark color) for a
+       hero that shouldn't carry the accent. */
+  --header-bg: var(--gradient-brand);
+
   /* Semantic */
   --success: #10B981;
   --success-rgb: 16, 185, 129;
@@ -231,7 +243,7 @@ body {
 
 /* ── Header ── */
 .header {
-  background: var(--gradient-brand);
+  background: var(--header-bg);
   border-radius: 24px;
   padding: 64px 56px;
   margin-bottom: 72px;
@@ -863,7 +875,7 @@ body {
 .btn-sm { height: 32px; padding: 0 16px; font-size: 13px; border-radius: 9999px; }
 .btn-md { height: 40px; padding: 0 24px; font-size: 14px; border-radius: 9999px; }
 .btn-lg { height: 48px; padding: 0 28px; font-size: 16px; border-radius: 9999px; }
-.btn-primary { background: var(--accent); color: var(--accent-foreground); }
+.btn-primary { background: var(--primary); color: var(--primary-foreground); }
 .btn-primary:hover { filter: brightness(0.9); }
 .btn-secondary { background: var(--mist); color: var(--ink); }
 .btn-secondary:hover { filter: brightness(0.96); }

package/integrations/vite.js

@@ -52,7 +52,6 @@ module.exports = function brandkitVite(options) {
     },
 
     closeBundle: function () {
-      // Copy brand directory to build output
       var srcDir = path.resolve(brandDir);
       if (!fs.existsSync(srcDir)) return;
 
@@ -61,7 +60,27 @@ module.exports = function brandkitVite(options) {
         fs.mkdirSync(outDir, { recursive: true });
       }
 
+      // Copy assets (config.json, logos, anything in brand/) to the output.
       copyDir(srcDir, outDir);
+
+      // Then produce a real production build into the output: theme baked into
+      // styles.css, engine.js copied, and the agent-native exports written +
+      // embedded in index.html. This makes the deployed /brand carry brand.json,
+      // tokens.json, brand.md and the inline <script id="brandkit-brand"> — so an
+      // agent pointed at the URL gets structured brand data without a manual
+      // `brandkit build` step. Falls back to the raw copy if config is missing.
+      var configPath = path.join(srcDir, 'config.json');
+      if (fs.existsSync(configPath)) {
+        try {
+          var config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+          var template = require('../lib/template');
+          var resolve = require('../lib/resolve');
+          template.build(resolve.getDistPath(), outDir, config);
+        } catch (e) {
+          // Leave the raw copy in place; don't fail the host build, but say why.
+          console.warn('[brandkit] agent-export step skipped: ' + e.message);
+        }
+      }
     }
   };
 };

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/template.js

@@ -1,5 +1,23 @@
 var fs = require('fs');
 var path = require('path');
+var exporter = require('./export');
+
+/**
+ * Build a CSS font stack from a font def. When the brand's official typeface
+ * isn't web-available, an optional `fallback` web stand-in is woven in:
+ *   'Family', 'Fallback', sans-serif
+ * No fallback → the original 'Family', sans-serif (backward-compatible).
+ */
+function fontStack(font) {
+  if (!font || !font.family) return 'sans-serif';
+  // Strip control chars (a raw newline ends a CSS string) then escape
+  // backslash + single-quote, so a config value can't break out of the quoted
+  // CSS string and inject rules into the generated :root block.
+  function q(s) { return String(s).replace(/[\u0000-\u001F\u007F]/g, '').replace(/[\\']/g, '\\$&'); }
+  var stack = "'" + q(font.family) + "'";
+  if (font.fallback) stack += ", '" + q(font.fallback) + "'";
+  return stack + ', sans-serif';
+}
 
 /**
  * Generate a :root CSS block from config.theme + config.fonts.
@@ -14,10 +32,10 @@ function generateRootCSS(config) {
   }
   if (config.fonts) {
     if (config.fonts.display) {
-      lines.push("  --font-display: '" + config.fonts.display.family + "', sans-serif;");
+      lines.push('  --font-display: ' + fontStack(config.fonts.display) + ';');
     }
     if (config.fonts.body) {
-      lines.push("  --font-body: '" + config.fonts.body.family + "', sans-serif;");
+      lines.push('  --font-body: ' + fontStack(config.fonts.body) + ';');
     }
   }
   lines.push('}');
@@ -54,15 +72,19 @@ function build(distDir, targetDir, config) {
   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(
@@ -70,6 +92,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
@@ -77,6 +109,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.2",
+  "version": "1.2.2",
   "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",