@usefragments/core 1.0.0

package/src/rules/theme-no-theme-coupled-literal.ts

@@ -0,0 +1,132 @@
+import type { FactIndex } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+
+export const RULE_ID = "theme/no-theme-coupled-literal";
+export const RULE_VERSION = "1";
+
+const COLOR_LITERAL_GLOBAL =
+  /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?|oklab|oklch|lab|lch)\(\s*[\d.%\s,\/]+\s*\)/g;
+const WHITE_RGBA = /^rgba?\(\s*255\s*,\s*255\s*,\s*255/i;
+const BLACK_RGBA = /^rgba?\(\s*0\s*,\s*0\s*,\s*0/i;
+const COLOR_MIX_OPEN = "color-mix(";
+const BOX_SHADOW_PROP = /^(?:-webkit-|-moz-)?box-shadow$/i;
+const NEUTRAL_SHADOW = /^(?:none|inherit|initial|unset|revert|revert-layer)\s*$/i;
+
+export function ruleThemeNoThemeCoupledLiteral(ix: FactIndex): Finding[] {
+  const policy = ix.policy.ruleConfig(RULE_ID);
+  if (!policy?.enabled) return [];
+
+  const findings: Finding[] = [];
+  for (const decl of ix.byKind("style_declaration")) {
+    if (isTokenFile(decl.file)) continue;
+    const hit = findThemeCoupledLiteral(decl.property, decl.value);
+    if (!hit) continue;
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity ?? "warn",
+        message: hit.message,
+        location: decl.location,
+        evidence: ix.evidence([decl.id, policy.id]),
+        fingerprintIdentity: {
+          file: decl.file,
+          selector: decl.selector,
+          declarationPath: decl.declarationPath,
+          property: decl.property,
+          rawValue: hit.rawValue,
+          reason: hit.reason,
+        },
+        attributes: {
+          property: decl.property,
+          rawValue: decl.value,
+          color: hit.rawValue,
+          suggestion: hit.suggestion,
+          source: "css",
+        },
+      }),
+    );
+  }
+
+  return findings;
+}
+
+function findThemeCoupledLiteral(
+  property: string,
+  value: string,
+): { rawValue: string; reason: string; message: string; suggestion: string } | null {
+  COLOR_LITERAL_GLOBAL.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = COLOR_LITERAL_GLOBAL.exec(value)) !== null) {
+    const raw = match[0];
+    if (insideLightDark(value, match.index)) continue;
+
+    if (insideColorMix(value, match.index)) {
+      return {
+        rawValue: raw,
+        reason: "color-mix",
+        message: `color-mix() argument ${raw} is theme-coupled. Use a semantic token or wrap the declaration in light-dark(...).`,
+        suggestion: `Replace ${raw} with a semantic token or light-dark(...)`,
+      };
+    }
+
+    if (BOX_SHADOW_PROP.test(property) && !NEUTRAL_SHADOW.test(value.trim())) {
+      return {
+        rawValue: raw,
+        reason: "box-shadow",
+        message: `Custom box-shadow with literal color ${raw} is theme-coupled. Use a shadow/elevation token or light-dark(...).`,
+        suggestion: "Use a shadow/elevation token or light-dark(...)",
+      };
+    }
+
+    if (WHITE_RGBA.test(raw) || BLACK_RGBA.test(raw)) {
+      return {
+        rawValue: raw,
+        reason: "white-black-rgba",
+        message: `Raw ${raw} assumes one theme. Wrap it in light-dark(...) or use a semantic token.`,
+        suggestion: WHITE_RGBA.test(raw)
+          ? `light-dark(/* TODO light-theme equivalent */, ${raw})`
+          : `light-dark(${raw}, /* TODO dark-theme equivalent */)`,
+      };
+    }
+  }
+
+  return null;
+}
+
+function insideLightDark(value: string, index: number): boolean {
+  return enclosingFunctionName(value, index) === "light-dark";
+}
+
+function insideColorMix(value: string, index: number): boolean {
+  return enclosingFunctionName(value, index) === "color-mix";
+}
+
+function enclosingFunctionName(value: string, index: number): string | null {
+  let depth = 0;
+  for (let i = index - 1; i >= 0; i--) {
+    const ch = value[i];
+    if (ch === ")") {
+      depth++;
+      continue;
+    }
+    if (ch !== "(") continue;
+    if (depth > 0) {
+      depth--;
+      continue;
+    }
+    const before = value.slice(0, i).match(/([a-z-]+)\s*$/i);
+    return before?.[1]?.toLowerCase() ?? null;
+  }
+  return null;
+}
+
+function isTokenFile(filePath: string): boolean {
+  const normalized = filePath.replace(/\\/g, "/");
+  const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+  if (base === "_tokens.scss" || base === "tokens.scss") return true;
+  return base.startsWith("_") && /(^|\/)tokens\//.test(normalized);
+}

package/src/rules/tiers.ts

@@ -0,0 +1,111 @@
+/**
+ * Rule taxonomy — the single source of truth for tier classification.
+ *
+ * Every governance rule is either:
+ *   - **Tier A (contract vocabulary)** — measures drift from a vocabulary the
+ *     team *declared* (the two-choice contract: canonical components + token
+ *     source files). Headline-eligible; on by default but *inert until a
+ *     contract is authored* (each Tier-A rule self-gates on its contract facts).
+ *   - **Tier B (generic hygiene)** — generic best-practice opinions (raw values,
+ *     a11y, theme literals, Tailwind). Never the headline; off by default for
+ *     customers, opt-in per rule.
+ *
+ * This map is consumed by the core customer-default preset (`./presets.ts`), the
+ * cloud policy composer, and the UI rules editor. There is exactly one copy —
+ * importers derive their defaults from it rather than re-listing rules (DRY).
+ *
+ * Identifiers are stable: this introduces no new rule ids, it only attaches a
+ * tier label to existing ones.
+ */
+
+export type RuleTier = "contract" | "hygiene";
+
+/**
+ * Tier of every rule in `RULES`. Tier A is exactly the two-choice-contract
+ * rules; everything else is hygiene. A coverage test asserts this map and
+ * `RULES` stay in lock-step (every rule id classified, no strays).
+ */
+export const RULE_TIER: Readonly<Record<string, RuleTier>> = {
+  // ---- Tier A — contract vocabulary -------------------------------------
+  "components/prefer-library": "contract", // canonical-component bypass (FUI1001/1004)
+  "tokens/css-vars-must-be-defined": "contract", // token drift (FUI2015)
+
+  // ---- Tier B — generic hygiene -----------------------------------------
+  "components/unknown-prop": "hygiene",
+  "components/forbidden-prop-value": "hygiene",
+  "props/invalid-value": "hygiene",
+  "imports/preferred-path": "hygiene",
+  "components/preferred-component": "hygiene",
+  "styles/no-raw-color": "hygiene",
+  "styles/no-raw-dimensions": "hygiene",
+  "styles/no-raw-spacing": "hygiene",
+  "styles/no-raw-typography": "hygiene",
+  "tailwind/arbitrary-color": "hygiene",
+  "tailwind/arbitrary-spacing": "hygiene",
+  "tailwind/forbidden-palette": "hygiene",
+  "tailwind/off-scale-spacing-token": "hygiene",
+  "tailwind/raw-color-via-token": "hygiene",
+  "tailwind/unknown-class": "hygiene",
+  "tokens/require-dual-fallback": "hygiene",
+  "theme/no-theme-coupled-literal": "hygiene",
+  "a11y/required-accessible-name": "hygiene",
+  // Composition constraints are authored contracts, but not part of the
+  // two-choice headline contract; they self-activate when patterns are declared
+  // (the compiler injects their configs), so off-by-default here is harmless.
+  "composition/cardinality": "hygiene",
+  "composition/co-occurrence": "hygiene",
+};
+
+/**
+ * Rules removed from the customer default preset *entirely* — Fragments-internal
+ * conventions that are meaningless on a customer repo. They remain available
+ * under the full `fragments` preset for Fragments' own dogfooding; they are
+ * never even an opt-in toggle in the customer default.
+ *
+ * `tokens/require-dual-fallback` — the `var(--x, $x)` SCSS micro-convention —
+ * was ~51% of the dogfood flood and is the canonical example.
+ */
+export const FRAGMENTS_INTERNAL_RULE_IDS: ReadonlySet<string> = new Set([
+  "tokens/require-dual-fallback",
+]);
+
+/** Tier of a rule id. Unknown ids fail safe to `hygiene` (off by default). */
+export function tierFor(ruleId: string): RuleTier {
+  return RULE_TIER[ruleId] ?? "hygiene";
+}
+
+/** True when the rule measures declared-contract drift (headline-eligible). */
+export function isContractTierRule(ruleId: string): boolean {
+  return tierFor(ruleId) === "contract";
+}
+
+/** All Tier-A (contract vocabulary) rule ids, in declaration order. */
+export function contractTierRuleIds(): string[] {
+  return Object.keys(RULE_TIER).filter(isContractTierRule);
+}
+
+/** All Tier-B (generic hygiene) rule ids, in declaration order. */
+export function hygieneTierRuleIds(): string[] {
+  return Object.keys(RULE_TIER).filter((id) => !isContractTierRule(id));
+}
+
+/**
+ * Vocabulary-first headline order: canonical-component bypass ranks above token
+ * drift, both above any hygiene. This is the SSOT the dashboard headline (brief
+ * 05) consumes so "vocabulary-first" is defined once, not re-encoded per surface.
+ */
+const VOCABULARY_ORDER: readonly string[] = [
+  "components/prefer-library",
+  "tokens/css-vars-must-be-defined",
+];
+
+/** Headline rank of a rule id (lower = higher in the vocabulary-first list). */
+export function vocabularyRank(ruleId: string): number {
+  const index = VOCABULARY_ORDER.indexOf(ruleId);
+  return index >= 0 ? index : VOCABULARY_ORDER.length;
+}
+
+/** Comparator ordering rule ids vocabulary-first (Tier A before hygiene). */
+export function compareByVocabularyRank(a: string, b: string): number {
+  return vocabularyRank(a) - vocabularyRank(b);
+}

package/src/rules/tokens-css-vars-must-be-defined.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  FactIndex,
+  makeContractTokenFact,
+  makeStyleCssVarsMustBeDefinedFact,
+  makeStyleDeclarationFact,
+} from "../index.js";
+import type { Fact } from "../index.js";
+import { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+
+/**
+ * ACCEPTANCE §4 (rule level) + §11 (regression lock).
+ *
+ * The off-contract-token rule (FUI2015) is INERT unless the contract declares
+ * the `style.cssVars.mustBeDefined` policy fact — the cloud appends it only when
+ * `tokenSourceFiles` is non-empty, so the `fragments` preset alone never
+ * activates it. When active, a `var(--x)` drifts iff `--x` shares the authored
+ * vocabulary's prefix family but is not in the vocabulary; genuinely-foreign
+ * custom properties are ignored (no false-positive flood — the original revert).
+ */
+
+const POLICY = makeStyleCssVarsMustBeDefinedFact({ severity: "warn" });
+
+function vocabulary(): Fact[] {
+  return [
+    makeContractTokenFact({ name: "--fui-color-accent" }),
+    makeContractTokenFact({ name: "--fui-space-2" }),
+  ];
+}
+
+function decl(selector: string, value: string): Fact {
+  const file = "src/Card.module.scss";
+  return makeStyleDeclarationFact({
+    file,
+    selector,
+    declarationPath: selector,
+    property: "color",
+    value,
+    location: { file, line: 1, column: 0 },
+  });
+}
+
+function index(facts: Fact[]): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(facts);
+  return ix;
+}
+
+describe("ruleTokensCssVarsMustBeDefined", () => {
+  it("flags an off-contract token that shares the contract prefix family (§4)", () => {
+    const ix = index([POLICY, ...vocabulary(), decl(".b", "var(--fui-color-brand)")]);
+
+    const findings = ruleTokensCssVarsMustBeDefined(ix);
+    expect(findings).toHaveLength(1);
+    // `warn` (governance severity) normalizes to `moderate` at the finding level.
+    expect(findings[0].severity).toBe("moderate");
+    expect(findings[0].attributes).toMatchObject({ tokenName: "--fui-color-brand" });
+  });
+
+  it("does NOT flag an in-contract token reference (§4)", () => {
+    const ix = index([
+      POLICY,
+      ...vocabulary(),
+      decl(".c", "var(--fui-color-accent, $fui-color-accent)"),
+    ]);
+
+    expect(ruleTokensCssVarsMustBeDefined(ix)).toHaveLength(0);
+  });
+
+  it("does NOT flag a genuinely-foreign var that shares no contract prefix (§4)", () => {
+    // `--brand-blue` / `--swiper-*` are outside the `--fui-` family — ignored,
+    // exactly the false positives that got the original brief reverted.
+    const ix = index([
+      POLICY,
+      ...vocabulary(),
+      decl(".x", "var(--brand-blue)"),
+      decl(".y", "var(--swiper-theme-color)"),
+    ]);
+
+    expect(ruleTokensCssVarsMustBeDefined(ix)).toHaveLength(0);
+  });
+
+  it("flags a locally-defined parallel custom property even when it has no shared prefix", () => {
+    const file = "src/landing.scss";
+    const ix = index([
+      POLICY,
+      ...vocabulary(),
+      makeStyleDeclarationFact({
+        file,
+        selector: ":root",
+        declarationPath: "0",
+        property: "--lp-accent",
+        value: "#39594d",
+        location: { file, line: 1, column: 0 },
+      }),
+      makeStyleDeclarationFact({
+        file,
+        selector: ".hero",
+        declarationPath: "1",
+        property: "color",
+        value: "var(--lp-accent)",
+        location: { file, line: 4, column: 2 },
+      }),
+      decl(".swiper", "var(--swiper-theme-color)"),
+    ]);
+
+    const findings = ruleTokensCssVarsMustBeDefined(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].attributes).toMatchObject({ tokenName: "--lp-accent" });
+  });
+
+  it("is INERT without the activation policy fact, even with off-contract vars (§11)", () => {
+    // No `style.cssVars.mustBeDefined` fact → the `fragments` preset alone never
+    // fires the rule. This is the regression lock at the rule boundary.
+    const ix = index([...vocabulary(), decl(".b", "var(--fui-color-brand)")]);
+
+    expect(ruleTokensCssVarsMustBeDefined(ix)).toHaveLength(0);
+  });
+
+  it("is INERT when the contract vocabulary is empty (no token definitions)", () => {
+    const ix = index([POLICY, decl(".b", "var(--fui-color-brand)")]);
+
+    expect(ruleTokensCssVarsMustBeDefined(ix)).toHaveLength(0);
+  });
+
+  // #33 — CSS function names are case-insensitive; VAR()/Var() must be detected.
+  it("detects an off-contract token through case-insensitive VAR()/Var() (#33)", () => {
+    const ix = index([
+      POLICY,
+      ...vocabulary(),
+      decl(".b", "VAR(--fui-color-brand)"),
+      decl(".c", "Var(--fui-color-brand)"),
+    ]);
+
+    const findings = ruleTokensCssVarsMustBeDefined(ix);
+    expect(findings).toHaveLength(2);
+    expect(findings[0].attributes).toMatchObject({ tokenName: "--fui-color-brand" });
+  });
+
+  // #17 — only the PRIMARY var() position is judged; a nested fallback var() that
+  // is off-contract must NOT be flagged.
+  it("ignores an off-contract var in nested FALLBACK position (#17)", () => {
+    const ix = index([
+      POLICY,
+      ...vocabulary(),
+      decl(".c", "var(--fui-color-accent, var(--fui-color-brand))"),
+    ]);
+
+    expect(ruleTokensCssVarsMustBeDefined(ix)).toHaveLength(0);
+  });
+
+  it("flags an off-contract PRIMARY even when its fallback is in-contract (#17)", () => {
+    const ix = index([
+      POLICY,
+      ...vocabulary(),
+      decl(".d", "var(--fui-color-brand, var(--fui-color-accent))"),
+    ]);
+
+    const findings = ruleTokensCssVarsMustBeDefined(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].attributes).toMatchObject({ tokenName: "--fui-color-brand" });
+  });
+
+  // #11 — one off-contract var referenced twice in ONE declaration is one fact.
+  it("dedupes the same off-contract var WITHIN one declaration (#11)", () => {
+    const ix = index([
+      POLICY,
+      ...vocabulary(),
+      decl(".b", "0 0 0 1px var(--fui-color-brand), inset 0 0 0 1px var(--fui-color-brand)"),
+    ]);
+
+    expect(ruleTokensCssVarsMustBeDefined(ix)).toHaveLength(1);
+  });
+
+  it("does NOT dedupe the same off-contract var across SEPARATE declarations (#11)", () => {
+    const ix = index([
+      POLICY,
+      ...vocabulary(),
+      decl(".b", "var(--fui-color-brand)"),
+      decl(".c", "var(--fui-color-brand)"),
+    ]);
+
+    expect(ruleTokensCssVarsMustBeDefined(ix)).toHaveLength(2);
+  });
+
+  // #22/#25/#31/#36 — a FLAT vocabulary (single-segment names, no prefix family)
+  // must still enforce drift; multi-segment foreign vars stay ignored.
+  it("enforces drift for a FLAT (single-segment) vocabulary (#22/#25/#31/#36)", () => {
+    const flat = (): Fact[] => [
+      makeContractTokenFact({ name: "--accent" }),
+      makeContractTokenFact({ name: "--bg" }),
+    ];
+
+    expect(
+      ruleTokensCssVarsMustBeDefined(index([POLICY, ...flat(), decl(".b", "var(--brand)")]))
+    ).toHaveLength(1);
+
+    // Multi-segment foreign var stays ignored even in flat mode.
+    expect(
+      ruleTokensCssVarsMustBeDefined(
+        index([POLICY, ...flat(), decl(".x", "var(--swiper-theme-color)")])
+      )
+    ).toHaveLength(0);
+
+    // In-contract flat ref is fine.
+    expect(
+      ruleTokensCssVarsMustBeDefined(index([POLICY, ...flat(), decl(".y", "var(--accent)")]))
+    ).toHaveLength(0);
+  });
+
+  // #18 — a MIXED vocabulary (namespaced + flat) enforces BOTH namespaces
+  // symmetrically, order-independently; multi-segment foreign stays ignored.
+  it("enforces BOTH halves of a MIXED namespaced+flat vocabulary (#18)", () => {
+    const mixed = (): Fact[] => [
+      makeContractTokenFact({ name: "--fui-color-accent" }),
+      makeContractTokenFact({ name: "--accent" }),
+    ];
+
+    const findings = ruleTokensCssVarsMustBeDefined(
+      index([
+        POLICY,
+        ...mixed(),
+        decl(".a", "var(--fui-color-brand)"), // namespaced drift
+        decl(".b", "var(--bg)"), // flat drift
+        decl(".c", "var(--swiper-theme-color)"), // foreign multi-segment, ignored
+      ])
+    );
+    expect(findings).toHaveLength(2);
+
+    // Determinism: reversed token add-order yields identical findings count.
+    const reversed = ruleTokensCssVarsMustBeDefined(
+      index([
+        POLICY,
+        makeContractTokenFact({ name: "--accent" }),
+        makeContractTokenFact({ name: "--fui-color-accent" }),
+        decl(".a", "var(--fui-color-brand)"),
+        decl(".b", "var(--bg)"),
+        decl(".c", "var(--swiper-theme-color)"),
+      ])
+    );
+    expect(reversed).toHaveLength(2);
+  });
+});

package/src/rules/tokens-css-vars-must-be-defined.ts

@@ -0,0 +1,156 @@
+import type { FactIndex } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import { contractPrefixFamilies } from "./utils.js";
+
+export const RULE_ID = "tokens/css-vars-must-be-defined";
+export const RULE_VERSION = "1";
+
+// The leading `var(--name` of a reference. The `var(` keyword is matched
+// case-insensitively (CSS function names are case-insensitive per spec, so
+// `VAR(`/`Var(` must be caught — #33) but the captured custom-property name stays
+// case-preserving (custom-property names ARE case-sensitive; vocabulary.has must
+// stay exact). We judge ONLY the PRIMARY var() position — everything in fallback
+// position (a nested `var()`, a `$`/literal fallback) is ignored uniformly (#17):
+// after each match we skip past this var()'s matching close-paren so an inner
+// fallback var() is never re-scanned as a fresh primary.
+const CSS_VAR_REFERENCE = /var\(\s*(--[A-Za-z0-9_-]+)/gi;
+
+/**
+ * Off-contract token drift (FUI2015).
+ *
+ * Activation is gated entirely on the `style.cssVars.mustBeDefined` policy fact,
+ * which is declared ONLY when a project has authored token source files (the
+ * cloud appends it when `tokenSourceFiles` is non-empty). No fact → no-op, so
+ * the `fragments` preset alone never activates this rule.
+ *
+ * When active, a `var(--x)` is drift iff `--x` is shaped like a contract token
+ * but is NOT in the vocabulary. "Shaped like a contract token" means one of:
+ *   1. it shares a prefix family of the authored vocabulary (e.g. `--fui-`); OR
+ *   2. it is single-segment (no hyphen after `--`, e.g. `--accent`) AND the
+ *      vocabulary itself contains at least one single-segment token.
+ * Clause 2 keeps the rule live for FLAT token systems (`--accent`, `--bg`, which
+ * yield no prefix family — #22/#25/#31/#36) and enforces the flat half of a MIXED
+ * `--fui-*` + `--accent` vocabulary symmetrically with the namespaced half (#18),
+ * order-independently. Genuinely foreign custom properties (`--swiper-*`,
+ * `--radix-*`, layout/animation vars) are multi-segment with no shared family, so
+ * they remain ignored — the rule neither floods on unrelated `var()`s nor fires
+ * for projects without a contract. Hardcoded values are handled by the unchanged
+ * `styles/no-raw-color` rule; this rule only judges custom-property references.
+ */
+export function ruleTokensCssVarsMustBeDefined(ix: FactIndex): Finding[] {
+  const policy = ix.policy.cssVarsMustBeDefined();
+  if (!policy) return [];
+
+  // The contract vocabulary travels on its OWN fact channel (contract_token),
+  // injected by the CLI from the user's token source files — kept separate from
+  // the local `token_definition` facts the raw-* rules + scale detection read.
+  const vocabulary = new Set(ix.byKind("contract_token").map((token) => token.name));
+  // The truly-unauthored case (no contract token facts) is the only hard return —
+  // it preserves the §11 inert-without-contract regression lock.
+  if (vocabulary.size === 0) return [];
+
+  // A flat/single-segment vocabulary (`--accent`, `--bg`) yields no prefix family,
+  // but the rule must STILL enforce it (#22/#25/#31/#36) — we no longer hard-return
+  // on an empty family set. `hasFlatTokens` lets single-segment refs through the
+  // shaped gate whenever the vocabulary itself declares single-segment tokens,
+  // which also enforces the flat half of a mixed vocabulary symmetrically (#18).
+  const prefixes = contractPrefixFamilies(vocabulary);
+  const hasFlatTokens = [...vocabulary].some(isSingleSegmentVarName);
+  const locallyDefinedCustomProperties = new Set(
+    ix
+      .byKind("style_declaration")
+      .filter((decl) => decl.property.startsWith("--"))
+      .map((decl) => decl.property)
+  );
+
+  const findings: Finding[] = [];
+
+  for (const decl of ix.byKind("style_declaration")) {
+    // Dedupe token names WITHIN one declaration so a value referencing the SAME
+    // off-contract var twice yields ONE finding (#11) — otherwise the two share an
+    // identical fingerprintIdentity and silently collapse to one at ingest. Scoped
+    // per-declaration: the same var in two DIFFERENT declarations still yields two.
+    const seen = new Set<string>();
+    CSS_VAR_REFERENCE.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = CSS_VAR_REFERENCE.exec(decl.value)) !== null) {
+      const tokenName = match[1];
+      // Advance past this var()'s matching close-paren so an inner fallback var()
+      // is never re-scanned as a fresh primary — only the PRIMARY position is
+      // judged (#17). `var(` starts at match.index, so the `(` is at +3.
+      CSS_VAR_REFERENCE.lastIndex = skipToCloseParen(decl.value, match.index + 3);
+
+      if (vocabulary.has(tokenName)) continue;
+      const shaped =
+        sharesContractPrefix(tokenName, prefixes) ||
+        (hasFlatTokens && isSingleSegmentVarName(tokenName)) ||
+        locallyDefinedCustomProperties.has(tokenName);
+      if (!shaped) continue;
+      if (seen.has(tokenName)) continue;
+      seen.add(tokenName);
+
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: policy.severity,
+          message: `var(${tokenName}) is not in the contract token vocabulary. Use a token defined in your contract's token source files.`,
+          location: decl.location,
+          evidence: ix.evidence([decl.id, policy.id]),
+          fingerprintIdentity: {
+            file: decl.file,
+            selector: decl.selector,
+            declarationPath: decl.declarationPath,
+            property: decl.property,
+            tokenName,
+          },
+          attributes: {
+            property: decl.property,
+            rawValue: decl.value,
+            tokenName,
+            source: "css",
+          },
+        })
+      );
+    }
+  }
+
+  return findings;
+}
+
+function sharesContractPrefix(name: string, prefixes: ReadonlySet<string>): boolean {
+  for (const prefix of prefixes) {
+    if (name.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether a `--name` is single-segment (no hyphen after the leading `--`), e.g.
+ * `--accent` (true) vs `--fui-color-accent` / `--swiper-theme-color` (false).
+ * Mirrors `contractPrefixFamilies`' index-of(`-`, 2) so the two stay consistent.
+ */
+function isSingleSegmentVarName(name: string): boolean {
+  return name.indexOf("-", 2) === -1;
+}
+
+/**
+ * Index just past the `)` that closes the open paren AT `openParenIndex`
+ * (a balanced-paren scan, so a nested fallback `var(--a, var(--b))` is skipped as
+ * one unit). Returns the string length if the value is unbalanced (no close),
+ * which safely ends the scan.
+ */
+function skipToCloseParen(value: string, openParenIndex: number): number {
+  let depth = 0;
+  for (let i = openParenIndex; i < value.length; i++) {
+    const ch = value[i];
+    if (ch === "(") depth++;
+    else if (ch === ")") {
+      depth--;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return value.length;
+}