stylelint-plugin-rhythmguard 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-09-06
+
+### Fixed
+
+- Whole numbers ending in zero were printed without their zeros: a scale containing `30px` and `60px` produced messages such as `nearest: 3px or 6px`, autofix wrote `3px` for a value snapped to `30px`, and scale inference added phantom small steps (`3px`, `6px`) to every scale that contained `30px` or `60px`. This affected all three Stylelint rules, the ESLint rule's suggested classes, the audit and `scale: "auto"`. Found while reading why GOV.UK's scale came out as `1, 2, 3, 4, 5, 6, 10, 15, ...`. If you use a scale with round-ten values, rerun `--fix` on files that were fixed with an earlier version.
+- `scale: "auto"` accepts tokens named `spacer`, so PatternFly's `--pf-t--global--spacer--*` ladder is read instead of falling back. ([#85](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/85))
+- Token-package discovery reads `@carbon/layout`, where Carbon defines `$spacing-01` to `$spacing-13`. `.scss` files are accepted as token sources, in `scaleSources` and `--token-source` too. ([#87](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/87))
+- `scale: "auto"` and `--scale auto` reject an inferred scale that does not look like one: fewer than three steps, fractional values, no common step (2, 3, 4, 5 or 8), or, in the audit, tokens that come mostly from component files without a near-perfect ladder. The rule then uses the preset and says why in its first message; the audit reports `contracts.scale.rejected` with the source, values and reasons, and the Markdown and text output show it next to the scale source. Component-local variables such as `--chip-spacing: 3px` can no longer become the project scale. ([#88](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/88))
+- Sass spacing maps with one namespace segment before the anchor, such as GOV.UK's `$govuk-spacing-points` and NHS.UK's `$nhsuk-spacing-points`, are read when they hold at least four distinct lengths. Namespaced scalars such as `$dropdown-spacer` and small maps stay excluded, and unitless Sass numbers (mixin parameter defaults such as `$spacing-responsive: 6`, multipliers such as `$spacing-unit: 8`) are no longer taken as lengths. ([#86](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/86))
+- When several Tailwind v4 `--spacing` bases are found, only the first is expanded. A union of ladders from several theme files produced fractional steps that matched nothing on shadcn/ui. ([#89](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/89))
+
+### Changed
+
+- The quiet benchmark manifest grew from 20 to 57 repositories: design systems (GOV.UK, NHS.UK, PatternFly, Cloudscape, Angular Material, Ionic, Element Plus, HashiCorp, SAP Fundamental Styles and UI5 Web Components, daisyUI, Skeleton, Semi, n8n, Utrecht, Mozilla Protocol, Foundation, CoreUI, Tabler, AdminLTE, Materialize, Pure, Tachyons) and CSS-heavy applications (Mastodon already; now Forem, Discourse, Zulip, Mattermost, Grafana, Metabase, Directus, Excalidraw, Ghost, Cal.com, VS Code base UI, Docusaurus, VitePress and Starlight themes). Every repository has a pinned snapshot and the State of Spacing edition is regenerated over the full set.
+- `npm run bench:outreach` drafts one audit issue per benchmark repository under `docs/outreach/audits/`; a separate paced posting script runs a per-repository preflight and records every outcome in `docs/outreach/embed-log.md`.
+
 ## [3.2.0] - 2026-09-06
 
 ### 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.svg?v=5" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=6" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
 </p>
 
 # stylelint-plugin-rhythmguard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "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"
@@ -116,7 +116,8 @@
     "test:watch": "node --test --watch test/*.test.js",
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "build:agents": "node scripts/build-agents.mjs",
-    "bench:state-of-spacing": "node scripts/bench/state-of-spacing.mjs"
+    "bench:state-of-spacing": "node scripts/bench/state-of-spacing.mjs",
+    "bench:outreach": "node scripts/bench/outreach.mjs"
   },
   "repository": {
     "type": "git",

package/src/audit/contract.js

@@ -394,6 +394,7 @@ function toAuditContractReport(report) {
         files: report.scale ? report.scale.files : [],
         offScaleProperties: report.offScaleProperties || {},
         offScaleValues: report.offScaleValues,
+        rejected: report.scale && report.scale.rejected ? report.scale.rejected : null,
         source: report.scale ? report.scale.source : 'default',
         tokenOpportunities: report.tokenOpportunities,
         values: report.scale ? report.scale.values : null,

package/src/audit/render-markdown.js

@@ -4,6 +4,9 @@ const { sortCountMap } = require('./contract');
 const { escapeMarkdown } = require('./render-utils');
 
 function describeScaleSource(scale) {
+  if (scale.rejected) {
+    return `${scale.source} (${scale.rejected.source} rejected: ${scale.rejected.reasons.join(', ')})`;
+  }
   return scale.files.length > 0
     ? `${scale.source} (${scale.files.join(', ')})`
     : scale.source;

package/src/audit/render-text.js

@@ -28,7 +28,8 @@ function renderText(report) {
   if (report.scale) {
     lines.push(`  Scale                    ${report.scale.values.join(', ')}`);
     const files = report.scale.files.length > 0 ? ` (${report.scale.files.join(', ')})` : '';
-    lines.push(`  Scale source             ${report.scale.source}${files}`);
+    const rejected = report.scale.rejected ? ` (${report.scale.rejected.source} rejected: ${report.scale.rejected.reasons.join(', ')})` : '';
+    lines.push(`  Scale source             ${report.scale.source}${files}${rejected}`);
   }
   lines.push('');
 

package/src/audit/report.js

@@ -18,7 +18,8 @@ const {
 } = require('./config');
 const { buildReport, collectTokenDefinitions } = require('./contract');
 const { DEFAULT_SCALE, formatPath } = require('./shared');
-const { discoverTokenPackages, scaleFromDefinitions } = require('../utils/scale-inference');
+const {
+  assessScale, discoverTokenPackages, scaleFromDefinitions } = require('../utils/scale-inference');
 const {
   assertDirectory,
   collectCssFindings,
@@ -129,6 +130,7 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
     }
   }
 
+  let rejected = null;
   const definitions = new Map();
   const matchesKind = createTokenKindMatcher('spacing');
   for (const filePath of cssFiles) {
@@ -155,12 +157,17 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
           files.add(file);
         }
       }
-      return {
-        files: Array.from(files).sort(),
-        source: 'scanned-css',
-        tokenCount: definitions.size,
-        values,
-      };
+      const sortedFiles = Array.from(files).sort();
+      const assessment = assessScale({ files: sortedFiles, source: 'scanned-css', values });
+      if (assessment.plausible) {
+        return {
+          files: sortedFiles,
+          source: 'scanned-css',
+          tokenCount: definitions.size,
+          values,
+        };
+      }
+      rejected = { files: sortedFiles, reasons: assessment.reasons, source: 'scanned-css', values };
     }
   }
 
@@ -178,7 +185,7 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
     }
   }
 
-  return { files: [], source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
+  return { files: [], ...(rejected ? { rejected } : {}), source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
 }
 
 function normalizeCreateAuditOptions(options = {}) {

package/src/cli/quickstart.js

@@ -160,7 +160,10 @@ async function run() {
   out.push('  Scale');
   out.push(`    Scale           ${scale.values.join(', ')}`);
   out.push(`    Source          ${describeScale(scale)}`);
-  if (scale.source === 'fallback') {
+  if (scale.source === 'fallback' && scale.rejected) {
+    out.push(`    Note            Spacing tokens were found but do not form a scale (${scale.rejected.reasons.join(', ')}); the rhythmic-4 preset is being used.`);
+    out.push('                    Point scaleSources at your real token file, or tighten tokenPattern.');
+  } else if (scale.source === 'fallback') {
     out.push('    Note            No spacing tokens found; the rhythmic-4 preset is being used.');
     out.push('                    Add scaleSources or define --space-*/--spacing-* custom properties to lint against your own scale.');
   }

package/src/utils/length.js

@@ -69,8 +69,10 @@ function formatNumber(value) {
     return '0';
   }
 
+  // String() already prints the shortest form (1.5, not 1.50). The old
+  // trailing-zero strip also turned 30 into 3 and 100 into 1.
   const rounded = Math.round(value * 10000) / 10000;
-  return String(rounded).replace(/\.?0+$/, '');
+  return String(rounded);
 }
 
 function formatLength(number, unit) {

package/src/utils/scale-inference.js

@@ -9,7 +9,7 @@ const { collectScssTokens, createTokenKindMatcher, parseTokenSources } = require
 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)(-|$)';
+const DEFAULT_AUTO_TOKEN_PATTERN = '(^--|-)(?<!letter-)(?<!word-)(space|spacing|spacer)(-|$)';
 // 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 = [
@@ -191,21 +191,38 @@ function scaleFromDefinitions(definitions, baseFontSize = 16) {
   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. */
+/**
+ * Merge Tailwind-style base multiples into a scale when a bare --spacing/--space
+ * base is defined. Only the first base found is expanded: a project that ships
+ * several theme files with different bases (shadcn/ui) has one active base at a
+ * time, and a union of ladders is a scale nobody designed (issue #89).
+ */
 function expandTailwindBase(scale, baseKeys, baseFontSize) {
-  const bases = pxValuesFromKeys(baseKeys, baseFontSize).filter((value) => value > 0);
-  if (bases.length === 0) {
+  const base = firstPositivePx(baseKeys, baseFontSize);
+  if (base === null) {
     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);
-    }
+  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 firstPositivePx(keys, baseFontSize) {
+  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) && px > 0) {
+      return px;
+    }
+  }
+  return null;
+}
+
 function rcTokenSources(cwd) {
   const rcPath = path.join(cwd, RC_FILE);
   if (!fs.existsSync(rcPath)) {
@@ -290,6 +307,7 @@ function resolveAutoScale({
     tokenRegex = new RegExp(DEFAULT_AUTO_TOKEN_PATTERN);
   }
 
+  let rejected = null;
   if (root) {
     const stylesheetMap = buildEffectiveTokenMap({
       options: { baseFontSize, tokenMap: {}, tokenMapFromCssCustomProperties: true },
@@ -298,7 +316,11 @@ function resolveAutoScale({
     });
     const scale = scaleFromTokenMap(stylesheetMap, baseFontSize, sassValuesFromRoot(root));
     if (scale) {
-      return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
+      const assessment = assessScale({ source: 'stylesheet', values: scale });
+      if (assessment.plausible) {
+        return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
+      }
+      rejected = { reasons: assessment.reasons, source: 'stylesheet', values: scale };
     }
   }
 
@@ -324,9 +346,56 @@ function resolveAutoScale({
     return { source: 'token-package', ...fromPackages };
   }
 
+  return fallbackInference(rejected);
+}
+
+const TRUSTED_SCALE_SOURCES = new Set(['scaleSources', 'rhythmguardrc', 'token-sources', 'tailwind', 'token-package', 'explicit', 'default']);
+const TOKEN_FILE_PATTERN = /(token|variable|spacing|space|theme|primitive|global|scale|layout)/i;
+const LADDER_STEPS = [2, 3, 4, 5, 8];
+const MIN_ASSESSED_STEPS = 3;
+// A scale with more steps than this must be a near-perfect ladder; otherwise it
+// is a list of every value a codebase happens to use (Semi Design: 42 steps).
+const MAX_LOOSE_STEPS = 24;
+
+/**
+ * Inference can pick up component-local variables (`--chip-spacing: 3px`) and
+ * assemble a "scale" nobody designed. Explicit sources are trusted. An inferred
+ * scale is plausible when it has at least three positive steps, is mostly whole
+ * pixels, mostly shares a common step (2, 3, 4, 5 or 8), and, past two dozen
+ * steps, is a near-perfect ladder. When the source
+ * files are known, a set that comes mostly from component files must be a
+ * near-perfect ladder to pass. Fallback is never the project's scale.
+ */
+function assessScale({ files = null, source, values = [] } = {}) {
+  if (source === 'fallback') {
+    return { plausible: false, reasons: ['fallback'] };
+  }
+  if (TRUSTED_SCALE_SOURCES.has(source)) {
+    return { plausible: true, reasons: [] };
+  }
+  const positives = values.map(Number).filter((value) => Number.isFinite(value) && value > 0);
+  const integers = positives.filter(Number.isInteger);
+  const integerShare = positives.length ? integers.length / positives.length : 0;
+  const coherence = positives.length
+    ? Math.max(...LADDER_STEPS.map((step) => integers.filter((value) => value % step === 0).length / positives.length))
+    : 0;
+  const reasons = [];
+  if (positives.length < MIN_ASSESSED_STEPS) reasons.push('fewer than three steps');
+  if (integerShare < 0.8) reasons.push('fractional values');
+  if (coherence < 0.7) reasons.push('no common step');
+  if (positives.length > MAX_LOOSE_STEPS && coherence < 0.9) reasons.push('too many steps');
+  if (Array.isArray(files) && files.length > 0) {
+    const tokenFileShare = files.filter((file) => TOKEN_FILE_PATTERN.test(file)).length / files.length;
+    if (tokenFileShare < 0.5 && coherence < 0.9) reasons.push('sources are component files');
+  }
+  return { plausible: reasons.length === 0, reasons };
+}
+
+function fallbackInference(rejected = null) {
   return {
     files: [],
     preset: FALLBACK_PRESET,
+    ...(rejected ? { rejected } : {}),
     scale: getScalePreset(FALLBACK_PRESET),
     source: 'fallback',
     tokenCount: 0,
@@ -338,12 +407,16 @@ function autoScaleFallbackNote(inference) {
   if (!inference || inference.source !== 'fallback') {
     return '';
   }
+  if (inference.rejected) {
+    return `The spacing tokens found do not form a spacing scale (${inference.rejected.reasons.join(', ')}); using preset "${inference.preset}".`;
+  }
 
   return `No spacing tokens were found for scale "auto"; using preset "${inference.preset}".`;
 }
 
 module.exports = {
   DEFAULT_AUTO_TOKEN_PATTERN,
+  assessScale,
   autoScaleFallbackNote,
   discoverTokenPackages,
   resolveAutoScale,

package/src/utils/token-packages.json

@@ -43,6 +43,13 @@
         "dist/css/global-vars.css"
       ],
       "note": "--spectrum-spacing-* in px"
+    },
+    {
+      "name": "@carbon/layout",
+      "files": [
+        "scss/generated/_spacing.scss"
+      ],
+      "note": "$spacing-01..13 in rem, Sass variables; Carbon's styles package forwards them from here"
     }
   ]
 }

package/src/utils/token-sources.js

@@ -38,7 +38,7 @@ const TOKEN_KIND_PATTERNS = Object.freeze({
   // --spacing) but never letter-/word-spacing. Sass names must start with the scale word
   // (an optional `system-` prefix allowed): $spacer, $spacers.3, $spacing-01, $system-spacing.
   // Component variables such as $dropdown-spacer or $card-spacer-y are not scale tokens.
-  spacing: /^(?:\$(?:system-)?(?:space|spacing|spacer)s?(?:-|$|\.)|--(?:[\w-]*-)?(?<!letter-)(?<!word-)(?:space|spacing)(?:-|$))/,
+  spacing: /^(?:\$(?:system-)?(?:space|spacing|spacer)s?(?:-|$|\.)|--(?:[\w-]*-)?(?<!letter-)(?<!word-)(?:space|spacing|spacer)(?:-|$))/,
   typography: /^--(?:font|font-size|line-height|leading|tracking|typography)-/,
 });
 
@@ -193,7 +193,8 @@ function normalizeTokenSource(source) {
 }
 
 function detectSourceFormat(filePath) {
-  if (path.extname(filePath).toLowerCase() === '.css') {
+  // .scss token files are read by the CSS collector too: custom properties plus Sass variables and maps.
+  if (['.css', '.scss'].includes(path.extname(filePath).toLowerCase())) {
     return 'css';
   }
 
@@ -283,16 +284,40 @@ function collectScssTokens(source, matchesKind) {
   };
 
   const tokens = [];
-  const push = (tokenName, value) => {
-    if (!value || !matchesKind(tokenName)) {
+  const push = (tokenName, value, force = false) => {
+    if (!value || (!force && !matchesKind(tokenName))) {
       return;
     }
-    tokens.push({ token: tokenName, value: formatScssValue(value) });
+    const formatted = formatScssValue(value);
+    // A unitless number is a multiplier or a map index, not a length. Zero is fine.
+    if (/^-?\d*\.?\d+$/.test(formatted) && parseFloat(formatted) !== 0) {
+      return;
+    }
+    tokens.push({ token: tokenName, value: formatted });
   };
+  // Namespaced maps such as GOV.UK's $govuk-spacing-points are only accepted
+  // for the spacing kind, and only when they hold a real ladder (issue #86).
+  const spacingKind = matchesKind('$spacing-probe');
 
   for (const [name, raw] of declarations) {
     const tokenName = `$${name}`;
     if (isScssMap(raw)) {
+      if (!matchesKind(tokenName) && spacingKind && NAMESPACED_SPACING_MAP.test(tokenName)) {
+        const entries = [];
+        walkScssMap(raw, [tokenName], (pathName, expression) => {
+          const value = evaluateScssExpression(expression, resolveVariable, new Set());
+          if (value) {
+            entries.push([pathName, value]);
+          }
+        });
+        const distinct = new Set(entries.map(([, value]) => formatScssValue(value)).filter((value) => /^-?\d*\.?\d+(?:px|rem|em)$/.test(value) && parseFloat(value) !== 0));
+        if (distinct.size >= MIN_NAMESPACED_MAP_LENGTHS) {
+          for (const [pathName, value] of entries) {
+            push(pathName, value, true);
+          }
+        }
+        continue;
+      }
       walkScssMap(raw, [tokenName], (pathName, expression) => {
         push(pathName, evaluateScssExpression(expression, resolveVariable, new Set()));
       });
@@ -304,6 +329,10 @@ function collectScssTokens(source, matchesKind) {
   return tokens;
 }
 
+/** `$<namespace>-spacing-points`, `$<ns>-space-scale`: one namespace segment before the anchor. */
+const NAMESPACED_SPACING_MAP = /^\$[a-z0-9]+-(?:space|spacing|spacer)s?(?:-|$)/i;
+const MIN_NAMESPACED_MAP_LENGTHS = 4;
+
 function stripScssComments(source) {
   return source
     .replace(/\/\*[\s\S]*?\*\//g, '')

package/types/audit.d.ts

@@ -98,9 +98,19 @@ export interface AuditBaselineComparison {
 
 export type AuditScaleSource = "default" | "explicit" | "fallback" | "scanned-css" | "token-package" | "token-sources";
 
+export interface AuditScaleRejected {
+  files?: string[];
+  /** Why the inferred set was not accepted as a scale, for example "no common step". */
+  reasons: string[];
+  source: AuditScaleSource;
+  values: Array<number | string>;
+}
+
 export interface AuditScale {
   /** Files the scale was derived from (token sources or scanned stylesheets). Empty for explicit, default and fallback. */
   files: string[];
+  /** Present when `source` is "fallback" because an inferred scale failed the plausibility check. */
+  rejected?: AuditScaleRejected | null;
   source: AuditScaleSource;
   tokenCount: number;
   values: Array<number | string>;
@@ -139,6 +149,7 @@ export interface AuditContractReport {
       files: string[];
       offScaleProperties?: Record<string, number>;
       offScaleValues?: unknown;
+      rejected: AuditScaleRejected | null;
       source: AuditScaleSource;
       tokenOpportunities?: unknown;
       values: Array<number | string> | null;