stylelint-plugin-rhythmguard 3.8.0 → 3.10.0

package/src/audit/token-ladders.js

@@ -0,0 +1,216 @@
+'use strict';
+
+const valueParser = require('postcss-value-parser');
+const { formatLength, numbersEqual, parseLengthToken, toPx } = require('../core/length');
+
+/**
+ * Token ladders (issue #205). A ladder is a set of custom properties that
+ * share a prefix and differ by a size step: `--font-size-text-xxs` to
+ * `-xxl`, `--space-1` to `--space-9`, `--radius-sm/md/lg`. Every step can be
+ * on the scale and the ladder still be broken, so each step is evaluated at
+ * its smallest and largest value (a static length, a clamp() minimum and
+ * maximum, the static arguments of min() and max(), followed through var())
+ * and adjacent steps are compared at both ends:
+ *
+ *   collapsed    two steps render the same size at one end
+ *   too-close    two steps differ by less than `minStepPx` (default 2px)
+ *   inverted     a step is larger than the next one at one end
+ *
+ * Each problem names the end it occurs at: `min`, `max`, or `both`.
+ *
+ * A step that cannot be evaluated (calc(), a viewport length, a token with
+ * several different definitions) is left out of the comparison.
+ */
+const DEFAULT_MIN_STEP_PX = 2;
+const MIN_LADDER_STEPS = 3;
+const VAR_REFERENCE = /^var\(\s*(--[\w-]+)\s*(?:,\s*([\s\S]+))?\)$/i;
+
+// T-shirt steps in order. Aliases share a rank (sm and s, 2xl and xxl).
+const SIZE_RANKS = new Map([
+  ['xxxs', -4], ['3xs', -4], ['xxs', -3], ['2xs', -3], ['xs', -2],
+  ['s', -1], ['sm', -1], ['small', -1],
+  ['m', 0], ['md', 0], ['medium', 0], ['base', 0],
+  ['l', 1], ['lg', 1], ['large', 1],
+  ['xl', 2], ['xxl', 3], ['2xl', 3], ['xxxl', 4], ['3xl', 4],
+  ['4xl', 5], ['5xl', 6], ['6xl', 7], ['7xl', 8], ['8xl', 9], ['9xl', 10],
+]);
+const STEP_SUFFIX = /^(--[\w-]+?)-([a-z0-9]+)$/i;
+
+/** The ladder a token belongs to and its rank on it, or null. */
+function ladderStep(token) {
+  const match = token.match(STEP_SUFFIX);
+  if (!match) {
+    return null;
+  }
+  const [, prefix, suffix] = match;
+  const lower = suffix.toLowerCase();
+  if (SIZE_RANKS.has(lower)) {
+    return { key: `${prefix} (sizes)`, prefix, rank: SIZE_RANKS.get(lower) };
+  }
+  if (/^\d+$/.test(lower)) {
+    return { key: `${prefix} (numbers)`, prefix, rank: Number(lower) };
+  }
+  return null;
+}
+
+function splitArguments(fnNode) {
+  const args = [[]];
+  for (const node of fnNode.nodes) {
+    if (node.type === 'div' && node.value === ',') {
+      args.push([]);
+    } else {
+      args[args.length - 1].push(node);
+    }
+  }
+  return args.map((nodes) => valueParser.stringify(nodes).trim());
+}
+
+function createEvaluator(declarations, baseFontSize) {
+  const memo = new Map();
+
+  const evaluateToken = (token, seen) => {
+    if (memo.has(token)) return memo.get(token);
+    const values = declarations.get(token);
+    if (!values || seen.has(token)) return null;
+    const ranges = [...values].map((value) => evaluate(value, new Set([...seen, token])));
+    const [first] = ranges;
+    const agree = first && ranges.every((range) => range && sameEnd(range.min, first.min) && sameEnd(range.max, first.max));
+    const result = agree ? first : null;
+    memo.set(token, result);
+    return result;
+  };
+
+  // { min, max } in px; an end is null when the value has no static bound there.
+  const evaluate = (raw, seen = new Set()) => {
+    const value = String(raw).trim();
+    const reference = value.match(VAR_REFERENCE);
+    if (reference) {
+      const [, target, fallback] = reference;
+      if (declarations.has(target)) return evaluateToken(target, seen);
+      return fallback === undefined ? null : evaluate(fallback, seen);
+    }
+    const parsed = valueParser(value).nodes.filter((node) => node.type !== 'space');
+    if (parsed.length !== 1) return null;
+    const [node] = parsed;
+    if (node.type === 'word') {
+      const length = parseLengthToken(node.value);
+      if (!length || !length.unit || length.unit === '%') return null;
+      const px = toPx(Math.abs(length.number), length.unit, baseFontSize);
+      if (px === null) return null;
+      const signed = length.number < 0 ? -px : px;
+      return { max: signed, min: signed };
+    }
+    if (node.type !== 'function') return null;
+    const name = node.value.toLowerCase();
+    const args = splitArguments(node).map((arg) => evaluate(arg, seen));
+    if (name === 'clamp') {
+      if (args.length !== 3 || !args[0] || !args[2] || args[0].min === null || args[2].max === null) return null;
+      return { max: args[2].max, min: args[0].min };
+    }
+    if (name === 'min' || name === 'max') {
+      const statics = args.filter((range) => range && range.min !== null && range.max !== null);
+      if (statics.length === 0) return null;
+      const pick = name === 'min' ? Math.min : Math.max;
+      const all = statics.length === args.length;
+      // min(5vw, 2rem) is at most 2rem and has no static minimum; max() mirrors it.
+      return {
+        max: name === 'min' || all ? pick(...statics.map((range) => range.max)) : null,
+        min: name === 'max' || all ? pick(...statics.map((range) => range.min)) : null,
+      };
+    }
+    return null;
+  };
+
+  return { evaluate, evaluateToken };
+}
+
+function sameEnd(a, b) {
+  return (a === null && b === null) || (a !== null && b !== null && numbersEqual(a, b));
+}
+
+function compareEnds(lower, upper, end, minStepPx) {
+  const a = lower[end];
+  const b = upper[end];
+  if (a === null || b === null) return null;
+  if (numbersEqual(a, b)) return { type: 'collapsed' };
+  if (a > b) return { type: 'inverted' };
+  if (b - a < minStepPx) return { difference: Math.round((b - a) * 1000) / 1000, type: 'too-close' };
+  return null;
+}
+
+/**
+ * Every ladder of at least three evaluable steps, with the problems between
+ * adjacent steps. `declarations` is the token-chain map: token to the set of
+ * values it is declared with.
+ */
+function resolveTokenLadders({ baseFontSize = 16, declarations, minStepPx = DEFAULT_MIN_STEP_PX }) {
+  const { evaluateToken } = createEvaluator(declarations, baseFontSize);
+  const ladders = new Map();
+  for (const token of declarations.keys()) {
+    const step = ladderStep(token);
+    if (!step) continue;
+    const range = evaluateToken(token, new Set());
+    if (!range) continue;
+    if (!ladders.has(step.key)) ladders.set(step.key, { prefix: step.prefix, steps: [] });
+    const ladder = ladders.get(step.key);
+    // An alias for a rank already on the ladder (s next to sm) is not a step.
+    if (ladder.steps.some((existing) => existing.rank === step.rank)) continue;
+    ladder.steps.push({ max: range.max, min: range.min, rank: step.rank, token });
+  }
+
+  const entries = [];
+  for (const ladder of ladders.values()) {
+    if (ladder.steps.length < MIN_LADDER_STEPS) continue;
+    const steps = ladder.steps.sort((a, b) => a.rank - b.rank);
+    const problems = [];
+    for (let index = 0; index < steps.length - 1; index += 1) {
+      const tokens = [steps[index].token, steps[index + 1].token];
+      const atMin = compareEnds(steps[index], steps[index + 1], 'min', minStepPx);
+      const atMax = compareEnds(steps[index], steps[index + 1], 'max', minStepPx);
+      // The same problem at both ends (always, for static steps) is one problem.
+      if (atMin && atMax && atMin.type === atMax.type && atMin.difference === atMax.difference) {
+        problems.push({ end: 'both', tokens, ...atMin });
+        continue;
+      }
+      if (atMin) problems.push({ end: 'min', tokens, ...atMin });
+      if (atMax) problems.push({ end: 'max', tokens, ...atMax });
+    }
+    entries.push({
+      prefix: ladder.prefix,
+      problems,
+      steps: steps.map(({ max, min, token }) => ({
+        max: max === null ? null : formatLength(max, 'px'),
+        min: min === null ? null : formatLength(min, 'px'),
+        token,
+      })),
+    });
+  }
+  entries.sort((a, b) => a.prefix.localeCompare(b.prefix));
+
+  const count = (type) => entries.reduce((sum, entry) => sum + entry.problems.filter((problem) => problem.type === type).length, 0);
+  return {
+    entries,
+    summary: {
+      collapsed: count('collapsed'),
+      inverted: count('inverted'),
+      ladders: entries.length,
+      minStepPx,
+      tooClose: count('too-close'),
+    },
+  };
+}
+
+/** The contract shape: counts for every ladder, entries only for ladders with a problem. */
+function toLaddersContract(ladders) {
+  return {
+    entries: ladders.entries.filter((entry) => entry.problems.length > 0),
+    summary: ladders.summary,
+  };
+}
+
+module.exports = {
+  DEFAULT_MIN_STEP_PX,
+  ladderStep,
+  resolveTokenLadders,
+  toLaddersContract,
+};

package/src/configs/embed.js

@@ -7,8 +7,8 @@
  * spacing tokens (scaleSources, .rhythmguardrc.json token sources, the
  * stylesheet's custom properties, a Tailwind config, then rhythmic-4).
  * No `extends`, no dependency beyond this plugin, and the shape is frozen for
- * the life of the 2.x line so a config that embeds it never changes behaviour
- * on a minor bump.
+ * the life of a major version so a config that embeds it never changes
+ * behaviour on a minor bump.
  */
 module.exports = {
   plugins: ['stylelint-plugin-rhythmguard'],

package/src/core/css-vocabulary.js

@@ -41,6 +41,30 @@ const PROPERTY_GROUP_PATTERNS = Object.freeze({
   ]),
 });
 
+/** The property group a CSS property belongs to, or null. */
+function propertyGroupOf(prop) {
+  const lower = String(prop || '').toLowerCase();
+  const found = Object.entries(PROPERTY_GROUP_PATTERNS).find(([, patterns]) => patterns.some((pattern) => pattern.test(lower)));
+  return found ? found[0] : null;
+}
+
+// Properties whose length is a different kind from the group that checks them.
+// outline-offset is checked with the radius group (it always has been), but it
+// is the gap between the border edge and the outline: a spacing length. A
+// radius token there would tie every focus ring to the corner radius.
+const PROPERTY_KIND_OVERRIDES = Object.freeze({
+  'outline-offset': 'spacing',
+});
+
+/**
+ * The kind of length a property takes, for choosing tokens and a group's
+ * scale. The property group, except where PROPERTY_KIND_OVERRIDES says otherwise.
+ */
+function propertyKindOf(prop) {
+  const lower = String(prop || '').toLowerCase();
+  return PROPERTY_KIND_OVERRIDES[lower] || propertyGroupOf(lower);
+}
+
 const DEFAULT_PROPERTY_GROUPS = Object.freeze(['spacing']);
 const PROPERTY_GROUP_NAMES = Object.freeze(Object.keys(PROPERTY_GROUP_PATTERNS));
 
@@ -101,6 +125,8 @@ const SUPPORTED_SCALE_UNITS = new Set([
 const DEFAULT_MATH_FUNCTION_ARGUMENT_FILTER = Object.freeze({});
 
 module.exports = {
+  propertyGroupOf,
+  propertyKindOf,
   DEFAULT_IGNORE_KEYWORDS,
   DEFAULT_MATH_FUNCTION_ARGUMENT_FILTER,
   DEFAULT_PROPERTY_GROUPS,

package/src/core/options.js

@@ -11,6 +11,7 @@ const {
   PROPERTY_GROUP_PATTERNS,
   SPACING_PROPERTY_PATTERNS,
   SUPPORTED_SCALE_UNITS,
+  propertyKindOf,
 } = require('./css-vocabulary');
 const { parseLengthToken } = require('./length');
 const {
@@ -257,6 +258,42 @@ function isPropertyScaleMap(value) {
   });
 }
 
+// Groups that take a length scale of their own; motion has use-motion-scale.
+const SCALED_GROUPS = Object.freeze(['spacing', 'radius', 'size', 'typography']);
+
+/** One group's scale: values, a preset name, "auto", or a { preset | scale | customScale } object. */
+function isGroupScaleEntry(value) {
+  if (isAutoScaleLiteral(value)) {
+    return true;
+  }
+  if (typeof value === 'string') {
+    return Boolean(getScalePreset(value));
+  }
+  return isScaleOverrideEntry(value);
+}
+
+function isGroupScalesMap(value) {
+  return isPlainObject(value)
+    && Object.entries(value).every(([group, scale]) => SCALED_GROUPS.includes(group) && isGroupScaleEntry(scale));
+}
+
+/**
+ * `scales` normalised to { group: { auto, scale } }. A group set to "auto"
+ * has no scale until the rule infers one from that group's tokens.
+ */
+function buildGroupScales(scales) {
+  if (!isGroupScalesMap(scales)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(scales).map(([group, entry]) => {
+    if (isAutoScaleLiteral(entry)) {
+      return [group, { auto: true, scale: null }];
+    }
+    const scale = typeof entry === 'string' ? getScalePreset(entry) : resolveScaleOverride(entry);
+    return [group, { auto: false, scale: Array.isArray(scale) ? [...scale] : null }];
+  }));
+}
+
 function buildPossibleOptionMap(schema) {
   return Object.fromEntries(
     Object.entries(schema).map(([optionName, descriptor]) => [
@@ -398,6 +435,9 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isScaleEntry,
     expectsArray: true,
   }),
+  checkMathBounds: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   enforceInsideMathFunctions: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -460,6 +500,10 @@ const USE_SCALE_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isPropertyScaleMap,
     expectsObject: true,
   }),
+  scales: Object.freeze({
+    entryValidator: isGroupScalesMap,
+    expectsObject: true,
+  }),
   tokenFunctions: Object.freeze({
     entryValidator: isNonEmptyString,
     expectsArray: true,
@@ -487,6 +531,9 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isScaleEntry,
     expectsArray: true,
   }),
+  checkMathBounds: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   enforceInsideMathFunctions: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -520,6 +567,10 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isPropertyScaleMap,
     expectsObject: true,
   }),
+  scales: Object.freeze({
+    entryValidator: isGroupScalesMap,
+    expectsObject: true,
+  }),
   scale: Object.freeze({
     allowLiterals: ['auto'],
     entryValidator: isScaleEntryOrAuto,
@@ -586,6 +637,7 @@ function buildScaleOptions(rawOptions) {
       options.baseFontSize > 0
         ? options.baseFontSize
         : 16,
+    checkMathBounds: options.checkMathBounds === true,
     enforceInsideMathFunctions: options.enforceInsideMathFunctions === true,
     fixToScale: options.fixToScale !== false,
     fixWith: options.fixWith === 'token' ? 'token' : 'value',
@@ -601,6 +653,7 @@ function buildScaleOptions(rawOptions) {
     properties: resolvePropertyPatterns(options),
     propertyGroups: normalizePropertyGroups(options.propertyGroups),
     propertyScaleOverrides: buildPropertyScaleOverrides(options.propertyScales),
+    groupScales: buildGroupScales(options.scales),
     scale: scaleSelection.scale,
     scaleAuto: isAutoScaleLiteral(options.scale),
     scaleSources: Array.isArray(options.scaleSources) ? options.scaleSources : [],
@@ -634,6 +687,7 @@ function buildTokenOptions(rawOptions) {
       options.baseFontSize > 0
         ? options.baseFontSize
         : 16,
+    checkMathBounds: options.checkMathBounds === true,
     enforceInsideMathFunctions: options.enforceInsideMathFunctions === true,
     ignoreMathFunctionArguments: normalizeMathFunctionArgumentMap(options.ignoreMathFunctionArguments),
     ignoreValues: Array.isArray(options.ignoreValues)
@@ -647,6 +701,7 @@ function buildTokenOptions(rawOptions) {
     properties: resolvePropertyPatterns(options),
     propertyGroups: normalizePropertyGroups(options.propertyGroups),
     propertyScaleOverrides: buildPropertyScaleOverrides(options.propertyScales),
+    groupScales: buildGroupScales(options.scales),
     scale: scaleSelection.scale,
     scaleAuto: isAutoScaleLiteral(options.scale),
     scaleSources: Array.isArray(options.scaleSources) ? options.scaleSources : [],
@@ -688,8 +743,9 @@ function createPropertyScaleResolver(options) {
     if (cached) {
       return cached;
     }
-    const selectedScale = resolvePropertyScale(prop, options);
+    const { group, scale: selectedScale } = resolvePropertyScaleEntry(prop, options);
     const state = {
+      group,
       scaleByUnit: normalizeScaleByUnit(selectedScale),
       scalePx: normalizeScale(selectedScale, options.baseFontSize),
     };
@@ -699,29 +755,41 @@ function createPropertyScaleResolver(options) {
 }
 
 function resolvePropertyScale(prop, options) {
-  if (!Array.isArray(options.propertyScaleOverrides)) {
-    return options.scale;
-  }
+  return resolvePropertyScaleEntry(prop, options).scale;
+}
 
-  for (const override of options.propertyScaleOverrides) {
+/**
+ * The scale a property is checked against, most specific first: a
+ * `propertyScales` entry for the property, then the `scales` entry for its
+ * group, then `scale`. `group` is set only when `scales` supplied it, so a
+ * message can say which scale it means.
+ */
+function resolvePropertyScaleEntry(prop, options) {
+  for (const override of options.propertyScaleOverrides || []) {
     if (override.matcher instanceof RegExp) {
       if (override.matcher.global || override.matcher.sticky) {
         override.matcher.lastIndex = 0;
       }
 
       if (override.matcher.test(prop)) {
-        return override.scale;
+        return { group: null, scale: override.scale };
       }
 
       continue;
     }
 
     if (String(override.matcher).toLowerCase() === prop.toLowerCase()) {
-      return override.scale;
+      return { group: null, scale: override.scale };
     }
   }
 
-  return options.scale;
+  const group = propertyKindOf(prop);
+  const groupScale = group && options.groupScales ? options.groupScales[group] : null;
+  if (groupScale && Array.isArray(groupScale.scale)) {
+    return { group, scale: groupScale.scale };
+  }
+
+  return { group: null, scale: options.scale };
 }
 
 module.exports = {
@@ -737,7 +805,9 @@ module.exports = {
   USE_SCALE_VALIDATION_SCHEMA,
   buildScaleOptions,
   buildTokenOptions,
+  SCALED_GROUPS,
   createPropertyScaleResolver,
+  isGroupScalesMap,
   isPlainObject,
   resolvePropertyScale,
 };

package/src/core/scale-inference.js

@@ -201,12 +201,16 @@ function scaleFromSources(sources, baseFontSize) {
  * `.rhythmguardrc.json` token sources and installed token packages. The same
  * places scale inference reads, in the same order.
  */
-function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenRegex }) {
+function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenPattern = null, tokenRegex }) {
   const definitions = root ? stylesheetDefinitions(root, tokenRegex, baseFontSize) : new Map();
   const sources = [...scaleSources, ...rcTokenSources(process.cwd()), ...discoverTokenPackages(process.cwd())];
-  const parsed = parseSourcesCached(sources, baseFontSize);
-  if (parsed) {
-    for (const [token, definition] of parsed.definitions) {
+  // A rule's own tokenPattern (`^--space-|^--radius-`) also applies to the
+  // files it reads, on top of the spacing names, unless a source sets its own.
+  const withPattern = tokenPattern
+    ? sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source }))
+    : [];
+  for (const parsed of [parseSourcesCached(sources, baseFontSize), parseSourcesCached(withPattern, baseFontSize)]) {
+    for (const [token, definition] of parsed ? parsed.definitions : []) {
       if (!definitions.has(token)) {
         definitions.set(token, definition);
       }
@@ -518,19 +522,58 @@ function fallbackInference(rejected = null) {
  * an explicit scale pass through untouched.
  */
 function withResolvedScale(options, root) {
-  if (!options.scaleAuto) {
-    return options;
+  if (options.scaleAuto) {
+    const inference = resolveAutoScale({
+      baseFontSize: options.baseFontSize,
+      root,
+      scaleSources: options.scaleSources,
+      tailwindConfigPath: options.tailwindConfigPath,
+      tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
+    });
+    options.scale = inference.scale;
+    options.scaleInference = inference;
+  }
+  for (const [group, entry] of Object.entries(options.groupScales || {})) {
+    if (entry.auto) {
+      entry.scale = inferGroupScale(group, options, root);
+    }
+  }
+  return options;
+}
+
+// Token names each group's "auto" reads. Spacing is the project scale itself.
+const GROUP_TOKEN_PATTERNS = Object.freeze({
+  radius: /^--radius-/,
+  size: /^--(?:size|width|height|container)-/,
+  typography: /^--(?:font-size|text|fs)-/,
+});
+
+/**
+ * A group's scale from its own tokens (`--font-size-*` and Tailwind's
+ * `--text-*` for typography, `--radius-*` for radius). Null when fewer than
+ * four values are found, and the group then uses `scale`. Fluid tokens
+ * (`clamp()`) have no single value and are not part of an inferred scale.
+ */
+function inferGroupScale(group, options, root) {
+  if (group === 'spacing') {
+    return options.scaleAuto ? options.scale : resolveAutoScale({
+      baseFontSize: options.baseFontSize,
+      root,
+      scaleSources: options.scaleSources,
+      tailwindConfigPath: options.tailwindConfigPath,
+      tokenPattern: DEFAULT_AUTO_TOKEN_PATTERN,
+    }).scale;
   }
-  const inference = resolveAutoScale({
+  const pattern = GROUP_TOKEN_PATTERNS[group];
+  const definitions = collectTokenDefinitions({
     baseFontSize: options.baseFontSize,
     root,
     scaleSources: options.scaleSources,
-    tailwindConfigPath: options.tailwindConfigPath,
-    tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
+    tokenPattern: pattern.source,
+    tokenRegex: pattern,
   });
-  options.scale = inference.scale;
-  options.scaleInference = inference;
-  return options;
+  const own = new Map([...definitions].filter(([token]) => pattern.test(token)));
+  return own.size > 0 ? scaleFromDefinitions(own, options.baseFontSize) : null;
 }
 
 function autoScaleFallbackNote(inference) {

package/src/core/token-index.js

@@ -1,7 +1,39 @@
 'use strict';
 
+const { propertyKindOf } = require('./css-vocabulary');
 const { fixedLengthValue, numbersEqual, toPx } = require('./length');
-const { parseTokenValueLength } = require('./token-sources');
+const { createTokenKindMatcher, parseTokenValueLength } = require('./token-sources');
+
+// Dedicated kinds first: a name like --radius-space-1 is a radius token.
+const TOKEN_KINDS = ['radius', 'typography', 'motion', 'size', 'spacing'].map((kind) => [kind, createTokenKindMatcher(kind)]);
+
+// Which token kinds may stand in for a property of each group. Spacing and size
+// share tokens in many systems (Open Props --size-*, mittwald --size-px--*);
+// radius, type and motion tokens serve only their own properties.
+const ACCEPTED_KINDS = Object.freeze({
+  motion: ['motion'],
+  radius: ['radius'],
+  size: ['size', 'spacing'],
+  spacing: ['spacing', 'size'],
+  typography: ['typography'],
+});
+
+/** The kind a token's name declares, or null when the name says nothing. */
+function tokenKindOf(token) {
+  const found = TOKEN_KINDS.find(([, matches]) => matches(token));
+  return found ? found[0] : null;
+}
+
+/**
+ * Whether a token may be offered for a property: a padding never gets a radius
+ * token, even when both hold 16px and the token pattern admits both. A token
+ * whose name declares no kind, or a property outside every group, is allowed.
+ */
+function tokenFitsProperty(token, prop) {
+  const group = prop ? propertyKindOf(prop) : null;
+  const kind = group ? tokenKindOf(String(token).replace(/^var\(\s*|\s*\)$/g, '')) : null;
+  return !group || !kind || ACCEPTED_KINDS[group].includes(kind);
+}
 
 /**
  * Which token a fix may write for a length. Strict on purpose: the token must
@@ -19,24 +51,37 @@ function tokenIndexFromDefinitions(definitions, baseFontSize = 16) {
       const unit = parsed.unit || 'px';
       const px = toPx(Math.abs(parsed.number), unit, baseFontSize);
       if (px === null || !Number.isFinite(px) || px === 0) continue;
-      index.push({ px, raw: String(raw).trim(), token: definition.token, unit });
+      const file = definition.files ? [...definition.files][0] : null;
+      index.push({ file: file && file !== 'stylesheet' ? file : null, px, raw: String(raw).trim(), token: definition.token, unit });
     }
   }
   return index;
 }
 
-function tokenForLength(index, px, unit) {
+/**
+ * Every custom property that holds a length, for one property. The shared
+ * resolver behind use-scale's `fixWith: "token"` and prefer-token, so the two
+ * rules always know the same tokens. Same unit first; with `anyUnit`, a token
+ * in another unit that holds the same px value counts when none matches the
+ * unit. Sorted, so messages are stable.
+ */
+function tokensForLength(index, px, unit, { anyUnit = false, prop = null } = {}) {
   const wanted = unit || 'px';
-  const candidates = new Set();
+  const sameUnit = new Set();
+  const otherUnit = new Set();
   for (const entry of index) {
-    if (entry.token.startsWith('--') && entry.unit === wanted && numbersEqual(entry.px, Math.abs(px))) {
-      candidates.add(entry.token);
+    if (!entry.token.startsWith('--') || !numbersEqual(entry.px, Math.abs(px)) || !tokenFitsProperty(entry.token, prop)) {
+      continue;
     }
+    (entry.unit === wanted ? sameUnit : otherUnit).add(entry.token);
   }
-  if (candidates.size !== 1) {
-    return null;
-  }
-  return `var(${[...candidates][0]})`;
+  const found = sameUnit.size > 0 || !anyUnit ? sameUnit : otherUnit;
+  return [...found].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+}
+
+function tokenForLength(index, px, unit, prop = null) {
+  const candidates = tokensForLength(index, px, unit, { prop });
+  return candidates.length === 1 ? `var(${candidates[0]})` : null;
 }
 
 /** A negative token reference that is still valid where it is written. */
@@ -54,9 +99,9 @@ function negateReplacement(replacement) {
  * The replacement text a length rule writes: the matching token when the
  * options ask for one and exactly one qualifies, otherwise the literal.
  */
-function replacementFor(parsedLength, nearestPx, options) {
+function replacementFor(parsedLength, nearestPx, options, prop = null) {
   if (options.fixWith === 'token' && options.tokenIndex) {
-    const token = tokenForLength(options.tokenIndex, nearestPx, parsedLength.unit || 'px');
+    const token = tokenForLength(options.tokenIndex, nearestPx, parsedLength.unit || 'px', prop);
     if (token) {
       return parsedLength.number < 0 ? negateReplacement(token) : token;
     }
@@ -76,7 +121,10 @@ function tokenHoldsNote(replacement, formattedNearest) {
 module.exports = {
   negateReplacement,
   replacementFor,
+  tokenFitsProperty,
   tokenHoldsNote,
   tokenForLength,
   tokenIndexFromDefinitions,
+  tokenKindOf,
+  tokensForLength,
 };

package/src/core/token-packages.json

@@ -86,6 +86,13 @@
         "dist/nhsuk/core/settings/_spacing.scss"
       ],
       "note": "$nhsuk-spacing-points map"
+    },
+    {
+      "name": "@mozilla-protocol/tokens",
+      "files": [
+        "dist/units/units.custom-properties.css"
+      ],
+      "note": "--spacing-xs..2xl in px; Protocol's Sass $spacing-* come from the same package"
     }
   ]
 }