@stacklist-app/brandkit 1.2.1 → 1.2.2

package/README.md

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

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" }
       }

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/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.2",
   "description": "Config-driven brand guide that bolts onto any website. Zero dependencies.",
   "main": "lib/resolve.js",
   "bin": {