stylelint-plugin-rhythmguard 3.6.0 → 3.7.1

package/CHANGELOG.md

@@ -6,6 +6,30 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.7.1] - 2026-09-17
+
+### Fixed
+
+- Sass maps declared through a merge helper are read: `$spacers: defaults((...), $spacers)` (Bootstrap v6), `map.merge($base, (...))` and `map-merge((...), (...))` contribute the merged map, later keys winning. The reader also follows Sass assignment rules now: a later plain assignment replaces an earlier `!default`, a later `!default` does not. Before, the first assignment always won, so Bootstrap v6's `$spacers: () !default;` hid the map that followed it and `scale: "auto"` fell back. ([#143](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/143))
+
+### Changed
+
+- The quiet benchmark has a `bootstrap-v6` row, the branch its maintainers asked to see (twbs/bootstrap#42907); the manifest accepts a `ref` so a row can pin a branch other than the default.
+- The release verify matrix and the post-publish smoke are back on the self-hosted farm. The repository variable `RELEASE_ON_HOSTED=true` moves a release onto GitHub-hosted runners while the farm is down, without a workflow edit or a re-cut; the release checklist explains when to use it.
+
+## [3.7.0] - 2026-09-17
+
+### Added
+
+- Every rule accepts `note`, a sentence of up to 200 characters appended to each finding after the built-in text: `... (nearest: 12px or 16px). See docs/spacing.md for approved exceptions.` The built-in text is unchanged, so tooling that matches on it keeps working. Stylelint and ESLint rules alike. ([#134](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/134))
+
+### Changed
+
+- `prefer-token` names the token it would write and where it was read from: `Unexpected raw scale value "12px". Use var(--space-3) (src/tokens.css).` The origin is the linted stylesheet, the `tokenMapFile` or the Tailwind config; an inline `tokenMap` entry is named without one, and a negative literal as `calc(-1 * var(--space-3))`. When no mapping holds the value the message says `No known token holds this value; use the nearest token or add one.` It said `Use design tokens for scale decisions.` in every case. ([#133](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/133))
+- `use-scale` and `no-offscale-transform` with `fixWith: "token"` append `var(--space-3) holds 12px.` when exactly one token qualifies, so the message names what the fix writes. ([#133](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/133))
+- `tailwind-class-use-scale` names the utility classes for the two nearest steps, with their px values, and its fix writes the utility class instead of an on-scale arbitrary value: `p-[13px]` reads `Use "p-3" (12px) or "p-4" (16px)` and becomes `p-3`; `md:-m-[13px]!` becomes `md:-m-3!`; `p-[0.8125rem]` becomes `p-3`. The class number is the snapped value divided by the new `spacingUnit` option (4px, Tailwind's `--spacing`); when it is not a quarter step the fix keeps the arbitrary form, and `spacingUnit: false` keeps it always. The audit's Tailwind findings carry the same text and `fixedToken`. ([#132](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/132))
+- The release workflow verifies and publishes on GitHub-hosted runners, and the post-publish smoke runs there too. The first 3.7.0 release waited 24 hours for a self-hosted runner that never registered and was cancelled; a release no longer depends on the farm. Pushes and pull requests still use it.
+
 ## [3.6.0] - 2026-09-09
 
 ### Added

package/CONTRIBUTING.md

@@ -106,7 +106,7 @@ The maintainer aims to respond to issues and PRs within a week. Small PRs merge
 
 ## Releases
 
-Maintainer-run. Bump `package.json` and `CHANGELOG.md`, create a GitHub release, and `release.yml` verifies on the self-hosted matrix and publishes through npm trusted publishing (OIDC) from a GitHub-hosted job. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
+Maintainer-run. Bump `package.json` and `CHANGELOG.md`, create a GitHub release, and `release.yml` verifies on the self-hosted matrix and publishes through npm trusted publishing (OIDC) from a GitHub-hosted job. The checklist covers cutting a release while the farm is down. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
 
 ## Benchmarking performance
 

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=9" 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.svg?v=11" 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=360)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=371)](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/agents/claude-code/SKILL.md

@@ -11,7 +11,7 @@ This project enforces its spacing scale with stylelint-plugin-rhythmguard.
 - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
 - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
 - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
-- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
 - When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
 - If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
 

package/agents/copilot/copilot-instructions.md

@@ -6,7 +6,7 @@ This project enforces its spacing scale with stylelint-plugin-rhythmguard.
 - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
 - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
 - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
-- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
 - When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
 - If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
 

package/agents/cursor/rhythmguard.mdc

@@ -12,7 +12,7 @@ This project enforces its spacing scale with stylelint-plugin-rhythmguard.
 - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
 - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
 - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
-- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
 - When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
 - If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "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"
@@ -153,7 +153,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "@types/node": "^22.20.1",
-    "c8": "^10.1.3",
+    "c8": "^12.0.0",
     "eslint": "^9.39.5",
     "postcss-scss": "^4.0.9",
     "stylelint": "^16.15.0",

package/src/audit/scan/templates.js

@@ -6,7 +6,7 @@
  */
 const fs = require('node:fs');
 const { formatLength } = require('../../core/length');
-const { createTailwindClassAnalyzer } = require('../../core/tailwind-class-analysis');
+const { createTailwindClassAnalyzer, offScaleClassMessage } = require('../../core/tailwind-class-analysis');
 const { createTailwindMotionAnalyzer } = require('../../core/tailwind-motion-analysis');
 const { formatTime } = require('../../core/time');
 const {
@@ -43,9 +43,7 @@ function collectTailwindFindings(templateFiles, options) {
             : null,
           rawValue: analysis.rawValue,
           rule: 'rhythmguard-tailwind/tailwind-class-use-scale',
-          text: analysis.reason === 'negative'
-            ? `Unexpected Tailwind arbitrary spacing value "${segment.token}". Negative values are disabled for this rule.`
-            : `Unexpected Tailwind arbitrary spacing value "${segment.token}". Use scale values.`,
+          text: offScaleClassMessage(segment.token, analysis),
           token: segment.token,
           type: 'tailwind-arbitrary-spacing',
           utility: analysis.utility,

package/src/core/length.js

@@ -205,6 +205,7 @@ function fixedLengthValue(parsedLength, nearestPx, { baseFontSize, unitStrategy,
 module.exports = {
   fixedLengthValue,
   formatLength,
+  formatNumber,
   fromPx,
   isHairlineLength,
   nearestScaleValues,

package/src/core/options.js

@@ -54,6 +54,22 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && value.trim().length > 0;
 }
 
+const MAX_NOTE_LENGTH = 200;
+
+/** A `note` is appended to every finding, so it stays a sentence: non-empty, at most 200 characters. */
+function isNote(value) {
+  return isNonEmptyString(value) && value.trim().length <= MAX_NOTE_LENGTH;
+}
+
+function normalizeNote(value) {
+  return isNote(value) ? value.trim() : '';
+}
+
+/** The message with the configured note after it, or the message alone. */
+function withNote(message, note) {
+  return note ? `${message} ${note}` : message;
+}
+
 function isSupportedUnit(value) {
   if (!isNonEmptyString(value)) {
     return false;
@@ -399,6 +415,9 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isMathFunctionArgumentMap,
     expectsObject: true,
   }),
+  note: Object.freeze({
+    entryValidator: isNote,
+  }),
   preset: Object.freeze({
     entryValidator: isNonEmptyString,
   }),
@@ -483,6 +502,9 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isMathFunctionArgumentMap,
     expectsObject: true,
   }),
+  note: Object.freeze({
+    entryValidator: isNote,
+  }),
   preset: Object.freeze({
     entryValidator: isNonEmptyString,
   }),
@@ -573,6 +595,7 @@ function buildScaleOptions(rawOptions) {
       : DEFAULT_IGNORE_KEYWORDS,
     invalidPreset: scaleSelection.invalidPreset,
     mathFunctionArguments: normalizeMathFunctionArgumentMap(options.mathFunctionArguments),
+    note: normalizeNote(options.note),
     preset: scaleSelection.selectedPreset,
     presetNames: listScalePresetNames(),
     properties: resolvePropertyPatterns(options),
@@ -618,6 +641,7 @@ function buildTokenOptions(rawOptions) {
       : DEFAULT_IGNORE_KEYWORDS,
     invalidPreset: scaleSelection.invalidPreset,
     mathFunctionArguments: normalizeMathFunctionArgumentMap(options.mathFunctionArguments),
+    note: normalizeNote(options.note),
     preset: scaleSelection.selectedPreset,
     presetNames: listScalePresetNames(),
     properties: resolvePropertyPatterns(options),
@@ -701,6 +725,10 @@ function resolvePropertyScale(prop, options) {
 }
 
 module.exports = {
+  MAX_NOTE_LENGTH,
+  isNote,
+  normalizeNote,
+  withNote,
   NO_OFFSCALE_TRANSFORM_POSSIBLE_OPTIONS,
   NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA,
   PREFER_TOKEN_POSSIBLE_OPTIONS,

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

@@ -2,6 +2,7 @@
 
 const {
   formatLength,
+  formatNumber,
   nearestScaleValues,
   normalizeScale,
   numbersEqual,
@@ -11,6 +12,9 @@ const {
 
 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;
 
 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>[^\]]+)\]$/;
 
@@ -24,6 +28,11 @@ function normalizeTailwindClassOptions(option = {}) {
         ? option.baseFontSize
         : 16,
     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,
     units: Array.isArray(option.units)
       ? option.units.map((unit) => String(unit).toLowerCase())
       : DEFAULT_UNITS,
@@ -121,6 +130,26 @@ function hasInvalidVariantPrefix(prefix) {
   return false;
 }
 
+/**
+ * The utility class Tailwind generates for a px value, or null when the value
+ * is not a quarter step of the spacing unit (v4 generates any quarter step;
+ * v3 generates the quarter steps of its default scale). `p-3` for 12px on a
+ * 4px unit; `-m-3` when the class or the value is negative.
+ */
+function utilityClassFor(utility, px, negative, spacingUnit) {
+  if (!spacingUnit) {
+    return null;
+  }
+  const steps = Math.abs(px) / spacingUnit;
+  const quarters = steps * 4;
+  if (Math.abs(quarters - Math.round(quarters)) > 1e-9) {
+    return null;
+  }
+  const name = utility.startsWith('-') ? utility.slice(1) : utility;
+  const sign = negative && steps !== 0 ? '-' : '';
+  return `${sign}${name}-${formatNumber(Math.round(quarters) / 4)}`;
+}
+
 function analyzeClassToken(token, options, scalePx) {
   const parsedToken = parseClassToken(token);
   if (parsedToken.prefix && hasInvalidVariantPrefix(parsedToken.prefix)) {
@@ -175,13 +204,22 @@ 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);
+
   const replacementValue = formatLength(replacementNumber, parsedLength.unit);
-  const fixedCandidate = parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
-  const fixedToken = `${parsedToken.prefix}${parsedToken.leadingImportant}${fixedCandidate}${parsedToken.trailingImportant}`;
+  const fixedCandidate = utilityFix || parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
 
   return {
-    fixedToken,
+    fixedToken: wrap(fixedCandidate),
     nearest,
+    // The utility classes for the two nearest steps, when both are quarter
+    // steps of the spacing unit; messages name these instead of px values.
+    nearestUtilities: lowerUtility && upperUtility ? { lower: lowerUtility, upper: upperUtility } : null,
     parsedLength,
     reason: 'off-scale',
     rawValue: match.groups.rawValue,
@@ -214,8 +252,26 @@ function createTailwindClassAnalyzer(option = {}) {
   };
 }
 
+/**
+ * The message text for an off-scale class: the two nearest utility classes
+ * with their px values when the unit makes them, the px steps otherwise.
+ */
+function offScaleClassMessage(token, analysis) {
+  if (analysis.reason === 'negative') {
+    return `Unexpected Tailwind arbitrary spacing value "${token}". Negative values are disabled for this rule.`;
+  }
+  const lowerPx = analysis.nearest ? formatLength(analysis.nearest.lower, 'px') : 'n/a';
+  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 `Unexpected Tailwind arbitrary spacing value "${token}". Use scale values (nearest: ${lowerPx} or ${upperPx}).`;
+}
+
 module.exports = {
   createTailwindClassAnalyzer,
   findClassSegments,
   normalizeTailwindClassOptions,
+  offScaleClassMessage,
 };

package/src/core/token-index.js

@@ -64,9 +64,19 @@ function replacementFor(parsedLength, nearestPx, options) {
   return fixedLengthValue(parsedLength, nearestPx, 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.
+ */
+function tokenHoldsNote(replacement, formattedNearest) {
+  const match = typeof replacement === 'string' ? replacement.match(/var\(--[^)]+\)/) : null;
+  return match ? `${match[0]} holds ${formattedNearest}.` : '';
+}
+
 module.exports = {
   negateReplacement,
   replacementFor,
+  tokenHoldsNote,
   tokenForLength,
   tokenIndexFromDefinitions,
 };

package/src/core/token-map.js

@@ -40,7 +40,19 @@ function normalizeTokenReference(tokenReference) {
   return `var(--${trimmed})`;
 }
 
-function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize) {
+/**
+ * Where a token came from, for messages: the path relative to the working
+ * directory when it is inside it, the absolute path otherwise.
+ */
+function displayOrigin(file) {
+  if (!file) {
+    return null;
+  }
+  const relative = path.relative(process.cwd(), file);
+  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
+}
+
+function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize, origins = null, origin = null) {
   if (typeof rawLength !== 'string') {
     return;
   }
@@ -55,6 +67,10 @@ function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize) {
     return;
   }
 
+  if (origins && origin && !origins[token]) {
+    origins[token] = origin;
+  }
+
   const absolute = Math.abs(parsed.number);
   const normalizedRaw = formatLength(absolute, parsed.unit || 'px');
   map[normalizedRaw] = token;
@@ -81,7 +97,7 @@ function mergeExplicitTokenMap(target, source) {
   return target;
 }
 
-function walkTokenGroup(map, group, prefix, baseFontSize) {
+function walkTokenGroup(map, group, prefix, baseFontSize, origins, origin) {
   for (const [key, value] of Object.entries(group)) {
     const tokenName = `${prefix}-${key}`;
 
@@ -91,24 +107,25 @@ function walkTokenGroup(map, group, prefix, baseFontSize) {
 
     // Leaf node with $value (DTCG)
     if (typeof value.$value === 'string') {
-      addLengthValueMapping(map, value.$value, tokenName, baseFontSize);
+      addLengthValueMapping(map, value.$value, tokenName, baseFontSize, origins, origin);
       continue;
     }
 
     // Leaf node with value (Style Dictionary)
     if (typeof value.value === 'string') {
-      addLengthValueMapping(map, value.value, tokenName, baseFontSize);
+      addLengthValueMapping(map, value.value, tokenName, baseFontSize, origins, origin);
       continue;
     }
 
-    // Nested group — recurse deeper
-    walkTokenGroup(map, value, tokenName, baseFontSize);
+    // Nested group: recurse deeper
+    walkTokenGroup(map, value, tokenName, baseFontSize, origins, origin);
   }
 }
 
 function mergeTokenMapFromFile({
   baseFontSize,
   currentMap,
+  origins = null,
   tokenMapFile,
 }) {
   if (!tokenMapFile) {
@@ -134,6 +151,7 @@ function mergeTokenMapFromFile({
   const nextMap = {
     ...currentMap,
   };
+  const origin = displayOrigin(resolvedPath);
 
   for (const [entryKey, entryValue] of Object.entries(parsed)) {
     if (typeof entryValue === 'string') {
@@ -142,36 +160,39 @@ function mergeTokenMapFromFile({
 
       if (keyAsLength) {
         nextMap[entryKey] = entryValue;
+        if (origins && !origins[entryValue]) {
+          origins[entryValue] = origin;
+        }
         continue;
       }
 
       if (valueAsLength) {
-        addLengthValueMapping(nextMap, entryValue, entryKey, baseFontSize);
+        addLengthValueMapping(nextMap, entryValue, entryKey, baseFontSize, origins, origin);
       }
 
       continue;
     }
 
     if (typeof entryValue === 'number') {
-      addLengthValueMapping(nextMap, `${entryValue}px`, entryKey, baseFontSize);
+      addLengthValueMapping(nextMap, `${entryValue}px`, entryKey, baseFontSize, origins, origin);
       continue;
     }
 
     if (isPlainObject(entryValue)) {
       // Style Dictionary format: { value: "16px" }
       if (typeof entryValue.value === 'string') {
-        addLengthValueMapping(nextMap, entryValue.value, entryKey, baseFontSize);
+        addLengthValueMapping(nextMap, entryValue.value, entryKey, baseFontSize, origins, origin);
         continue;
       }
 
       // W3C DTCG format: { $value: "16px", $type: "dimension" }
       if (typeof entryValue.$value === 'string') {
-        addLengthValueMapping(nextMap, entryValue.$value, entryKey, baseFontSize);
+        addLengthValueMapping(nextMap, entryValue.$value, entryKey, baseFontSize, origins, origin);
         continue;
       }
 
-      // Nested group — recurse (e.g. { spacing: { 4: { $value: "16px" } } })
-      walkTokenGroup(nextMap, entryValue, entryKey, baseFontSize);
+      // Nested group: recurse (e.g. { spacing: { 4: { $value: "16px" } } })
+      walkTokenGroup(nextMap, entryValue, entryKey, baseFontSize, origins, origin);
     }
   }
 
@@ -181,12 +202,14 @@ function mergeTokenMapFromFile({
 function mergeTokenMapFromCssCustomProperties({
   baseFontSize,
   currentMap,
+  origins = null,
   root,
   tokenRegex,
 }) {
   const nextMap = {
     ...currentMap,
   };
+  const origin = displayOrigin(root && root.source && root.source.input ? root.source.input.file : null);
 
   root.walkDecls((decl) => {
     const prop = decl.prop.toLowerCase();
@@ -203,7 +226,7 @@ function mergeTokenMapFromCssCustomProperties({
       return;
     }
 
-    addLengthValueMapping(nextMap, decl.value, `var(${decl.prop})`, baseFontSize);
+    addLengthValueMapping(nextMap, decl.value, `var(${decl.prop})`, baseFontSize, origins, origin);
   });
 
   return nextMap;
@@ -321,6 +344,7 @@ function loadTailwindSpacing(resolvedPath) {
 
 function mergeTokenMapFromTailwindSpacing({
   currentMap,
+  origins = null,
   tailwindConfigPath,
 }) {
   if (!tailwindConfigPath) {
@@ -354,13 +378,23 @@ function mergeTokenMapFromTailwindSpacing({
     const absolute = Math.abs(parsed.number);
     const normalizedRaw = formatLength(absolute, parsed.unit || 'px');
     nextMap[normalizedRaw] = `theme(spacing.${key})`;
+    if (origins && !origins[nextMap[normalizedRaw]]) {
+      origins[nextMap[normalizedRaw]] = displayOrigin(resolvedPath);
+    }
   }
 
   return nextMap;
 }
 
+/**
+ * The raw-length to token-reference map a rule fixes with. Pass `origins` to
+ * also learn where each token reference came from (the token map file, the
+ * stylesheet, the Tailwind config), keyed by the reference; an explicit
+ * `tokenMap` entry has no origin.
+ */
 function buildEffectiveTokenMap({
   options,
+  origins = null,
   root,
   tokenRegex,
 }) {
@@ -370,6 +404,7 @@ function buildEffectiveTokenMap({
     tokenMap = mergeTokenMapFromFile({
       baseFontSize: options.baseFontSize,
       currentMap: tokenMap,
+      origins,
       tokenMapFile: options.tokenMapFile,
     });
   }
@@ -378,6 +413,7 @@ function buildEffectiveTokenMap({
     tokenMap = mergeTokenMapFromCssCustomProperties({
       baseFontSize: options.baseFontSize,
       currentMap: tokenMap,
+      origins,
       root,
       tokenRegex,
     });
@@ -386,6 +422,7 @@ function buildEffectiveTokenMap({
   if (options.tokenMapFromTailwindSpacing && options.tailwindConfigPath) {
     tokenMap = mergeTokenMapFromTailwindSpacing({
       currentMap: tokenMap,
+      origins,
       tailwindConfigPath: options.tailwindConfigPath,
     });
   }

package/src/core/token-sources.js

@@ -456,15 +456,67 @@ function parseScssDeclarations(source) {
     }
 
     startPattern.lastIndex = index;
+    const isDefault = /!default\b/.test(value);
     const cleaned = value.replace(/!(default|global)\b/g, '').trim();
-    if (cleaned && !declarations.has(name)) {
+    // Sass semantics at the top level: `!default` assigns only when the variable is
+    // still unset, a plain assignment always wins. Bootstrap v6 declares
+    // `$spacers: () !default;` and then `$spacers: defaults((...), $spacers);`.
+    if (cleaned && (!declarations.has(name) || !isDefault)) {
       declarations.set(name, cleaned);
     }
   }
 
+  for (const [name, raw] of declarations) {
+    const unwrapped = unwrapScssMapCall(raw, declarations);
+    if (unwrapped) {
+      declarations.set(name, unwrapped);
+    }
+  }
+
   return declarations;
 }
 
+/**
+ * A map declared through a merge helper, read as the map it produces:
+ * `defaults((...), $spacers)` (Bootstrap v6), `map.merge($a, (...))`,
+ * `map-merge((...), (...))`. Map-literal arguments and variables that hold a
+ * map are merged left to right with later keys winning, as Sass does; anything
+ * else (an unset `!default` placeholder, an expression) contributes nothing.
+ */
+const SCSS_MAP_MERGE_CALL = /^(?:defaults|map\.merge|map-merge)\s*\(([\s\S]*)\)$/;
+
+function unwrapScssMapCall(raw, declarations) {
+  const match = raw.match(SCSS_MAP_MERGE_CALL);
+  if (!match) {
+    return null;
+  }
+  const entries = new Map();
+  for (const argument of splitTopLevel(match[1], ',')) {
+    const text = argument.trim();
+    let mapLiteral = null;
+    if (isScssMap(text)) {
+      mapLiteral = text;
+    } else if (/^\$[\w-]+$/.test(text)) {
+      const referenced = declarations.get(text.slice(1));
+      if (referenced && isScssMap(referenced)) {
+        mapLiteral = referenced;
+      }
+    }
+    if (!mapLiteral) {
+      continue;
+    }
+    for (const entry of splitTopLevel(mapLiteral.slice(1, -1), ',')) {
+      const pair = splitTopLevel(entry, ':');
+      if (pair.length < 2) continue;
+      entries.set(pair[0].trim(), pair.slice(1).join(':').trim());
+    }
+  }
+  if (entries.size === 0) {
+    return null;
+  }
+  return `(${[...entries].map(([key, expression]) => `${key}: ${expression}`).join(', ')})`;
+}
+
 function isScssMap(raw) {
   return raw.startsWith('(') && raw.endsWith(')') && /:/.test(raw);
 }

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

@@ -1,5 +1,6 @@
 'use strict';
 
+const { MAX_NOTE_LENGTH, normalizeNote, withNote } = require('../../core/options');
 const { formatTime } = require('../../core/time');
 const { createTailwindMotionAnalyzer } = require('../../core/tailwind-motion-analysis');
 
@@ -51,7 +52,7 @@ function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
       ? formatTime(analysis.nearest.upper, 'ms')
       : 'n/a';
     context.report({
-      message: buildMessage(analysis, segment, lower, upper),
+      message: withNote(buildMessage(analysis, segment, lower, upper), analyzer.note),
       node,
       fix:
         fixedText && analysis.reason === 'duration'
@@ -95,13 +96,16 @@ module.exports = {
             },
             type: 'array',
           },
+          note: { maxLength: MAX_NOTE_LENGTH, minLength: 1, type: 'string' },
         },
         type: 'object',
       },
     ],
   },
   create(context) {
-    const analyzer = createTailwindMotionAnalyzer(context.options && context.options[0]);
+    const option = (context.options && context.options[0]) || {};
+    const analyzer = createTailwindMotionAnalyzer(option);
+    analyzer.note = normalizeNote(option.note);
     const sourceCode = context.sourceCode || context.getSourceCode();
 
     return {

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

@@ -1,7 +1,7 @@
 'use strict';
 
-const { formatLength } = require('../../core/length');
-const { createTailwindClassAnalyzer } = require('../../core/tailwind-class-analysis');
+const { MAX_NOTE_LENGTH, normalizeNote, withNote } = require('../../core/options');
+const { createTailwindClassAnalyzer, offScaleClassMessage } = require('../../core/tailwind-class-analysis');
 
 const RULE_NAME = 'tailwind-class-use-scale';
 
@@ -44,17 +44,8 @@ function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
     : null;
 
   for (const { analysis, segment } of findings) {
-    const lower = analysis.nearest
-      ? formatLength(analysis.nearest.lower, 'px')
-      : 'n/a';
-    const upper = analysis.nearest
-      ? formatLength(analysis.nearest.upper, 'px')
-      : 'n/a';
     context.report({
-      message:
-        analysis.reason === 'negative'
-          ? `Unexpected Tailwind arbitrary spacing value "${segment.token}". Negative values are disabled for this rule.`
-          : `Unexpected Tailwind arbitrary spacing value "${segment.token}". Use scale values (nearest: ${lower} or ${upper}).`,
+      message: withNote(offScaleClassMessage(segment.token, analysis), analyzer.note),
       node,
       fix:
         fixedText && analysis.reason !== 'negative'
@@ -77,6 +68,7 @@ module.exports = {
         properties: {
           allowNegative: { type: 'boolean' },
           baseFontSize: { type: 'number' },
+          note: { maxLength: MAX_NOTE_LENGTH, minLength: 1, type: 'string' },
           scale: {
             items: {
               anyOf: [
@@ -86,6 +78,12 @@ module.exports = {
             },
             type: 'array',
           },
+          spacingUnit: {
+            anyOf: [
+              { exclusiveMinimum: true, minimum: 0, type: 'number' },
+              { enum: [false] },
+            ],
+          },
           units: {
             items: { type: 'string' },
             type: 'array',
@@ -96,7 +94,9 @@ module.exports = {
     ],
   },
   create(context) {
-    const analyzer = createTailwindClassAnalyzer(context.options && context.options[0]);
+    const option = (context.options && context.options[0]) || {};
+    const analyzer = createTailwindClassAnalyzer(option);
+    analyzer.note = normalizeNote(option.note);
     const sourceCode = context.sourceCode || context.getSourceCode();
 
     return {

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

@@ -30,14 +30,14 @@ const { validatePrimary, validateNoOffscaleTransformSecondaryOptions } = require
 
 const { reportInvalidPreset, reportProblem, reportValueNode } = require('../report');
 const { decisionFor, loadRcDecisions } = require('../../core/decisions');
-const { replacementFor, tokenIndexFromDefinitions } = require('../../core/token-index');
+const { replacementFor, tokenHoldsNote, tokenIndexFromDefinitions } = require('../../core/token-index');
 
 const ruleName = 'rhythmguard/no-offscale-transform';
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, lower, upper) =>
-    `Unexpected transform translation value "${value}". Use scale values (nearest: ${lower} or ${upper}).`,
+  rejected: (value, lower, upper, note = '') =>
+    `Unexpected transform translation value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
 });
 
 const ruleFunction = (primary, secondaryOptions) => {
@@ -93,6 +93,7 @@ const ruleFunction = (primary, secondaryOptions) => {
             node.value,
             formatLength(nearest.lower, nearestUnit),
             formatLength(nearest.upper, nearestUnit),
+            [tokenHoldsNote(fixedValue, formatLength(nearest.nearest, nearestUnit)), options.note].filter(Boolean).join(' '),
           ),
           node,
           replacement: fixedValue,

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

@@ -38,22 +38,27 @@ const ruleName = 'rhythmguard/prefer-token';
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value) =>
-    `Unexpected raw scale value "${value}". Use design tokens for scale decisions.`,
+  rejected: (value, replacement = null, origin = null, note = '') =>
+    `Unexpected raw scale value "${value}". ${replacement
+      ? `Use ${replacement}${origin ? ` (${origin})` : ''}.`
+      : 'No known token holds this value; use the nearest token or add one.'}${note ? ` ${note}` : ''}`,
 });
 
 function applyNegativeToken(replacement, parsedLength) {
   return !replacement || parsedLength.number >= 0 ? replacement : negateReplacement(replacement);
 }
 
+/** The token for a raw length, and the text the fix writes (negated when the literal is). */
 function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {
+  const found = (token) => ({ replacement: applyNegativeToken(token, parsedLength), token });
+
   if (Object.prototype.hasOwnProperty.call(tokenMap, raw)) {
-    return applyNegativeToken(tokenMap[raw], parsedLength);
+    return found(tokenMap[raw]);
   }
 
   const absoluteRaw = formatLength(Math.abs(parsedLength.number), parsedLength.unit || 'px');
   if (Object.prototype.hasOwnProperty.call(tokenMap, absoluteRaw)) {
-    return applyNegativeToken(tokenMap[absoluteRaw], parsedLength);
+    return found(tokenMap[absoluteRaw]);
   }
 
   if (options.unitStrategy === 'convert') {
@@ -61,7 +66,7 @@ function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {
     if (absPx !== null) {
       const pxKey = `${absPx}px`;
       if (Object.prototype.hasOwnProperty.call(tokenMap, pxKey)) {
-        return applyNegativeToken(tokenMap[pxKey], parsedLength);
+        return found(tokenMap[pxKey]);
       }
     }
   }
@@ -92,8 +97,10 @@ const ruleFunction = (primary, secondaryOptions) => {
     withResolvedScale(options, root);
 
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
+    const origins = {};
     const tokenMap = buildEffectiveTokenMap({
       options,
+      origins,
       root,
       tokenRegex,
     });
@@ -114,8 +121,10 @@ const ruleFunction = (primary, secondaryOptions) => {
       const { scaleByUnit, scalePx } = getScaleStateForProperty(prop);
       let changed = false;
 
-      const reportNode = (node, replacement = null) => {
-        reportValueNode({ decl, message: messages.rejected(node.value), node, replacement, result, ruleName });
+      const reportNode = (node, resolved = null) => {
+        const replacement = resolved ? resolved.replacement : null;
+        const origin = resolved ? origins[resolved.token] || null : null;
+        reportValueNode({ decl, message: messages.rejected(node.value, replacement, origin, options.note), node, replacement, result, ruleName });
       };
 
       const checkWordNode = (node, context) => {
@@ -181,9 +190,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
         }
 
-        const replacement = resolveTokenReplacement(tokenMap, node.value, parsedLength, options);
-
-        reportNode(node, replacement);
+        reportNode(node, resolveTokenReplacement(tokenMap, node.value, parsedLength, options));
         return true;
       };
 

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

@@ -20,6 +20,7 @@ const {
 
 const { reportValueNode } = require('../report');
 const { validatePrimary } = require('../validate');
+const { isNote, normalizeNote, withNote } = require('../../core/options');
 
 const ruleName = 'rhythmguard/use-motion-scale';
 const DURATION_PROPERTIES = new Set([
@@ -39,12 +40,12 @@ const EASING_PROPERTIES = new Set([
 const EASING_FUNCTIONS = new Set(['cubic-bezier', 'linear', 'steps']);
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
-  invalidDuration: (value) =>
-    `Unexpected negative motion duration "${value}". Use non-negative duration values.`,
-  rejectedDuration: (value, lower, upper) =>
-    `Unexpected motion duration "${value}". Use duration scale values (nearest: ${lower} or ${upper}).`,
-  rejectedEasing: (value) =>
-    `Unexpected raw motion easing "${value}". Use motion tokens for easing decisions.`,
+  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),
+  rejectedEasing: (value, note = '') =>
+    withNote(`Unexpected raw motion easing "${value}". Use motion tokens for easing decisions.`, note),
 });
 
 function isPlainObject(value) {
@@ -59,6 +60,7 @@ function buildOptions(rawOptions) {
     durationUnits: normalizeDurationUnits(options.durationUnits),
     easingTokenMap: isPlainObject(options.easingTokenMap) ? options.easingTokenMap : {},
     fixToScale: options.fixToScale !== false,
+    note: normalizeNote(options.note),
   };
 }
 
@@ -78,6 +80,7 @@ function validateSecondaryOptions(result, secondaryOptions) {
           typeof entry === 'string' && entry.trim().length > 0,
         )],
       fixToScale: [true, false],
+      note: [isNote],
     },
   });
 }
@@ -124,8 +127,9 @@ const ruleFunction = (primary, secondaryOptions) => {
               node.value,
               formatTime(nearest.lower, 'ms'),
               formatTime(nearest.upper, 'ms'),
+              options.note,
             )
-            : messages.invalidDuration(node.value),
+            : messages.invalidDuration(node.value, options.note),
           node,
           replacement: fixedValue,
           result,
@@ -146,7 +150,7 @@ const ruleFunction = (primary, secondaryOptions) => {
             }
             : null,
           length: source.length,
-          message: messages.rejectedEasing(source),
+          message: messages.rejectedEasing(source, options.note),
           node,
           result,
           ruleName,

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

@@ -32,7 +32,7 @@ const {
 
 const { createTokenRegex, reportInvalidPreset, reportProblem, reportValueNode } = require('../report');
 const { decisionFor, loadRcDecisions } = require('../../core/decisions');
-const { replacementFor, tokenIndexFromDefinitions } = require('../../core/token-index');
+const { replacementFor, tokenHoldsNote, tokenIndexFromDefinitions } = require('../../core/token-index');
 const { validatePrimary, validateUseScaleSecondaryOptions } = require('../validate');
 
 const ruleName = 'rhythmguard/use-scale';
@@ -198,9 +198,10 @@ const ruleFunction = (primary, secondaryOptions) => {
     const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px') => {
       const lower = nearest ? formatLength(nearest.lower, nearestUnit) : 'n/a';
       const upper = nearest ? formatLength(nearest.upper, nearestUnit) : 'n/a';
+      const tokenNote = nearest ? tokenHoldsNote(fixedValue, formatLength(nearest.nearest, nearestUnit)) : '';
       reportValueNode({
         decl,
-        message: messages.rejected(value, lower, upper, fallbackNote),
+        message: messages.rejected(value, lower, upper, [fallbackNote, tokenNote, options.note].filter(Boolean).join(' ')),
         node,
         replacement: fixedValue,
         result,

package/types/shared.d.ts

@@ -21,6 +21,8 @@ export interface RhythmguardRuleOptions {
   fixWith?: "value" | "token";
   /** Read the `decisions` section of `.rhythmguardrc.json` (default true). The audit sets false and applies decisions itself. */
   decisions?: boolean;
+  /** A sentence of up to 200 characters appended to every finding, after the built-in text. */
+  note?: string;
   baseFontSize?: number;
   customScale?: ScaleValue[];
   includeMathFunctions?: boolean;