@stacklist-app/brandkit 1.2.2 → 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

package/config.schema.json

@@ -51,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

@@ -123,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
        ============================================================== */
@@ -686,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;
+        }
       });
     }
 
@@ -886,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/package.json

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