@stacklist-app/brandkit 1.2.1 → 1.2.3

package/README.md

@@ -43,6 +43,8 @@ A brandkit guide isn't just a page for people — `build` (and the standalone `e
 
 `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.
 
+And for a person who wants to hand the guide to their own agent, the sidebar shows a **"Using an AI agent?"** callout with a one-click copy-paste prompt — it carries absolute URLs to `brand.json` / `tokens.json` / `brand.md` and tells the agent to read those instead of scraping the page. Hide it with `brand.agentCallout: false`.
+
 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
@@ -76,7 +78,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

package/config.schema.json

@@ -11,7 +11,8 @@
       "type": "object",
       "required": ["family"],
       "properties": {
-        "family": { "type": "string", "description": "Font family name (matches the Google Fonts family)." },
+        "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" }
       }
@@ -50,7 +51,8 @@
         "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)." }
+        "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)." },
+        "agentCallout": { "type": "boolean", "description": "Show the 'Using an AI agent?' callout under the sidebar nav — a copy-paste prompt pointing an agent at the brand.json / tokens.json / brand.md exports. Defaults to true; set false to hide it." }
       }
     },
     "fonts": {

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', '');
@@ -106,6 +123,57 @@
       }).join('');
     }
 
+    /* ==============================================================
+       2b. Render agent callout — a paste-ready prompt that points an AI
+       agent at the machine-readable exports (brand.json / tokens.json /
+       brand.md) so it reads structured brand data instead of scraping the
+       rendered page. Opt out with brand.agentCallout === false.
+       ============================================================== */
+    function renderAgentCallout() {
+      var box = document.getElementById('agent-callout');
+      if (!box) return;
+      if (cfg.brand && cfg.brand.agentCallout === false) return;
+
+      // Resolve export URLs relative to this page exactly as a link would, so
+      // the pasted prompt carries absolute URLs the agent can fetch directly.
+      // Clear any userinfo so basic-auth creds in the page URL don't leak into
+      // the copied prompt (a relative path already drops the page query/hash).
+      function exportUrl(file) {
+        var u = new URL(file, location.href);
+        u.username = ''; u.password = '';
+        return u.href;
+      }
+      var brandUrl, tokensUrl, mdUrl;
+      try {
+        brandUrl = exportUrl('brand.json');
+        tokensUrl = exportUrl('tokens.json');
+        mdUrl = exportUrl('brand.md');
+      } catch (_) {
+        brandUrl = 'brand.json'; tokensUrl = 'tokens.json'; mdUrl = 'brand.md';
+      }
+      // Strip control chars / newlines and collapse whitespace so a hostile
+      // brand name can't smuggle instructions into the paste-ready agent prompt.
+      var name = ((cfg.brand && (cfg.brand.displayName || cfg.brand.name)) || 'this brand')
+        .replace(/[\u0000-\u001F\u007F\u00AD\u200B-\u200F\u202A-\u202E\u2060-\u2069\uFEFF]/g, ' ').replace(/\s+/g, ' ').trim() || 'this brand';
+      var prompt =
+        'This page is a brandkit brand guide for ' + name + '. It publishes ' +
+        'machine-readable brand data — read these instead of scraping the page:\n\n' +
+        '- ' + brandUrl + ' — full structured brand: colors (roles + contrast), typography, voice, logos, spacing\n' +
+        '- ' + tokensUrl + ' — W3C design tokens (DTCG $type/$value), for code and design tooling\n' +
+        '- ' + mdUrl + ' — brand brief: how to stay on-brand\n\n' +
+        'Fetch them, then apply ' + name + "'s colors, type, and voice to what you're building.";
+
+      box.innerHTML =
+        '<div class="sidebar-agent-title">Using an AI agent?</div>' +
+        '<p class="sidebar-agent-desc">Paste this so it reads the brand data, not the page.</p>' +
+        '<button type="button" class="sidebar-agent-btn" id="agent-callout-btn">Copy agent prompt</button>';
+      // Set the payload via property (not an HTML attribute) so no font/brand
+      // value needs escaping and newlines survive intact.
+      var btn = box.querySelector('#agent-callout-btn');
+      if (btn) btn.dataset.copy = prompt;
+      box.hidden = false;
+    }
+
     /* ==============================================================
        3. Render colors
        ============================================================== */
@@ -669,6 +737,13 @@
           copyText(codeLine.dataset.copy);
           return;
         }
+
+        // Agent callout prompt
+        var agentBtn = e.target.closest('#agent-callout-btn');
+        if (agentBtn) {
+          copyText(agentBtn.dataset.copy);
+          return;
+        }
       });
     }
 
@@ -734,7 +809,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 +866,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]);
         }
       }
 
@@ -863,6 +944,7 @@
     bootstrap();
     renderShell();
     renderNav();
+    renderAgentCallout();
     renderSectionIntros();
     renderColors();
     renderGradients();

package/dist/index.html

@@ -14,6 +14,7 @@
   <nav class="sidebar">
     <div class="sidebar-brand">brandkit</div>
     <ul class="sidebar-nav" id="nav"></ul>
+    <div class="sidebar-agent" id="agent-callout" hidden></div>
   </nav>
 
   <!-- Main Content -->

package/dist/styles.css

@@ -129,11 +129,49 @@ body {
 .sidebar-nav a:hover { color: var(--ink); background: var(--cloud); }
 .sidebar-nav a.active { color: var(--accent-text); border-left-color: var(--accent-text); background: rgba(var(--accent-rgb), 0.04); font-weight: 500; }
 
+/* Agent callout — paste-ready prompt that points an AI agent at the exports */
+.sidebar-agent {
+  margin: 28px 16px 8px;
+  padding: 14px;
+  border: 1px solid var(--mist);
+  border-radius: 12px;
+  background: rgba(var(--accent-rgb), 0.04);
+}
+.sidebar-agent-title {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--ink);
+  margin-bottom: 4px;
+}
+.sidebar-agent-desc {
+  font-size: 11px;
+  line-height: 1.4;
+  color: var(--slate);
+  margin: 0 0 10px;
+}
+.sidebar-agent-btn {
+  display: block;
+  width: 100%;
+  padding: 7px 10px;
+  font-size: 12px;
+  font-weight: 500;
+  font-family: inherit;
+  color: var(--primary-foreground);
+  background: var(--primary);
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: filter 150ms ease;
+}
+.sidebar-agent-btn:hover { filter: brightness(0.9); }
+.sidebar-agent-btn:active { transform: translateY(1px); }
+.sidebar-agent-btn:focus-visible { outline: 2px solid var(--accent-text); outline-offset: 2px; }
+
 /* ── Sidebar Grouped Navigation ── */
 .nav-group {
   padding: 20px 24px 6px;
   font-family: var(--font-body), sans-serif;
-  font-size: 10px;
+  font-size: 12px;
   font-weight: 700;
   letter-spacing: 0.10em;
   text-transform: uppercase;

package/lib/template.js

@@ -2,6 +2,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.
  */
@@ -15,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('}');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacklist-app/brandkit",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Config-driven brand guide that bolts onto any website. Zero dependencies.",
   "main": "lib/resolve.js",
   "bin": {