brandrail 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@ Keep AI-generated UI on-brand. `brandrail` checks code and live pages against yo
 (Brand Kit), and writes your rules into the files AI coding tools read.
 
 ```bash
-npx brandrail init            # brandrail.config.json + AGENTS.md, CLAUDE.md, Cursor/Copilot/Windsurf/Gemini rules
+npx brandrail init            # brandrail.config.json, src/brandrail.tokens.css + AGENTS.md, CLAUDE.md, Cursor/Copilot/Windsurf/Gemini rules
 npx brandrail check           # violations + brand score for this repo
 npx brandrail scan <url>      # check a running page in a real browser
 ```
@@ -23,7 +23,7 @@ npx brandrail check --changed --upload    # only changed lines, results in the d
 | --- | --- |
 | `check [paths]` | `--format pretty\|json\|markdown\|github`, `--fail-below 80`, `--changed [base]`, `--upload` |
 | `scan <url>` | `--pages 3`, `--storage-state auth.json` (pages behind a login), `--wait 2000`, `--upload`. Needs `npm i -D playwright && npx playwright install chromium` |
-| `init` | `--from-api`, `--mcp`, `--no-rules`, `--force` |
+| `init` | `--from-api`, `--mcp`, `--tokens-css <file>`, `--no-rules`, `--force`. Writes the Brand Kit as CSS variables; import that file once at your app entry |
 | `import <tokens.json>` | DTCG, Tokens Studio or Figma variables JSON into the config. `--replace`, `--primitives` |
 | `rules` | List the rules |
 

package/dist/brandrail.mjs

@@ -175,10 +175,10 @@ function resolveConfig(config) {
     if (!l.type && !l.path.startsWith("color")) continue;
     const rgb = parseColor(l.value);
     if (!rgb) continue;
-    const cssVar = `--${l.path.replace(/\./g, "-")}`;
-    colors.push({ path: l.path, cssVar, hex: toHex(rgb), lab: rgbToLab(rgb), alpha: rgb.a });
+    const cssVar2 = `--${l.path.replace(/\./g, "-")}`;
+    colors.push({ path: l.path, cssVar: cssVar2, hex: toHex(rgb), lab: rgbToLab(rgb), alpha: rgb.a });
     const dark = typeof l.dark === "string" ? parseColor(l.dark) : null;
-    if (dark) colors.push({ path: l.path, cssVar, hex: toHex(dark), lab: rgbToLab(dark), alpha: dark.a, mode: "dark" });
+    if (dark) colors.push({ path: l.path, cssVar: cssVar2, hex: toHex(dark), lab: rgbToLab(dark), alpha: dark.a, mode: "dark" });
   }
   const spaceLeaves = all.filter((l) => /^(space|spacing)\./.test(l.path));
   const spacing = [0, 1, 2];
@@ -604,7 +604,7 @@ function makeIgnore(globs) {
 }
 
 // ../engine/src/check.ts
-var ENGINE_VERSION = "0.1.0";
+var ENGINE_VERSION = "0.2.0";
 var WEIGHT = { error: 4, warning: 1.5, info: 0.25 };
 function computeScore(counts, lines) {
   const penalty = counts.error * WEIGHT.error + counts.warning * WEIGHT.warning + counts.info * WEIGHT.info;
@@ -673,7 +673,7 @@ function check(files, configInput, opts = {}) {
 }
 
 // ../engine/src/report.ts
-var RENDERED_ONLY = { "text-contrast": "Low text contrast", "font-size-scale": "Off-scale font size" };
+var RENDERED_ONLY = { "text-contrast": "Low text contrast", "font-size-scale": "Off-scale font size", "page-rendered": "Blank page" };
 var title = (id) => RULES.find((r) => r.id === id)?.title ?? RENDERED_ONLY[id] ?? id;
 var ansi = (on) => {
   const w = (code) => (s) => on ? `\x1B[${code}m${s}\x1B[0m` : s;
@@ -784,129 +784,6 @@ var starterConfig = {
   ignore: []
 };
 
-// ../engine/src/instructions.ts
-var RULES_START = "<!-- brandrail:start -->";
-var RULES_END = "<!-- brandrail:end -->";
-function generateInstructions(config, opts = {}) {
-  const r = resolveConfig(config);
-  const lines = [];
-  lines.push(`# Design system rules${opts.org ? ` \u2014 ${opts.org}` : ""}`);
-  lines.push("");
-  lines.push(
-    `All UI in this repo must follow the Brand Kit${r.tokenVersion ? ` (v${r.tokenVersion})` : ""}. These rules are checked on every pull request by Brandrail.`
-  );
-  lines.push("");
-  if (r.components.length) {
-    lines.push("## Components");
-    lines.push("Always use these components. Never re-create them with raw HTML elements:");
-    for (const c of r.components) {
-      const tags = [...r.replaces].filter(([, v]) => v === c).map(([t]) => `<${t}>`);
-      lines.push(`- \`${c.name}\` from \`${c.importPath}\`${tags.length ? ` (instead of ${tags.join(", ")})` : ""}`);
-    }
-    lines.push("");
-  }
-  if (r.colors.length) {
-    lines.push("## Colours");
-    lines.push("Use CSS variables only. Never write hex, rgb() or hsl() values, and never use Tailwind palette classes like `bg-blue-500`.");
-    for (const c of r.colors) {
-      if (c.mode) continue;
-      const dark = r.colors.find((d) => d.mode === "dark" && d.path === c.path);
-      lines.push(`- \`var(${c.cssVar})\` \u2014 ${c.path} (${c.hex}${dark ? `, dark ${dark.hex}` : ""})`);
-    }
-    lines.push("");
-  }
-  lines.push("## Spacing, radius and type");
-  lines.push(`- Spacing (padding, margin, gap) must be one of: ${r.spacing.filter((s) => s > 2).map((s) => `${s}px`).join(", ")}.`);
-  lines.push(`- Corner radius must be one of: ${r.radii.filter((x) => x > 0 && x < 999).map((x) => `${x}px`).join(", ")} (or fully rounded).`);
-  if (r.fonts.length) lines.push(`- Fonts: use ${r.fontVars.map((v) => `\`var(${v})\``).join(" or ")}; never set another font-family.`);
-  lines.push("");
-  lines.push("## Before you finish");
-  lines.push("- If the Brandrail MCP server is connected, call `validate_snippet` on the UI you wrote and fix every violation.");
-  lines.push("- Otherwise run `npx brandrail check` and fix errors before committing.");
-  lines.push("");
-  lines.push("<details><summary>Checked rules</summary>");
-  lines.push("");
-  for (const rule of RULES) {
-    if (r.rules[rule.id] === "off") continue;
-    lines.push(`- **${rule.title}** (\`${rule.id}\`): ${rule.description}`);
-  }
-  lines.push("");
-  lines.push("</details>");
-  return lines.join("\n");
-}
-function upsertSection(existing, section) {
-  const block = `${RULES_START}
-${section}
-${RULES_END}`;
-  const start = existing.indexOf(RULES_START);
-  const end = existing.indexOf(RULES_END);
-  if (start !== -1 && end > start) return existing.slice(0, start) + block + existing.slice(end + RULES_END.length);
-  return existing.trim() ? `${existing.trimEnd()}
-
-${block}
-` : `${block}
-`;
-}
-
-// ../engine/src/mcp-config.ts
-var json = (o) => `${JSON.stringify(o, null, 2)}
-`;
-function mcpClientConfigs(url) {
-  return [
-    {
-      id: "claude-code",
-      name: "Claude Code",
-      file: ".mcp.json",
-      projectFile: true,
-      content: json({ mcpServers: { brandrail: { type: "http", url, headers: { Authorization: "Bearer ${BRANDRAIL_KEY}" } } } }),
-      command: `claude mcp add --transport http brandrail ${url} --header "Authorization: Bearer $BRANDRAIL_KEY"`
-    },
-    {
-      id: "codex",
-      name: "Codex",
-      file: "~/.codex/config.toml",
-      projectFile: false,
-      content: `[mcp_servers.brandrail]
-url = "${url}"
-bearer_token_env_var = "BRANDRAIL_KEY"
-`,
-      command: `codex mcp add brandrail --url ${url} --bearer-token-env-var BRANDRAIL_KEY`
-    },
-    {
-      id: "cursor",
-      name: "Cursor",
-      file: ".cursor/mcp.json",
-      projectFile: true,
-      content: json({ mcpServers: { brandrail: { url, headers: { Authorization: "Bearer ${env:BRANDRAIL_KEY}" } } } })
-    },
-    {
-      id: "vscode",
-      name: "GitHub Copilot (VS Code)",
-      file: ".vscode/mcp.json",
-      projectFile: true,
-      content: json({
-        inputs: [{ type: "promptString", id: "brandrail-key", description: "Brandrail API key", password: true }],
-        servers: { brandrail: { type: "http", url, headers: { Authorization: "Bearer ${input:brandrail-key}" } } }
-      })
-    },
-    {
-      id: "windsurf",
-      name: "Windsurf",
-      file: "~/.codeium/windsurf/mcp_config.json",
-      projectFile: false,
-      content: json({ mcpServers: { brandrail: { serverUrl: url, headers: { Authorization: "Bearer ${env:BRANDRAIL_KEY}" } } } })
-    }
-  ];
-}
-var RULE_FILES = [
-  { file: "AGENTS.md", readBy: "Codex, Jules, Amp, Cursor and other agents" },
-  { file: "CLAUDE.md", readBy: "Claude Code" },
-  { file: ".cursor/rules/brandrail.mdc", readBy: "Cursor" },
-  { file: ".github/copilot-instructions.md", readBy: "GitHub Copilot" },
-  { file: ".windsurf/rules/brandrail.md", readBy: "Windsurf" },
-  { file: "GEMINI.md", readBy: "Gemini CLI" }
-];
-
 // ../engine/src/tokens.ts
 var EXT = "dev.brandrail";
 function slug(s) {
@@ -1374,6 +1251,139 @@ function mergeTokens(base, incoming) {
   return buildDtcg([...m.values()]);
 }
 
+// ../engine/src/instructions.ts
+var RULES_START = "<!-- brandrail:start -->";
+var RULES_END = "<!-- brandrail:end -->";
+function generateInstructions(config, opts = {}) {
+  const r = resolveConfig(config);
+  const lines = [];
+  lines.push(`# Design system rules${opts.org ? ` \u2014 ${opts.org}` : ""}`);
+  lines.push("");
+  lines.push(
+    `All UI in this repo must follow the Brand Kit${r.tokenVersion ? ` (v${r.tokenVersion})` : ""}. These rules are checked on every pull request by Brandrail.`
+  );
+  lines.push("");
+  if (opts.tokensCss) {
+    lines.push("## Setup");
+    lines.push(`- \`${opts.tokensCss}\` defines every CSS variable below (light and dark). Import it once at the app entry, before other styles. Don't edit it: it's generated from the Brand Kit.`);
+    lines.push("");
+  }
+  if (r.components.length) {
+    lines.push("## Components");
+    lines.push("Always use these components. Never re-create them with raw HTML elements:");
+    for (const c of r.components) {
+      const tags = [...r.replaces].filter(([, v]) => v === c).map(([t]) => `<${t}>`);
+      lines.push(`- \`${c.name}\` from \`${c.importPath}\`${tags.length ? ` (instead of ${tags.join(", ")})` : ""}`);
+    }
+    lines.push("");
+  }
+  if (r.colors.length) {
+    lines.push("## Colours");
+    lines.push("Use CSS variables only. Never write hex, rgb() or hsl() values, and never use Tailwind palette classes like `bg-blue-500`.");
+    for (const c of r.colors) {
+      if (c.mode) continue;
+      const dark = r.colors.find((d) => d.mode === "dark" && d.path === c.path);
+      lines.push(`- \`var(${c.cssVar})\` \u2014 ${c.path} (${c.hex}${dark ? `, dark ${dark.hex}` : ""})`);
+    }
+    lines.push("");
+  }
+  lines.push("## Spacing, radius and type");
+  const named = (prefix) => flattenTokens(config.tokens).filter((t) => prefix.test(t.path)).map((t) => `\`var(--${t.path.replace(/\./g, "-")})\` ${t.value}`);
+  const spaceVars = named(/^(space|spacing)\./);
+  const radiusVars = named(/^radius\./);
+  const sizeVars = named(/^font\.size\./);
+  lines.push(`- Spacing (padding, margin, gap) must be one of: ${r.spacing.filter((s) => s > 2).map((s) => `${s}px`).join(", ")}.${spaceVars.length ? ` Prefer the variables: ${spaceVars.join(", ")}.` : ""}`);
+  lines.push(`- Corner radius must be one of: ${r.radii.filter((x) => x > 0 && x < 999).map((x) => `${x}px`).join(", ")} (or fully rounded).${radiusVars.length ? ` Variables: ${radiusVars.join(", ")}.` : ""}`);
+  if (sizeVars.length) lines.push(`- Font sizes come from the type scale: ${sizeVars.join(", ")}. Matching line heights are \`--font-line-height-*\`.`);
+  if (r.fonts.length) lines.push(`- Fonts: use ${r.fontVars.map((v) => `\`var(${v})\``).join(" or ")}; never set another font-family.`);
+  lines.push("");
+  lines.push("## Before you finish");
+  lines.push("- If the Brandrail MCP server is connected, call `validate_snippet` on the UI you wrote and fix every violation.");
+  lines.push("- Otherwise run `npx brandrail check` and fix errors before committing.");
+  lines.push("");
+  lines.push("<details><summary>Checked rules</summary>");
+  lines.push("");
+  for (const rule of RULES) {
+    if (r.rules[rule.id] === "off") continue;
+    lines.push(`- **${rule.title}** (\`${rule.id}\`): ${rule.description}`);
+  }
+  lines.push("");
+  lines.push("</details>");
+  return lines.join("\n");
+}
+function upsertSection(existing, section) {
+  const block = `${RULES_START}
+${section}
+${RULES_END}`;
+  const start = existing.indexOf(RULES_START);
+  const end = existing.indexOf(RULES_END);
+  if (start !== -1 && end > start) return existing.slice(0, start) + block + existing.slice(end + RULES_END.length);
+  return existing.trim() ? `${existing.trimEnd()}
+
+${block}
+` : `${block}
+`;
+}
+
+// ../engine/src/mcp-config.ts
+var json = (o) => `${JSON.stringify(o, null, 2)}
+`;
+function mcpClientConfigs(url) {
+  return [
+    {
+      id: "claude-code",
+      name: "Claude Code",
+      file: ".mcp.json",
+      projectFile: true,
+      content: json({ mcpServers: { brandrail: { type: "http", url, headers: { Authorization: "Bearer ${BRANDRAIL_KEY}" } } } }),
+      command: `claude mcp add --transport http brandrail ${url} --header "Authorization: Bearer $BRANDRAIL_KEY"`
+    },
+    {
+      id: "codex",
+      name: "Codex",
+      file: "~/.codex/config.toml",
+      projectFile: false,
+      content: `[mcp_servers.brandrail]
+url = "${url}"
+bearer_token_env_var = "BRANDRAIL_KEY"
+`,
+      command: `codex mcp add brandrail --url ${url} --bearer-token-env-var BRANDRAIL_KEY`
+    },
+    {
+      id: "cursor",
+      name: "Cursor",
+      file: ".cursor/mcp.json",
+      projectFile: true,
+      content: json({ mcpServers: { brandrail: { url, headers: { Authorization: "Bearer ${env:BRANDRAIL_KEY}" } } } })
+    },
+    {
+      id: "vscode",
+      name: "GitHub Copilot (VS Code)",
+      file: ".vscode/mcp.json",
+      projectFile: true,
+      content: json({
+        inputs: [{ type: "promptString", id: "brandrail-key", description: "Brandrail API key", password: true }],
+        servers: { brandrail: { type: "http", url, headers: { Authorization: "Bearer ${input:brandrail-key}" } } }
+      })
+    },
+    {
+      id: "windsurf",
+      name: "Windsurf",
+      file: "~/.codeium/windsurf/mcp_config.json",
+      projectFile: false,
+      content: json({ mcpServers: { brandrail: { serverUrl: url, headers: { Authorization: "Bearer ${env:BRANDRAIL_KEY}" } } } })
+    }
+  ];
+}
+var RULE_FILES = [
+  { file: "AGENTS.md", readBy: "Codex, Jules, Amp, Cursor and other agents" },
+  { file: "CLAUDE.md", readBy: "Claude Code" },
+  { file: ".cursor/rules/brandrail.mdc", readBy: "Cursor" },
+  { file: ".github/copilot-instructions.md", readBy: "GitHub Copilot" },
+  { file: ".windsurf/rules/brandrail.md", readBy: "Windsurf" },
+  { file: "GEMINI.md", readBy: "Gemini CLI" }
+];
+
 // ../engine/src/rendered.ts
 function collectRenderedNodes(maxNodes = 3e3) {
   const SKIP = /* @__PURE__ */ new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "IFRAME", "HEAD", "META", "LINK", "BR", "WBR", "SOURCE", "TRACK"]);
@@ -1587,6 +1597,17 @@ function checkRendered(pages, configInput, opts = {}) {
       }
     }
     const path = pagePath(page.url);
+    if (page.nodes.length < 5) {
+      violations.push({
+        ruleId: "page-rendered",
+        severity: "error",
+        file: path,
+        line: 0,
+        column: 0,
+        message: `The page rendered ${page.nodes.length} visible element${page.nodes.length === 1 ? "" : "s"}, so there was nothing to check`,
+        suggestion: "Open it in a browser: it may have crashed, need a login (use --storage-state), or need longer to load (--wait)."
+      });
+    }
     for (const g of groups.values()) {
       violations.push({
         ruleId: g.ruleId,
@@ -1631,6 +1652,21 @@ function pagePath(url) {
   }
 }
 
+// ../engine/src/tokens-css.ts
+var cssVar = (path) => `--${path.replace(/\./g, "-")}`;
+function generateTokensCss(tokens, opts = {}) {
+  const flat = flattenTokens(tokens);
+  const head = `/* Generated by Brandrail from the ${opts.org ? `${opts.org} ` : ""}Brand Kit${opts.version ? ` v${opts.version}` : ""}. Do not edit: run \`npx brandrail init --from-api\` to update. */`;
+  const light = flat.map((t) => `  ${cssVar(t.path)}: ${t.type === "fontFamily" ? t.value : t.value};`);
+  const dark = flat.filter((t) => t.dark).map((t) => `  ${cssVar(t.path)}: ${t.dark};`);
+  const out = [head, "", ":root {", ...light, "}"];
+  if (dark.length) {
+    out.push("", '[data-theme="dark"] {', ...dark, "}", "", "@media (prefers-color-scheme: dark) {", '  :root:not([data-theme="light"]) {', ...dark.map((l) => `  ${l}`), "  }", "}");
+  }
+  return `${out.join("\n")}
+`;
+}
+
 // src/api.ts
 var DEFAULT_API = "https://web-phi-nine-77.vercel.app";
 function apiBase() {
@@ -1834,6 +1870,7 @@ Options for init
   --no-rules             Don't write AGENTS.md (Codex), CLAUDE.md, Cursor, Copilot, Windsurf, Gemini rule files
   --mcp                  Also add the Brandrail MCP server to .mcp.json, .cursor/mcp.json, .vscode/mcp.json
                          and print the Codex / Windsurf config
+  --tokens-css <file>    Where to write the CSS variables (default src/brandrail.tokens.css); --no-tokens-css to skip
   --force                Overwrite an existing brandrail.config.json
 
 Options for scan
@@ -1863,7 +1900,7 @@ function parseArgs(argv) {
       const [k, v] = a.slice(2).split("=", 2);
       const next = rest[i + 1];
       if (v !== void 0) flags[k] = v;
-      else if (next !== void 0 && !next.startsWith("-") && ["config", "format", "fail-below", "changed", "pages", "storage-state", "wait", "width"].includes(k)) {
+      else if (next !== void 0 && !next.startsWith("-") && ["config", "format", "fail-below", "changed", "pages", "storage-state", "wait", "width", "tokens-css"].includes(k)) {
         flags[k] = next;
         i++;
       } else flags[k] = true;
@@ -1934,8 +1971,18 @@ Brand score ${report.score} is below ${threshold}.`);
   }
   return 0;
 }
-function writeRuleFiles(root, config, org) {
-  const md = generateInstructions(config, { org });
+function tokensCssPath(root, config, flags) {
+  if (typeof flags["tokens-css"] === "string") return flags["tokens-css"];
+  if (config.tokensCss) return config.tokensCss;
+  return existsSync3(join3(root, "src")) ? "src/brandrail.tokens.css" : "brandrail.tokens.css";
+}
+function writeTokensCss(root, rel, config, org) {
+  const abs = join3(root, rel);
+  mkdirSync(dirname2(abs), { recursive: true });
+  writeFileSync(abs, generateTokensCss(config.tokens, { version: config.tokenVersion, org }));
+}
+function writeRuleFiles(root, config, org, tokensCss) {
+  const md = generateInstructions(config, { org, tokensCss });
   const written = [];
   const write = (rel, content) => {
     const abs = join3(root, rel);
@@ -2018,12 +2065,22 @@ async function cmdInit(cwd, flags) {
   if (existsSync3(target) && !flags.force && !flags["from-api"]) {
     log(`${CONFIG_FILE} already exists (use --force to overwrite). Updating rule files from it.`);
     config = readConfig(target);
+    org ??= config.org;
   } else {
+    if (existsSync3(target)) {
+      const prev = readConfig(target);
+      config = { ...prev, ...config, rules: { ...prev.rules, ...config.rules }, ignore: prev.ignore ?? config.ignore, tokensCss: prev.tokensCss };
+    }
     writeFileSync(target, `${JSON.stringify(config, null, 2)}
 `);
     log(`\u2714 wrote ${CONFIG_FILE}${org ? ` from ${org}'s Brand Kit` : " (starter tokens \u2014 edit them or use --from-api)"}`);
   }
-  if (flags.rules !== false) for (const f of writeRuleFiles(cwd, config, org)) log(`\u2714 updated ${f}`);
+  const css = flags["tokens-css"] === false ? void 0 : tokensCssPath(cwd, config, flags);
+  if (css) {
+    writeTokensCss(cwd, css, config, org);
+    log(`\u2714 wrote ${css}  (the Brand Kit as CSS variables \u2014 import it once at your app entry)`);
+  }
+  if (flags.rules !== false) for (const f of writeRuleFiles(cwd, config, org, css)) log(`\u2714 updated ${f}`);
   if (flags.mcp) writeMcpConfigs(cwd);
   log("\nNext: npx brandrail check");
   return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brandrail",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Keep AI-generated UI on-brand: checks code and live pages against your design system, and wires your Brand Kit into Claude Code, Cursor, Copilot and Codex.",
   "keywords": [
     "design-system",
@@ -23,7 +23,7 @@
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
-    "brandrail": "./dist/brandrail.mjs"
+    "brandrail": "dist/brandrail.mjs"
   },
   "files": [
     "dist",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/brandrail.mjs --external:playwright --external:playwright-core --banner:js='#!/usr/bin/env node'",
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/brandrail.mjs --external:playwright --external:playwright-core --banner:js='#!/usr/bin/env node' && chmod +x dist/brandrail.mjs",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "pnpm run build"
   },