@stacklist-app/brandkit 1.1.1

package/README.md

@@ -0,0 +1,95 @@
+# @stacklist-app/brandkit
+
+A config-driven brand guide that bolts onto any website. One `config.json` drives the entire guide — colors, typography, logos, voice, components, spacing, accessibility. Zero runtime dependencies.
+
+Swap the config and assets to generate a brand guide for any project. An optional `generate` command scrapes an existing codebase (Tailwind config, CSS variables, logo files) to bootstrap the config automatically.
+
+## Install
+
+```bash
+npm install github:The-Stack-Lab/brandkit
+# or pin to a tag
+npm install github:The-Stack-Lab/brandkit#v1.1.1
+```
+
+Requires Node.js 18+.
+
+## Quickstart
+
+```bash
+npx brandkit init brand        # scaffold brand/config.json + starter assets
+npx brandkit generate brand    # optional: auto-extract tokens from your codebase
+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.
+
+## CLI
+
+| Command | Description |
+|---|---|
+| `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 |
+
+## Framework integrations
+
+Serve the brand guide at `/brand` in your existing dev server and bundle it on build.
+
+**Vite**
+```js
+// vite.config.js
+import brandkit from '@stacklist-app/brandkit/integrations/vite'
+
+export default {
+  plugins: [brandkit()],
+}
+```
+
+**Astro**
+```js
+// astro.config.mjs
+import brandkit from '@stacklist-app/brandkit/integrations/astro'
+
+export default {
+  integrations: [brandkit()],
+}
+```
+
+**Next.js / plain HTML**: run `brandkit build brand` and serve the resulting directory as a static route.
+
+## Config
+
+`config.json` is the single source of truth. Top-level keys:
+
+- `brand` — name, tagline, description, version
+- `fonts` — display + body with Google Fonts import
+- `theme` — CSS variable map (colors, gradients, font vars)
+- `nav` — sidebar structure
+- `colors` — brand / neutrals / semantic palettes
+- `gradients`, `gradientUsage` — gradient definitions + do/don't lists
+- `logos`, `logoSizes` — logo variants + download sizes
+- `typography` — type scale and specimens
+- `hierarchy` — text hierarchy demo
+- `voice` — tone description + do/don't examples
+- `components` — buttons, cards, stats
+- `spacing` — spacing scale tokens
+- `accessibility` — contrast ratio grid
+- `cssVariables` — variable reference
+
+See `example/config.json` for a complete reference implementation (Freeway PHX).
+
+## How theming works
+
+`dist/styles.css` uses CSS custom properties (`var(--purple)`, `var(--font-display)`, etc.) with no `:root` block.
+
+- **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`.
+
+Swap the config, and every color, gradient, and font token updates everywhere.
+
+## License
+
+MIT © The Stack Lab

package/bin/brandkit.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+var args = process.argv.slice(2);
+var command = args[0] || 'help';
+
+switch (command) {
+  case 'init':
+    require('../cli/init')(args.slice(1));
+    break;
+  case 'dev':
+    require('../cli/dev')(args.slice(1));
+    break;
+  case 'build':
+    require('../cli/build')(args.slice(1));
+    break;
+  case 'generate':
+    require('../cli/generate')(args.slice(1));
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    printHelp();
+    break;
+  case '--version':
+  case '-v':
+    var pkg = require('../package.json');
+    console.log(pkg.version);
+    break;
+  default:
+    console.error('Unknown command: ' + command);
+    printHelp();
+    process.exit(1);
+}
+
+function printHelp() {
+  console.log('');
+  console.log('  brandkit — config-driven brand guide');
+  console.log('');
+  console.log('  Usage:');
+  console.log('    brandkit init [dir]        Scaffold a new brand guide');
+  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('');
+  console.log('  Options:');
+  console.log('    --help, -h     Show this help message');
+  console.log('    --version, -v  Show version number');
+  console.log('');
+}

package/cli/build.js

@@ -0,0 +1,35 @@
+var fs = require('fs');
+var path = require('path');
+var resolve = require('../lib/resolve');
+var template = require('../lib/template');
+
+module.exports = function build(args) {
+  var targetDir = path.resolve(args[0] || '.');
+  var distDir = resolve.getDistPath();
+
+  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);
+  }
+
+  console.log('');
+  console.log('  brandkit build');
+  console.log('');
+  console.log('  Reading ' + path.relative(process.cwd(), configPath) + '...');
+
+  var config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+
+  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   styles.css   (:root variables generated)');
+  console.log('    copied  engine.js');
+  console.log('');
+  console.log('  Ready to deploy. Serve ' + path.relative(process.cwd(), targetDir) + '/ as static files.');
+  console.log('');
+};

package/cli/dev.js

@@ -0,0 +1,129 @@
+var http = require('http');
+var fs = require('fs');
+var path = require('path');
+var url = require('url');
+
+var MIME_TYPES = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+};
+
+module.exports = function dev(args) {
+  var dir = path.resolve(args[0] || '.');
+  var port = 4800;
+
+  // Parse --port flag
+  for (var i = 0; i < args.length; i++) {
+    if (args[i] === '--port' && args[i + 1]) {
+      port = parseInt(args[i + 1], 10) || 4800;
+    }
+  }
+
+  // Validate directory has a config.json
+  var configPath = path.join(dir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    console.error('');
+    console.error('  No config.json found in ' + dir);
+    console.error('  Run: brandkit init ' + path.relative(process.cwd(), dir));
+    console.error('');
+    process.exit(1);
+  }
+
+  // SSE clients for live reload
+  var sseClients = [];
+
+  var server = http.createServer(function (req, res) {
+    var parsed = url.parse(req.url);
+    var pathname = parsed.pathname;
+
+    // SSE endpoint for live reload
+    if (pathname === '/__brandkit_reload') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'Access-Control-Allow-Origin': '*'
+      });
+      res.write('data: connected\n\n');
+      sseClients.push(res);
+      req.on('close', function () {
+        var idx = sseClients.indexOf(res);
+        if (idx !== -1) sseClients.splice(idx, 1);
+      });
+      return;
+    }
+
+    // Serve static files
+    if (pathname === '/') pathname = '/index.html';
+    var filePath = path.join(dir, pathname);
+
+    // Security: prevent path traversal
+    if (!filePath.startsWith(dir)) {
+      res.writeHead(403);
+      res.end('Forbidden');
+      return;
+    }
+
+    fs.readFile(filePath, function (err, data) {
+      if (err) {
+        res.writeHead(404);
+        res.end('Not found: ' + pathname);
+        return;
+      }
+      var ext = path.extname(filePath).toLowerCase();
+      var mime = MIME_TYPES[ext] || 'application/octet-stream';
+      res.writeHead(200, { 'Content-Type': mime });
+
+      // Inject live reload script into HTML
+      if (ext === '.html') {
+        var html = data.toString();
+        var reloadScript =
+          '<script>' +
+          '(function(){' +
+          'var es=new EventSource("/__brandkit_reload");' +
+          'es.onmessage=function(e){if(e.data==="reload")location.reload();};' +
+          'es.onerror=function(){es.close();setTimeout(function(){location.reload();},2000);};' +
+          '})();' +
+          '</script>';
+        html = html.replace('</body>', reloadScript + '</body>');
+        res.end(html);
+      } else {
+        res.end(data);
+      }
+    });
+  });
+
+  server.listen(port, function () {
+    console.log('');
+    console.log('  brandkit dev');
+    console.log('');
+    console.log('  Serving brand guide at http://localhost:' + port + '/');
+    console.log('  Watching ' + path.relative(process.cwd(), configPath) + ' for changes...');
+    console.log('');
+  });
+
+  // Watch config.json for changes
+  var debounce = null;
+  fs.watch(dir, { recursive: true }, function (eventType, filename) {
+    if (!filename) return;
+    // Only reload on relevant file changes
+    var ext = path.extname(filename).toLowerCase();
+    if (['.json', '.html', '.css', '.js'].indexOf(ext) === -1) return;
+
+    clearTimeout(debounce);
+    debounce = setTimeout(function () {
+      sseClients.forEach(function (client) {
+        client.write('data: reload\n\n');
+      });
+    }, 100);
+  });
+};

package/cli/generate.js

@@ -0,0 +1,272 @@
+var fs = require('fs');
+var path = require('path');
+var extractTailwind = require('../lib/extract-tailwind');
+var extractCSS = require('../lib/extract-css');
+var extractLogos = require('../lib/extract-logos');
+var helpers = require('../lib/generate-helpers');
+var schema = require('../lib/config-schema');
+
+module.exports = function generate(args) {
+  var brandDir = path.resolve(args[0] || 'brand');
+  var projectDir = process.cwd();
+
+  console.log('');
+  console.log('  brandkit generate');
+  console.log('');
+  console.log('  Scanning project...');
+
+  var extracted = {};
+  var summary = [];
+
+  // Extract from Tailwind config
+  var tw = extractTailwind.extract(projectDir);
+  if (tw.colors) {
+    summary.push('    Found Tailwind config \u2014 extracting colors, fonts, spacing');
+    extracted.tailwindColors = tw.colors;
+  }
+  if (tw.fonts) extracted.tailwindFonts = tw.fonts;
+  if (tw.spacing) extracted.tailwindSpacing = tw.spacing;
+
+  // Extract CSS custom properties
+  var cssVars = extractCSS.extract(projectDir);
+  if (cssVars) {
+    summary.push('    Found CSS custom properties \u2014 extracting theme variables');
+    extracted.cssVars = cssVars;
+  }
+
+  // Extract logos
+  var logos = extractLogos.extract(projectDir);
+  if (logos && logos.length) {
+    var logoNames = logos.map(function (l) { return path.basename(Object.values(l.variants)[0]); });
+    summary.push('    Found ' + logoNames.join(', ') + ' \u2014 adding to logos');
+    extracted.logos = logos;
+  }
+
+  if (!summary.length) {
+    summary.push('    No Tailwind config, CSS variables, or logo assets detected');
+    summary.push('    Creating starter config with example entries');
+  }
+
+  // Load existing config or create starter
+  var configPath = path.join(brandDir, 'config.json');
+  var existingConfig = null;
+  if (fs.existsSync(configPath)) {
+    try {
+      existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      console.log('    Found existing config.json \u2014 preserving manual fields');
+    } catch (_) {
+      console.log('    Existing config.json is invalid \u2014 creating fresh');
+    }
+  }
+
+  var baseConfig = existingConfig || schema.starterConfig();
+
+  // Build extracted config fields
+  var newFields = {};
+
+  // Colors from Tailwind (with auto-computed oklch and light flag)
+  if (extracted.tailwindColors) {
+    newFields.colors = buildColors(extracted.tailwindColors);
+  }
+
+  // Theme from CSS variables
+  if (extracted.cssVars) {
+    newFields.theme = extractCSS.mapToTheme(extracted.cssVars);
+  }
+
+  // Fonts from Tailwind
+  if (extracted.tailwindFonts) {
+    var fonts = {};
+    if (extracted.tailwindFonts.display) {
+      fonts.display = {
+        family: extracted.tailwindFonts.display.family,
+        googleImport: extracted.tailwindFonts.display.family + ':wght@300;400;500;600;700',
+        description: '__TODO: Describe the display font.'
+      };
+    }
+    if (extracted.tailwindFonts.body) {
+      fonts.body = {
+        family: extracted.tailwindFonts.body.family,
+        googleImport: extracted.tailwindFonts.body.family + ':wght@300;400;500;600;700',
+        description: '__TODO: Describe the body font.'
+      };
+    }
+    if (Object.keys(fonts).length) newFields.fonts = fonts;
+  }
+
+  // Spacing from Tailwind
+  if (extracted.tailwindSpacing) {
+    newFields.spacing = extracted.tailwindSpacing;
+  }
+
+  // Logos (make paths relative to brand dir)
+  if (extracted.logos) {
+    newFields.logos = extracted.logos.map(function (logo) {
+      var variants = {};
+      var keys = Object.keys(logo.variants);
+      for (var i = 0; i < keys.length; i++) {
+        variants[keys[i]] = path.relative(brandDir, path.join(projectDir, logo.variants[keys[i]]));
+      }
+      return {
+        name: logo.name,
+        description: logo.description,
+        variants: variants,
+        background: logo.background
+      };
+    });
+  }
+
+  // --- Auto-compute derived fields ---
+  // Only overwrite if existing field is empty or all-scaffold (__TODO)
+
+  // Determine the theme to derive from (extracted or existing)
+  var theme = newFields.theme || baseConfig.theme;
+
+  // Auto-generate gradients from theme
+  if (theme && isEmptyOrScaffold(baseConfig.gradients)) {
+    var gradients = helpers.buildGradientsFromTheme(theme);
+    if (gradients.length) {
+      newFields.gradients = gradients;
+      summary.push('    Gradients: ' + gradients.length + ' auto-generated from theme');
+    }
+  }
+
+  // Auto-generate hierarchy from theme
+  if (theme && isEmptyOrScaffold(baseConfig.hierarchy)) {
+    newFields.hierarchy = helpers.buildHierarchyFromTheme(theme);
+    summary.push('    Hierarchy: 4 levels auto-generated from theme colors');
+  }
+
+  // Auto-generate accessibility pairs from all extracted colors
+  if (isEmptyOrScaffold(baseConfig.accessibility)) {
+    var allColors = [];
+    var colorSource = newFields.colors || baseConfig.colors;
+    if (colorSource) {
+      ['brand', 'neutrals', 'semantic'].forEach(function (key) {
+        var group = colorSource[key];
+        if (group) {
+          var items = group.items || group;
+          if (Array.isArray(items)) {
+            allColors = allColors.concat(items);
+          }
+        }
+      });
+    }
+    if (allColors.length) {
+      var a11y = helpers.generateA11yPairs(allColors);
+      if (a11y.length) {
+        newFields.accessibility = a11y;
+        summary.push('    Accessibility: ' + a11y.length + ' contrast pairs auto-computed');
+      }
+    }
+  }
+
+  // Auto-generate cssVariables from theme
+  if (theme && isEmptyOrScaffold(baseConfig.cssVariables)) {
+    var cssVarSections = helpers.buildCssVariablesFromTheme(theme);
+    if (cssVarSections.length) {
+      newFields.cssVariables = cssVarSections;
+      summary.push('    CSS Variables: ' + cssVarSections.length + ' sections auto-generated');
+    }
+  }
+
+  // Auto-scaffold typography if empty or missing
+  if (isEmptyOrScaffold(baseConfig.typography)) {
+    newFields.typography = helpers.scaffoldTypography();
+    summary.push('    Typography: standard type scale scaffolded');
+  }
+
+  // Print all summary messages (including derived fields computed above)
+  summary.forEach(function (line) { console.log(line); });
+
+  // Merge
+  var finalConfig = schema.mergeConfigs(baseConfig, newFields);
+
+  // Ensure brand dir exists
+  if (!fs.existsSync(brandDir)) {
+    fs.mkdirSync(brandDir, { recursive: true });
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(finalConfig, null, 2) + '\n');
+
+  // Count what needs TODO attention
+  var todoCount = countTodos(finalConfig);
+
+  console.log('');
+  console.log('  Generated ' + path.relative(process.cwd(), configPath));
+  if (extracted.tailwindColors) console.log('    Colors: ' + extracted.tailwindColors.length + ' extracted (with oklch)');
+  if (extracted.tailwindFonts) console.log('    Fonts: ' + Object.keys(extracted.tailwindFonts).length + ' detected');
+  if (extracted.tailwindSpacing) console.log('    Spacing: ' + extracted.tailwindSpacing.length + ' tokens');
+  if (extracted.logos) console.log('    Logos: ' + extracted.logos.length + ' files found');
+  if (todoCount > 0) console.log('    TODO: ' + todoCount + ' fields need manual or AI attention');
+  console.log('');
+};
+
+function buildColors(colorList) {
+  var brand = [];
+  var neutrals = [];
+  var semantic = [];
+
+  var semanticNames = ['success', 'warning', 'error', 'danger', 'info'];
+  var neutralNames = ['gray', 'grey', 'slate', 'zinc', 'neutral', 'stone', 'black', 'white'];
+
+  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.name) continue;
+    var lowerName = c.name.toLowerCase();
+
+    var isSemantic = false;
+    var isNeutral = false;
+    for (var j = 0; j < semanticNames.length; j++) {
+      if (lowerName.indexOf(semanticNames[j]) !== -1) { isSemantic = true; break; }
+    }
+    if (!isSemantic) {
+      for (var k = 0; k < neutralNames.length; k++) {
+        if (lowerName.indexOf(neutralNames[k]) !== -1) { isNeutral = true; break; }
+      }
+    }
+
+    // Auto-compute oklch and light flag
+    var entry = {
+      name: c.name,
+      hex: c.hex,
+      oklch: helpers.hexToOklch(c.hex),
+      cssVar: '--color-' + c.name.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+      role: c.role || '',
+      light: helpers.isLightColor(c.hex)
+    };
+
+    if (isSemantic) semantic.push(entry);
+    else if (isNeutral) neutrals.push(entry);
+    else brand.push(entry);
+  }
+
+  return {
+    brand: { label: 'Brand', items: brand },
+    neutrals: { label: 'Neutrals', items: neutrals },
+    semantic: { label: 'Semantic', items: semantic }
+  };
+}
+
+function countTodos(obj) {
+  var count = 0;
+  var str = JSON.stringify(obj);
+  var regex = /__TODO/g;
+  while (regex.exec(str) !== null) count++;
+  return count;
+}
+
+/**
+ * Check if a field is empty or only contains scaffold/placeholder data.
+ * Returns true if the field should be overwritten by auto-generation.
+ */
+function isEmptyOrScaffold(value) {
+  if (!value) return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  // Check if all entries are scaffold (contain __TODO)
+  var str = JSON.stringify(value);
+  if (str.indexOf('__TODO') !== -1) return true;
+  return false;
+}

package/cli/init.js

@@ -0,0 +1,62 @@
+var fs = require('fs');
+var path = require('path');
+var resolve = require('../lib/resolve');
+var schema = require('../lib/config-schema');
+
+module.exports = function init(args) {
+  var targetDir = path.resolve(args[0] || 'brand');
+  var distDir = resolve.getDistPath();
+
+  console.log('');
+  console.log('  brandkit');
+  console.log('');
+  console.log('  Scaffolding into ' + path.relative(process.cwd(), targetDir) + '/...');
+
+  // Create target directory
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Create logos directory
+  var logosDir = path.join(targetDir, 'logos');
+  if (!fs.existsSync(logosDir)) {
+    fs.mkdirSync(logosDir, { recursive: true });
+  }
+
+  // Check for --update flag: only update engine files, preserve config
+  var isUpdate = args.indexOf('--update') !== -1;
+
+  // Copy engine files from dist/
+  var files = ['engine.js', 'styles.css', 'index.html'];
+  for (var i = 0; i < files.length; i++) {
+    var src = path.join(distDir, files[i]);
+    var dest = path.join(targetDir, files[i]);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+      console.log('    copied  ' + files[i]);
+    }
+  }
+
+  // Create starter config.json (skip if exists and not forcing)
+  var configPath = path.join(targetDir, 'config.json');
+  if (!fs.existsSync(configPath) && !isUpdate) {
+    var starter = schema.starterConfig();
+    fs.writeFileSync(configPath, JSON.stringify(starter, null, 2) + '\n');
+    console.log('    created config.json');
+  } else if (isUpdate) {
+    console.log('    kept    config.json (--update)');
+  } else {
+    console.log('    kept    config.json (already exists)');
+  }
+
+  console.log('');
+  if (isUpdate) {
+    console.log('  Updated engine files. Config and logos preserved.');
+  } else {
+    console.log('  Next steps:');
+    console.log('    1. Edit ' + path.relative(process.cwd(), configPath) + ' with your brand data');
+    console.log('    2. Add logo files to ' + path.relative(process.cwd(), logosDir) + '/');
+    console.log('    3. Run: npx brandkit dev ' + path.relative(process.cwd(), targetDir));
+  }
+  console.log('');
+};