stylelint-plugin-rhythmguard 3.10.2 → 3.12.0

package/src/core/options.js

@@ -14,6 +14,7 @@ const {
   propertyKindOf,
 } = require('./css-vocabulary');
 const { parseLengthToken } = require('./length');
+const { VALID_TOKEN_SOURCE_FORMATS } = require('./token-sources');
 const {
   getScalePreset,
   listScalePresetNames,
@@ -100,7 +101,10 @@ function isScaleSourceEntry(value) {
     return true;
   }
 
-  return isPlainObject(value) && (isNonEmptyString(value.path) || isNonEmptyString(value.file));
+  return isPlainObject(value)
+    && (isNonEmptyString(value.path) || isNonEmptyString(value.file))
+    // An unknown format is an invalid option, not a throw from the parser (issue #265).
+    && (value.format === undefined || VALID_TOKEN_SOURCE_FORMATS.has(String(value.format).trim().toLowerCase()));
 }
 
 function isScaleEntry(value) {
@@ -515,6 +519,8 @@ const USE_SCALE_VALIDATION_SCHEMA = Object.freeze({
 
 const NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA = Object.freeze({
   ...SCALE_VALIDATION_SCHEMA,
+  tokenFunctions: USE_SCALE_VALIDATION_SCHEMA.tokenFunctions,
+  tokenPattern: USE_SCALE_VALIDATION_SCHEMA.tokenPattern,
 });
 
 const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
@@ -809,5 +815,6 @@ module.exports = {
   createPropertyScaleResolver,
   isGroupScalesMap,
   isPlainObject,
+  isScaleEntry,
   resolvePropertyScale,
 };

package/src/core/scale-inference.js

@@ -12,6 +12,7 @@ const {
   parseTokenSources,
   parseTokenValueLength,
 } = require('./token-sources');
+const { normalizeTokenSourceEntry } = require('./token-source-entries');
 const { getScalePreset } = require('../presets/scales');
 
 // Matches the audit default so lint and audit agree on what a spacing token is.
@@ -28,7 +29,6 @@ const RC_FILE = '.rhythmguardrc.json';
 
 const { cachedByFiles } = require('./fs-cache');
 
-const sourceCache = new Map();
 const TOKEN_PACKAGES = require('./token-packages.json').packages;
 
 /**
@@ -112,12 +112,17 @@ function discoverTokenPackagesUncached(cwd, consult) {
   return sources;
 }
 
+/** A non-zero number without a unit is a ratio or a multiplier, not a length (issue #268). */
+function isUnitlessNonZero(parsed) {
+  return parsed.unit === '' && parsed.number !== 0;
+}
+
 function pxValuesFromKeys(keys, baseFontSize) {
   const values = new Set([0]);
 
   for (const key of keys) {
     const parsed = parseLengthToken(String(key));
-    if (!parsed) {
+    if (!parsed || isUnitlessNonZero(parsed)) {
       continue;
     }
 
@@ -130,59 +135,53 @@ function pxValuesFromKeys(keys, baseFontSize) {
   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;
+/**
+ * Parse token sources once per (source set, base font size), revalidated by
+ * the mtime of every source file. The entry is keyed by the paths alone and
+ * replaced when a file changes, so an editor that saves a token file a
+ * thousand times keeps one entry, not a thousand (issue #264). Entries that
+ * do not normalise (a bad format, no path) are skipped with a warning; they
+ * never throw out of a lint.
+ */
+function parseSourcesCached(sources, baseFontSize) {
+  const normalized = [];
+  const warnings = [];
+  for (const entry of sources) {
+    const { error, source } = normalizeTokenSourceEntry(entry, process.cwd());
+    if (error) {
+      warnings.push(error);
+    } else {
+      normalized.push(source);
     }
-
-    return {
-      format: typeof source.format === 'string' ? source.format : 'auto',
-      path: path.resolve(source.baseDir || baseDir, rawPath),
-      ...(source.tokenPattern ? { tokenPattern: source.tokenPattern } : {}),
-    };
   }
-
-  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}|${source.tokenPattern || ''}|${mtime}`;
-    })
-    .join('\n');
-}
-
-/** Parse token sources once per (sources, base font size, file mtimes). */
-function parseSourcesCached(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)) {
-    sourceCache.set(key, parseTokenSources({ baseFontSize, sources: normalized, tokenKind: 'spacing' }));
-  }
-  return sourceCache.get(key);
+    return warnings.length > 0 ? { definitions: new Map(), sources: [], warnings } : null;
+  }
+  const files = normalized.map((source) => path.resolve(source.baseDir, source.path));
+  const key = [
+    `token-sources:${baseFontSize}`,
+    ...normalized.map((source, index) => `${files[index]}|${source.format}|${source.tokenPattern || ''}`),
+  ].join('\n');
+  const parsed = cachedByFiles(key, (consult) => {
+    for (const file of files) {
+      consult(file);
+    }
+    return parseTokenSources({ baseFontSize, sources: normalized, tokenKind: 'spacing' });
+  });
+  return warnings.length > 0 ? { ...parsed, warnings: [...warnings, ...parsed.warnings] } : parsed;
 }
 
-function scaleFromSources(sources, baseFontSize) {
+/**
+ * The scale a list of token sources defines, or null. Warnings from sources
+ * that are missing or do not parse go into `warnings` either way, so a
+ * fallback can say which source failed (issue #270).
+ */
+function scaleFromSources(sources, baseFontSize, warnings = []) {
   const parsed = parseSourcesCached(sources, baseFontSize);
   if (!parsed) {
     return null;
   }
+  warnings.push(...parsed.warnings);
   // scaleFromDefinitions also expands a bare Tailwind --spacing base into its multiples.
   const scale = scaleFromDefinitions(parsed.definitions, baseFontSize);
   return scale
@@ -203,7 +202,7 @@ function scaleFromSources(sources, baseFontSize) {
  */
 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 sources = [...scaleSources, ...rcTokenSources(process.cwd()).sources, ...discoverTokenPackages(process.cwd())];
   // 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
@@ -323,7 +322,7 @@ function expandTailwindBase(scale, baseKeys, baseFontSize) {
 function firstPositivePx(keys, baseFontSize) {
   for (const key of keys) {
     const parsed = parseLengthToken(String(key));
-    if (!parsed) {
+    if (!parsed || isUnitlessNonZero(parsed)) {
       continue;
     }
     const px = toPx(Math.abs(parsed.number), parsed.unit || 'px', baseFontSize);
@@ -342,25 +341,38 @@ function rcTokenSources(cwd) {
   });
 }
 
+/**
+ * Token sources from `audit.tokenSources` in .rhythmguardrc.json, read through
+ * the normaliser the audit uses, so lint and audit read the same files
+ * (issue #271). A file that does not parse or an entry that does not
+ * normalise is a warning, never a throw (issue #265).
+ */
 function rcTokenSourcesUncached(rcPath) {
   if (!fs.existsSync(rcPath)) {
-    return [];
+    return { sources: [], warnings: [] };
   }
 
   let config;
   try {
     config = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
-  } catch {
-    return [];
+  } catch (err) {
+    return { sources: [], warnings: [`${RC_FILE} could not be read: ${err.message}`] };
   }
 
   const audit = config && typeof config === 'object' ? config.audit : null;
-  const sources = audit && Array.isArray(audit.tokenSources) ? audit.tokenSources : [];
+  const entries = audit && Array.isArray(audit.tokenSources) ? audit.tokenSources : [];
   const baseDir = path.dirname(rcPath);
-
-  return sources
-    .map((source) => normalizeSource(source, baseDir))
-    .filter(Boolean);
+  const sources = [];
+  const warnings = [];
+  for (const entry of entries) {
+    const { error, source } = normalizeTokenSourceEntry(entry, baseDir);
+    if (error) {
+      warnings.push(`${RC_FILE}: ${error}`);
+    } else {
+      sources.push(source);
+    }
+  }
+  return { sources, warnings };
 }
 
 /**
@@ -372,7 +384,10 @@ function rcTokenSourcesUncached(rcPath) {
 function sassTokensFromRoot(root) {
   const lines = [];
   root.walkDecls((decl) => {
-    if (typeof decl.prop === 'string' && decl.prop.startsWith('$')) {
+    // Only top-level or `!global` variables are the project's; `$spacer: 2px`
+    // inside `.compact` is local to that block (issue #266).
+    const global = (decl.parent && decl.parent.type === 'root') || /!global\b/.test(String(decl.value));
+    if (typeof decl.prop === 'string' && decl.prop.startsWith('$') && global) {
       lines.push(`${decl.prop}: ${decl.value};`);
     }
   });
@@ -408,12 +423,16 @@ function resolveAutoScale({
   tailwindConfigPath = null,
   tokenPattern = DEFAULT_AUTO_TOKEN_PATTERN,
 } = {}) {
-  const fromOption = scaleFromSources(scaleSources, baseFontSize);
+  // Warnings from every source tried, for the fallback note when none yields a scale.
+  const warnings = [];
+  const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings);
   if (fromOption) {
     return { source: 'scaleSources', ...fromOption };
   }
 
-  const fromRc = scaleFromSources(rcTokenSources(process.cwd()), baseFontSize);
+  const rc = rcTokenSources(process.cwd());
+  warnings.push(...rc.warnings);
+  const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings);
   if (fromRc) {
     return { source: 'rhythmguardrc', ...fromRc };
   }
@@ -454,12 +473,12 @@ function resolveAutoScale({
     }
   }
 
-  const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize);
+  const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize, warnings);
   if (fromPackages) {
     return { source: 'token-package', ...fromPackages };
   }
 
-  return fallbackInference(rejected);
+  return fallbackInference(rejected, warnings);
 }
 
 const TRUSTED_SCALE_SOURCES = new Set(['scaleSources', 'rhythmguardrc', 'token-sources', 'tailwind', 'token-package', 'explicit', 'default']);
@@ -504,7 +523,7 @@ function assessScale({ files = null, source, values = [] } = {}) {
   return { plausible: reasons.length === 0, reasons };
 }
 
-function fallbackInference(rejected = null) {
+function fallbackInference(rejected = null, warnings = []) {
   return {
     files: [],
     preset: FALLBACK_PRESET,
@@ -512,7 +531,7 @@ function fallbackInference(rejected = null) {
     scale: getScalePreset(FALLBACK_PRESET),
     source: 'fallback',
     tokenCount: 0,
-    warnings: [],
+    warnings,
   };
 }
 
@@ -545,7 +564,8 @@ function withResolvedScale(options, root) {
 const GROUP_TOKEN_PATTERNS = Object.freeze({
   radius: /^--radius-/,
   size: /^--(?:size|width|height|container)-/,
-  typography: /^--(?:font-size|text|fs)-/,
+  // Tailwind's `--text-sm--line-height` is a sub-token of `--text-sm`, not a font size (issue #262).
+  typography: /^--(?:font-size|text|fs)-(?!.*--)/,
 });
 
 /**
@@ -556,13 +576,18 @@ const GROUP_TOKEN_PATTERNS = Object.freeze({
  */
 function inferGroupScale(group, options, root) {
   if (group === 'spacing') {
-    return options.scaleAuto ? options.scale : resolveAutoScale({
+    if (options.scaleAuto) {
+      return options.scale;
+    }
+    const inference = resolveAutoScale({
       baseFontSize: options.baseFontSize,
       root,
       scaleSources: options.scaleSources,
       tailwindConfigPath: options.tailwindConfigPath,
       tokenPattern: DEFAULT_AUTO_TOKEN_PATTERN,
-    }).scale;
+    });
+    // No spacing tokens: the group uses `scale`, like every other group (issue #261).
+    return inference.source === 'fallback' ? null : inference.scale;
   }
   const pattern = GROUP_TOKEN_PATTERNS[group];
   const definitions = collectTokenDefinitions({
@@ -581,10 +606,16 @@ function autoScaleFallbackNote(inference) {
     return '';
   }
   if (inference.rejected) {
-    return `The spacing tokens found do not form a spacing scale (${inference.rejected.reasons.join(', ')}); using preset "${inference.preset}".`;
+    return `The spacing tokens found do not form a spacing scale (${inference.rejected.reasons.join(', ')}); using preset "${inference.preset}".${sourceWarningsNote(inference.warnings)}`;
   }
 
-  return `No spacing tokens were found for scale "auto"; using preset "${inference.preset}".`;
+  return `No spacing tokens were found for scale "auto"; using preset "${inference.preset}".${sourceWarningsNote(inference.warnings)}`;
+}
+
+/** Why the token sources gave nothing: a missing file, a parse error, a bad rc entry (issue #270). */
+function sourceWarningsNote(warnings) {
+  const unique = Array.from(new Set(warnings || []));
+  return unique.map((warning) => ` ${/[.!?]$/.test(warning) ? warning : `${warning}.`}`).join('');
 }
 
 module.exports = {

package/src/core/tailwind-class-analysis.js

@@ -6,34 +6,39 @@ const {
   nearestScaleValues,
   nearestText,
   normalizeScale,
-  numbersEqual,
   parseLengthToken,
+  pxOnScale,
   toPx,
 } = require('./length');
 
+// The ESLint rule's and the audit's default scale. It is not the `rhythmic-4`
+// preset (which continues to 40, 48, 64); unifying the defaults changes
+// reports, so it waits for a major (#246).
 const DEFAULT_SCALE = [0, 4, 8, 12, 16, 24, 32];
 const DEFAULT_UNITS = ['px', 'rem', 'em'];
 // Tailwind's numeric spacing utilities are multiples of one unit: `--spacing`
-// (0.25rem, 4px) in v4, and the same 4px step in the v3 default scale.
-const DEFAULT_SPACING_UNIT_PX = 4;
+// (0.25rem) in v4, and the same 0.25rem step in the v3 default scale. In px
+// that is a quarter of the root font size: 4px at 16px, 2.5px at 10px (#247).
+const SPACING_UNIT_REM = 0.25;
 
 const ARBITRARY_SPACING_CLASS = /^(?<utility>-?(?:m(?:[trblxy])?|p(?:[trblxy])?|gap(?:-[xy])?|space-[xy]|inset(?:-[xy])?|top|right|bottom|left|translate-[xy]|scroll-(?:m|p)(?:[trblxy])?))-\[(?<rawValue>[^\]]+)\]$/;
 
 function normalizeTailwindClassOptions(option = {}) {
+  const baseFontSize =
+    typeof option.baseFontSize === 'number' &&
+    Number.isFinite(option.baseFontSize) &&
+    option.baseFontSize > 0
+      ? option.baseFontSize
+      : 16;
   return {
     allowNegative: option.allowNegative !== false,
-    baseFontSize:
-      typeof option.baseFontSize === 'number' &&
-      Number.isFinite(option.baseFontSize) &&
-      option.baseFontSize > 0
-        ? option.baseFontSize
-        : 16,
+    baseFontSize,
     scale: Array.isArray(option.scale) ? option.scale : DEFAULT_SCALE,
     spacingUnit: option.spacingUnit === false
       ? null
       : typeof option.spacingUnit === 'number' && Number.isFinite(option.spacingUnit) && option.spacingUnit > 0
         ? option.spacingUnit
-        : DEFAULT_SPACING_UNIT_PX,
+        : baseFontSize * SPACING_UNIT_REM,
     units: Array.isArray(option.units)
       ? option.units.map((unit) => String(unit).toLowerCase())
       : DEFAULT_UNITS,
@@ -167,7 +172,10 @@ function analyzeClassToken(token, options, scalePx) {
     return null;
   }
 
-  if (!options.allowNegative && parsedLength.number < 0) {
+  // `-m-[16px]` and `m-[-16px]` are both negative margins (#241).
+  const negative = match.groups.utility.startsWith('-') || parsedLength.number < 0;
+
+  if (!options.allowNegative && negative) {
     return {
       fixedToken: null,
       nearest: null,
@@ -187,7 +195,7 @@ function analyzeClassToken(token, options, scalePx) {
     return null;
   }
 
-  const isOnScale = scalePx.some((entry) => numbersEqual(entry, pxValue));
+  const isOnScale = pxOnScale(scalePx, pxValue, parsedLength.unit, options.baseFontSize);
   if (isOnScale) {
     return null;
   }
@@ -205,12 +213,14 @@ function analyzeClassToken(token, options, scalePx) {
     ? signedNearest
     : signedNearest / options.baseFontSize;
 
-  const negative = match.groups.utility.startsWith('-') || parsedLength.number < 0;
   const wrap = (candidate) =>
     `${parsedToken.prefix}${parsedToken.leadingImportant}${candidate}${parsedToken.trailingImportant}`;
-  const utilityFix = utilityClassFor(match.groups.utility, nearest.nearest, negative, options.spacingUnit);
-  const lowerUtility = utilityClassFor(match.groups.utility, nearest.lower, negative, options.spacingUnit);
-  const upperUtility = utilityClassFor(match.groups.utility, nearest.upper, negative, options.spacingUnit);
+  // Utility classes are root-relative; an `em` value follows the element's own
+  // font size, so it keeps the arbitrary form and its unit (#247).
+  const spacingUnit = parsedLength.unit === 'em' ? null : options.spacingUnit;
+  const utilityFix = utilityClassFor(match.groups.utility, nearest.nearest, negative, spacingUnit);
+  const lowerUtility = utilityClassFor(match.groups.utility, nearest.lower, negative, spacingUnit);
+  const upperUtility = utilityClassFor(match.groups.utility, nearest.upper, negative, spacingUnit);
 
   const replacementValue = formatLength(replacementNumber, parsedLength.unit);
   const fixedCandidate = utilityFix || parsedToken.candidate.replace(match.groups.rawValue, replacementValue);

package/src/core/tailwind-motion-analysis.js

@@ -15,6 +15,9 @@ const {
 const { findClassSegments } = require('./tailwind-class-analysis');
 
 const ARBITRARY_MOTION_CLASS = /^(?<utility>duration|delay|ease)-\[(?<rawValue>[^\]]+)\]$/;
+// The raw curves the Stylelint rule reports; anything else in `ease-[...]`,
+// such as `var(--ease-out)` or `--my-ease`, is already a token (#245).
+const RAW_EASING_CURVE = /^(?:cubic-bezier|linear|steps)\(/i;
 
 function normalizeTailwindMotionOptions(option = {}) {
   return {
@@ -85,6 +88,10 @@ function analyzeMotionToken(token, options) {
   }
 
   if (match.groups.utility === 'ease') {
+    if (!RAW_EASING_CURVE.test(match.groups.rawValue.trim())) {
+      return null;
+    }
+
     return {
       fixedToken: null,
       rawValue: match.groups.rawValue,
@@ -98,7 +105,9 @@ function analyzeMotionToken(token, options) {
     return null;
   }
 
-  if (parsedTime.number < 0) {
+  // A negative delay starts the motion partway through and is valid; only a
+  // negative duration is (#236). The size of a delay is still checked.
+  if (parsedTime.number < 0 && match.groups.utility === 'duration') {
     return {
       fixedToken: null,
       nearest: null,
@@ -112,7 +121,7 @@ function analyzeMotionToken(token, options) {
     return null;
   }
 
-  const msValue = toMs(parsedTime.number, parsedTime.unit);
+  const msValue = toMs(Math.abs(parsedTime.number), parsedTime.unit);
   if (msValue === null) {
     return null;
   }
@@ -132,7 +141,7 @@ function analyzeMotionToken(token, options) {
     return null;
   }
 
-  const replacementValue = formatTime(converted, parsedTime.unit);
+  const replacementValue = formatTime(parsedTime.number < 0 ? -converted : converted, parsedTime.unit);
   const fixedCandidate = parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
   const fixedToken = `${parsedToken.prefix}${parsedToken.leadingImportant}${fixedCandidate}${parsedToken.trailingImportant}`;
 

package/src/core/token-index.js

@@ -35,24 +35,42 @@ function tokenFitsProperty(token, prop) {
   return !group || !kind || ACCEPTED_KINDS[group].includes(kind);
 }
 
+/**
+ * The lengths one definition holds, each with its signed px value, or null
+ * when the token holds more than one value. A token redefined under a media
+ * query, a theme or a data attribute (`--space-3: 12px` at the root and 20px
+ * from 768px up) renders differently there, so no single length stands for it
+ * (issue #231). A value that is not a plain length counts as another value.
+ */
+function singleValuedLengths(definition, baseFontSize) {
+  const lengths = [];
+  for (const raw of definition.values) {
+    const parsed = parseTokenValueLength(String(raw).trim());
+    if (!parsed) return definition.values.size > 1 ? null : [];
+    const unit = parsed.unit || 'px';
+    const px = toPx(parsed.number, unit, baseFontSize);
+    if (px === null || !Number.isFinite(px)) return definition.values.size > 1 ? null : [];
+    lengths.push({ px, raw: String(raw).trim(), unit });
+  }
+  return lengths.every((length) => numbersEqual(length.px, lengths[0].px)) ? lengths : null;
+}
+
 /**
  * Which token a fix may write for a length. Strict on purpose: the token must
- * hold the same px value in the same unit as the literal being fixed, it must
- * be a custom property (a Sass variable is not valid in CSS output), and it
- * must be the only candidate. A fix that guesses a token is worse than a fix
- * that writes a number, so anything ambiguous falls back to the literal.
+ * hold the same px value, with the same sign, in the same unit as the literal
+ * being fixed, it must hold that one value everywhere, it must be a custom
+ * property (a Sass variable is not valid in CSS output), and it must be the
+ * only candidate. A fix that guesses a token is worse than a fix that writes
+ * a number, so anything ambiguous falls back to the literal.
  */
 function tokenIndexFromDefinitions(definitions, baseFontSize = 16) {
   const index = [];
   for (const definition of definitions.values()) {
-    for (const raw of definition.values) {
-      const parsed = parseTokenValueLength(String(raw).trim());
-      if (!parsed) continue;
-      const unit = parsed.unit || 'px';
-      const px = toPx(Math.abs(parsed.number), unit, baseFontSize);
-      if (px === null || !Number.isFinite(px) || px === 0) continue;
+    const lengths = singleValuedLengths(definition, baseFontSize);
+    for (const { px, raw, unit } of lengths || []) {
+      if (px === 0) continue;
       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 });
+      index.push({ file: file && file !== 'stylesheet' ? file : null, px, raw, token: definition.token, unit });
     }
   }
   return index;
@@ -61,16 +79,17 @@ function tokenIndexFromDefinitions(definitions, baseFontSize = 16) {
 /**
  * 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.
+ * rules always know the same tokens. The px value is signed: 8 finds the
+ * tokens that hold 8px, -8 the tokens that hold -8px. 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 sameUnit = new Set();
   const otherUnit = new Set();
   for (const entry of index) {
-    if (!entry.token.startsWith('--') || !numbersEqual(entry.px, Math.abs(px)) || !tokenFitsProperty(entry.token, prop)) {
+    if (!entry.token.startsWith('--') || !numbersEqual(entry.px, px) || !tokenFitsProperty(entry.token, prop)) {
       continue;
     }
     (entry.unit === wanted ? sameUnit : otherUnit).add(entry.token);
@@ -79,6 +98,22 @@ function tokensForLength(index, px, unit, { anyUnit = false, prop = null } = {})
   return [...found].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
 }
 
+/**
+ * The tokens for a signed length, and whether a fix negates them. A negative
+ * value takes the tokens that hold it, written as they are, and otherwise the
+ * tokens that hold its magnitude, negated. A positive value never gets a
+ * negative token (issue #221).
+ */
+function signedTokensForLength(index, px, unit, options = {}) {
+  if (px < 0) {
+    const negative = tokensForLength(index, px, unit, options);
+    if (negative.length > 0) {
+      return { negate: false, tokens: negative };
+    }
+  }
+  return { negate: px < 0, tokens: tokensForLength(index, Math.abs(px), unit, options) };
+}
+
 function tokenForLength(index, px, unit, prop = null) {
   const candidates = tokensForLength(index, px, unit, { prop });
   return candidates.length === 1 ? `var(${candidates[0]})` : null;
@@ -97,30 +132,47 @@ 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.
+ * options ask for one and exactly one qualifies, otherwise the literal. The
+ * nearest value is in px, or in the literal's unit with `unitStrategy:
+ * "exact"`; tokens are indexed in px, so the lookup converts it (issue #223).
+ * `avoidTokens` are the var() names a fallback literal falls back from; one
+ * of them is never written, the literal is.
  */
-function replacementFor(parsedLength, nearestPx, options, prop = null) {
+function replacementFor(parsedLength, nearest, options, prop = null, avoidTokens = []) {
   if (options.fixWith === 'token' && options.tokenIndex) {
-    const token = tokenForLength(options.tokenIndex, nearestPx, parsedLength.unit || 'px', prop);
-    if (token) {
-      return parsedLength.number < 0 ? negateReplacement(token) : token;
+    const unit = parsedLength.unit || 'px';
+    const nearestPx = options.unitStrategy === 'exact' ? toPx(Math.abs(nearest), unit, options.baseFontSize) : Math.abs(nearest);
+    if (nearestPx !== null) {
+      const signedPx = parsedLength.number < 0 ? -nearestPx : nearestPx;
+      const { negate, tokens } = signedTokensForLength(options.tokenIndex, signedPx, unit, { prop });
+      // A var() fallback never falls back to the token it is the fallback of (issue #240).
+      if (tokens.length === 1 && !avoidTokens.includes(tokens[0])) {
+        const token = `var(${tokens[0]})`;
+        return negate ? negateReplacement(token) : token;
+      }
     }
   }
-  return fixedLengthValue(parsedLength, nearestPx, options);
+  return fixedLengthValue(parsedLength, nearest, options);
 }
 
 /**
  * The sentence a length rule appends when its fix writes a token: which token
- * holds the snapped value. Empty when the replacement is a literal.
+ * holds the snapped value. Empty when the replacement is a literal. A token
+ * written as is for a negative literal holds the negative value.
  */
-function tokenHoldsNote(replacement, formattedNearest) {
+function tokenHoldsNote(replacement, formattedNearest, negativeLiteral = false) {
   const match = typeof replacement === 'string' ? replacement.match(/var\(--[^)]+\)/) : null;
-  return match ? `${match[0]} holds ${formattedNearest}.` : '';
+  if (!match) {
+    return '';
+  }
+  const holdsNegative = negativeLiteral && replacement === match[0];
+  return `${match[0]} holds ${holdsNegative ? `-${formattedNearest}` : formattedNearest}.`;
 }
 
 module.exports = {
   negateReplacement,
   replacementFor,
+  signedTokensForLength,
   tokenFitsProperty,
   tokenHoldsNote,
   tokenForLength,