@motion-proto/live-tokens 0.78.0 → 0.80.0

package/bin/rules/importsAndRoutes.mjs

@@ -0,0 +1,136 @@
+import { basename, relative } from 'node:path';
+import { deepImportRepair } from '../lib/catalogue.mjs';
+import { lineOf } from '../lib/findings.mjs';
+
+const shared = {
+  'deep-import': {
+    severity: 'error',
+    repair: 'auto',
+    guidance:
+      'A run without --no-fix rewrites a /src/system/components/<Name>.svelte specifier to the public /components/<Name>.svelte. Import any other deep specifier from a public subpath, which `details.exports` lists.',
+  },
+};
+
+export const pageRules = {
+  'reserved-route': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: 'Move the route out of /live-tokens/*.',
+  },
+  'site-css-in-main': {
+    severity: 'error',
+    repair: 'authored',
+    guidance:
+      "Delete the import from main.ts, and add it to each page's <script>. Page CSS then stays off the editor routes.",
+  },
+  'missing-source': {
+    severity: 'warn',
+    repair: 'authored',
+    guidance: "Add source: 'src/...' to the route entry.",
+  },
+  ...shared,
+};
+
+export const componentRules = {
+  ...shared,
+};
+
+// Deep imports into the package internals are not a supported API.
+const DEEP_IMPORT_PATTERNS = [
+  /^@motion-proto\/live-tokens\/src\//,
+  /node_modules\/@motion-proto\/live-tokens/,
+];
+
+/** `deep-import` for one import statement in a page. */
+export function checkPageImport({ index, specifier }, add) {
+  for (const pattern of DEEP_IMPORT_PATTERNS) {
+    if (pattern.test(specifier)) {
+      add('deep-import', index, `deep import into package internals: ${specifier}`, deepImportRepair(specifier));
+    }
+  }
+}
+
+/** `reserved-route`, then `missing-source`, then `site-css-in-main`, over a page's script and markup. */
+export function checkRoutes({ file, code }, add) {
+  for (const m of code.matchAll(/['"](\/live-tokens[^'"]*)['"]\s*:/g)) {
+    add('reserved-route', m.index, `route '${m[1]}' is inside the reserved /live-tokens/* namespace`);
+  }
+
+  for (const m of code.matchAll(/\blazy\s*:/g)) {
+    const entry = enclosingObject(code, m.index);
+    if (entry && !/\bsource\s*:/.test(entry)) {
+      add('missing-source', m.index, `route entry has no 'source', so Page Source cannot open it`);
+    }
+  }
+
+  if (/^main\.(ts|js)$/.test(basename(file))) {
+    for (const m of code.matchAll(/import\s+['"]([^'"]*site\.css)['"]/g)) {
+      add(
+        'site-css-in-main',
+        m.index,
+        `site.css imported from main; import it from each page's <script> so it cannot leak into editor routes`,
+      );
+    }
+  }
+}
+
+/** The object literal enclosing `index`, found by balancing braces outward. */
+function enclosingObject(text, index) {
+  let depth = 0;
+  let start = -1;
+  for (let i = index; i >= 0; i--) {
+    const c = text[i];
+    if (c === '}') depth++;
+    else if (c === '{') {
+      if (depth === 0) {
+        start = i;
+        break;
+      }
+      depth--;
+    }
+  }
+  if (start === -1) return null;
+  depth = 0;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+function extractImports(source) {
+  const out = [];
+  const re = /import\s+(?:[^'"]*\s+from\s+)?['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    out.push({ specifier: m[1], index: m.index + m[0].length - 1 - m[1].length });
+  }
+  return out;
+}
+
+/**
+ * `deep-import` for each `[path, text]` pair a component owns: its runtime,
+ * its editor, or the file that registers it. Each line resolves against that
+ * file's own text.
+ */
+export function checkComponentImports(root, files, recordAt) {
+  for (const [path, text] of files) {
+    for (const { specifier, index } of extractImports(text)) {
+      for (const pattern of DEEP_IMPORT_PATTERNS) {
+        if (pattern.test(specifier)) {
+          recordAt(
+            'deep-import',
+            `${relative(root, path)}: deep import not supported: ${specifier}`,
+            relative(root, path),
+            lineOf(text, index),
+            deepImportRepair(specifier),
+          );
+        }
+      }
+    }
+  }
+}

package/bin/rules/testRuns.mjs

@@ -0,0 +1,122 @@
+import { COLOR_BY_ROLE } from './tokens.mjs';
+
+// Detection lives in bin/contractRunner.mjs: `runContractTests` for the
+// component rules, `runPageTests` for the page rules. The ids are fixed by
+// design decisions 8 and 9. Every one is an error, including the setup rules,
+// which `--tests` treats as never-silenceable (see cli.mjs). A failed
+// obligation is always authored: the component has to start behaving.
+
+const RERUN =
+  'Rerun the same command with --tests until every applicable rule passes with no rule left --off.';
+
+const CREATE_COMPONENT = 'live-tokens-create-component';
+
+const tooling = {
+  'tests-not-installed': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The run itself failed because a tool is missing. Install the named package, @playwright/test, vitest, or happy-dom, as a devDependency, then run \`npx playwright install chromium\` for a missing browser. ${RERUN}`,
+  },
+  'tests-setup': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The run itself failed before it reported. Fix the tool, the path, or the config the message names. ${RERUN}`,
+  },
+  'tests-incomplete': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `An obligation never ran to a result. Add the missing contract, or find from the message why the suite skipped it. ${RERUN}`,
+  },
+};
+
+export const componentRules = {
+  'contract-registry': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The registry contract failed. Register the component in the shared module the Registration section of ${CREATE_COMPONENT} wires up, importable by the app and by check-component --tests.`,
+  },
+  'contract-behavior': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `A declared case in the component's contract failed under Vitest: a callback that never fired, fired with the wrong argument, or fired when the case said it should stay silent. Wire the runtime as the recipe in ${CREATE_COMPONENT} wires it.`,
+  },
+  'contract-render': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `A shipped alias never wrote through its editor control, or the editor targets the wrong part. Fix the editor schema, states, or preview props by the Component editor section of ${CREATE_COMPONENT}.`,
+  },
+  'contract-alias': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The editor has to declare every part and every shipped alias, and each alias it paints with has to resolve at the root. Fix the editor schema by the Component editor section of ${CREATE_COMPONENT}, and point a broken alias at a design token.`,
+  },
+  'contract-persist': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `An edit failed to persist, or reset failed to restore the saved config. Make the :global(:root) default the value Reset should restore, per the Runtime component section of ${CREATE_COMPONENT}.`,
+  },
+  'contract-theme': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The component failed to take the theme's values and give them back. Make each :global(:root) default read a design token, composed when needed, and declare a structural keyword, such as start, in the editor's \`intrinsics\`.`,
+  },
+  'contract-states': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The editor preview failed to show the state being edited. Fix the editor states or preview props by the Component editor section of ${CREATE_COMPONENT}.`,
+  },
+  'contract-interaction': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The component failed to answer the pointer or the keyboard in the editor. Fix the editor schema, states, or preview props by the Component editor section of ${CREATE_COMPONENT}.`,
+  },
+  'contract-listed': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The component is missing from its registry group. Register it in the shared module the Registration section of ${CREATE_COMPONENT} wires up, importable by the app and by check-component --tests.`,
+  },
+  'contract-sketch': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Add the missing Sketch part or marker, per the Sketch mode and overlays section of ${CREATE_COMPONENT}.`,
+  },
+  'contract-missing': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Add a ComponentContract for the component to the module contractsModule names, as references/contract-tests.md in ${CREATE_COMPONENT} shows. ${RERUN}`,
+  },
+  ...tooling,
+};
+
+export const pageRules = {
+  'page-component-paint': {
+    severity: 'error',
+    repair: 'authored',
+    guidance:
+      "The finding names the page file and the line of the instance whose part painted a value its semantic property never resolves to. Remove the global rule that reaches past the component, from site.css or the page's own CSS, and retune the component's semantic property for the whole project at /live-tokens/components.",
+  },
+  'page-text-style': {
+    severity: 'error',
+    repair: 'authored',
+    guidance:
+      'The finding names the page file, the line of the text element, and the nearest bundle it missed. Set the text style on the text element itself, from one shipped bundle: heading, body, editorial, or code, each printed by `npx live-tokens tokens --scale <name>`. An ancestor typed for a different role hands down the wrong style.',
+  },
+  'page-contrast': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The finding names the page file, the line of the text element, the surface ancestor, and both computed colors. Pick the text token the surface pairs with. ${COLOR_BY_ROLE}`,
+  },
+  'page-grid': {
+    severity: 'error',
+    repair: 'authored',
+    guidance:
+      'The finding names the page file and the line of the section whose edge sits off a column line. Move the edge onto the line: place it by page-column numbers per the Grid section of live-tokens-create-page, and center a section with symmetric insets. Keep its margin, width, and transform out of the centering.',
+  },
+  'page-overflow': {
+    severity: 'error',
+    repair: 'authored',
+    guidance:
+      'The finding names the page file and the line of the element or the instance that overflows. Give the control its shipped width, remove a fixed width wider than its column at the viewport, and set overflow-x: auto only on an element meant to scroll, such as a code block. When the page grid itself overflows at a phone width, collapse it to grid-template-columns: 1fr and column-gap: 0, per the Grid section of live-tokens-create-page.',
+  },
+  ...tooling,
+};

package/bin/rules/tokens.mjs

@@ -0,0 +1,426 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { loadBuiltEngine, resolveTokensCssPath } from '../migrate.mjs';
+import { scaleTokens } from '../lib/catalogue.mjs';
+import { COLOR_SCALES, GEOMETRY_SCALES, STATE_TOKENS, readKindRules, tokenScale, unreadTokens } from '../lib/componentSource.mjs';
+import { colorScaleOfProperty, hasColorLiteral, hasDimensionLiteral, stripVarFallbacks } from '../lib/cssValues.mjs';
+import { readComponentConfig } from '../lib/dataDir.mjs';
+import { findJsonKeyLine, isExcluded } from '../lib/findings.mjs';
+import { geometryScaleOfProperty, resolveGeometryLiteral } from '../lib/geometry.mjs';
+import { declarationPatch, declarations, neutralise, pageDeclaredNames } from '../lib/pageSource.mjs';
+import { isContractToken } from '../lib/tokenVocabulary.mjs';
+
+export const COLOR_BY_ROLE =
+  'Pick the color token by the role the color plays, and the theme moves every role together. ' +
+  'Text on a surface takes --text-primary through --text-disabled, the neutral text scale, or --text-<family> for a family color. ' +
+  'Light text on a dark chip takes --text-inverted, which carries no AA guarantee. ' +
+  'A surface fill takes --surface-<family>-<level>, where the role names the family: neutral for chrome, brand for emphasis, danger for status. ' +
+  'A stroke takes --border-<family>-<level>, with levels from faint to strong. ' +
+  'A translucent layer that dims what is behind it, such as the layer behind a modal, takes --scrim-low, --scrim, or --scrim-high. ' +
+  'A translucent wash on a surface, such as a hover state, takes --tint-low, --tint, or --tint-high. ' +
+  "Any other translucent color takes the role's token at an opacity, color-mix(in srgb, var(--surface-brand) 80%, transparent), the form the editor reads. " +
+  'A fully transparent color takes --color-transparent. ' +
+  'A gradient takes a --gradient-* token, or one composed from surface tokens. ' +
+  "`npx live-tokens tokens --scale <name>` prints a scale's names and values, with --json for data.";
+
+export const GEOMETRY_BY_SCALE =
+  'Pick the geometry token from its scale. ' +
+  'Spacing takes the nearest --space-<px> step, and `npx live-tokens tokens --scale space` prints the steps. ' +
+  'A stroke width, an outline included, takes --border-width-1, --border-width-2, or --border-width-4. ' +
+  'A corner takes --radius-sm through --radius-4xl, or --radius-full. ' +
+  'A shadow takes --shadow-sm through --shadow-xl in place of the whole value. ' +
+  'Part of a calc() takes the token inside the calc, such as calc(var(--space-64) * -2 + var(--space-8)). ' +
+  'A duration or easing takes --duration-* or --ease-*, and a blur() takes --blur-*. No rule reports those three, so fix them while in the file.';
+
+const COMPONENT_DEFAULT = 'In a component, make the :global(:root) default read the token, composed when needed.';
+
+const INTRINSIC = "Declare a structural keyword, such as start, in the editor's `intrinsics`.";
+
+const shared = {
+  'tokens-migration': {
+    severity: 'error',
+    repair: 'auto',
+    guidance:
+      'A run without --no-fix applies these migrations to tokens.css. Each one adds design tokens the installed package reads and changes no existing token. `details.migrations` names them.',
+  },
+  'tokens-breaking-migration': {
+    severity: 'error',
+    repair: 'choice',
+    guidance:
+      'Each migration in `details.migrations` renames, removes, or rewrites design tokens in tokens.css. Read the plan with `npx live-tokens migrate --check`, apply it with `npx live-tokens migrate`, and move any page or component that reads an old name to the new one. To keep tokens.css as it is, record the `exception`.',
+  },
+  'color-literal': {
+    severity: 'error',
+    repair: 'choice',
+    guidance: `Replace the literal with a design token. \`details.candidates\` lists the tokens on the scale the property reads. ${COLOR_BY_ROLE} ${COMPONENT_DEFAULT}`,
+  },
+  'dimension-literal': {
+    severity: 'warn',
+    repair: 'auto',
+    guidance:
+      'A run without --no-fix replaces each literal that has one nearest step. ' +
+      'A literal left over has no single nearest step, so pick by the visual weight the candidates in `details` show. ' +
+      `A size, such as a hero's height, is layout. Leave it. ${GEOMETRY_BY_SCALE} ${COMPONENT_DEFAULT}`,
+  },
+};
+
+export const pageRules = {
+  'unknown-token': {
+    severity: 'error',
+    repair: 'choice',
+    guidance:
+      'Search tokens.css for the stem. When the name has the shape of a design token and no longer exists, `npx live-tokens migrate --check` lists the migration that adds the current name.',
+  },
+  'raw-text-axis': {
+    severity: 'error',
+    repair: 'choice',
+    guidance:
+      'Set every axis from one text style bundle, -font-family through -letter-spacing. The text styles are heading, body, editorial, and code, and `npx live-tokens tokens --scale heading` prints one of them. Rewrite a font: shorthand the same way.',
+  },
+  'hardcoded-columns': {
+    severity: 'warn',
+    repair: 'choice',
+    guidance:
+      'Use repeat(var(--columns-count), 1fr) for the page grid, and repeat(calc(var(--columns-count) - 2), 1fr) for a sub-grid that spans fewer columns. `details.candidates` holds both forms.',
+  },
+  ...shared,
+};
+
+export const componentRules = {
+  'unread-token': {
+    severity: 'warn',
+    repair: 'choice',
+    guidance:
+      "The message names the property the runtime declares in :global(:root) and never reads. Wire it into the runtime's CSS where it paints, as the Runtime component section of live-tokens-create-component wires a property, or delete the declaration when nothing should paint with it.",
+  },
+  'unknown-token-ref': {
+    severity: 'error',
+    repair: 'choice',
+    guidance:
+      "Point the default at a design token or one of the component's own semantic properties. A state is a segment of a property name, so replace a reference that starts with a state by the token that state should paint. When the name has the shape of a design token and no longer exists, search tokens.css for the rename, and `npx live-tokens migrate --check` lists the migration that adds it. " +
+      COMPONENT_DEFAULT,
+  },
+  'default-not-token': {
+    severity: 'error',
+    repair: 'choice',
+    guidance: `Make the :global(:root) default read a design token, composed when needed. ${INTRINSIC}`,
+  },
+  'config-token': {
+    severity: 'error',
+    repair: 'choice',
+    guidance:
+      "The message names the alias in component-configs/<id>/default.json that names something outside the vocabulary, or a bare literal on a property the editor declares no intrinsic for. Point the alias at a design token or one of the component's own semantic properties, or declare the intrinsic in the editor. " +
+      `${COLOR_BY_ROLE} ${GEOMETRY_BY_SCALE}`,
+  },
+  ...shared,
+};
+
+/**
+ * The semantic half of the contract: a component token is a *property name*, and
+ * its default is the theme token that property reads. So every default must
+ * resolve to a real token — otherwise the component stops repainting when the
+ * theme changes, which is the whole point of declaring it.
+ */
+export function checkDefaultsAreSemantic({ blocks, runtime, root, runtimePath, vocab, intrinsic }, record) {
+  const rel = relative(root, runtimePath);
+  const kindRules = readKindRules(root);
+
+  const own = new Set();
+  for (const block of blocks) {
+    for (const m of block.matchAll(/(?:^|[;{])\s*(--[a-z0-9-]+)\s*:/gm)) own.add(m[1]);
+  }
+
+  for (const block of blocks) {
+    for (const m of block.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      const [decl, name, raw] = m;
+      const value = raw.trim();
+      const at = runtime.indexOf(decl);
+
+      const painted = stripVarFallbacks(value);
+      const refs = [...painted.matchAll(/var\(\s*(--[a-z0-9-]+)/g)].map((x) => x[1]);
+      for (const ref of refs) {
+        if (own.has(ref) || vocab.knows(ref)) continue;
+        record(
+          'unknown-token-ref',
+          STATE_TOKENS.includes(ref.replace(/^--/, '').split('-')[0])
+            ? `${rel}: ${name} reads ${ref}, but a state is a segment of a property name. Read the token the state should paint`
+            : isContractToken(ref)
+              ? `${rel}: ${name} reads ${ref}, which has the shape of a design token but no longer exists. Check tokens.css for a rename`
+              : `${rel}: ${name} reads ${ref}, which is not a design token or a semantic property`,
+          at,
+        );
+      }
+
+      if (hasColorLiteral(painted)) {
+        const scale = tokenScale(name, kindRules, COLOR_SCALES);
+        record(
+          'color-literal',
+          `${rel}: ${name}: ${value} is a colour literal; defaults must reference design tokens (e.g. var(--surface-primary))`,
+          at,
+          { details: { scale, candidates: scaleTokens(vocab, scale).map((t) => t.name) } },
+        );
+        continue;
+      }
+
+      if (refs.length === 0 && !intrinsic.some((re) => re.test(name))) {
+        record(
+          'default-not-token',
+          `${rel}: ${name}: ${value} has no design token behind it. Back it with a token, or declare it in the editor's \`intrinsics\` when it is a structural keyword`,
+          at,
+        );
+      }
+
+      if (hasDimensionLiteral(painted)) {
+        const scale = tokenScale(name, kindRules, GEOMETRY_SCALES);
+        const resolved = resolveGeometryLiteral(value, scale, scaleTokens(vocab, scale));
+        // Anchored at the whole declaration: a value-only patch applied at the
+        // first namesake literal at or after the line, whatever property held it.
+        const patch = resolved.patch
+          ? { from: decl, to: `${decl.slice(0, decl.length - raw.length - 1)}${raw.replace(value, resolved.patch.to)};` }
+          : null;
+        record(
+          'dimension-literal',
+          `${rel}: ${name}: ${value} pins a raw dimension; use a --space-*, --radius-*, or --border-width-* token`,
+          at,
+          {
+            details: { scale: resolved.scale, literals: resolved.literals, ...(patch ? { patch } : {}) },
+            ...(patch ? {} : { repair: 'choice' }),
+          },
+        );
+      }
+    }
+  }
+}
+
+/** Every `--name` inside a JSON string value, in the order it appears. Simple
+ *  greedy extraction: `--card-default-body-padding` is one match, never two,
+ *  since `[a-z0-9-]+` already consumes the longer run first. */
+const TOKEN_NAME_RE = /--[a-z0-9-]+/g;
+
+/**
+ * Saved assignments, validated as data. Every `--name` an alias string in
+ * `component-configs/<id>/default.json` carries, whatever wraps it (`var()`,
+ * the color-mix opacity form the editor writes, or nothing), must resolve —
+ * a design token, or one of the component's own properties. A string with no
+ * `--name` at all is a bare literal, allowed only on a property the editor
+ * declares in `intrinsics`. A structured (non-string) alias value, such as a
+ * gradient, is out of scope here.
+ */
+export function checkConfigTokens({ id, root, intrinsic, vocab }, recordAt) {
+  const config = readComponentConfig(root, id);
+  if (!config) return;
+  const { text, data } = config;
+  const rel = relative(root, config.path);
+  // Only this component's own tokens, not the union across every component:
+  // an alias naming a sibling component's property is exactly the case this
+  // rule exists to catch.
+  const ownTokens = vocab.components.get(id)?.tokens;
+  const knows = (name) => vocab.themeTokens.has(name) || (ownTokens?.has(name) ?? false);
+  for (const [prop, value] of Object.entries(data.aliases ?? {})) {
+    if (typeof value !== 'string') continue;
+    const line = findJsonKeyLine(text, prop);
+    const names = value.match(TOKEN_NAME_RE);
+    if (!names) {
+      if (!intrinsic.some((re) => re.test(prop))) {
+        recordAt(
+          'config-token',
+          `${rel}: ${prop}: "${value}" has no design token behind it, and ${prop} is not a declared intrinsic`,
+          rel,
+          line,
+          { details: { property: prop, value } },
+        );
+      }
+      continue;
+    }
+    for (const name of names) {
+      if (knows(name)) continue;
+      recordAt(
+        'config-token',
+        `${rel}: ${prop} names ${name}, which is not a design token or a semantic property`,
+        rel,
+        line,
+        { details: { property: prop, value } },
+      );
+    }
+  }
+}
+
+/** A property nothing in the file reads paints nothing, so the editor offers a
+ *  control that moves nothing. */
+export function checkUnreadTokens({ root, runtimePath, runtime, declared }, record) {
+  for (const name of unreadTokens(runtime, declared)) {
+    record(
+      'unread-token',
+      `${relative(root, runtimePath)}: ${name} is declared and never read in this file's own CSS. Read it where it paints, or drop it`,
+      runtime.indexOf(name),
+      { details: { property: name } },
+    );
+  }
+}
+
+const TEXT_AXES = ['font-size', 'font-family', 'font-weight', 'line-height', 'letter-spacing'];
+
+// The single-axis scales in tokens.css. A text style bundle carries its axis
+// as a suffix (--body-md-font-size, --code-font-family), so no bundle name
+// matches, and neither does a custom property the page declares itself. A
+// weight alone cannot move the scale or the fonts, so --font-weight-* is not one.
+const SINGLE_AXIS_TOKEN =
+  /^--(?:font-size|line-height|letter-spacing)-|^--font-(?:sans|serif|mono|display|editorial)$/;
+
+// The geometry the theme owns: spacing, stroke, radius, and shadow all have a
+// token scale, and `set-geometry` moves them. Sizing (a hero's height, a
+// column's minimum width, a max content width) is layout, has no scale, and
+// stays literal.
+const THEMED_GEOMETRY = /^(padding|margin|gap|row-gap|column-gap|border|outline|inset|top|right|bottom|left|box-shadow|text-shadow)(-|$)|-radius$/;
+
+// A local two-up or three-up is a layout. From four columns on, a hardcoded
+// count reads as a claim about the page grid, which `--columns-count` owns.
+const PAGE_GRID_COLUMNS = 4;
+
+// The two forms that keep a grid in step: the page grid itself, and a sub-grid
+// spanning fewer than every column.
+const COLUMN_FORMS = ['repeat(var(--columns-count), 1fr)', 'repeat(calc(var(--columns-count) - N), 1fr)'];
+
+/** `unknown-token` over each style region, then the value rules over each of its declarations. */
+export function checkPageValues({ text, regions, inlineRegions, vocab }, add) {
+  const declared = pageDeclaredNames(text, regions);
+  for (const region of [...regions, ...inlineRegions]) {
+    const css = neutralise(region.text);
+    const at = (i) => region.offset + i;
+
+    for (const m of css.matchAll(/var\(\s*(--[a-z0-9-]+)/g)) {
+      const name = m[1];
+      if (declared.has(name) || vocab.knows(name)) continue;
+      add(
+        'unknown-token',
+        at(m.index),
+        isContractToken(name)
+          ? `${name} has the shape of a design token but no longer exists. Check tokens.css for a rename`
+          : `${name} is not a design token, a semantic property, or declared in this file`,
+      );
+    }
+
+    for (const decl of declarations(css)) checkDeclaration(decl, { text, region, vocab, at }, add);
+  }
+}
+
+/** A colour literal or a raw text axis ends the checks for its declaration. */
+function checkDeclaration(decl, { text, region, vocab, at }, add) {
+  const { prop, value, index } = decl;
+  if (prop.startsWith('--')) return;
+
+  // A `var()` fallback only renders when the token is missing, so a literal
+  // inside one is not the page's value.
+  const painted = stripVarFallbacks(value);
+  if (!TEXT_AXES.includes(prop) && hasColorLiteral(painted)) {
+    const scale = colorScaleOfProperty(prop);
+    add('color-literal', at(index), `${prop}: ${value}. Use a design token.`, {
+      details: { scale, candidates: scaleTokens(vocab, scale).map((t) => t.name) },
+    });
+    return;
+  }
+
+  if (TEXT_AXES.includes(prop) || prop === 'font') {
+    const axis = [...painted.matchAll(/var\(\s*(--[a-z0-9-]+)/g)]
+      .map((m) => m[1])
+      .find((name) => SINGLE_AXIS_TOKEN.test(name));
+    if (axis) {
+      add(
+        'raw-text-axis',
+        at(index),
+        `${prop}: ${value}. ${axis} is one axis. Set every axis from one text style bundle (--heading-*, --body-*, --editorial-*, --code-*).`,
+      );
+      return;
+    }
+
+    // Of the literals only absolute type values are a finding. `em`, `%`,
+    // and a unitless line-height are relative to the inherited type, so
+    // they ride whatever the theme sets rather than overriding it.
+    if (
+      !value.includes('var(') &&
+      !/^(inherit|initial|unset|normal)$/.test(value) &&
+      /\d(px|rem|pt)\b|^[a-z"']/i.test(value)
+    ) {
+      add(
+        'raw-text-axis',
+        at(index),
+        `${prop}: ${value}. Set type from a text style bundle (--heading-*, --body-*, --editorial-*, --code-*).`,
+      );
+      return;
+    }
+  }
+
+  if (THEMED_GEOMETRY.test(prop) && hasDimensionLiteral(painted)) {
+    const scale = geometryScaleOfProperty(prop);
+    const resolved = resolveGeometryLiteral(value, scale, scaleTokens(vocab, scale));
+    const patch = resolved.patch ? declarationPatch(text, region, decl, resolved.patch.to) : null;
+    add(
+      'dimension-literal',
+      at(index),
+      `${prop}: ${value}. Use a --space-*, --radius-*, --border-width-*, or --shadow-* token.`,
+      {
+        details: { scale: resolved.scale, literals: resolved.literals, ...(patch ? { patch } : {}) },
+        ...(patch ? {} : { repair: 'choice' }),
+      },
+    );
+  }
+
+  const columns = value.match(/\brepeat\(\s*(\d+)\s*,\s*1fr\s*\)/);
+  if (columns && Number(columns[1]) >= PAGE_GRID_COLUMNS) {
+    add(
+      'hardcoded-columns',
+      at(index),
+      `${prop}: ${value}. Use repeat(var(--columns-count), 1fr) so the page grid stays in step.`,
+      { details: { columns: Number(columns[1]), candidates: COLUMN_FORMS } },
+    );
+  }
+}
+
+/**
+ * Runs before either checker reads the vocabulary, so a tokens.css behind the
+ * installed package never surfaces as unknown tokens. `engine` is a test seam.
+ */
+export async function checkTokensCssMigrations({ root = process.cwd(), apply, engine } = {}) {
+  const result = { applied: [], findings: [] };
+  const loaded = engine ?? (await loadBuiltEngine());
+  if (!loaded) return result;
+  const { TOKENS_CSS_MIGRATIONS, readLiveTokensConfig, runAdditiveTokensCssMigrations, runTokensCssMigrations } = loaded;
+  const tokensPath = resolveTokensCssPath(null, readLiveTokensConfig().tokensCssPath, root);
+  if (!tokensPath || !existsSync(tokensPath)) return result;
+  const file = relative(root, tokensPath);
+  if (isExcluded(file, root)) return result;
+
+  const migration = (id) => TOKENS_CSS_MIGRATIONS.find((m) => m.id === id);
+  const listed = (ids) => ids.map((id) => ({ id, description: migration(id).description }));
+
+  let css = readFileSync(tokensPath, 'utf8');
+  const additive = runAdditiveTokensCssMigrations(css);
+  if (additive.changed) {
+    const finding = {
+      rule: 'tokens-migration',
+      file,
+      line: 1,
+      message: `${file} lacks design tokens the installed package reads: ${additive.applied.join(', ')}`,
+      details: { migrations: listed(additive.applied) },
+    };
+    if (apply) {
+      writeFileSync(tokensPath, additive.css);
+      css = additive.css;
+      result.applied.push(finding);
+    } else {
+      result.findings.push(finding);
+    }
+  }
+
+  const breaking = runTokensCssMigrations(css).applied.filter((id) => migration(id).kind === 'breaking');
+  if (breaking.length > 0) {
+    result.findings.push({
+      rule: 'tokens-breaking-migration',
+      file,
+      line: 1,
+      message: `${file} has breaking migrations pending: ${breaking.join(', ')}`,
+      details: { migrations: listed(breaking) },
+    });
+  }
+  return result;
+}