From d1c6180e0f84129e75094bbb4b61aa0d2e862e15 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Aug 2026 15:23:16 +0000
Subject: [PATCH 1/4] feat(ci): add check:forbidden-strings gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two framework promises were honour-system only, with no gate able to catch
a regression against either:

  1. "Every visual value is a named token; hardcoded numbers are treated as
     bugs" — a literal #3b5bdb in core/macros.css passes every existing check.
  2. "Standalone, no external requests" — an absolute URL reaching a dist
     bundle would make every consumer page phone home, silently.

The existing check:* gates all answer "is X in sync with Y?"; neither of the
above is a sync question, so nothing covered them.

Adds a rule-driven scanner over the source tree and the built bundles:

  - hardcoded-color: hex / rgb() / hsl() literals in core/ + optional/ CSS,
    excluding the four token source files whose job is to declare raw values.
    Comments are masked with scripts/lib/parse.js's offset-preserving
    maskComments, so issue references (#496, #497) are not false positives
    and reported line numbers still point at the original source.
  - external-url: any absolute URL in dist/*.css.
  - debug-statement: console.log/debug and debugger in configurator/src.
    scripts/ is out of scope — those are CLIs whose console.log is output.

Deliberate exceptions live in ALLOW, keyed by rule id -> file -> the exact
matched text (not merely the path), so excepting `#fff` in core/base.css does
not blanket-approve a future literal in that same file. Each entry carries a
reason, matching the docs/ref-allowlist.json contract.

Runs in the artifacts-freshness job after check-artifacts.js, which rebuilds
dist/ — so the bundle rules have something to scan.

13 negative tests assert each rule bites, that comment masking neither hides a
real violation nor mis-reports its line, and that an unbuilt tree does not
crash the gate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01STwfcKmspjEbUYrKDVZgqt
---
 .github/workflows/ci.yml              |   5 +
 CLAUDE.md                             |   1 +
 package.json                          |   1 +
 scripts/check-forbidden-strings.js    | 265 ++++++++++++++++++++++++++
 tests/check-forbidden-strings.test.js | 176 +++++++++++++++++
 5 files changed, 448 insertions(+)
 create mode 100644 scripts/check-forbidden-strings.js
 create mode 100644 tests/check-forbidden-strings.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b571819e..dcbfe9d5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -109,6 +109,11 @@ jobs:
       - run: node scripts/check-hook-tokens.js
       - run: node scripts/check-mirrors.js
       - run: node scripts/check-bundle-defs.js
+      # Strings that must never ship: hardcoded colour literals outside the
+      # token source files, and external URLs in a built bundle. Runs after
+      # check-artifacts.js, which rebuilds dist/ — so the bundle rules have
+      # something to scan.
+      - run: npm run check:forbidden-strings
 
   dependency-audit:
     name: Dependency vulnerability audit
diff --git a/CLAUDE.md b/CLAUDE.md
index 53ab14a8..1e7360ae 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,6 +61,7 @@ requires a rebuild+redeploy, not just a file edit.
 | `npm run check:layer-order` | Verify `docs/architecture.md`'s `@layer` block and specificity ladder match `core/layers.css` (CI gate) |
 | `npm run check:macros` | Verify `.sf-*` macro classes match `docs/macros.md` (CI gate) |
 | `npm run check:registry` | Verify `token-registry.json` is in sync with source (CI gate) |
+| `npm run check:forbidden-strings` | Verify no hardcoded colour literal sits outside the token source files and no shipped bundle contains an external URL (CI gate) |
 | `npm run audit:check` | Verify `docs/registry.json` matches source without writing (CI gate) |
 | `npm run lint:css` | Lint all CSS source with stylelint (CI gate) |
 | `npm run lint:css:fix` | Lint CSS source and auto-fix violations |
diff --git a/package.json b/package.json
index f99a4af0..7a8698ef 100644
--- a/package.json
+++ b/package.json
@@ -48,6 +48,7 @@
     "check:hook-tokens": "node scripts/check-hook-tokens.js",
     "check:mirrors": "node scripts/check-mirrors.js",
     "check:bundle-defs": "node scripts/check-bundle-defs.js",
+    "check:forbidden-strings": "node scripts/check-forbidden-strings.js --check",
     "configurator:sync": "node configurator/scripts/sync-api.mjs",
     "docs:tokens": "node scripts/gen-token-reference.js",
     "docs:index": "node scripts/gen-token-index.js",
diff --git a/scripts/check-forbidden-strings.js b/scripts/check-forbidden-strings.js
new file mode 100644
index 00000000..477faaed
--- /dev/null
+++ b/scripts/check-forbidden-strings.js
@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * CI gate: strings that must never ship.
+ *
+ * The other check:* gates all answer "is X still in sync with Y?" — they prove
+ * generated artifacts match their sources (check-artifacts), that docs only
+ * name live API (check-doc-refs, check-llm-guide), that ids are permanent
+ * (check-token-registry). None of them can answer the different question this
+ * gate exists for: "did something get into the source or the shipped bundle
+ * that has no business being there at all?"
+ *
+ * Two framework promises are currently honour-system only:
+ *
+ *   1. "Every visual value is a named token; hardcoded numbers are treated as
+ *      bugs" (README, CLAUDE.md). Nothing stops a literal `#3b5bdb` landing in
+ *      core/macros.css — it would pass every existing gate.
+ *   2. "Standalone — no runtime dependencies", "no external requests". Nothing
+ *      stops a `@import url(https://fonts.googleapis.com/…)` reaching a dist
+ *      bundle, which would silently make every consumer's page phone home.
+ *
+ * Both are exactly the class of regression that is cheap to prevent and
+ * expensive to notice later. This gate turns each promise into a mechanical
+ * check over the source tree AND the built bundles.
+ *
+ * Deliberate exceptions are recorded per rule in ALLOW, each with a reason —
+ * same contract as docs/ref-allowlist.json. An unexplained exception is not
+ * possible: the allow entry IS the explanation, and it names the exact matched
+ * text, not just the file, so a second unrelated violation in an
+ * already-excepted file still fails.
+ *
+ * Run:
+ *   node scripts/check-forbidden-strings.js          # report, exit 0
+ *   node scripts/check-forbidden-strings.js --check  # report, exit 1 on any hit
+ *   npm run check:forbidden-strings                  # the --check form (CI)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { maskComments } from './lib/parse.js';
+
+// SLASHED_ROOT lets the negative tests run this gate against a fixture tree.
+const slashedRoot = process.env.SLASHED_ROOT?.trim();
+const ROOT = slashedRoot
+  ? path.resolve(slashedRoot)
+  : path.resolve(import.meta.dirname, '..');
+
+const checkMode = process.argv.includes('--check');
+
+/**
+ * Files whose entire job is to declare raw values — the bottom of the token
+ * stack, where a literal colour is the definition, not a shortcut.
+ */
+const TOKEN_SOURCE_FILES = [
+  'core/tokens.css',
+  'core/tokens.layout.css',
+  'core/tokens.macros.css',
+  'optional/tokens.components.css',
+];
+
+/**
+ * @typedef {object} Rule
+ * @property {string}   id          stable slug, used in output and in ALLOW
+ * @property {string}   label       one-line description of what was found
+ * @property {string}   why         what breaks if this ships (printed on failure)
+ * @property {RegExp}   pattern     global regex; every match is a candidate hit
+ * @property {string[]} targets     path prefixes to walk, relative to ROOT
+ * @property {string[]} extensions  file extensions to read
+ * @property {string[]} [exclude]   exact relative paths to skip entirely
+ * @property {boolean}  [maskComments] blank comment bodies before matching
+ *                                  (offset-preserving, so line numbers still
+ *                                  point at the original source)
+ */
+
+/** @type {Rule[]} */
+const RULES = [
+  {
+    id: 'hardcoded-color',
+    label: 'hardcoded colour literal outside the token source files',
+    why:
+      'The framework promises every visual value is a named token. A literal colour ' +
+      'here cannot be rebranded, cannot participate in the light-dark() / oklch() ' +
+      'derivation chain, and will not follow a consumer\'s theme.',
+    // Hex literals plus the legacy colour functions. oklch()/color-mix() are
+    // absent by design: those are the derivation syntax the token layer is
+    // built on, not a hardcoded value.
+    pattern: /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\(/g,
+    targets: ['core/', 'optional/'],
+    extensions: ['.css'],
+    exclude: TOKEN_SOURCE_FILES,
+    maskComments: true,
+  },
+  {
+    id: 'external-url',
+    label: 'external URL in a shipped bundle',
+    why:
+      'A shipped bundle must never cause a network request. Any absolute URL here ' +
+      'means every consumer page silently fetches from a third party — breaking the ' +
+      '"standalone, no external requests" guarantee and leaking visitor IPs.',
+    pattern: /https?:\/\/[^\s"')]+/g,
+    targets: ['dist/'],
+    extensions: ['.css'],
+    // Deliberately NOT comment-masked: a URL in a bundle banner is still a URL
+    // shipped to consumers, and should be a recorded decision.
+  },
+  {
+    id: 'debug-statement',
+    label: 'debug statement left in configurator source',
+    why:
+      'console.log/debug and debugger statements are development leftovers. They ship ' +
+      'to the deployed configurator, clutter the console, and can leak internal state. ' +
+      'Diagnostics that are meant to survive belong in console.warn/error.',
+    pattern: /\bconsole\s*\.\s*(?:log|debug)\s*\(|\bdebugger\b/g,
+    targets: ['configurator/src/'],
+    extensions: ['.ts', '.svelte', '.js'],
+    // scripts/ is deliberately out of scope: those are CLIs whose console.log
+    // IS their output.
+  },
+];
+
+/**
+ * Deliberate, reasoned exceptions.
+ *
+ * Shape: ALLOW[ruleId][relativePath][exactMatchedText] = reason.
+ *
+ * Keyed by the matched TEXT, not just the file, so excepting `#fff` in a file
+ * does not blanket-approve a future `#3b5bdb` in that same file.
+ */
+const ALLOW = {
+  'hardcoded-color': {
+    'core/base.css': {
+      '#fff':
+        'var() fallback of last resort — renders readable if the token layer ' +
+        'failed to load entirely. Not a themeable value by definition.',
+    },
+    'optional/components.css': {
+      '#000':
+        'linear-gradient(#000 0 0) mask stops — a mask reads only the alpha ' +
+        'channel, so the colour is structurally inert and tokenising it would ' +
+        'imply a themeable value that does not exist.',
+    },
+  },
+  'external-url': {
+    'dist/slashed.full.css': {
+      'http://www.w3.org/2000/svg':
+        'XML namespace identifier inside an inline SVG data: URI. Namespaces are ' +
+        'never dereferenced — no network request is made.',
+    },
+  },
+};
+
+// The same inline-SVG namespace appears in every bundle variant; mirror the one
+// documented exception across them rather than repeating the reason four times.
+for (const variant of [
+  'dist/slashed.optimal.css',
+  'dist/slashed.full.flat.css',
+  'dist/slashed.optimal.flat.css',
+  'dist/slashed.full.min.css',
+  'dist/slashed.optimal.min.css',
+  'dist/slashed.full.flat.min.css',
+  'dist/slashed.optimal.flat.min.css',
+]) {
+  ALLOW['external-url'][variant] = ALLOW['external-url']['dist/slashed.full.css'];
+}
+
+/**
+ * Collect every file under a rule's targets matching its extensions.
+ * A target may be a directory prefix ("core/") or an exact file.
+ * @param {Rule} rule
+ * @returns {string[]} repo-relative paths, sorted
+ */
+function collectFiles(rule) {
+  const out = new Set();
+  const exclude = new Set(rule.exclude ?? []);
+
+  const visit = (abs, rel) => {
+    let stat;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      return; // target absent (e.g. dist/ before a build) — nothing to scan
+    }
+    if (stat.isDirectory()) {
+      for (const entry of fs.readdirSync(abs)) {
+        if (entry === 'node_modules' || entry.startsWith('.')) continue;
+        visit(path.join(abs, entry), rel ? `${rel}/${entry}` : entry);
+      }
+      return;
+    }
+    if (!rule.extensions.some((ext) => rel.endsWith(ext))) return;
+    if (exclude.has(rel)) return;
+    out.add(rel);
+  };
+
+  for (const target of rule.targets) {
+    const clean = target.replace(/\/$/, '');
+    visit(path.join(ROOT, clean), clean);
+  }
+  return [...out].sort();
+}
+
+/** 1-based line number of a character offset. */
+function lineAt(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) {
+    if (text[i] === '\n') line++;
+  }
+  return line;
+}
+
+/**
+ * Run one rule over the tree.
+ * @param {Rule} rule
+ * @returns {{ rule: Rule, hits: Array<{file:string,line:number,text:string}>, allowed: number, scanned: number }}
+ */
+function runRule(rule) {
+  const hits = [];
+  let allowed = 0;
+  const files = collectFiles(rule);
+
+  for (const rel of files) {
+    const raw = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    // maskComments blanks comment bodies with same-length whitespace, so match
+    // offsets still line up with the original file's line numbering.
+    const haystack = rule.maskComments ? maskComments(raw) : raw;
+    const allowForFile = ALLOW[rule.id]?.[rel] ?? {};
+
+    rule.pattern.lastIndex = 0;
+    for (const match of haystack.matchAll(rule.pattern)) {
+      const text = match[0];
+      if (Object.prototype.hasOwnProperty.call(allowForFile, text)) {
+        allowed++;
+        continue;
+      }
+      hits.push({ file: rel, line: lineAt(haystack, match.index ?? 0), text });
+    }
+  }
+
+  return { rule, hits, allowed, scanned: files.length };
+}
+
+const results = RULES.map(runRule);
+const failing = results.filter((r) => r.hits.length > 0);
+
+if (failing.length) {
+  console.error('check:forbidden-strings FAILED:\n');
+  for (const { rule, hits } of failing) {
+    console.error(`  [${rule.id}] ${rule.label}`);
+    console.error(`  ${rule.why}\n`);
+    for (const hit of hits) {
+      console.error(`    ${hit.file}:${hit.line}  ${hit.text}`);
+    }
+    console.error('');
+  }
+  console.error(
+    'If a match is deliberate, add it to ALLOW in scripts/check-forbidden-strings.js\n' +
+      'keyed by rule id → file → the exact matched text, with a reason explaining why\n' +
+      'it is safe. An exception without a reason is not an exception.',
+  );
+  if (checkMode) process.exit(1);
+} else {
+  const summary = results
+    .map((r) => `${r.rule.id}: ${r.scanned} file(s)${r.allowed ? `, ${r.allowed} allowed` : ''}`)
+    .join('; ');
+  console.log(`check:forbidden-strings OK — ${summary}.`);
+}
diff --git a/tests/check-forbidden-strings.test.js b/tests/check-forbidden-strings.test.js
new file mode 100644
index 00000000..7efd4fd5
--- /dev/null
+++ b/tests/check-forbidden-strings.test.js
@@ -0,0 +1,176 @@
+/**
+ * Negative tests for scripts/check-forbidden-strings.js.
+ *
+ * A gate that has never been observed to fail is indistinguishable from a gate
+ * that cannot fail. Each test below plants exactly one violation in a fixture
+ * tree (SLASHED_ROOT), and asserts the gate reports it and — under --check —
+ * exits non-zero. The passing-fixture test guards the opposite failure mode: a
+ * rule so broad it fires on legitimate source.
+ */
+import { test, describe, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const GATE = path.join(ROOT, 'scripts', 'check-forbidden-strings.js');
+
+const tmpDirs = [];
+
+/**
+ * Build a minimal fixture tree. Every file is optional; omitted ones are
+ * written with clean, rule-satisfying content so a test can plant a single
+ * violation without the others interfering.
+ * @param {{ [relPath: string]: string }} files
+ */
+function buildFixture(files = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slashed-forbidden-'));
+  tmpDirs.push(dir);
+
+  const defaults = {
+    // Excluded from hardcoded-color by design — proves the exclusion works.
+    'core/tokens.css': ':root { --sf-color-primary: #3b5bdb; }\n',
+    'core/base.css': 'body { color: var(--sf-color-text); }\n',
+    'optional/forms.css': 'input { border: 1px solid var(--sf-color-border); }\n',
+    'dist/slashed.optimal.css': '/*! SLASHED v0.0.0 */\n:root { --sf-x: 1; }\n',
+    'configurator/src/lib/thing.ts': 'export const x = 1;\n',
+  };
+
+  for (const [rel, content] of Object.entries({ ...defaults, ...files })) {
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  return dir;
+}
+
+function runGate(dir, args = []) {
+  return spawnSync(process.execPath, [GATE, ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, SLASHED_ROOT: dir },
+  });
+}
+
+after(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('check-forbidden-strings', () => {
+  test('passes on a clean fixture', () => {
+    const r = runGate(buildFixture(), ['--check']);
+    assert.equal(r.status, 0, `expected pass:\n${r.stderr}`);
+    assert.match(r.stdout, /check:forbidden-strings OK/);
+  });
+
+  test('does not flag colour literals inside the token source files', () => {
+    // core/tokens.css in the default fixture is full of hex; it must stay silent.
+    const r = runGate(buildFixture(), ['--check']);
+    assert.equal(r.status, 0, `token source files must be exempt:\n${r.stderr}`);
+  });
+
+  test('flags a hardcoded hex colour in a non-token CSS file', () => {
+    const dir = buildFixture({
+      'core/macros.css': '.sf-prose { color: #3b5bdb; }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1, 'expected a non-zero exit');
+    assert.match(r.stderr, /hardcoded-color/);
+    assert.match(r.stderr, /core\/macros\.css:1/);
+    assert.match(r.stderr, /#3b5bdb/);
+  });
+
+  test('flags a hardcoded rgb() colour', () => {
+    const dir = buildFixture({
+      'optional/utilities.css': '.sf-x { background: rgba(0, 0, 0, 0.5); }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /optional\/utilities\.css:1/);
+  });
+
+  test('ignores a colour literal that appears only inside a comment', () => {
+    const dir = buildFixture({
+      'core/macros.css': '/* was #3b5bdb before tokenising, and issue #496 */\n.sf-x { color: var(--sf-color-primary); }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 0, `comments must be masked:\n${r.stderr}`);
+  });
+
+  test('reports the original line number despite comment masking', () => {
+    const dir = buildFixture({
+      'core/macros.css': '/* banner\n   spanning\n   lines */\n.sf-x { color: #abc; }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1);
+    // The violation is on line 4 of the original file; a non-offset-preserving
+    // comment strip would report line 1 or 2 here.
+    assert.match(r.stderr, /core\/macros\.css:4/);
+  });
+
+  test('flags an external URL in a shipped bundle', () => {
+    const dir = buildFixture({
+      'dist/slashed.optimal.css': "@import url(https://fonts.googleapis.com/css2?family=Inter);\n",
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /external-url/);
+    assert.match(r.stderr, /fonts\.googleapis\.com/);
+  });
+
+  test('allows the inline-SVG XML namespace in a bundle', () => {
+    const dir = buildFixture({
+      'dist/slashed.optimal.css':
+        ".sf-x { background: url('data:image/svg+xml,<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>'); }\n",
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 0, `namespace URI must be allowed:\n${r.stderr}`);
+  });
+
+  test('flags a console.log left in configurator source', () => {
+    const dir = buildFixture({
+      'configurator/src/lib/thing.ts': 'export function f() { console.log("hi"); }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /debug-statement/);
+  });
+
+  test('does not flag console.warn in configurator source', () => {
+    const dir = buildFixture({
+      'configurator/src/lib/thing.ts': 'export function f() { console.warn("real diagnostic"); }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 0, `console.warn is legitimate:\n${r.stderr}`);
+  });
+
+  test('without --check, reports the violation but exits 0', () => {
+    const dir = buildFixture({
+      'core/macros.css': '.sf-x { color: #3b5bdb; }\n',
+    });
+    const r = runGate(dir);
+    assert.equal(r.status, 0, 'report-only mode must not fail the shell');
+    assert.match(r.stderr, /hardcoded-color/);
+  });
+
+  test('an allowed match does not blanket-approve other matches in the same file', () => {
+    // core/base.css has a real ALLOW entry for `#fff`. A different literal in
+    // that same file must still fail — this is the key property of keying the
+    // allowlist by matched text rather than by path.
+    const dir = buildFixture({
+      'core/base.css': 'body { color: var(--sf-color-bg, #fff); border-color: #3b5bdb; }\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1, 'a second, unexcepted literal must still fail');
+    assert.match(r.stderr, /#3b5bdb/);
+    assert.doesNotMatch(r.stderr, /#fff/);
+  });
+
+  test('tolerates a missing target directory', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slashed-forbidden-empty-'));
+    tmpDirs.push(dir);
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 0, `an unbuilt tree must not crash the gate:\n${r.stderr}`);
+  });
+});

From e46134802dd3d683da666aa65e8a2e39a2e364c7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Aug 2026 15:26:58 +0000
Subject: [PATCH 2/4] fix(components): complete the text--subtle rename in the
 .sf-card surface block
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 0.7.25 rename of --sf-color-text--secondary to --sf-color-text--subtle
was applied in core/tokens.css but missed one mirror: the .sf-card block in
optional/components.css, which re-derives the resolved colour tokens for a
card sitting on an active surface, still declared the pre-rename name.

The two declarations are character-for-character the same light-dark()/oklch
formula, and that block's own comment (SL-001) states it mirrors tokens.css's
"Resolved color tokens" — so this was a missed spot, not a deliberate
divergence.

Effect: nothing reads var(--sf-color-text--secondary), so the card was setting
a name no one consumes while consumers reading the live --sf-color-text--subtle
inside a card on a coloured surface silently got the unadjusted :root value
instead of the card-tuned one. token-registry.json already had the old name
flagged removed; only the stale declaration kept it textually alive.

No catalogue or doc churn: a full rebuild regenerates every artifact byte for
byte, because the declaration sat inside a @container style() block the API
index never catalogued.

Found by the new check:token-renames gate, which refuses to migrate users away
from a token that is still live.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01STwfcKmspjEbUYrKDVZgqt
---
 optional/components.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/optional/components.css b/optional/components.css
index 715167b9..555eeffc 100644
--- a/optional/components.css
+++ b/optional/components.css
@@ -444,7 +444,7 @@
           oklch(from var(--sf-color-neutral-source-light) clamp(0.05, calc(l - 0.4 - var(--sf-contrast-bias)), 0.35) c h),
           oklch(from var(--sf-color-neutral)              clamp(0.70, calc(l + 0.25 + var(--sf-contrast-bias)), 1)    c h));
         --sf-color-text: var(--sf-color-heading);
-        --sf-color-text--secondary: light-dark(
+        --sf-color-text--subtle: light-dark(
           oklch(from var(--sf-color-neutral-source-light) clamp(0.15, calc(l - 0.25 - var(--sf-contrast-bias)), 0.45) c h),
           oklch(from var(--sf-color-neutral)              clamp(0.55, calc(l + 0.1 + var(--sf-contrast-bias)), 0.90) c h));
         --sf-color-border: light-dark(

From f63dcd0c3dc46276345dabcc95be598d3b179181 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Aug 2026 15:37:22 +0000
Subject: [PATCH 3/4] feat(tooling): portable theme file with automatic token
 migration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The configurator could persist an override set two ways, and neither is a file
you can put in a repository: localStorage (trapped in one browser profile) and
the share link (a compressed base64url blob — ideal for a short URL, opaque in
a diff, and keyed by numeric token id).

Adds a third form: *.slashed-theme.json, a name-keyed, sorted, pretty-printed
snapshot. Because it is keyed by name and byte-stable, `git diff` shows exactly
which token changed value — so a rebrand becomes reviewable in a pull request,
and a theme can live next to the CSS it themes.

Name-keying is what makes it readable and also what makes it vulnerable to a
rename, so the format ships with a migration path:

  docs/token-renames.json — a curated mirror of docs/migration.md, seeded with
  the 45 renames and 31 removals that release actually documents. This cannot
  be generated: token-registry.json keeps ids permanent, but
  check-token-registry.js deliberately permits renames as in-place name updates
  on the same id, so after a rename the old name is simply gone with nothing to
  look it up by. Harmless for the id-keyed codec, fatal for a name-keyed file.
  A rename and a delete+add pair are also indistinguishable to a generator.

  scripts/check-token-renames.js — CI gate holding the map to three invariants:
  every rename target is live, no old name is still live, renames and removals
  are disjoint. Requiring targets to be live forbids chains by construction.
  It found a real bug on its first run (fixed in the preceding commit).

  scripts/migrate-theme.js — CLI. Report-only by default and exits non-zero
  when migration is needed, so it doubles as a CI check over committed theme
  files; --write is the explicit opt-in to mutate. Never discards an override
  it does not recognise: unknown names are reported and kept, because absence
  of knowledge is not evidence the user was wrong.

Configurator gets export + import in the Setup panel, applying the same
migration on load and listing every adjustment made. Its implementation is a
deliberate mirror rather than a shared import: the @framework-css alias is
remapped by the WordPress plugin to a vendored dist/ with no scripts/, so
reaching across the package boundary at runtime would break that build. The
mirror is held honest by configurator/tests/themeFile.test.ts, which runs both
implementations over the same fixtures under Vitest (which, unlike the shipped
bundle, can import both) and asserts identical results.

32 new tests: format validation, migration semantics (idempotence, collision
handling, unknown-token preservation), round-trip byte stability, CLI exit
codes, and 10 negative tests per gate invariant.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01STwfcKmspjEbUYrKDVZgqt
---
 .github/workflows/ci.yml                      |   4 +
 CLAUDE.md                                     |  36 +++
 configurator/scripts/sync-api.mjs             |  46 ++++
 .../src/components/DomainPanel.svelte         |   2 +-
 .../src/components/panels/ExportPanel.svelte  | 107 +++++++-
 .../src/data/token-renames.generated.json     |  86 +++++++
 configurator/src/lib/themeFile.ts             | 199 +++++++++++++++
 configurator/tests/themeFile.test.ts          | 133 ++++++++++
 docs/getting-started.md                       |  38 +++
 docs/token-renames.json                       | 109 ++++++++
 package.json                                  |   2 +
 scripts/artifacts.json                        |   8 +-
 scripts/check-token-renames.js                | 127 ++++++++++
 scripts/lib/theme-file.js                     | 215 ++++++++++++++++
 scripts/migrate-theme.js                      | 132 ++++++++++
 tests/check-token-renames.test.js             | 141 +++++++++++
 tests/theme-file.test.js                      | 238 ++++++++++++++++++
 17 files changed, 1617 insertions(+), 6 deletions(-)
 create mode 100644 configurator/src/data/token-renames.generated.json
 create mode 100644 configurator/src/lib/themeFile.ts
 create mode 100644 configurator/tests/themeFile.test.ts
 create mode 100644 docs/token-renames.json
 create mode 100644 scripts/check-token-renames.js
 create mode 100644 scripts/lib/theme-file.js
 create mode 100644 scripts/migrate-theme.js
 create mode 100644 tests/check-token-renames.test.js
 create mode 100644 tests/theme-file.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index dcbfe9d5..90066707 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -114,6 +114,10 @@ jobs:
       # check-artifacts.js, which rebuilds dist/ — so the bundle rules have
       # something to scan.
       - run: npm run check:forbidden-strings
+      # docs/token-renames.json must stay truthful: every rename target live,
+      # no old name still live. A stale map migrates theme files onto dead
+      # tokens, which is worse than having no map at all.
+      - run: npm run check:token-renames
 
   dependency-audit:
     name: Dependency vulnerability audit
diff --git a/CLAUDE.md b/CLAUDE.md
index 1e7360ae..712f2a21 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -62,6 +62,8 @@ requires a rebuild+redeploy, not just a file edit.
 | `npm run check:macros` | Verify `.sf-*` macro classes match `docs/macros.md` (CI gate) |
 | `npm run check:registry` | Verify `token-registry.json` is in sync with source (CI gate) |
 | `npm run check:forbidden-strings` | Verify no hardcoded colour literal sits outside the token source files and no shipped bundle contains an external URL (CI gate) |
+| `npm run check:token-renames` | Verify `docs/token-renames.json` is truthful — every rename target is a live token, no old name still is (CI gate) |
+| `npm run migrate:theme -- <file> [--write]` | Migrate a `*.slashed-theme.json` theme file onto the current token API |
 | `npm run audit:check` | Verify `docs/registry.json` matches source without writing (CI gate) |
 | `npm run lint:css` | Lint all CSS source with stylelint (CI gate) |
 | `npm run lint:css:fix` | Lint CSS source and auto-fix violations |
@@ -141,6 +143,40 @@ instance token, an example of a component the framework does not ship) — recor
 it in `docs/ref-allowlist.json` with a reason. `docs/migration.md` (historical)
 and `docs/roadmap.md` (forward-looking) are whole-doc exclusions.
 
+## Token renames — MANDATORY
+
+`docs/token-renames.json` is the machine-readable mirror of `docs/migration.md`.
+It is what lets a **theme file** (`*.slashed-theme.json` — the portable,
+name-keyed override snapshot, see `scripts/lib/theme-file.js`) survive a rename:
+`npm run migrate:theme -- <file> --write` rewrites old names, drops removed ones
+with the reason, and never discards an override it does not recognise.
+
+**Any PR that renames or removes a `--sf-*` token must add the corresponding
+entry**, in the same PR as the CSS change:
+
+- **Renamed** → add to `renames` as `"--sf-old": "--sf-new"`. Record the
+  *fully resolved* destination, never an intermediate name: rename targets must
+  be live, so a chain (`a → b → c`) fails the gate by construction.
+- **Removed with no replacement** → add to `removals` with a reason saying what
+  to use instead. A removal without a reason is rejected.
+
+This cannot be generated. `token-registry.json` keeps ids permanent, but
+`check-token-registry.js` deliberately permits renames as *in-place name
+updates on the same id* — so after a rename the old name is simply gone, with
+nothing to look it up by. That is harmless for the share-link codec (it stores
+ids) and fatal for a name-keyed theme file. A rename and a delete+add pair are
+also indistinguishable to a generator, so the map is curated by hand.
+
+```bash
+npm run check:token-renames   # must pass — CI fails if it doesn't
+```
+
+The gate holds the map to three invariants: every rename target is live, no old
+name is still live, and renames and removals are disjoint. Note that "live"
+includes tokens merely *declared* in `core/`/`optional/` CSS — so a leftover
+declaration of a supposedly-renamed token will fail this gate, which is how it
+catches a half-finished rename.
+
 ## Tests
 
 ```bash
diff --git a/configurator/scripts/sync-api.mjs b/configurator/scripts/sync-api.mjs
index c5cf95f9..60529052 100644
--- a/configurator/scripts/sync-api.mjs
+++ b/configurator/scripts/sync-api.mjs
@@ -43,12 +43,14 @@ const SOURCE =
 const ANNOTATIONS_FILE = path.join(FRAMEWORK_ROOT, 'docs', 'token-annotations.json');
 const BUNDLE_CONFIG_FILE = path.join(FRAMEWORK_ROOT, 'bundle.config.json');
 const REGISTRY_FILE = path.join(FRAMEWORK_ROOT, 'token-registry.json');
+const RENAMES_FILE = path.join(FRAMEWORK_ROOT, 'docs', 'token-renames.json');
 
 const OUT_DIR = path.join(CONFIGURATOR_ROOT, 'src', 'data');
 const OUT = path.join(OUT_DIR, 'api-index.generated.json');
 const CLASSES_OUT = path.join(OUT_DIR, 'classes.generated.json');
 const BUNDLES_OUT = path.join(OUT_DIR, 'bundles.generated.json');
 const REGISTRY_OUT = path.join(OUT_DIR, 'token-registry.generated.json');
+const RENAMES_OUT = path.join(OUT_DIR, 'token-renames.generated.json');
 
 // jsDelivr serves the published dist branch (see .github/workflows/publish-dist.yml)
 // at the repo root, so a bundle's minified file is <CDN_BASE>/slashed.<id>.min.css.
@@ -314,6 +316,10 @@ function main() {
   // verbatim so the configurator imports it the same way model.js imports the
   // api-index — and so the runtime can never drift from the committed registry.
   syncRegistry();
+
+  // Rename/removal map for theme-file import (src/lib/themeFile.ts), so an
+  // override set authored against an older SLASHED can be migrated on load.
+  syncRenames();
 }
 
 /**
@@ -348,4 +354,44 @@ function syncRegistry() {
   );
 }
 
+/**
+ * Copy docs/token-renames.json → src/data/token-renames.generated.json, so the
+ * configurator's theme-file import can migrate an old override set without
+ * reaching outside its own package at runtime (the @framework-css alias is
+ * remapped by the WP plugin, so cross-boundary runtime imports are not safe
+ * here — a generated data file is).
+ *
+ * The map's truthfulness is guaranteed upstream by scripts/check-token-renames.js.
+ */
+function syncRenames() {
+  if (!fs.existsSync(RENAMES_FILE)) {
+    console.error(
+      `[configurator:sync] token-renames.json not found at ${RENAMES_FILE}\n` +
+        `It is a hand-maintained mirror of docs/migration.md — it should be committed.`
+    );
+    process.exit(1);
+  }
+  let map;
+  try {
+    map = JSON.parse(fs.readFileSync(RENAMES_FILE, 'utf8'));
+  } catch (err) {
+    console.error(`[configurator:sync] ${RENAMES_FILE} is not valid JSON (${err.message}).`);
+    process.exit(1);
+  }
+  const out = {
+    _sync: {
+      generatedBy: 'configurator/scripts/sync-api.mjs',
+      source: 'docs/token-renames.json',
+    },
+    renames: map.renames ?? {},
+    removals: map.removals ?? {},
+  };
+  fs.writeFileSync(RENAMES_OUT, JSON.stringify(out, null, 2) + '\n', 'utf8');
+  console.log(
+    `[configurator:sync] ${path.relative(FRAMEWORK_ROOT, RENAMES_OUT)} ← ` +
+      `docs/token-renames.json (${Object.keys(out.renames).length} renames, ` +
+      `${Object.keys(out.removals).length} removals)`
+  );
+}
+
 main();
diff --git a/configurator/src/components/DomainPanel.svelte b/configurator/src/components/DomainPanel.svelte
index 89c8b55e..fb7270cb 100644
--- a/configurator/src/components/DomainPanel.svelte
+++ b/configurator/src/components/DomainPanel.svelte
@@ -64,7 +64,7 @@
   {:else if domain === "wcag"}
     <WcagPanel {tokens} {overrides} {onSet} {onBulkChange} />
   {:else if domain === "setup"}
-    <ExportPanel {overrides} />
+    <ExportPanel {overrides} {tokens} {onApplyTheme} />
   {:else if domain === "cheatsheet"}
     <CheatsheetPanel />
   {/if}
diff --git a/configurator/src/components/panels/ExportPanel.svelte b/configurator/src/components/panels/ExportPanel.svelte
index 1d014fbd..1851c829 100644
--- a/configurator/src/components/panels/ExportPanel.svelte
+++ b/configurator/src/components/panels/ExportPanel.svelte
@@ -1,16 +1,61 @@
 <script lang="ts">
-  import { Check, Copy, Download, Link } from '@lucide/svelte';
+  import { Check, Copy, Download, Link, Upload, TriangleAlert } from '@lucide/svelte';
   import { generateCSS, buildShareUrl } from '../../lib/codec';
   import { getShareBaseUrl } from '../../lib/persistence';
+  import { serializeThemeFile, importThemeFile } from '../../lib/themeFile';
+  import type { SlashedToken } from '../../types';
 
-  let { overrides }: {
+  let { overrides, tokens = [], onApplyTheme }: {
     overrides: Record<string, string>;
+    tokens?: SlashedToken[];
+    onApplyTheme?: (overrides: Record<string, string>) => void;
   } = $props();
 
+  // Declared globally in src/vite-env.d.ts, injected by Vite at build time.
+  const frameworkVersion =
+    typeof __SLASHED_VERSION__ !== "undefined" ? __SLASHED_VERSION__ : undefined;
+
   let outputMode = $state<"layer" | "root">("layer");
   let copied = $state(false);
   let copiedLink = $state(false);
 
+  // Theme-file import feedback: what the migration did, or why it refused.
+  let importNotes = $state<string[]>([]);
+  let importErrors = $state<string[]>([]);
+  let fileInput = $state<HTMLInputElement | null>(null);
+
+  let liveTokenNames = $derived(new Set(tokens.map((t) => t.name)));
+
+  function handleDownloadTheme() {
+    const json = serializeThemeFile({ overrides, slashedVersion: frameworkVersion });
+    const blob = new Blob([json], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = "slashed-theme.json";
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+
+  async function handleImportTheme(event: Event) {
+    const input = event.target as HTMLInputElement;
+    const file = input.files?.[0];
+    if (!file) return;
+
+    importNotes = [];
+    importErrors = [];
+
+    const result = await importThemeFile(file, liveTokenNames);
+    if (!result.overrides) {
+      importErrors = result.errors;
+    } else {
+      importNotes = result.notes;
+      onApplyTheme?.(result.overrides);
+    }
+    // Allow re-selecting the same file after a fix.
+    input.value = "";
+  }
+
   let css = $derived(generateCSS(overrides, { mode: outputMode, banner: true }));
   let count = $derived(Object.keys(overrides).length);
 
@@ -139,6 +184,64 @@
     </div>
   </div>
 
+  <!-- Portable theme file: the reviewable, committable form of this override set -->
+  <div class="space-y-2">
+    <div class="text-[10px] font-bold text-slate-500 uppercase tracking-widest">Theme file</div>
+    <p class="text-[10px] text-slate-600 dark:text-slate-400 leading-relaxed">
+      A named, sorted JSON snapshot you can commit next to your CSS and review in a diff.
+      Importing one migrates tokens renamed since it was written.
+    </p>
+
+    <div class="flex gap-2">
+      <button
+        onclick={handleDownloadTheme}
+        disabled={count === 0}
+        class="flex-1 flex items-center justify-center gap-2 py-2 rounded-lg border border-black/8 dark:border-white/8 bg-black/4 dark:bg-white/4 text-[10px] font-bold text-slate-600 dark:text-slate-400 hover:bg-black/8 dark:hover:bg-white/8 hover:text-slate-800 dark:hover:text-slate-200 transition-all cursor-pointer disabled:opacity-40 disabled:cursor-not-allowed"
+      >
+        <Download class="w-3 h-3" />
+        Download .json
+      </button>
+      <button
+        onclick={() => fileInput?.click()}
+        class="flex-1 flex items-center justify-center gap-2 py-2 rounded-lg border border-black/8 dark:border-white/8 bg-black/4 dark:bg-white/4 text-[10px] font-bold text-slate-600 dark:text-slate-400 hover:bg-black/8 dark:hover:bg-white/8 hover:text-slate-800 dark:hover:text-slate-200 transition-all cursor-pointer"
+      >
+        <Upload class="w-3 h-3" />
+        Import…
+      </button>
+    </div>
+
+    <input
+      bind:this={fileInput}
+      type="file"
+      accept="application/json,.json"
+      onchange={handleImportTheme}
+      class="hidden"
+    />
+
+    {#if importErrors.length}
+      <div class="rounded-lg bg-red-500/8 border border-red-500/20 p-3 space-y-1">
+        <div class="flex items-center gap-1.5 text-[10px] font-bold text-red-700 dark:text-red-300">
+          <TriangleAlert class="w-3 h-3" />
+          Import refused — nothing was changed
+        </div>
+        {#each importErrors as err}
+          <div class="text-[10px] text-red-700/80 dark:text-red-300/80 leading-relaxed font-mono">{err}</div>
+        {/each}
+      </div>
+    {/if}
+
+    {#if importNotes.length}
+      <div class="rounded-lg bg-amber-500/8 border border-amber-500/20 p-3 space-y-1">
+        <div class="text-[10px] font-bold text-amber-700 dark:text-amber-300">
+          Imported with {importNotes.length} adjustment{importNotes.length !== 1 ? "s" : ""}
+        </div>
+        {#each importNotes as note}
+          <div class="text-[10px] text-amber-700/80 dark:text-amber-300/80 leading-relaxed font-mono">{note}</div>
+        {/each}
+      </div>
+    {/if}
+  </div>
+
   <!-- W3C Design Tokens export -->
   <button
     onclick={handleDownloadW3C}
diff --git a/configurator/src/data/token-renames.generated.json b/configurator/src/data/token-renames.generated.json
new file mode 100644
index 00000000..5bb14446
--- /dev/null
+++ b/configurator/src/data/token-renames.generated.json
@@ -0,0 +1,86 @@
+{
+  "_sync": {
+    "generatedBy": "configurator/scripts/sync-api.mjs",
+    "source": "docs/token-renames.json"
+  },
+  "renames": {
+    "--sf-color-primary-light": "--sf-color-primary-source-light",
+    "--sf-color-primary-dark": "--sf-color-primary-source-dark",
+    "--sf-color-secondary-light": "--sf-color-secondary-source-light",
+    "--sf-color-secondary-dark": "--sf-color-secondary-source-dark",
+    "--sf-color-tertiary-light": "--sf-color-tertiary-source-light",
+    "--sf-color-tertiary-dark": "--sf-color-tertiary-source-dark",
+    "--sf-color-action-light": "--sf-color-action-source-light",
+    "--sf-color-action-dark": "--sf-color-action-source-dark",
+    "--sf-color-neutral-light": "--sf-color-neutral-source-light",
+    "--sf-color-neutral-dark": "--sf-color-neutral-source-dark",
+    "--sf-color-base-light": "--sf-color-base-source-light",
+    "--sf-color-base-dark": "--sf-color-base-source-dark",
+    "--sf-color-success-light": "--sf-color-success-source-light",
+    "--sf-color-success-dark": "--sf-color-success-source-dark",
+    "--sf-color-warning-light": "--sf-color-warning-source-light",
+    "--sf-color-warning-dark": "--sf-color-warning-source-dark",
+    "--sf-color-info-light": "--sf-color-info-source-light",
+    "--sf-color-info-dark": "--sf-color-info-source-dark",
+    "--sf-color-danger-light": "--sf-color-danger-source-light",
+    "--sf-color-danger-dark": "--sf-color-danger-source-dark",
+    "--sf-color-error": "--sf-color-danger",
+    "--sf-color-error-subtle": "--sf-color-danger-subtle",
+    "--sf-color-error-muted": "--sf-color-danger-muted",
+    "--sf-color-error-strong": "--sf-color-danger-strong",
+    "--sf-color-error-source-light": "--sf-color-danger-source-light",
+    "--sf-color-error-source-dark": "--sf-color-danger-source-dark",
+    "--sf-color-primary-ghost": "--sf-color-primary-tint",
+    "--sf-color-secondary-ghost": "--sf-color-secondary-tint",
+    "--sf-color-tertiary-ghost": "--sf-color-tertiary-tint",
+    "--sf-color-action-ghost": "--sf-color-action-tint",
+    "--sf-color-neutral-ghost": "--sf-color-neutral-tint",
+    "--sf-color-base-ghost": "--sf-color-base-tint",
+    "--sf-color-base-superlight": "--sf-color-base-50",
+    "--sf-color-base-xlight": "--sf-color-base-200",
+    "--sf-color-base-lighter": "--sf-color-base-400",
+    "--sf-color-base-darker": "--sf-color-base-600",
+    "--sf-color-base-xdark": "--sf-color-base-800",
+    "--sf-color-base-superdark": "--sf-color-base-950",
+    "--sf-color-text--on-surface": "--sf-color-text--on-base",
+    "--sf-color-text--secondary": "--sf-color-text--subtle",
+    "--sf-z-low": "--sf-z-sticky",
+    "--sf-z-mid": "--sf-z-fixed",
+    "--sf-z-high": "--sf-z-dropdown",
+    "--sf-z-top": "--sf-z-toast",
+    "--sf-avatar-size": "--sf-card-avatar-size"
+  },
+  "removals": {
+    "--sf-z-max": "Ambiguous by design: 0.6.0 split the old top rung into --sf-z-overlay (1030) and --sf-z-modal (1040). Pick the one matching your element's role — this is not auto-migrated because the wrong choice silently reorders your stacking context.",
+    "--sf-blur-xs": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-s": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-m": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-l": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-xl": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-opacity-0": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-10": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-25": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-50": "Removed in 0.6.0 — use --sf-opacity-muted (0.5), or a literal value.",
+    "--sf-opacity-75": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-100": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-stroke-thin": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-regular": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-bold": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-heavy": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-col-width-s": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-width-m": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-width-l": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-rule-width-s": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-col-rule-width-m": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-col-rule-width-l": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-font-weight-thin": "Removed in 0.6.0 — write font-weight: 100 inline, or re-tune a role token (--sf-font-weight-{body,heading,display,interactive,strong}).",
+    "--sf-font-weight-extralight": "Removed in 0.6.0 — write font-weight: 200 inline, or re-tune a role token.",
+    "--sf-font-weight-extrabold": "Removed in 0.6.0 — write font-weight: 800 inline, or re-tune a role token.",
+    "--sf-font-weight-black": "Removed in 0.6.0 — write font-weight: 900 inline, or re-tune a role token.",
+    "--sf-fluid-custom-1": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-fluid-custom-2": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-fluid-custom-3": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-truncate-suffix": "Removed in 0.6.0 — it was never read. .sf-truncate uses text-overflow: ellipsis.",
+    "--sf-corner-scoop-size": "Removed before 1.0 together with the .sf-corner-scoop macro (issue #484): a single absolute size needed per-element tuning to read well at both button and hero scale, and the mask clipped box-shadow/border."
+  }
+}
diff --git a/configurator/src/lib/themeFile.ts b/configurator/src/lib/themeFile.ts
new file mode 100644
index 00000000..ebcc4b3e
--- /dev/null
+++ b/configurator/src/lib/themeFile.ts
@@ -0,0 +1,199 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Theme-file import/export for the configurator.
+ *
+ * A theme file is the third persistence form, alongside localStorage
+ * (savedThemes.ts) and the share link (codec.ts). Unlike those two it is a
+ * FILE: keyed by token name, sorted, pretty-printed — something you commit next
+ * to the CSS it themes and review in a pull request.
+ *
+ * This is a browser-side mirror of scripts/lib/theme-file.js. The two are kept
+ * honest by tests/themeFile.test.ts, which runs both implementations over the
+ * same fixtures and asserts identical results. A runtime import of the Node
+ * module is deliberately avoided: the `@framework-css` alias is remapped by the
+ * WordPress plugin to a vendored dist/ that has no scripts/, so reaching
+ * outside this package at runtime would break that build.
+ */
+import RENAME_MAP from "../data/token-renames.generated.json";
+
+export const THEME_SCHEMA_VERSION = 1;
+export const THEME_SCHEMA_URL = "https://slashed.codeslash.dev/schema/theme/v1.json";
+
+const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
+const UNSAFE_VALUE_RE = /[;{}]|\/\*|\*\//;
+
+export interface ThemeFile {
+  schemaVersion: number;
+  slashedVersion: string | null;
+  name: string | null;
+  overrides: Record<string, string>;
+}
+
+export interface MigrationReport {
+  overrides: Record<string, string>;
+  renamed: Array<{ from: string; to: string }>;
+  removed: Array<{ name: string; reason: string }>;
+  unknown: string[];
+  collisions: Array<{ from: string; to: string; kept: string }>;
+}
+
+const renames: Record<string, string> = (RENAME_MAP as any).renames ?? {};
+const removals: Record<string, string> = (RENAME_MAP as any).removals ?? {};
+
+/** Sort an object's keys — stable, diff-friendly output. */
+export function sortKeys(obj: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const key of Object.keys(obj).sort()) out[key] = obj[key];
+  return out;
+}
+
+export function validateThemeFile(raw: unknown): { theme: ThemeFile | null; errors: string[] } {
+  const errors: string[] = [];
+  const fail = (msg: string) => {
+    errors.push(msg);
+    return { theme: null, errors };
+  };
+
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return fail("theme file must be a JSON object.");
+  }
+
+  const { schemaVersion, overrides, name, slashedVersion } = raw as any;
+
+  if (!Number.isInteger(schemaVersion)) return fail("`schemaVersion` is missing or not an integer.");
+  if (schemaVersion < 1) return fail(`\`schemaVersion\` must be >= 1 (got ${schemaVersion}).`);
+  if (schemaVersion > THEME_SCHEMA_VERSION) {
+    return fail(
+      `\`schemaVersion\` ${schemaVersion} is newer than this SLASHED understands ` +
+        `(max ${THEME_SCHEMA_VERSION}). Upgrade SLASHED to read this file.`,
+    );
+  }
+
+  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) {
+    return fail("`overrides` is missing or not an object.");
+  }
+  if (name != null && typeof name !== "string") errors.push("`name` must be a string when present.");
+  if (slashedVersion != null && typeof slashedVersion !== "string") {
+    errors.push("`slashedVersion` must be a string when present.");
+  }
+
+  const clean: Record<string, string> = {};
+  for (const [key, value] of Object.entries(overrides as Record<string, unknown>)) {
+    if (!TOKEN_NAME_RE.test(key)) {
+      errors.push(`overrides["${key}"]: not a well-formed --sf-* token name.`);
+      continue;
+    }
+    if (typeof value !== "string") {
+      errors.push(`overrides["${key}"]: value must be a string (got ${typeof value}).`);
+      continue;
+    }
+    if (UNSAFE_VALUE_RE.test(value)) {
+      errors.push(`overrides["${key}"]: value contains CSS-breaking characters (; { } or comment markers).`);
+      continue;
+    }
+    clean[key] = value.trim();
+  }
+
+  if (errors.length) return { theme: null, errors };
+
+  return {
+    theme: {
+      schemaVersion,
+      slashedVersion: typeof slashedVersion === "string" ? slashedVersion : null,
+      name: typeof name === "string" ? name : null,
+      overrides: clean,
+    },
+    errors: [],
+  };
+}
+
+export function parseThemeFile(text: string): { theme: ThemeFile | null; errors: string[] } {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err: any) {
+    return { theme: null, errors: [`not valid JSON (${err.message}).`] };
+  }
+  return validateThemeFile(raw);
+}
+
+/**
+ * Migrate an override set onto the current token API. Never discards an
+ * override it does not recognise — unknown names are reported and kept.
+ */
+export function migrateOverrides(
+  overrides: Record<string, string>,
+  opts: { live?: Set<string> } = {},
+): MigrationReport {
+  const out: Record<string, string> = {};
+  const renamed: MigrationReport["renamed"] = [];
+  const removed: MigrationReport["removed"] = [];
+  const unknown: string[] = [];
+  const collisions: MigrationReport["collisions"] = [];
+
+  for (const key of Object.keys(overrides).sort()) {
+    const value = overrides[key];
+
+    if (Object.prototype.hasOwnProperty.call(removals, key)) {
+      removed.push({ name: key, reason: removals[key] });
+      continue;
+    }
+
+    const target = renames[key];
+    if (target) {
+      if (Object.prototype.hasOwnProperty.call(overrides, target)) {
+        collisions.push({ from: key, to: target, kept: overrides[target] });
+        continue;
+      }
+      out[target] = value;
+      renamed.push({ from: key, to: target });
+      continue;
+    }
+
+    if (opts.live && !opts.live.has(key)) unknown.push(key);
+    out[key] = value;
+  }
+
+  return { overrides: sortKeys(out), renamed, removed, unknown, collisions };
+}
+
+export function serializeThemeFile(theme: {
+  overrides: Record<string, string>;
+  name?: string;
+  slashedVersion?: string;
+}): string {
+  const doc = {
+    $schema: THEME_SCHEMA_URL,
+    schemaVersion: THEME_SCHEMA_VERSION,
+    ...(theme.slashedVersion ? { slashedVersion: theme.slashedVersion } : {}),
+    ...(theme.name ? { name: theme.name } : {}),
+    overrides: sortKeys(theme.overrides ?? {}),
+  };
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+/**
+ * Read a user-selected file and return the migrated override set plus a
+ * human-readable summary of what changed on the way in.
+ */
+export async function importThemeFile(
+  file: File,
+  live?: Set<string>,
+): Promise<{ overrides: Record<string, string> | null; name: string | null; errors: string[]; notes: string[] }> {
+  const text = await file.text();
+  const { theme, errors } = parseThemeFile(text);
+  if (!theme) return { overrides: null, name: null, errors, notes: [] };
+
+  const result = migrateOverrides(theme.overrides, { live });
+  const notes: string[] = [];
+  for (const { from, to } of result.renamed) notes.push(`renamed ${from} → ${to}`);
+  for (const { from, to } of result.collisions) notes.push(`dropped ${from} (${to} already set)`);
+  for (const { name, reason } of result.removed) notes.push(`removed ${name} — ${reason}`);
+  for (const name of result.unknown) notes.push(`unknown ${name} (kept)`);
+
+  return { overrides: result.overrides, name: theme.name, errors: [], notes };
+}
diff --git a/configurator/tests/themeFile.test.ts b/configurator/tests/themeFile.test.ts
new file mode 100644
index 00000000..a6520374
--- /dev/null
+++ b/configurator/tests/themeFile.test.ts
@@ -0,0 +1,133 @@
+/**
+ * Theme-file import/export, plus the parity contract with the framework's
+ * Node implementation.
+ *
+ * src/lib/themeFile.ts and scripts/lib/theme-file.js are two implementations of
+ * one format. They exist separately on purpose (the configurator cannot import
+ * across the package boundary at runtime — see the header of themeFile.ts), so
+ * the drift risk is real and has to be tested rather than commented about.
+ *
+ * Vitest runs in Node, so this test — unlike the shipped bundle — CAN import
+ * both and run them over the same fixtures.
+ */
+import { describe, test, expect } from "vitest";
+import {
+  THEME_SCHEMA_VERSION,
+  parseThemeFile,
+  migrateOverrides,
+  serializeThemeFile,
+  validateThemeFile,
+} from "../src/lib/themeFile";
+import * as node from "../../scripts/lib/theme-file.js";
+import renameMap from "../src/data/token-renames.generated.json";
+
+/** The rename map as the Node implementation takes it (it is passed explicitly there). */
+const nodeOpts = {
+  renames: (renameMap as any).renames,
+  removals: (renameMap as any).removals,
+};
+
+const FIXTURES: Array<{ label: string; raw: unknown }> = [
+  {
+    label: "well-formed minimal",
+    raw: { schemaVersion: 1, overrides: { "--sf-color-primary-source-light": "#3b5bdb" } },
+  },
+  {
+    label: "legacy names needing migration",
+    raw: {
+      schemaVersion: 1,
+      slashedVersion: "0.6.10",
+      name: "Acme",
+      overrides: {
+        "--sf-color-primary-light": "#3b5bdb",
+        "--sf-color-error": "#e03131",
+        "--sf-opacity-25": "0.25",
+        "--sf-radius-m": "10px",
+      },
+    },
+  },
+  { label: "not an object", raw: "nope" },
+  { label: "missing schemaVersion", raw: { overrides: {} } },
+  { label: "future schemaVersion", raw: { schemaVersion: 99, overrides: {} } },
+  { label: "bad token name", raw: { schemaVersion: 1, overrides: { "color-primary": "red" } } },
+  {
+    label: "CSS-breaking value",
+    raw: { schemaVersion: 1, overrides: { "--sf-color-primary": "red; background: url(x)" } },
+  },
+  { label: "non-string value", raw: { schemaVersion: 1, overrides: { "--sf-radius-m": 10 } } },
+];
+
+describe("parity with scripts/lib/theme-file.js", () => {
+  test("the schema version matches", () => {
+    expect(THEME_SCHEMA_VERSION).toBe(node.THEME_SCHEMA_VERSION);
+  });
+
+  test.each(FIXTURES)("validate agrees on: $label", ({ raw }) => {
+    const mine = validateThemeFile(raw);
+    const theirs = node.validateThemeFile(raw);
+    expect(mine.theme).toEqual(theirs.theme);
+    expect(mine.errors).toEqual(theirs.errors);
+  });
+
+  test.each(FIXTURES)("migrate agrees on: $label", ({ raw }) => {
+    const mine = validateThemeFile(raw);
+    if (!mine.theme) return; // invalid fixtures are covered by the validate test
+    const live = new Set(["--sf-radius-m", "--sf-color-primary-source-light"]);
+    expect(migrateOverrides(mine.theme.overrides, { live })).toEqual(
+      node.migrateOverrides(mine.theme.overrides, { ...nodeOpts, live }),
+    );
+  });
+
+  test("serialize produces byte-identical output", () => {
+    const args = {
+      overrides: { "--sf-b": "2", "--sf-a": "1" },
+      name: "Acme",
+      slashedVersion: "0.7.31",
+    };
+    expect(serializeThemeFile(args)).toBe(node.serializeThemeFile(args));
+  });
+});
+
+describe("theme file round-trip", () => {
+  test("serialize → parse preserves the override set", () => {
+    const overrides = { "--sf-color-primary-source-light": "#3b5bdb", "--sf-radius-m": "10px" };
+    const { theme, errors } = parseThemeFile(serializeThemeFile({ overrides, name: "Acme" }));
+    expect(errors).toEqual([]);
+    expect(theme?.overrides).toEqual(overrides);
+    expect(theme?.name).toBe("Acme");
+  });
+
+  test("output is key-order independent", () => {
+    const a = serializeThemeFile({ overrides: { "--sf-b": "2", "--sf-a": "1" } });
+    const b = serializeThemeFile({ overrides: { "--sf-a": "1", "--sf-b": "2" } });
+    expect(a).toBe(b);
+  });
+});
+
+describe("migration on import", () => {
+  test("rewrites renamed tokens using the synced map", () => {
+    const r = migrateOverrides({ "--sf-color-error": "#e03131" });
+    expect(r.overrides).toEqual({ "--sf-color-danger": "#e03131" });
+    expect(r.renamed).toEqual([{ from: "--sf-color-error", to: "--sf-color-danger" }]);
+  });
+
+  test("drops removed tokens with a reason", () => {
+    const r = migrateOverrides({ "--sf-opacity-25": "0.25" });
+    expect(r.overrides).toEqual({});
+    expect(r.removed[0].name).toBe("--sf-opacity-25");
+    expect(r.removed[0].reason).toBeTruthy();
+  });
+
+  test("keeps an unknown token rather than discarding user data", () => {
+    const r = migrateOverrides({ "--sf-mystery": "1rem" }, { live: new Set(["--sf-radius-m"]) });
+    expect(r.overrides).toEqual({ "--sf-mystery": "1rem" });
+    expect(r.unknown).toEqual(["--sf-mystery"]);
+  });
+
+  test("is idempotent", () => {
+    const once = migrateOverrides({ "--sf-color-error": "#e03131" });
+    const twice = migrateOverrides(once.overrides);
+    expect(twice.overrides).toEqual(once.overrides);
+    expect(twice.renamed).toEqual([]);
+  });
+});
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 2f8be674..2e8b254e 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -125,6 +125,44 @@ whole dark palette derive from those six. Prefer to design visually? Open the
 [configurator](https://slashed.codeslash.dev/configurator/) and export the
 override CSS.
 
+### Keeping a theme as a file
+
+Alongside the override CSS, the configurator exports a **theme file** —
+`slashed-theme.json`, a sorted, name-keyed snapshot of your overrides:
+
+```json
+{
+  "$schema": "https://slashed.codeslash.dev/schema/theme/v1.json",
+  "schemaVersion": 1,
+  "slashedVersion": "0.7.31",
+  "name": "Acme Corp",
+  "overrides": {
+    "--sf-color-primary-source-light": "#3b5bdb"
+  }
+}
+```
+
+Unlike a share link (compressed, opaque) this is meant to be committed next to
+the CSS it themes: a `git diff` shows exactly which token changed value, so a
+rebrand is reviewable in a pull request. Import it back into the configurator at
+any time.
+
+When you upgrade SLASHED, a theme file written against an older version is
+migrated onto the current token names **on import** — just load it in the
+configurator and it is brought forward automatically. Renamed tokens are
+rewritten, removed ones are dropped with an explanation of what to use instead,
+and anything unrecognised is reported but left untouched: the migration never
+silently discards your data. The panel lists every adjustment it made.
+
+Working inside a clone of this repository, the same migration is available as a
+CLI, which is useful for migrating committed theme files in bulk or as a CI
+check (it exits non-zero when a file needs migrating):
+
+```bash
+npm run migrate:theme -- acme.slashed-theme.json          # report what would change
+npm run migrate:theme -- acme.slashed-theme.json --write  # apply
+```
+
 ---
 
 ## 6. The one rule that matters
diff --git a/docs/token-renames.json b/docs/token-renames.json
new file mode 100644
index 00000000..dd4da16f
--- /dev/null
+++ b/docs/token-renames.json
@@ -0,0 +1,109 @@
+{
+  "_meta": {
+    "purpose": "Machine-readable map of token names that changed or disappeared, so a theme file authored against an older SLASHED can be migrated forward automatically.",
+    "sourceOfTruth": "docs/migration.md — this file is its machine-readable mirror. Every entry here corresponds to a documented breaking change; do not add an entry that migration.md does not describe.",
+    "whyNotTheRegistry": "token-registry.json cannot answer this. Its ids are permanent, but check-token-registry.js explicitly permits renames as IN-PLACE name updates on the same id — so after a rename the old name is simply gone from the registry, with nothing to look it up by. That is harmless for the share-link codec (it stores ids, not names) but fatal for a name-keyed theme file. Renames are a human fact and cannot be derived from the catalogue: a rename and a (delete + add) pair are indistinguishable to a generator.",
+    "contract": "Every value in `renames` must be a LIVE token, and no key in `renames` or `removals` may be live. Enforced by scripts/check-token-renames.js. Because a rename target must be live, chains are impossible by construction — always record the fully resolved destination, never an intermediate name.",
+    "consumedBy": [
+      "scripts/migrate-theme.js",
+      "scripts/lib/theme-file.js",
+      "configurator (via configurator/src/data/token-renames.generated.json)"
+    ]
+  },
+
+  "renames": {
+    "--sf-color-primary-light": "--sf-color-primary-source-light",
+    "--sf-color-primary-dark": "--sf-color-primary-source-dark",
+    "--sf-color-secondary-light": "--sf-color-secondary-source-light",
+    "--sf-color-secondary-dark": "--sf-color-secondary-source-dark",
+    "--sf-color-tertiary-light": "--sf-color-tertiary-source-light",
+    "--sf-color-tertiary-dark": "--sf-color-tertiary-source-dark",
+    "--sf-color-action-light": "--sf-color-action-source-light",
+    "--sf-color-action-dark": "--sf-color-action-source-dark",
+    "--sf-color-neutral-light": "--sf-color-neutral-source-light",
+    "--sf-color-neutral-dark": "--sf-color-neutral-source-dark",
+    "--sf-color-base-light": "--sf-color-base-source-light",
+    "--sf-color-base-dark": "--sf-color-base-source-dark",
+    "--sf-color-success-light": "--sf-color-success-source-light",
+    "--sf-color-success-dark": "--sf-color-success-source-dark",
+    "--sf-color-warning-light": "--sf-color-warning-source-light",
+    "--sf-color-warning-dark": "--sf-color-warning-source-dark",
+    "--sf-color-info-light": "--sf-color-info-source-light",
+    "--sf-color-info-dark": "--sf-color-info-source-dark",
+    "--sf-color-danger-light": "--sf-color-danger-source-light",
+    "--sf-color-danger-dark": "--sf-color-danger-source-dark",
+
+    "--sf-color-error": "--sf-color-danger",
+    "--sf-color-error-subtle": "--sf-color-danger-subtle",
+    "--sf-color-error-muted": "--sf-color-danger-muted",
+    "--sf-color-error-strong": "--sf-color-danger-strong",
+    "--sf-color-error-source-light": "--sf-color-danger-source-light",
+    "--sf-color-error-source-dark": "--sf-color-danger-source-dark",
+
+    "--sf-color-primary-ghost": "--sf-color-primary-tint",
+    "--sf-color-secondary-ghost": "--sf-color-secondary-tint",
+    "--sf-color-tertiary-ghost": "--sf-color-tertiary-tint",
+    "--sf-color-action-ghost": "--sf-color-action-tint",
+    "--sf-color-neutral-ghost": "--sf-color-neutral-tint",
+    "--sf-color-base-ghost": "--sf-color-base-tint",
+
+    "--sf-color-base-superlight": "--sf-color-base-50",
+    "--sf-color-base-xlight": "--sf-color-base-200",
+    "--sf-color-base-lighter": "--sf-color-base-400",
+    "--sf-color-base-darker": "--sf-color-base-600",
+    "--sf-color-base-xdark": "--sf-color-base-800",
+    "--sf-color-base-superdark": "--sf-color-base-950",
+
+    "--sf-color-text--on-surface": "--sf-color-text--on-base",
+    "--sf-color-text--secondary": "--sf-color-text--subtle",
+
+    "--sf-z-low": "--sf-z-sticky",
+    "--sf-z-mid": "--sf-z-fixed",
+    "--sf-z-high": "--sf-z-dropdown",
+    "--sf-z-top": "--sf-z-toast",
+
+    "--sf-avatar-size": "--sf-card-avatar-size"
+  },
+
+  "removals": {
+    "--sf-z-max": "Ambiguous by design: 0.6.0 split the old top rung into --sf-z-overlay (1030) and --sf-z-modal (1040). Pick the one matching your element's role — this is not auto-migrated because the wrong choice silently reorders your stacking context.",
+
+    "--sf-blur-xs": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-s": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-m": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-l": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+    "--sf-blur-xl": "Removed in 0.6.0 — use --sf-blur (single default) or an inline blur(Npx).",
+
+    "--sf-opacity-0": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-10": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-25": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-50": "Removed in 0.6.0 — use --sf-opacity-muted (0.5), or a literal value.",
+    "--sf-opacity-75": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+    "--sf-opacity-100": "Removed in 0.6.0 — use --sf-opacity-muted / --sf-opacity-disabled, or a literal value.",
+
+    "--sf-stroke-thin": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-regular": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-bold": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+    "--sf-stroke-heavy": "Removed in 0.6.0 — use an SVG stroke-width=\"N\" attribute or a --sf-border-width-* token.",
+
+    "--sf-col-width-s": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-width-m": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-width-l": "Removed in 0.6.0 — set the column-width property directly.",
+    "--sf-col-rule-width-s": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-col-rule-width-m": "Removed in 0.6.0 — set the column-rule-width property directly.",
+    "--sf-col-rule-width-l": "Removed in 0.6.0 — set the column-rule-width property directly.",
+
+    "--sf-font-weight-thin": "Removed in 0.6.0 — write font-weight: 100 inline, or re-tune a role token (--sf-font-weight-{body,heading,display,interactive,strong}).",
+    "--sf-font-weight-extralight": "Removed in 0.6.0 — write font-weight: 200 inline, or re-tune a role token.",
+    "--sf-font-weight-extrabold": "Removed in 0.6.0 — write font-weight: 800 inline, or re-tune a role token.",
+    "--sf-font-weight-black": "Removed in 0.6.0 — write font-weight: 900 inline, or re-tune a role token.",
+
+    "--sf-fluid-custom-1": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-fluid-custom-2": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+    "--sf-fluid-custom-3": "Removed in 0.6.0 — write a clamp() directly. --sf-fluid-min-vw / --sf-fluid-max-vw are unchanged.",
+
+    "--sf-truncate-suffix": "Removed in 0.6.0 — it was never read. .sf-truncate uses text-overflow: ellipsis.",
+
+    "--sf-corner-scoop-size": "Removed before 1.0 together with the .sf-corner-scoop macro (issue #484): a single absolute size needed per-element tuning to read well at both button and hero scale, and the mask clipped box-shadow/border."
+  }
+}
diff --git a/package.json b/package.json
index 7a8698ef..d207f074 100644
--- a/package.json
+++ b/package.json
@@ -49,6 +49,8 @@
     "check:mirrors": "node scripts/check-mirrors.js",
     "check:bundle-defs": "node scripts/check-bundle-defs.js",
     "check:forbidden-strings": "node scripts/check-forbidden-strings.js --check",
+    "check:token-renames": "node scripts/check-token-renames.js",
+    "migrate:theme": "node scripts/migrate-theme.js",
     "configurator:sync": "node configurator/scripts/sync-api.mjs",
     "docs:tokens": "node scripts/gen-token-reference.js",
     "docs:index": "node scripts/gen-token-index.js",
diff --git a/scripts/artifacts.json b/scripts/artifacts.json
index 8bbd936f..462318b5 100644
--- a/scripts/artifacts.json
+++ b/scripts/artifacts.json
@@ -16,18 +16,20 @@
       "configurator/src/data/api-index.generated.json",
       "configurator/src/data/classes.generated.json",
       "configurator/src/data/bundles.generated.json",
-      "configurator/src/data/token-registry.generated.json"
+      "configurator/src/data/token-registry.generated.json",
+      "configurator/src/data/token-renames.generated.json"
     ]
   },
   {
     "name": "configurator api sync",
-    "srcPrefixes": ["docs/token-annotations.json", "docs/api-index.json", "bundle.config.json", "token-registry.json"],
+    "srcPrefixes": ["docs/token-annotations.json", "docs/api-index.json", "bundle.config.json", "token-registry.json", "docs/token-renames.json"],
     "buildCmd": "npm run configurator:sync",
     "outputs": [
       "configurator/src/data/api-index.generated.json",
       "configurator/src/data/classes.generated.json",
       "configurator/src/data/bundles.generated.json",
-      "configurator/src/data/token-registry.generated.json"
+      "configurator/src/data/token-registry.generated.json",
+      "configurator/src/data/token-renames.generated.json"
     ]
   }
 ]
diff --git a/scripts/check-token-renames.js b/scripts/check-token-renames.js
new file mode 100644
index 00000000..e9ae0338
--- /dev/null
+++ b/scripts/check-token-renames.js
@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * CI gate for docs/token-renames.json — the map that lets an old theme file be
+ * migrated onto the current token set.
+ *
+ * A rename map is only useful if it is TRUE, and it decays silently: a target
+ * token that is later renamed again turns the map into a machine that migrates
+ * users onto a dead name. This gate holds three invariants:
+ *
+ *   1. Every rename TARGET is live. This is what makes the map trustworthy —
+ *      and it forbids chains by construction: if `a → b` and `b → c` were both
+ *      recorded, `b` would be a rename key and therefore not live, so the gate
+ *      fires. Always record the fully resolved destination.
+ *   2. No rename KEY is live. A live old name means the rename never happened,
+ *      was reverted, or the name was recycled for something new — in every case
+ *      migrating away from it would corrupt a working theme.
+ *   3. No removal KEY is live, and removals and renames are disjoint. A token
+ *      cannot be both "gone, here's advice" and "silently rewritten".
+ *
+ * "Live" comes from scripts/lib/live-api.js — the same definition
+ * check-doc-refs.js and check-llm-guide.js use, so all three gates agree on
+ * what the current API is.
+ *
+ * Run:
+ *   node scripts/check-token-renames.js
+ *   npm run check:token-renames
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveTokens } from './lib/live-api.js';
+
+const slashedRoot = process.env.SLASHED_ROOT?.trim();
+const ROOT = slashedRoot
+  ? path.resolve(slashedRoot)
+  : path.resolve(import.meta.dirname, '..');
+
+const MAP_FILE = path.join(ROOT, 'docs', 'token-renames.json');
+
+if (!fs.existsSync(MAP_FILE)) {
+  console.error(`check:token-renames FAILED: ${MAP_FILE} not found.`);
+  process.exit(1);
+}
+
+let map;
+try {
+  map = JSON.parse(fs.readFileSync(MAP_FILE, 'utf8'));
+} catch (err) {
+  console.error(`check:token-renames FAILED: docs/token-renames.json is not valid JSON (${err.message}).`);
+  process.exit(1);
+}
+
+const renames = map.renames ?? {};
+const removals = map.removals ?? {};
+const errors = [];
+
+const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
+
+// Shape checks first — a malformed entry would otherwise produce a confusing
+// "not live" error for a name that was never well-formed.
+for (const [from, to] of Object.entries(renames)) {
+  if (!TOKEN_NAME_RE.test(from)) errors.push(`rename key "${from}" is not a well-formed --sf-* token name.`);
+  if (typeof to !== 'string' || !TOKEN_NAME_RE.test(to)) {
+    errors.push(`rename target for "${from}" ("${to}") is not a well-formed --sf-* token name.`);
+  }
+  if (from === to) errors.push(`rename "${from}" maps to itself.`);
+}
+for (const [name, reason] of Object.entries(removals)) {
+  if (!TOKEN_NAME_RE.test(name)) errors.push(`removal key "${name}" is not a well-formed --sf-* token name.`);
+  if (typeof reason !== 'string' || reason.trim() === '') {
+    errors.push(`removal "${name}" has no reason — every removal must say what to use instead.`);
+  }
+}
+
+// ── 3 (part): renames and removals must be disjoint ──────────────────────────
+for (const name of Object.keys(removals)) {
+  if (Object.prototype.hasOwnProperty.call(renames, name)) {
+    errors.push(
+      `"${name}" appears in BOTH renames and removals — it cannot be silently rewritten and manually resolved at the same time.`,
+    );
+  }
+}
+
+const live = buildLiveTokens(ROOT);
+
+// ── 1: every rename target is live (and, by consequence, no chains) ──────────
+for (const [from, to] of Object.entries(renames)) {
+  if (typeof to !== 'string' || !live.has(to)) {
+    const chained = Object.prototype.hasOwnProperty.call(renames, to);
+    errors.push(
+      chained
+        ? `rename "${from}" → "${to}" points at another rename key — record the fully resolved destination (${renames[to]}) instead of a chain.`
+        : `rename "${from}" → "${to}" points at a token that is not live. If "${to}" was itself renamed, re-point this entry at its current name.`,
+    );
+  }
+}
+
+// ── 2: no rename key is live ─────────────────────────────────────────────────
+for (const from of Object.keys(renames)) {
+  if (live.has(from)) {
+    errors.push(
+      `rename key "${from}" is still LIVE — migrating away from a token that exists would break a working theme. Drop the entry, or finish the rename in the CSS.`,
+    );
+  }
+}
+
+// ── 3: no removal key is live ────────────────────────────────────────────────
+for (const name of Object.keys(removals)) {
+  if (live.has(name)) {
+    errors.push(
+      `removal "${name}" is still LIVE — a token that exists must not be reported to users as removed.`,
+    );
+  }
+}
+
+if (errors.length) {
+  console.error('check:token-renames FAILED:');
+  for (const e of errors) console.error(`  - ${e}`);
+  console.error('\ndocs/token-renames.json is the machine-readable mirror of docs/migration.md.');
+  console.error('Every rename target must be a live token; no old name may still be live.');
+  process.exit(1);
+}
+
+console.log(
+  `check:token-renames OK — ${Object.keys(renames).length} rename(s), ` +
+    `${Object.keys(removals).length} removal(s), all resolved against the live token set.`,
+);
diff --git a/scripts/lib/theme-file.js b/scripts/lib/theme-file.js
new file mode 100644
index 00000000..15dc2439
--- /dev/null
+++ b/scripts/lib/theme-file.js
@@ -0,0 +1,215 @@
+/**
+ * The SLASHED theme file — a portable, reviewable snapshot of a token override
+ * set.
+ *
+ * The configurator could already persist overrides two ways, and neither is a
+ * file you can put in a repository:
+ *
+ *   - localStorage (savedThemes.ts) — trapped in one browser profile.
+ *   - the share link (codec.ts) — a compressed base64url blob. Ideal for its
+ *     job (a short URL), useless for review: it is opaque in a diff, and it is
+ *     keyed by numeric token id.
+ *
+ * A theme file is keyed by token NAME and pretty-printed with sorted keys, so
+ * `git diff` shows `--sf-color-primary-source-light` changing value, which is
+ * the whole point. It is the artifact you hand a client, commit next to the
+ * CSS it themes, or review in a pull request.
+ *
+ * Consumed by scripts/migrate-theme.js and (mirrored through
+ * configurator/src/data/) by the configurator's import/export.
+ */
+
+/**
+ * Bumped only when the file SHAPE changes (a new/renamed/removed field), never
+ * when the token set changes — token drift is handled by migrateOverrides()
+ * against docs/token-renames.json, which is versionless by design.
+ */
+export const THEME_SCHEMA_VERSION = 1;
+
+export const THEME_SCHEMA_URL = 'https://slashed.codeslash.dev/schema/theme/v1.json';
+
+/** Well-formed `--sf-*` custom property name. */
+const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
+
+/**
+ * Characters that would let a value break out of the `--token: value;`
+ * declaration it is written into and inject arbitrary CSS. Mirrors the intent
+ * of the configurator's sanitizeValue(), but rejects instead of silently
+ * rewriting: a CLI processing a file from disk should say what is wrong, not
+ * quietly alter the user's data.
+ */
+const UNSAFE_VALUE_RE = /[;{}]|\/\*|\*\//;
+
+/**
+ * Validate and normalise a parsed theme file.
+ *
+ * @param {unknown} raw parsed JSON (not a string)
+ * @returns {{ theme: null | { schemaVersion: number, slashedVersion: string|null, name: string|null, overrides: Record<string,string> }, errors: string[] }}
+ */
+export function validateThemeFile(raw) {
+  const errors = [];
+  const fail = (msg) => {
+    errors.push(msg);
+    return { theme: null, errors };
+  };
+
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return fail('theme file must be a JSON object.');
+  }
+
+  const { schemaVersion, overrides, name, slashedVersion } = /** @type {any} */ (raw);
+
+  if (!Number.isInteger(schemaVersion)) {
+    return fail('`schemaVersion` is missing or not an integer.');
+  }
+  if (schemaVersion < 1) {
+    return fail(`\`schemaVersion\` must be >= 1 (got ${schemaVersion}).`);
+  }
+  if (schemaVersion > THEME_SCHEMA_VERSION) {
+    // Refusing beats guessing: a newer shape may carry fields whose meaning we
+    // cannot know, and silently ignoring them would corrupt the theme.
+    return fail(
+      `\`schemaVersion\` ${schemaVersion} is newer than this SLASHED understands ` +
+        `(max ${THEME_SCHEMA_VERSION}). Upgrade SLASHED to read this file.`,
+    );
+  }
+
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    return fail('`overrides` is missing or not an object.');
+  }
+  if (name != null && typeof name !== 'string') errors.push('`name` must be a string when present.');
+  if (slashedVersion != null && typeof slashedVersion !== 'string') {
+    errors.push('`slashedVersion` must be a string when present.');
+  }
+
+  const clean = {};
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!TOKEN_NAME_RE.test(key)) {
+      errors.push(`overrides["${key}"]: not a well-formed --sf-* token name.`);
+      continue;
+    }
+    if (typeof value !== 'string') {
+      errors.push(`overrides["${key}"]: value must be a string (got ${typeof value}).`);
+      continue;
+    }
+    if (UNSAFE_VALUE_RE.test(value)) {
+      errors.push(
+        `overrides["${key}"]: value contains CSS-breaking characters (; { } or comment markers).`,
+      );
+      continue;
+    }
+    clean[key] = value.trim();
+  }
+
+  if (errors.length) return { theme: null, errors };
+
+  return {
+    theme: {
+      schemaVersion,
+      slashedVersion: typeof slashedVersion === 'string' ? slashedVersion : null,
+      name: typeof name === 'string' ? name : null,
+      overrides: clean,
+    },
+    errors: [],
+  };
+}
+
+/**
+ * Parse theme-file JSON text.
+ * @param {string} text
+ * @returns {ReturnType<typeof validateThemeFile>}
+ */
+export function parseThemeFile(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { theme: null, errors: [`not valid JSON (${err.message}).`] };
+  }
+  return validateThemeFile(raw);
+}
+
+/**
+ * Migrate an override set onto the current token API.
+ *
+ * Deliberately never drops an override it does not understand: an unrecognised
+ * token is REPORTED, not deleted. The map is knowledge about the framework's
+ * own history, and absence of knowledge is not evidence the user was wrong —
+ * they may be theming a token from a build this checkout has never seen.
+ *
+ * @param {Record<string,string>} overrides
+ * @param {object} opts
+ * @param {Record<string,string>} opts.renames   old name → current name
+ * @param {Record<string,string>} opts.removals  dead name → guidance
+ * @param {Set<string>} [opts.live]              current token names; omit to skip the unknown-token report
+ * @returns {{
+ *   overrides: Record<string,string>,
+ *   renamed: Array<{ from: string, to: string }>,
+ *   removed: Array<{ name: string, reason: string }>,
+ *   unknown: string[],
+ *   collisions: Array<{ from: string, to: string, kept: string }>,
+ * }}
+ */
+export function migrateOverrides(overrides, { renames = {}, removals = {}, live } = {}) {
+  const out = {};
+  const renamed = [];
+  const removed = [];
+  const unknown = [];
+  const collisions = [];
+
+  for (const key of Object.keys(overrides).sort()) {
+    const value = overrides[key];
+
+    if (Object.prototype.hasOwnProperty.call(removals, key)) {
+      removed.push({ name: key, reason: removals[key] });
+      continue;
+    }
+
+    const target = renames[key];
+    if (target) {
+      // The file may already carry the NEW name too (e.g. it was migrated
+      // halfway, or the user set both). The explicit current-name value wins —
+      // it is the one the author most recently meant.
+      if (Object.prototype.hasOwnProperty.call(overrides, target)) {
+        collisions.push({ from: key, to: target, kept: overrides[target] });
+        continue;
+      }
+      out[target] = value;
+      renamed.push({ from: key, to: target });
+      continue;
+    }
+
+    if (live && !live.has(key)) unknown.push(key);
+    out[key] = value;
+  }
+
+  return { overrides: sortKeys(out), renamed, removed, unknown, collisions };
+}
+
+/** Return a new object with keys in sorted order (stable, diff-friendly output). */
+export function sortKeys(obj) {
+  const out = {};
+  for (const key of Object.keys(obj).sort()) out[key] = obj[key];
+  return out;
+}
+
+/**
+ * Serialise a theme file. Keys are sorted and the output is pretty-printed with
+ * a trailing newline so re-exporting an unchanged theme produces an empty diff.
+ *
+ * @param {object} theme
+ * @param {Record<string,string>} theme.overrides
+ * @param {string} [theme.name]
+ * @param {string} [theme.slashedVersion]
+ * @returns {string}
+ */
+export function serializeThemeFile({ overrides, name, slashedVersion }) {
+  const doc = {
+    $schema: THEME_SCHEMA_URL,
+    schemaVersion: THEME_SCHEMA_VERSION,
+    ...(slashedVersion ? { slashedVersion } : {}),
+    ...(name ? { name } : {}),
+    overrides: sortKeys(overrides ?? {}),
+  };
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
diff --git a/scripts/migrate-theme.js b/scripts/migrate-theme.js
new file mode 100644
index 00000000..85a9c8b4
--- /dev/null
+++ b/scripts/migrate-theme.js
@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Migrate a SLASHED theme file onto the current token API.
+ *
+ * A theme file (see scripts/lib/theme-file.js) is keyed by token NAME, which is
+ * what makes it reviewable in a diff — and also what makes it vulnerable to a
+ * rename. This is the tool that repairs one: it rewrites renamed tokens, drops
+ * removed ones with the reason, and reports anything it does not recognise.
+ *
+ * Usage:
+ *   node scripts/migrate-theme.js <file.slashed-theme.json>            # report only
+ *   node scripts/migrate-theme.js <file.slashed-theme.json> --write    # rewrite in place
+ *   npm run migrate:theme -- <file> [--write]
+ *
+ * Exit codes:
+ *   0  nothing to do (or --write succeeded)
+ *   1  the file is invalid, or migration is needed and --write was not passed
+ *
+ * The report-only default is deliberate: exit 1 on "migration needed" makes
+ * this usable as a CI check over a repository's committed theme files, while
+ * --write is the explicit opt-in to mutate someone's file.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveTokens } from './lib/live-api.js';
+import { parseThemeFile, migrateOverrides, serializeThemeFile } from './lib/theme-file.js';
+
+const slashedRoot = process.env.SLASHED_ROOT?.trim();
+const ROOT = slashedRoot
+  ? path.resolve(slashedRoot)
+  : path.resolve(import.meta.dirname, '..');
+
+const args = process.argv.slice(2);
+const write = args.includes('--write');
+const files = args.filter((a) => !a.startsWith('--'));
+
+if (files.length === 0) {
+  console.error('Usage: node scripts/migrate-theme.js <file.slashed-theme.json> [--write]');
+  process.exit(1);
+}
+
+/** Read docs/token-renames.json. */
+function readRenameMap() {
+  const file = path.join(ROOT, 'docs', 'token-renames.json');
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return { renames: parsed.renames ?? {}, removals: parsed.removals ?? {} };
+  } catch (err) {
+    console.error(`migrate-theme: cannot read docs/token-renames.json (${err.message}).`);
+    process.exit(1);
+  }
+}
+
+/** Current framework version, stamped into a migrated file. */
+function frameworkVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+const { renames, removals } = readRenameMap();
+const live = buildLiveTokens(ROOT);
+const version = frameworkVersion();
+
+let needsWork = false;
+let hadError = false;
+
+for (const rel of files) {
+  const abs = path.resolve(rel);
+  // Echo the path the user typed — a computed relative path turns an absolute
+  // argument into an unrecognisable ../../.. chain.
+  const label = rel;
+
+  if (!fs.existsSync(abs)) {
+    console.error(`${label}: file not found.`);
+    hadError = true;
+    continue;
+  }
+
+  const { theme, errors } = parseThemeFile(fs.readFileSync(abs, 'utf8'));
+  if (!theme) {
+    console.error(`${label}: invalid theme file.`);
+    for (const e of errors) console.error(`  - ${e}`);
+    hadError = true;
+    continue;
+  }
+
+  const result = migrateOverrides(theme.overrides, { renames, removals, live });
+  const changed = result.renamed.length + result.removed.length + result.collisions.length;
+
+  console.log(`${label}${theme.name ? ` (“${theme.name}”)` : ''}`);
+  console.log(
+    `  ${Object.keys(theme.overrides).length} override(s)` +
+      `${theme.slashedVersion ? `, authored against SLASHED ${theme.slashedVersion}` : ''}.`,
+  );
+
+  for (const { from, to } of result.renamed) console.log(`  renamed  ${from} → ${to}`);
+  for (const { from, to, kept } of result.collisions) {
+    console.log(`  dropped  ${from} (already set as ${to}; kept the current name's value "${kept}")`);
+  }
+  for (const { name, reason } of result.removed) console.log(`  removed  ${name}\n             ${reason}`);
+  for (const name of result.unknown) {
+    console.log(`  unknown  ${name} (not a live token and not in the rename map — left untouched)`);
+  }
+
+  if (changed === 0) {
+    console.log('  nothing to migrate.\n');
+    continue;
+  }
+  needsWork = true;
+
+  if (write) {
+    fs.writeFileSync(
+      abs,
+      serializeThemeFile({
+        overrides: result.overrides,
+        name: theme.name ?? undefined,
+        slashedVersion: version ?? theme.slashedVersion ?? undefined,
+      }),
+      'utf8',
+    );
+    console.log(`  written — ${changed} change(s) applied${version ? `, stamped SLASHED ${version}` : ''}.\n`);
+  } else {
+    console.log(`  ${changed} change(s) needed. Re-run with --write to apply.\n`);
+  }
+}
+
+if (hadError) process.exit(1);
+if (needsWork && !write) process.exit(1);
diff --git a/tests/check-token-renames.test.js b/tests/check-token-renames.test.js
new file mode 100644
index 00000000..8d3a13d0
--- /dev/null
+++ b/tests/check-token-renames.test.js
@@ -0,0 +1,141 @@
+/**
+ * Negative tests for scripts/check-token-renames.js.
+ *
+ * The rename map's value is entirely in its truthfulness — a stale entry does
+ * not merely fail to help, it actively migrates a user onto a dead token. Each
+ * test plants one violation in a fixture tree (SLASHED_ROOT) and asserts the
+ * gate refuses it.
+ *
+ * The fixture supplies both inputs live-api.js unions: token-registry.json and
+ * the core/ + optional/ CSS declarations.
+ */
+import { test, describe, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const GATE = path.join(ROOT, 'scripts', 'check-token-renames.js');
+
+const tmpDirs = [];
+after(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/**
+ * @param {object} map            contents of docs/token-renames.json
+ * @param {string[]} liveTokens   tokens that should count as live
+ */
+function buildFixture(map, liveTokens = ['--sf-color-danger', '--sf-z-toast']) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slashed-renames-'));
+  tmpDirs.push(dir);
+  fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'core'), { recursive: true });
+
+  fs.writeFileSync(path.join(dir, 'docs', 'token-renames.json'), JSON.stringify(map, null, 2));
+  fs.writeFileSync(
+    path.join(dir, 'token-registry.json'),
+    JSON.stringify({
+      _meta: { nextId: liveTokens.length },
+      tokens: liveTokens.map((name, id) => ({ id, name })),
+    }),
+  );
+  // live-api.js also unions in tokens DECLARED in core/ + optional/ CSS.
+  fs.writeFileSync(
+    path.join(dir, 'core', 'tokens.css'),
+    `:root {\n${liveTokens.map((t) => `  ${t}: red;`).join('\n')}\n}\n`,
+  );
+  return dir;
+}
+
+const runGate = (dir) =>
+  spawnSync(process.execPath, [GATE], { encoding: 'utf8', env: { ...process.env, SLASHED_ROOT: dir } });
+
+describe('check-token-renames', () => {
+  test('passes on a truthful map', () => {
+    const dir = buildFixture({
+      renames: { '--sf-color-error': '--sf-color-danger' },
+      removals: { '--sf-opacity-25': 'Use --sf-opacity-muted.' },
+    });
+    const r = runGate(dir);
+    assert.equal(r.status, 0, `expected pass:\n${r.stderr}`);
+    assert.match(r.stdout, /check:token-renames OK/);
+  });
+
+  test('fails when a rename target is not live', () => {
+    const dir = buildFixture({ renames: { '--sf-color-error': '--sf-color-gone' }, removals: {} });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /points at a token that is not live/);
+  });
+
+  test('fails on a rename chain, naming the resolved destination', () => {
+    const dir = buildFixture({
+      renames: {
+        '--sf-color-error': '--sf-color-middle',
+        '--sf-color-middle': '--sf-color-danger',
+      },
+      removals: {},
+    });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /points at another rename key/);
+    assert.match(r.stderr, /--sf-color-danger/);
+  });
+
+  test('fails when an old name is still live', () => {
+    // --sf-color-danger is live, so claiming it was renamed away is a lie.
+    const dir = buildFixture({ renames: { '--sf-color-danger': '--sf-z-toast' }, removals: {} });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /is still LIVE/);
+  });
+
+  test('fails when a removed token is still live', () => {
+    const dir = buildFixture({ renames: {}, removals: { '--sf-color-danger': 'gone' } });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /must not be reported to users as removed/);
+  });
+
+  test('fails when a token is both renamed and removed', () => {
+    const dir = buildFixture({
+      renames: { '--sf-color-error': '--sf-color-danger' },
+      removals: { '--sf-color-error': 'gone' },
+    });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /BOTH renames and removals/);
+  });
+
+  test('fails on a self-referential rename', () => {
+    const dir = buildFixture({ renames: { '--sf-color-danger': '--sf-color-danger' }, removals: {} });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /maps to itself/);
+  });
+
+  test('fails on a malformed token name', () => {
+    const dir = buildFixture({ renames: { 'color-error': '--sf-color-danger' }, removals: {} });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /well-formed/);
+  });
+
+  test('fails when a removal carries no reason', () => {
+    const dir = buildFixture({ renames: {}, removals: { '--sf-opacity-25': '   ' } });
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /no reason/);
+  });
+
+  test('fails on malformed JSON rather than throwing', () => {
+    const dir = buildFixture({ renames: {}, removals: {} });
+    fs.writeFileSync(path.join(dir, 'docs', 'token-renames.json'), '{ not json');
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /not valid JSON/);
+  });
+});
diff --git a/tests/theme-file.test.js b/tests/theme-file.test.js
new file mode 100644
index 00000000..04998783
--- /dev/null
+++ b/tests/theme-file.test.js
@@ -0,0 +1,238 @@
+/**
+ * Tests for the portable theme file: the format contract
+ * (scripts/lib/theme-file.js) and the migration CLI (scripts/migrate-theme.js).
+ *
+ * The properties that matter here are the ones a user's data depends on:
+ * a theme file must round-trip byte for byte, migration must be idempotent, and
+ * nothing the tool does not understand may be silently discarded.
+ */
+import { test, describe, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  THEME_SCHEMA_VERSION,
+  validateThemeFile,
+  parseThemeFile,
+  migrateOverrides,
+  serializeThemeFile,
+} from '../scripts/lib/theme-file.js';
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const CLI = path.join(ROOT, 'scripts', 'migrate-theme.js');
+
+const tmpDirs = [];
+function tmpFile(contents, name = 'x.slashed-theme.json') {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slashed-theme-'));
+  tmpDirs.push(dir);
+  const file = path.join(dir, name);
+  fs.writeFileSync(file, contents);
+  return file;
+}
+after(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const RENAMES = { '--sf-color-error': '--sf-color-danger', '--sf-z-top': '--sf-z-toast' };
+const REMOVALS = { '--sf-opacity-25': 'Use --sf-opacity-muted.' };
+
+describe('validateThemeFile', () => {
+  const ok = {
+    schemaVersion: 1,
+    overrides: { '--sf-color-primary-source-light': '#3b5bdb' },
+  };
+
+  test('accepts a minimal well-formed file', () => {
+    const { theme, errors } = validateThemeFile(ok);
+    assert.deepEqual(errors, []);
+    assert.equal(theme.overrides['--sf-color-primary-source-light'], '#3b5bdb');
+    assert.equal(theme.name, null);
+  });
+
+  test('rejects a non-object', () => {
+    for (const bad of [null, [], 'x', 42]) {
+      assert.equal(validateThemeFile(bad).theme, null);
+    }
+  });
+
+  test('rejects a missing or non-integer schemaVersion', () => {
+    assert.equal(validateThemeFile({ overrides: {} }).theme, null);
+    assert.equal(validateThemeFile({ schemaVersion: '1', overrides: {} }).theme, null);
+  });
+
+  test('refuses a schemaVersion from the future rather than guessing', () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: THEME_SCHEMA_VERSION + 1,
+      overrides: {},
+    });
+    assert.equal(theme, null);
+    assert.match(errors[0], /newer than this SLASHED understands/);
+  });
+
+  test('rejects a key that is not an --sf-* token', () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      overrides: { 'color-primary': 'red' },
+    });
+    assert.equal(theme, null);
+    assert.match(errors[0], /well-formed/);
+  });
+
+  test('rejects a value that could break out of the declaration', () => {
+    for (const bad of ['red; background: url(evil)', 'red }', '/* x */ red']) {
+      const { theme, errors } = validateThemeFile({
+        schemaVersion: 1,
+        overrides: { '--sf-color-primary': bad },
+      });
+      assert.equal(theme, null, `expected rejection of ${JSON.stringify(bad)}`);
+      assert.match(errors[0], /CSS-breaking/);
+    }
+  });
+
+  test('parseThemeFile reports malformed JSON without throwing', () => {
+    const { theme, errors } = parseThemeFile('{ not json');
+    assert.equal(theme, null);
+    assert.match(errors[0], /not valid JSON/);
+  });
+});
+
+describe('migrateOverrides', () => {
+  test('rewrites a renamed token, preserving its value', () => {
+    const r = migrateOverrides({ '--sf-color-error': '#e03131' }, { renames: RENAMES, removals: REMOVALS });
+    assert.deepEqual(r.overrides, { '--sf-color-danger': '#e03131' });
+    assert.deepEqual(r.renamed, [{ from: '--sf-color-error', to: '--sf-color-danger' }]);
+  });
+
+  test('drops a removed token and surfaces its reason', () => {
+    const r = migrateOverrides({ '--sf-opacity-25': '0.25' }, { renames: RENAMES, removals: REMOVALS });
+    assert.deepEqual(r.overrides, {});
+    assert.equal(r.removed[0].name, '--sf-opacity-25');
+    assert.match(r.removed[0].reason, /opacity-muted/);
+  });
+
+  test('keeps an unrecognised token instead of discarding it', () => {
+    const live = new Set(['--sf-color-danger']);
+    const r = migrateOverrides({ '--sf-from-the-future': '1rem' }, { renames: RENAMES, removals: REMOVALS, live });
+    assert.deepEqual(r.overrides, { '--sf-from-the-future': '1rem' });
+    assert.deepEqual(r.unknown, ['--sf-from-the-future']);
+  });
+
+  test('a live token is passed through without being reported unknown', () => {
+    const live = new Set(['--sf-radius-m']);
+    const r = migrateOverrides({ '--sf-radius-m': '10px' }, { renames: RENAMES, removals: REMOVALS, live });
+    assert.deepEqual(r.overrides, { '--sf-radius-m': '10px' });
+    assert.deepEqual(r.unknown, []);
+  });
+
+  test('when both old and new names are set, the current name wins', () => {
+    const r = migrateOverrides(
+      { '--sf-color-error': '#old', '--sf-color-danger': '#new' },
+      { renames: RENAMES, removals: REMOVALS },
+    );
+    assert.deepEqual(r.overrides, { '--sf-color-danger': '#new' });
+    assert.equal(r.collisions.length, 1);
+    assert.equal(r.collisions[0].kept, '#new');
+    assert.deepEqual(r.renamed, []);
+  });
+
+  test('is idempotent — migrating an already-migrated set changes nothing', () => {
+    const once = migrateOverrides({ '--sf-color-error': '#e03131' }, { renames: RENAMES, removals: REMOVALS });
+    const twice = migrateOverrides(once.overrides, { renames: RENAMES, removals: REMOVALS });
+    assert.deepEqual(twice.overrides, once.overrides);
+    assert.equal(twice.renamed.length, 0);
+    assert.equal(twice.removed.length, 0);
+  });
+
+  test('output keys are sorted regardless of input order', () => {
+    const r = migrateOverrides(
+      { '--sf-z-index': '1', '--sf-a-token': '2', '--sf-m-token': '3' },
+      { renames: {}, removals: {} },
+    );
+    assert.deepEqual(Object.keys(r.overrides), ['--sf-a-token', '--sf-m-token', '--sf-z-index']);
+  });
+});
+
+describe('serializeThemeFile', () => {
+  test('round-trips through parseThemeFile unchanged', () => {
+    const overrides = { '--sf-color-primary-source-light': '#3b5bdb', '--sf-radius-m': '10px' };
+    const text = serializeThemeFile({ overrides, name: 'Acme', slashedVersion: '0.7.31' });
+    const { theme, errors } = parseThemeFile(text);
+    assert.deepEqual(errors, []);
+    assert.deepEqual(theme.overrides, overrides);
+    assert.equal(theme.name, 'Acme');
+    assert.equal(theme.slashedVersion, '0.7.31');
+  });
+
+  test('is byte-stable — re-serialising produces an identical string', () => {
+    const a = serializeThemeFile({ overrides: { '--sf-b': '2', '--sf-a': '1' }, name: 'X' });
+    const b = serializeThemeFile({ overrides: { '--sf-a': '1', '--sf-b': '2' }, name: 'X' });
+    assert.equal(a, b, 'key order in the input must not affect the output');
+    assert.match(a, /\n$/, 'must end with a newline');
+  });
+
+  test('omits optional fields rather than writing nulls', () => {
+    const text = serializeThemeFile({ overrides: {} });
+    assert.doesNotMatch(text, /"name"/);
+    assert.doesNotMatch(text, /"slashedVersion"/);
+    assert.match(text, /"schemaVersion": 1/);
+  });
+});
+
+describe('migrate-theme CLI', () => {
+  const run = (args) => spawnSync(process.execPath, [CLI, ...args], { encoding: 'utf8', cwd: ROOT });
+
+  const legacyTheme = JSON.stringify(
+    {
+      schemaVersion: 1,
+      slashedVersion: '0.6.10',
+      name: 'Acme',
+      overrides: { '--sf-color-primary-light': '#3b5bdb', '--sf-color-error': '#e03131' },
+    },
+    null,
+    2,
+  );
+
+  test('report-only mode exits 1 when migration is needed, without touching the file', () => {
+    const file = tmpFile(legacyTheme);
+    const before = fs.readFileSync(file, 'utf8');
+    const r = run([file]);
+    assert.equal(r.status, 1, r.stderr);
+    assert.match(r.stdout, /renamed\s+--sf-color-primary-light → --sf-color-primary-source-light/);
+    assert.equal(fs.readFileSync(file, 'utf8'), before, 'report-only must not write');
+  });
+
+  test('--write applies the migration and then exits 0 on a re-run', () => {
+    const file = tmpFile(legacyTheme);
+    assert.equal(run([file, '--write']).status, 0);
+
+    const migrated = JSON.parse(fs.readFileSync(file, 'utf8'));
+    assert.ok(migrated.overrides['--sf-color-primary-source-light']);
+    assert.ok(migrated.overrides['--sf-color-danger']);
+    assert.equal(migrated.overrides['--sf-color-primary-light'], undefined);
+
+    const second = run([file]);
+    assert.equal(second.status, 0, 'a migrated file needs no further work');
+    assert.match(second.stdout, /nothing to migrate/);
+  });
+
+  test('exits 1 with a readable message on an invalid file', () => {
+    const r = run([tmpFile('{ "schemaVersion": 99, "overrides": {} }')]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /invalid theme file/);
+    assert.match(r.stderr, /newer than this SLASHED understands/);
+  });
+
+  test('exits 1 when the file does not exist', () => {
+    const r = run(['/nonexistent/theme.json']);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /file not found/);
+  });
+
+  test('exits 1 with usage when given no file', () => {
+    const r = run([]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Usage:/);
+  });
+});

From 8cc4cbd4a100fda2901a1ece9b7ef10c91ee45bf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Aug 2026 19:04:57 +0000
Subject: [PATCH 4/4] fix(tooling): close four gaps found in review of the
 theme-file gates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All four review findings reproduced; each is fixed with a regression test.

Theme-file validation (both implementations):

- An empty or whitespace-only value was trimmed and kept as an active
  override, so generateCSS() emitted `--sf-x: ;` — a broken declaration
  shadowing the real token with nothing. codec.ts already drops empty values
  on encode and decode; a file is now told rather than silently fixed.
- Values and the theme name accepted control characters. JSON forbids them as
  literal bytes but the escape form is legal, so a crafted file could carry an
  ESC into the migration CLI's output, which a terminal interprets. Rejected
  at validation — the single choke point — with escaping in the CLI as a
  second layer, since migrateOverrides() is exported.
- Whitespace is now collapsed the way codec.ts's sanitizeValue() does it
  BEFORE the control-character test, so a multi-line box-shadow value
  normalises instead of being rejected, and the two paths cannot disagree
  about what a value means.

Migration:

- Two different old names can resolve to the same live token, and the map
  already contains such pairs (--sf-color-danger-light and
  --sf-color-error-source-light both land on --sf-color-danger-source-light).
  The second assignment overwrote the first with no collision record — the
  exact silent data loss migrateOverrides() documents as impossible. Sorted
  iteration makes first-claim-wins deterministic; the loser is now reported.

Gates:

- check:forbidden-strings missed direct modern colour literals. Now flags
  hwb/lab/lch/oklab/oklch/color() while exempting oklch(from …) and
  oklch(var(…)) — those are the derivation syntax the token layer is built on,
  not hardcoded values. optional/customize-example.css is excluded: it ships
  in no bundle and literal brand colours are its entire purpose.
  (The reviewer cited optional/utilities.css:263, which is inside a comment
  block for a staged utility — correctly not flagged, before or after.)
- The external-url rule ignored protocol-relative //host/path references,
  which CSS accepts in @import and the browser fetches using the page scheme.
  Verified the widened pattern produces no new matches on the real bundles.
- docs/token-renames.json accepted an array at the root or in either section.
  An array yields no entries, so every downstream check passed vacuously and
  the CLI silently migrated nothing. Both the gate and the CLI now refuse it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01STwfcKmspjEbUYrKDVZgqt
---
 configurator/src/lib/themeFile.ts     | 35 ++++++++++++-
 configurator/tests/themeFile.test.ts  | 58 ++++++++++++++++++++++
 scripts/check-forbidden-strings.js    | 26 +++++++---
 scripts/check-token-renames.js        | 25 +++++++++-
 scripts/lib/theme-file.js             | 46 ++++++++++++++++-
 scripts/migrate-theme.js              | 32 ++++++++++--
 tests/check-forbidden-strings.test.js | 38 ++++++++++++++
 tests/check-token-renames.test.js     | 19 +++++++
 tests/theme-file.test.js              | 71 +++++++++++++++++++++++++++
 9 files changed, 337 insertions(+), 13 deletions(-)

diff --git a/configurator/src/lib/themeFile.ts b/configurator/src/lib/themeFile.ts
index ebcc4b3e..09053f80 100644
--- a/configurator/src/lib/themeFile.ts
+++ b/configurator/src/lib/themeFile.ts
@@ -26,6 +26,14 @@ export const THEME_SCHEMA_URL = "https://slashed.codeslash.dev/schema/theme/v1.j
 const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
 const UNSAFE_VALUE_RE = /[;{}]|\/\*|\*\//;
 
+/**
+ * Non-whitespace control characters (C0 + DEL), checked AFTER whitespace has
+ * been collapsed — so tab/newline in a legitimately multi-line value normalise
+ * away rather than being rejected, matching codec.ts's sanitizeValue(). What
+ * remains (ESC, BEL, NUL …) is meaningless in CSS and is rejected.
+ */
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+
 export interface ThemeFile {
   schemaVersion: number;
   slashedVersion: string | null;
@@ -77,6 +85,9 @@ export function validateThemeFile(raw: unknown): { theme: ThemeFile | null; erro
     return fail("`overrides` is missing or not an object.");
   }
   if (name != null && typeof name !== "string") errors.push("`name` must be a string when present.");
+  if (typeof name === "string" && CONTROL_CHAR_RE.test(name)) {
+    errors.push("`name` contains control characters.");
+  }
   if (slashedVersion != null && typeof slashedVersion !== "string") {
     errors.push("`slashedVersion` must be a string when present.");
   }
@@ -95,7 +106,21 @@ export function validateThemeFile(raw: unknown): { theme: ThemeFile | null; erro
       errors.push(`overrides["${key}"]: value contains CSS-breaking characters (; { } or comment markers).`);
       continue;
     }
-    clean[key] = value.trim();
+    // Collapse whitespace exactly as codec.ts's sanitizeValue() does, so the
+    // two paths cannot disagree about what a value means.
+    const normalised = value.replace(/\s+/g, " ").trim();
+    if (CONTROL_CHAR_RE.test(normalised)) {
+      errors.push(`overrides["${key}"]: value contains control characters.`);
+      continue;
+    }
+    if (normalised === "") {
+      // An empty override is not a reset — generateCSS() would emit
+      // `--sf-x: ;`, a broken declaration that shadows the real token with
+      // nothing. codec.ts already drops empty values on encode and decode.
+      errors.push(`overrides["${key}"]: value is empty. Remove the entry to leave the token at its default.`);
+      continue;
+    }
+    clean[key] = normalised;
   }
 
   if (errors.length) return { theme: null, errors };
@@ -149,6 +174,14 @@ export function migrateOverrides(
         collisions.push({ from: key, to: target, kept: overrides[target] });
         continue;
       }
+      // Two different old names can resolve to the same live token (the map
+      // contains such pairs). Without this branch the later key would silently
+      // overwrite the earlier one. Sorted iteration makes first-claim-wins
+      // deterministic.
+      if (Object.prototype.hasOwnProperty.call(out, target)) {
+        collisions.push({ from: key, to: target, kept: out[target] });
+        continue;
+      }
       out[target] = value;
       renamed.push({ from: key, to: target });
       continue;
diff --git a/configurator/tests/themeFile.test.ts b/configurator/tests/themeFile.test.ts
index a6520374..379c0322 100644
--- a/configurator/tests/themeFile.test.ts
+++ b/configurator/tests/themeFile.test.ts
@@ -55,6 +55,21 @@ const FIXTURES: Array<{ label: string; raw: unknown }> = [
     raw: { schemaVersion: 1, overrides: { "--sf-color-primary": "red; background: url(x)" } },
   },
   { label: "non-string value", raw: { schemaVersion: 1, overrides: { "--sf-radius-m": 10 } } },
+  // PR #671 review regressions — both implementations must agree on these.
+  { label: "empty value", raw: { schemaVersion: 1, overrides: { "--sf-radius-m": "" } } },
+  { label: "whitespace-only value", raw: { schemaVersion: 1, overrides: { "--sf-radius-m": "   " } } },
+  {
+    label: "control chars in value",
+    raw: { schemaVersion: 1, overrides: { "--sf-radius-m": "10px\u001b[2J" } },
+  },
+  {
+    label: "control chars in name",
+    raw: { schemaVersion: 1, name: "Acme\u001b[31m", overrides: { "--sf-radius-m": "10px" } },
+  },
+  {
+    label: "multi-line value normalises rather than failing",
+    raw: { schemaVersion: 1, overrides: { "--sf-shadow-m": "0 1px 2px #0001,\n  0 2px 4px #0002" } },
+  },
 ];
 
 describe("parity with scripts/lib/theme-file.js", () => {
@@ -88,6 +103,38 @@ describe("parity with scripts/lib/theme-file.js", () => {
   });
 });
 
+describe("value hygiene", () => {
+  test("an empty or whitespace-only value is refused, not imported as an empty override", () => {
+    // Would otherwise reach generateCSS() and emit `--sf-x: ;`.
+    for (const bad of ["", "   "]) {
+      const { theme, errors } = validateThemeFile({
+        schemaVersion: 1,
+        overrides: { "--sf-radius-m": bad },
+      });
+      expect(theme).toBeNull();
+      expect(errors.join(" ")).toMatch(/value is empty/);
+    }
+  });
+
+  test("control characters are refused", () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      overrides: { "--sf-radius-m": "10px\u001b[2J" },
+    });
+    expect(theme).toBeNull();
+    expect(errors.join(" ")).toMatch(/control characters/);
+  });
+
+  test("a multi-line value is normalised, not rejected", () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      overrides: { "--sf-shadow-m": "0 1px 2px #0001,\n  0 2px 4px #0002" },
+    });
+    expect(errors).toEqual([]);
+    expect(theme?.overrides["--sf-shadow-m"]).toBe("0 1px 2px #0001, 0 2px 4px #0002");
+  });
+});
+
 describe("theme file round-trip", () => {
   test("serialize → parse preserves the override set", () => {
     const overrides = { "--sf-color-primary-source-light": "#3b5bdb", "--sf-radius-m": "10px" };
@@ -124,6 +171,17 @@ describe("migration on import", () => {
     expect(r.unknown).toEqual(["--sf-mystery"]);
   });
 
+  test("reports a collision when two old names resolve to one target", () => {
+    // Real pair in the shipped map: both land on --sf-color-danger-source-light.
+    const r = migrateOverrides({
+      "--sf-color-danger-light": "#aaa",
+      "--sf-color-error-source-light": "#bbb",
+    });
+    expect(r.overrides).toEqual({ "--sf-color-danger-source-light": "#aaa" });
+    expect(r.collisions).toHaveLength(1);
+    expect(r.collisions[0].kept).toBe("#aaa");
+  });
+
   test("is idempotent", () => {
     const once = migrateOverrides({ "--sf-color-error": "#e03131" });
     const twice = migrateOverrides(once.overrides);
diff --git a/scripts/check-forbidden-strings.js b/scripts/check-forbidden-strings.js
index 477faaed..b9d200e9 100644
--- a/scripts/check-forbidden-strings.js
+++ b/scripts/check-forbidden-strings.js
@@ -80,13 +80,24 @@ const RULES = [
       'The framework promises every visual value is a named token. A literal colour ' +
       'here cannot be rebranded, cannot participate in the light-dark() / oklch() ' +
       'derivation chain, and will not follow a consumer\'s theme.',
-    // Hex literals plus the legacy colour functions. oklch()/color-mix() are
-    // absent by design: those are the derivation syntax the token layer is
-    // built on, not a hardcoded value.
-    pattern: /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\(/g,
+    // Hex literals, the legacy colour functions, and the modern ones.
+    //
+    // The modern functions need a lookahead: oklch(from …) and oklch(var(…))
+    // are the DERIVATION syntax the whole token layer is built on, not
+    // hardcoded values — flagging those would condemn the architecture. A
+    // direct oklch(0.6 0.25 30) is a literal like any other and is flagged.
+    // color-mix( is unaffected: \bcolor\( cannot match across the "-mix".
+    pattern:
+      /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\(|\b(?:hwb|lab|lch|oklab|oklch|color)\(\s*(?!from\b|var\()/gi,
     targets: ['core/', 'optional/'],
     extensions: ['.css'],
-    exclude: TOKEN_SOURCE_FILES,
+    exclude: [
+      ...TOKEN_SOURCE_FILES,
+      // A copy-and-customise starter that ships in no bundle (see its own
+      // header, and bundle.config.json). Literal brand colours are the point
+      // of the file — they are what a user replaces.
+      'optional/customize-example.css',
+    ],
     maskComments: true,
   },
   {
@@ -96,7 +107,10 @@ const RULES = [
       'A shipped bundle must never cause a network request. Any absolute URL here ' +
       'means every consumer page silently fetches from a third party — breaking the ' +
       '"standalone, no external requests" guarantee and leaking visitor IPs.',
-    pattern: /https?:\/\/[^\s"')]+/g,
+    // (?:https?:)? — a protocol-relative //host/path is a real external
+    // request too: CSS accepts @import url(//fonts.example/x.css) and the
+    // browser fetches it using the page's scheme.
+    pattern: /(?:https?:)?\/\/[^\s"')]+/gi,
     targets: ['dist/'],
     extensions: ['.css'],
     // Deliberately NOT comment-masked: a URL in a bundle banner is still a URL
diff --git a/scripts/check-token-renames.js b/scripts/check-token-renames.js
index e9ae0338..9e44db48 100644
--- a/scripts/check-token-renames.js
+++ b/scripts/check-token-renames.js
@@ -50,10 +50,31 @@ try {
   process.exit(1);
 }
 
-const renames = map.renames ?? {};
-const removals = map.removals ?? {};
 const errors = [];
 
+/**
+ * A section must be a plain object. An array passes `typeof x === 'object'`
+ * and yields no entries, so `{"renames": []}` would sail through every
+ * downstream check and leave the CLI silently migrating nothing.
+ */
+function readSection(name) {
+  const value = map[name];
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push(`\`${name}\` must be an object (got ${Array.isArray(value) ? 'an array' : typeof value}).`);
+    return {};
+  }
+  return value;
+}
+
+if (!map || typeof map !== 'object' || Array.isArray(map)) {
+  console.error('check:token-renames FAILED: docs/token-renames.json must be a JSON object.');
+  process.exit(1);
+}
+
+const renames = readSection('renames');
+const removals = readSection('removals');
+
 const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
 
 // Shape checks first — a malformed entry would otherwise produce a confusing
diff --git a/scripts/lib/theme-file.js b/scripts/lib/theme-file.js
index 15dc2439..e63cf014 100644
--- a/scripts/lib/theme-file.js
+++ b/scripts/lib/theme-file.js
@@ -40,6 +40,19 @@ const TOKEN_NAME_RE = /^--sf-[a-z0-9-]+$/;
  */
 const UNSAFE_VALUE_RE = /[;{}]|\/\*|\*\//;
 
+/**
+ * Non-whitespace control characters (C0 + DEL), tested AFTER whitespace has
+ * been collapsed — so tab/newline in a legitimately multi-line value (a long
+ * box-shadow, say) normalise away instead of being rejected, matching how the
+ * configurator's sanitizeValue() treats whitespace.
+ *
+ * What remains (ESC, BEL, NUL …) is meaningless in a CSS value, and echoing one
+ * into a terminal from the migration CLI would emit an ANSI/OSC sequence chosen
+ * by whoever wrote the file. This is the single choke point protecting every
+ * consumer.
+ */
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+
 /**
  * Validate and normalise a parsed theme file.
  *
@@ -78,6 +91,9 @@ export function validateThemeFile(raw) {
     return fail('`overrides` is missing or not an object.');
   }
   if (name != null && typeof name !== 'string') errors.push('`name` must be a string when present.');
+  if (typeof name === 'string' && CONTROL_CHAR_RE.test(name)) {
+    errors.push('`name` contains control characters.');
+  }
   if (slashedVersion != null && typeof slashedVersion !== 'string') {
     errors.push('`slashedVersion` must be a string when present.');
   }
@@ -98,7 +114,24 @@ export function validateThemeFile(raw) {
       );
       continue;
     }
-    clean[key] = value.trim();
+    // Collapse whitespace exactly as the configurator's sanitizeValue() does,
+    // so the two paths cannot disagree about what a value means.
+    const normalised = value.replace(/\s+/g, ' ').trim();
+    if (CONTROL_CHAR_RE.test(normalised)) {
+      errors.push(`overrides["${key}"]: value contains control characters.`);
+      continue;
+    }
+    if (normalised === '') {
+      // An empty override is not a reset — generateCSS() would emit
+      // `--sf-x: ;`, a broken declaration that shadows the real token with
+      // nothing. The configurator's codec already drops empty values on both
+      // encode and decode; a file gets told instead of silently fixed.
+      errors.push(
+        `overrides["${key}"]: value is empty. Remove the entry to leave the token at its default.`,
+      );
+      continue;
+    }
+    clean[key] = normalised;
   }
 
   if (errors.length) return { theme: null, errors };
@@ -174,6 +207,17 @@ export function migrateOverrides(overrides, { renames = {}, removals = {}, live
         collisions.push({ from: key, to: target, kept: overrides[target] });
         continue;
       }
+      // Two different old names can resolve to the SAME live token — the map
+      // really does contain such pairs (e.g. --sf-color-danger-light and
+      // --sf-color-error-source-light both land on
+      // --sf-color-danger-source-light). Without this branch the later key
+      // would overwrite the earlier one and vanish from the report, which is
+      // precisely the silent data loss this function promises never to do.
+      // Keys are walked in sorted order, so first-claim-wins is deterministic.
+      if (Object.prototype.hasOwnProperty.call(out, target)) {
+        collisions.push({ from: key, to: target, kept: out[target] });
+        continue;
+      }
       out[target] = value;
       renamed.push({ from: key, to: target });
       continue;
diff --git a/scripts/migrate-theme.js b/scripts/migrate-theme.js
index 85a9c8b4..465b7ade 100644
--- a/scripts/migrate-theme.js
+++ b/scripts/migrate-theme.js
@@ -45,7 +45,18 @@ function readRenameMap() {
   const file = path.join(ROOT, 'docs', 'token-renames.json');
   try {
     const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
-    return { renames: parsed.renames ?? {}, removals: parsed.removals ?? {} };
+    // Mirror check-token-renames.js: an array here would yield no entries and
+    // silently migrate nothing, which is worse than refusing to run.
+    const section = (name) => {
+      const value = parsed?.[name];
+      if (value === undefined) return {};
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        console.error(`migrate-theme: docs/token-renames.json \`${name}\` must be an object.`);
+        process.exit(1);
+      }
+      return value;
+    };
+    return { renames: section('renames'), removals: section('removals') };
   } catch (err) {
     console.error(`migrate-theme: cannot read docs/token-renames.json (${err.message}).`);
     process.exit(1);
@@ -61,6 +72,21 @@ function frameworkVersion() {
   }
 }
 
+/**
+ * Escape anything non-printable before echoing a file-supplied value to the
+ * terminal. validateThemeFile() already rejects control characters, so nothing
+ * should reach here — this is the second layer, because migrateOverrides() is
+ * exported and a future caller could feed it unvalidated input, and a terminal
+ * is a control-sequence interpreter, not a text sink.
+ * @param {string} value
+ */
+function forTerminal(value) {
+  return String(value).replace(
+    /[\u0000-\u001f\u007f]/g,
+    (ch) => `\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`,
+  );
+}
+
 const { renames, removals } = readRenameMap();
 const live = buildLiveTokens(ROOT);
 const version = frameworkVersion();
@@ -91,7 +117,7 @@ for (const rel of files) {
   const result = migrateOverrides(theme.overrides, { renames, removals, live });
   const changed = result.renamed.length + result.removed.length + result.collisions.length;
 
-  console.log(`${label}${theme.name ? ` (“${theme.name}”)` : ''}`);
+  console.log(`${label}${theme.name ? ` (“${forTerminal(theme.name)}”)` : ''}`);
   console.log(
     `  ${Object.keys(theme.overrides).length} override(s)` +
       `${theme.slashedVersion ? `, authored against SLASHED ${theme.slashedVersion}` : ''}.`,
@@ -99,7 +125,7 @@ for (const rel of files) {
 
   for (const { from, to } of result.renamed) console.log(`  renamed  ${from} → ${to}`);
   for (const { from, to, kept } of result.collisions) {
-    console.log(`  dropped  ${from} (already set as ${to}; kept the current name's value "${kept}")`);
+    console.log(`  dropped  ${from} (already set as ${to}; kept the current name's value "${forTerminal(kept)}")`);
   }
   for (const { name, reason } of result.removed) console.log(`  removed  ${name}\n             ${reason}`);
   for (const name of result.unknown) {
diff --git a/tests/check-forbidden-strings.test.js b/tests/check-forbidden-strings.test.js
index 7efd4fd5..5a7ed88a 100644
--- a/tests/check-forbidden-strings.test.js
+++ b/tests/check-forbidden-strings.test.js
@@ -109,6 +109,44 @@ describe('check-forbidden-strings', () => {
     assert.match(r.stderr, /core\/macros\.css:4/);
   });
 
+  test('flags a direct modern colour literal', () => {
+    for (const decl of [
+      'color: oklch(0.6 0.25 30)',
+      'color: oklab(0.5 0.1 0.1)',
+      'color: lch(50% 40 30)',
+      'color: lab(50% 40 30)',
+      'color: hwb(120 10% 20%)',
+      'color: color(display-p3 1 0 0)',
+    ]) {
+      const dir = buildFixture({ 'core/macros.css': `.sf-x { ${decl}; }\n` });
+      const r = runGate(dir, ['--check']);
+      assert.equal(r.status, 1, `expected ${decl} to be flagged`);
+      assert.match(r.stderr, /hardcoded-color/);
+    }
+  });
+
+  test('does not flag relative-colour derivations, which are the token architecture', () => {
+    for (const decl of [
+      'color: oklch(from var(--sf-color-primary) l c h)',
+      'color: oklch(var(--sf-l) var(--sf-c) var(--sf-h))',
+      'color: color-mix(in oklab, red, blue)',
+    ]) {
+      const dir = buildFixture({ 'core/macros.css': `.sf-x { ${decl}; }\n` });
+      const r = runGate(dir, ['--check']);
+      assert.equal(r.status, 0, `${decl} must be allowed:\n${r.stderr}`);
+    }
+  });
+
+  test('flags a protocol-relative external URL in a bundle', () => {
+    const dir = buildFixture({
+      'dist/slashed.optimal.css': '@import url(//fonts.example.com/style.css);\n',
+    });
+    const r = runGate(dir, ['--check']);
+    assert.equal(r.status, 1, 'a //host reference still causes a network request');
+    assert.match(r.stderr, /external-url/);
+    assert.match(r.stderr, /fonts\.example\.com/);
+  });
+
   test('flags an external URL in a shipped bundle', () => {
     const dir = buildFixture({
       'dist/slashed.optimal.css': "@import url(https://fonts.googleapis.com/css2?family=Inter);\n",
diff --git a/tests/check-token-renames.test.js b/tests/check-token-renames.test.js
index 8d3a13d0..6539bc86 100644
--- a/tests/check-token-renames.test.js
+++ b/tests/check-token-renames.test.js
@@ -131,6 +131,25 @@ describe('check-token-renames', () => {
     assert.match(r.stderr, /no reason/);
   });
 
+  test('fails when the root value is an array', () => {
+    const dir = buildFixture({ renames: {}, removals: {} });
+    fs.writeFileSync(path.join(dir, 'docs', 'token-renames.json'), '[]');
+    const r = runGate(dir);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /must be a JSON object/);
+  });
+
+  test('fails when a section is an array rather than an object', () => {
+    // An array yields no entries, so every downstream check would pass
+    // vacuously and the CLI would silently migrate nothing.
+    for (const section of ['renames', 'removals']) {
+      const dir = buildFixture({ renames: {}, removals: {}, [section]: [] });
+      const r = runGate(dir);
+      assert.equal(r.status, 1, `expected ${section}: [] to fail`);
+      assert.match(r.stderr, new RegExp(`\\\`${section}\\\` must be an object`));
+    }
+  });
+
   test('fails on malformed JSON rather than throwing', () => {
     const dir = buildFixture({ renames: {}, removals: {} });
     fs.writeFileSync(path.join(dir, 'docs', 'token-renames.json'), '{ not json');
diff --git a/tests/theme-file.test.js b/tests/theme-file.test.js
index 04998783..2ea7e730 100644
--- a/tests/theme-file.test.js
+++ b/tests/theme-file.test.js
@@ -91,6 +91,39 @@ describe('validateThemeFile', () => {
     }
   });
 
+  test('rejects an empty or whitespace-only value', () => {
+    // Regression (PR #671 review): these used to trim to "" and be accepted as
+    // an active override, so generateCSS() emitted `--sf-x: ;` — a broken
+    // declaration shadowing the real token with nothing.
+    for (const bad of ['', '   ', '\t\n']) {
+      const { theme, errors } = validateThemeFile({
+        schemaVersion: 1,
+        overrides: { '--sf-color-primary': bad },
+      });
+      assert.equal(theme, null, `expected rejection of ${JSON.stringify(bad)}`);
+      assert.match(errors[0], /value is empty/);
+    }
+  });
+
+  test('rejects control characters in a value', () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      overrides: { '--sf-color-primary': 'red\u001b[2Jwiped' },
+    });
+    assert.equal(theme, null);
+    assert.match(errors[0], /control characters/);
+  });
+
+  test('rejects control characters in the theme name', () => {
+    const { theme, errors } = validateThemeFile({
+      schemaVersion: 1,
+      name: 'Acme\u001b[31m',
+      overrides: { '--sf-radius-m': '10px' },
+    });
+    assert.equal(theme, null);
+    assert.match(errors.join(' '), /`name` contains control characters/);
+  });
+
   test('parseThemeFile reports malformed JSON without throwing', () => {
     const { theme, errors } = parseThemeFile('{ not json');
     assert.equal(theme, null);
@@ -137,6 +170,29 @@ describe('migrateOverrides', () => {
     assert.deepEqual(r.renamed, []);
   });
 
+  test('reports a collision when two old names resolve to one target', () => {
+    // Reachable with the real map: --sf-color-danger-light and
+    // --sf-color-error-source-light both land on --sf-color-danger-source-light.
+    // Without a collision record the later key would silently overwrite the
+    // earlier one — the exact data loss this function promises never to do.
+    const renames = {
+      '--sf-color-danger-light': '--sf-color-danger-source-light',
+      '--sf-color-error-source-light': '--sf-color-danger-source-light',
+    };
+    const r = migrateOverrides(
+      { '--sf-color-danger-light': '#aaa', '--sf-color-error-source-light': '#bbb' },
+      { renames, removals: {} },
+    );
+    // Sorted order: --sf-color-danger-light claims the target first.
+    assert.deepEqual(r.overrides, { '--sf-color-danger-source-light': '#aaa' });
+    assert.deepEqual(r.renamed, [
+      { from: '--sf-color-danger-light', to: '--sf-color-danger-source-light' },
+    ]);
+    assert.equal(r.collisions.length, 1);
+    assert.equal(r.collisions[0].from, '--sf-color-error-source-light');
+    assert.equal(r.collisions[0].kept, '#aaa');
+  });
+
   test('is idempotent — migrating an already-migrated set changes nothing', () => {
     const once = migrateOverrides({ '--sf-color-error': '#e03131' }, { renames: RENAMES, removals: REMOVALS });
     const twice = migrateOverrides(once.overrides, { renames: RENAMES, removals: REMOVALS });
@@ -224,6 +280,21 @@ describe('migrate-theme CLI', () => {
     assert.match(r.stderr, /newer than this SLASHED understands/);
   });
 
+  test('refuses a file carrying terminal control sequences', () => {
+    const file = tmpFile(
+      JSON.stringify({
+        schemaVersion: 1,
+        name: 'Acme',
+        overrides: { '--sf-color-primary': 'red\u001b[2J' },
+      }),
+    );
+    const r = run([file]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /control characters/);
+    assert.ok(!r.stderr.includes('\u001b[2J'), 'must not echo the raw escape sequence');
+    assert.ok(!r.stdout.includes('\u001b[2J'), 'must not echo the raw escape sequence');
+  });
+
   test('exits 1 when the file does not exist', () => {
     const r = run(['/nonexistent/theme.json']);
     assert.equal(r.status, 1);