diff --git a/configurator/scripts/check-curation.mjs b/configurator/scripts/check-curation.mjs
index ee271b70..c97b73c1 100644
--- a/configurator/scripts/check-curation.mjs
+++ b/configurator/scripts/check-curation.mjs
@@ -5,15 +5,17 @@
  * Every PUBLIC / PUBLIC-ADVANCED knob token must map to a named domain so it
  * shows up in the right panel rather than an uncategorised fallback.
  *
- * Patterns kept in sync with src/lib/domains.ts — if you update the domain
- * patterns there, update DOMAIN_PATTERNS here as well.
+ * Classification is driven by src/data/domain-map.json — the same file
+ * src/lib/domains.ts uses at runtime — so this guard and the app can never
+ * drift. If the framework adds a token in a brand-new namespace, add that
+ * namespace to domain-map.json.
  *
  * Usage:  node scripts/check-curation.mjs        # exits 1 on any orphan
  * Also asserted by tests/curation.test.js so CI catches it either way.
  */
 import { pathToFileURL } from 'url';
 import data from '../src/data/api-index.generated.json' with { type: 'json' };
-import DOMAIN_PATTERNS from '../src/data/domain-patterns.json' with { type: 'json' };
+import DOMAIN_MAP from '../src/data/domain-map.json' with { type: 'json' };
 
 /**
  * Tokens that legitimately live outside the named domains.
@@ -21,17 +23,27 @@ import DOMAIN_PATTERNS from '../src/data/domain-patterns.json' with { type: 'jso
  */
 const ALLOWLIST = new Set([]);
 
+const NAMESPACE_DOMAIN = DOMAIN_MAP.namespaces;
+const EXCEPTIONS = DOMAIN_MAP.exceptions;
+
+/** The `--sf-<namespace>-…` segment of a token name. */
+function inferNamespace(name) {
+  const m = /^--sf-([a-z0-9]+)/.exec(name || '');
+  return m ? m[1] : '';
+}
+
 /**
- * Returns true when a token name matches any domain pattern.
- * @param {{name:string}} token
+ * Returns true when a token is explicitly classified into a domain — i.e. it
+ * has a per-token exception or its (manifest-authored) namespace is mapped.
+ * Mirrors src/lib/domains.ts's classifyKnown() from the same domain-map.json.
+ * @param {{name:string, namespace?:string}} token
  * @returns {boolean}
  */
 function isExplicitlyClassified(token) {
   const name = token.name || '';
-  for (const patterns of Object.values(DOMAIN_PATTERNS)) {
-    if (patterns.some(p => name.includes(p))) return true;
-  }
-  return false;
+  if (EXCEPTIONS[name]) return true;
+  const ns = token.namespace || inferNamespace(name);
+  return Boolean(NAMESPACE_DOMAIN[ns]);
 }
 
 /**
@@ -54,7 +66,7 @@ if (import.meta.url === pathToFileURL(process.argv[1]).href) {
       `[configurator:curation] ${orphans.length} knob token(s) match no domain ` +
         `pattern and would only appear in an uncategorised bucket:\n` +
         orphans.map(n => `  - ${n}`).join('\n') +
-        `\n\nAdd a name pattern to src/data/domain-patterns.json.`
+        `\n\nAdd the token's namespace to src/data/domain-map.json.`
     );
     process.exit(1);
   }
diff --git a/configurator/src/components/DomainPanel.svelte b/configurator/src/components/DomainPanel.svelte
index fb7270cb..a638d1f9 100644
--- a/configurator/src/components/DomainPanel.svelte
+++ b/configurator/src/components/DomainPanel.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
   import { SlidersHorizontal, List } from '@lucide/svelte';
   import type { SlashedToken } from '../types';
-  import { DOMAIN_PATTERNS, domainOf } from '../lib/domains';
+  import { domainOf } from '../lib/domains';
   import HomePanel from './panels/HomePanel.svelte';
   import ColorsPanel from './panels/ColorsPanel.svelte';
   import TypographyPanel from './panels/TypographyPanel.svelte';
@@ -45,12 +45,8 @@
     view = "controls";
   });
 
-  let patterns = $derived(DOMAIN_PATTERNS[domain] ?? [domain]);
-
-  // Uses domainOf() rather than the raw patterns list so this badge always
-  // agrees with App.svelte's "Reset N" count — matching against a single
-  // domain's patterns in isolation over-counts where patterns overlap (e.g.
-  // layout's "-bg-" also appears in color tokens like --sf-color-bg--active).
+  // domainOf() is the single classifier shared with the sidebar badge and the
+  // category Reset, so this count always agrees with them.
   let domainOverridesInTokenTab = $derived(
     tokens.filter((t) => domainOf(t.name) === domain && t.name in overrides).length
   );
@@ -104,7 +100,7 @@
         <AllTokensTab
           {tokens}
           {overrides}
-          {patterns}
+          {domain}
           {onSet}
           {onReset}
         />
diff --git a/configurator/src/components/inputs/TokenRow.svelte b/configurator/src/components/inputs/TokenRow.svelte
index 6fae647a..632bad68 100644
--- a/configurator/src/components/inputs/TokenRow.svelte
+++ b/configurator/src/components/inputs/TokenRow.svelte
@@ -2,14 +2,33 @@
   import type { SlashedToken } from '../../types';
   import { resolveColor, previewVersion } from '../../lib/previewResolver.svelte';
   import { scaleForValue } from '../../lib/variableScales';
+  import { roleOf, aliasTargetOf, tokenState, ROLE_LABEL, type TokenRole, type TokenState } from '../../lib/tokenModel';
 
-  let { token, overrideValue, onSet, onReset }: {
+  let { token, overrideValue, onSet, onReset, dependentsCount = 0 }: {
     token: SlashedToken;
     overrideValue?: string;
     onSet: (value: string) => void;
     onReset: () => void;
+    /** How many other tokens reference this one (from the dependency graph). */
+    dependentsCount?: number;
   } = $props();
 
+  // --- Token model: role, alias target and override state -------------------
+  // These make the row honest about *what kind of token* is being edited and
+  // whether the current override quietly disconnects it from the system that
+  // produces it (a generated output/alias/scale step). See lib/tokenModel.ts.
+  let role = $derived<TokenRole>(roleOf(token));
+  let aliasTarget = $derived(aliasTargetOf(token));
+  let overrideState = $derived<TokenState>(
+    overrideValue === undefined ? "default" : tokenState(token, { [token.name]: overrideValue })
+  );
+  const ROLE_STYLE: Record<TokenRole, string> = {
+    source: "text-slate-500 dark:text-slate-400 bg-black/5 dark:bg-white/8",
+    alias:  "text-sky-700 dark:text-sky-300 bg-sky-500/10",
+    output: "text-violet-700 dark:text-violet-300 bg-violet-500/10",
+  };
+  let aliasShort = $derived(aliasTarget ? aliasTarget.replace("--sf-", "") : "");
+
   const CUSTOM = "__sf_custom__";
   let expanded = $state(false);
 
@@ -73,9 +92,22 @@
         style:background={swatchColor}
       ></div>
     {/if}
-    <div class="text-[10px] font-mono text-slate-700 dark:text-slate-300 truncate flex-1" title={token.name}>
+    <div class="text-[10px] font-mono text-slate-700 dark:text-slate-300 truncate min-w-0 flex-1" title={token.name}>
       {shortName}
     </div>
+    <!-- Role badge: source (settable) · alias (re-export) · output (generated).
+         Makes it obvious when you're about to edit something the system derives
+         rather than a knob you own. -->
+    <span
+      class={`shrink-0 px-1 py-px rounded text-[7px] font-bold uppercase tracking-wider ${ROLE_STYLE[role]}`}
+      title={role === "source"
+        ? "Source — a value you set"
+        : role === "alias"
+          ? `Alias — re-exports ${aliasShort}`
+          : "Output — generated from other tokens"}
+    >
+      {ROLE_LABEL[role]}
+    </span>
     {#if isOverridden}
       <button
         onclick={onReset}
@@ -91,6 +123,45 @@
     <div class="text-[9px] text-slate-400 dark:text-slate-600 leading-snug mt-0.5 pl-3.5">{token.description}</div>
   {/if}
 
+  <!-- Relationship context: where this token inherits from, and what depends on
+       it. Turns the flat list into a navigable graph the audit found missing. -->
+  {#if aliasTarget || dependentsCount > 0}
+    <div class="flex flex-wrap items-center gap-x-2 gap-y-0.5 mt-0.5 pl-3.5 text-[8px] text-slate-400 dark:text-slate-600">
+      {#if aliasTarget}
+        <span class="font-mono">↳ inherits <span class="text-sky-600 dark:text-sky-400">{aliasShort}</span></span>
+      {/if}
+      {#if dependentsCount > 0}
+        <span title={`${dependentsCount} token${dependentsCount !== 1 ? "s" : ""} reference this token in the framework defaults`}>
+          used by {dependentsCount} default{dependentsCount !== 1 ? "s" : ""}
+        </span>
+      {/if}
+    </div>
+  {/if}
+
+  <!-- Detached / invalid warning: only when the override actually disconnects
+       the token from its generator, or fails validation. -->
+  {#if overrideState === "detached"}
+    <div class="flex items-start gap-1 mt-1 ml-3.5 px-1.5 py-1 rounded bg-amber-500/10 text-[8px] text-amber-700 dark:text-amber-300 leading-snug">
+      <span class="font-bold shrink-0">Detached</span>
+      <span>
+        {role === "alias"
+          ? `frozen — no longer follows ${aliasShort}.`
+          : role === "output"
+            ? "frozen — no longer derived from its source tokens."
+            : "a generated scale step is pinned; its source knob won't move it."}
+        <button onclick={onReset} class="underline hover:text-amber-900 dark:hover:text-amber-100 cursor-pointer">Restore link</button>
+      </span>
+    </div>
+  {:else if overrideState === "invalid"}
+    <div class="flex items-start gap-1 mt-1 ml-3.5 px-1.5 py-1 rounded bg-rose-500/10 text-[8px] text-rose-700 dark:text-rose-300 leading-snug">
+      <span class="font-bold shrink-0">Invalid</span>
+      <span>
+        this value can't be applied safely.
+        <button onclick={onReset} class="underline hover:text-rose-900 dark:hover:text-rose-100 cursor-pointer">Reset</button>
+      </span>
+    </div>
+  {/if}
+
   <div class="mt-1 pl-3.5">
     {#if showScalePicker && scaleOpts}
       <select
diff --git a/configurator/src/components/panels/AllTokensTab.svelte b/configurator/src/components/panels/AllTokensTab.svelte
index c151e11e..6dd11aa5 100644
--- a/configurator/src/components/panels/AllTokensTab.svelte
+++ b/configurator/src/components/panels/AllTokensTab.svelte
@@ -1,24 +1,32 @@
 <script lang="ts">
   import type { SlashedToken } from '../../types';
   import TokenRow from '../inputs/TokenRow.svelte';
+  import { buildDependencyGraph } from '../../lib/tokenModel';
+  import { domainOf } from '../../lib/domains';
 
-  let { tokens, overrides, patterns, onSet, onReset }: {
+  let { tokens, overrides, domain, onSet, onReset }: {
     tokens: SlashedToken[];
     overrides: Record<string, string>;
-    patterns: string[];
+    domain: string;
     onSet: (name: string, value: string) => void;
     onReset: (name: string) => void;
   } = $props();
 
   const TIER_ORDER: Record<string, number> = { PUBLIC: 0, "PUBLIC-ADVANCED": 1, INTERNAL: 2 };
 
+  // Whole-catalogue dependency graph (built once from the full token set, not
+  // just this domain's slice) so every row can show how many tokens read it.
+  let graph = $derived(buildDependencyGraph(tokens));
+
   let query = $state("");
   let showInternal = $state(false);
   let onlyModified = $state(false);
 
+  // Filter by the SAME classifier the sidebar badge and category Reset use, so
+  // this list can never disagree with them about what belongs to the domain.
   let domainTokens = $derived(
     tokens
-      .filter((t) => patterns.some((p) => t.name.includes(p)))
+      .filter((t) => domainOf(t.name) === domain)
       .sort((a, b) => {
         const ta = TIER_ORDER[a.tier ?? "INTERNAL"] ?? 2;
         const tb = TIER_ORDER[b.tier ?? "INTERNAL"] ?? 2;
@@ -141,6 +149,7 @@
             <TokenRow
               token={t}
               overrideValue={overrides[t.name]}
+              dependentsCount={graph.usedBy[t.name]?.length ?? 0}
               onSet={(v) => onSet(t.name, v)}
               onReset={() => onReset(t.name)}
             />
diff --git a/configurator/src/components/panels/GenericTokenPanel.svelte b/configurator/src/components/panels/GenericTokenPanel.svelte
index 317c56ab..7f9e1e1f 100644
--- a/configurator/src/components/panels/GenericTokenPanel.svelte
+++ b/configurator/src/components/panels/GenericTokenPanel.svelte
@@ -1,24 +1,22 @@
 <script lang="ts">
   import type { SlashedToken } from '../../types';
   import TokenRow from '../inputs/TokenRow.svelte';
+  import { domainOf } from '../../lib/domains';
 
-  let { domain, tokens, overrides, onSet, onReset, patterns }: {
+  let { domain, tokens, overrides, onSet, onReset }: {
     domain: string;
     tokens: SlashedToken[];
     overrides: Record<string, string>;
     onSet: (name: string, value: string) => void;
     onReset: (name: string) => void;
-    patterns?: string[];
   } = $props();
 
   let query = $state("");
 
-  let domainTokens = $derived(() => {
-    const pats = patterns ?? [domain];
-    return tokens.filter((t) =>
-      pats.some((p) => t.name.includes(p)) && t.tier !== "INTERNAL"
-    );
-  });
+  // Same classifier as the sidebar badge / Reset / All-tokens list.
+  let domainTokens = $derived(() =>
+    tokens.filter((t) => domainOf(t.name) === domain && t.tier !== "INTERNAL")
+  );
 
   let filtered = $derived(() => {
     if (!query) return domainTokens();
diff --git a/configurator/src/data/domain-map.json b/configurator/src/data/domain-map.json
new file mode 100644
index 00000000..2c8d7698
--- /dev/null
+++ b/configurator/src/data/domain-map.json
@@ -0,0 +1,106 @@
+{
+  "_doc": "Authoritative, metadata-driven token→domain classification. Keyed on the framework-authored `namespace` (the segment after --sf-), which is precise and never drifts from the framework — unlike the old substring matching, where overlapping fragments (e.g. 'color' in --sf-focus-ring-color) routed a token to the wrong panel and made the sidebar badge, the category Reset, and the All-tokens list disagree. A namespace maps to exactly one domain; the handful of genuinely mixed namespaces are resolved per-token in `exceptions`. Every domain here must also exist in domains.ts's DOMAINS list. check-curation.mjs consumes the same file, so the build guard and the runtime can never diverge.",
+  "namespaces": {
+    "color": "colors",
+    "contrast": "colors",
+    "palette": "colors",
+    "lumlocker": "colors",
+    "gradient": "colors",
+    "marker": "colors",
+
+    "text": "typography",
+    "font": "typography",
+    "body": "typography",
+    "heading": "typography",
+    "h1": "typography",
+    "h2": "typography",
+    "h3": "typography",
+    "h4": "typography",
+    "h5": "typography",
+    "h6": "typography",
+    "leading": "typography",
+    "tracking": "typography",
+    "link": "typography",
+    "optical": "typography",
+    "display": "typography",
+    "code": "typography",
+    "fluid": "typography",
+
+    "space": "spacing",
+    "gap": "spacing",
+    "gutter": "spacing",
+    "section": "spacing",
+    "component": "spacing",
+    "content": "spacing",
+
+    "container": "layout",
+    "grid": "layout",
+    "center": "layout",
+    "cluster": "layout",
+    "cover": "layout",
+    "equal": "layout",
+    "frame": "layout",
+    "imposter": "layout",
+    "reel": "layout",
+    "sidebar": "layout",
+    "switcher": "layout",
+    "alternate": "layout",
+    "bento": "layout",
+    "stack": "layout",
+    "header": "layout",
+    "sticky": "layout",
+    "safe": "layout",
+    "touch": "layout",
+    "breakout": "layout",
+    "box": "layout",
+    "bg": "layout",
+    "ratio": "layout",
+
+    "radius": "borders",
+    "border": "borders",
+    "divider": "borders",
+    "field": "borders",
+    "media": "borders",
+
+    "shadow": "shadows",
+
+    "motion": "motion",
+    "duration": "motion",
+    "ease": "motion",
+    "transition": "motion",
+    "stagger": "motion",
+    "scroll": "motion",
+    "hover": "motion",
+    "theme": "motion",
+    "animation": "motion",
+
+    "blur": "effects",
+    "opacity": "effects",
+    "drop": "effects",
+
+    "prose": "macros",
+    "flow": "macros",
+    "line": "macros",
+    "scrim": "macros",
+    "surface": "macros",
+    "mask": "macros",
+
+    "btn": "components",
+    "card": "components",
+
+    "z": "misc",
+    "icon": "misc",
+    "size": "misc",
+    "object": "misc",
+    "scrollbar": "misc",
+    "focus": "misc",
+    "is": "misc"
+  },
+  "exceptions": {
+    "--sf-content-width": "layout",
+    "--sf-content-intrinsic-size": "macros",
+    "--sf-scroll-shadow-size": "macros",
+    "--sf-scroll-offset-gap": "layout",
+    "--sf-field-required-marker": "misc"
+  }
+}
diff --git a/configurator/src/data/domain-patterns.json b/configurator/src/data/domain-patterns.json
deleted file mode 100644
index cd3e01f2..00000000
--- a/configurator/src/data/domain-patterns.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
-  "macros":     ["prose", "flow-space", "line-clamp", "aspect", "scroll-shadow", "scrim", "surface-color", "surface-bg", "content-intrinsic", "overlap-"],
-  "colors":     ["color", "contrast", "palette", "lumlocker", "gradient"],
-  "typography": ["font", "--sf-text", "leading", "tracking", "weight", "body-font", "heading-font",
-                 "body-em", "body-text", "heading-text", "display-l-", "display-m-",
-                 "-h1-", "-h2-", "-h3-", "-h4-", "-h5-", "-h6-",
-                 "link-", "optical-sizing", "fluid-width", "fluid-min-vw", "fluid-max-vw"],
-  "spacing":    ["space", "section", "gutter", "content-gap", "component-pad", "density"],
-  "layout":     ["container", "layout", "grid", "breakpoint", "measure", "column",
-                 "header-height", "touch-target", "bento", "cluster",
-                 "cover-min", "equal-min", "equal-rule", "frame", "ratio-", "reel", "safe-", "sidebar",
-                 "switcher", "-bg-"],
-  "components": ["btn-", "card-"],
-  "borders":    ["radius", "border-width", "border-scale", "border-style", "divider"],
-  "shadows":    ["shadow"],
-  "motion":     ["motion", "duration", "easing", "ease", "scroll-timeline", "stagger", "hover-"],
-  "effects":    ["filter", "blur", "backdrop", "opacity", "effect"],
-  "misc":       ["z-", "cursor", "ring", "focus", "outline", "selection", "icon",
-                 "field-required", "object-fit", "object-position", "print-", "scrollbar", "size-"]
-}
diff --git a/configurator/src/lib/domains.ts b/configurator/src/lib/domains.ts
index 7720e8d9..a1f9ff68 100644
--- a/configurator/src/lib/domains.ts
+++ b/configurator/src/lib/domains.ts
@@ -1,13 +1,75 @@
-import RAW from '../data/domain-patterns.json';
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
 
-/** Token name substrings that define each domain's scope. Single source of truth: src/data/domain-patterns.json */
-export const DOMAIN_PATTERNS: Record<string, string[]> = RAW as unknown as Record<string, string[]>;
+/**
+ * Token → domain (panel) classification — the single, deterministic source of
+ * truth used by the sidebar badges, the category Reset, the command palette,
+ * Home counts and the All-tokens list.
+ *
+ * Previously this was substring matching over a hand-kept pattern list. Because
+ * fragments overlapped (e.g. "color" is a substring of --sf-focus-ring-color,
+ * "-bg-" of --sf-color-bg--active, "shadow" of --sf-drop-shadow-*), a token
+ * could match several domains at once. The order of the pattern object then
+ * silently decided the winner, and the All-tokens tab filtered by the raw
+ * patterns while the badge/Reset used first-match `domainOf()` — so the two
+ * routinely disagreed about which tokens "belong" to a panel.
+ *
+ * This version classifies on the framework-authored `namespace` (the segment
+ * after `--sf-`), which is precise and one-to-one with a domain. The map lives
+ * in src/data/domain-map.json and is shared verbatim with the build-time
+ * curation guard (scripts/check-curation.mjs), so runtime and CI can never
+ * drift. A namespace maps to exactly one domain; the few genuinely mixed
+ * namespaces are resolved per-token in the map's `exceptions`.
+ */
+import MAP from '../data/domain-map.json';
+import apiIndex from '../data/api-index.generated.json';
+import type { ApiIndex } from '../types';
+
+const NAMESPACE_DOMAIN = (MAP as { namespaces: Record<string, string> }).namespaces;
+const EXCEPTIONS = (MAP as { exceptions: Record<string, string> }).exceptions;
+
+/** The domain used when a token matches no known namespace. */
+export const FALLBACK_DOMAIN = 'misc';
+
+/** All domain ids a token can classify into, in canonical panel order. */
+export const DOMAINS = [
+  'colors', 'typography', 'spacing', 'layout', 'borders', 'shadows',
+  'motion', 'effects', 'macros', 'components', 'misc',
+] as const;
+
+export type Domain = (typeof DOMAINS)[number];
+
+// Authoritative name → namespace, taken from the baked manifest. Lets us use
+// the framework's own namespace assignment for every shipping token, and fall
+// back to name inference only for keys that aren't in the catalogue (legacy /
+// imported / renamed overrides).
+const NAME_TO_NAMESPACE: Record<string, string> = {};
+for (const t of (apiIndex as ApiIndex).tokens ?? []) {
+  NAME_TO_NAMESPACE[t.name] = t.namespace ?? inferNamespace(t.name);
+}
+
+/** The `--sf-<namespace>-…` segment of a token name. */
+export function inferNamespace(tokenName: string): string {
+  const m = /^--sf-([a-z0-9]+)/.exec(tokenName);
+  return m ? m[1] : '';
+}
+
+/**
+ * The domain a token is *explicitly* classified into, or null when its
+ * namespace is unknown (i.e. it would only land in the Misc fallback). The
+ * curation guard treats a null here for a public knob as an orphan.
+ */
+export function classifyKnown(tokenName: string): Domain | null {
+  const exc = EXCEPTIONS[tokenName];
+  if (exc) return exc as Domain;
+  const ns = NAME_TO_NAMESPACE[tokenName] ?? inferNamespace(tokenName);
+  const domain = NAMESPACE_DOMAIN[ns];
+  return (domain as Domain) ?? null;
+}
 
 /** Return the domain key for a given token name, falling back to "misc". */
-export function domainOf(tokenName: string): string {
-  for (const [domain, patterns] of Object.entries(DOMAIN_PATTERNS)) {
-    if (domain === "misc") continue;
-    if (patterns.some(p => tokenName.includes(p))) return domain;
-  }
-  return "misc";
+export function domainOf(tokenName: string): Domain {
+  return classifyKnown(tokenName) ?? FALLBACK_DOMAIN;
 }
diff --git a/configurator/src/lib/tokenModel.ts b/configurator/src/lib/tokenModel.ts
new file mode 100644
index 00000000..5fe1f579
--- /dev/null
+++ b/configurator/src/lib/tokenModel.ts
@@ -0,0 +1,388 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Token model — the configurator's first-class understanding of *how tokens
+ * relate to each other*, derived from the framework-authored manifest metadata
+ * (`role`, `aliasOf`, `namespace`, `value`) rather than re-guessed from names.
+ *
+ * The audit found the studio treats every token as an equal, free-standing
+ * string: it does not know which tokens are user-settable SOURCES, which are
+ * one-to-one ALIASES, and which are generated OUTPUTS; nor which tokens depend
+ * on which. That lets a user "freeze" a derived output or a generated scale
+ * step and silently disconnect it from the system that produces it, with no
+ * warning anywhere but the two scale panels.
+ *
+ * This module centralises that knowledge so every surface (All-tokens rows,
+ * the future Changes panel, scale cards) can speak the same language:
+ *
+ *   • role        — source | alias | output
+ *   • alias target — the single token an alias/relink points at
+ *   • dependency graph — dependsOn / usedBy across the whole catalogue
+ *   • token state — how a given override relates to the framework default:
+ *                    default | custom | relinked | detached | invalid
+ *   • scale families — the generative ladders (text/display/space/radius/
+ *                    border-width/motion) and detection of step overrides that
+ *                    shadow their source knobs
+ *   • validation  — best-effort rejection of CSS-breaking / empty values
+ *
+ * Everything here is pure and headless-safe: value validation upgrades to real
+ * `CSS.supports()` checks in a browser but degrades to structural checks under
+ * jsdom / Node so it can be unit-tested and run inside the WP plugin.
+ */
+
+import type { SlashedToken } from "../types";
+
+// ---------------------------------------------------------------------------
+// References & aliasing
+// ---------------------------------------------------------------------------
+
+const VAR_REF_RE = /var\(\s*(--sf-[\w-]+)/g;
+// A *pure* single-token reference: the whole value is exactly `var(--sf-x)`
+// (an optional fallback is allowed). This is what makes a token a true alias —
+// a one-to-one re-export — as opposed to a compound value that merely *uses*
+// other tokens (color-mix(), calc(), a border shorthand, …).
+const PURE_VAR_RE = /^var\(\s*(--sf-[\w-]+)\s*(?:,[\s\S]*)?\)$/;
+
+/** Reject unbalanced function syntax before classifying a value as an alias. */
+function hasBalancedParens(value: string): boolean {
+  let depth = 0;
+  for (const char of value) {
+    if (char === "(") depth += 1;
+    if (char === ")" && --depth < 0) return false;
+  }
+  return depth === 0;
+}
+
+/** Every distinct `--sf-*` token referenced (via `var()`) inside a value. */
+export function referencesIn(value: string | null | undefined): string[] {
+  if (!value) return [];
+  const out = new Set<string>();
+  let m: RegExpExecArray | null;
+  VAR_REF_RE.lastIndex = 0;
+  while ((m = VAR_REF_RE.exec(value)) !== null) out.add(m[1]);
+  return [...out];
+}
+
+/** The single token a pure `var(--sf-x)` value points at, else null. */
+export function pureVarTarget(value: string | null | undefined): string | null {
+  if (!value || !hasBalancedParens(value)) return null;
+  const m = PURE_VAR_RE.exec(value.trim());
+  return m ? m[1] : null;
+}
+
+/**
+ * The token an alias re-exports. Prefers the framework-declared `aliasOf`;
+ * falls back to a pure single-`var()` default value. Returns null for sources
+ * and compound outputs.
+ */
+export function aliasTargetOf(token: SlashedToken): string | null {
+  if (token.aliasOf) return token.aliasOf;
+  return pureVarTarget(token.value);
+}
+
+// ---------------------------------------------------------------------------
+// Role: source | alias | output
+// ---------------------------------------------------------------------------
+
+export type TokenRole = "source" | "alias" | "output";
+
+/**
+ * Whether a token is an INPUT you set (`source`), a one-to-one re-export of
+ * another token (`alias`), or a derived OUTPUT you read (`output`).
+ *
+ * Built on the manifest's own `role` (knob vs consumption) and `aliasOf`, so it
+ * never drifts from the framework: a pure re-export is an alias; a consumption
+ * value that composes multiple tokens is an output; everything else is a
+ * settable source.
+ */
+export function roleOf(token: SlashedToken): TokenRole {
+  if (aliasTargetOf(token)) return "alias";
+  if (token.role === "consumption") return "output";
+  return "source";
+}
+
+export const ROLE_LABEL: Record<TokenRole, string> = {
+  source: "Source",
+  alias: "Alias",
+  output: "Output",
+};
+
+// ---------------------------------------------------------------------------
+// Dependency graph
+// ---------------------------------------------------------------------------
+
+export interface DependencyGraph {
+  /** token → the tokens it references in its default value. */
+  dependsOn: Record<string, string[]>;
+  /** token → the tokens whose default value references it. */
+  usedBy: Record<string, string[]>;
+}
+
+/**
+ * Build the whole-catalogue dependency graph from token default values. This is
+ * the piece the audit found missing: it lets any surface answer "what feeds
+ * this token?" and "what breaks if I freeze it?".
+ */
+export function buildDependencyGraph(tokens: SlashedToken[]): DependencyGraph {
+  const known = new Set(tokens.map((t) => t.name));
+  const dependsOn: Record<string, string[]> = {};
+  const usedBy: Record<string, string[]> = {};
+
+  for (const t of tokens) {
+    const refs = referencesIn(t.value).filter((r) => r !== t.name && known.has(r));
+    dependsOn[t.name] = refs;
+    for (const r of refs) {
+      (usedBy[r] ??= []).push(t.name);
+    }
+  }
+  // Stable, deterministic ordering for predictable UI + diffs.
+  for (const k of Object.keys(usedBy)) usedBy[k].sort();
+  return { dependsOn, usedBy };
+}
+
+// ---------------------------------------------------------------------------
+// Generative scale families
+// ---------------------------------------------------------------------------
+
+export interface ScaleFamily {
+  id: string;
+  label: string;
+  /** Source knobs the framework computes the ladder from. */
+  sources: string[];
+  /** Generated step tokens; a concrete override here shadows the sources. */
+  steps: string[];
+}
+
+const STEP_KEYS = ["2xs", "xs", "s", "m", "l", "xl", "2xl", "3xl", "4xl"] as const;
+const stepTokens = (prefix: string) => STEP_KEYS.map((s) => `--sf-${prefix}-${s}`);
+
+/**
+ * The framework's generative ladders. Sources mirror persistence.ts's
+ * derived-scale engine (the same formula the CSS and WP PHP emitter use), so
+ * shadow detection here matches what the live preview actually computes.
+ */
+export const SCALE_FAMILIES: ScaleFamily[] = [
+  {
+    id: "text",
+    label: "Type scale",
+    sources: [
+      "--sf-text-base-min", "--sf-text-base-max",
+      "--sf-text-ratio-min", "--sf-text-ratio-max",
+      "--sf-text-scale", "--sf-fluid-min-vw", "--sf-fluid-max-vw",
+    ],
+    steps: stepTokens("text"),
+  },
+  {
+    id: "display",
+    label: "Display scale",
+    sources: [
+      "--sf-text-display-base-min", "--sf-text-display-base-max",
+      "--sf-text-ratio-min", "--sf-text-ratio-max",
+      "--sf-text-display-scale", "--sf-fluid-min-vw", "--sf-fluid-max-vw",
+    ],
+    steps: ["--sf-text-display-s", "--sf-text-display-m", "--sf-text-display-l"],
+  },
+  {
+    id: "space",
+    label: "Spacing scale",
+    sources: [
+      "--sf-space-base-min", "--sf-space-base-max",
+      "--sf-space-ratio-min", "--sf-space-ratio-max",
+      "--sf-space-scale", "--sf-fluid-min-vw", "--sf-fluid-max-vw",
+    ],
+    steps: stepTokens("space"),
+  },
+  {
+    id: "radius",
+    label: "Radius scale",
+    sources: ["--sf-radius-scale"],
+    steps: [
+      ...stepTokens("radius"),
+      "--sf-radius-none", "--sf-radius-full", "--sf-radius-pill", "--sf-radius-outer",
+    ],
+  },
+  {
+    id: "border-width",
+    label: "Border-width scale",
+    sources: ["--sf-border-scale"],
+    steps: ["--sf-border-width-1", "--sf-border-width-2", "--sf-border-width-3", "--sf-border-width-4"],
+  },
+  {
+    id: "motion",
+    label: "Duration scale",
+    sources: ["--sf-motion-scale"],
+    // Only catalogue tokens are listed. The framework's derived engine also
+    // scales --sf-animation-delay-N, but those are compute-only (not real
+    // manifest tokens), so a user can never store an override that shadows
+    // them — they're deliberately excluded from step detection.
+    steps: [
+      "--sf-duration-instant", "--sf-duration-fast", "--sf-duration-normal",
+      "--sf-duration-slow", "--sf-duration-slower", "--sf-duration-none",
+      "--sf-theme-transition-duration",
+    ],
+  },
+];
+
+const SCALE_STEP_SET = new Set(SCALE_FAMILIES.flatMap((f) => f.steps));
+const SCALE_STEP_TO_FAMILY: Record<string, ScaleFamily> = {};
+for (const f of SCALE_FAMILIES) for (const s of f.steps) SCALE_STEP_TO_FAMILY[s] = f;
+
+/** True when a token is a generated step of one of the scale families. */
+export function isGeneratedScaleStep(name: string): boolean {
+  return SCALE_STEP_SET.has(name);
+}
+
+export interface ScaleShadow {
+  family: ScaleFamily;
+  /** Steps stored as concrete overrides — these freeze the ladder. */
+  shadowedSteps: string[];
+  /** Source knobs the user has also overridden (now partly/fully inert). */
+  overriddenSources: string[];
+}
+
+/**
+ * For each family, which generated steps are shadowed by concrete overrides —
+ * generalising the old text/space-only detector to radius, border-width and
+ * motion too (a gap the audit flagged). Only families with at least one
+ * shadowed step are returned.
+ */
+export function scaleShadows(overrides: Record<string, string>): ScaleShadow[] {
+  const out: ScaleShadow[] = [];
+  for (const family of SCALE_FAMILIES) {
+    // A relink or expression that still references a scale source continues to
+    // follow that scale; only a value disconnected from all sources pins a step.
+    const shadowedSteps = family.steps.filter((step) => {
+      const value = overrides[step];
+      return value !== undefined && !referencesIn(value).some((ref) => family.sources.includes(ref));
+    });
+    if (shadowedSteps.length === 0) continue;
+    const overriddenSources = family.sources.filter((s) => s in overrides);
+    out.push({ family, shadowedSteps, overriddenSources });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+  valid: boolean;
+  reason?: string;
+}
+
+// Characters that would break out of a `--token: value;` declaration or a CSS
+// comment — the same class themeFile.ts / codec.ts already refuse. Rejecting
+// them here stops an invalid value from ever entering the active override map
+// (and fixes the `--sf-x: ;` empty-value export hole).
+const CSS_BREAKING_RE = /[;{}]|\/\*|\*\//;
+const CONTROL_CHAR_RE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+const MAX_CODEC_BYTES = 65_535;
+
+/** Map a token's `syntax` metadata to a real CSS property we can probe. */
+function probePropertyForSyntax(syntax: string | null | undefined): string | null {
+  const s = (syntax ?? "").toLowerCase();
+  if (!s) return null;
+  if (s.includes("<color>")) return "color";
+  if (s.includes("<length>") || s.includes("<length-percentage>")) return "width";
+  if (s.includes("<percentage>")) return "width";
+  // z-index also accepts `auto`, which is not part of CSS <integer>; reject
+  // that keyword explicitly. Opacity preserves fractional <number> support.
+  if (s.includes("<integer>")) return "z-index";
+  if (s.includes("<number>")) return "opacity";
+  if (s.includes("<time>")) return "transition-duration";
+  if (s.includes("<angle>")) return "rotate";
+  return null;
+}
+
+/**
+ * Best-effort validation of an override value for a token. Always applies the
+ * structural checks (non-empty, no CSS-breaking characters). In a browser it
+ * additionally probes `CSS.supports()` against a property matching the token's
+ * declared syntax; under Node/jsdom it stops at the structural checks.
+ *
+ * Values containing `var()`/`calc()`/`clamp()`/`env()` are never syntax-probed
+ * — they resolve at compute time and `CSS.supports` can't judge them — but they
+ * still must pass the structural checks.
+ */
+export function validateTokenValue(token: SlashedToken, value: string): ValidationResult {
+  if (typeof value !== "string") return { valid: false, reason: "not a string" };
+  const v = value.trim();
+  if (v === "") return { valid: false, reason: "empty value" };
+  if (CSS_BREAKING_RE.test(v)) return { valid: false, reason: "contains CSS-breaking characters" };
+  if (CONTROL_CHAR_RE.test(v)) return { valid: false, reason: "contains control characters" };
+  if (new TextEncoder().encode(v).byteLength > MAX_CODEC_BYTES) return { valid: false, reason: "exceeds export size limit" };
+  if (!hasBalancedParens(v)) return { valid: false, reason: "unbalanced parentheses" };
+
+  const syntax = (token.syntax ?? "").toLowerCase();
+  // `auto` is valid z-index syntax, but not a <number> or <integer> token.
+  if ((syntax.includes("<number>") || syntax.includes("<integer>")) && v.toLowerCase() === "auto") {
+    return { valid: false, reason: `not a valid ${token.syntax}` };
+  }
+
+  const hasFn = /\b(?:var|calc|clamp|min|max|env)\s*\(/.test(v);
+  if (!hasFn && typeof CSS !== "undefined" && typeof CSS.supports === "function") {
+    const prop = probePropertyForSyntax(token.syntax);
+    if (prop) {
+      try {
+        if (!CSS.supports(prop, v)) {
+          return { valid: false, reason: `not a valid ${token.syntax}` };
+        }
+      } catch {
+        /* CSS.supports can throw on exotic input — treat as inconclusive. */
+      }
+    }
+  }
+  return { valid: true };
+}
+
+// ---------------------------------------------------------------------------
+// Token state
+// ---------------------------------------------------------------------------
+
+/**
+ * How a token's current override relates to the framework default.
+ *
+ *   default   — no override; the framework value (possibly an alias) is in use.
+ *   custom    — a settable source overridden with a concrete value. Expected.
+ *   relinked  — overridden with a pure `var(--sf-x)`; re-pointed at another
+ *               token (deliberate re-inheritance).
+ *   detached  — a concrete override on an OUTPUT, an ALIAS, or a generated
+ *               scale STEP: it freezes the value and disconnects it from the
+ *               system that would otherwise produce it. The situation the audit
+ *               calls out as easy to create and impossible to notice.
+ *   invalid   — the override value fails validation.
+ */
+export type TokenState = "default" | "custom" | "relinked" | "detached" | "invalid";
+
+export function tokenState(token: SlashedToken, overrides: Record<string, string>): TokenState {
+  const ov = overrides[token.name];
+  if (ov === undefined) return "default";
+  if (!validateTokenValue(token, ov).valid) return "invalid";
+  if (pureVarTarget(ov)) return "relinked";
+  const role = roleOf(token);
+  if (role === "output" || role === "alias" || isGeneratedScaleStep(token.name)) {
+    return "detached";
+  }
+  return "custom";
+}
+
+export const STATE_LABEL: Record<TokenState, string> = {
+  default: "Default",
+  custom: "Custom",
+  relinked: "Re-linked",
+  detached: "Detached",
+  invalid: "Invalid",
+};
+
+/**
+ * True when a token's *default* effective value flows from another token — i.e.
+ * it is an alias or references a scale step by default. Used to show "Inherits
+ * from …" affordances on a token still in its default state.
+ */
+export function inheritsByDefault(token: SlashedToken): boolean {
+  return aliasTargetOf(token) !== null || referencesIn(token.value).length > 0;
+}
diff --git a/configurator/tests/domains.test.ts b/configurator/tests/domains.test.ts
index 2e1bd474..f15b393d 100644
--- a/configurator/tests/domains.test.ts
+++ b/configurator/tests/domains.test.ts
@@ -1,14 +1,17 @@
 /**
  * Unit tests for src/lib/domains.ts — the runtime that routes each token to the
- * panel (domain) it appears under. Previously only exercised indirectly via the
- * curation CLI. `domainOf` is the runtime side of the same contract
- * check:curation guards, so it deserves its own direct lock.
- *
- * Why this matters: `domainOf` and check-curation's classifier must agree — if
- * they drift, a knob can pass CI yet land in the wrong panel (or a phantom one).
+ * panel (domain) it appears under. This is the single classifier shared by the
+ * sidebar badge, the category Reset, the command palette, Home counts and the
+ * All-tokens list, so if it drifts a knob can land in the wrong panel (or a
+ * phantom one). It is now metadata-driven (framework `namespace`), sharing
+ * src/data/domain-map.json with the build-time curation guard.
  */
 import { describe, test, expect } from 'vitest';
-import { domainOf, DOMAIN_PATTERNS } from '../src/lib/domains';
+import {
+  domainOf, classifyKnown, inferNamespace, DOMAINS, FALLBACK_DOMAIN,
+} from '../src/lib/domains';
+import apiIndex from '../src/data/api-index.generated.json';
+import type { ApiIndex } from '../src/types';
 
 describe('domainOf', () => {
   test.each([
@@ -19,32 +22,69 @@ describe('domainOf', () => {
     ['--sf-shadow-m', 'shadows'],
     ['--sf-motion-scale', 'motion'],
     ['--sf-container-wide', 'layout'],
-    ['--sf-btn-pad', 'components'],
+    ['--sf-btn-padding-block', 'components'],
     ['--sf-blur-m', 'effects'],
+    // Namespace-driven fixes for the old substring collisions:
+    ['--sf-drop-shadow-m', 'effects'],   // was "shadows" via the "shadow" fragment
+    ['--sf-focus-ring-color', 'misc'],   // was "colors" via the "color" fragment
+    ['--sf-transition-fast', 'motion'],  // was "misc" (no pattern)
+    ['--sf-box-padding', 'layout'],      // was "misc"
   ])('%s → %s', (name, expected) => {
     expect(domainOf(name)).toBe(expected);
   });
 
   test('an unrecognised name falls back to "misc"', () => {
-    expect(domainOf('--sf-totally-unknown-xyz')).toBe('misc');
+    expect(domainOf('--sf-totally-unknown-xyz')).toBe(FALLBACK_DOMAIN);
   });
 
-  test('a name matching a misc pattern also resolves to "misc"', () => {
-    // z-index tokens legitimately live in the Misc panel.
+  test('misc-namespace tokens resolve to "misc" explicitly (not via fallback)', () => {
     expect(domainOf('--sf-z-modal')).toBe('misc');
     expect(domainOf('--sf-focus-ring-width')).toBe('misc');
+    expect(classifyKnown('--sf-z-modal')).toBe('misc');
   });
 
-  test('never returns a domain key that is absent from DOMAIN_PATTERNS', () => {
-    const keys = new Set(Object.keys(DOMAIN_PATTERNS));
+  test('per-token exceptions override their namespace default', () => {
+    // `content` defaults to spacing, but these two are genuinely elsewhere.
+    expect(domainOf('--sf-content-gap')).toBe('spacing');
+    expect(domainOf('--sf-content-width')).toBe('layout');
+    expect(domainOf('--sf-content-intrinsic-size')).toBe('macros');
+    // `scroll` defaults to motion.
+    expect(domainOf('--sf-scroll-timeline-range-start')).toBe('motion');
+    expect(domainOf('--sf-scroll-shadow-size')).toBe('macros');
+  });
+
+  test('never returns a domain key that is absent from DOMAINS', () => {
+    const keys = new Set<string>(DOMAINS);
     for (const n of ['--sf-color-x', '--sf-unknown', '--sf-z-base', '--sf-btn-y']) {
       expect(keys.has(domainOf(n))).toBe(true);
     }
   });
 
-  test('a more specific domain wins over the misc fallback', () => {
-    // "size-" is a misc pattern, but "--sf-btn-*" should still classify as a
-    // component if it ever collides — this guards the precedence order.
-    expect(domainOf('--sf-container-narrow')).toBe('layout');
+  test('classifyKnown returns null only for unknown namespaces', () => {
+    expect(classifyKnown('--sf-space-m')).toBe('spacing');
+    expect(classifyKnown('--sf-totally-unknown-xyz')).toBeNull();
+  });
+});
+
+describe('inferNamespace', () => {
+  test('extracts the segment after --sf-', () => {
+    expect(inferNamespace('--sf-focus-ring-color')).toBe('focus');
+    expect(inferNamespace('--sf-text-display-scale')).toBe('text');
+    expect(inferNamespace('--sf-h1-size')).toBe('h1');
+  });
+});
+
+describe('real catalogue', () => {
+  const tokens = ((apiIndex as ApiIndex).tokens ?? []);
+
+  test('every shipping token classifies into a known domain (no fall-through)', () => {
+    const orphans = tokens.filter((t) => classifyKnown(t.name) === null).map((t) => t.name);
+    expect(orphans, `namespaces missing from domain-map.json: ${orphans.join(', ')}`).toEqual([]);
+  });
+
+  test('name inference agrees with the framework-authored namespace for every token', () => {
+    for (const t of tokens) {
+      if (t.namespace) expect(inferNamespace(t.name)).toBe(t.namespace);
+    }
   });
 });
diff --git a/configurator/tests/tokenModel.test.ts b/configurator/tests/tokenModel.test.ts
new file mode 100644
index 00000000..ca230d3b
--- /dev/null
+++ b/configurator/tests/tokenModel.test.ts
@@ -0,0 +1,258 @@
+/**
+ * Unit tests for src/lib/tokenModel.ts — the configurator's model of how tokens
+ * relate to each other (role, alias target, dependency graph, override state,
+ * generative scale families, value validation).
+ *
+ * Why this matters: this is the foundation the UX redesign builds on. Every
+ * surface that warns "you are detaching a generated output" or "this inherits
+ * from X" reads from here, so the classification must be pinned. The final
+ * block also runs the model over the *real* baked catalogue to guarantee every
+ * shipping token classifies without throwing and the graph is internally
+ * consistent.
+ */
+import { describe, test, expect } from 'vitest';
+import {
+  referencesIn,
+  pureVarTarget,
+  aliasTargetOf,
+  roleOf,
+  buildDependencyGraph,
+  scaleShadows,
+  isGeneratedScaleStep,
+  validateTokenValue,
+  tokenState,
+  inheritsByDefault,
+  SCALE_FAMILIES,
+} from '../src/lib/tokenModel';
+import type { SlashedToken } from '../src/types';
+import apiIndex from '../src/data/api-index.generated.json';
+import type { ApiIndex } from '../src/types';
+
+const tok = (name: string, over: Partial<SlashedToken> = {}): SlashedToken => ({
+  name,
+  value: '0',
+  ...over,
+});
+
+describe('referencesIn', () => {
+  test('collects every distinct --sf token referenced via var()', () => {
+    expect(referencesIn('color-mix(in oklab, var(--sf-color-a), var(--sf-color-b) 20%)'))
+      .toEqual(['--sf-color-a', '--sf-color-b']);
+  });
+  test('dedupes repeated references', () => {
+    expect(referencesIn('calc(var(--sf-x) + var(--sf-x))')).toEqual(['--sf-x']);
+  });
+  test('empty / literal values yield no references', () => {
+    expect(referencesIn('1rem')).toEqual([]);
+    expect(referencesIn(null)).toEqual([]);
+    expect(referencesIn(undefined)).toEqual([]);
+  });
+});
+
+describe('pureVarTarget', () => {
+  test('matches a bare single-token reference', () => {
+    expect(pureVarTarget('var(--sf-space-m)')).toBe('--sf-space-m');
+  });
+  test('matches a single reference with a fallback', () => {
+    expect(pureVarTarget('var(--sf-gap, 1rem)')).toBe('--sf-gap');
+  });
+  test('rejects compound values that merely use a token', () => {
+    expect(pureVarTarget('var(--sf-border-width-2) solid var(--sf-border)')).toBeNull();
+    expect(pureVarTarget('calc(var(--sf-space-m) * 2)')).toBeNull();
+    expect(pureVarTarget('var(--sf-space-m, 1rem))')).toBeNull();
+    expect(pureVarTarget('1rem')).toBeNull();
+  });
+});
+
+describe('aliasTargetOf', () => {
+  test('prefers the framework-declared aliasOf', () => {
+    expect(aliasTargetOf(tok('--sf-a', { aliasOf: '--sf-b', value: 'anything' }))).toBe('--sf-b');
+  });
+  test('falls back to a pure var() default value', () => {
+    expect(aliasTargetOf(tok('--sf-a', { value: 'var(--sf-b)' }))).toBe('--sf-b');
+  });
+  test('is null for sources and compound outputs', () => {
+    expect(aliasTargetOf(tok('--sf-a', { value: '1rem' }))).toBeNull();
+    expect(aliasTargetOf(tok('--sf-a', { value: 'calc(var(--sf-b) + 1px)' }))).toBeNull();
+  });
+});
+
+describe('roleOf', () => {
+  test('a literal knob is a source', () => {
+    expect(roleOf(tok('--sf-space-base-min', { value: '1', role: 'knob' }))).toBe('source');
+  });
+  test('a pure re-export is an alias', () => {
+    expect(roleOf(tok('--sf-heading-font', { value: 'var(--sf-body-font)', role: 'consumption' }))).toBe('alias');
+  });
+  test('a composed consumption value is an output', () => {
+    expect(roleOf(tok('--sf-x', { value: 'color-mix(in oklab, var(--sf-a), var(--sf-b))', role: 'consumption' }))).toBe('output');
+  });
+  test('aliasOf wins even when role is missing', () => {
+    expect(roleOf(tok('--sf-x', { aliasOf: '--sf-y', value: 'x' }))).toBe('alias');
+  });
+});
+
+describe('buildDependencyGraph', () => {
+  const tokens: SlashedToken[] = [
+    tok('--sf-base', { value: '1rem' }),
+    tok('--sf-mid', { value: 'calc(var(--sf-base) * 2)' }),
+    tok('--sf-top', { value: 'var(--sf-mid)' }),
+    tok('--sf-selfref', { value: 'var(--sf-selfref)' }), // pathological; must not self-link
+    tok('--sf-ext', { value: 'var(--sf-not-in-catalogue)' }),
+  ];
+  const g = buildDependencyGraph(tokens);
+
+  test('dependsOn lists direct references within the catalogue', () => {
+    expect(g.dependsOn['--sf-mid']).toEqual(['--sf-base']);
+    expect(g.dependsOn['--sf-top']).toEqual(['--sf-mid']);
+  });
+  test('usedBy is the reverse edge', () => {
+    expect(g.usedBy['--sf-base']).toEqual(['--sf-mid']);
+    expect(g.usedBy['--sf-mid']).toEqual(['--sf-top']);
+  });
+  test('ignores self-references and unknown targets', () => {
+    expect(g.dependsOn['--sf-selfref']).toEqual([]);
+    expect(g.dependsOn['--sf-ext']).toEqual([]);
+  });
+});
+
+describe('scale families & shadowing', () => {
+  test('generated steps are recognised across all families', () => {
+    expect(isGeneratedScaleStep('--sf-space-l')).toBe(true);
+    expect(isGeneratedScaleStep('--sf-radius-m')).toBe(true);
+    expect(isGeneratedScaleStep('--sf-border-width-2')).toBe(true);
+    expect(isGeneratedScaleStep('--sf-duration-normal')).toBe(true);
+    expect(isGeneratedScaleStep('--sf-space-base-min')).toBe(false); // a source, not a step
+  });
+
+  test('detects shadowed steps for radius/border/motion — the gap the audit flagged', () => {
+    const shadows = scaleShadows({
+      '--sf-radius-m': '10px',
+      '--sf-radius-scale': '1.5',
+      '--sf-border-width-2': '3px',
+      '--sf-duration-normal': '400ms',
+    });
+    const byId = Object.fromEntries(shadows.map((s) => [s.family.id, s]));
+    expect(byId.radius.shadowedSteps).toEqual(['--sf-radius-m']);
+    expect(byId.radius.overriddenSources).toEqual(['--sf-radius-scale']);
+    expect(byId['border-width'].shadowedSteps).toEqual(['--sf-border-width-2']);
+    expect(byId.motion.shadowedSteps).toEqual(['--sf-duration-normal']);
+  });
+
+  test('does not mark scale-linked expressions as pinned', () => {
+    const shadows = scaleShadows({
+      '--sf-radius-m': 'var(--sf-radius-scale)',
+      '--sf-radius-l': 'calc(var(--sf-radius-scale) * 2)',
+      '--sf-radius-none': '0px',
+    });
+    expect(shadows).toHaveLength(1);
+    expect(shadows[0].shadowedSteps).toEqual(['--sf-radius-none']);
+  });
+
+  test('no shadows reported when only sources are overridden', () => {
+    expect(scaleShadows({ '--sf-space-scale': '1.2' })).toEqual([]);
+  });
+});
+
+describe('validateTokenValue', () => {
+  const t = tok('--sf-x', { syntax: '<length>' });
+  test('rejects empty and CSS-breaking values', () => {
+    expect(validateTokenValue(t, '').valid).toBe(false);
+    expect(validateTokenValue(t, '   ').valid).toBe(false);
+    expect(validateTokenValue(t, '1rem; }').valid).toBe(false);
+    expect(validateTokenValue(t, 'red /* x */').valid).toBe(false);
+    expect(validateTokenValue(t, 'red\u0000').valid).toBe(false);
+    expect(validateTokenValue(t, 'x'.repeat(65_536)).valid).toBe(false);
+  });
+  test('accepts plain values and expressions under Node (structural only)', () => {
+    expect(validateTokenValue(t, '1rem').valid).toBe(true);
+    expect(validateTokenValue(t, 'clamp(1rem, 2vw, 3rem)').valid).toBe(true);
+    expect(validateTokenValue(t, 'var(--sf-space-m)').valid).toBe(true);
+  });
+  test('keeps numeric grammar distinct from z-index', () => {
+    const number = tok('--sf-ratio', { syntax: '<number>' });
+    const integer = tok('--sf-layer', { syntax: '<integer>' });
+    expect(validateTokenValue(number, '1.25').valid).toBe(true);
+    expect(validateTokenValue(number, 'auto').valid).toBe(false);
+    expect(validateTokenValue(integer, 'auto').valid).toBe(false);
+  });
+  test('rejects malformed expressions rather than treating them as safe', () => {
+    expect(validateTokenValue(t, 'var(--sf-space-m, 1rem))').valid).toBe(false);
+  });
+});
+
+describe('tokenState', () => {
+  const source = tok('--sf-space-base-min', { value: '1', role: 'knob' });
+  const alias = tok('--sf-heading-font', { value: 'var(--sf-body-font)', role: 'consumption' });
+  const output = tok('--sf-x', { value: 'color-mix(in oklab, var(--sf-a), var(--sf-b))', role: 'consumption' });
+  const step = tok('--sf-radius-m', { value: '8px', role: 'knob' });
+
+  test('no override → default', () => {
+    expect(tokenState(source, {})).toBe('default');
+  });
+  test('concrete override on a source → custom', () => {
+    expect(tokenState(source, { '--sf-space-base-min': '1.1' })).toBe('custom');
+  });
+  test('pure var override → relinked (deliberate re-inheritance)', () => {
+    expect(tokenState(source, { '--sf-space-base-min': 'var(--sf-space-s)' })).toBe('relinked');
+  });
+  test('concrete override on an output → detached', () => {
+    expect(tokenState(output, { '--sf-x': 'red' })).toBe('detached');
+  });
+  test('concrete override on an alias → detached', () => {
+    expect(tokenState(alias, { '--sf-heading-font': 'Georgia, serif' })).toBe('detached');
+  });
+  test('concrete override on a generated scale step → detached', () => {
+    expect(tokenState(step, { '--sf-radius-m': '10px' })).toBe('detached');
+  });
+  test('invalid value wins over everything', () => {
+    expect(tokenState(source, { '--sf-space-base-min': '1; }' })).toBe('invalid');
+    expect(tokenState(source, { '--sf-space-base-min': 'var(--sf-space-m, 1rem))' })).toBe('invalid');
+  });
+});
+
+describe('inheritsByDefault', () => {
+  test('true for aliases and tokens that reference others', () => {
+    expect(inheritsByDefault(tok('--sf-a', { value: 'var(--sf-b)' }))).toBe(true);
+    expect(inheritsByDefault(tok('--sf-a', { value: 'calc(var(--sf-b) + 1px)' }))).toBe(true);
+  });
+  test('false for literal sources', () => {
+    expect(inheritsByDefault(tok('--sf-a', { value: '1rem' }))).toBe(false);
+  });
+});
+
+// --- Real catalogue: the model must survive every shipping token ------------
+describe('real baked catalogue', () => {
+  const tokens = ((apiIndex as ApiIndex).tokens ?? []) as SlashedToken[];
+
+  test('catalogue is non-trivial', () => {
+    expect(tokens.length).toBeGreaterThan(500);
+  });
+
+  test('every token classifies into a role without throwing', () => {
+    const counts: Record<string, number> = { source: 0, alias: 0, output: 0 };
+    for (const t of tokens) counts[roleOf(t)]++;
+    expect(counts.source).toBeGreaterThan(0);
+    expect(counts.alias).toBeGreaterThan(0);
+    expect(counts.output).toBeGreaterThan(0);
+    expect(counts.source + counts.alias + counts.output).toBe(tokens.length);
+  });
+
+  test('dependency graph is internally consistent (every usedBy edge has a matching dependsOn)', () => {
+    const g = buildDependencyGraph(tokens);
+    for (const [target, dependents] of Object.entries(g.usedBy)) {
+      for (const dep of dependents) {
+        expect(g.dependsOn[dep]).toContain(target);
+      }
+    }
+  });
+
+  test('every scale-family source and step is a real token in the catalogue', () => {
+    const names = new Set(tokens.map((t) => t.name));
+    for (const family of SCALE_FAMILIES) {
+      for (const s of [...family.sources, ...family.steps]) {
+        expect(names.has(s), `${s} (family ${family.id}) should exist in the catalogue`).toBe(true);
+      }
+    }
+  });
+});