brandrail 0.1.0 → 0.3.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.3.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,10 +1251,150 @@ function mergeTokens(base, incoming) {
   return buildDtcg([...m.values()]);
 }
 
+// ../engine/src/instructions.ts
+var KIT_PACKAGE = "@brandrail/kit";
+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("");
+  const usesKit = r.components.some((c) => c.importPath === KIT_PACKAGE);
+  if (opts.tokensCss || usesKit) {
+    lines.push("## Setup");
+    if (opts.tokensCss) {
+      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.`);
+    }
+    if (usesKit) {
+      lines.push(`- Import \`${KIT_PACKAGE}/styles.css\` once at the app entry. Pass \`theme="brandrail"\` to kit components, and \`colorMode={ColorMode.DARK}\` (from \`${KIT_PACKAGE}\`) for dark mode. The Brand Kit styles them through the CSS variables; don't override their colours, spacing or fonts with your own CSS.`);
+    }
+    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"]);
-  const px2 = (v) => {
+  const px3 = (v) => {
     const n = parseFloat(v);
     return Number.isFinite(n) ? Math.round(n * 100) / 100 : 0;
   };
@@ -1425,8 +1442,8 @@ function collectRenderedNodes(maxNodes = 3e3) {
     const r = el.getBoundingClientRect();
     if (r.width < 1 || r.height < 1) continue;
     const text = Array.from(el.childNodes).filter((n) => n.nodeType === 3).map((n) => n.textContent ?? "").join(" ").replace(/\s+/g, " ").trim();
-    const borderW = Math.max(px2(cs.borderTopWidth), px2(cs.borderRightWidth), px2(cs.borderBottomWidth), px2(cs.borderLeftWidth));
-    const borderSide = px2(cs.borderTopWidth) > 0 ? cs.borderTopColor : px2(cs.borderBottomWidth) > 0 ? cs.borderBottomColor : px2(cs.borderLeftWidth) > 0 ? cs.borderLeftColor : cs.borderRightColor;
+    const borderW = Math.max(px3(cs.borderTopWidth), px3(cs.borderRightWidth), px3(cs.borderBottomWidth), px3(cs.borderLeftWidth));
+    const borderSide = px3(cs.borderTopWidth) > 0 ? cs.borderTopColor : px3(cs.borderBottomWidth) > 0 ? cs.borderBottomColor : px3(cs.borderLeftWidth) > 0 ? cs.borderLeftColor : cs.borderRightColor;
     nodes.push({
       selector: selectorOf(el),
       tag: el.tagName.toLowerCase(),
@@ -1436,12 +1453,12 @@ function collectRenderedNodes(maxNodes = 3e3) {
       borderColor: borderW > 0 && cs.borderTopStyle !== "none" ? borderSide : void 0,
       effectiveBackground: effectiveBg(el),
       fontFamily: cs.fontFamily,
-      fontSize: px2(cs.fontSize),
+      fontSize: px3(cs.fontSize),
       fontWeight: parseInt(cs.fontWeight, 10) || 400,
-      radius: Math.max(px2(cs.borderTopLeftRadius), px2(cs.borderTopRightRadius), px2(cs.borderBottomLeftRadius), px2(cs.borderBottomRightRadius)),
+      radius: Math.max(px3(cs.borderTopLeftRadius), px3(cs.borderTopRightRadius), px3(cs.borderBottomLeftRadius), px3(cs.borderBottomRightRadius)),
       minSide: Math.round(Math.min(r.width, r.height)),
-      padding: [px2(cs.paddingTop), px2(cs.paddingRight), px2(cs.paddingBottom), px2(cs.paddingLeft)],
-      gap: cs.display.includes("flex") || cs.display.includes("grid") ? [px2(cs.rowGap), px2(cs.columnGap)] : []
+      padding: [px3(cs.paddingTop), px3(cs.paddingRight), px3(cs.paddingBottom), px3(cs.paddingLeft)],
+      gap: cs.display.includes("flex") || cs.display.includes("grid") ? [px3(cs.rowGap), px3(cs.columnGap)] : []
     });
   }
   const links = Array.from(document.querySelectorAll("a[href]")).map((a) => a.href).filter((h) => {
@@ -1587,6 +1604,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 +1659,176 @@ 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")}
+`;
+}
+
+// ../engine/src/kit-bridge.ts
+var ROLE_PATTERNS = {
+  canvas: [/canvas\.default$/, /^color\.(bg|background)(\.default)?$/, /surface(\.1|\.default)?$/, /canvas$/, /(bg|background)/],
+  subtle: [/canvas\.subtle$/, /(bg|background)\.subtle$/, /surface\.2$/, /fill\.1$/, /subtle$/],
+  fg: [/fg\.default$/, /text\.(default|primary|dark-primary)$/, /^color\.(fg|text|foreground)$/, /fg|text/],
+  muted: [/fg\.muted$/, /text\.(muted|secondary|dark-secondary)$/, /muted|secondary/],
+  border: [/border\.default$/, /^color\.(base\.)?border$/, /border/],
+  primary: [/action\.primary$/, /^color\.(brand\.)?primary$/, /brand(-active)?$/, /primary/, /brand/],
+  accent: [/accent(\.default)?$/, /link/, /info/, /accent/],
+  danger: [/danger(\.default|-active)?$/, /error/, /danger/]
+};
+var ROLE_FALLBACK = {
+  canvas: ["#ffffff", "#0d1117"],
+  subtle: ["#f6f8fa", "#151b23"],
+  fg: ["#1f2328", "#f0f6fc"],
+  muted: ["#59636e", "#9198a1"],
+  border: ["#d1d9e0", "#3d444d"],
+  primary: ["#1f883d", "#238636"],
+  accent: ["#0969da", "#4493f8"],
+  danger: ["#cf222e", "#f85149"]
+};
+var HEX = /^#(?:[0-9a-f]{6}|[0-9a-f]{8})$/i;
+function pickColorRoles(colors, dark = false) {
+  const out = {};
+  for (const role of Object.keys(ROLE_PATTERNS)) {
+    let hit;
+    for (const re of ROLE_PATTERNS[role]) {
+      hit = colors.find((c) => re.test(c.path) && HEX.test(c.value));
+      if (hit) break;
+    }
+    const fb = ROLE_FALLBACK[role][dark ? 1 : 0];
+    if (!hit) out[role] = { value: fb };
+    else if (!dark) out[role] = { value: hit.value, path: hit.path };
+    else if (hit.dark) out[role] = { value: hit.dark, path: hit.path };
+    else out[role] = role === "primary" || role === "accent" || role === "danger" ? { value: hit.value, path: hit.path } : { value: fb, path: hit.path };
+  }
+  return out;
+}
+var KIT_SPACING = { 3: 4, 4: 6, 5: 8, 6: 10, 7: 12, 8: 16, 9: 20, 10: 24, 11: 28, 12: 32, 13: 36, 14: 40, 15: 44, 16: 48, 17: 56, 18: 64 };
+var KIT_RADIUS = { 1: 2, 2: 4, 3: 6, 4: 8, 5: 10, 6: 12, 7: 16, 8: 22, 9: 28 };
+var KIT_RADIUS_NAME = { 2: "sm", 3: "md", 6: "lg" };
+var KIT_TYPE = [
+  ["Xs", 12, 18],
+  ["Sm", 14, 22],
+  ["Base", 16, 24],
+  ["Md", 16, 24],
+  ["Lg", 18, 28],
+  ["Xl", 20, 32],
+  ["2xl", 24, 38],
+  ["3xl", 30, 42],
+  ["4xl", 36, 52]
+];
+var KIT_THEMES = ["brandrail", "themeA", "themeB"];
+var px2 = (v) => {
+  const m = v.trim().match(/^(-?\d*\.?\d+)(px|rem)?$/);
+  return m ? Number.parseFloat(m[1]) * (m[2] === "rem" ? 16 : 1) : null;
+};
+var nearest2 = (values, v) => values.reduce((best, x) => Math.abs(x - v) < Math.abs(best - v) ? x : best, values[0]);
+function luminance(hex) {
+  const n = hex.replace("#", "").slice(0, 6);
+  const [r, g, b] = [0, 2, 4].map((i) => parseInt(n.slice(i, i + 2), 16) / 255).map((c) => c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+var contrast = (a, b) => {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p);
+  return (x + 0.05) / (y + 0.05);
+};
+function onColor(bg, candidates) {
+  return candidates.filter((c) => HEX.test(c)).sort((a, b) => contrast(b, bg) - contrast(a, bg))[0] ?? "#ffffff";
+}
+function scalesOf(flat) {
+  const leaf = (p) => p.split(".").pop();
+  const spacing = flat.filter((t) => /^(space|spacing)\./.test(t.path) && !/\.unit$/.test(t.path)).map((t) => px2(t.value)).filter((v) => v !== null && v > 0 && v < 999);
+  const unit = flat.find((t) => /^space\.unit$/.test(t.path));
+  if (!spacing.length && unit && px2(unit.value)) for (const m of [0.5, 1, 1.5, 2, 3, 4, 5, 6]) spacing.push(px2(unit.value) * m);
+  const radii = flat.filter((t) => /^radius\./.test(t.path)).map((t) => ({ name: leaf(t.path), value: px2(t.value) ?? -1 })).filter((r) => r.value > 0 && r.value < 999);
+  const lineHeights = new Map(flat.filter((t) => /^font\.line-height\./.test(t.path)).map((t) => [leaf(t.path), px2(t.value) ?? void 0]));
+  const type = flat.filter((t) => /^font\.size\./.test(t.path)).map((t) => ({ name: leaf(t.path), size: px2(t.value) ?? 0, lineHeight: lineHeights.get(leaf(t.path)) })).filter((t) => t.size > 0);
+  const font = flat.find((t) => t.type === "fontFamily" || /^font\.family\./.test(t.path))?.value;
+  return { spacing, radii, type, font };
+}
+function scaleVars(s) {
+  const out = [];
+  if (s.spacing.length) for (const [n, v] of Object.entries(KIT_SPACING)) out.push(`--spacing${n}: ${nearest2(s.spacing, v)}px;`);
+  if (s.radii.length) {
+    const values = s.radii.map((r) => r.value);
+    for (const [n, v] of Object.entries(KIT_RADIUS)) {
+      const named = s.radii.find((r) => r.name === KIT_RADIUS_NAME[Number(n)]);
+      out.push(`--defaultRadius-rad${n}: ${named ? named.value : nearest2(values, v)}px;`);
+    }
+  }
+  if (s.type.length) {
+    const sizes = s.type.map((t) => t.size);
+    for (const [name, size, lh] of KIT_TYPE) {
+      const step = s.type.find((t) => t.name.toLowerCase() === name.toLowerCase()) ?? s.type.find((t) => t.size === nearest2(sizes, size));
+      out.push(`--fontA-fontSize${name}: ${step.size}px;`, `--fontA-lineHeight${name}: ${step.lineHeight ?? Math.round(step.size * lh / size)}px;`);
+    }
+    const base = s.type.find((t) => t.name === "base") ?? s.type.find((t) => t.size === nearest2(sizes, 14));
+    out.push(`--fontSizeBase: ${base.size}px;`);
+  }
+  return out;
+}
+function colorVars(colors, dark, font) {
+  const r = pickColorRoles(colors, dark);
+  const find = (re) => {
+    const c = colors.find((x) => re.test(x.path));
+    return c ? dark ? c.dark ?? c.value : c.value : void 0;
+  };
+  const success = find(/success/);
+  const warning = find(/warning|attention/);
+  const mix = (a, b, pct) => `color-mix(in srgb, ${a} ${pct}%, ${b})`;
+  const v = {
+    baseSurface1: r.canvas.value,
+    baseSurface2: r.subtle.value,
+    baseSurface3: mix(r.subtle.value, r.border.value, 70),
+    baseFill1: r.subtle.value,
+    baseFill2: mix(r.subtle.value, r.border.value, 50),
+    baseFill3: r.border.value,
+    baseFill4: mix(r.muted.value, r.border.value, 60),
+    baseFill5: r.muted.value,
+    baseBorder: r.border.value,
+    baseDisabled: mix(r.fg.value, "transparent", 28),
+    textDarkPrimary: r.fg.value,
+    textDarkSecondary: r.muted.value,
+    textDarkTertiary: mix(r.muted.value, r.canvas.value, 75),
+    textLightPrimary: onColor(r.primary.value, [pickColorRoles(colors, false).canvas.value, pickColorRoles(colors, false).fg.value]),
+    stateBrandActive: r.primary.value,
+    stateBrandHover: mix(r.primary.value, "black", 88),
+    stateBrandSelected: mix(r.primary.value, "black", 75),
+    stateDangerActive: r.danger.value,
+    stateDangerHover: mix(r.danger.value, "black", 85),
+    stateDangerSelected: mix(r.danger.value, r.canvas.value, 14),
+    stateHighlightActive: r.accent.value,
+    stateHighlightHover: mix(r.accent.value, r.canvas.value, 85),
+    stateHighlightSelected: mix(r.accent.value, r.canvas.value, 14)
+  };
+  if (success) Object.assign(v, { stateSuccessActive: success, stateSuccessHover: mix(success, "black", 88), stateSuccessSelected: mix(success, r.canvas.value, 14) });
+  if (warning) Object.assign(v, { stateWarningActive: warning, stateWarningHover: mix(warning, "black", 88), stateWarningSelected: mix(warning, r.canvas.value, 14) });
+  if (font) Object.assign(v, { "fontA-fontFamily": font, "fontB-fontFamily": font });
+  return Object.entries(v).map(([k, val]) => `--${k}: ${val};`);
+}
+function kitBridgeCss(tokens, opts = {}) {
+  const flat = flattenTokens(tokens);
+  const colors = flat.filter((t) => t.type === "color").map((t) => ({ path: t.path, value: t.value, dark: t.dark }));
+  const sc = scalesOf(flat);
+  const scales = scaleVars(sc);
+  const block = (sel2, lines) => lines.length ? `${sel2} {
+  ${lines.join("\n  ")}
+}` : "";
+  const themes = `:is(${KIT_THEMES.map((t) => `.${t}`).join(", ")})`;
+  const s = opts.scope;
+  const sel = s ? { scale: s, light: `${s}, ${s} .light`, dark: `${s} .dark, ${s}.dark` } : { scale: "html:root", light: `html:root, html:root ${themes}.light`, dark: `html:root ${themes}.dark` };
+  return [block(sel.scale, scales), block(sel.light, colorVars(colors, false, sc.font)), block(sel.dark, colorVars(colors, true, sc.font))].filter(Boolean).join("\n");
+}
+
 // src/api.ts
 var DEFAULT_API = "https://web-phi-nine-77.vercel.app";
 function apiBase() {
@@ -1834,6 +2032,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 +2062,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 +2133,25 @@ 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 });
+  let css = generateTokensCss(config.tokens, { version: config.tokenVersion, org });
+  const usesKit = (config.components ?? []).some((c) => c.importPath === "@brandrail/kit");
+  if (usesKit) css += `
+/* @brandrail/kit follows the Brand Kit: colours, font, spacing, radius and type scale. */
+${kitBridgeCss(config.tokens)}
+`;
+  writeFileSync(abs, css);
+  return usesKit;
+}
+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 +2234,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) {
+    const kit = writeTokensCss(cwd, css, config, org);
+    log(`\u2714 wrote ${css}  (the Brand Kit as CSS variables${kit ? ", and @brandrail/kit themed from it" : ""} \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.3.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",
@@ -35,16 +35,15 @@
   "publishConfig": {
     "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'",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "devDependencies": {
-    "@brandrail/engine": "workspace:*",
     "@types/node": "^22",
     "esbuild": "^0.28.2",
     "playwright-core": "1.63.0",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "@brandrail/engine": "0.1.0"
+  },
+  "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' && chmod +x dist/brandrail.mjs",
+    "typecheck": "tsc --noEmit"
   }
-}
+}