@stacklist-app/brandkit 1.1.1 → 1.2.1

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.1
+npm install @stacklist-app/brandkit
 ```
 
 Requires Node.js 18+.
@@ -23,7 +21,7 @@ npx brandkit dev brand         # preview at http://localhost:4800 (live reload)
 npx brandkit build brand       # bake into static files for production
 ```
 
-The `brand` directory name is your choice — pass any path.
+`init` scaffolds a complete, ready-to-run demo brand (the self-titled "Brandkit" guide), so `dev` shows a polished guide immediately — then you swap in your own colors, fonts, copy, and logos. The `brand` directory name is your choice — pass any path.
 
 ## CLI
 
@@ -32,7 +30,20 @@ The `brand` directory name is your choice — pass any path.
 | `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
 
@@ -64,7 +75,7 @@ export default {
 
 `config.json` is the single source of truth. Top-level keys:
 
-- `brand` — name, tagline, description, version
+- `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
 - `theme` — CSS variable map (colors, gradients, font vars)
 - `nav` — sidebar structure
@@ -79,14 +90,29 @@ export default {
 - `accessibility` — contrast ratio grid
 - `cssVariables` — variable reference
 
-See `example/config.json` for a complete reference implementation (Freeway PHX).
+See `example/config.json` for the complete default demo brand — the same config `init` scaffolds.
+
+## Theming
+
+`dist/styles.css` ships a baseline `:root` block with sensible defaults for **every** token it consumes, so a minimal or partial config never renders broken. Your config only needs to *override* what it wants to change.
+
+The accent uses a fill/text split (the same convention as Material and shadcn/ui):
+
+- `--accent` — the fill color (buttons, active states)
+- `--accent-foreground` — text/icons **on** the fill (must meet contrast against `--accent`)
+- `--accent-text` — the accent used **as** text or links on a light surface
+
+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:
 
-## How theming works
+- `--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`)
 
-`dist/styles.css` uses CSS custom properties (`var(--purple)`, `var(--font-display)`, etc.) with no `:root` block.
+The fallbacks mean single-accent brands need set none of these.
 
-- **Dev**: the engine reads `config.theme` and injects a `<style data-brandkit-theme>` tag at runtime.
-- **Build**: `brandkit build` prepends the generated `:root` block to `styles.css` and injects the Google Fonts `<link>` and page title into `index.html`.
+- **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`.
 
 Swap the config, and every color, gradient, and font token updates everywhere.
 

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/cli/generate.js

@@ -72,6 +72,7 @@ module.exports = function generate(args) {
   // Theme from CSS variables
   if (extracted.cssVars) {
     newFields.theme = extractCSS.mapToTheme(extracted.cssVars);
+    ensureThemeDefaults(newFields.theme);
   }
 
   // Fonts from Tailwind
@@ -202,6 +203,39 @@ module.exports = function generate(args) {
   console.log('');
 };
 
+// Fill in the companion tokens styles.css consumes but a host stylesheet
+// rarely defines: the "r, g, b" variants used by rgba() tints, and the
+// accent on-color pairing. A light fill (e.g. orange) gets a black
+// foreground so buttons stay legible; --accent-text defaults to the fill.
+function ensureThemeDefaults(theme) {
+  if (!theme) return;
+  var rgbPairs = {
+    '--accent': '--accent-rgb',
+    '--ink': '--ink-rgb',
+    '--error': '--error-rgb',
+    '--success': '--success-rgb'
+  };
+  Object.keys(rgbPairs).forEach(function (hexKey) {
+    var rgbKey = rgbPairs[hexKey];
+    var val = theme[hexKey];
+    if (val && !theme[rgbKey] && /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(val)) {
+      theme[rgbKey] = helpers.hexToRgbString(val);
+    }
+  });
+  if (theme['--accent'] && !theme['--accent-foreground'] && /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(theme['--accent'])) {
+    // Pick the on-fill color with the higher WCAG contrast (not a luminance
+    // threshold — a mid-tone fill like orange reads better with black text
+    // even though it isn't "light").
+    var lum = helpers.relativeLuminance(theme['--accent']);
+    var contrastWhite = 1.05 / (lum + 0.05);
+    var contrastBlack = (lum + 0.05) / 0.05;
+    theme['--accent-foreground'] = contrastBlack >= contrastWhite ? '#000000' : '#FFFFFF';
+  }
+  if (theme['--accent'] && !theme['--accent-text']) {
+    theme['--accent-text'] = theme['--accent'];
+  }
+}
+
 function buildColors(colorList) {
   var brand = [];
   var neutrals = [];
@@ -213,7 +247,7 @@ function buildColors(colorList) {
   for (var i = 0; i < colorList.length; i++) {
     var c = colorList[i];
     // Skip colors without valid hex (Tailwind function-based colors, etc.)
-    if (!c.hex || typeof c.hex !== 'string' || !/^#[0-9a-fA-F]{3,8}$/.test(c.hex)) continue;
+    if (!c.hex || typeof c.hex !== 'string' || !/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(c.hex)) continue;
     if (!c.name) continue;
     var lowerName = c.name.toLowerCase();
 

package/cli/init.js

@@ -37,6 +37,22 @@ module.exports = function init(args) {
     }
   }
 
+  // Copy the default showcase logos so the scaffold renders complete out of
+  // the box. Skipped on --update (preserve the user's assets) and skipped per
+  // file if the user already has one with that name.
+  var distLogosDir = path.join(distDir, 'logos');
+  if (!isUpdate && fs.existsSync(distLogosDir)) {
+    var logoFiles = fs.readdirSync(distLogosDir);
+    for (var l = 0; l < logoFiles.length; l++) {
+      var logoSrc = path.join(distLogosDir, logoFiles[l]);
+      var logoDest = path.join(logosDir, logoFiles[l]);
+      if (!fs.existsSync(logoDest)) {
+        fs.copyFileSync(logoSrc, logoDest);
+        console.log('    copied  logos/' + logoFiles[l]);
+      }
+    }
+  }
+
   // Create starter config.json (skip if exists and not forcing)
   var configPath = path.join(targetDir, 'config.json');
   if (!fs.existsSync(configPath) && !isUpdate) {

package/config.schema.json

@@ -0,0 +1,253 @@
+{
+  "$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", "description": "Font family name (matches the Google Fonts family)." },
+        "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

@@ -163,8 +163,18 @@
        4. Render gradients
        ============================================================== */
     function renderGradients() {
+      var gradientsSection = document.getElementById('gradients');
+      // No gradient configured → hide the whole section. The swatches are
+      // CSS-backed (var(--gradient-brand)), so leaving the scaffolding would
+      // render the default gradient under an empty "Gradient System" header.
+      if (!cfg.gradients || !cfg.gradients.length) {
+        if (gradientsSection) gradientsSection.style.display = 'none';
+        return;
+      }
+      if (gradientsSection) gradientsSection.style.display = '';
+
       var stopsContainer = document.getElementById('gradient-stops');
-      if (!stopsContainer || !cfg.gradients || !cfg.gradients.length) return;
+      if (!stopsContainer) return;
       var brand = cfg.gradients[0];
       if (brand && brand.stops && brand.stops.length) {
         stopsContainer.innerHTML = brand.stops.map(function (s) {
@@ -732,11 +742,20 @@
        18. Render shell (header, intro, footer, misc)
        ============================================================== */
     function renderShell() {
-      // Header
+      // Header — show brand.headerLogo image if set, else the brand name as text.
+      // brand.guideLabel renames the "Web Style Guide" label (header + footer).
+      var guideLabel = cfg.brand.guideLabel || 'Web Style Guide';
       var wordmark = document.getElementById('header-wordmark');
-      if (wordmark) wordmark.textContent = cfg.brand.name;
+      if (wordmark) {
+        if (cfg.brand.headerLogo) {
+          wordmark.innerHTML = '<img class="header-logo" src="' + esc(cfg.brand.headerLogo) +
+            '" alt="' + esc(cfg.brand.name || 'Logo') + '">';
+        } else {
+          wordmark.textContent = cfg.brand.name;
+        }
+      }
       var meta = document.getElementById('header-meta');
-      if (meta) meta.innerHTML = 'Web Style Guide v' + cfg.brand.version + '<br>' + cfg.brand.date;
+      if (meta) meta.innerHTML = esc(guideLabel) + ' v' + esc(cfg.brand.version) + '<br>' + esc(cfg.brand.date);
 
       // Intro
       var intro = document.getElementById('intro');
@@ -749,8 +768,8 @@
       // Footer
       var footer = document.getElementById('footer');
       if (footer) footer.innerHTML =
-        '<span>' + cfg.brand.url + ' \u00B7 ' + cfg.brand.byline + '</span>' +
-        '<span>Web Style Guide v' + cfg.brand.version + ' \u00B7 ' + cfg.brand.date + '</span>';
+        '<span>' + esc(cfg.brand.url) + ' \u00B7 ' + esc(cfg.brand.byline) + '</span>' +
+        '<span>' + esc(guideLabel) + ' v' + esc(cfg.brand.version) + ' \u00B7 ' + esc(cfg.brand.date) + '</span>';
 
       // Typography specimens — read descriptions from config
       var typeDisplayName = document.getElementById('type-display-name');
@@ -771,11 +790,21 @@
       var testerFont = document.getElementById('type-tester-font');
       var testerInput = document.getElementById('type-tester-input');
       if (testerFont && cfg.fonts) {
-        testerFont.innerHTML =
-          '<option value="' + cfg.fonts.display.family + '">' + cfg.fonts.display.family + '</option>' +
-          '<option value="' + cfg.fonts.body.family + '">' + cfg.fonts.body.family + '</option>';
-        if (testerInput) {
-          testerInput.style.fontFamily = "'" + cfg.fonts.display.family + "', sans-serif";
+        // De-duplicate families 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); }
+        });
+        testerFont.innerHTML = uniqueFams.map(function (f) {
+          return '<option value="' + esc(f) + '">' + esc(f) + '</option>';
+        }).join('');
+        if (testerInput && uniqueFams.length) {
+          testerInput.style.fontFamily = "'" + uniqueFams[0] + "', sans-serif";
         }
       }
 
@@ -816,9 +845,16 @@
           '</div>';
       }
 
-      // Sidebar brand name
+      // Sidebar brand — logo image if brand.sidebarLogo is set, else brand name
       var sidebarBrand = document.querySelector('.sidebar-brand');
-      if (sidebarBrand) sidebarBrand.textContent = 'brandkit';
+      if (sidebarBrand) {
+        if (cfg.brand.sidebarLogo) {
+          sidebarBrand.innerHTML = '<img class="sidebar-logo" src="' + esc(cfg.brand.sidebarLogo) +
+            '" alt="' + esc(cfg.brand.name || 'Logo') + '">';
+        } else {
+          sidebarBrand.textContent = cfg.brand.name || 'Brand';
+        }
+      }
     }
 
     /* ==============================================================

package/dist/logos/brandkit-mark-white.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96" role="img" aria-label="Brandkit mark, reversed">
+  <rect x="1.5" y="1.5" width="93" height="93" rx="20.5" fill="none" stroke="#FFFFFF" stroke-width="3"/>
+  <g fill="#FFFFFF">
+    <rect x="26" y="28" width="44" height="11" rx="5.5"/>
+    <rect x="26" y="43" width="44" height="11" rx="5.5" opacity="0.82"/>
+    <rect x="26" y="58" width="28" height="11" rx="5.5" opacity="0.64"/>
+  </g>
+</svg>

package/dist/logos/brandkit-mark.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96" role="img" aria-label="Brandkit mark">
+  <defs>
+    <linearGradient id="bk-grad" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4F46E5"/>
+      <stop offset="1" stop-color="#7C3AED"/>
+    </linearGradient>
+  </defs>
+  <rect width="96" height="96" rx="22" fill="url(#bk-grad)"/>
+  <g fill="#FFFFFF">
+    <rect x="26" y="28" width="44" height="11" rx="5.5"/>
+    <rect x="26" y="43" width="44" height="11" rx="5.5" opacity="0.82"/>
+    <rect x="26" y="58" width="28" height="11" rx="5.5" opacity="0.64"/>
+  </g>
+</svg>