stylelint-plugin-rhythmguard 3.8.0 → 3.10.0

package/CHANGELOG.md

@@ -6,6 +6,52 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [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
+
+- `scale: "auto"` reads `@mozilla-protocol/tokens` when it is installed: `--spacing-xs` to `--spacing-2xl` (4 to 48px) from `dist/units/units.custom-properties.css`. Mozilla Protocol's benchmark row is measured against that package at 7.0.0, as a Protocol contributor pointed out in mozilla/protocol#1132: 19 off-scale values, against 18 on the `rhythmic-4` fallback, because 12px is not a Protocol step and 48px is.
+
+### Fixed
+
+- `prefer-token` reads the token sources `use-scale` reads for `fixWith: "token"`: the linted stylesheet, `scaleSources`, the `audit.tokenSources` files in `.rhythmguardrc.json` and installed token packages ([#202](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/202)). Before, a token declared in a config token source was invisible to `prefer-token`, which then said no token held a value that one did; on one consumer, 478 of 611 baselined warnings were values an existing token holds. Both rules now resolve tokens through one function, so a token is known to both or to neither, and a contract test holds them to it. The fix writes such a token only when exactly one holds the value in the literal's unit, the same rule `fixWith: "token"` follows.
+- Tokens are matched to the property's kind. A `tokenPattern` such as `^--space-|^--radius-` no longer lets `padding: 1rem` be pointed at, or fixed to, `--radius-xl` because it also holds 16px. Radius, typography and motion tokens serve their own properties; spacing and size tokens serve each other's. Applies to `prefer-token` and to `fixWith: "token"` in `use-scale` and `no-offscale-transform`.
+- A rule's own `tokenPattern` applies to the token source files it reads as well as to the stylesheet, so `--radius-*` tokens in a config token source are found when the pattern asks for them.
+- The audit no longer hangs on template files that contain an unclosed quote followed by escape-dense source. The Tailwind class-string scanner found string literals with a regex whose alternation was ambiguous on every backslash, so from an apostrophe in a comment or a quote inside a regex literal it backtracked exponentially over the `\{ \[ \(` of the next regex literal; on the Ace editor's `mode-alda.js` (10 KB, vendored by a MediaWiki skin) one `rhythmguard audit` ran for eleven hours before it was killed, and Bootswatch's audit took longer than three minutes. The finder is now a single linear pass: an escape never closes a literal, a `'` or `"` literal that reaches a line break is not a literal, a backtick literal may span lines. Both repositories audit in seconds. The benchmark gained five findings that an unclosed quote had been hiding (four in Ghost's `input-group.tsx`, one in Cal.com's `Button.tsx`).
+- The audit no longer throws `All input files were ignored because of the ignore pattern` when a project's own `.stylelintignore` excludes every stylesheet the walk found. The files are counted as `scanned.stylelintIgnored` in the JSON contract and shown in text and Markdown output, so a clean report cannot hide that nothing was audited.
+
+### Messages
+
+Message text changes are listed here, so teams that key a warning baseline on message text know which warnings will reappear as resolved-plus-new pairs (see [#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)).
+
+- `prefer-token`, when a token in a config token source, `scaleSources` or an installed token package holds the value: was `No known token holds this value; use the nearest token or add one.`, now `Use var(--token) (path/to/tokens.css).` When a token in another unit holds it, the message names that token and the fix leaves the literal.
+- `prefer-token`, when several tokens hold the value: was `No known token holds this value; ...`, now `Use one of the tokens that hold it: var(--a) or var(--b).`
+- Unchanged: the message for a value no token holds, and every `use-scale` message.
+
+### Changed
+
+- The post-publish smoke waits for the version through `npm view --prefer-online`, the client that will install it, instead of the raw packument; for 3.8.0 the packument listed the version a minute before `npm install` could resolve it and the smoke failed.
+- The quiet benchmark installs the token packages maintainers named as the home of their scale. A manifest row lists them under `tokenPackages` with a pinned version; `npm run bench:quiet` installs them once under `benchmarks/quiet/packages/` with install scripts disabled and passes the allowlisted token files to the audit as explicit sources, so the row is measured against the ladder the maintainers pointed at instead of the `rhythmic-4` fallback or a set of consumer tokens. Carbon (`@carbon/layout`), Primer CSS and Primer React (`@primer/primitives`), mittwald Flow (`@mittwald/flow-design-tokens`) and AdminLTE (`bootstrap`) are measured this way; the SAP rows stay unmeasured because their theming package carries no ladder. The State of Spacing edition marks these rows `installed` and counts them.
+- PatternFly's fourteen benchmark findings are labelled by review: four in a vendored Font Awesome partial and ten in documentation example CSS, none in component SCSS, as the reply in patternfly/patternfly#8579 said. Per-repo labels live in `benchmarks/quiet/labels/`.
+- New README banner for 3.8.0. GitHub shows the transparent SVG; npmjs.com, which renders the README on a white page, gets the non-transparent PNG (`assets/rhythmguard-banner.png`): the release job swaps the banner line with `scripts/ci/npm-readme.mjs` just before `npm publish`, and a contract test fails if the banner line is not found exactly once. The npm page changes with the next published version.
+- `rhythmguard` and `eslint-plugin-rhythmguard` are on npm (3.8.0, first published by hand on 2026-09-27). `npx rhythmguard` now works in a project that has installed nothing, and the README's first command and ESLint setup use the two packages. Later releases publish them from `release.yml` once each has a trusted publisher and `PUBLISH_COMPANIONS` is set.
+
 ## [3.8.0] - 2026-09-18
 
 ### Added

package/CONTRIBUTING.md

@@ -6,7 +6,7 @@ Thank you for being here. Rhythmguard is a small, opinionated tool with one job:
 
 **Report a false positive.** A finding your team considers wrong is the most valuable report we get. It is how percentages and hairlines stopped being findings. Open a [false-positive report](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/new?template=false-positive.yml) with the CSS or class string and your config. No fix required.
 
-**Add a repository to the quiet benchmark.** The benchmark audits public design systems and fails CI when the findings change. Adding a repo is one JSON entry in `benchmarks/quiet/repos.json` plus `npm run bench:quiet -- --only <name>` to create its snapshot. Systems with tokens in unusual places are the most useful additions. The same results feed the dated [State of Spacing](./docs/STATE_OF_SPACING.md) editions, so every repository you add widens that report.
+**Add a repository to the quiet benchmark.** The benchmark audits public design systems and fails CI when the findings change. Adding a repo is one JSON entry in `benchmarks/quiet/repos.json` plus `npm run bench:quiet -- --only <name>` to create its snapshot. Systems with tokens in unusual places are the most useful additions. When the scale ships in an npm package rather than in the repository, list it under `tokenPackages` with a pinned version (the package must be in `src/core/token-packages.json`); the bench installs it and measures the row against that ladder. The same results feed the dated [State of Spacing](./docs/STATE_OF_SPACING.md) editions, so every repository you add widens that report.
 
 **Review a drift list.** Each benchmark repo has a list of findings that heuristics call real drift. Labelling them as real or as an allowance in `benchmarks/quiet/labels/<repo>.json` with a one-line reason turns a heuristic number into a reviewed one, and any systematic pattern you find becomes a candidate default.
 
@@ -16,6 +16,8 @@ Thank you for being here. Rhythmguard is a small, opinionated tool with one job:
 
 **Contribute a community scale.** JSON files in `scales/community/`, scaffolded with `npm run scales:add -- --name my-team-scale --base 8 --steps 0,4,8,12,16,24,32` and checked with `npm run scales:validate`. Spec and policy in [`docs/COMMUNITY_SCALES.md`](./docs/COMMUNITY_SCALES.md).
 
+The plan for the next nine months is in [`ROADMAP.md`](./ROADMAP.md), and every item there is an issue labelled [`roadmap`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/labels/roadmap) with a milestone. Items labelled `decision` are open questions with the evidence that will settle them; a comment with evidence is a contribution.
+
 Issues labelled [`good first issue`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/labels/good%20first%20issue) are scoped for a first PR. [`help wanted`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/labels/help%20wanted) marks work the maintainer would like a second pair of hands on. If you want to work on something larger, open an issue first so we can agree the shape before you write code.
 
 ## Getting set up
@@ -27,7 +29,7 @@ npm ci
 npm test
 ```
 
-Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` through `scripts/test.mjs` and take about ten seconds. They are grouped by what they prove:
+Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` through `scripts/test.mjs` and take about fifteen seconds. They are grouped by what they prove:
 
 | Folder | Proves | Run one |
 | --- | --- | --- |
@@ -48,7 +50,7 @@ Run these before you push. They are what CI runs, so a green local run means a g
 ```bash
 npm run lint        # eslint
 npm run typecheck   # the published TypeScript declarations against a consumer file and the examples
-npm test            # 200+ tests, Stylelint 16
+npm test            # 300+ tests, on the Stylelint in the lockfile (17)
 ```
 
 Optional, depending on what you touched:
@@ -59,6 +61,8 @@ npm run test:pack-smoke        # pack the tarball and install it in a temp proje
 npm run scales:validate        # community scale JSON
 npm run bench:quiet -- --check # findings on the benchmark repos must match snapshots
 npm run build:agents           # after editing the block in docs/FOR_AGENTS.md
+npm run build:playground       # after changing anything under src/ the rules use
+npm run bench:agents -- --dry-run --limit 4   # the agent eval pipeline, no API key needed
 ```
 
 The local gate runs on whatever Node you have installed; CI runs Node 20 and 22. Node 20.19 is the floor, so avoid features that arrived in Node 21 or later. Glob patterns for `node --test` were one such feature, and they took a release run down.
@@ -67,7 +71,7 @@ If your shell's npm registry is overridden by a corporate `.npmrc`, add `--regis
 
 ### Pull requests from forks
 
-CI for this repository runs on self-hosted runners for pushes and same-repo branches. For pull requests from forks a separate job runs on GitHub-hosted runners with Node 22 and current Stylelint 16, covering lint, typecheck and the test suite. You will see its result on your PR. The full matrix and the benchmark run after merge.
+CI for this repository runs on self-hosted runners for pushes and same-repo branches. For pull requests from forks a separate job runs on GitHub-hosted runners with Node 22 and the Stylelint in the lockfile (17), covering lint, typecheck and the test suite. You will see its result on your PR. The full matrix and the benchmark run after merge.
 
 ## Where things live
 
@@ -96,7 +100,8 @@ CI for this repository runs on self-hosted runners for pushes and same-repo bran
 ## Compatibility
 
 - Stylelint `^16.0.0 || ^17.0.0`. The 16.0.0 floor has known autofix differences; CI runs the floor suite against it.
-- Node `>=20.19.0`.
+- Node `>=20.19.0` until 4.0, which raises it to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)).
+- ESLint `>=8.0.0` for the companion rules; tested on 9.
 - CommonJS and ESM entry points; every export has a declaration under `types/`.
 - Three runtime dependencies: `known-css-properties`, `postcss` and `postcss-value-parser`. `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers and dev dependencies here. `test/contracts/architecture.test.js` fails if a runtime import is not declared.
 
@@ -106,7 +111,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. 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).
+Maintainer-run. Bump `package.json`, the two companion packages under `packages/` and `CHANGELOG.md` to the same version, 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=12" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.png?v=13" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
 </p>
 
 # stylelint-plugin-rhythmguard
@@ -7,18 +7,18 @@
 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=380)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3100)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![npm 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)
 
 Rhythmguard is scale-aware rather than a blanket ban: values on your scale pass, values off it are reported with the two nearest steps, and tokens are only ever suggested from a map you control. It works on CSS and SCSS declarations through Stylelint and on Tailwind class strings through an ESLint companion, and it ships an audit CLI so you can measure drift and ratchet it down before enforcing anything.
 
-What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). Pair it with a color linter if you need one; do not expect one tool to do both.
+What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). It reads CSS and SCSS; Less and CSS-in-JS are not read. Pair it with a color linter if you need one; do not expect one tool to do both.
 
 ## Start here
 
 ```bash
-npx stylelint-plugin-rhythmguard
+npx rhythmguard
 ```
 
 No install, no config. It detects your stack and token files, infers your spacing scale from your own tokens, audits the current directory, and prints the exact `.stylelintrc.json` (and ESLint snippet for Tailwind) to paste. This is the whole run on Bootstrap's `v6-dev` branch, unedited:
@@ -47,11 +47,15 @@ That enables `rhythmguard/use-scale` on spacing properties with the default 4px
 }
 ```
 
-For class strings in JSX, TSX, Vue, Svelte or Astro, add the ESLint companion. It is the same rules under two names: `stylelint-plugin-rhythmguard/eslint` if you already have this package, or [`eslint-plugin-rhythmguard`](packages/eslint-plugin-rhythmguard#readme) on its own.
+For class strings in JSX, TSX, Vue, Svelte or Astro, add the ESLint companion, [`eslint-plugin-rhythmguard`](packages/eslint-plugin-rhythmguard#readme). It is the same rules as `stylelint-plugin-rhythmguard/eslint`, so either import works. The rules also run under Oxlint's JS plugins.
+
+```bash
+npm install --save-dev eslint eslint-plugin-rhythmguard
+```
 
 ```js
 // eslint.config.js
-import rhythmguard from 'stylelint-plugin-rhythmguard/eslint';
+import rhythmguard from 'eslint-plugin-rhythmguard';
 
 export default [
   {
@@ -80,6 +84,8 @@ Every rule validates its options up front. Unknown option names and wrong shapes
 
 ## Audit before you enforce
 
+With the package installed, the `rhythmguard` command is available to `npx`:
+
 ```bash
 npx rhythmguard audit ./src --format markdown
 npx rhythmguard audit ./src --write-baseline
@@ -101,14 +107,15 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 - [For coding agents](docs/FOR_AGENTS.md): a paste-ready `AGENTS.md` block, installable with `npx rhythmguard init --agents all` for Claude Code, Cursor and Copilot
 - [Quiet benchmark](docs/QUIET_BENCHMARK.md): findings on public design systems, checked on every change
 - [State of Spacing](docs/STATE_OF_SPACING.md): dated editions of the same data, ranked by drift density, with the values and properties that drifted
-- [Agent evals](docs/AGENT_EVALS.md): does a finding get a coding agent to zero drift, in how many rounds, at what cost, against a rules-only control
+- [Agent evals](docs/AGENT_EVALS.md): does a finding get a coding agent to zero drift, in how many rounds, at what cost, against a rules-only control. First edition (2026-10-10): every model fixed every finding in one round with or without the findings; fixing from findings cost Sonnet 5 less than half as much
 - [Architecture](docs/ARCHITECTURE.md): the layers, the rule kit, the invariants and where each is enforced
-- [Product direction](docs/STRATEGY_2026-09.md)
+- [Roadmap](ROADMAP.md): what is planned from October 2026 to June 2027, and the checkpoint that decides the pace
+- [Product analysis, September 2026](docs/STRATEGY_2026-09.md): the market data behind the roadmap
 - Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/) runs the real rules, bundled for the browser, on CSS or SCSS you paste; `scale: "auto"`, tokens and fixes included, and a test proves it reports what Stylelint reports
 
 ## Compatibility
 
-Stylelint 16 and 17. Node 20.19 or newer. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
+Stylelint 16 and 17. Node 20.19 or newer; Node 20 itself is end of life, and 4.0 raises the floor to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)). The ESLint companion needs ESLint 8 or newer, is tested on ESLint 9, and has been checked by hand on ESLint 10 and Oxlint 1.85. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
 
 ## Contributing and support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "description": "Nobody chose 13px. Catches off-scale spacing in CSS and Tailwind class strings and snaps it to your scale or tokens. Stylelint rules, an ESLint companion, and an audit CLI.",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -158,18 +158,18 @@
     "postcss-value-parser": "^4.2.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.126.0",
-    "@eslint/js": "^9.39.5",
+    "@anthropic-ai/sdk": "^0.133.0",
+    "@eslint/js": "^10.0.0",
     "@types/node": "^22.20.1",
     "c8": "^12.0.0",
-    "esbuild": "^0.25.10",
-    "eslint": "^9.39.5",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.0.0",
     "postcss-scss": "^4.0.9",
-    "stylelint": "^16.15.0",
+    "stylelint": "^17.0.0",
     "stylelint-config-tailwindcss": "^1.0.1",
     "stylelint-plugin-logical-css": "^2.0.2",
     "stylelint-scales": "^5.0.0",
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.0"
   },
   "engines": {
     "node": ">=20.19.0"

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,
@@ -45,7 +46,7 @@ function loadAuditConfig(parsed) {
   try {
     config = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
   } catch (err) {
-    throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: ${err.message}`);
+    throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: ${err.message}`, { cause: err });
   }
 
   if (!config || typeof config !== 'object' || Array.isArray(config)) {
@@ -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/contract.js

@@ -26,7 +26,7 @@ function collectTokenContract({
   const matchesKind = createTokenKindMatcher(tokenKind);
 
   for (const filePath of cssFiles) {
-    let source = '';
+    let source;
     try {
       source = fs.readFileSync(filePath, 'utf8');
     } catch {
@@ -235,6 +235,7 @@ function buildReport({
   scanScope,
   scssFiles = 0,
   scssSkipped = 0,
+  stylelintIgnored = 0,
   templateFiles,
   tailwindFindings,
   tokenCandidateMinCount,
@@ -308,6 +309,7 @@ function buildReport({
       cssFiles: cssFiles.length,
       scssFiles,
       scssSkipped,
+      stylelintIgnored,
       templateFiles: templateFiles.length,
       totalFiles,
     },

package/src/audit/render-markdown.js

@@ -27,6 +27,7 @@ function renderMarkdown(report) {
     `| Template files scanned | ${report.templateFilesScanned} |`,
     ...(report.scanned && report.scanned.scssFiles > 0 ? [`| SCSS files scanned | ${report.scanned.scssFiles - report.scanned.scssSkipped} |`] : []),
     ...(report.scanned && report.scanned.scssSkipped > 0 ? [`| SCSS files skipped (install postcss-scss) | ${report.scanned.scssSkipped} |`] : []),
+    ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`| Stylesheets ignored by .stylelintignore (not audited) | ${report.scanned.stylelintIgnored} |`] : []),
     `| Files with issues | ${report.filesWithIssues} |`,
     `| Total findings | ${report.totalWarnings} |`,
     `| Scale cleanliness | ${report.scaleCleanliness}% |`,
@@ -54,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) {
@@ -117,6 +119,39 @@ 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]);
+    }
+    lines.push(`**\`${escapeMarkdown(entry.prefix)}\`**`);
+    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

@@ -21,6 +21,7 @@ function renderText(report) {
     `  Template files scanned   ${String(report.templateFilesScanned).padStart(4)}`,
     ...(report.scanned && report.scanned.scssFiles > 0 ? [`  SCSS files scanned       ${String(report.scanned.scssFiles - report.scanned.scssSkipped).padStart(4)}`] : []),
     ...(report.scanned && report.scanned.scssSkipped > 0 ? [`  SCSS files skipped       ${String(report.scanned.scssSkipped).padStart(4)}  (install postcss-scss to audit them)`] : []),
+    ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`  Ignored by .stylelintignore ${String(report.scanned.stylelintIgnored).padStart(4)}  (not audited)`] : []),
     `  Files with issues        ${String(report.filesWithIssues).padStart(4)}`,
     `  Scale cleanliness        ${scoreBar(report.scaleCleanliness)}  ${report.scaleCleanliness}%`,
   ];
@@ -50,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);
@@ -89,6 +92,7 @@ async function createAuditReport(options) {
     scanScope,
     scssFiles: cssResults.scssFiles || 0,
     scssSkipped: cssResults.scssSkipped || 0,
+    stylelintIgnored: cssResults.stylelintIgnored || 0,
     tailwindFindings: decided.tailwindFindings,
     templateFiles,
     tokenCandidateMinCount: parsed.tokenCandidateMinCount,
@@ -97,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/files.js

@@ -80,7 +80,7 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
   const args = parsed.staged
     ? ['diff', '--name-only', '--cached', '--diff-filter=ACMR', '--']
     : ['diff', '--name-only', '--diff-filter=ACMR', parsed.since, '--'];
-  let output = '';
+  let output;
 
   try {
     output = execFileSync('git', args, {
@@ -90,7 +90,7 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
     });
   } catch (err) {
     const stderr = err.stderr ? String(err.stderr).trim() : err.message;
-    throw new Error(`Unable to read changed files from git: ${stderr}`);
+    throw new Error(`Unable to read changed files from git: ${stderr}`, { cause: err });
   }
 
   const cssFiles = [];

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,
@@ -77,7 +81,10 @@ async function runStylelintAudit(cssFiles, options) {
   const results = [];
 
   if (plainFiles.length > 0) {
+    // A project's own .stylelintignore may exclude every file we pass; that is
+    // a count to report, not a reason for the audit to throw.
     const result = await stylelint.lint({
+      allowEmptyInput: true,
       files: plainFiles,
       config: {
         plugins: [pluginPath],
@@ -92,6 +99,7 @@ async function runStylelintAudit(cssFiles, options) {
     const scssSyntax = resolveScssSyntax();
     if (scssSyntax) {
       const result = await stylelint.lint({
+        allowEmptyInput: true,
         files: scssFiles,
         config: {
           customSyntax: scssSyntax,
@@ -107,6 +115,10 @@ async function runStylelintAudit(cssFiles, options) {
 
   results.scssFiles = scssFiles.length;
   results.scssSkipped = scssSkipped;
+  // Stylelint returns no result at all for a file its ignore file excludes, so
+  // the difference between what was passed and what came back is that count.
+  const linted = plainFiles.length + scssFiles.length - scssSkipped;
+  results.stylelintIgnored = Math.max(0, linted - results.length);
   return results;
 }
 
@@ -119,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/scan/templates.js

@@ -18,7 +18,7 @@ function collectTailwindFindings(templateFiles, options) {
   const findings = [];
 
   for (const filePath of templateFiles) {
-    let source = '';
+    let source;
     try {
       source = fs.readFileSync(filePath, 'utf8');
     } catch {
@@ -64,7 +64,7 @@ function collectTailwindMotionFindings(templateFiles, options) {
   const findings = [];
 
   for (const filePath of templateFiles) {
-    let source = '';
+    let source;
     try {
       source = fs.readFileSync(filePath, 'utf8');
     } catch {
@@ -115,17 +115,51 @@ function buildTailwindMotionFindingText(token, analysis) {
   return `Unexpected Tailwind arbitrary motion duration "${token}". Use duration scale values.`;
 }
 
+/**
+ * Linear scan for string literals. A regex did this before, and from every
+ * quote that never closes (an apostrophe in a comment, a quote inside a regex
+ * literal) it backtracked to the end of the file; on a 3.5 MB minified editor
+ * bundle that took hours. This walks the source once: an escape never closes a
+ * literal, a ' or " literal that reaches a line break is not a literal (the
+ * language agrees), and a backtick literal may span lines.
+ */
 function findStringLiterals(source) {
   const literals = [];
-  const literalPattern = /(["'`])((?:\\[\s\S]|(?!\1)[\s\S])*?)\1/g;
-  let match;
-
-  while ((match = literalPattern.exec(source)) !== null) {
-    literals.push({
-      quote: match[1],
-      value: match[2],
-      valueStart: match.index + 1,
-    });
+  const { length } = source;
+  let index = 0;
+
+  while (index < length) {
+    const quote = source[index];
+    if (quote !== '"' && quote !== "'" && quote !== '`') {
+      index += 1;
+      continue;
+    }
+
+    const valueStart = index + 1;
+    let cursor = valueStart;
+    let closed = false;
+    while (cursor < length) {
+      const char = source[cursor];
+      if (char === '\\') {
+        cursor += 2;
+        continue;
+      }
+      if (char === quote) {
+        closed = true;
+        break;
+      }
+      if (quote !== '`' && char === '\n') {
+        break;
+      }
+      cursor += 1;
+    }
+
+    if (closed) {
+      literals.push({ quote, value: source.slice(valueStart, cursor), valueStart });
+      index = cursor + 1;
+    } else {
+      index = valueStart;
+    }
   }
 
   return literals;

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,