stylelint-plugin-rhythmguard 2.1.0 → 2.2.0

package/src/rules/no-offscale-transform/index.js

@@ -5,6 +5,7 @@ const valueParser = require('postcss-value-parser');
 const {
   formatLength,
   fromPx,
+  isHairlineLength,
   nearestScaleValues,
   normalizeScale,
   normalizeScaleByUnit,
@@ -25,6 +26,11 @@ const {
   walkTransformTranslateNodes,
 } = require('../../utils/value-utils');
 
+const {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  resolveAutoScale,
+} = require('../../utils/scale-inference');
+
 const ruleName = 'rhythmguard/no-offscale-transform';
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
@@ -84,6 +90,18 @@ const ruleFunction = (primary, secondaryOptions) => {
       });
     }
 
+    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;
+    }
+
     const scaleCache = new Map();
     const getScaleStateForProperty = (prop) => {
       const cached = scaleCache.get(prop);
@@ -152,6 +170,10 @@ const ruleFunction = (primary, secondaryOptions) => {
           return;
         }
 
+        if (options.allowHairlines && isHairlineLength(parsedLength, options.baseFontSize)) {
+          return;
+        }
+
         if (!options.allowNegative && parsedLength.number < 0) {
           return;
         }

package/src/rules/prefer-token/index.js

@@ -4,6 +4,7 @@ const stylelint = require('stylelint');
 const valueParser = require('postcss-value-parser');
 const {
   formatLength,
+  isHairlineLength,
   normalizeScale,
   normalizeScaleByUnit,
   numbersEqual,
@@ -28,6 +29,11 @@ const {
 } = require('../../utils/value-utils');
 const { buildEffectiveTokenMap } = require('../../utils/token-map');
 
+const {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  resolveAutoScale,
+} = require('../../utils/scale-inference');
+
 const ruleName = 'rhythmguard/prefer-token';
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
@@ -112,6 +118,18 @@ const ruleFunction = (primary, secondaryOptions) => {
       });
     }
 
+    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;
+    }
+
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     const tokenMap = buildEffectiveTokenMap({
       options,
@@ -196,6 +214,16 @@ const ruleFunction = (primary, secondaryOptions) => {
           return false;
         }
 
+        // Percentages are relative to the container or the element itself; they are
+        // never spacing-token candidates (translate(-50%, -50%) centering, inset: 100%).
+        if (parsedLength.unit === '%') {
+          return false;
+        }
+
+        if (options.allowHairlines && isHairlineLength(parsedLength, options.baseFontSize)) {
+          return false;
+        }
+
         if (
           parsedLength.unit &&
           parsedLength.unit !== '%' &&

package/src/rules/use-scale/index.js

@@ -5,6 +5,7 @@ const valueParser = require('postcss-value-parser');
 const {
   formatLength,
   fromPx,
+  isHairlineLength,
   nearestScaleValues,
   normalizeScale,
   normalizeScaleByUnit,
@@ -29,13 +30,19 @@ const {
   walkTransformTranslateNodes,
 } = require('../../utils/value-utils');
 
+const {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  autoScaleFallbackNote,
+  resolveAutoScale,
+} = require('../../utils/scale-inference');
+
 const ruleName = 'rhythmguard/use-scale';
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, lower, upper) =>
-    `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).`,
+  rejected: (value, lower, upper, note = '') =>
+    `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
 });
 
 function getFixedNodeValue(parsedLength, nearestPx, options) {
@@ -82,7 +89,16 @@ function checkLengthValue({
     return false;
   }
 
-  if (parsedLength.unit === '%' && options.allowPercentages) {
+  if (parsedLength.unit === '%') {
+    if (options.allowPercentages) {
+      return false;
+    }
+
+    report(node.value, decl, node, null, null, '%');
+    return false;
+  }
+
+  if (options.allowHairlines && isHairlineLength(parsedLength, options.baseFontSize)) {
     return false;
   }
 
@@ -180,8 +196,21 @@ const ruleFunction = (primary, secondaryOptions) => {
       });
     }
 
+    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;
+    }
+
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     const scaleCache = new Map();
+    let fallbackNote = autoScaleFallbackNote(options.scaleInference);
 
     const getScaleStateForProperty = (prop) => {
       const cached = scaleCache.get(prop);
@@ -208,7 +237,7 @@ const ruleFunction = (primary, secondaryOptions) => {
       const payload = {
         endIndex,
         index,
-        message: messages.rejected(value, lower, upper),
+        message: messages.rejected(value, lower, upper, fallbackNote),
         node: decl,
         result,
         ruleName,
@@ -221,6 +250,7 @@ const ruleFunction = (primary, secondaryOptions) => {
         };
       }
 
+      fallbackNote = '';
       stylelint.utils.report(payload);
     };
 

package/src/utils/length.js

@@ -25,6 +25,21 @@ function parseLengthToken(rawValue) {
   return { number, raw: value, unit };
 }
 
+/**
+ * A hairline is a non-zero length that resolves to one CSS pixel or less:
+ * 1px, -1px, 0.5px, 0.0625rem. Such values compensate for a border width or a
+ * rendering quirk; they are not spacing decisions, so the scale rules exempt
+ * them by default (`allowHairlines`).
+ */
+function isHairlineLength(parsedLength, baseFontSize) {
+  if (!parsedLength || parsedLength.number === 0 || parsedLength.unit === '%') {
+    return false;
+  }
+
+  const px = toPx(Math.abs(parsedLength.number), parsedLength.unit || 'px', baseFontSize);
+  return px !== null && px > 0 && px <= 1;
+}
+
 function toPx(number, unit, baseFontSize) {
   if (unit === '' || unit === 'px') {
     return number;
@@ -168,6 +183,7 @@ function nearestScaleValues(target, scale) {
 module.exports = {
   formatLength,
   fromPx,
+  isHairlineLength,
   nearestScaleValues,
   normalizeScale,
   normalizeScaleByUnit,

package/src/utils/options.js

@@ -65,6 +65,22 @@ function isUnitStrategy(value) {
   return value === 'convert' || value === 'exact';
 }
 
+function isAutoScaleLiteral(value) {
+  return value === 'auto';
+}
+
+function isScaleEntryOrAuto(value) {
+  return isAutoScaleLiteral(value) || isScaleEntry(value);
+}
+
+function isScaleSourceEntry(value) {
+  if (isNonEmptyString(value)) {
+    return true;
+  }
+
+  return isPlainObject(value) && (isNonEmptyString(value.path) || isNonEmptyString(value.file));
+}
+
 function isScaleEntry(value) {
   if (typeof value === 'number') {
     return Number.isFinite(value) && value >= 0;
@@ -237,7 +253,10 @@ function validateSecondaryOptionShapes(result, ruleName, secondaryOptions, schem
       continue;
     }
 
-    if (descriptor.expectsArray && !Array.isArray(optionValue)) {
+    const literalAllowed = Array.isArray(descriptor.allowLiterals)
+      && descriptor.allowLiterals.includes(optionValue);
+
+    if (descriptor.expectsArray && !Array.isArray(optionValue) && !literalAllowed) {
       valid = false;
       result.warn(
         `Invalid value ${stringifyOptionValue(optionValue)} for option "${optionName}" of rule "${ruleName}"`,
@@ -412,6 +431,9 @@ function resolveUnits(options) {
 }
 
 const SCALE_VALIDATION_SCHEMA = Object.freeze({
+  allowHairlines: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   allowNegative: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -443,9 +465,17 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isNonEmptyString,
   }),
   scale: Object.freeze({
-    entryValidator: isScaleEntry,
+    allowLiterals: ['auto'],
+    entryValidator: isScaleEntryOrAuto,
     expectsArray: true,
   }),
+  scaleSources: Object.freeze({
+    entryValidator: isScaleSourceEntry,
+    expectsArray: true,
+  }),
+  tailwindConfigPath: Object.freeze({
+    entryValidator: isNonEmptyString,
+  }),
   unitStrategy: Object.freeze({
     entryValidator: isUnitStrategy,
   }),
@@ -487,6 +517,9 @@ const NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA = Object.freeze({
 });
 
 const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
+  allowHairlines: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   allowNumericScale: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -528,7 +561,12 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
     expectsObject: true,
   }),
   scale: Object.freeze({
-    entryValidator: isScaleEntry,
+    allowLiterals: ['auto'],
+    entryValidator: isScaleEntryOrAuto,
+    expectsArray: true,
+  }),
+  scaleSources: Object.freeze({
+    entryValidator: isScaleSourceEntry,
     expectsArray: true,
   }),
   tailwindConfigPath: Object.freeze({
@@ -578,6 +616,7 @@ function buildScaleOptions(rawOptions) {
   const scaleSelection = resolveScaleSelection(options, DEFAULT_SCALE);
 
   return {
+    allowHairlines: options.allowHairlines !== false,
     allowNegative: options.allowNegative !== false,
     allowPercentages: options.allowPercentages !== false,
     baseFontSize:
@@ -600,6 +639,13 @@ function buildScaleOptions(rawOptions) {
     propertyGroups: normalizePropertyGroups(options.propertyGroups),
     propertyScaleOverrides: buildPropertyScaleOverrides(options.propertyScales),
     scale: scaleSelection.scale,
+    scaleAuto: isAutoScaleLiteral(options.scale),
+    scaleSources: Array.isArray(options.scaleSources) ? options.scaleSources : [],
+    tailwindConfigPath:
+      typeof options.tailwindConfigPath === 'string' && options.tailwindConfigPath.length > 0
+        ? options.tailwindConfigPath
+        : null,
+    tokenPatternExplicit: typeof options.tokenPattern === 'string' && options.tokenPattern.length > 0,
     tokenFunctions: Array.isArray(options.tokenFunctions)
       ? options.tokenFunctions.map((value) => String(value).toLowerCase())
       : ['var', 'theme', 'token'],
@@ -617,6 +663,7 @@ function buildTokenOptions(rawOptions) {
   const scaleSelection = resolveScaleSelection(options, DEFAULT_SCALE);
 
   return {
+    allowHairlines: options.allowHairlines !== false,
     allowNumericScale: options.allowNumericScale === true,
     baseFontSize:
       typeof options.baseFontSize === 'number' &&
@@ -637,6 +684,9 @@ function buildTokenOptions(rawOptions) {
     propertyGroups: normalizePropertyGroups(options.propertyGroups),
     propertyScaleOverrides: buildPropertyScaleOverrides(options.propertyScales),
     scale: scaleSelection.scale,
+    scaleAuto: isAutoScaleLiteral(options.scale),
+    scaleSources: Array.isArray(options.scaleSources) ? options.scaleSources : [],
+    tokenPatternExplicit: typeof options.tokenPattern === 'string' && options.tokenPattern.length > 0,
     tailwindConfigPath:
       typeof options.tailwindConfigPath === 'string' && options.tailwindConfigPath.length > 0
         ? options.tailwindConfigPath

package/src/utils/scale-inference.js

@@ -0,0 +1,255 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseLengthToken, toPx } = require('./length');
+const { buildEffectiveTokenMap } = require('./token-map');
+const { parseTokenSources } = require('./token-sources');
+const { getScalePreset } = require('../presets/scales');
+
+// Matches the audit default so lint and audit agree on what a spacing token is.
+const DEFAULT_AUTO_TOKEN_PATTERN = '(^--|-)(?<!letter-)(?<!word-)(space|spacing)(-|$)';
+// Tailwind v4 defines one base (`--spacing: 0.25rem`) and derives utilities by multiplying it.
+const TAILWIND_BASE_TOKENS = new Set(['--spacing', '--space']);
+const TAILWIND_SPACING_MULTIPLIERS = [
+  0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96,
+];
+const FALLBACK_PRESET = 'rhythmic-4';
+// Zero plus at least three distinct token values; a one- or two-token scale is worse than the default.
+const MIN_INFERRED_SCALE_LENGTH = 4;
+const RC_FILE = '.rhythmguardrc.json';
+
+const sourceCache = new Map();
+
+function pxValuesFromKeys(keys, baseFontSize) {
+  const values = new Set([0]);
+
+  for (const key of keys) {
+    const parsed = parseLengthToken(String(key));
+    if (!parsed) {
+      continue;
+    }
+
+    const px = toPx(Math.abs(parsed.number), parsed.unit || 'px', baseFontSize);
+    if (px !== null && Number.isFinite(px)) {
+      values.add(px);
+    }
+  }
+
+  return Array.from(values).sort((a, b) => a - b);
+}
+
+function normalizeSource(source, baseDir) {
+  if (typeof source === 'string') {
+    return { format: 'auto', path: path.resolve(baseDir, source) };
+  }
+
+  if (source && typeof source === 'object') {
+    const rawPath = source.path || source.file;
+    if (typeof rawPath !== 'string') {
+      return null;
+    }
+
+    return {
+      format: typeof source.format === 'string' ? source.format : 'auto',
+      path: path.resolve(source.baseDir || baseDir, rawPath),
+    };
+  }
+
+  return null;
+}
+
+function cacheKey(sources) {
+  return sources
+    .map((source) => {
+      let mtime = 'missing';
+      try {
+        mtime = String(fs.statSync(source.path).mtimeMs);
+      } catch {
+        // missing file: key still changes when it appears
+      }
+      return `${source.path}|${source.format}|${mtime}`;
+    })
+    .join('\n');
+}
+
+function scaleFromSources(sources, baseFontSize) {
+  const normalized = sources.map((source) => normalizeSource(source, process.cwd())).filter(Boolean);
+  if (normalized.length === 0) {
+    return null;
+  }
+
+  const key = `${baseFontSize}\n${cacheKey(normalized)}`;
+  if (sourceCache.has(key)) {
+    return sourceCache.get(key);
+  }
+
+  const parsed = parseTokenSources({ baseFontSize, sources: normalized, tokenKind: 'spacing' });
+  const keys = [];
+  for (const definition of parsed.definitions.values()) {
+    keys.push(...definition.normalizedValues);
+  }
+
+  const scale = pxValuesFromKeys(keys, baseFontSize);
+  const outcome = scale.length >= MIN_INFERRED_SCALE_LENGTH
+    ? {
+      files: parsed.sources.map((source) => source.file),
+      scale,
+      tokenCount: parsed.definitions.size,
+      warnings: parsed.warnings,
+    }
+    : null;
+
+  sourceCache.set(key, outcome);
+  return outcome;
+}
+
+/** Build a px scale from token definitions as produced by token-sources.js / contract.js. */
+function scaleFromDefinitions(definitions, baseFontSize = 16) {
+  const keys = [];
+  const baseKeys = [];
+  for (const definition of definitions.values()) {
+    if (TAILWIND_BASE_TOKENS.has(definition.token)) {
+      baseKeys.push(...definition.normalizedValues);
+      continue;
+    }
+    keys.push(...definition.normalizedValues);
+  }
+  const scale = expandTailwindBase(pxValuesFromKeys(keys, baseFontSize), baseKeys, baseFontSize);
+  return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
+}
+
+/** Merge Tailwind-style base multiples into a scale when a bare --spacing/--space base is defined. */
+function expandTailwindBase(scale, baseKeys, baseFontSize) {
+  const bases = pxValuesFromKeys(baseKeys, baseFontSize).filter((value) => value > 0);
+  if (bases.length === 0) {
+    return scale;
+  }
+  const values = new Set(scale);
+  for (const base of bases) {
+    for (const multiplier of TAILWIND_SPACING_MULTIPLIERS) {
+      values.add(Math.round(base * multiplier * 1000) / 1000);
+    }
+  }
+  return Array.from(values).sort((a, b) => a - b);
+}
+
+function rcTokenSources(cwd) {
+  const rcPath = path.join(cwd, RC_FILE);
+  if (!fs.existsSync(rcPath)) {
+    return [];
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
+  } catch {
+    return [];
+  }
+
+  const audit = config && typeof config === 'object' ? config.audit : null;
+  const sources = audit && Array.isArray(audit.tokenSources) ? audit.tokenSources : [];
+  const baseDir = path.dirname(rcPath);
+
+  return sources
+    .map((source) => normalizeSource(source, baseDir))
+    .filter(Boolean);
+}
+
+function scaleFromTokenMap(map, baseFontSize) {
+  const keys = [];
+  const baseKeys = [];
+  for (const [key, reference] of Object.entries(map)) {
+    const name = String(reference).match(/^var\((--[\w-]+)\)$/);
+    if (name && TAILWIND_BASE_TOKENS.has(name[1])) {
+      baseKeys.push(key);
+    } else {
+      keys.push(key);
+    }
+  }
+  const scale = expandTailwindBase(pxValuesFromKeys(keys, baseFontSize), baseKeys, baseFontSize);
+  return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
+}
+
+/**
+ * Resolve `scale: "auto"`. First matching source wins; sources are not merged so
+ * the provenance is a single file list or the stylesheet.
+ */
+function resolveAutoScale({
+  baseFontSize = 16,
+  root,
+  scaleSources = [],
+  tailwindConfigPath = null,
+  tokenPattern = DEFAULT_AUTO_TOKEN_PATTERN,
+} = {}) {
+  const fromOption = scaleFromSources(scaleSources, baseFontSize);
+  if (fromOption) {
+    return { source: 'scaleSources', ...fromOption };
+  }
+
+  const fromRc = scaleFromSources(rcTokenSources(process.cwd()), baseFontSize);
+  if (fromRc) {
+    return { source: 'rhythmguardrc', ...fromRc };
+  }
+
+  let tokenRegex;
+  try {
+    tokenRegex = new RegExp(tokenPattern);
+  } catch {
+    tokenRegex = new RegExp(DEFAULT_AUTO_TOKEN_PATTERN);
+  }
+
+  if (root) {
+    const stylesheetMap = buildEffectiveTokenMap({
+      options: { baseFontSize, tokenMap: {}, tokenMapFromCssCustomProperties: true },
+      root,
+      tokenRegex,
+    });
+    const scale = scaleFromTokenMap(stylesheetMap, baseFontSize);
+    if (scale) {
+      return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
+    }
+  }
+
+  if (tailwindConfigPath) {
+    const tailwindMap = buildEffectiveTokenMap({
+      options: {
+        baseFontSize,
+        tailwindConfigPath,
+        tokenMap: {},
+        tokenMapFromTailwindSpacing: true,
+      },
+      root,
+      tokenRegex,
+    });
+    const scale = scaleFromTokenMap(tailwindMap, baseFontSize);
+    if (scale) {
+      return { files: [tailwindConfigPath], scale, source: 'tailwind', tokenCount: scale.length - 1, warnings: [] };
+    }
+  }
+
+  return {
+    files: [],
+    preset: FALLBACK_PRESET,
+    scale: getScalePreset(FALLBACK_PRESET),
+    source: 'fallback',
+    tokenCount: 0,
+    warnings: [],
+  };
+}
+
+function autoScaleFallbackNote(inference) {
+  if (!inference || inference.source !== 'fallback') {
+    return '';
+  }
+
+  return `No spacing tokens were found for scale "auto"; using preset "${inference.preset}".`;
+}
+
+module.exports = {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  autoScaleFallbackNote,
+  resolveAutoScale,
+  scaleFromDefinitions,
+};

package/src/utils/token-map.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { parseTokenValueLength } = require('./token-sources');
+
 const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
@@ -43,7 +45,7 @@ function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize) {
     return;
   }
 
-  const parsed = parseLengthToken(rawLength);
+  const parsed = parseTokenValueLength(rawLength);
   if (!parsed) {
     return;
   }
@@ -196,7 +198,7 @@ function mergeTokenMapFromCssCustomProperties({
       return;
     }
 
-    const parsed = parseLengthToken(decl.value);
+    const parsed = parseTokenValueLength(decl.value);
     if (!parsed || parsed.number === 0) {
       return;
     }

package/src/utils/token-sources.js

@@ -31,7 +31,8 @@ const TOKEN_KIND_PATTERNS = Object.freeze({
   radius: /^--radius-/,
   motion: /^--(?:motion|duration|delay|ease|easing)-/,
   size: /^--(?:size|width|height|container)-/,
-  spacing: /^--(?:space|spacing)-/,
+  // Anchored or prefixed (--spacing-4, --lb-spacing-md, bare Tailwind v4 --spacing), never letter-/word-spacing.
+  spacing: /(?:^--|-)(?<!letter-)(?<!word-)(?:space|spacing)(?:-|$)/,
   typography: /^--(?:font|font-size|line-height|leading|tracking|typography)-/,
 });
 
@@ -377,6 +378,34 @@ function addDefinition(definitions, {
   definitions.set(token, entry);
 }
 
+const CALC_LENGTH_TIMES_VAR = /^calc\(\s*(-?[\d.]+(?:px|rem|em)?)\s*\*\s*var\([^()]*\)\s*\)$/i;
+const CALC_VAR_TIMES_LENGTH = /^calc\(\s*var\([^()]*\)\s*\*\s*(-?[\d.]+(?:px|rem|em)?)\s*\)$/i;
+
+/**
+ * Parse the length a token value carries. Accepts plain lengths and the
+ * `calc(<length> * var(--factor))` form design systems use for scaling
+ * (Radix Themes: `--space-1: calc(4px * var(--scaling))`).
+ */
+function parseTokenValueLength(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  const direct = parseLengthToken(trimmed);
+  if (direct) {
+    return direct;
+  }
+
+  const match = trimmed.match(CALC_LENGTH_TIMES_VAR) || trimmed.match(CALC_VAR_TIMES_LENGTH);
+  if (!match) {
+    return null;
+  }
+
+  const inner = parseLengthToken(match[1]);
+  return inner ? { ...inner, raw: trimmed } : null;
+}
+
 function getNormalizedValueKeys(value, baseFontSize = 16) {
   if (value === null || value === undefined) {
     return [];
@@ -388,7 +417,7 @@ function getNormalizedValueKeys(value, baseFontSize = 16) {
   }
 
   const keys = new Set([raw]);
-  const parsed = parseLengthToken(raw);
+  const parsed = parseTokenValueLength(raw);
   if (!parsed) {
     return Array.from(keys);
   }
@@ -417,4 +446,5 @@ module.exports = {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
   parseTokenSources,
+  parseTokenValueLength,
 };