stylelint-plugin-rhythmguard 3.10.0 → 3.10.2

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.10.2] - 2026-10-15
+
+### Messages
+
+- A value below the smallest step or above the largest named that step twice: `Use scale values (nearest: 14px or 14px).` It is now named once: `(nearest: 14px)`, and for a Tailwind class `Use "p-8" (32px).` Applies to `use-scale`, `no-offscale-transform`, `use-motion-scale` and both ESLint rules. Messages for values between two steps are unchanged.
+
+### Changed
+
+- New README banner without a version number, so it no longer needs replacing each release. GitHub shows the transparent SVG; npmjs.com gets a non-transparent PNG rendered from it on the same background as before.
+
+## [3.10.1] - 2026-10-15
+
+### Fixed
+
+- Token ladders: a ladder whose every step is a `var()` alias of a step on one other ladder, such as Tailwind `@theme` names over a token file, is folded into that ladder instead of being reported again with the same problems. The ladder it aliases lists it under `aliases`, and the Markdown report names it next to that ladder.
+
 ## [3.10.0] - 2026-10-15
 
 ### Added

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.png?v=13" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.png?v=14" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
 </p>
 
 # stylelint-plugin-rhythmguard
@@ -7,7 +7,7 @@
 Nobody chose 13px. Rhythmguard catches off-scale spacing in CSS and Tailwind class strings, tells you the nearest steps on your scale, and snaps to them or to your tokens when you ask.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/petrilahdelma/stylelint-plugin-rhythmguard/ci.yml?branch=main&label=ci)](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3100)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3102)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![npm downloads](https://img.shields.io/npm/dm/stylelint-plugin-rhythmguard.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.10.0",
+  "version": "3.10.2",
   "description": "Nobody chose 13px. Catches off-scale spacing in CSS and Tailwind class strings and snaps it to your scale or tokens. Stylelint rules, an ESLint companion, and an audit CLI.",
   "bin": {
     "rhythmguard": "src/cli/index.js"

package/src/audit/render-markdown.js

@@ -141,7 +141,8 @@ function appendTokenLaddersMarkdown(lines, ladders) {
       const note = `${LADDER_PROBLEM_TEXT[problem.type]}${where} with \`${problem.tokens[0]}\``;
       flagged.set(problem.tokens[1], [...(flagged.get(problem.tokens[1]) || []), note]);
     }
-    lines.push(`**\`${escapeMarkdown(entry.prefix)}\`**`);
+    const aliasNote = entry.aliases ? ` (also aliased as ${entry.aliases.map((alias) => `\`${escapeMarkdown(alias)}\``).join(', ')})` : '';
+    lines.push(`**\`${escapeMarkdown(entry.prefix)}\`**${aliasNote}`);
     lines.push('');
     lines.push('| Token | Min | Max | Problem |');
     lines.push('| --- | --- | --- | --- |');

package/src/audit/token-ladders.js

@@ -19,7 +19,8 @@ const { formatLength, numbersEqual, parseLengthToken, toPx } = require('../core/
  * 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.
+ * several different definitions) is left out of the comparison. A ladder
+ * that only aliases another one step for step is folded into it.
  */
 const DEFAULT_MIN_STEP_PX = 2;
 const MIN_LADDER_STEPS = 3;
@@ -158,9 +159,37 @@ function resolveTokenLadders({ baseFontSize = 16, declarations, minStepPx = DEFA
     ladder.steps.push({ max: range.max, min: range.min, rank: step.rank, token });
   }
 
+  const eligible = [...ladders.values()].filter((ladder) => ladder.steps.length >= MIN_LADDER_STEPS);
+  const ladderOfToken = new Map();
+  for (const ladder of eligible) {
+    for (const step of ladder.steps) ladderOfToken.set(step.token, ladder);
+  }
+  // A ladder whose every step is a var() alias of a step on one other ladder
+  // (Tailwind @theme names over a token file) has that ladder's problems, not
+  // its own. It is listed under the other ladder's `aliases` and not counted.
+  const aliasTarget = (ladder) => {
+    let target = null;
+    for (const step of ladder.steps) {
+      const values = declarations.get(step.token);
+      const reference = values && values.size === 1 ? [...values][0].trim().match(VAR_REFERENCE) : null;
+      const owner = reference ? ladderOfToken.get(reference[1]) : null;
+      if (!owner || owner === ladder || (target && owner !== target)) return null;
+      target = owner;
+    }
+    return target;
+  };
+  const aliases = new Map();
+  for (const ladder of eligible) {
+    const target = aliasTarget(ladder);
+    if (target && !aliasTarget(target)) {
+      aliases.set(ladder, target);
+      target.aliases = [...(target.aliases || []), ladder.prefix].sort();
+    }
+  }
+
   const entries = [];
-  for (const ladder of ladders.values()) {
-    if (ladder.steps.length < MIN_LADDER_STEPS) continue;
+  for (const ladder of eligible) {
+    if (aliases.has(ladder)) continue;
     const steps = ladder.steps.sort((a, b) => a.rank - b.rank);
     const problems = [];
     for (let index = 0; index < steps.length - 1; index += 1) {
@@ -176,6 +205,7 @@ function resolveTokenLadders({ baseFontSize = 16, declarations, minStepPx = DEFA
       if (atMax) problems.push({ end: 'max', tokens, ...atMax });
     }
     entries.push({
+      ...(ladder.aliases ? { aliases: ladder.aliases } : {}),
       prefix: ladder.prefix,
       problems,
       steps: steps.map(({ max, min, token }) => ({

package/src/core/length.js

@@ -182,6 +182,14 @@ function nearestScaleValues(target, scale) {
   };
 }
 
+/**
+ * "nearest: 12px or 16px" for a value between two steps, "nearest: 14px" for a
+ * value below the smallest step or above the largest, where both are the same.
+ */
+function nearestText(lower, upper) {
+  return lower === upper ? `nearest: ${lower}` : `nearest: ${lower} or ${upper}`;
+}
+
 /**
  * The replacement text for an off-scale length, or null when the value's unit
  * is not one the rule may rewrite. Keeps the sign, and with the `exact` unit
@@ -203,6 +211,7 @@ function fixedLengthValue(parsedLength, nearestPx, { baseFontSize, unitStrategy,
 }
 
 module.exports = {
+  nearestText,
   fixedLengthValue,
   formatLength,
   formatNumber,

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

@@ -4,6 +4,7 @@ const {
   formatLength,
   formatNumber,
   nearestScaleValues,
+  nearestText,
   normalizeScale,
   numbersEqual,
   parseLengthToken,
@@ -264,9 +265,11 @@ function offScaleClassMessage(token, analysis) {
   const upperPx = analysis.nearest ? formatLength(analysis.nearest.upper, 'px') : 'n/a';
   if (analysis.nearestUtilities) {
     const { lower, upper } = analysis.nearestUtilities;
-    return `Unexpected Tailwind arbitrary spacing value "${token}". Use "${lower}" (${lowerPx}) or "${upper}" (${upperPx}).`;
+    return lower === upper
+      ? `Unexpected Tailwind arbitrary spacing value "${token}". Use "${lower}" (${lowerPx}).`
+      : `Unexpected Tailwind arbitrary spacing value "${token}". Use "${lower}" (${lowerPx}) or "${upper}" (${upperPx}).`;
   }
-  return `Unexpected Tailwind arbitrary spacing value "${token}". Use scale values (nearest: ${lowerPx} or ${upperPx}).`;
+  return `Unexpected Tailwind arbitrary spacing value "${token}". Use scale values (${nearestText(lowerPx, upperPx)}).`;
 }
 
 module.exports = {

package/src/eslint/rules/tailwind-class-use-motion-scale.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { MAX_NOTE_LENGTH, normalizeNote, withNote } = require('../../core/options');
+const { nearestText } = require('../../core/length');
 const { formatTime } = require('../../core/time');
 const { createTailwindMotionAnalyzer } = require('../../core/tailwind-motion-analysis');
 
@@ -71,7 +72,7 @@ function buildMessage(analysis, segment, lower, upper) {
     return `Unexpected Tailwind arbitrary motion duration "${segment.token}". Use non-negative duration values.`;
   }
 
-  return `Unexpected Tailwind arbitrary motion duration "${segment.token}". Use duration scale values (nearest: ${lower} or ${upper}).`;
+  return `Unexpected Tailwind arbitrary motion duration "${segment.token}". Use duration scale values (${nearestText(lower, upper)}).`;
 }
 
 module.exports = {

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

@@ -6,6 +6,7 @@ const {
   formatLength,
   isHairlineLength,
   nearestScaleValues,
+  nearestText,
   numbersEqual,
   parseLengthToken,
   toPx,
@@ -37,7 +38,7 @@ const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
   rejected: (value, lower, upper, note = '') =>
-    `Unexpected transform translation value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
+    `Unexpected transform translation value "${value}". Use scale values (${nearestText(lower, upper)}).${note ? ` ${note}` : ''}`,
 });
 
 const ruleFunction = (primary, secondaryOptions) => {

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

@@ -4,6 +4,7 @@ const stylelint = require('stylelint');
 const valueParser = require('postcss-value-parser');
 const {
   nearestScaleValues,
+  nearestText,
   numbersEqual,
 } = require('../../core/length');
 const {
@@ -43,7 +44,7 @@ const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidDuration: (value, note = '') =>
     withNote(`Unexpected negative motion duration "${value}". Use non-negative duration values.`, note),
   rejectedDuration: (value, lower, upper, note = '') =>
-    withNote(`Unexpected motion duration "${value}". Use duration scale values (nearest: ${lower} or ${upper}).`, note),
+    withNote(`Unexpected motion duration "${value}". Use duration scale values (${nearestText(lower, upper)}).`, note),
   rejectedEasing: (value, note = '') =>
     withNote(`Unexpected raw motion easing "${value}". Use motion tokens for easing decisions.`, note),
 });

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

@@ -6,6 +6,7 @@ const {
   formatLength,
   isHairlineLength,
   nearestScaleValues,
+  nearestText,
   numbersEqual,
   parseLengthToken,
   toPx,
@@ -44,7 +45,7 @@ const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
   rejected: (value, lower, upper, note = '', position = null, aside = '', group = null) =>
-    `Unexpected off-scale ${position ? `${position} "${value}"${aside}` : `value "${value}"`}. Use ${group ? `${group} ` : ''}scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
+    `Unexpected off-scale ${position ? `${position} "${value}"${aside}` : `value "${value}"`}. Use ${group ? `${group} ` : ''}scale values (${nearestText(lower, upper)}).${note ? ` ${note}` : ''}`,
 });
 
 /** " (16.8px)" after a bound written in rem or em, so the reader sees what was compared. */