stylelint-plugin-rhythmguard 2.1.0 → 3.0.0

package/CHANGELOG.md

@@ -6,6 +6,55 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-09-06
+
+Upgrade notes: [`docs/MIGRATING_TO_3.md`](./docs/MIGRATING_TO_3.md).
+
+### Breaking
+
+- Node 20.19 or newer is required. Node 18 support is removed.
+- `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peer dependencies instead of dependencies. Install `stylelint-config-tailwindcss` yourself if you extend `configs/tailwind`. The package now has one runtime dependency, `known-css-properties`.
+- Removed configs `expanded`, `logical`, `migration` and `react-tailwind`. Their rule blocks are reproduced in the migration guide. `plugin.configs` has five keys: `embed`, `motion`, `recommended`, `strict`, `tailwind`.
+- `rhythmguard init` writes the `tailwind` config plus Next.js build ignores for Next.js projects instead of `react-tailwind`.
+
+### Removed
+
+- Campaign media, slide images, outreach drafts and old planning documents are no longer in the repository. The README banner and the cover image referenced by a published article remain.
+
+### Added
+
+- The audit now scans `.scss` files through `postcss-scss` (new optional peer dependency). Without it, SCSS files are reported as skipped instead of ignored. `scanned.scssFiles` and `scanned.scssSkipped` join the JSON contract; text and Markdown output show the counts.
+- Quiet benchmark widened from 7 to 20 public repositories, adding SCSS-first systems: Bootstrap, Primer CSS, Penpot, Mastodon, Gutenberg components, GitLab UI, Pico, Bulma, Spectrum CSS, USWDS, Carbon, Salesforce Lightning, wp-calypso components.
+
+- `scale: "auto"` now reads spacing tokens shipped by installed design-token packages when the project's own stylesheets define none: `tailwindcss` (v4 `theme.css`), `@radix-ui/themes`, `@mantine/core`, `@primer/primitives`, `@shopify/polaris-tokens`, `@spectrum-css/tokens`. Provenance is `token-package`. Token-source entries accept a per-file `tokenPattern` for packages that name spacing differently. The allowlist is `src/utils/token-packages.json`.
+- Sass variables and maps are token sources for `--scale auto`, for `scaleSources` files, and for `scale: "auto"` inside the rules when the linted `.scss` file declares them (with `postcss-scss`): `$spacer: 1rem`, `$spacing-01: 0.125rem`, and maps such as `$spacers: (1: $spacer * .25, ...)` with nested maps, variable references, `* / + -` arithmetic and `math.div()`. Unevaluable function calls, strings, keywords and interpolated keys are skipped. Bootstrap, Bulma, Carbon and USWDS now infer their own scales in the quiet benchmark.
+
+### Changed
+
+- New README banner.
+- Contributing: rewritten `CONTRIBUTING.md` with ways to contribute and the local gate, a Contributor Covenant code of conduct, a false-positive issue template, a current security policy, and a GitHub-hosted CI job so pull requests from forks get lint, typecheck and test feedback.
+
+## [2.2.0] - 2026-09-05
+
+### Added
+
+- Added `scale: "auto"` to `rhythmguard/use-scale`, `rhythmguard/no-offscale-transform` and `rhythmguard/prefer-token`. The scale is inferred from spacing tokens: `scaleSources` files, then `.rhythmguardrc.json` audit token sources, then the linted stylesheet's custom properties, then `tailwindConfigPath`, with a `rhythmic-4` fallback that is announced in the first report of the file. First matching source wins.
+- Added the `scaleSources` rule option and made `tailwindConfigPath` available to every scale rule.
+- Added `rhythmguard audit --scale auto`, which infers one project-level scale from token sources, then spacing custom properties across the scanned CSS, then the default. The JSON contract now carries `contracts.scale.values`, `source` and `files`; text and Markdown output print the scale and its source.
+- Added the quiet benchmark (`npm run bench:quiet`): audits public design systems with `--scale auto`, classifies findings as drift, noise or allowance, and writes `docs/QUIET_BENCHMARK.md` with a per-repo false-positive rate. Manifest and classification rules live in `benchmarks/quiet/`.
+- Scale inference now reads token values written as `calc(<length> * var(--factor))` (Radix Themes), expands a bare Tailwind v4 `--spacing` base into the default multiplier scale, and matches prefixed spacing tokens such as `--lb-spacing-md` while excluding `letter-spacing` and `word-spacing`.
+
+- Added `docs/FOR_AGENTS.md` with a paste-ready `AGENTS.md` block and the commands a coding agent should run, and a "what it is not" paragraph at the top of the README (no color checking, class strings need the ESLint companion, no SCSS in the audit).
+- The quiet benchmark now pins each repository to a recorded commit and keeps snapshots of its findings under `benchmarks/quiet/snapshots/`. `npm run bench:quiet -- --check` fails when the finding set or the inferred scale changes, `--update-snapshots` accepts a reviewed change, `--latest` audits upstream heads. A farm workflow runs the check on every change and the upstream run weekly.
+- `npx rhythmguard` with no command now runs a zero-config quickstart: detects Tailwind (and its major version), Next.js, an existing Stylelint config and token files; infers the spacing scale from the project's own tokens; audits the current directory; and prints the exact `.stylelintrc.json` (plus an ESLint snippet for Tailwind) to paste. `--help` is unchanged; `rhythmguard quickstart` is an explicit alias.
+- Added `stylelint-plugin-rhythmguard/configs/embed`: `use-scale` at warning level with `scale: "auto"`, no `extends`, shape frozen for 2.x. The entry point for shared-config authors who want to enable spacing governance for their consumers without knowing each consumer's scale. Guide in `docs/FOR_CONFIG_AUTHORS.md`.
+- Added `allowHairlines` (default `true`) to `use-scale`, `no-offscale-transform` and `prefer-token`. Non-zero lengths that resolve to one CSS pixel or less (`1px`, `-1px`, `0.5px`, `0.0625rem`) are exempt: they compensate for borders and rendering, not spacing. The quiet benchmark showed them to be the only systematic false positive left across Radix Themes, Mantine, Primer React and Liveblocks. Set `allowHairlines: false` to restore the previous reports.
+
+### Fixed
+
+- `rhythmguard/prefer-token` no longer reports percentages such as `translate(-50%, -50%)` or `inset: 100%` as raw scale values. Percentages are never token candidates. This was the largest noise source in the quiet benchmark.
+- `rhythmguard/use-scale` with `allowPercentages: false` now reports percentage lengths instead of silently skipping them.
+
 ## [2.1.0] - 2026-09-05
 
 ### Added

package/CONTRIBUTING.md

@@ -1,83 +1,99 @@
-# Contributing
+# Contributing to Rhythmguard
 
-Thanks for contributing to `stylelint-plugin-rhythmguard`.
+Thank you for being here. Rhythmguard is a small, opinionated tool with one job: keep spacing on a scale. Most of the useful work on it is small too, and a first contribution can land in an afternoon. This page tells you where the useful work is, how the checks run, and what to expect from review.
 
-## Development Setup
+## Ways to contribute
 
-```bash
-npm ci
-npm run lint
-npm test
-```
+**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.
+
+**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.
+
+**Teach inference a new token source.** Sass variables and maps, token packages, framework theme files. If your scale lives somewhere the tool cannot see, the fix is a parser in `src/utils/token-sources.js` and a test.
 
-Optional checks:
+**Improve a rule page.** Every rule has a page under `docs/rules/`. A clearer example or a missing edge case is a welcome PR.
+
+**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).
+
+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
 
 ```bash
-npm run test:compat-floor
-npm run test:coverage
-npm run test:pack-smoke
-npm run scales:validate
+git clone https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard.git
+cd stylelint-plugin-rhythmguard
+npm ci
+npm test
 ```
 
-## Community Scale Contributions
+Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` and take about five seconds.
 
-Rhythmguard accepts community presets through JSON files in `scales/community`.
+## The local gate
 
-Create a new scale file:
+Run these before you push. They are what CI runs, so a green local run means a green PR.
 
 ```bash
-npm run scales:add -- --name my-team-scale --base 8 --steps 0,4,8,12,16,24,32
+npm run lint        # eslint
+npm run typecheck   # the published TypeScript declarations against a consumer file and the examples
+npm test            # 150+ tests, Stylelint 16
 ```
 
-Then validate:
+Optional, depending on what you touched:
 
 ```bash
-npm run scales:validate
+npm run test:compat-floor      # Stylelint 16.0.0, the oldest supported
+npm run test:pack-smoke        # pack the tarball and install it in a temp project
+npm run scales:validate        # community scale JSON
+npm run bench:quiet -- --check # findings on the benchmark repos must match snapshots
 ```
 
-Scale files must pass schema and collision checks. See [`docs/COMMUNITY_SCALES.md`](./docs/COMMUNITY_SCALES.md) for the full spec and policy.
+If your shell's npm registry is overridden by a corporate `.npmrc`, add `--registry https://registry.npmjs.org` to `npm ci` and prefix `test:pack-smoke` with `npm_config_registry=https://registry.npmjs.org`.
 
-## Compatibility Targets
+### Pull requests from forks
 
-- Stylelint `^16.0.0 || ^17.0.0`. Stylelint `16.0.0` has known autofix and API differences; CI runs the floor-compat suite against it and the full suite non-blocking.
-- Node `>=18.18.0` for Stylelint 16, `>=20.19.0` for Stylelint 17. The CI matrix excludes Node 18 with Stylelint 17.
-- Dual CommonJS and ESM entry points; every export has a declaration under `types/`. `npm run typecheck` compiles the declarations, a consumer check file, and the examples.
+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.
 
-## Performance Benchmarking
+## How we write changes
 
-```bash
-npm run bench:perf
-npm run bench:perf:fix
-```
+**Tests first.** Every behaviour change starts with a failing test. If you send a fix without one, expect the review to ask for it; the test is what proves the fix is the right one and keeps it that way.
+
+**Rules explain their defaults.** A new default, or a change to one, needs a written reason on the rule's page under `docs/rules/` and, where the benchmark can show it, a number. The hairline section in [`docs/rules/use-scale.md`](./docs/rules/use-scale.md#hairlines) is the model.
+
+**The benchmark is the regression suite for real code.** If your change alters findings on any benchmark repository, `npm run bench:quiet -- --check` fails and prints the diff. Review it. If the new findings are right, run `npm run bench:quiet -- --update-snapshots`, commit `benchmarks/quiet/snapshots/`, and say in the PR why they are right.
+
+**Fixes are deterministic.** Autofix snaps to the nearest scale step or to an explicit token map. It never guesses a token. Keep that property.
 
-Compares runtime against `stylelint-scales` on a deterministic corpus. Method and arguments: [`docs/BENCHMARKING.md`](./docs/BENCHMARKING.md).
+**Prose without em dashes.** House style, applied to docs and messages alike.
 
-## Semver Rules
+## Semver
 
-- Patch (`x.y.Z`): bug fixes, docs updates, non-breaking internal changes.
-- Minor (`x.Y.z`): backward-compatible new options, presets, or behavior.
-- Major (`X.y.z`): any breaking behavior change for existing rules/configs.
+- Patch: bug fixes, docs, internal changes.
+- Minor: new options, presets, sources, or behaviour that does not change existing reports.
+- Major: any change to default reports for existing configs, to autofix behaviour, or to exported entry points.
 
-Breaking examples:
+`configs/recommended`, `configs/strict`, `configs/tailwind` and `configs/embed` stay stable within a major. The `embed` config's shape is frozen for 2.x because shared configs depend on it.
 
-- changing default scale behavior
-- changing autofix behavior in a non-compatible way
-- changing/removing exported config entry points
+## Compatibility
 
-## Rule Change Requirements
+- 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`.
+- CommonJS and ESM entry points; every export has a declaration under `types/`.
+- One runtime dependency, `known-css-properties`. `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers and dev dependencies here.
 
-When changing rule logic:
+## Review
 
-1. add/adjust tests for the behavior
-2. validate deterministic fix behavior
-3. update the rule's page in `docs/rules/` if options or behavior changed
-4. update CHANGELOG
+The maintainer aims to respond to issues and PRs within a week. Small PRs merge faster than large ones; if a change can be split, split it. Reviews are about the change, never the person, and the [code of conduct](./CODE_OF_CONDUCT.md) applies everywhere in this project.
 
-## Release Workflow
+## Releases
 
-1. Run the local gate: `npm run lint && npm run typecheck && npm test && npm run test:pack-smoke`.
-2. Update `CHANGELOG.md` and bump `package.json`.
-3. Create a GitHub release. `release.yml` runs the Node and Stylelint matrix on the self-hosted runners, then publishes to npm with provenance when `NPM_TOKEN` is configured, or skips publish with a notice when it is not.
-4. `post-publish-smoke.yml` installs the published version in a clean project.
+Maintainer-run. Bump `package.json` and `CHANGELOG.md`, create a GitHub release, and `release.yml` verifies on the self-hosted matrix and publishes through npm trusted publishing (OIDC) from a GitHub-hosted job. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
+
+## Benchmarking performance
+
+```bash
+npm run bench:perf
+npm run bench:perf:fix
+```
 
-Keep `configs/recommended` and `configs/strict` stable across minors. Rule docs live in `docs/rules/`; a test checks that every rule's `meta.url` points at its page.
+Compares runtime against `stylelint-scales` on a deterministic corpus. Method in [`docs/BENCHMARKING.md`](./docs/BENCHMARKING.md).

package/README.md

@@ -1,19 +1,27 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=3" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=4" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
 </p>
 
 # stylelint-plugin-rhythmguard
 
-Spacing scale and design-token governance for CSS and Tailwind. `padding: 13px` and `p-[13px]` get reported with the nearest on-scale values, and fixed to them when you ask.
+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.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb)](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 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.
 
-## Install
+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. SCSS is audited when `postcss-scss` is installed.
+
+## Start here
+
+```bash
+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:
 
 ```bash
 npm install --save-dev stylelint stylelint-plugin-rhythmguard
@@ -62,7 +70,7 @@ Every rule validates its options up front. Unknown option names and wrong shapes
 
 ## Configs
 
-`recommended`, `strict`, `tailwind`, `react-tailwind`, `expanded`, `logical`, `migration`, `motion`. All are `stylelint-plugin-rhythmguard/configs/<name>`. What each enables, the full custom setup, and the scale-selection precedence are in [docs/CONFIGS.md](docs/CONFIGS.md). Built-in and community scale presets are in [docs/SCALE_PRESETS.md](docs/SCALE_PRESETS.md).
+`recommended`, `strict`, `tailwind`, `motion` (experimental), and `embed` for authors of shared configs (see [docs/FOR_CONFIG_AUTHORS.md](docs/FOR_CONFIG_AUTHORS.md)). All are `stylelint-plugin-rhythmguard/configs/<name>`. What each enables, the full custom setup, and the scale-selection precedence are in [docs/CONFIGS.md](docs/CONFIGS.md). Built-in and community scale presets are in [docs/SCALE_PRESETS.md](docs/SCALE_PRESETS.md).
 
 ## Audit before you enforce
 
@@ -83,12 +91,15 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 - [Framework setup](docs/FRAMEWORKS.md) for Vue, Lit, Astro and SvelteKit
 - [Comparison with adjacent plugins](docs/COMPARISON.md) and migration recipes
 - [Real before/after excerpts](docs/ADOPTION_DIFFS.md) from public codebases
+- [For shared-config authors](docs/FOR_CONFIG_AUTHORS.md): the `embed` entry point and how inference works per consumer
+- [For coding agents](docs/FOR_AGENTS.md): a paste-ready `AGENTS.md` block and the commands to run
+- [Quiet benchmark](docs/QUIET_BENCHMARK.md): findings on public design systems, checked on every change
 - [Product direction](docs/STRATEGY_2026-09.md)
 - Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/)
 
 ## Compatibility
 
-Stylelint 16 and 17. Node 18.18 or newer for Stylelint 16, Node 20.19 or newer for Stylelint 17. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 18, 20 and 22 against Stylelint 16.0.0, 16.x and 17.x.
+Stylelint 16 and 17. Node 20.19 or newer. One runtime dependency (`known-css-properties`); `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/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported |
 | --- | --- |
-| 0.1.x | Yes |
-| < 0.1.0 | No |
+| 2.x | Yes |
+| < 2.0 | No, upgrade to 2.x |
 
 ## Reporting a Vulnerability
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "2.1.0",
-  "description": "Token governance for CSS and Tailwind — enforce spacing scales, require design tokens, catch arbitrary values",
+  "version": "3.0.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"
   },
@@ -32,6 +32,11 @@
       "require": "./src/configs/recommended.js",
       "import": "./src/configs/recommended.mjs"
     },
+    "./configs/embed": {
+      "types": "./types/config.d.ts",
+      "require": "./src/configs/embed.js",
+      "import": "./src/configs/embed.mjs"
+    },
     "./configs/strict": {
       "types": "./types/config.d.ts",
       "require": "./src/configs/strict.js",
@@ -42,31 +47,11 @@
       "require": "./src/configs/tailwind.js",
       "import": "./src/configs/tailwind.mjs"
     },
-    "./configs/expanded": {
-      "types": "./types/config.d.ts",
-      "require": "./src/configs/expanded.js",
-      "import": "./src/configs/expanded.mjs"
-    },
-    "./configs/logical": {
-      "types": "./types/config.d.ts",
-      "require": "./src/configs/logical.js",
-      "import": "./src/configs/logical.mjs"
-    },
-    "./configs/migration": {
-      "types": "./types/config.d.ts",
-      "require": "./src/configs/migration.js",
-      "import": "./src/configs/migration.mjs"
-    },
     "./configs/motion": {
       "types": "./types/config.d.ts",
       "require": "./src/configs/motion.js",
       "import": "./src/configs/motion.mjs"
     },
-    "./configs/react-tailwind": {
-      "types": "./types/config.d.ts",
-      "require": "./src/configs/react-tailwind.js",
-      "import": "./src/configs/react-tailwind.mjs"
-    },
     "./presets": {
       "types": "./types/presets.d.ts",
       "require": "./src/presets/index.js",
@@ -118,6 +103,7 @@
   "scripts": {
     "bench:perf": "node scripts/bench/compare.mjs",
     "bench:perf:fix": "node scripts/bench/compare.mjs --fix",
+    "bench:quiet": "node scripts/bench/quiet.mjs",
     "lint": "eslint .",
     "scales:add": "node scripts/scales/add-scale.mjs",
     "scales:validate": "node scripts/scales/validate-community-scales.mjs",
@@ -139,27 +125,41 @@
     "email": "hello@petrilahdelma.com"
   },
   "peerDependencies": {
-    "stylelint": "^16.0.0 || ^17.0.0"
-  },
-  "dependencies": {
-    "known-css-properties": "^0.37.0",
+    "stylelint": "^16.0.0 || ^17.0.0",
+    "postcss-scss": "^4.0.0",
     "stylelint-config-tailwindcss": "^1.0.1",
     "stylelint-plugin-logical-css": "^2.0.2"
   },
+  "peerDependenciesMeta": {
+    "postcss-scss": {
+      "optional": true
+    },
+    "stylelint-config-tailwindcss": {
+      "optional": true
+    },
+    "stylelint-plugin-logical-css": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "known-css-properties": "^0.37.0"
+  },
   "devDependencies": {
     "@eslint/js": "^9.22.0",
     "@types/node": "^22.20.1",
     "c8": "^10.1.3",
     "eslint": "^9.22.0",
     "geist": "^1.7.0",
+    "postcss-scss": "^4.0.9",
     "postcss-value-parser": "^4.2.0",
     "stylelint": "^16.15.0",
+    "stylelint-config-tailwindcss": "^1.0.1",
     "stylelint-plugin-logical-css": "^2.0.2",
     "stylelint-scales": "^5.0.0",
     "typescript": "^5.9.3"
   },
   "engines": {
-    "node": ">=18.18.0"
+    "node": ">=20.19.0"
   },
   "publishConfig": {
     "access": "public"

package/scales/community/product-decimal-10.json

@@ -1,10 +1,33 @@
 {
   "name": "product-decimal-10",
-  "description": "Decimal-friendly product spacing scale for dashboard-heavy enterprise UIs.",
+  "description": "Decimal-friendly product spacing scale for dashboard-heavy UIs.",
   "base": 10,
-  "steps": [0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64, 80],
-  "aliases": ["decimal-10", "enterprise-10"],
-  "tags": ["product", "dashboard", "community"],
+  "steps": [
+    0,
+    2,
+    4,
+    6,
+    8,
+    10,
+    12,
+    16,
+    20,
+    24,
+    32,
+    40,
+    48,
+    64,
+    80
+  ],
+  "aliases": [
+    "decimal-10",
+    "enterprise-10"
+  ],
+  "tags": [
+    "product",
+    "dashboard",
+    "community"
+  ],
   "contributor": "Petri Lahdelma",
   "contributorUrl": "https://github.com/PetriLahdelma"
 }

package/src/audit/args.js

@@ -36,7 +36,8 @@ Options:
   --token-source-format <format> Token source format: auto, css, flat-json, style-dictionary, dtcg (default: auto)
   --token-kind <kind>            Token kind: spacing, radius, typography, size, motion, all (default: spacing)
   --token-candidate-min-count <n> Minimum repeated raw value count for token candidates (default: 2)
-  --scale <values>               Comma-separated scale values (default: 0,4,8,12,16,24,32)
+  --scale <values|auto>          Comma-separated scale values (default: 0,4,8,12,16,24,32);
+                                 auto infers the scale from token sources, then scanned CSS
   --base-font-size <number>      px base for rem/em conversion (default: 16)
 `;
 
@@ -406,6 +407,10 @@ function parseScale(raw) {
     throw new Error('Missing value for --scale.');
   }
 
+  if (raw.trim().toLowerCase() === 'auto') {
+    return 'auto';
+  }
+
   const scale = raw.split(',')
     .map((part) => part.trim())
     .filter(Boolean)

package/src/audit/config.js

@@ -134,11 +134,21 @@ function parseBooleanOption(value, optionName) {
 }
 
 function normalizeCliTokenSources(sources, format) {
-  return sources.map((sourcePath) => ({
-    baseDir: process.cwd(),
-    format,
-    path: sourcePath,
-  }));
+  return sources.map((source) => {
+    // The programmatic API may pass typed { path | file, format?, baseDir? } entries.
+    if (source && typeof source === 'object') {
+      return {
+        baseDir: source.baseDir || process.cwd(),
+        format: source.format || format,
+        path: source.path || source.file,
+      };
+    }
+    return {
+      baseDir: process.cwd(),
+      format,
+      path: source,
+    };
+  });
 }
 
 function normalizeConfigTokenSources(sources, baseDir) {

package/src/audit/contract.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const {
   addDefinition,
+  collectScssTokens,
   createTokenKindMatcher,
   getNormalizedValueKeys,
 } = require('../utils/token-sources');
@@ -112,6 +113,16 @@ function collectTokenDefinitions(source, file, definitions, matchesKind, baseFon
       value: match[2].trim(),
     });
   }
+
+  for (const sassToken of collectScssTokens(source, matchesKind)) {
+    addDefinition(definitions, {
+      baseFontSize,
+      file,
+      source: file,
+      token: sassToken.token,
+      value: sassToken.value,
+    });
+  }
 }
 
 function collectTokenUses(source, file, uses, matchesKind) {
@@ -243,7 +254,10 @@ function buildReport({
   externalTokenDefinitions,
   includeMotion,
   motionFindings,
+  scale,
   scanScope,
+  scssFiles = 0,
+  scssSkipped = 0,
   templateFiles,
   tailwindFindings,
   tokenCandidateMinCount,
@@ -306,10 +320,13 @@ function buildReport({
       values: Object.fromEntries(sortCountMap(motionValues).slice(0, 10)),
     },
     offScaleValues: Object.fromEntries(sortCountMap(offScaleValues).slice(0, 10)),
+    scale: scale || null,
     scaleCleanliness,
     scanScope,
     scanned: {
       cssFiles: cssFiles.length,
+      scssFiles,
+      scssSkipped,
       templateFiles: templateFiles.length,
       totalFiles,
     },
@@ -370,8 +387,11 @@ function toAuditContractReport(report) {
       motion: report.motion,
       scale: {
         cleanliness: report.scaleCleanliness,
+        files: report.scale ? report.scale.files : [],
         offScaleValues: report.offScaleValues,
+        source: report.scale ? report.scale.source : 'default',
         tokenOpportunities: report.tokenOpportunities,
+        values: report.scale ? report.scale.values : null,
       },
       tokens: report.tokenContract,
     },

package/src/audit/render-markdown.js

@@ -3,6 +3,12 @@
 const { sortCountMap } = require('./contract');
 const { escapeMarkdown } = require('./render-utils');
 
+function describeScaleSource(scale) {
+  return scale.files.length > 0
+    ? `${scale.source} (${scale.files.join(', ')})`
+    : scale.source;
+}
+
 function renderMarkdown(report) {
   const lines = [
     '# Rhythmguard Design-System Audit',
@@ -15,11 +21,18 @@ function renderMarkdown(report) {
     '| --- | ---: |',
     `| CSS files scanned | ${report.cssFilesScanned} |`,
     `| 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} |`] : []),
     `| Files with issues | ${report.filesWithIssues} |`,
     `| Total findings | ${report.totalWarnings} |`,
     `| Scale cleanliness | ${report.scaleCleanliness}% |`,
   ];
 
+  if (report.scale) {
+    lines.push(`| Scale | ${report.scale.values.join(', ')} |`);
+    lines.push(`| Scale source | ${describeScaleSource(report.scale)} |`);
+  }
+
   if (report.baseline) {
     lines.push(`| New findings | ${report.baseline.newFindingsCount} |`);
     lines.push(`| Resolved findings | ${report.baseline.resolvedFindingsCount} |`);

package/src/audit/render-text.js

@@ -19,11 +19,19 @@ function renderText(report) {
     '',
     `  CSS files scanned        ${String(report.cssFilesScanned).padStart(4)}`,
     `  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)`] : []),
     `  Files with issues        ${String(report.filesWithIssues).padStart(4)}`,
     `  Scale cleanliness        ${scoreBar(report.scaleCleanliness)}  ${report.scaleCleanliness}%`,
-    '',
   ];
 
+  if (report.scale) {
+    lines.push(`  Scale                    ${report.scale.values.join(', ')}`);
+    const files = report.scale.files.length > 0 ? ` (${report.scale.files.join(', ')})` : '';
+    lines.push(`  Scale source             ${report.scale.source}${files}`);
+  }
+  lines.push('');
+
   appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
   appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
   appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);