stylelint-plugin-rhythmguard 2.2.0 → 3.1.0

package/CHANGELOG.md

@@ -6,6 +6,45 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-09-06
+
+### Added
+
+- Audit findings for CSS declarations carry the declaration's `property`, recovered from the source at the warning position (`null` inside at-rules). Off-scale findings are counted by property in `offScaleProperties`, exposed as `contracts.scale.offScaleProperties`, rendered as a histogram in text, Markdown and HTML output and as a `Top properties` line in the quickstart. Baseline keys and benchmark snapshots are unchanged. ([#64](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/64))
+
+### Changed
+
+- `rhythmguard audit --help` describes what `--scale auto` reads and in which order, SCSS scanning through `postcss-scss`, and the value, property and file breakdowns.
+- CI and release workflows no longer run the full suite on the Stylelint 16.0.0 floor as an allowed-to-fail step; that step produced an error annotation on every green run. The blocking floor suite is unchanged. Actions `checkout` and `setup-node` moved to v5.
+
+## [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

package/CONTRIBUTING.md

@@ -1,84 +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
-5. run the quiet benchmark: `npm run bench:quiet -- --check`. It audits real public design systems at pinned commits and fails when the finding set or the inferred scale changes. If the change is intended, review the printed diff, run `npm run bench:quiet -- --update-snapshots`, and commit `benchmarks/quiet/snapshots/` with a sentence in the PR on why the new findings are right. CI runs the same check.
+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,19 @@
 <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=5" 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.
 
-What it is not: it does not check colors or hex values, the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below), and it does not parse SCSS in the audit. 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). 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
 
@@ -70,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`, 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).
+`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
 
@@ -99,7 +99,7 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 
 ## 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.2.0",
-  "description": "Token governance for CSS and Tailwind — enforce spacing scales, require design tokens, catch arbitrary values",
+  "version": "3.1.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"
   },
@@ -47,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",
@@ -145,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

@@ -37,8 +37,14 @@ Options:
   --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|auto>          Comma-separated scale values (default: 0,4,8,12,16,24,32);
-                                 auto infers the scale from token sources, then scanned CSS
+                                 auto infers the scale from token sources, then --space-*/--spacing-*
+                                 custom properties and Sass variables in scanned CSS/SCSS, then
+                                 installed design-token packages, and reports where it came from
   --base-font-size <number>      px base for rem/em conversion (default: 16)
+
+Scans .css files, and .scss files when postcss-scss is installed. Reports drift by
+value, by property and by file; text output prints histograms, markdown is PR-ready,
+json is the stable 2.0 contract.
 `;
 
 function parseArgs(argv) {

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) {
@@ -245,6 +256,8 @@ function buildReport({
   motionFindings,
   scale,
   scanScope,
+  scssFiles = 0,
+  scssSkipped = 0,
   templateFiles,
   tailwindFindings,
   tokenCandidateMinCount,
@@ -255,6 +268,9 @@ function buildReport({
   const offScaleValues = countByValue(cssFindings
     .filter((finding) => finding.type === 'off-scale' && finding.value)
     .map((finding) => finding.value));
+  const offScaleProperties = countByValue(cssFindings
+    .filter((finding) => finding.type === 'off-scale' && finding.property)
+    .map((finding) => finding.property));
   const tokenOpportunities = countByValue(cssFindings
     .filter((finding) => finding.type === 'token-opportunity' && finding.value)
     .map((finding) => finding.value));
@@ -306,12 +322,15 @@ function buildReport({
       findings: motionFindings.length,
       values: Object.fromEntries(sortCountMap(motionValues).slice(0, 10)),
     },
+    offScaleProperties: Object.fromEntries(sortCountMap(offScaleProperties).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,
     },
@@ -373,6 +392,7 @@ function toAuditContractReport(report) {
       scale: {
         cleanliness: report.scaleCleanliness,
         files: report.scale ? report.scale.files : [],
+        offScaleProperties: report.offScaleProperties || {},
         offScaleValues: report.offScaleValues,
         source: report.scale ? report.scale.source : 'default',
         tokenOpportunities: report.tokenOpportunities,

package/src/audit/render-html.js

@@ -34,6 +34,7 @@ function renderHtml(report) {
     metricHtml('CSS files', report.cssFilesScanned),
     metricHtml('Template files', report.templateFilesScanned),
     '</section>',
+    renderHtmlTable('CSS Off-Scale Properties', ['Property', 'Count'], Object.entries(report.offScaleProperties || {})),
     renderHtmlTable('Top Affected Files', ['File', 'Findings'], report.topAffectedFiles.map(({ file, count }) => [file, count])),
     renderHtmlTable('Token Contract Sources', ['File', 'Format', 'Tokens'], report.tokenContract.sources.map((source) => [
       source.file,

package/src/audit/render-markdown.js

@@ -21,6 +21,8 @@ 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}% |`,
@@ -38,6 +40,7 @@ function renderMarkdown(report) {
   lines.push('');
 
   appendMarkdownCounts(lines, 'CSS Off-Scale Values', report.offScaleValues);
+  appendMarkdownCounts(lines, 'CSS Off-Scale Properties', report.offScaleProperties, 'Property');
   appendMarkdownCounts(lines, 'CSS Token Opportunities', report.tokenOpportunities);
   appendMarkdownCounts(lines, 'Tailwind Class-String Drift', report.tailwindArbitraryValues);
   appendMarkdownCounts(lines, 'Motion Rhythm Drift', report.motion.values);
@@ -202,8 +205,8 @@ function appendBaselineMarkdown(lines, report) {
   }
 }
 
-function appendMarkdownCounts(lines, title, counts) {
-  const entries = sortCountMap(counts);
+function appendMarkdownCounts(lines, title, counts, label = 'Value') {
+  const entries = sortCountMap(counts || {});
 
   if (entries.length === 0) {
     return;
@@ -211,7 +214,7 @@ function appendMarkdownCounts(lines, title, counts) {
 
   lines.push(`## ${title}`);
   lines.push('');
-  lines.push('| Value | Count |');
+  lines.push(`| ${label} | Count |`);
   lines.push('| --- | ---: |');
   for (const [value, count] of entries) {
     lines.push(`| \`${escapeMarkdown(value)}\` | ${count} |`);

package/src/audit/render-text.js

@@ -19,6 +19,8 @@ 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}%`,
   ];
@@ -31,6 +33,7 @@ function renderText(report) {
   lines.push('');
 
   appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
+  appendHistogram(lines, 'CSS OFF-SCALE PROPERTIES', report.offScaleProperties);
   appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
   appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);
   appendHistogram(lines, 'MOTION RHYTHM DRIFT', report.motion.values);
@@ -143,9 +146,9 @@ function appendBaselineText(lines, report) {
   }
 }
 
-function appendHistogram(lines, title, counts) {
-  const entries = sortCountMap(counts);
-  const total = sumCounts(counts);
+function appendHistogram(lines, title, counts = {}) {
+  const entries = sortCountMap(counts || {});
+  const total = sumCounts(counts || {});
 
   if (entries.length === 0) {
     return;

package/src/audit/report.js

@@ -18,7 +18,7 @@ const {
 } = require('./config');
 const { buildReport, collectTokenDefinitions } = require('./contract');
 const { DEFAULT_SCALE, formatPath } = require('./shared');
-const { scaleFromDefinitions } = require('../utils/scale-inference');
+const { discoverTokenPackages, scaleFromDefinitions } = require('../utils/scale-inference');
 const {
   assertDirectory,
   collectCssFindings,
@@ -79,6 +79,8 @@ async function createAuditReport(options) {
     motionFindings,
     scale,
     scanScope,
+    scssFiles: cssResults.scssFiles || 0,
+    scssSkipped: cssResults.scssSkipped || 0,
     tailwindFindings: collectTailwindFindings(templateFiles, lintOptions),
     templateFiles,
     tokenCandidateMinCount: parsed.tokenCandidateMinCount,
@@ -98,6 +100,8 @@ async function createAuditReport(options) {
   return report;
 }
 
+const NON_AUTHORED_SEGMENT = /(^|\/)(test|tests|__tests__|spec|specs|fixtures?|__fixtures__|__snapshots__|vendor|third[-_]?party|storybook-static)(\/|$)/i;
+
 /**
  * One project-level scale for the whole audit, with provenance.
  * "auto": external token sources, then spacing custom properties across the scanned
@@ -128,6 +132,11 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
   const definitions = new Map();
   const matchesKind = createTokenKindMatcher('spacing');
   for (const filePath of cssFiles) {
+    // Test, fixture and vendored stylesheets often redefine tokens to exercise
+    // overrides; they are findings noise and must not shape the inferred scale.
+    if (NON_AUTHORED_SEGMENT.test(formatPath(filePath))) {
+      continue;
+    }
     let text;
     try {
       text = fs.readFileSync(filePath, 'utf8');
@@ -155,6 +164,20 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
     }
   }
 
+  const packageSources = discoverTokenPackages(process.cwd());
+  if (packageSources.length > 0) {
+    const parsedPackages = parseTokenSources({ baseFontSize, sources: packageSources, tokenKind: 'spacing' });
+    const values = scaleFromDefinitions(parsedPackages.definitions, baseFontSize);
+    if (values) {
+      return {
+        files: parsedPackages.sources.map((source) => source.file),
+        source: 'token-package',
+        tokenCount: parsedPackages.definitions.size,
+        values,
+      };
+    }
+  }
+
   return { files: [], source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
 }