stylelint-plugin-rhythmguard 3.7.1 → 3.9.0

package/CHANGELOG.md

@@ -6,6 +6,51 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [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
+
+- `npm run bench:agents`, the agent eval harness: sixteen tasks over three fixture projects, each run as before (no linter), with findings (up to three correction rounds) and rules only (the control), through Sonnet 5, Haiku 4.5 and Opus 5; outcomes, rounds to zero and cost per condition in a dated edition under `docs/agent-evals/`. `--dry-run` exercises the whole pipeline against a scripted model. Method in `docs/AGENT_EVALS.md`. ([#135](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/135))
+- The browser playground runs the real rules. `docs/playground/rhythmguard.js` is an esbuild bundle of the shipped `use-scale`, `prefer-token`, `no-offscale-transform` and `use-motion-scale` with a small Stylelint shim; the page offers `scale: "auto"`, every preset, SCSS, and a fixed-CSS view. A contract test rebuilds the bundle and compares the page's sample against Stylelint, so the playground cannot drift from the plugin again. ([#57](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/57))
+- `use-scale` evaluates Sass expressions in `.scss` declarations: `padding: $spacer * .3` is reported as off scale with `Evaluates to 4.8px.` when `$spacer` resolves from the linted file, `scaleSources`, the config's token sources or an installed package; each term of `padding: $y $x` is checked on its own; `* / + -`, negation, parentheses and `math.div()` are understood. Unresolvable terms are left alone as before, and an expression is never rewritten by `--fix`. The audit inherits it, so SCSS design systems now see drift that hid behind a variable.
+- [`PetriLahdelma/rhythmguard-action`](https://github.com/PetriLahdelma/rhythmguard-action), a GitHub Action that runs the audit, annotates the diff, posts the report as one pull-request comment updated in place, and fails on new drift against a committed baseline. Linked from the README and the CI adoption recipe.
+- `rhythmguard`, the command as its own package: `npx rhythmguard` resolves a package of that name, and none existed, so the first command in the README failed in a project that had installed nothing (`npx stylelint-plugin-rhythmguard` worked, and the README says that until the package is published). `packages/rhythmguard` is one dependency and one line that runs the CLI, now exported as `stylelint-plugin-rhythmguard/cli` with a `main()`.
+- `eslint-plugin-rhythmguard`, the ESLint companion under its own package name, from `packages/eslint-plugin-rhythmguard`. It re-exports `stylelint-plugin-rhythmguard/eslint`, so the rules, options and messages are one implementation; it exists so a search for an ESLint Tailwind plugin finds it. Published by the release run once the package has a trusted publisher.
+
+### Changed
+
+- The post-publish smoke waits up to ten minutes for the registry to list the new version before deciding it is unpublished. It checked once, and the registry took three minutes to list 3.7.1, so the smoke skipped itself and had to be dispatched by hand.
+
 ## [3.7.1] - 2026-09-17
 
 ### Fixed

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
 
@@ -116,3 +121,11 @@ npm run bench:perf:fix
 ```
 
 Compares runtime against `stylelint-scales` on a deterministic corpus. Method in [`docs/BENCHMARKING.md`](./docs/BENCHMARKING.md).
+
+## The README recording
+
+`assets/quickstart.gif` is recorded with [vhs](https://github.com/charmbracelet/vhs) from `assets/quickstart.tape` on a shallow clone of Bootstrap `v6-dev` at `/tmp/bootstrap`. Re-record when the quickstart output changes: `git clone --depth 1 --branch v6-dev https://github.com/twbs/bootstrap.git /tmp/bootstrap && vhs assets/quickstart.tape`, then bump the `?v=` cache key on the image in `README.md`.
+
+## The browser playground
+
+`docs/index.html` runs the real rules through `docs/playground/rhythmguard.js`, an esbuild bundle of `src/` with a Stylelint shim and no-op Node shims (`scripts/playground/`). Rebuild it after any change under `src/` that the rules use: `npm run build:playground`, and commit the file. `test/contracts/playground.test.js` rebuilds the bundle and fails when the committed one is stale, and checks that the page's sample gets the same warnings from the bundle and from Stylelint.

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=11" 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,13 +7,13 @@
 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=371)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![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 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
 
@@ -21,7 +21,13 @@ What it is not: it does not check colors or hex values, and the Stylelint rules
 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. Then:
+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:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/quickstart.gif?v=1" width="100%" alt="Terminal recording: npx stylelint-plugin-rhythmguard on Bootstrap v6-dev detects the stack, infers the 13-step spacing scale from scss/_config.scss, reports 20 off-scale values in CSS and prints a .stylelintrc.json to paste" />
+</p>
+
+Then:
 
 ```bash
 npm install --save-dev stylelint stylelint-plugin-rhythmguard
@@ -41,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:
+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 [
   {
@@ -74,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
@@ -81,7 +93,7 @@ npx rhythmguard audit ./src --since-baseline --fail-on-new-drift
 npx rhythmguard audit ./src --format github
 ```
 
-The audit scans CSS declarations, Tailwind class strings and your token contract, prints a scale-cleanliness score, and supports baselines so legacy codebases can gate only new drift. Formats: text, Markdown, JSON 2.0, HTML, GitHub Actions annotations, and a shields.io badge document for your README. Full reference in [docs/AUDIT.md](docs/AUDIT.md), rollout recipe and the badge workflow in [docs/CI_ADOPTION.md](docs/CI_ADOPTION.md).
+The audit scans CSS declarations, Tailwind class strings and your token contract, prints a scale-cleanliness score, and supports baselines so legacy codebases can gate only new drift. Formats: text, Markdown, JSON 2.0, HTML, GitHub Actions annotations, and a shields.io badge document for your README. Full reference in [docs/AUDIT.md](docs/AUDIT.md), rollout recipe and the badge workflow in [docs/CI_ADOPTION.md](docs/CI_ADOPTION.md). In GitHub Actions, [`PetriLahdelma/rhythmguard-action@v1`](https://github.com/PetriLahdelma/rhythmguard-action) runs the audit, annotates the diff, comments on the pull request and fails on new drift in one step.
 
 `npx rhythmguard audit ./src --plan` turns the report into a proposed `decisions` section (adopt a value, allow it, or snap it), and `npx rhythmguard fix ./src --value 10px --to "var(--space-sm)" --write` executes one decision as one reviewable change; see [decisions](docs/AUDIT.md#decisions). `npx rhythmguard init` writes a starter config for your stack, and `init --agents all` installs the coding-agent instructions. `npx rhythmguard doctor` checks the setup.
 
@@ -95,13 +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. 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)
-- Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/), a simplified re-implementation for trying values in the browser; the real rules run under Node ([#57](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/57) tracks bundling them)
+- [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.7.1",
+  "version": "3.9.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"
@@ -62,6 +62,11 @@
       "require": "./src/audit/index.js",
       "import": "./src/audit/index.mjs"
     },
+    "./cli": {
+      "types": "./types/cli.d.ts",
+      "require": "./src/cli/index.js",
+      "import": "./src/cli/index.mjs"
+    },
     "./rules/use-scale": {
       "types": "./types/rule.d.ts",
       "require": "./src/rules/use-scale/index.js",
@@ -117,7 +122,9 @@
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "build:agents": "node scripts/build-agents.mjs",
     "bench:state-of-spacing": "node scripts/bench/state-of-spacing.mjs",
-    "bench:outreach": "node scripts/bench/outreach.mjs"
+    "bench:outreach": "node scripts/bench/outreach.mjs",
+    "build:playground": "node scripts/build-playground.mjs",
+    "bench:agents": "node scripts/bench/agents/run.mjs"
   },
   "repository": {
     "type": "git",
@@ -151,16 +158,18 @@
     "postcss-value-parser": "^4.2.0"
   },
   "devDependencies": {
-    "@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",
-    "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/config.js

@@ -45,7 +45,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)) {

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}% |`,

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}%`,
   ];

package/src/audit/report.js

@@ -89,6 +89,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,

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

@@ -77,7 +77,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 +95,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 +111,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;
 }
 

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/cli/index.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 'use strict';
 
-const command = process.argv[2];
-
 const HELP = `Usage: rhythmguard [command]
 
 With no command: zero-config quickstart. Detects your stack and tokens, infers
@@ -29,23 +27,34 @@ Examples:
   npx rhythmguard doctor
 `;
 
-if (command === '--help' || command === '-h') {
-  process.stdout.write(HELP);
-  process.exit(0);
+/** Dispatch on process.argv. The `rhythmguard` bin and the `rhythmguard` alias package both call this. */
+function main() {
+  const command = process.argv[2];
+
+  if (command === '--help' || command === '-h') {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+
+  if (!command || command === 'quickstart') {
+    require('./quickstart').run();
+  } else if (command === 'audit') {
+    require('./audit').run();
+  } else if (command === 'fix') {
+    require('./fix').run();
+  } else if (command === 'init') {
+    require('./init').run();
+  } else if (command === 'doctor') {
+    require('./doctor');
+  } else {
+    process.stderr.write(`Unknown command: ${command}\n\n`);
+    process.stdout.write(HELP);
+    process.exit(1);
+  }
 }
 
-if (!command || command === 'quickstart') {
-  require('./quickstart').run();
-} else if (command === 'audit') {
-  require('./audit').run();
-} else if (command === 'fix') {
-  require('./fix').run();
-} else if (command === 'init') {
-  require('./init').run();
-} else if (command === 'doctor') {
-  require('./doctor');
-} else {
-  process.stderr.write(`Unknown command: ${command}\n\n`);
-  process.stdout.write(HELP);
-  process.exit(1);
+module.exports = { HELP, main };
+
+if (require.main === module) {
+  main();
 }

package/src/cli/index.mjs

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cli = require('./index.js');
+
+export default cli;
+export const HELP = cli.HELP;
+export const main = cli.main;

package/src/configs/embed.js

@@ -7,8 +7,8 @@
  * spacing tokens (scaleSources, .rhythmguardrc.json token sources, the
  * stylesheet's custom properties, a Tailwind config, then rhythmic-4).
  * No `extends`, no dependency beyond this plugin, and the shape is frozen for
- * the life of the 2.x line so a config that embeds it never changes behaviour
- * on a minor bump.
+ * the life of a major version so a config that embeds it never changes
+ * behaviour on a minor bump.
  */
 module.exports = {
   plugins: ['stylelint-plugin-rhythmguard'],

package/src/core/scale-inference.js

@@ -201,12 +201,16 @@ function scaleFromSources(sources, baseFontSize) {
  * `.rhythmguardrc.json` token sources and installed token packages. The same
  * places scale inference reads, in the same order.
  */
-function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenRegex }) {
+function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenPattern = null, tokenRegex }) {
   const definitions = root ? stylesheetDefinitions(root, tokenRegex, baseFontSize) : new Map();
   const sources = [...scaleSources, ...rcTokenSources(process.cwd()), ...discoverTokenPackages(process.cwd())];
-  const parsed = parseSourcesCached(sources, baseFontSize);
-  if (parsed) {
-    for (const [token, definition] of parsed.definitions) {
+  // A rule's own tokenPattern (`^--space-|^--radius-`) also applies to the
+  // files it reads, on top of the spacing names, unless a source sets its own.
+  const withPattern = tokenPattern
+    ? sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source }))
+    : [];
+  for (const parsed of [parseSourcesCached(sources, baseFontSize), parseSourcesCached(withPattern, baseFontSize)]) {
+    for (const [token, definition] of parsed ? parsed.definitions : []) {
       if (!definitions.has(token)) {
         definitions.set(token, definition);
       }

package/src/core/token-index.js

@@ -1,7 +1,45 @@
 'use strict';
 
+const { PROPERTY_GROUP_PATTERNS } = require('./css-vocabulary');
 const { fixedLengthValue, numbersEqual, toPx } = require('./length');
-const { parseTokenValueLength } = require('./token-sources');
+const { createTokenKindMatcher, parseTokenValueLength } = require('./token-sources');
+
+// Dedicated kinds first: a name like --radius-space-1 is a radius token.
+const TOKEN_KINDS = ['radius', 'typography', 'motion', 'size', 'spacing'].map((kind) => [kind, createTokenKindMatcher(kind)]);
+
+// Which token kinds may stand in for a property of each group. Spacing and size
+// share tokens in many systems (Open Props --size-*, mittwald --size-px--*);
+// radius, type and motion tokens serve only their own properties.
+const ACCEPTED_KINDS = Object.freeze({
+  motion: ['motion'],
+  radius: ['radius'],
+  size: ['size', 'spacing'],
+  spacing: ['spacing', 'size'],
+  typography: ['typography'],
+});
+
+/** The kind a token's name declares, or null when the name says nothing. */
+function tokenKindOf(token) {
+  const found = TOKEN_KINDS.find(([, matches]) => matches(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 kind = group ? tokenKindOf(String(token).replace(/^var\(\s*|\s*\)$/g, '')) : null;
+  return !group || !kind || ACCEPTED_KINDS[group].includes(kind);
+}
 
 /**
  * Which token a fix may write for a length. Strict on purpose: the token must
@@ -19,24 +57,37 @@ function tokenIndexFromDefinitions(definitions, baseFontSize = 16) {
       const unit = parsed.unit || 'px';
       const px = toPx(Math.abs(parsed.number), unit, baseFontSize);
       if (px === null || !Number.isFinite(px) || px === 0) continue;
-      index.push({ px, raw: String(raw).trim(), token: definition.token, unit });
+      const file = definition.files ? [...definition.files][0] : null;
+      index.push({ file: file && file !== 'stylesheet' ? file : null, px, raw: String(raw).trim(), token: definition.token, unit });
     }
   }
   return index;
 }
 
-function tokenForLength(index, px, unit) {
+/**
+ * Every custom property that holds a length, for one property. The shared
+ * resolver behind use-scale's `fixWith: "token"` and prefer-token, so the two
+ * rules always know the same tokens. Same unit first; with `anyUnit`, a token
+ * in another unit that holds the same px value counts when none matches the
+ * unit. Sorted, so messages are stable.
+ */
+function tokensForLength(index, px, unit, { anyUnit = false, prop = null } = {}) {
   const wanted = unit || 'px';
-  const candidates = new Set();
+  const sameUnit = new Set();
+  const otherUnit = new Set();
   for (const entry of index) {
-    if (entry.token.startsWith('--') && entry.unit === wanted && numbersEqual(entry.px, Math.abs(px))) {
-      candidates.add(entry.token);
+    if (!entry.token.startsWith('--') || !numbersEqual(entry.px, Math.abs(px)) || !tokenFitsProperty(entry.token, prop)) {
+      continue;
     }
+    (entry.unit === wanted ? sameUnit : otherUnit).add(entry.token);
   }
-  if (candidates.size !== 1) {
-    return null;
-  }
-  return `var(${[...candidates][0]})`;
+  const found = sameUnit.size > 0 || !anyUnit ? sameUnit : otherUnit;
+  return [...found].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+}
+
+function tokenForLength(index, px, unit, prop = null) {
+  const candidates = tokensForLength(index, px, unit, { prop });
+  return candidates.length === 1 ? `var(${candidates[0]})` : null;
 }
 
 /** A negative token reference that is still valid where it is written. */
@@ -54,9 +105,9 @@ function negateReplacement(replacement) {
  * The replacement text a length rule writes: the matching token when the
  * options ask for one and exactly one qualifies, otherwise the literal.
  */
-function replacementFor(parsedLength, nearestPx, options) {
+function replacementFor(parsedLength, nearestPx, options, prop = null) {
   if (options.fixWith === 'token' && options.tokenIndex) {
-    const token = tokenForLength(options.tokenIndex, nearestPx, parsedLength.unit || 'px');
+    const token = tokenForLength(options.tokenIndex, nearestPx, parsedLength.unit || 'px', prop);
     if (token) {
       return parsedLength.number < 0 ? negateReplacement(token) : token;
     }
@@ -76,7 +127,10 @@ function tokenHoldsNote(replacement, formattedNearest) {
 module.exports = {
   negateReplacement,
   replacementFor,
+  tokenFitsProperty,
   tokenHoldsNote,
   tokenForLength,
   tokenIndexFromDefinitions,
+  tokenKindOf,
+  tokensForLength,
 };

package/src/core/token-packages.json

@@ -86,6 +86,13 @@
         "dist/nhsuk/core/settings/_spacing.scss"
       ],
       "note": "$nhsuk-spacing-points map"
+    },
+    {
+      "name": "@mozilla-protocol/tokens",
+      "files": [
+        "dist/units/units.custom-properties.css"
+      ],
+      "note": "--spacing-xs..2xl in px; Protocol's Sass $spacing-* come from the same package"
     }
   ]
 }

package/src/core/token-sources.js

@@ -123,7 +123,7 @@ function parseTokenSources({
       continue;
     }
 
-    let tokens = [];
+    let tokens;
     const matchesSource = normalizedSource.tokenPattern
       ? createPatternMatcher(normalizedSource.tokenPattern, matchesKind)
       : matchesKind;
@@ -413,6 +413,36 @@ function collectScssTokens(source, matchesKind) {
   return tokens;
 }
 
+/**
+ * A variable resolver over a Sass source text, for evaluating declaration
+ * values: same-file declarations first, then `fallback(name)` for a length
+ * declared elsewhere (a scaleSources file, an installed package).
+ */
+function createScssVariableResolver(source, fallback = () => null) {
+  const declarations = parseScssDeclarations(source || '');
+  const cache = new Map();
+  const resolveVariable = (name, stack) => {
+    if (cache.has(name)) {
+      return cache.get(name);
+    }
+    if (stack.has(name)) {
+      return null;
+    }
+    let value;
+    if (declarations.has(name)) {
+      stack.add(name);
+      const raw = declarations.get(name);
+      value = isScssMap(raw) ? null : evaluateScssExpression(raw, resolveVariable, stack);
+      stack.delete(name);
+    } else {
+      value = fallback(name);
+    }
+    cache.set(name, value);
+    return value;
+  };
+  return resolveVariable;
+}
+
 /** `$<namespace>-spacing-points`, `$<ns>-space-scale`: one namespace segment before the anchor. */
 const NAMESPACED_SPACING_MAP = /^\$[a-z0-9]+-(?:space|spacing|spacer)s?(?:-|$)/i;
 const MIN_NAMESPACED_MAP_LENGTHS = 4;
@@ -587,20 +617,19 @@ function tokenizeScssExpression(expression) {
       }
       return null;
     }
+    const start = index + (match[0].length - match[0].trimStart().length);
     index = SCSS_TOKEN_PATTERN.lastIndex;
-    if (match[1] !== undefined) tokens.push({ type: 'number', raw: match[1] });
-    else if (match[2] !== undefined) tokens.push({ type: 'var', name: match[2].slice(1) });
-    else if (match[3] !== undefined) tokens.push({ type: 'call', name: match[3] });
-    else tokens.push({ type: 'op', value: match[4] });
+    const span = { end: index, start };
+    if (match[1] !== undefined) tokens.push({ type: 'number', raw: match[1], ...span });
+    else if (match[2] !== undefined) tokens.push({ type: 'var', name: match[2].slice(1), ...span });
+    else if (match[3] !== undefined) tokens.push({ type: 'call', name: match[3], ...span });
+    else tokens.push({ type: 'op', value: match[4], ...span });
   }
   return tokens;
 }
 
-function evaluateScssExpression(expression, resolveVariable, stack) {
-  const tokens = tokenizeScssExpression(expression.trim());
-  if (!tokens || tokens.length === 0) {
-    return null;
-  }
+/** A recursive-descent parser over Sass expression tokens; `parseExpression` consumes one arithmetic expression. */
+function createScssParser(tokens, resolveVariable, stack) {
   let position = 0;
   const peek = () => tokens[position];
   const next = () => tokens[position++];
@@ -687,8 +716,46 @@ function evaluateScssExpression(expression, resolveVariable, stack) {
     return value;
   };
 
-  const result = parseExpression();
-  return position === tokens.length ? result : null;
+  return {
+    get position() { return position; },
+    parseExpression,
+  };
+}
+
+function evaluateScssExpression(expression, resolveVariable, stack) {
+  const tokens = tokenizeScssExpression(expression.trim());
+  if (!tokens || tokens.length === 0) {
+    return null;
+  }
+  const parser = createScssParser(tokens, resolveVariable, stack);
+  const result = parser.parseExpression();
+  return parser.position === tokens.length ? result : null;
+}
+
+/**
+ * A space-separated Sass value (`$spacer * .3 $spacer`) as its evaluated terms,
+ * each with the source text it came from, or null when any term cannot be
+ * evaluated (an unknown variable, a keyword, a function the evaluator does not
+ * know). A `-` between terms is read as subtraction, as Sass does.
+ */
+function evaluateScssValueList(value, resolveVariable, stack) {
+  const tokens = tokenizeScssExpression(value);
+  if (!tokens || tokens.length === 0) {
+    return null;
+  }
+  const parser = createScssParser(tokens, resolveVariable, stack);
+  const terms = [];
+  while (parser.position < tokens.length) {
+    const startToken = tokens[parser.position];
+    const before = parser.position;
+    const result = parser.parseExpression();
+    if (!result || parser.position === before) {
+      return null;
+    }
+    const endToken = tokens[parser.position - 1];
+    terms.push({ ...result, end: endToken.end, start: startToken.start, text: value.slice(startToken.start, endToken.end) });
+  }
+  return terms;
 }
 
 function formatScssValue(value) {
@@ -905,6 +972,8 @@ function formatPath(filePath) {
 }
 
 module.exports = {
+  createScssVariableResolver,
+  evaluateScssValueList,
   VALID_TOKEN_KINDS,
   VALID_TOKEN_SOURCE_FORMATS,
   addDefinition,

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

@@ -69,7 +69,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     withResolvedScale(options, root);
     if (options.fixWith === 'token') {
       options.tokenIndex = tokenIndexFromDefinitions(
-        collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex: new RegExp(options.tokenPattern) }),
+        collectTokenDefinitions({
+          baseFontSize: options.baseFontSize,
+          root,
+          scaleSources: options.scaleSources,
+          tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+          tokenRegex: new RegExp(options.tokenPattern),
+        }),
         options.baseFontSize,
       );
     }
@@ -157,7 +163,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
 
           const fixedValue = options.fixToScale
-            ? replacementFor(parsedLength, nearest.nearest, options)
+            ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
             : null;
 
           report(node, nearest, unit, fixedValue);
@@ -181,7 +187,7 @@ const ruleFunction = (primary, secondaryOptions) => {
         }
 
         const fixedValue = options.fixToScale
-          ? replacementFor(parsedLength, nearest.nearest, options)
+          ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
           : null;
 
         report(node, nearest, 'px', fixedValue);

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

@@ -25,25 +25,40 @@ const {
 const { buildEffectiveTokenMap } = require('../../core/token-map');
 
 const {
+  collectTokenDefinitions,
   withResolvedScale,
 } = require('../../core/scale-inference');
 
 const { createTokenRegex, reportInvalidPreset, reportValueNode } = require('../report');
 const { validatePrimary, validatePreferTokenSecondaryOptions } = require('../validate');
 
-const { negateReplacement } = require('../../core/token-index');
+const {
+  negateReplacement,
+  tokenFitsProperty,
+  tokenIndexFromDefinitions,
+  tokensForLength,
+} = require('../../core/token-index');
 
 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 = '') =>
+  rejected: (value, replacement = null, origin = null, note = '', candidates = []) =>
     `Unexpected raw scale value "${value}". ${replacement
       ? `Use ${replacement}${origin ? ` (${origin})` : ''}.`
-      : 'No known token holds this value; use the nearest token or add one.'}${note ? ` ${note}` : ''}`,
+      : candidates.length > 1
+        ? `Use one of the tokens that hold it: ${listTokens(candidates)}.`
+        : 'No known token holds this value; use the nearest token or add one.'}${note ? ` ${note}` : ''}`,
 });
 
+function listTokens(tokens) {
+  const references = tokens.map((token) => `var(${token})`);
+  return references.length > 1
+    ? `${references.slice(0, -1).join(', ')} or ${references[references.length - 1]}`
+    : references.join('');
+}
+
 function applyNegativeToken(replacement, parsedLength) {
   return !replacement || parsedLength.number >= 0 ? replacement : negateReplacement(replacement);
 }
@@ -74,6 +89,36 @@ function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {
   return null;
 }
 
+/**
+ * The tokens use-scale's `fixWith: "token"` would see: the stylesheet,
+ * `scaleSources`, `.rhythmguardrc.json` token sources and installed token
+ * packages, filtered to the property's kind. One same-unit token is a fix; a
+ * token in another unit, or several tokens, are named but never written.
+ */
+function resolveFromIndex(tokenIndex, parsedLength, prop, options) {
+  const px = toPx(Math.abs(parsedLength.number), parsedLength.unit || 'px', options.baseFontSize);
+  if (px === null || tokenIndex.length === 0) {
+    return { candidates: [] };
+  }
+  const unit = parsedLength.unit || 'px';
+  const sameUnit = tokensForLength(tokenIndex, px, unit, { prop });
+  const candidates = sameUnit.length > 0 || options.unitStrategy !== 'convert'
+    ? sameUnit
+    : tokensForLength(tokenIndex, px, unit, { anyUnit: true, prop });
+  if (candidates.length !== 1) {
+    return { candidates };
+  }
+  const token = `var(${candidates[0]})`;
+  const entry = tokenIndex.find((item) => item.token === candidates[0]);
+  return {
+    candidates,
+    fixable: sameUnit.length === 1,
+    origin: entry ? entry.file : null,
+    replacement: applyNegativeToken(token, parsedLength),
+    token,
+  };
+}
+
 const ruleFunction = (primary, secondaryOptions) => {
   return (root, result) => {
     const valid = validatePrimary(result, ruleName, primary);
@@ -105,6 +150,17 @@ const ruleFunction = (primary, secondaryOptions) => {
       tokenRegex,
     });
 
+    const tokenIndex = tokenIndexFromDefinitions(
+      collectTokenDefinitions({
+        baseFontSize: options.baseFontSize,
+        root,
+        scaleSources: options.scaleSources,
+        tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+        tokenRegex,
+      }),
+      options.baseFontSize,
+    );
+
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
     root.walkDecls((decl) => {
@@ -121,10 +177,23 @@ const ruleFunction = (primary, secondaryOptions) => {
       const { scaleByUnit, scalePx } = getScaleStateForProperty(prop);
       let changed = false;
 
-      const reportNode = (node, resolved = null) => {
-        const replacement = resolved ? resolved.replacement : null;
-        const origin = resolved ? origins[resolved.token] || null : null;
-        reportValueNode({ decl, message: messages.rejected(node.value, replacement, origin, options.note), node, replacement, result, ruleName });
+      const reportNode = (node, parsedLength) => {
+        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 });
+          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),
+          node,
+          replacement: indexed.fixable ? named : null,
+          result,
+          ruleName,
+        });
       };
 
       const checkWordNode = (node, context) => {
@@ -190,7 +259,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
         }
 
-        reportNode(node, resolveTokenReplacement(tokenMap, node.value, parsedLength, options));
+        reportNode(node, parsedLength);
         return true;
       };
 

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

@@ -29,6 +29,7 @@ const {
   collectTokenDefinitions,
   withResolvedScale,
 } = require('../../core/scale-inference');
+const { createScssVariableResolver, evaluateScssValueList } = require('../../core/token-sources');
 
 const { createTokenRegex, reportInvalidPreset, reportProblem, reportValueNode } = require('../report');
 const { decisionFor, loadRcDecisions } = require('../../core/decisions');
@@ -59,13 +60,17 @@ function readDecisions(options, { result, root }) {
 
 function checkLengthValue({
   decl,
+  evaluated = null,
+  fixable = true,
   node,
   options,
   report,
   scaleByUnit,
   scalePx,
 }) {
-  const parsedLength = parseLengthToken(node.value);
+  // `evaluated` is a length that came from a Sass expression; the node's text is
+  // the expression, which is reported but never rewritten.
+  const parsedLength = evaluated || parseLengthToken(node.value);
 
   if (!parsedLength) {
     return false;
@@ -130,11 +135,11 @@ function checkLengthValue({
       return false;
     }
 
-    const fixedValue = options.fixToScale
-      ? replacementFor(parsedLength, nearest.nearest, options)
+    const fixedValue = options.fixToScale && fixable
+      ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
       : null;
 
-    report(node.value, decl, node, nearest, fixedValue, unit);
+    report(node.value, decl, node, nearest, fixedValue, unit, evaluated ? evaluatedNote(evaluated, options) : '');
     return true;
   }
 
@@ -154,11 +159,58 @@ function checkLengthValue({
     return false;
   }
 
-  const fixedValue = options.fixToScale
-    ? replacementFor(parsedLength, nearest.nearest, options)
+  const fixedValue = options.fixToScale && fixable
+    ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
     : null;
 
-  report(node.value, decl, node, nearest, fixedValue, 'px');
+  report(node.value, decl, node, nearest, fixedValue, 'px', evaluated ? evaluatedNote(evaluated, options) : '');
+  return true;
+}
+
+/** What a Sass expression came to, so the reader sees the number the scale was checked against. */
+function evaluatedNote(evaluated, options) {
+  const px = toPx(evaluated.number, evaluated.unit, options.baseFontSize);
+  return px === null ? '' : `Evaluates to ${formatLength(px, 'px')}.`;
+}
+
+/**
+ * Sass values (`$spacer * .3`, `math.div($spacer, 2)`, `$y $x`) are evaluated
+ * with the file's own variables first and the project's spacing tokens second,
+ * and each term is checked like a literal. Terms that do not resolve are left
+ * alone, as they always were.
+ */
+function checkSassValue({ decl, options, report, resolveVariable, scaleByUnit, scalePx }) {
+  const terms = evaluateScssValueList(decl.value, resolveVariable, new Set());
+  if (!terms) {
+    // Not fully evaluable (an unknown variable, interpolation, a keyword): the
+    // literal walk below still checks the plain lengths in the value.
+    return false;
+  }
+  // Right to left, so a fix spliced into an earlier term never shifts the spans
+  // of the terms still to be checked. Stylelint orders the warnings by position.
+  for (const term of [...terms].reverse()) {
+    if (!term.unit || term.number === 0) {
+      continue;
+    }
+    const node = {
+      sourceIndex: term.start,
+      type: 'word',
+      get value() { return term.text; },
+      // The fix writes into the declaration at the term's span.
+      set value(replacement) { decl.value = `${decl.value.slice(0, term.start)}${replacement}${decl.value.slice(term.end)}`; },
+    };
+    checkLengthValue({
+      decl,
+      evaluated: { number: term.number, unit: term.unit },
+      // A term that is a plain literal keeps its autofix; an expression is only reported.
+      fixable: parseLengthToken(term.text) !== null,
+      node,
+      options,
+      report,
+      scaleByUnit,
+      scalePx,
+    });
+  }
   return true;
 }
 
@@ -187,7 +239,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     if (options.fixWith === 'token') {
       options.tokenIndex = tokenIndexFromDefinitions(
-        collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex }),
+        collectTokenDefinitions({
+          baseFontSize: options.baseFontSize,
+          root,
+          scaleSources: options.scaleSources,
+          tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+          tokenRegex,
+        }),
         options.baseFontSize,
       );
     }
@@ -195,13 +253,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     let fallbackNote = autoScaleFallbackNote(options.scaleInference);
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
-    const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px') => {
+    const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px', extraNote = '') => {
       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, options.note].filter(Boolean).join(' ')),
+        message: messages.rejected(value, lower, upper, [fallbackNote, tokenNote, extraNote, options.note].filter(Boolean).join(' ')),
         node,
         replacement: fixedValue,
         result,
@@ -210,9 +268,24 @@ const ruleFunction = (primary, secondaryOptions) => {
       fallbackNote = '';
     };
 
+    // Built on the first Sass value seen, so plain CSS pays nothing.
+    let resolveSassVariable = null;
+    const sassResolver = () => {
+      if (!resolveSassVariable) {
+        const definitions = collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex });
+        resolveSassVariable = createScssVariableResolver(root.source && root.source.input ? root.source.input.css : '', (name) => {
+          const definition = definitions.get(`$${name}`);
+          const first = definition ? [...definition.values][0] : null;
+          const parsed = first ? parseLengthToken(String(first).trim()) : null;
+          return parsed && parsed.unit ? { number: parsed.number, unit: parsed.unit } : null;
+        });
+      }
+      return resolveSassVariable;
+    };
+
     root.walkDecls((decl) => {
       const prop = decl.prop.toLowerCase();
-      if (prop.startsWith('--')) {
+      if (prop.startsWith('--') || prop.startsWith('$')) {
         return;
       }
 
@@ -221,6 +294,11 @@ const ruleFunction = (primary, secondaryOptions) => {
       }
 
       const { scaleByUnit, scalePx } = getScaleStateForProperty(prop);
+
+      if (decl.value.includes('$') && checkSassValue({ decl, options, report, resolveVariable: sassResolver(), scaleByUnit, scalePx })) {
+        return;
+      }
+
       const parsed = valueParser(decl.value);
       let changed = false;
 

package/types/audit.d.ts

@@ -68,6 +68,8 @@ export interface AuditScanned {
   scssFiles?: number;
   /** .scss files found but not audited because postcss-scss is not installed. */
   scssSkipped?: number;
+  /** Stylesheets Stylelint skipped because the project's own .stylelintignore excludes them. */
+  stylelintIgnored?: number;
   templateFiles: number;
   totalFiles?: number;
   [key: string]: unknown;

package/types/cli.d.ts

@@ -0,0 +1,9 @@
+/** The usage text printed by `rhythmguard --help`. */
+export const HELP: string;
+
+/** Run the rhythmguard CLI against `process.argv`. Exits the process on completion or error. */
+export function main(): void;
+
+declare const cli: { HELP: string; main: typeof main };
+
+export default cli;