From 0d6aa4625ecb31ebd6ae9660a3c20fbea4f97397 Mon Sep 17 00:00:00 2001
From: Kiro Agent <244629292+kiro-agent@users.noreply.github.com>
Date: Wed, 19 Aug 2026 21:29:49 +0000
Subject: [PATCH 1/3] feat(configurator): add token relationship model and
 surface roles/state in All tokens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce src/lib/tokenModel.ts, the configurator's first-class understanding
of how tokens relate — derived from the framework manifest (role, aliasOf,
namespace, value) instead of re-guessing from names:

- roleOf: source | alias | output
- aliasTargetOf / referencesIn / pureVarTarget
- buildDependencyGraph: whole-catalogue dependsOn / usedBy
- SCALE_FAMILIES + scaleShadows: generalise scale-step shadow detection to
  radius, border-width and motion (previously only text/space)
- validateTokenValue: reject empty / CSS-breaking values (closes the "--x: ;"
  export hole) with optional CSS.supports probing in the browser
- tokenState: default | custom | relinked | detached | invalid

Wire it into the All tokens screen (TokenRow/AllTokensTab): each row now shows
a role badge, its alias source ("inherits X"), a "used by N" dependents count,
and an explicit Detached/Invalid warning with a one-click restore — directly
addressing the audit findings that outputs were editable like knobs with no
dependency context and detachment was invisible.

Adds tests/tokenModel.test.ts (34 tests incl. a guard over the real baked
catalogue). check, lint and all 244 unit tests pass.
---
 .../src/components/inputs/TokenRow.svelte     |  75 +++-
 .../src/components/panels/AllTokensTab.svelte |   6 +
 configurator/src/lib/tokenModel.ts            | 356 ++++++++++++++++++
 configurator/tests/tokenModel.test.ts         | 234 ++++++++++++
 4 files changed, 669 insertions(+), 2 deletions(-)
 create mode 100644 configurator/src/lib/tokenModel.ts
 create mode 100644 configurator/tests/tokenModel.test.ts

diff --git a/configurator/src/components/inputs/TokenRow.svelte b/configurator/src/components/inputs/TokenRow.svelte
index 6fae647a..ad14a196 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" : ""} read this value`}>
+          used by {dependentsCount}
+        </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..f144e4bf 100644
--- a/configurator/src/components/panels/AllTokensTab.svelte
+++ b/configurator/src/components/panels/AllTokensTab.svelte
@@ -1,6 +1,7 @@
 <script lang="ts">
   import type { SlashedToken } from '../../types';
   import TokenRow from '../inputs/TokenRow.svelte';
+  import { buildDependencyGraph } from '../../lib/tokenModel';
 
   let { tokens, overrides, patterns, onSet, onReset }: {
     tokens: SlashedToken[];
@@ -12,6 +13,10 @@
 
   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);
@@ -141,6 +146,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/lib/tokenModel.ts b/configurator/src/lib/tokenModel.ts
new file mode 100644
index 00000000..eb234877
--- /dev/null
+++ b/configurator/src/lib/tokenModel.ts
@@ -0,0 +1,356 @@
+/**
+ * @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]*)?\)$/;
+
+/** 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) 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"),
+  },
+  {
+    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) {
+    const shadowedSteps = family.steps.filter((s) => s in overrides);
+    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 = /[;{}]|\/\*|\*\//;
+
+/** 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";
+  if (s.includes("<number>") || s.includes("<integer>")) return "z-index";
+  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" };
+
+  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/tokenModel.test.ts b/configurator/tests/tokenModel.test.ts
new file mode 100644
index 00000000..90b8a9b2
--- /dev/null
+++ b/configurator/tests/tokenModel.test.ts
@@ -0,0 +1,234 @@
+/**
+ * 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('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('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);
+  });
+  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);
+  });
+});
+
+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');
+  });
+});
+
+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);
+      }
+    }
+  });
+});

From 127792507092d11cad8e837b46f753f5500ac749 Mon Sep 17 00:00:00 2001
From: Kiro Agent <244629292+kiro-agent@users.noreply.github.com>
Date: Thu, 20 Aug 2026 05:01:18 +0000
Subject: [PATCH 2/3] fix(configurator): validate token overrides accurately

---
 configurator/src/lib/tokenModel.ts    | 36 ++++++++++++++++++++++++---
 configurator/tests/tokenModel.test.ts | 22 ++++++++++++++++
 2 files changed, 54 insertions(+), 4 deletions(-)

diff --git a/configurator/src/lib/tokenModel.ts b/configurator/src/lib/tokenModel.ts
index eb234877..4c2ef84a 100644
--- a/configurator/src/lib/tokenModel.ts
+++ b/configurator/src/lib/tokenModel.ts
@@ -46,6 +46,16 @@ const VAR_REF_RE = /var\(\s*(--sf-[\w-]+)/g;
 // 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 [];
@@ -58,7 +68,7 @@ export function referencesIn(value: string | null | undefined): string[] {
 
 /** The single token a pure `var(--sf-x)` value points at, else null. */
 export function pureVarTarget(value: string | null | undefined): string | null {
-  if (!value) return null;
+  if (!value || !hasBalancedParens(value)) return null;
   const m = PURE_VAR_RE.exec(value.trim());
   return m ? m[1] : null;
 }
@@ -189,7 +199,10 @@ export const SCALE_FAMILIES: ScaleFamily[] = [
     id: "radius",
     label: "Radius scale",
     sources: ["--sf-radius-scale"],
-    steps: stepTokens("radius"),
+    steps: [
+      ...stepTokens("radius"),
+      "--sf-radius-none", "--sf-radius-full", "--sf-radius-pill", "--sf-radius-outer",
+    ],
   },
   {
     id: "border-width",
@@ -239,7 +252,12 @@ export interface ScaleShadow {
 export function scaleShadows(overrides: Record<string, string>): ScaleShadow[] {
   const out: ScaleShadow[] = [];
   for (const family of SCALE_FAMILIES) {
-    const shadowedSteps = family.steps.filter((s) => s in overrides);
+    // 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 });
@@ -269,7 +287,10 @@ function probePropertyForSyntax(syntax: string | null | undefined): string | nul
   if (s.includes("<color>")) return "color";
   if (s.includes("<length>") || s.includes("<length-percentage>")) return "width";
   if (s.includes("<percentage>")) return "width";
-  if (s.includes("<number>") || s.includes("<integer>")) return "z-index";
+  // 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;
@@ -290,6 +311,13 @@ export function validateTokenValue(token: SlashedToken, value: string): Validati
   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 (!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") {
diff --git a/configurator/tests/tokenModel.test.ts b/configurator/tests/tokenModel.test.ts
index 90b8a9b2..ea36c71a 100644
--- a/configurator/tests/tokenModel.test.ts
+++ b/configurator/tests/tokenModel.test.ts
@@ -59,6 +59,7 @@ describe('pureVarTarget', () => {
   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();
   });
 });
@@ -138,6 +139,16 @@ describe('scale families & shadowing', () => {
     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([]);
   });
@@ -156,6 +167,16 @@ describe('validateTokenValue', () => {
     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', () => {
@@ -184,6 +205,7 @@ describe('tokenState', () => {
   });
   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');
   });
 });
 

From 03663624bfa020a7619bf14e68727fb49a55a878 Mon Sep 17 00:00:00 2001
From: Kiro Agent <244629292+kiro-agent@users.noreply.github.com>
Date: Thu, 20 Aug 2026 05:12:13 +0000
Subject: [PATCH 3/3] fix(configurator): align token safety with export limits

---
 configurator/src/lib/tokenModel.ts    | 4 ++++
 configurator/tests/tokenModel.test.ts | 2 ++
 2 files changed, 6 insertions(+)

diff --git a/configurator/src/lib/tokenModel.ts b/configurator/src/lib/tokenModel.ts
index 4c2ef84a..5fe1f579 100644
--- a/configurator/src/lib/tokenModel.ts
+++ b/configurator/src/lib/tokenModel.ts
@@ -279,6 +279,8 @@ export interface ValidationResult {
 // 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 {
@@ -311,6 +313,8 @@ export function validateTokenValue(token: SlashedToken, value: string): Validati
   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();
diff --git a/configurator/tests/tokenModel.test.ts b/configurator/tests/tokenModel.test.ts
index ea36c71a..ca230d3b 100644
--- a/configurator/tests/tokenModel.test.ts
+++ b/configurator/tests/tokenModel.test.ts
@@ -161,6 +161,8 @@ describe('validateTokenValue', () => {
     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);