stylelint-plugin-rhythmguard 3.9.0 → 3.10.1

package/CHANGELOG.md

@@ -6,6 +6,28 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [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
+
+- The audit reports token ladders as `contracts.tokens.ladders`: custom properties that share a prefix and a size suffix (`xxs` to `xxl`, `sm`/`md`/`lg`, `1` to `n`) are evaluated at their smallest and largest value (a static length, `clamp()` bounds, the static arguments of `min()` and `max()`, through `var()`) and neighbours are compared at both ends. Collapsed steps (the same size), steps under `minStepPx` apart (default 2px, `audit.ladders.minStepPx`) and inverted steps are reported, and the Markdown report shows each such ladder as a min and max table. A fluid body ladder whose three smallest steps all start at 14px now says so. The section adds no findings and does not change the exit code. ([#205](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/205))
+- `scales` on `use-scale` and `prefer-token`: a scale per property group (`spacing`, `radius`, `size`, `typography`), so a type ladder such as 14, 16, 18, 20, 24, 32, 40 can sit next to a 4px spacing scale in one rule block. A group takes values, a preset name or `"auto"`, which reads the group's own tokens (`--font-size-*` and `--text-*`, `--radius-*`). `propertyScales` still wins for its property. Findings checked against a group scale say so: `Use typography scale values (nearest: 16px or 18px).`; every other message is unchanged. The audit takes the same map as `audit.scales` and checks each group it names. ([#204](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/204))
+- `checkMathBounds` on `use-scale` and `prefer-token`, and `--check-math-bounds` (or `audit.checkMathBounds`) on the audit: the minimum and maximum of `clamp()` and each length argument of `min()` and `max()` are checked like literals, with the position in the message (`Unexpected off-scale clamp() maximum "1.05rem" (16.8px). ...`). Before, wrapping a value in `clamp()` was a way to leave the scale without a finding. The preferred value of `clamp()` is fluid by design and never checked; neither is an expression, a `var()` or a viewport length. `--fix` and `fixWith: "token"` apply per bound. Off by default in 3.x because it adds findings to existing configs; on by default is a candidate for 4.0. ([#203](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/203))
+
+### Fixed
+
+- `outline-offset` is no longer offered radius tokens. It is checked with the `radius` property group, so 3.9.0's token-kind matching pointed it at `--radius-*`: on one consumer, all 89 `prefer-token` warnings that named a radius token were on `outline-offset` (`outline-offset: -2px` read `Use calc(-1 * var(--radius-sm))`). It is the gap between the border edge and the outline, a spacing length, so it now takes spacing tokens, and under `scales` the spacing scale. Which properties each group checks is unchanged. A contract test asserts that no property but the corner radii resolves to a radius token.
+
+### Messages
+
+- `prefer-token` on `outline-offset`, when a radius token held the value: was `Use var(--radius-*)`, now names the spacing token that holds it, or `No known token holds this value; ...` when none does.
+
 ## [3.9.0] - 2026-10-15
 
 ### Added

package/README.md

@@ -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=390)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3101)](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.9.0",
+  "version": "3.10.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"

package/src/audit/args.js

@@ -54,6 +54,8 @@ const OPTIONS = [
   { flag: '--since', kind: 'value', value: '<git-ref>', help: 'Scan only changed files since a git ref',
     apply: (p, raw) => { p.since = parsePathOption(raw, '--since'); setFrom(p, 'since'); } },
   { flag: '--staged', kind: 'flag', help: 'Scan only staged files', apply: (p) => { p.staged = true; setFrom(p, 'staged'); } },
+  { flag: '--check-math-bounds', kind: 'flag', help: 'Check clamp() minimum and maximum and min()/max() arguments against the scale',
+    apply: (p) => { p.checkMathBounds = true; setFrom(p, 'checkMathBounds'); } },
   { flag: '--include-motion', kind: 'flag', help: 'Include opt-in motion duration/easing drift',
     apply: (p) => { p.includeMotion = true; setFrom(p, 'includeMotion'); } },
   { flag: '--token-source', kind: 'value', value: '<file>', help: 'External token source (repeatable, comma-separated)',

package/src/audit/config.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { normalizeDecisions } = require('../core/decisions');
+const { SCALED_GROUPS, isGroupScalesMap } = require('../core/options');
 const {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
@@ -109,6 +110,11 @@ function applyAuditConfig(parsed, configResult) {
   applyConfigScalar(next, audit, cliOptions, 'tokenKind', 'tokenKind', normalizeTokenKind);
   applyConfigScalar(next, audit, cliOptions, 'baseFontSize', 'baseFontSize', parseBaseFontSize);
   applyConfigScalar(next, audit, cliOptions, 'includeMotion', 'includeMotion', parseBooleanOption);
+  applyConfigScalar(next, audit, cliOptions, 'checkMathBounds', 'checkMathBounds', parseBooleanOption);
+  applyConfigScalar(next, audit, cliOptions, 'scales', 'scales', parseGroupScales);
+  if (audit.ladders !== undefined) {
+    next.ladderMinStepPx = parseLadderOptions(audit.ladders);
+  }
   applyConfigScalar(next, audit, cliOptions, 'scale', 'scale', (value) => {
     if (Array.isArray(value)) {
       return value;
@@ -130,6 +136,23 @@ function applyConfigScalar(target, audit, cliOptions, targetKey, configKey, pars
   target[targetKey] = parser(audit[configKey], configKey);
 }
 
+function parseLadderOptions(value) {
+  const minStepPx = value && typeof value === 'object' && !Array.isArray(value) ? value.minStepPx : undefined;
+  if (typeof minStepPx !== 'number' || !Number.isFinite(minStepPx) || minStepPx < 0) {
+    throw new Error('ladders.minStepPx must be a non-negative number of px.');
+  }
+
+  return minStepPx;
+}
+
+function parseGroupScales(value, optionName) {
+  if (!isGroupScalesMap(value)) {
+    throw new Error(`${optionName} must map ${SCALED_GROUPS.join(', ')} to a scale, a preset name or "auto".`);
+  }
+
+  return value;
+}
+
 function parseBooleanOption(value, optionName) {
   if (typeof value !== 'boolean') {
     throw new Error(`${optionName} must be a boolean.`);

package/src/audit/render-markdown.js

@@ -55,6 +55,7 @@ function renderMarkdown(report) {
   appendMarkdownCounts(lines, 'Motion Rhythm Drift', report.motion.values);
   appendTokenContractMarkdown(lines, report.tokenContract);
   appendTokenChainsMarkdown(lines, report.tokenContract.chains);
+  appendTokenLaddersMarkdown(lines, report.tokenContract.ladders);
   appendBaselineMarkdown(lines, report);
 
   if (report.topAffectedFiles.length > 0) {
@@ -118,6 +119,40 @@ function appendTokenChainsMarkdown(lines, chains) {
   }
 }
 
+const LADDER_PROBLEM_TEXT = Object.freeze({
+  collapsed: 'collapsed',
+  inverted: 'inverted',
+  'too-close': 'too close',
+});
+
+function appendTokenLaddersMarkdown(lines, ladders) {
+  if (!ladders || ladders.entries.length === 0) {
+    return;
+  }
+  const { summary } = ladders;
+  lines.push('## Token Ladders');
+  lines.push('');
+  lines.push(`${ladders.entries.length} of ${summary.ladders} token ladders have steps that do not read as steps: ${summary.collapsed} collapsed, ${summary.tooClose} under ${summary.minStepPx}px apart, ${summary.inverted} inverted. Each step is shown at its smallest and largest value.`);
+  lines.push('');
+  for (const entry of ladders.entries.slice(0, 20)) {
+    const flagged = new Map();
+    for (const problem of entry.problems) {
+      const where = problem.end === 'both' ? '' : ` at ${problem.end}`;
+      const note = `${LADDER_PROBLEM_TEXT[problem.type]}${where} with \`${problem.tokens[0]}\``;
+      flagged.set(problem.tokens[1], [...(flagged.get(problem.tokens[1]) || []), note]);
+    }
+    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('| --- | --- | --- | --- |');
+    for (const step of entry.steps) {
+      lines.push(`| \`${escapeMarkdown(step.token)}\` | ${step.min || 'fluid'} | ${step.max || 'fluid'} | ${(flagged.get(step.token) || []).join('; ')} |`);
+    }
+    lines.push('');
+  }
+}
+
 function appendTokenContractMarkdown(lines, tokenContract) {
   const {
     conflictingTokens,

package/src/audit/render-text.js

@@ -51,6 +51,11 @@ function renderText(report) {
     lines.push(`  Token chains             ${summary['on-scale']} of ${summary.total} resolve to the scale (${summary['off-scale']} off-scale, ${summary.unresolved} unresolved, ${summary.ambiguous} ambiguous)`);
     lines.push('');
   }
+  if (report.tokenContract.ladders && report.tokenContract.ladders.summary.ladders > 0) {
+    const { summary } = report.tokenContract.ladders;
+    lines.push(`  Token ladders            ${summary.ladders} checked (${summary.collapsed} collapsed, ${summary.tooClose} under ${summary.minStepPx}px apart, ${summary.inverted} inverted steps)`);
+    lines.push('');
+  }
   appendBaselineText(lines, report);
 
   if (report.topAffectedFiles.length > 0) {

package/src/audit/report.js

@@ -26,6 +26,7 @@ const {
 } = require('../core/scale-inference');
 const { applyDecisions, buildDecisionPlan } = require('./decisions');
 const { collectDeclarations, resolveTokenChains, toChainsContract } = require('./token-chains');
+const { resolveTokenLadders, toLaddersContract } = require('./token-ladders');
 const { assertDirectory, getScanFiles } = require('./scan/files');
 const { collectCssFindings, runStylelintAudit } = require('./scan/stylesheets');
 const { collectTailwindFindings, collectTailwindMotionFindings } = require('./scan/templates');
@@ -58,8 +59,10 @@ async function createAuditReport(options) {
 
   const lintOptions = {
     baseFontSize: parsed.baseFontSize,
+    checkMathBounds: parsed.checkMathBounds,
     includeMotion: parsed.includeMotion,
     scale: scale.values,
+    scales: parsed.scales,
   };
 
   const cssResults = await runStylelintAudit(cssFiles, lintOptions);
@@ -98,15 +101,21 @@ async function createAuditReport(options) {
     tokenSourceWarnings: tokenSourceResult.warnings,
   });
 
+  const declarations = collectDeclarations({
+    cssFiles,
+    externalDefinitions: tokenSourceResult.definitions,
+    skipFile: (file) => NON_AUTHORED_SEGMENT.test(file),
+  });
   report.tokenContract.chains = toChainsContract(resolveTokenChains({
     baseFontSize: parsed.baseFontSize,
-    declarations: collectDeclarations({
-      cssFiles,
-      externalDefinitions: tokenSourceResult.definitions,
-      skipFile: (file) => NON_AUTHORED_SEGMENT.test(file),
-    }),
+    declarations,
     scale: scale.values,
   }));
+  report.tokenContract.ladders = toLaddersContract(resolveTokenLadders({
+    baseFontSize: parsed.baseFontSize,
+    declarations,
+    minStepPx: parsed.ladderMinStepPx,
+  }));
   report.decisions = decided.summary;
   report.decisionPlan = buildDecisionPlan({
     baseFontSize: parsed.baseFontSize,

package/src/audit/scan/stylesheets.js

@@ -47,7 +47,10 @@ async function runStylelintAudit(cssFiles, options) {
       {
         decisions: false,
         baseFontSize: options.baseFontSize,
+        checkMathBounds: options.checkMathBounds === true,
         scale: options.scale,
+        // audit.scales adds the groups it names, each checked against its own scale.
+        ...(options.scales ? { propertyGroups: ['spacing', ...Object.keys(options.scales)], scales: options.scales } : {}),
         severity: 'warning',
       },
     ],
@@ -55,6 +58,7 @@ async function runStylelintAudit(cssFiles, options) {
       true,
       {
         baseFontSize: options.baseFontSize,
+        checkMathBounds: options.checkMathBounds === true,
         scale: options.scale,
         severity: 'warning',
         tokenMapFromCssCustomProperties: true,
@@ -127,10 +131,10 @@ function collectCssFindings(fileResults) {
       const text = warning.text || '';
       const source = readSourceOnce(sources, fileResult.source);
       const offScaleMatch = text.match(
-        /Unexpected (?:off-scale value|transform translation value) "([^"]+)"/,
+        /Unexpected (?:off-scale (?:value|(?:clamp|min|max)\(\) (?:minimum|maximum|argument))|transform translation value) "([^"]+)"/,
       );
       const tokenMatch = text.match(
-        /Unexpected raw scale value "([^"]+)"/,
+        /Unexpected raw (?:scale value|(?:clamp|min|max)\(\) (?:minimum|maximum|argument)) "([^"]+)"/,
       );
       const motionDurationMatch = text.match(
         /Unexpected (?:motion duration|negative motion duration) "([^"]+)"/,

package/src/audit/shared.js

@@ -75,12 +75,15 @@ function createDefaultAuditOptions() {
     format: 'text',
     ignorePath: DEFAULT_IGNORE_PATH,
     ignorePatterns: [],
+    checkMathBounds: false,
     includeMotion: false,
+    ladderMinStepPx: 2,
     maxFindings: null,
     minCleanliness: null,
     noConfig: false,
     outputPath: null,
     scale: DEFAULT_SCALE,
+    scales: null,
     schema: false,
     since: null,
     sinceBaseline: false,

package/src/audit/token-ladders.js

@@ -0,0 +1,246 @@
+'use strict';
+
+const valueParser = require('postcss-value-parser');
+const { formatLength, numbersEqual, parseLengthToken, toPx } = require('../core/length');
+
+/**
+ * Token ladders (issue #205). A ladder is a set of custom properties that
+ * share a prefix and differ by a size step: `--font-size-text-xxs` to
+ * `-xxl`, `--space-1` to `--space-9`, `--radius-sm/md/lg`. Every step can be
+ * on the scale and the ladder still be broken, so each step is evaluated at
+ * its smallest and largest value (a static length, a clamp() minimum and
+ * maximum, the static arguments of min() and max(), followed through var())
+ * and adjacent steps are compared at both ends:
+ *
+ *   collapsed    two steps render the same size at one end
+ *   too-close    two steps differ by less than `minStepPx` (default 2px)
+ *   inverted     a step is larger than the next one at one end
+ *
+ * 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. 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;
+const VAR_REFERENCE = /^var\(\s*(--[\w-]+)\s*(?:,\s*([\s\S]+))?\)$/i;
+
+// T-shirt steps in order. Aliases share a rank (sm and s, 2xl and xxl).
+const SIZE_RANKS = new Map([
+  ['xxxs', -4], ['3xs', -4], ['xxs', -3], ['2xs', -3], ['xs', -2],
+  ['s', -1], ['sm', -1], ['small', -1],
+  ['m', 0], ['md', 0], ['medium', 0], ['base', 0],
+  ['l', 1], ['lg', 1], ['large', 1],
+  ['xl', 2], ['xxl', 3], ['2xl', 3], ['xxxl', 4], ['3xl', 4],
+  ['4xl', 5], ['5xl', 6], ['6xl', 7], ['7xl', 8], ['8xl', 9], ['9xl', 10],
+]);
+const STEP_SUFFIX = /^(--[\w-]+?)-([a-z0-9]+)$/i;
+
+/** The ladder a token belongs to and its rank on it, or null. */
+function ladderStep(token) {
+  const match = token.match(STEP_SUFFIX);
+  if (!match) {
+    return null;
+  }
+  const [, prefix, suffix] = match;
+  const lower = suffix.toLowerCase();
+  if (SIZE_RANKS.has(lower)) {
+    return { key: `${prefix} (sizes)`, prefix, rank: SIZE_RANKS.get(lower) };
+  }
+  if (/^\d+$/.test(lower)) {
+    return { key: `${prefix} (numbers)`, prefix, rank: Number(lower) };
+  }
+  return null;
+}
+
+function splitArguments(fnNode) {
+  const args = [[]];
+  for (const node of fnNode.nodes) {
+    if (node.type === 'div' && node.value === ',') {
+      args.push([]);
+    } else {
+      args[args.length - 1].push(node);
+    }
+  }
+  return args.map((nodes) => valueParser.stringify(nodes).trim());
+}
+
+function createEvaluator(declarations, baseFontSize) {
+  const memo = new Map();
+
+  const evaluateToken = (token, seen) => {
+    if (memo.has(token)) return memo.get(token);
+    const values = declarations.get(token);
+    if (!values || seen.has(token)) return null;
+    const ranges = [...values].map((value) => evaluate(value, new Set([...seen, token])));
+    const [first] = ranges;
+    const agree = first && ranges.every((range) => range && sameEnd(range.min, first.min) && sameEnd(range.max, first.max));
+    const result = agree ? first : null;
+    memo.set(token, result);
+    return result;
+  };
+
+  // { min, max } in px; an end is null when the value has no static bound there.
+  const evaluate = (raw, seen = new Set()) => {
+    const value = String(raw).trim();
+    const reference = value.match(VAR_REFERENCE);
+    if (reference) {
+      const [, target, fallback] = reference;
+      if (declarations.has(target)) return evaluateToken(target, seen);
+      return fallback === undefined ? null : evaluate(fallback, seen);
+    }
+    const parsed = valueParser(value).nodes.filter((node) => node.type !== 'space');
+    if (parsed.length !== 1) return null;
+    const [node] = parsed;
+    if (node.type === 'word') {
+      const length = parseLengthToken(node.value);
+      if (!length || !length.unit || length.unit === '%') return null;
+      const px = toPx(Math.abs(length.number), length.unit, baseFontSize);
+      if (px === null) return null;
+      const signed = length.number < 0 ? -px : px;
+      return { max: signed, min: signed };
+    }
+    if (node.type !== 'function') return null;
+    const name = node.value.toLowerCase();
+    const args = splitArguments(node).map((arg) => evaluate(arg, seen));
+    if (name === 'clamp') {
+      if (args.length !== 3 || !args[0] || !args[2] || args[0].min === null || args[2].max === null) return null;
+      return { max: args[2].max, min: args[0].min };
+    }
+    if (name === 'min' || name === 'max') {
+      const statics = args.filter((range) => range && range.min !== null && range.max !== null);
+      if (statics.length === 0) return null;
+      const pick = name === 'min' ? Math.min : Math.max;
+      const all = statics.length === args.length;
+      // min(5vw, 2rem) is at most 2rem and has no static minimum; max() mirrors it.
+      return {
+        max: name === 'min' || all ? pick(...statics.map((range) => range.max)) : null,
+        min: name === 'max' || all ? pick(...statics.map((range) => range.min)) : null,
+      };
+    }
+    return null;
+  };
+
+  return { evaluate, evaluateToken };
+}
+
+function sameEnd(a, b) {
+  return (a === null && b === null) || (a !== null && b !== null && numbersEqual(a, b));
+}
+
+function compareEnds(lower, upper, end, minStepPx) {
+  const a = lower[end];
+  const b = upper[end];
+  if (a === null || b === null) return null;
+  if (numbersEqual(a, b)) return { type: 'collapsed' };
+  if (a > b) return { type: 'inverted' };
+  if (b - a < minStepPx) return { difference: Math.round((b - a) * 1000) / 1000, type: 'too-close' };
+  return null;
+}
+
+/**
+ * Every ladder of at least three evaluable steps, with the problems between
+ * adjacent steps. `declarations` is the token-chain map: token to the set of
+ * values it is declared with.
+ */
+function resolveTokenLadders({ baseFontSize = 16, declarations, minStepPx = DEFAULT_MIN_STEP_PX }) {
+  const { evaluateToken } = createEvaluator(declarations, baseFontSize);
+  const ladders = new Map();
+  for (const token of declarations.keys()) {
+    const step = ladderStep(token);
+    if (!step) continue;
+    const range = evaluateToken(token, new Set());
+    if (!range) continue;
+    if (!ladders.has(step.key)) ladders.set(step.key, { prefix: step.prefix, steps: [] });
+    const ladder = ladders.get(step.key);
+    // An alias for a rank already on the ladder (s next to sm) is not a step.
+    if (ladder.steps.some((existing) => existing.rank === step.rank)) continue;
+    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 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) {
+      const tokens = [steps[index].token, steps[index + 1].token];
+      const atMin = compareEnds(steps[index], steps[index + 1], 'min', minStepPx);
+      const atMax = compareEnds(steps[index], steps[index + 1], 'max', minStepPx);
+      // The same problem at both ends (always, for static steps) is one problem.
+      if (atMin && atMax && atMin.type === atMax.type && atMin.difference === atMax.difference) {
+        problems.push({ end: 'both', tokens, ...atMin });
+        continue;
+      }
+      if (atMin) problems.push({ end: 'min', tokens, ...atMin });
+      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 }) => ({
+        max: max === null ? null : formatLength(max, 'px'),
+        min: min === null ? null : formatLength(min, 'px'),
+        token,
+      })),
+    });
+  }
+  entries.sort((a, b) => a.prefix.localeCompare(b.prefix));
+
+  const count = (type) => entries.reduce((sum, entry) => sum + entry.problems.filter((problem) => problem.type === type).length, 0);
+  return {
+    entries,
+    summary: {
+      collapsed: count('collapsed'),
+      inverted: count('inverted'),
+      ladders: entries.length,
+      minStepPx,
+      tooClose: count('too-close'),
+    },
+  };
+}
+
+/** The contract shape: counts for every ladder, entries only for ladders with a problem. */
+function toLaddersContract(ladders) {
+  return {
+    entries: ladders.entries.filter((entry) => entry.problems.length > 0),
+    summary: ladders.summary,
+  };
+}
+
+module.exports = {
+  DEFAULT_MIN_STEP_PX,
+  ladderStep,
+  resolveTokenLadders,
+  toLaddersContract,
+};

package/src/core/css-vocabulary.js

@@ -41,6 +41,30 @@ const PROPERTY_GROUP_PATTERNS = Object.freeze({
   ]),
 });
 
+/** The property group a CSS property belongs to, or null. */
+function propertyGroupOf(prop) {
+  const lower = String(prop || '').toLowerCase();
+  const found = Object.entries(PROPERTY_GROUP_PATTERNS).find(([, patterns]) => patterns.some((pattern) => pattern.test(lower)));
+  return found ? found[0] : null;
+}
+
+// Properties whose length is a different kind from the group that checks them.
+// outline-offset is checked with the radius group (it always has been), but it
+// is the gap between the border edge and the outline: a spacing length. A
+// radius token there would tie every focus ring to the corner radius.
+const PROPERTY_KIND_OVERRIDES = Object.freeze({
+  'outline-offset': 'spacing',
+});
+
+/**
+ * The kind of length a property takes, for choosing tokens and a group's
+ * scale. The property group, except where PROPERTY_KIND_OVERRIDES says otherwise.
+ */
+function propertyKindOf(prop) {
+  const lower = String(prop || '').toLowerCase();
+  return PROPERTY_KIND_OVERRIDES[lower] || propertyGroupOf(lower);
+}
+
 const DEFAULT_PROPERTY_GROUPS = Object.freeze(['spacing']);
 const PROPERTY_GROUP_NAMES = Object.freeze(Object.keys(PROPERTY_GROUP_PATTERNS));
 
@@ -101,6 +125,8 @@ const SUPPORTED_SCALE_UNITS = new Set([
 const DEFAULT_MATH_FUNCTION_ARGUMENT_FILTER = Object.freeze({});
 
 module.exports = {
+  propertyGroupOf,
+  propertyKindOf,
   DEFAULT_IGNORE_KEYWORDS,
   DEFAULT_MATH_FUNCTION_ARGUMENT_FILTER,
   DEFAULT_PROPERTY_GROUPS,

package/src/core/options.js

@@ -11,6 +11,7 @@ const {
   PROPERTY_GROUP_PATTERNS,
   SPACING_PROPERTY_PATTERNS,
   SUPPORTED_SCALE_UNITS,
+  propertyKindOf,
 } = require('./css-vocabulary');
 const { parseLengthToken } = require('./length');
 const {
@@ -257,6 +258,42 @@ function isPropertyScaleMap(value) {
   });
 }
 
+// Groups that take a length scale of their own; motion has use-motion-scale.
+const SCALED_GROUPS = Object.freeze(['spacing', 'radius', 'size', 'typography']);
+
+/** One group's scale: values, a preset name, "auto", or a { preset | scale | customScale } object. */
+function isGroupScaleEntry(value) {
+  if (isAutoScaleLiteral(value)) {
+    return true;
+  }
+  if (typeof value === 'string') {
+    return Boolean(getScalePreset(value));
+  }
+  return isScaleOverrideEntry(value);
+}
+
+function isGroupScalesMap(value) {
+  return isPlainObject(value)
+    && Object.entries(value).every(([group, scale]) => SCALED_GROUPS.includes(group) && isGroupScaleEntry(scale));
+}
+
+/**
+ * `scales` normalised to { group: { auto, scale } }. A group set to "auto"
+ * has no scale until the rule infers one from that group's tokens.
+ */
+function buildGroupScales(scales) {
+  if (!isGroupScalesMap(scales)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(scales).map(([group, entry]) => {
+    if (isAutoScaleLiteral(entry)) {
+      return [group, { auto: true, scale: null }];
+    }
+    const scale = typeof entry === 'string' ? getScalePreset(entry) : resolveScaleOverride(entry);
+    return [group, { auto: false, scale: Array.isArray(scale) ? [...scale] : null }];
+  }));
+}
+
 function buildPossibleOptionMap(schema) {
   return Object.fromEntries(
     Object.entries(schema).map(([optionName, descriptor]) => [
@@ -398,6 +435,9 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isScaleEntry,
     expectsArray: true,
   }),
+  checkMathBounds: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   enforceInsideMathFunctions: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -460,6 +500,10 @@ const USE_SCALE_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isPropertyScaleMap,
     expectsObject: true,
   }),
+  scales: Object.freeze({
+    entryValidator: isGroupScalesMap,
+    expectsObject: true,
+  }),
   tokenFunctions: Object.freeze({
     entryValidator: isNonEmptyString,
     expectsArray: true,
@@ -487,6 +531,9 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isScaleEntry,
     expectsArray: true,
   }),
+  checkMathBounds: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   enforceInsideMathFunctions: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -520,6 +567,10 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isPropertyScaleMap,
     expectsObject: true,
   }),
+  scales: Object.freeze({
+    entryValidator: isGroupScalesMap,
+    expectsObject: true,
+  }),
   scale: Object.freeze({
     allowLiterals: ['auto'],
     entryValidator: isScaleEntryOrAuto,
@@ -586,6 +637,7 @@ function buildScaleOptions(rawOptions) {
       options.baseFontSize > 0
         ? options.baseFontSize
         : 16,
+    checkMathBounds: options.checkMathBounds === true,
     enforceInsideMathFunctions: options.enforceInsideMathFunctions === true,
     fixToScale: options.fixToScale !== false,
     fixWith: options.fixWith === 'token' ? 'token' : 'value',
@@ -601,6 +653,7 @@ function buildScaleOptions(rawOptions) {
     properties: resolvePropertyPatterns(options),
     propertyGroups: normalizePropertyGroups(options.propertyGroups),
     propertyScaleOverrides: buildPropertyScaleOverrides(options.propertyScales),
+    groupScales: buildGroupScales(options.scales),
     scale: scaleSelection.scale,
     scaleAuto: isAutoScaleLiteral(options.scale),
     scaleSources: Array.isArray(options.scaleSources) ? options.scaleSources : [],
@@ -634,6 +687,7 @@ function buildTokenOptions(rawOptions) {
       options.baseFontSize > 0
         ? options.baseFontSize
         : 16,
+    checkMathBounds: options.checkMathBounds === true,
     enforceInsideMathFunctions: options.enforceInsideMathFunctions === true,
     ignoreMathFunctionArguments: normalizeMathFunctionArgumentMap(options.ignoreMathFunctionArguments),
     ignoreValues: Array.isArray(options.ignoreValues)
@@ -647,6 +701,7 @@ function buildTokenOptions(rawOptions) {
     properties: resolvePropertyPatterns(options),
     propertyGroups: normalizePropertyGroups(options.propertyGroups),
     propertyScaleOverrides: buildPropertyScaleOverrides(options.propertyScales),
+    groupScales: buildGroupScales(options.scales),
     scale: scaleSelection.scale,
     scaleAuto: isAutoScaleLiteral(options.scale),
     scaleSources: Array.isArray(options.scaleSources) ? options.scaleSources : [],
@@ -688,8 +743,9 @@ function createPropertyScaleResolver(options) {
     if (cached) {
       return cached;
     }
-    const selectedScale = resolvePropertyScale(prop, options);
+    const { group, scale: selectedScale } = resolvePropertyScaleEntry(prop, options);
     const state = {
+      group,
       scaleByUnit: normalizeScaleByUnit(selectedScale),
       scalePx: normalizeScale(selectedScale, options.baseFontSize),
     };
@@ -699,29 +755,41 @@ function createPropertyScaleResolver(options) {
 }
 
 function resolvePropertyScale(prop, options) {
-  if (!Array.isArray(options.propertyScaleOverrides)) {
-    return options.scale;
-  }
+  return resolvePropertyScaleEntry(prop, options).scale;
+}
 
-  for (const override of options.propertyScaleOverrides) {
+/**
+ * The scale a property is checked against, most specific first: a
+ * `propertyScales` entry for the property, then the `scales` entry for its
+ * group, then `scale`. `group` is set only when `scales` supplied it, so a
+ * message can say which scale it means.
+ */
+function resolvePropertyScaleEntry(prop, options) {
+  for (const override of options.propertyScaleOverrides || []) {
     if (override.matcher instanceof RegExp) {
       if (override.matcher.global || override.matcher.sticky) {
         override.matcher.lastIndex = 0;
       }
 
       if (override.matcher.test(prop)) {
-        return override.scale;
+        return { group: null, scale: override.scale };
       }
 
       continue;
     }
 
     if (String(override.matcher).toLowerCase() === prop.toLowerCase()) {
-      return override.scale;
+      return { group: null, scale: override.scale };
     }
   }
 
-  return options.scale;
+  const group = propertyKindOf(prop);
+  const groupScale = group && options.groupScales ? options.groupScales[group] : null;
+  if (groupScale && Array.isArray(groupScale.scale)) {
+    return { group, scale: groupScale.scale };
+  }
+
+  return { group: null, scale: options.scale };
 }
 
 module.exports = {
@@ -737,7 +805,9 @@ module.exports = {
   USE_SCALE_VALIDATION_SCHEMA,
   buildScaleOptions,
   buildTokenOptions,
+  SCALED_GROUPS,
   createPropertyScaleResolver,
+  isGroupScalesMap,
   isPlainObject,
   resolvePropertyScale,
 };

package/src/core/scale-inference.js

@@ -522,19 +522,58 @@ function fallbackInference(rejected = null) {
  * an explicit scale pass through untouched.
  */
 function withResolvedScale(options, root) {
-  if (!options.scaleAuto) {
-    return options;
+  if (options.scaleAuto) {
+    const inference = resolveAutoScale({
+      baseFontSize: options.baseFontSize,
+      root,
+      scaleSources: options.scaleSources,
+      tailwindConfigPath: options.tailwindConfigPath,
+      tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
+    });
+    options.scale = inference.scale;
+    options.scaleInference = inference;
+  }
+  for (const [group, entry] of Object.entries(options.groupScales || {})) {
+    if (entry.auto) {
+      entry.scale = inferGroupScale(group, options, root);
+    }
   }
-  const inference = resolveAutoScale({
+  return options;
+}
+
+// Token names each group's "auto" reads. Spacing is the project scale itself.
+const GROUP_TOKEN_PATTERNS = Object.freeze({
+  radius: /^--radius-/,
+  size: /^--(?:size|width|height|container)-/,
+  typography: /^--(?:font-size|text|fs)-/,
+});
+
+/**
+ * A group's scale from its own tokens (`--font-size-*` and Tailwind's
+ * `--text-*` for typography, `--radius-*` for radius). Null when fewer than
+ * four values are found, and the group then uses `scale`. Fluid tokens
+ * (`clamp()`) have no single value and are not part of an inferred scale.
+ */
+function inferGroupScale(group, options, root) {
+  if (group === 'spacing') {
+    return options.scaleAuto ? options.scale : resolveAutoScale({
+      baseFontSize: options.baseFontSize,
+      root,
+      scaleSources: options.scaleSources,
+      tailwindConfigPath: options.tailwindConfigPath,
+      tokenPattern: DEFAULT_AUTO_TOKEN_PATTERN,
+    }).scale;
+  }
+  const pattern = GROUP_TOKEN_PATTERNS[group];
+  const definitions = collectTokenDefinitions({
     baseFontSize: options.baseFontSize,
     root,
     scaleSources: options.scaleSources,
-    tailwindConfigPath: options.tailwindConfigPath,
-    tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
+    tokenPattern: pattern.source,
+    tokenRegex: pattern,
   });
-  options.scale = inference.scale;
-  options.scaleInference = inference;
-  return options;
+  const own = new Map([...definitions].filter(([token]) => pattern.test(token)));
+  return own.size > 0 ? scaleFromDefinitions(own, options.baseFontSize) : null;
 }
 
 function autoScaleFallbackNote(inference) {

package/src/core/token-index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { PROPERTY_GROUP_PATTERNS } = require('./css-vocabulary');
+const { propertyKindOf } = require('./css-vocabulary');
 const { fixedLengthValue, numbersEqual, toPx } = require('./length');
 const { createTokenKindMatcher, parseTokenValueLength } = require('./token-sources');
 
@@ -24,19 +24,13 @@ function tokenKindOf(token) {
   return found ? found[0] : null;
 }
 
-function propertyGroupOf(prop) {
-  const lower = String(prop || '').toLowerCase();
-  const found = Object.entries(PROPERTY_GROUP_PATTERNS).find(([, patterns]) => patterns.some((pattern) => pattern.test(lower)));
-  return found ? found[0] : null;
-}
-
 /**
  * Whether a token may be offered for a property: a padding never gets a radius
  * token, even when both hold 16px and the token pattern admits both. A token
  * whose name declares no kind, or a property outside every group, is allowed.
  */
 function tokenFitsProperty(token, prop) {
-  const group = prop ? propertyGroupOf(prop) : null;
+  const group = prop ? propertyKindOf(prop) : null;
   const kind = group ? tokenKindOf(String(token).replace(/^var\(\s*|\s*\)$/g, '')) : null;
   return !group || !kind || ACCEPTED_KINDS[group].includes(kind);
 }

package/src/core/value-nodes.js

@@ -191,6 +191,55 @@ function shouldLintMathArgument(context, options) {
   return true;
 }
 
+const BOUND_FUNCTIONS = new Set(['clamp', 'min', 'max']);
+
+function isBoundFunction(node) {
+  return node.type === 'function' && BOUND_FUNCTIONS.has(node.value.toLowerCase());
+}
+
+function splitArguments(nodes) {
+  const args = [[]];
+  for (const node of nodes) {
+    if (node.type === 'div' && node.value === ',') {
+      args.push([]);
+      continue;
+    }
+    if (node.type !== 'space' && node.type !== 'comment') {
+      args[args.length - 1].push(node);
+    }
+  }
+  return args;
+}
+
+/**
+ * The static bounds of a fluid value (issue #203): the minimum and maximum of
+ * `clamp(MIN, VAL, MAX)` and every argument of `min()` and `max()`. A bound
+ * counts only when it is one word, a length literal; the preferred value of
+ * clamp(), an expression, or a var() is fluid by design and left alone. A
+ * bound that is itself min(), max() or clamp() is followed.
+ */
+function collectMathBounds(fnNode) {
+  const name = fnNode.value.toLowerCase();
+  const args = splitArguments(fnNode.nodes);
+  const positioned = name === 'clamp'
+    ? (args.length === 3 ? [[args[0], 'clamp() minimum'], [args[2], 'clamp() maximum']] : [])
+    : args.map((arg) => [arg, `${name}() argument`]);
+
+  const bounds = [];
+  for (const [arg, position] of positioned) {
+    if (arg.length !== 1) {
+      continue;
+    }
+    const [node] = arg;
+    if (node.type === 'word') {
+      bounds.push({ node, position });
+    } else if (isBoundFunction(node)) {
+      bounds.push(...collectMathBounds(node));
+    }
+  }
+  return bounds;
+}
+
 function declarationValueIndex(decl) {
   const declarationText = decl.toString();
   const idx = declarationText.indexOf(decl.value);
@@ -198,7 +247,9 @@ function declarationValueIndex(decl) {
 }
 
 module.exports = {
+  collectMathBounds,
   declarationValueIndex,
+  isBoundFunction,
   isKeyword,
   isMathFunction,
   isTokenFunction,

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

@@ -14,6 +14,8 @@ const {
   createPropertyScaleResolver,
 } = require('../../core/options');
 const {
+  collectMathBounds,
+  isBoundFunction,
   isKeyword,
   isMathFunction,
   isTokenFunction,
@@ -44,8 +46,8 @@ const ruleName = 'rhythmguard/prefer-token';
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, replacement = null, origin = null, note = '', candidates = []) =>
-    `Unexpected raw scale value "${value}". ${replacement
+  rejected: (value, replacement = null, origin = null, note = '', candidates = [], position = null) =>
+    `Unexpected raw ${position || 'scale value'} "${value}". ${replacement
       ? `Use ${replacement}${origin ? ` (${origin})` : ''}.`
       : candidates.length > 1
         ? `Use one of the tokens that hold it: ${listTokens(candidates)}.`
@@ -177,18 +179,18 @@ const ruleFunction = (primary, secondaryOptions) => {
       const { scaleByUnit, scalePx } = getScaleStateForProperty(prop);
       let changed = false;
 
-      const reportNode = (node, parsedLength) => {
+      const reportNode = (node, parsedLength, position = null) => {
         const mapped = resolveTokenReplacement(tokenMap, node.value, parsedLength, options);
         if (mapped && tokenFitsProperty(mapped.token, prop)) {
           const origin = origins[mapped.token] || null;
-          reportValueNode({ decl, message: messages.rejected(node.value, mapped.replacement, origin, options.note), node, replacement: mapped.replacement, result, ruleName });
+          reportValueNode({ decl, message: messages.rejected(node.value, mapped.replacement, origin, options.note, [], position), node, replacement: mapped.replacement, result, ruleName });
           return;
         }
         const indexed = resolveFromIndex(tokenIndex, parsedLength, prop, options);
         const named = indexed.replacement || null;
         reportValueNode({
           decl,
-          message: messages.rejected(node.value, named, indexed.origin || null, options.note, indexed.candidates),
+          message: messages.rejected(node.value, named, indexed.origin || null, options.note, indexed.candidates, position),
           node,
           replacement: indexed.fixable ? named : null,
           result,
@@ -196,12 +198,12 @@ const ruleFunction = (primary, secondaryOptions) => {
         });
       };
 
-      const checkWordNode = (node, context) => {
+      const checkWordNode = (node, context, position = null) => {
         if (isKeyword(node.value, options.ignoreValues)) {
           return false;
         }
 
-        if (!shouldLintMathArgument(context, options)) {
+        if (!position && !shouldLintMathArgument(context, options)) {
           return false;
         }
 
@@ -259,7 +261,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
         }
 
-        reportNode(node, parsedLength);
+        reportNode(node, parsedLength, position);
         return true;
       };
 
@@ -285,12 +287,22 @@ const ruleFunction = (primary, secondaryOptions) => {
           return false;
         });
       } else {
+        const checkedBounds = new Set();
         walkRootValueNodes(parsed, (node, context) => {
           if (node.type === 'function') {
             if (isTokenFunction(node, options.tokenFunctions, tokenRegex)) {
               return true;
             }
 
+            if (options.checkMathBounds && isBoundFunction(node)) {
+              for (const bound of collectMathBounds(node)) {
+                if (!checkedBounds.has(bound.node)) {
+                  checkedBounds.add(bound.node);
+                  changed = checkWordNode(bound.node, null, bound.position) || changed;
+                }
+              }
+            }
+
             if (isMathFunction(node.value) && !options.enforceInsideMathFunctions) {
               return true;
             }
@@ -298,7 +310,7 @@ const ruleFunction = (primary, secondaryOptions) => {
             return false;
           }
 
-          if (node.type !== 'word') {
+          if (node.type !== 'word' || checkedBounds.has(node)) {
             return false;
           }
 

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

@@ -15,6 +15,8 @@ const {
   createPropertyScaleResolver,
 } = require('../../core/options');
 const {
+  collectMathBounds,
+  isBoundFunction,
   isKeyword,
   isMathFunction,
   isTokenFunction,
@@ -41,10 +43,20 @@ const ruleName = 'rhythmguard/use-scale';
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, lower, upper, note = '') =>
-    `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
+  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}` : ''}`,
 });
 
+/** " (16.8px)" after a bound written in rem or em, so the reader sees what was compared. */
+function pxAside(value, baseFontSize) {
+  const parsed = parseLengthToken(value);
+  if (!parsed || !parsed.unit || parsed.unit === 'px' || parsed.unit === '%') {
+    return '';
+  }
+  const px = toPx(Math.abs(parsed.number), parsed.unit, baseFontSize);
+  return px === null ? '' : ` (${formatLength(parsed.number < 0 ? -px : px, 'px')})`;
+}
+
 /** Decisions from .rhythmguardrc.json; an invalid section is reported once and ignored. */
 function readDecisions(options, { result, root }) {
   if (!options.readDecisions) {
@@ -253,13 +265,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     let fallbackNote = autoScaleFallbackNote(options.scaleInference);
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
-    const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px', extraNote = '') => {
+    const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px', extraNote = '', position = null) => {
       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, tokenNote, extraNote, options.note].filter(Boolean).join(' ')),
+        message: messages.rejected(value, lower, upper, [fallbackNote, tokenNote, extraNote, options.note].filter(Boolean).join(' '), position, position ? pxAside(value, options.baseFontSize) : '', getScaleStateForProperty(decl.prop.toLowerCase()).group),
         node,
         replacement: fixedValue,
         result,
@@ -342,6 +354,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           return false;
         });
       } else {
+        const checkedBounds = new Set();
         walkRootValueNodes(parsed, (node, context) => {
 
           if (node.type === 'function') {
@@ -349,6 +362,20 @@ const ruleFunction = (primary, secondaryOptions) => {
               return true;
             }
 
+            if (options.checkMathBounds && isBoundFunction(node)) {
+              for (const bound of collectMathBounds(node)) {
+                if (checkedBounds.has(bound.node)) {
+                  continue;
+                }
+                checkedBounds.add(bound.node);
+                if (isKeyword(bound.node.value, options.ignoreValues)) {
+                  continue;
+                }
+                const boundReport = (value, d, n, nearest, fixed, unit, extra) => report(value, d, n, nearest, fixed, unit, extra, bound.position);
+                changed = checkLengthValue({ decl, node: bound.node, options, report: boundReport, scaleByUnit, scalePx }) || changed;
+              }
+            }
+
             if (
               isMathFunction(node.value) &&
               !options.enforceInsideMathFunctions
@@ -359,7 +386,7 @@ const ruleFunction = (primary, secondaryOptions) => {
             return false;
           }
 
-          if (node.type !== 'word') {
+          if (node.type !== 'word' || checkedBounds.has(node)) {
             return false;
           }
 

package/types/audit.d.ts

@@ -32,7 +32,11 @@ export interface AuditOptions {
   format?: "json" | "json-v1" | "markdown" | "text" | "html" | "github" | "badge";
   ignorePath?: string;
   ignorePatterns?: string[];
+  /** Check clamp() bounds and min()/max() arguments against the scale (equivalent to `--check-math-bounds`). */
+  checkMathBounds?: boolean;
   includeMotion?: boolean;
+  /** A scale per property group (`spacing`, `radius`, `size`, `typography`): values, a preset name or "auto". Each group named is also checked. */
+  scales?: Partial<Record<"spacing" | "radius" | "size" | "typography", Array<number | string> | string | { preset?: string; scale?: Array<number | string>; customScale?: Array<number | string> }>>;
   maxFindings?: number;
   minCleanliness?: number;
   /** Skip config discovery entirely (equivalent to `--no-config`). */

package/types/shared.d.ts

@@ -17,6 +17,8 @@ export interface ScaleSource {
 export interface RhythmguardRuleOptions {
   /** Exempt non-zero lengths of one CSS pixel or less (1px, -1px, 0.5px, 0.0625rem). Default true. */
   allowHairlines?: boolean;
+  /** Check the static bounds of fluid values: the clamp() minimum and maximum and each length argument of min() and max(). Default false; the preferred value of clamp() is never checked. */
+  checkMathBounds?: boolean;
   /** What autofix writes: the nearest literal (default) or, with "token", `var(--name)` when exactly one custom property holds that value in the same unit. */
   fixWith?: "value" | "token";
   /** Read the `decisions` section of `.rhythmguardrc.json` (default true). The audit sets false and applies decisions itself. */
@@ -34,6 +36,12 @@ export interface RhythmguardRuleOptions {
    * properties, then `tailwindConfigPath`, falling back to the `rhythmic-4` preset.
    */
   scale?: ScaleValue[] | "auto";
+  /**
+   * A scale per property group, used before `scale` and after `propertyScales`: values, a
+   * preset name, or `"auto"` to infer the group's scale from its tokens (`--font-size-*` and
+   * `--text-*` for typography, `--radius-*` for radius). Findings then name the group's scale.
+   */
+  scales?: Partial<Record<"spacing" | "radius" | "size" | "typography", ScaleValue[] | string | { preset?: string; scale?: ScaleValue[]; customScale?: ScaleValue[] }>>;
   /** Token files consulted first when `scale` is `"auto"`. */
   scaleSources?: Array<string | ScaleSource>;
   /** Tailwind v3 config whose `theme.spacing` feeds `scale: "auto"` and `tokenMapFromTailwindSpacing`. */