@goldencomm/baseline-tokens 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @goldencomm/baseline-tokens
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Core Baseline tokens (the Figma variable export, imported as DTCG), the lints, the Style Dictionary build to every
+platform output, and the system icon generator. Two ways to run it:
+
+**In this monorepo** (core): `npm run tokens:import` after a plugin export; `npm run tokens`, `npm run icons:build`.
+Outputs are committed for every platform and gated by `npm run check`.
+
+**In a client project** (one platform), via the CLI this package ships:
+```bash
+npx baseline-tokens build  --platform wordpress --out wp-content/themes/<theme> --client client.tokens.json
+npx baseline-tokens icons  --platform wordpress --out wp-content/themes/<theme> --client client.tokens.json
+npx baseline-tokens client from-defs --core-mode scheme-1=defs.json --core-mode scheme-2=defs2.json --out client.tokens.json
+```
+`--out` is the platform root: the Next/HTML folder that imports `tokens.css`, or the WordPress / Shopify theme
+folder. `client.tokens.json` holds value overrides keyed by core paths (`<collection-slug>.<mode-slug>` -> DTCG tree);
+a name core does not have is rejected (ADR-0001: a client theme is core with different values), except additions in
+Primitives folders that are never emitted (`colors/*` ramps, `spacing/*`), which a clone may add freely and the build
+ignores with a note (ADR-0027 §5). The lints `spacing-derived`, `radius-derived` and `tailwind-frozen` (against the
+installed `tailwindcss`) refuse hand-edited derived scales; regenerate them in the plugin's Scales panel. The Claude runbook
+that produces it from a client's Figma theme is `.claude/skills/baseline-client-tokens/SKILL.md`.
+
+**Code Connect for a client** (ADR-0021: the client's Figma library is a clone of the Core file, so node ids are
+Core's and only the file key differs):
+```bash
+npx baseline-tokens code-connect --platform wordpress --out wp-content/themes/<theme> --figma-file <clone key or URL> --parse
+npx baseline-tokens code-connect --platform wordpress --out wp-content/themes/<theme> --figma-file <clone key or URL> --publish   # CI only
+```
+Writes `<root>/figma.config.json` (label per platform, default include globs `components/ui/**` for Next,
+`blocks/**` + `code-connect/**` for WordPress, `blocks/**` for Shopify; override with `--include <glob>`), with
+`documentUrlSubstitutions` mapping Core's key to the clone's. `--parse` checks the templates, `--dry-run` validates
+against Figma (validation is on since ADR-0029), `--publish` publishes and refuses outside CI (`CI` unset) or without `FIGMA_ACCESS_TOKEN`. The Code
+Connect CLI runs from the platform root (its include globs resolve against the working directory), using the
+project's own `@figma/code-connect` when installed, otherwise `npx`. Re-run after every re-clone (new file key).
+
+`icons` needs the client's active Iconify set installed in the project (`npm i -D @iconify-json/<prefix>`); the
+command names it. The other sets are optional peers (this repo installs all five to keep the vocabulary complete).
+
+## Files
+| | |
+|---|---|
+| `import.mjs` | plugin export -> `src/figma/<collection>.<mode>.json` + `manifest.json` |
+| `lint.mjs` | shadcn set, naming/codeSyntax derivation (ADR-0012), component geometry rules (ADR-0017/0019) |
+| `build.mjs` | Style Dictionary -> registry CSS/cssVars, WordPress/HTML `tokens.css`, Shopify snippets + settings; copies `typeset.css` per platform (ADR-0028) |
+| `typeset.css` | Canonical Baseline fork of shadcn typeset (prose rhythm); platform copies are build outputs |
+| `icons.mjs` | vocabulary x active set -> React icon map, WordPress icon collection, Shopify snippet + block options, HTML sprite, Code Connect reverse maps |
+| `cli.mjs` | the per-platform orchestration above (scratch copy of core + client overrides -> generators -> copy out) |
+| `test/run.mjs` | fixture -> import -> lint -> build assertions, determinism, and a client-override CLI smoke |
+
+Env for tests/CLI: `TOKENS_SRC_DIR` (token source), `TOKENS_OUT_ROOT` (monorepo-shaped output root), `TOKENS_CLIENT=1`
+(client mode: resolved literals may replace core aliases).

package/build.mjs

@@ -0,0 +1,491 @@
+// Style Dictionary v5 build -> committed platform outputs. Runs from this folder only (chdir guard).
+// Theme modes become CSS blocks: first mode (Scheme 1) -> :root and [data-scheme="scheme-1"], others -> [data-scheme="<mode-slug>"].
+// Responsive modes -> @media (min-width) blocks. Primitives are inputs for alias resolution, never emitted.
+import StyleDictionary from "style-dictionary";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+process.chdir(here);
+const root = process.env.TOKENS_OUT_ROOT ?? join(here, "..");
+const src = process.env.TOKENS_SRC_DIR ?? join(here, "src", "figma");
+if (!existsSync(join(src, "manifest.json"))) { console.error("build: run import first"); process.exit(1); }
+const manifest = JSON.parse(readFileSync(join(src, "manifest.json"), "utf8"));
+const col = (name) => manifest.collections.find((c) => c.name === name);
+const modeFile = (c, m) => join(src, `${c.slug}.${m.slug}.json`);
+const primitives = col("Primitives");
+const theme = col("Color Schemes");
+if (!theme) { console.error("build: Color Schemes collection missing"); process.exit(1); }
+
+// Apply a Figma "color with opacity" to a resolved hex literal -> 8-digit hex. Correct for a PRIMITIVE, whose
+// value is the same in every mode. NOT correct for a component tint that aliases a scheme role -- see roleTint.
+const withOpacity = (hex, opacity) => {
+  if (!/^#[0-9a-f]{6}$/i.test(hex) || opacity === undefined) return hex;
+  return hex + Math.round(opacity * 255).toString(16).padStart(2, "0");
+};
+
+// A component tint is an alias to a Color Schemes role carrying an opacity (ADR-0017 §2). It must resolve at
+// RUNTIME, not here: baking it would resolve the role against whichever mode Style Dictionary loaded and
+// freeze the colour, which is exactly what the exception exists to avoid.
+//
+// color-mix() rather than relative colour syntax (`rgb(from var(--primary) r g b / 5%)`), and not for speed --
+// both resolve once during style computation, neither is on a per-frame path, and the difference is not
+// measurable. The reasons are support and consistency: color-mix() is Baseline widely available while relative
+// colour syntax is only newly available, and Tailwind v4 already emits exactly this form for every `/alpha`
+// utility in this codebase. Emitting the same string means swapping `bg-primary/5` for the variable is a
+// byte-identical resolved value, which is trivial to verify.
+const componentRefs = new Map(); // token path -> raw $value, before Style Dictionary resolves it
+const roleVars = new Map(); // color role path -> its custom property
+const indexRaw = (file, into, wantCodeSyntax) => {
+  const walk = (node, path) => {
+    for (const [k, v] of Object.entries(node)) {
+      if (!v || typeof v !== "object") continue;
+      if ("$value" in v) {
+        const cs = v.$extensions?.["com.goldencomm.figma"]?.codeSyntax;
+        if (!wantCodeSyntax) into.set([...path, k].join("."), v.$value);
+        else if (cs) into.set([...path, k].join("."), cs);
+      } else walk(v, [...path, k]);
+    }
+  };
+  walk(JSON.parse(readFileSync(file, "utf8")), []);
+};
+// A plain role alias (no opacity, or 100%; ADR-0017 §2 amended 2026-10-05) is emitted as var(--role), for the same
+// reason: it must follow the scheme at runtime.
+const roleTint = (t) => {
+  const ext = t.$extensions?.["com.goldencomm.figma"];
+  if (t.$type !== "color" || !ext || !/Components$/.test(ext.collection ?? "")) return null;
+  const raw = componentRefs.get(t.path.join("."));
+  const ref = typeof raw === "string" && raw.match(/^\{(.+)\}$/);
+  const cssVar = ref && roleVars.get(ref[1]);
+  const plain = typeof ext.opacity !== "number" || ext.opacity >= 1;
+  if (plain) return cssVar ? `var(${cssVar})` : null;
+  if (!cssVar) {
+    console.error(`build: ${t.path.join("/")} is a component tint but its alias does not resolve to an emitting colour role (ADR-0017 §2)`);
+    process.exit(1);
+  }
+  // 0.05 -> 5%, without floating-point noise
+  const pct = Math.round(ext.opacity * 10000) / 100;
+  return `color-mix(in oklab, var(${cssVar}) ${pct}%, transparent)`;
+};
+// fontFamily tokens hold one family name (a Figma FONT_FAMILY variable); the build quotes it when needed and
+// appends the generic stack for its role (font/sans -> sans-serif ...). Loading the face is a project concern.
+const GENERIC = { sans: "ui-sans-serif, system-ui, sans-serif", serif: "ui-serif, Georgia, serif", mono: "ui-monospace, monospace" };
+const fmtFamily = (t) => {
+  const fam = String(t.$value);
+  const role = t.path.find((p) => GENERIC[p]) ?? (/mono/i.test(fam) ? "mono" : "sans");
+  return `${/[^\w-]/.test(fam) ? `"${fam}"` : fam}, ${GENERIC[role]}`;
+};
+const fmtValue = (t) => {
+  const v = t.$value;
+  const tint = roleTint(t);
+  if (tint) return tint;
+  if (t.$type === "fontFamily") return fmtFamily(t);
+  if (v && typeof v === "object" && "unit" in v) return `${v.value}${v.unit}`;
+  return withOpacity(String(v), t.$extensions?.["com.goldencomm.figma"]?.opacity);
+};
+const cssName = (t) => t.$extensions?.["com.goldencomm.figma"]?.codeSyntax;
+
+// Format: emit tokens from `options.collections` that carry a WEB codeSyntax, inside `options.selector`.
+StyleDictionary.registerFormat({
+  name: "baseline/css-block",
+  format: ({ dictionary, options }) => {
+    const tokens = dictionary.allTokens
+      .filter((t) => options.collections.includes(t.$extensions?.["com.goldencomm.figma"]?.collection))
+      .filter((t) => cssName(t) && !t.path[0].startsWith("_"))
+      .sort((a, b) => cssName(a).localeCompare(cssName(b)));
+    if (!tokens.length) return "";
+    const body = tokens.map((t) => `  ${cssName(t)}: ${fmtValue(t)};`).join("\n");
+    return `${options.selector} {\n${body}\n}\n`;
+  },
+});
+
+async function buildBlock({ sources, collections, selector }) {
+  const sd = new StyleDictionary({
+    source: sources,
+    usesDtcg: true,
+    // lint.mjs already proves every alias resolves; legacy STRING values that merely contain braces must not abort the build
+    log: { verbosity: process.env.TOKENS_VERBOSE ? "verbose" : "silent", warnings: "disabled", errors: { brokenReferences: "console" } },
+    platforms: {
+      css: {
+        transforms: ["name/kebab"],
+        files: [{ destination: "_.css", format: "baseline/css-block", options: { collections, selector } }],
+      },
+    },
+  });
+  await sd.hasInitialized;
+  const [file] = await sd.formatPlatform("css");
+  return file.output;
+}
+
+const primSources = primitives ? primitives.modes.map((m) => modeFile(primitives, m)) : [];
+// Components (ADR-0017): geometry aliases with codeSyntax are emitted into :root next to the scales they alias
+const components = manifest.collections.find((c) => /Components$/.test(c.name));
+const compSources = components ? [modeFile(components, components.modes[0])] : [];
+// Index the raw (unresolved) Components values and the emitting colour roles, so roleTint can turn a
+// component tint back into the role it aliases. Style Dictionary has already resolved $value by then.
+if (components) indexRaw(modeFile(components, components.modes[0]), componentRefs, false);
+indexRaw(modeFile(theme, theme.modes[0]), roleVars, true);
+const responsive = col("Responsive");
+const respModes = responsive ? responsive.modes.map((m) => {
+  const tree = JSON.parse(readFileSync(modeFile(responsive, m), "utf8"));
+  const min = tree["breakpoint-min-width"]?.$value;
+  return { m, minPx: min && typeof min === "object" ? min.value : (min ?? 0) };
+}).sort((a, b) => a.minPx - b.minPx) : [];
+const baseResp = respModes.find((r) => r.minPx === 0);
+
+let css = "/* Generated by tokens/build.mjs from the Figma export. Do not edit. */\n";
+const [first, ...rest] = theme.modes;
+// :root = Scheme 1 colors + emitted Primitives scales + the Responsive base (mobile) mode
+// Collections that are never emitted but may be alias targets (legacy 2.0 typography, 3.0 sizes) are loaded for
+// resolution only; the `collections` filter decides what is written.
+const resolveOnly = manifest.collections
+  .filter((c) => !["Color Schemes", "Primitives", "Responsive", "Surface"].includes(c.name) && c !== components)
+  .map((c) => modeFile(c, c.modes[0]));
+css += await buildBlock({
+  sources: [...primSources, ...compSources, ...resolveOnly, modeFile(theme, first), ...(baseResp ? [modeFile(responsive, baseResp.m)] : [])],
+  collections: ["Color Schemes", "Primitives", "Responsive", ...(components ? [components.name] : [])], selector: ":root",
+});
+// Scheme 1 is also written under its own data-scheme (B5, 2026-10-07), so a Scheme 1 Section inside a Scheme 2 page
+// (or any other nesting) resets the roles; :root alone only covers the page default.
+for (const m of [first, ...rest]) {
+  css += await buildBlock({ sources: [...primSources, modeFile(theme, m)], collections: ["Color Schemes"], selector: `[data-scheme="${m.slug}"]` });
+}
+// Component tints (ADR-0017 §2) are color-mix() over a scheme role. A custom property's var() is resolved where the
+// property is declared, so a tint declared only on :root keeps Scheme 1's colour inside every other scheme (found
+// 2026-10-01: Card's footer and outline stayed light inside scheme-2). Re-declaring the tints on every scheme root
+// makes each one resolve against that scheme's roles. Shopify gets the same rule on its scheme classes below.
+// A plain role alias (var(--role), amended 2026-10-05) needs the same; geometry aliases (var(--bl-…)) do not.
+const TINT_DECL = /^\s+(--bl-[\w-]+): (color-mix\(in oklab, var\(--[\w-]+\) [\d.]+%, transparent\)|var\((--[\w-]+)\));$/gm;
+const roleCssVars = new Set(roleVars.values());
+const tintDecls = [...css.matchAll(TINT_DECL)].filter((x) => !x[3] || roleCssVars.has(x[3])).map((x) => [x[1], x[2]]);
+if (tintDecls.length) css += `[data-scheme] {\n${tintDecls.map(([k, v]) => `  ${k}: ${v};`).join("\n")}\n}\n`;
+// Responsive modes above the base become mobile-first @media blocks, smallest first, emitting only the
+// declarations whose value differs from the previous (smaller) breakpoint.
+const parseDecls = (block) => Object.fromEntries([...block.matchAll(/^\s+(--[\w-]+): (.+);$/gm)].map((x) => [x[1], x[2]]));
+let previous = baseResp ? parseDecls(await buildBlock({ sources: [...primSources, modeFile(responsive, baseResp.m)], collections: ["Responsive"], selector: ":root" })) : {};
+for (const { m, minPx } of respModes) {
+  if (minPx === 0) continue;
+  const block = await buildBlock({ sources: [...primSources, modeFile(responsive, m)], collections: ["Responsive"], selector: ":root" });
+  if (!block) continue;
+  const decls = parseDecls(block);
+  const changed = Object.entries(decls).filter(([k, v]) => previous[k] !== v);
+  previous = decls;
+  if (!changed.length) continue;
+  css += `@media (min-width: ${minPx}px) {\n  :root {\n${changed.map(([k, v]) => `    ${k}: ${v};`).join("\n")}\n  }\n}\n`;
+}
+
+// Tailwind v4 theme map (ADR-0012): colors --color-<x>: var(--<x>); scales --<path>: var(--bl-<path>)
+const SHADCN = [
+  "background", "foreground", "card", "card-foreground", "popover", "popover-foreground",
+  "primary", "primary-foreground", "secondary", "secondary-foreground", "muted", "muted-foreground",
+  "accent", "accent-foreground", "destructive", "border", "input", "ring",
+  "chart-1", "chart-2", "chart-3", "chart-4", "chart-5",
+  "sidebar", "sidebar-foreground", "sidebar-primary", "sidebar-primary-foreground",
+  "sidebar-accent", "sidebar-accent-foreground", "sidebar-border", "sidebar-ring",
+];
+function collectCodeNames(file) {
+  const out = [];
+  const walk = (node) => { for (const v of Object.values(node)) { if (v && typeof v === "object" && "$value" in v) { const cs = v.$extensions?.["com.goldencomm.figma"]?.codeSyntax; if (cs?.startsWith("--bl-")) out.push(cs); } else if (v && typeof v === "object") walk(v); } };
+  walk(JSON.parse(readFileSync(file, "utf8")));
+  return out;
+}
+const scaleNames = [...new Set([
+  ...primSources.flatMap(collectCodeNames),
+  ...(responsive ? [collectCodeNames(modeFile(responsive, responsive.modes[0]))].flat() : []),
+])].sort();
+// Container sizes are written as their literal values, not var(--bl-container-*): Tailwind builds its @<size>
+// container variants (@md/field-group:) from --container-*, and a container-query condition cannot read a custom
+// property, so with var() Tailwind silently dropped every one of those rules (found 2026-10-02: Field's responsive
+// orientation never applied). The value still comes from Figma; it is fixed at build time instead of runtime, so a
+// container size must be one value at every width (a Responsive one fails here).
+const LITERAL_IN_THEME = /^--bl-container-/;
+const literalOf = (cs) => {
+  const hits = [...css.matchAll(new RegExp(`(?:^|[\\s;{])${cs}:\\s*([^;]+);`, "g"))].map((m) => m[1].trim());
+  if (hits.length !== 1) throw new Error(`build: ${cs} must be declared once (static) to be written as a literal in @theme; found ${hits.length}`);
+  if (hits[0].includes("var(")) throw new Error(`build: ${cs} resolves to ${hits[0]}, not a literal, so a container query cannot use it`);
+  return hits[0];
+};
+const themeMap =
+  "@theme inline {\n" +
+  [
+    ...SHADCN.map((n) => `  --color-${n}: var(--${n});`),
+    ...scaleNames.map((cs) => `  ${cs.replace(/^--bl-/, "--")}: ${LITERAL_IN_THEME.test(cs) ? literalOf(cs) : `var(${cs})`};`),
+  ].join("\n") +
+  "\n}\n";
+
+// registry:base `css` field: the same CSS as a selector -> declarations object (nested for @media).
+function cssToObject(text) {
+  const obj = {};
+  const re = /([^{}]+)\{([^{}]*)\}/g; // flat blocks
+  let rest = text;
+  // pull @media blocks first (they nest one level)
+  rest = rest.replace(/(@media[^{]+)\{\s*([\s\S]*?)\n\}\n/g, (_, q, inner) => { obj[q.trim()] = cssToObject(inner); return ""; });
+  for (const m of rest.matchAll(re)) {
+    const decls = Object.fromEntries(m[2].split(";").map((d) => d.trim()).filter(Boolean).map((d) => { const i = d.indexOf(":"); return [d.slice(0, i).trim(), d.slice(i + 1).trim()]; }));
+    if (Object.keys(decls).length) obj[m[1].trim()] = decls;
+  }
+  return obj;
+}
+// shadcn registry:base wants `cssVars.theme` (theme keys without --) and `cssVars.light` (root values without --);
+// everything else (scheme blocks, @media) goes in the `css` field as selector -> declarations.
+const cssObj = cssToObject((css + themeMap).replace(/^\/\*.*\*\/\n/, ""));
+const strip = (o) => Object.fromEntries(Object.entries(o).map(([k, v]) => [k.replace(/^--/, ""), v]));
+const baseCssVars = { theme: strip(cssObj["@theme inline"] ?? {}), light: strip(cssObj[":root"] ?? {}) };
+const baseCssRest = Object.fromEntries(Object.entries(cssObj).filter(([k]) => k !== "@theme inline" && k !== ":root"));
+// ---------------------------------------------------------------------------------------------------------------
+// Shopify (ADR-0007): static scales -> snippets/baseline-tokens.liquid ({% stylesheet %}); colors -> a Baseline group
+// in config/settings_schema.json (color_palette + color_scheme_group with the shadcn roles) seeded in
+// config/settings_data.json; snippets/baseline-schemes.liquid maps each scheme to the same CSS variables.
+// ---------------------------------------------------------------------------------------------------------------
+const shopifyDir = join(root, "platforms", "shopify", "theme");
+const shopifyOutputs = {};
+if (existsSync(shopifyDir)) {
+  const roles = SHADCN; // 31 shadcn roles in fixed order
+  const sid = (r) => r.replace(/-/g, "_");
+  const label = (r) => r.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+
+  // non-color scale CSS: :root --bl-* lines + the responsive @media blocks
+  const rootBl = (cssObj[":root"] ? Object.entries(cssObj[":root"]).filter(([k]) => k.startsWith("--bl-")) : []);
+  const mediaBlocks = Object.entries(cssObj).filter(([k]) => k.startsWith("@media"));
+  let tokensLiquid = "{% comment %} Generated by tokens/build.mjs from the Figma export. Do not edit. Static (non-color) Baseline scales. {% endcomment %}\n{% stylesheet %}\n:root {\n";
+  tokensLiquid += rootBl.map(([k, v]) => `  ${k}: ${v};`).join("\n") + "\n}\n";
+  // the component tints again on every scheme class (color-<id>, any id a merchant creates), as [data-scheme] above
+  if (tintDecls.length) tokensLiquid += `[class^="color-"],\n[class*=" color-"] {\n${tintDecls.map(([k, v]) => `  ${k}: ${v};`).join("\n")}\n}\n`;
+  for (const [q, inner] of mediaBlocks) {
+    const decls = Object.entries(inner[":root"] ?? {});
+    if (!decls.length) continue;
+    tokensLiquid += `${q} {\n  :root {\n${decls.map(([k, v]) => `    ${k}: ${v};`).join("\n")}\n  }\n}\n`;
+  }
+  tokensLiquid += "{% endstylesheet %}\n";
+  shopifyOutputs["platforms/shopify/theme/snippets/baseline-tokens.liquid"] = tokensLiquid;
+
+  // per-scheme resolved colors (from the generated CSS blocks)
+  const schemeColors = { [first.slug]: cssObj[":root"] ?? {} };
+  for (const m of rest) schemeColors[m.slug] = { ...(cssObj[":root"] ?? {}), ...(cssObj[`[data-scheme="${m.slug}"]`] ?? {}) };
+  const roleValue = (slug, r) => schemeColors[slug]?.[`--${r}`] ?? "#000000";
+  const hex6 = (v) => (typeof v === "string" && /^#[0-9a-f]{8}$/i.test(v) ? v.slice(0, 7) : v); // Shopify color settings take 6-digit hex
+  // Shopify color settings are opaque 6-digit hex, so a role Figma defines WITH an alpha loses it on the way
+  // through settings_data and has to have it re-applied in Liquid. The alpha is read back off the built value
+  // rather than hardcoded, so a designer moving color/ring off 25 % moves Shopify too. It has to be the same
+  // in every scheme, because the snippet emits one rule for all of them.
+  const roleAlpha = (r) => {
+    const alphas = new Set(theme.modes.map((m) => {
+      const v = roleValue(m.slug, r);
+      return /^#[0-9a-f]{8}$/i.test(v) ? parseInt(v.slice(7), 16) / 255 : 1;
+    }));
+    if (alphas.size > 1) {
+      console.error(`build: color/${r} has a different alpha per scheme (${[...alphas].join(", ")}); the Shopify snippet emits one rule for every scheme and cannot express that`);
+      process.exit(1);
+    }
+    return Math.round([...alphas][0] * 100) / 100;
+  };
+
+  // palette: the most-referenced primitive colors (max 20)
+  const primTokens = primitives ? primitives.modes.flatMap((m) => { const t = JSON.parse(readFileSync(modeFile(primitives, m), "utf8")); const out = []; const walk = (node, path) => { for (const [k, v] of Object.entries(node)) { if (v && typeof v === "object" && "$value" in v) out.push({ path: [...path, k].join("/"), value: v.$value }); else if (v && typeof v === "object") walk(v, [...path, k]); } }; walk(t, []); return out; }) : [];
+  const refCount = new Map();
+  for (const m of theme.modes) { const tree = JSON.parse(readFileSync(modeFile(theme, m), "utf8")); const walk = (node) => { for (const v of Object.values(node)) { if (v && typeof v === "object" && "$value" in v) { if (typeof v.$value === "string" && v.$value.startsWith("{")) refCount.set(v.$value.slice(1, -1), (refCount.get(v.$value.slice(1, -1)) ?? 0) + 1); } else if (v && typeof v === "object") walk(v); } }; walk(tree); }
+  const palette = {};
+  for (const [ref] of [...refCount.entries()].sort((a, b) => b[1] - a[1])) {
+    if (Object.keys(palette).length >= 20) break;
+    const tok = primTokens.find((p) => p.path.replace(/\//g, ".") === ref);
+    if (!tok || typeof tok.value !== "string" || !tok.value.startsWith("#")) continue;
+    const key = ref.replace(/^colors\./, "").replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+    if (/^[a-zA-Z]/.test(key)) palette[key] = hex6(tok.value);
+  }
+
+  const baselineGroup = {
+    name: "GC Baseline",
+    settings: [
+      { type: "header", content: "Color schemes" },
+      { type: "paragraph", content: "Generated from the GC Baseline design tokens (Figma). Roles follow shadcn; scheme-1 is the page default." },
+      { type: "color_scheme", id: "default_color_scheme", label: "Default color scheme", default: first.slug },
+      {
+        type: "color_scheme_group",
+        id: "color_schemes",
+        definition: [
+          ...roles.map((r) => ({ type: "color", id: sid(r), label: label(r), default: hex6(roleValue(first.slug, r)) })),
+          // Shopify requires a gradient counterpart for the background role; Baseline leaves it empty by default
+          { type: "color_background", id: "background_gradient", label: "Background gradient" },
+        ],
+        role: {
+          background: { solid: "background", gradient: "background_gradient" },
+          text: "foreground",
+          primary_button: "primary",
+          on_primary_button: "primary_foreground",
+          primary_button_border: "primary",
+          secondary_button: "secondary",
+          on_secondary_button: "secondary_foreground",
+          secondary_button_border: "border",
+          links: "primary",
+          icons: "foreground",
+        },
+      },
+      { type: "header", content: "Palette" },
+      { type: "color_palette", id: "baseline_palette", default: palette },
+    ],
+  };
+  const schemaPath = join(shopifyDir, "config", "settings_schema.json");
+  const schema = existsSync(schemaPath) ? JSON.parse(readFileSync(schemaPath, "utf8")) : [];
+  // ADR-0034: the group is "GC Baseline"; a theme built before the rename still has "Baseline", replaced in place
+  const idx = schema.findIndex((g) => g.name === "GC Baseline" || g.name === "Baseline");
+  if (idx >= 0) schema[idx] = baselineGroup; else schema.push(baselineGroup);
+  shopifyOutputs["platforms/shopify/theme/config/settings_schema.json"] = JSON.stringify(schema, null, 2) + "\n";
+
+  // seed schemes (keep whatever else the merchant/theme has in settings_data)
+  const dataPath = join(shopifyDir, "config", "settings_data.json");
+  let data = { current: {} };
+  if (existsSync(dataPath)) { try { data = JSON.parse(readFileSync(dataPath, "utf8").replace(/^\s*\/\*[\s\S]*?\*\/\s*/, "")); } catch { data = { current: {} }; } }
+  if (typeof data.current !== "object" || data.current === null) data.current = {};
+  data.current.color_schemes = Object.fromEntries(theme.modes.map((m) => [m.slug, { settings: Object.fromEntries(roles.map((r) => [sid(r), hex6(roleValue(m.slug, r))])) }]));
+  if (!data.current.default_color_scheme) data.current.default_color_scheme = first.slug;
+  shopifyOutputs["platforms/shopify/theme/config/settings_data.json"] = JSON.stringify(data, null, 2) + "\n";
+
+  // schemes snippet: one class per scheme exposing the shadcn variables (Liquid is allowed in {% style %}, not {% stylesheet %})
+  shopifyOutputs["platforms/shopify/theme/snippets/baseline-schemes.liquid"] =
+    "{% comment %} Generated by tokens/build.mjs. Maps each color scheme to the Baseline CSS variables (ADR-0007). {% endcomment %}\n" +
+    "{% style %}\n{% for scheme in settings.color_schemes %}\n  .color-{{ scheme.id }} {\n" +
+    // `ring` is a merchant setting like the rest, but Figma gives it an alpha the setting cannot carry, so
+    // it is re-applied here. Without this the Shopify focus ring was a solid block of primary.
+    roles
+      .map((r) =>
+        r === "ring"
+          ? `    --${r}: {{ scheme.settings.${sid(r)} | color_modify: 'alpha', ${roleAlpha("ring")} }};`
+          : `    --${r}: {{ scheme.settings.${sid(r)} }};`,
+      )
+      .join("\n") +
+    // Baseline extension roles (ADR-0026) are derived from the scheme's shadcn roles, not merchant settings:
+    // there is no ring-invalid setting, so it comes off destructive carrying color/ring-invalid's own alpha.
+    `\n    --ring-invalid: {{ scheme.settings.destructive | color_modify: 'alpha', ${roleAlpha("ring-invalid")} }};` +
+    // color/overlay (ADR-0032) derives from no role and has no merchant setting: the Figma value, the same in every scheme.
+    (schemeColors[first.slug]?.["--overlay"] ? `\n    --overlay: ${schemeColors[first.slug]["--overlay"]};` : "") +
+    "\n    --color-background: var(--background);\n    --color-foreground: var(--foreground);\n    background-color: var(--background);\n    color: var(--foreground);\n  }\n{% endfor %}\n{% endstyle %}\n";
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// typeset (ADR-0028 §2): prose rhythm is one stylesheet. tokens/typeset.css is the canonical Baseline fork of shadcn
+// typeset (kept in this package so the client CLI can emit it). The React registry gets it verbatim. WordPress gets
+// a derived copy: (a) unlayered, because core's block styles are unlayered and an unlayered declaration beats any
+// @layer one regardless of specificity (core's `:where(body .is-layout-flow) > *` gap would otherwise win inside
+// .typeset); (b) the block editor's canvas root counts as the wrapper, matched through :where() so specificity is
+// unchanged, so the editor shows the same rhythm without a class.
+// ---------------------------------------------------------------------------------------------------------------
+const typesetSrc = readFileSync(join(here, "typeset.css"), "utf8");
+// Platforms whose own CSS is unlayered (WordPress core, Shopify themes) get the rules unlayered too.
+const typesetUnlayered = (src) => src.replace(/^@layer components \{\n([\s\S]*?)\n\}\n/gm, (_, body) => body.replace(/^  /gm, "") + "\n");
+function typesetForWordPress(src) {
+  const out = typesetUnlayered(src).replace(/\.typeset(?![\w-])/g, ":is(.typeset, :where(.editor-styles-wrapper .is-root-container))");
+  return "/* Generated by tokens/build.mjs from tokens/typeset.css. Do not edit. WordPress copy: unlayered (core block\n   styles are unlayered) and the block editor canvas root counts as the .typeset wrapper. */\n" + out;
+}
+// Shopify (ADR-0007 rules): one {% stylesheet %} per file, no Liquid inside it; Shopify concatenates every
+// stylesheet tag into one unlayered theme CSS file, so the copy is unlayered as well.
+const typesetForShopify = (src) =>
+  "{% comment %} Generated by tokens/build.mjs from tokens/typeset.css. Do not edit. Prose rhythm (ADR-0028): render once from layout/theme.liquid; class=\"typeset\" on every richtext output. {% endcomment %}\n{% stylesheet %}\n" +
+  typesetUnlayered(src).replace(/^\/\*[\s\S]*?\*\/\n\n/, "") + "{% endstylesheet %}\n";
+const typesetOutputs = {
+  "registry/src/styles/typeset.css": typesetSrc,
+  "platforms/wordpress/theme/src/typeset.css": typesetForWordPress(typesetSrc),
+  ...(existsSync(shopifyDir) ? { "platforms/shopify/theme/snippets/typeset.liquid": typesetForShopify(typesetSrc) } : {}),
+};
+
+// ---------------------------------------------------------------------------------------------------------------
+// Content ramp (ADR-0014, amended 2026-10-07): Figma's display/* and heading/* text styles (src/figma/text-styles.json,
+// written by import.mjs from the export) become one class per style, named as the style with "/" -> "-"
+// (display/lg -> display-lg). Each declaration reads the variable the style binds: size and line-height through their
+// codeSyntax (so the Responsive steps keep changing per breakpoint), the family through font/*, the weight as the
+// Figma-only font-weight value (ADR-0022 §1: never emitted, code writes the number). Not `text-*`: shadcn's cn
+// (tailwind-merge) would read text-display-lg as a colour and drop it beside text-foreground.
+// ---------------------------------------------------------------------------------------------------------------
+const textStylesPath = join(src, "text-styles.json");
+const rampStyles = existsSync(textStylesPath) ? JSON.parse(readFileSync(textStylesPath, "utf8")).textStyles.filter((s) => /^(display|heading)\//.test(s.name)) : [];
+const tokenTree = {};
+const tokenAt = (ref) => {
+  const [colName, name] = ref.split("|");
+  const c = manifest.collections.find((x) => x.name === colName);
+  if (!c) throw new Error(`text style binds ${ref}: no such collection`);
+  tokenTree[colName] ??= JSON.parse(readFileSync(modeFile(c, c.modes.find((m) => /base|mode 1|value/i.test(m.name)) ?? c.modes[0]), "utf8"));
+  const leaf = name.split("/").reduce((o, k) => o?.[k], tokenTree[colName]);
+  if (!leaf) throw new Error(`text style binds ${ref}: no such variable`);
+  return leaf;
+};
+const cssVarOf = (ref) => {
+  const cs = tokenAt(ref).$extensions?.["com.goldencomm.figma"]?.codeSyntax;
+  if (!cs) throw new Error(`text style binds ${ref}, which has no codeSyntax (not emitted)`);
+  return `var(${cs})`;
+};
+const rampDecls = rampStyles.map((s) => {
+  const b = s.bindings;
+  for (const f of ["fontFamily", "fontSize", "lineHeight", "fontWeight"]) if (!b[f]) throw new Error(`text style ${s.name} has no ${f} variable: bind it in Figma`);
+  return {
+    name: s.name, cls: s.name.replace(/\//g, "-"),
+    decls: [
+      ["font-family", cssVarOf(b.fontFamily)],
+      ["font-size", cssVarOf(b.fontSize)],
+      ["line-height", cssVarOf(b.lineHeight)],
+      ["font-weight", String(tokenAt(b.fontWeight).$value)],
+    ],
+  };
+});
+const block = (sel, decls, indent = "") => `${indent}${sel} {\n${decls.map(([p, v]) => `${indent}  ${p}: ${v};`).join("\n")}\n${indent}}\n`;
+const rampHeader = (how) => `/* Generated by tokens/build.mjs from the Figma text styles (src/figma/text-styles.json). Do not edit. Content ramp\n   (ADR-0014): ${how} */\n`;
+const rampOutputs = rampDecls.length ? {
+  // React and HTML: Tailwind utilities, so variants work (md:heading-xl) and they sit in the utilities layer above typeset
+  "registry/src/styles/text-styles.css": rampHeader("one Tailwind utility per style, e.g. className=\"display-lg\".") +
+    rampDecls.map((r) => `@utility ${r.cls} {\n${r.decls.map(([p, v]) => `  ${p}: ${v};`).join("\n")}\n}\n`).join(""),
+  // WordPress: a class per style plus core's font-size preset class (theme.json fontSizes, same slugs). Doubled class:
+  // typeset's unlayered heading rules are (0,1,1) and must not win the line-height or weight.
+  "platforms/wordpress/theme/src/text-styles.css": rampHeader("a class per style, and the matching core font-size preset (has-<style>-font-size).") +
+    rampDecls.map((r) => block(`:is(.${r.cls}, .has-${r.cls}-font-size):is(.${r.cls}, .has-${r.cls}-font-size)`, r.decls)).join(""),
+  ...(existsSync(shopifyDir) ? {
+    "platforms/shopify/theme/snippets/text-styles.liquid":
+      `{% comment %} Generated by tokens/build.mjs from the Figma text styles. Do not edit. Content ramp (ADR-0014): render once from layout/theme.liquid; the heading block applies the classes. {% endcomment %}\n{% stylesheet %}\n` +
+      rampDecls.map((r) => block(`.${r.cls}.${r.cls}`, r.decls)).join("") + "{% endstylesheet %}\n",
+  } : {}),
+} : {};
+
+const outputs = {
+  ...shopifyOutputs,
+  ...typesetOutputs,
+  ...rampOutputs,
+  "registry/src/styles/tokens.css": css + themeMap,
+  "registry/src/base.cssvars.json": JSON.stringify(baseCssVars, null, 2) + "\n",
+  "registry/src/base.css.json": JSON.stringify(baseCssRest, null, 2) + "\n",
+  // WordPress runs its own Tailwind build (ADR-0008), so it needs the @theme map too
+  "platforms/wordpress/theme/assets/tokens.css": css + themeMap,
+  // the HTML target runs its own Tailwind build too (scripts/gen-html.mjs)
+  "platforms/html/dist/tokens.css": css + themeMap,
+};
+for (const [rel, content] of Object.entries(outputs)) {
+  const p = join(root, rel);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+}
+console.log(`build: wrote ${Object.keys(outputs).length} files (${css.split("\n").length} lines of CSS)`);
+
+// ---------------------------------------------------------------------------------------------------------
+// Cross-token invariants. These are relationships between variables that no single variable can express, so
+// nothing else would catch them breaking -- the symptom is a component looking slightly wrong, which is
+// exactly the kind of thing that survives review. Asserted against the EMITTED css, so it checks what ships
+// rather than what the source says.
+// ---------------------------------------------------------------------------------------------------------
+{
+  const emitted = readFileSync(join(root, "registry", "src", "styles", "tokens.css"), "utf8");
+  const px = (name) => {
+    const m = new RegExp(`--${name}:\\s*(-?[\\d.]+)px`).exec(emitted);
+    return m ? Number(m[1]) : null;
+  };
+  // Base UI's Select positions the panel so the selected row's TEXT sits over the trigger's text
+  // (alignItemWithTrigger). The two insets have to match or the panel sits off its trigger.
+  const panel = px("bl-select-panel-padding");
+  const item = px("bl-select-item-padding-x");
+  const trigger = px("bl-select-md-padding-x");
+  if (panel !== null && item !== null && trigger !== null && panel + item !== trigger) {
+    console.error(
+      `build: select panel inset does not match the trigger's. ` +
+        `select/panel/padding (${panel}) + select/item/padding-x (${item}) = ${panel + item}, ` +
+        `but select/md/padding-x is ${trigger}. alignItemWithTrigger will sit the panel ` +
+        `${trigger - (panel + item)}px off its trigger.`,
+    );
+    process.exit(1);
+  }
+}