stylelint-plugin-rhythmguard 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -6,6 +6,34 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-09-06
+
+### Fixed
+
+- Whole numbers ending in zero were printed without their zeros: a scale containing `30px` and `60px` produced messages such as `nearest: 3px or 6px`, autofix wrote `3px` for a value snapped to `30px`, and scale inference added phantom small steps (`3px`, `6px`) to every scale that contained `30px` or `60px`. This affected all three Stylelint rules, the ESLint rule's suggested classes, the audit and `scale: "auto"`. Found while reading why GOV.UK's scale came out as `1, 2, 3, 4, 5, 6, 10, 15, ...`. If you use a scale with round-ten values, rerun `--fix` on files that were fixed with an earlier version.
+- `scale: "auto"` accepts tokens named `spacer`, so PatternFly's `--pf-t--global--spacer--*` ladder is read instead of falling back. ([#85](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/85))
+- Token-package discovery reads `@carbon/layout`, where Carbon defines `$spacing-01` to `$spacing-13`. `.scss` files are accepted as token sources, in `scaleSources` and `--token-source` too. ([#87](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/87))
+- `scale: "auto"` and `--scale auto` reject an inferred scale that does not look like one: fewer than three steps, fractional values, no common step (2, 3, 4, 5 or 8), or, in the audit, tokens that come mostly from component files without a near-perfect ladder. The rule then uses the preset and says why in its first message; the audit reports `contracts.scale.rejected` with the source, values and reasons, and the Markdown and text output show it next to the scale source. Component-local variables such as `--chip-spacing: 3px` can no longer become the project scale. ([#88](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/88))
+- Sass spacing maps with one namespace segment before the anchor, such as GOV.UK's `$govuk-spacing-points` and NHS.UK's `$nhsuk-spacing-points`, are read when they hold at least four distinct lengths. Namespaced scalars such as `$dropdown-spacer` and small maps stay excluded, and unitless Sass numbers (mixin parameter defaults such as `$spacing-responsive: 6`, multipliers such as `$spacing-unit: 8`) are no longer taken as lengths. ([#86](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/86))
+- When several Tailwind v4 `--spacing` bases are found, only the first is expanded. A union of ladders from several theme files produced fractional steps that matched nothing on shadcn/ui. ([#89](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/89))
+
+### Changed
+
+- The quiet benchmark manifest grew from 20 to 57 repositories: design systems (GOV.UK, NHS.UK, PatternFly, Cloudscape, Angular Material, Ionic, Element Plus, HashiCorp, SAP Fundamental Styles and UI5 Web Components, daisyUI, Skeleton, Semi, n8n, Utrecht, Mozilla Protocol, Foundation, CoreUI, Tabler, AdminLTE, Materialize, Pure, Tachyons) and CSS-heavy applications (Mastodon already; now Forem, Discourse, Zulip, Mattermost, Grafana, Metabase, Directus, Excalidraw, Ghost, Cal.com, VS Code base UI, Docusaurus, VitePress and Starlight themes). Every repository has a pinned snapshot and the State of Spacing edition is regenerated over the full set.
+- `npm run bench:outreach` drafts one audit issue per benchmark repository under `docs/outreach/audits/`; a separate paced posting script runs a per-repository preflight and records every outcome in `docs/outreach/embed-log.md`.
+
+## [3.2.0] - 2026-09-06
+
+### Added
+
+- `rhythmguard audit --format badge` writes a shields.io endpoint document for a README badge: `spacing drift` as a percentage by default, or the off-scale count with `--badge-metric findings`. Workflow in `docs/CI_ADOPTION.md`. ([#68](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/68))
+- `rhythmguard init --agents <claude|cursor|copilot|all>` installs the agents block from `docs/FOR_AGENTS.md` as a Claude Code skill, a Cursor rule, or a block in `.github/copilot-instructions.md`. The packs ship in the package under `agents/`, are generated by `npm run build:agents`, and a test keeps them in sync with the docs. ([#69](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/69))
+- `npm run bench:state-of-spacing` generates a dated State of Spacing edition from the quiet benchmark results: one row per repository with scale source, off-scale count, drift per 100 CSS files, cleanliness, top values, top properties, and the change since the previous edition. Benchmark results now record the property of each finding. First edition at 20 repositories in `docs/STATE_OF_SPACING.md`. ([#70](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/70))
+
+### Changed
+
+- Dev dependencies: eslint 9.39.5; the unused `geist` package and its `next` and `sharp` chain are gone, and `npm audit` reports no findings. No runtime dependency changed.
+
 ## [3.1.0] - 2026-09-06
 
 ### Added

package/CONTRIBUTING.md

@@ -6,7 +6,7 @@ Thank you for being here. Rhythmguard is a small, opinionated tool with one job:
 
 **Report a false positive.** A finding your team considers wrong is the most valuable report we get. It is how percentages and hairlines stopped being findings. Open a [false-positive report](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/new?template=false-positive.yml) with the CSS or class string and your config. No fix required.
 
-**Add a repository to the quiet benchmark.** The benchmark audits public design systems and fails CI when the findings change. Adding a repo is one JSON entry in `benchmarks/quiet/repos.json` plus `npm run bench:quiet -- --only <name>` to create its snapshot. Systems with tokens in unusual places are the most useful additions.
+**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.
 
 **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.
 

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=5" 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=6" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
 </p>
 
 # stylelint-plugin-rhythmguard
@@ -85,6 +85,8 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 
 `npx rhythmguard init` writes a starter config for your stack. `npx rhythmguard doctor` checks the setup.
 
+A README badge comes from the same audit: `--format badge` writes a shields.io endpoint document, see [`docs/CI_ADOPTION.md`](./docs/CI_ADOPTION.md#5-show-a-badge).
+
 ## Guides
 
 - [Tailwind integration](docs/TAILWIND.md), including v4 `@theme` tokens and what each layer covers
@@ -92,8 +94,9 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 - [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
+- [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
 - [Product direction](docs/STRATEGY_2026-09.md)
 - Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/)
 

package/agents/claude-code/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: rhythmguard
+description: Keep CSS and Tailwind spacing on the project scale. Use when writing or changing CSS, SCSS, CSS Modules or Tailwind class strings, and before finishing any such change.
+---
+
+## Spacing scale
+
+This project enforces its spacing scale with stylelint-plugin-rhythmguard.
+
+- Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
+- A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
+- Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
+- Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
+- If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
+
+Source: docs/FOR_AGENTS.md in the stylelint-plugin-rhythmguard repository (https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/FOR_AGENTS.md). Regenerate with `npx rhythmguard init --agents`.

package/agents/copilot/copilot-instructions.md

@@ -0,0 +1,13 @@
+## Spacing scale
+
+This project enforces its spacing scale with stylelint-plugin-rhythmguard.
+
+- Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
+- A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
+- Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
+- Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
+- If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
+
+Source: docs/FOR_AGENTS.md in the stylelint-plugin-rhythmguard repository (https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/FOR_AGENTS.md). Regenerate with `npx rhythmguard init --agents`.

package/agents/cursor/rhythmguard.mdc

@@ -0,0 +1,19 @@
+---
+description: Spacing scale rules enforced by stylelint-plugin-rhythmguard
+globs: ["**/*.css", "**/*.scss", "**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.html"]
+alwaysApply: true
+---
+
+## Spacing scale
+
+This project enforces its spacing scale with stylelint-plugin-rhythmguard.
+
+- Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
+- A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
+- Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
+- Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
+- Tailwind arbitrary spacing values such as `p-[13px]` are findings too; use the scale utility (`p-3`) or an on-scale arbitrary value.
+- When the audit's `contracts.scale.offScaleProperties` table is dominated by margins on sibling elements, put a `gap` on the parent instead of fixing each margin. The parent owns the spacing between its children.
+- If the audit reports the scale source as `fallback`, the project has no discoverable spacing tokens. Ask before adding any; do not guess a scale.
+
+Source: docs/FOR_AGENTS.md in the stylelint-plugin-rhythmguard repository (https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/FOR_AGENTS.md). Regenerate with `npx rhythmguard init --agents`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.1.0",
+  "version": "3.3.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"
@@ -89,6 +89,7 @@
     }
   },
   "files": [
+    "agents",
     "examples",
     "scales",
     "schemas",
@@ -113,7 +114,10 @@
     "test:npm-smoke": "node scripts/ci/npm-registry-smoke.mjs --package stylelint-plugin-rhythmguard --version latest",
     "test:pack-smoke": "node scripts/ci/pack-smoke.mjs",
     "test:watch": "node --test --watch test/*.test.js",
-    "typecheck": "tsc -p tsconfig.typecheck.json"
+    "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"
   },
   "repository": {
     "type": "git",
@@ -125,8 +129,8 @@
     "email": "hello@petrilahdelma.com"
   },
   "peerDependencies": {
-    "stylelint": "^16.0.0 || ^17.0.0",
     "postcss-scss": "^4.0.0",
+    "stylelint": "^16.0.0 || ^17.0.0",
     "stylelint-config-tailwindcss": "^1.0.1",
     "stylelint-plugin-logical-css": "^2.0.2"
   },
@@ -145,11 +149,10 @@
     "known-css-properties": "^0.37.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.22.0",
+    "@eslint/js": "^9.39.5",
     "@types/node": "^22.20.1",
     "c8": "^10.1.3",
-    "eslint": "^9.22.0",
-    "geist": "^1.7.0",
+    "eslint": "^9.39.5",
     "postcss-scss": "^4.0.9",
     "postcss-value-parser": "^4.2.0",
     "stylelint": "^16.15.0",

package/src/audit/args.js

@@ -4,6 +4,7 @@ const {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
 } = require('../utils/token-sources');
+const { BADGE_METRICS } = require('./render-badge');
 const {
   VALID_FORMATS,
   createDefaultAuditOptions,
@@ -13,12 +14,14 @@ const {
 const HELP = `Usage: rhythmguard audit <dir> [options]
 
 Options:
-  --format <text|json|json-v1|markdown|html|github> Output format (default: text)
+  --format <text|json|json-v1|markdown|html|github|badge> Output format (default: text)
                                  github = GitHub Actions workflow-command annotations
+                                 badge = shields.io endpoint JSON for a README badge
+  --badge-metric <drift|findings> Badge value: drift percent or off-scale count (default: drift)
   --json                         Alias for --format json
   --markdown                     Alias for --format markdown
   --schema                       Print the audit JSON schema and exit
-  --output <file>                Write json, markdown, or html output to a file
+  --output <file>                Write json, markdown, html or badge output to a file
   --config <file>                Load audit config (default: .rhythmguardrc.json when present)
   --no-config                    Ignore .rhythmguardrc.json discovery
   --ignore <pattern>             Exclude root-relative path/glob (repeatable, comma-separated)
@@ -283,6 +286,16 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--badge-metric') {
+      parsed.badgeMetric = String(argv[++index] || '').toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith('--badge-metric=')) {
+      parsed.badgeMetric = arg.slice('--badge-metric='.length).toLowerCase();
+      continue;
+    }
+
     if (arg === '--format') {
       parsed.format = String(argv[++index] || '').toLowerCase();
       continue;
@@ -329,6 +342,10 @@ function parseArgs(argv) {
     throw new Error(`Invalid format "${parsed.format}". Expected text, json, json-v1, markdown, html, or github.`);
   }
 
+  if (!BADGE_METRICS.has(parsed.badgeMetric)) {
+    throw new Error(`Invalid badge metric "${parsed.badgeMetric}". Expected drift or findings.`);
+  }
+
   if (parsed.since && parsed.staged) {
     throw new Error('Use either --since or --staged, not both.');
   }

package/src/audit/contract.js

@@ -394,6 +394,7 @@ function toAuditContractReport(report) {
         files: report.scale ? report.scale.files : [],
         offScaleProperties: report.offScaleProperties || {},
         offScaleValues: report.offScaleValues,
+        rejected: report.scale && report.scale.rejected ? report.scale.rejected : null,
         source: report.scale ? report.scale.source : 'default',
         tokenOpportunities: report.tokenOpportunities,
         values: report.scale ? report.scale.values : null,

package/src/audit/render-badge.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * shields.io endpoint badge: https://shields.io/badges/endpoint
+ *
+ * `drift` reports 100 minus scale cleanliness as a percentage (the share of
+ * scanned files with at least one finding). `findings` reports the number of
+ * off-scale CSS values plus Tailwind class-string findings.
+ */
+const BADGE_METRICS = new Set(['drift', 'findings']);
+
+const THRESHOLDS = {
+  drift: [[2, 'brightgreen'], [5, 'green'], [15, 'yellow']],
+  findings: [[0, 'brightgreen'], [10, 'green'], [50, 'yellow']],
+};
+
+function badgeColor(metric, value) {
+  for (const [limit, color] of THRESHOLDS[metric]) {
+    if (value <= limit) {
+      return color;
+    }
+  }
+  return 'orange';
+}
+
+function badgeValue(report, metric) {
+  if (metric === 'drift') {
+    const cleanliness = Number.isFinite(report.scaleCleanliness) ? report.scaleCleanliness : 100;
+    return Math.max(0, Math.min(100, 100 - cleanliness));
+  }
+  const css = (report.findings && report.findings.css) || [];
+  const tailwind = (report.findings && report.findings.tailwind) || [];
+  return css.filter((finding) => finding.type === 'off-scale').length + tailwind.length;
+}
+
+function renderBadge(report, { metric = 'drift' } = {}) {
+  if (!BADGE_METRICS.has(metric)) {
+    throw new Error(`Unknown badge metric "${metric}". Use one of: ${Array.from(BADGE_METRICS).join(', ')}.`);
+  }
+  const value = badgeValue(report, metric);
+  const badge = {
+    schemaVersion: 1,
+    label: metric === 'drift' ? 'spacing drift' : 'off-scale values',
+    message: metric === 'drift' ? `${value}%` : String(value),
+    color: badgeColor(metric, value),
+  };
+  return `${JSON.stringify(badge, null, 2)}\n`;
+}
+
+module.exports = {
+  BADGE_METRICS,
+  badgeColor,
+  renderBadge,
+};

package/src/audit/render-markdown.js

@@ -4,6 +4,9 @@ const { sortCountMap } = require('./contract');
 const { escapeMarkdown } = require('./render-utils');
 
 function describeScaleSource(scale) {
+  if (scale.rejected) {
+    return `${scale.source} (${scale.rejected.source} rejected: ${scale.rejected.reasons.join(', ')})`;
+  }
   return scale.files.length > 0
     ? `${scale.source} (${scale.files.join(', ')})`
     : scale.source;

package/src/audit/render-text.js

@@ -28,7 +28,8 @@ function renderText(report) {
   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}`);
+    const rejected = report.scale.rejected ? ` (${report.scale.rejected.source} rejected: ${report.scale.rejected.reasons.join(', ')})` : '';
+    lines.push(`  Scale source             ${report.scale.source}${files}${rejected}`);
   }
   lines.push('');
 

package/src/audit/report.js

@@ -18,7 +18,8 @@ const {
 } = require('./config');
 const { buildReport, collectTokenDefinitions } = require('./contract');
 const { DEFAULT_SCALE, formatPath } = require('./shared');
-const { discoverTokenPackages, scaleFromDefinitions } = require('../utils/scale-inference');
+const {
+  assessScale, discoverTokenPackages, scaleFromDefinitions } = require('../utils/scale-inference');
 const {
   assertDirectory,
   collectCssFindings,
@@ -129,6 +130,7 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
     }
   }
 
+  let rejected = null;
   const definitions = new Map();
   const matchesKind = createTokenKindMatcher('spacing');
   for (const filePath of cssFiles) {
@@ -155,12 +157,17 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
           files.add(file);
         }
       }
-      return {
-        files: Array.from(files).sort(),
-        source: 'scanned-css',
-        tokenCount: definitions.size,
-        values,
-      };
+      const sortedFiles = Array.from(files).sort();
+      const assessment = assessScale({ files: sortedFiles, source: 'scanned-css', values });
+      if (assessment.plausible) {
+        return {
+          files: sortedFiles,
+          source: 'scanned-css',
+          tokenCount: definitions.size,
+          values,
+        };
+      }
+      rejected = { files: sortedFiles, reasons: assessment.reasons, source: 'scanned-css', values };
     }
   }
 
@@ -178,7 +185,7 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
     }
   }
 
-  return { files: [], source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
+  return { files: [], ...(rejected ? { rejected } : {}), source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
 }
 
 function normalizeCreateAuditOptions(options = {}) {

package/src/audit/shared.js

@@ -18,7 +18,7 @@ const DEFAULT_AUDIT_TOKEN_PATTERN = '^--(space|spacing)-';
 
 const DEFAULT_TOKEN_CANDIDATE_MIN_COUNT = 2;
 
-const VALID_FORMATS = new Set(['text', 'json', 'json-v1', 'markdown', 'html', 'github']);
+const VALID_FORMATS = new Set(['text', 'json', 'json-v1', 'markdown', 'html', 'github', 'badge']);
 
 const SKIP_DIRS = new Set([
   '.git',
@@ -69,6 +69,7 @@ function createDefaultAuditOptions() {
     configPath: DEFAULT_CONFIG_PATH,
     dir: null,
     failOnNewDrift: false,
+    badgeMetric: 'drift',
     format: 'text',
     ignorePath: DEFAULT_IGNORE_PATH,
     ignorePatterns: [],

package/src/cli/audit.js

@@ -13,6 +13,7 @@ const {
   toAuditContractReport,
 } = require('../audit/contract');
 const { renderGithub } = require('../audit/render-github');
+const { renderBadge } = require('../audit/render-badge');
 const { renderHtml } = require('../audit/render-html');
 const { renderMarkdown } = require('../audit/render-markdown');
 const { renderText } = require('../audit/render-text');
@@ -73,6 +74,12 @@ async function run() {
     return;
   }
 
+  if (parsed.format === 'badge') {
+    writeOutput(renderBadge(report, { metric: parsed.badgeMetric }), parsed.outputPath);
+    finish(auditFailures);
+    return;
+  }
+
   if (parsed.format === 'github') {
     writeOutput(renderGithub(report), parsed.outputPath);
     finish(auditFailures);
@@ -108,6 +115,7 @@ module.exports = {
   createAuditReport,
   loadAuditConfig,
   parseArgs,
+  renderBadge,
   renderHtml,
   run,
   toAuditContractReport,

package/src/cli/index.js

@@ -12,6 +12,7 @@ Commands:
   quickstart    Same as running with no command
   audit <dir>   Report design-system drift across CSS and Tailwind class strings
   init          Scaffold a Rhythmguard config for your project
+                --agents <claude|cursor|copilot|all> installs the agent instruction packs instead
   doctor        Validate your Rhythmguard setup
 
 Options:
@@ -22,6 +23,7 @@ Examples:
   npx rhythmguard audit ./src
   npx rhythmguard audit ./src --format markdown
   npx rhythmguard init
+  npx rhythmguard init --agents all
   npx rhythmguard doctor
 `;
 

package/src/cli/init.js

@@ -98,7 +98,84 @@ function selectProfile(stack) {
   return 'recommended';
 }
 
+const AGENT_TARGETS = {
+  claude: { source: 'claude-code/SKILL.md', target: path.join('.claude', 'skills', 'rhythmguard', 'SKILL.md'), mode: 'write' },
+  cursor: { source: 'cursor/rhythmguard.mdc', target: path.join('.cursor', 'rules', 'rhythmguard.mdc'), mode: 'write' },
+  copilot: { source: 'copilot/copilot-instructions.md', target: path.join('.github', 'copilot-instructions.md'), mode: 'append' },
+};
+const AGENT_BLOCK_START = '<!-- rhythmguard:agents:start -->';
+const AGENT_BLOCK_END = '<!-- rhythmguard:agents:end -->';
+
+function parseInitArgs(argv) {
+  const parsed = { agents: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--agents') {
+      parsed.agents = String(argv[++index] || 'all').toLowerCase();
+    } else if (arg.startsWith('--agents=')) {
+      parsed.agents = arg.slice('--agents='.length).toLowerCase();
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Copies the generated packs under <package>/agents into the locations each
+ * agent reads. Claude Code and Cursor files are owned by Rhythmguard and
+ * overwritten; copilot-instructions.md is shared, so the block is appended
+ * between markers and replaced in place on later runs.
+ */
+function installAgents(selection, cwd = process.cwd()) {
+  const names = selection === 'all' ? Object.keys(AGENT_TARGETS) : [selection];
+  const unknown = names.filter((name) => !AGENT_TARGETS[name]);
+  if (unknown.length > 0) {
+    throw new Error(`Unknown agents target "${unknown[0]}". Use claude, cursor, copilot or all.`);
+  }
+
+  const packsDir = path.join(__dirname, '..', '..', 'agents');
+  const written = [];
+  for (const name of names) {
+    const { mode, source, target } = AGENT_TARGETS[name];
+    const content = fs.readFileSync(path.join(packsDir, source), 'utf8');
+    const targetPath = path.join(cwd, target);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+
+    if (mode === 'append' && fs.existsSync(targetPath)) {
+      const existing = fs.readFileSync(targetPath, 'utf8');
+      const block = `${AGENT_BLOCK_START}\n${content.trimEnd()}\n${AGENT_BLOCK_END}\n`;
+      const start = existing.indexOf(AGENT_BLOCK_START);
+      const end = existing.indexOf(AGENT_BLOCK_END);
+      const next = start !== -1 && end !== -1
+        ? `${existing.slice(0, start)}${block}${existing.slice(end + AGENT_BLOCK_END.length).replace(/^\n/, '')}`
+        : `${existing.trimEnd()}\n\n${block}`;
+      fs.writeFileSync(targetPath, next);
+    } else {
+      fs.writeFileSync(targetPath, content);
+    }
+    written.push(target);
+  }
+  return written;
+}
+
 async function run() {
+  const args = parseInitArgs(process.argv.slice(3));
+
+  if (args.agents) {
+    let written;
+    try {
+      written = installAgents(args.agents);
+    } catch (error) {
+      process.stderr.write(`${error.message}\n`);
+      process.exit(1);
+    }
+    process.stdout.write('\nRhythmguard agent packs\n\n');
+    for (const file of written) {
+      process.stdout.write(`✓ Wrote ${file}\n`);
+    }
+    process.stdout.write('\nThe block is the one in docs/FOR_AGENTS.md. Trim it to the lines that apply.\n\n');
+    return;
+  }
+
   const prompter = createPrompter();
 
   try {
@@ -152,7 +229,7 @@ async function run() {
   }
 }
 
-module.exports = { detect, run, selectProfile };
+module.exports = { AGENT_TARGETS, detect, installAgents, run, selectProfile };
 
 if (require.main === module) {
   run();

package/src/cli/quickstart.js

@@ -160,7 +160,10 @@ async function run() {
   out.push('  Scale');
   out.push(`    Scale           ${scale.values.join(', ')}`);
   out.push(`    Source          ${describeScale(scale)}`);
-  if (scale.source === 'fallback') {
+  if (scale.source === 'fallback' && scale.rejected) {
+    out.push(`    Note            Spacing tokens were found but do not form a scale (${scale.rejected.reasons.join(', ')}); the rhythmic-4 preset is being used.`);
+    out.push('                    Point scaleSources at your real token file, or tighten tokenPattern.');
+  } else if (scale.source === 'fallback') {
     out.push('    Note            No spacing tokens found; the rhythmic-4 preset is being used.');
     out.push('                    Add scaleSources or define --space-*/--spacing-* custom properties to lint against your own scale.');
   }

package/src/utils/length.js

@@ -69,8 +69,10 @@ function formatNumber(value) {
     return '0';
   }
 
+  // String() already prints the shortest form (1.5, not 1.50). The old
+  // trailing-zero strip also turned 30 into 3 and 100 into 1.
   const rounded = Math.round(value * 10000) / 10000;
-  return String(rounded).replace(/\.?0+$/, '');
+  return String(rounded);
 }
 
 function formatLength(number, unit) {

package/src/utils/scale-inference.js

@@ -9,7 +9,7 @@ const { collectScssTokens, createTokenKindMatcher, parseTokenSources } = require
 const { getScalePreset } = require('../presets/scales');
 
 // Matches the audit default so lint and audit agree on what a spacing token is.
-const DEFAULT_AUTO_TOKEN_PATTERN = '(^--|-)(?<!letter-)(?<!word-)(space|spacing)(-|$)';
+const DEFAULT_AUTO_TOKEN_PATTERN = '(^--|-)(?<!letter-)(?<!word-)(space|spacing|spacer)(-|$)';
 // Tailwind v4 defines one base (`--spacing: 0.25rem`) and derives utilities by multiplying it.
 const TAILWIND_BASE_TOKENS = new Set(['--spacing', '--space']);
 const TAILWIND_SPACING_MULTIPLIERS = [
@@ -191,21 +191,38 @@ function scaleFromDefinitions(definitions, baseFontSize = 16) {
   return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
 }
 
-/** Merge Tailwind-style base multiples into a scale when a bare --spacing/--space base is defined. */
+/**
+ * Merge Tailwind-style base multiples into a scale when a bare --spacing/--space
+ * base is defined. Only the first base found is expanded: a project that ships
+ * several theme files with different bases (shadcn/ui) has one active base at a
+ * time, and a union of ladders is a scale nobody designed (issue #89).
+ */
 function expandTailwindBase(scale, baseKeys, baseFontSize) {
-  const bases = pxValuesFromKeys(baseKeys, baseFontSize).filter((value) => value > 0);
-  if (bases.length === 0) {
+  const base = firstPositivePx(baseKeys, baseFontSize);
+  if (base === null) {
     return scale;
   }
   const values = new Set(scale);
-  for (const base of bases) {
-    for (const multiplier of TAILWIND_SPACING_MULTIPLIERS) {
-      values.add(Math.round(base * multiplier * 1000) / 1000);
-    }
+  for (const multiplier of TAILWIND_SPACING_MULTIPLIERS) {
+    values.add(Math.round(base * multiplier * 1000) / 1000);
   }
   return Array.from(values).sort((a, b) => a - b);
 }
 
+function firstPositivePx(keys, baseFontSize) {
+  for (const key of keys) {
+    const parsed = parseLengthToken(String(key));
+    if (!parsed) {
+      continue;
+    }
+    const px = toPx(Math.abs(parsed.number), parsed.unit || 'px', baseFontSize);
+    if (px !== null && Number.isFinite(px) && px > 0) {
+      return px;
+    }
+  }
+  return null;
+}
+
 function rcTokenSources(cwd) {
   const rcPath = path.join(cwd, RC_FILE);
   if (!fs.existsSync(rcPath)) {
@@ -290,6 +307,7 @@ function resolveAutoScale({
     tokenRegex = new RegExp(DEFAULT_AUTO_TOKEN_PATTERN);
   }
 
+  let rejected = null;
   if (root) {
     const stylesheetMap = buildEffectiveTokenMap({
       options: { baseFontSize, tokenMap: {}, tokenMapFromCssCustomProperties: true },
@@ -298,7 +316,11 @@ function resolveAutoScale({
     });
     const scale = scaleFromTokenMap(stylesheetMap, baseFontSize, sassValuesFromRoot(root));
     if (scale) {
-      return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
+      const assessment = assessScale({ source: 'stylesheet', values: scale });
+      if (assessment.plausible) {
+        return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
+      }
+      rejected = { reasons: assessment.reasons, source: 'stylesheet', values: scale };
     }
   }
 
@@ -324,9 +346,56 @@ function resolveAutoScale({
     return { source: 'token-package', ...fromPackages };
   }
 
+  return fallbackInference(rejected);
+}
+
+const TRUSTED_SCALE_SOURCES = new Set(['scaleSources', 'rhythmguardrc', 'token-sources', 'tailwind', 'token-package', 'explicit', 'default']);
+const TOKEN_FILE_PATTERN = /(token|variable|spacing|space|theme|primitive|global|scale|layout)/i;
+const LADDER_STEPS = [2, 3, 4, 5, 8];
+const MIN_ASSESSED_STEPS = 3;
+// A scale with more steps than this must be a near-perfect ladder; otherwise it
+// is a list of every value a codebase happens to use (Semi Design: 42 steps).
+const MAX_LOOSE_STEPS = 24;
+
+/**
+ * Inference can pick up component-local variables (`--chip-spacing: 3px`) and
+ * assemble a "scale" nobody designed. Explicit sources are trusted. An inferred
+ * scale is plausible when it has at least three positive steps, is mostly whole
+ * pixels, mostly shares a common step (2, 3, 4, 5 or 8), and, past two dozen
+ * steps, is a near-perfect ladder. When the source
+ * files are known, a set that comes mostly from component files must be a
+ * near-perfect ladder to pass. Fallback is never the project's scale.
+ */
+function assessScale({ files = null, source, values = [] } = {}) {
+  if (source === 'fallback') {
+    return { plausible: false, reasons: ['fallback'] };
+  }
+  if (TRUSTED_SCALE_SOURCES.has(source)) {
+    return { plausible: true, reasons: [] };
+  }
+  const positives = values.map(Number).filter((value) => Number.isFinite(value) && value > 0);
+  const integers = positives.filter(Number.isInteger);
+  const integerShare = positives.length ? integers.length / positives.length : 0;
+  const coherence = positives.length
+    ? Math.max(...LADDER_STEPS.map((step) => integers.filter((value) => value % step === 0).length / positives.length))
+    : 0;
+  const reasons = [];
+  if (positives.length < MIN_ASSESSED_STEPS) reasons.push('fewer than three steps');
+  if (integerShare < 0.8) reasons.push('fractional values');
+  if (coherence < 0.7) reasons.push('no common step');
+  if (positives.length > MAX_LOOSE_STEPS && coherence < 0.9) reasons.push('too many steps');
+  if (Array.isArray(files) && files.length > 0) {
+    const tokenFileShare = files.filter((file) => TOKEN_FILE_PATTERN.test(file)).length / files.length;
+    if (tokenFileShare < 0.5 && coherence < 0.9) reasons.push('sources are component files');
+  }
+  return { plausible: reasons.length === 0, reasons };
+}
+
+function fallbackInference(rejected = null) {
   return {
     files: [],
     preset: FALLBACK_PRESET,
+    ...(rejected ? { rejected } : {}),
     scale: getScalePreset(FALLBACK_PRESET),
     source: 'fallback',
     tokenCount: 0,
@@ -338,12 +407,16 @@ function autoScaleFallbackNote(inference) {
   if (!inference || inference.source !== 'fallback') {
     return '';
   }
+  if (inference.rejected) {
+    return `The spacing tokens found do not form a spacing scale (${inference.rejected.reasons.join(', ')}); using preset "${inference.preset}".`;
+  }
 
   return `No spacing tokens were found for scale "auto"; using preset "${inference.preset}".`;
 }
 
 module.exports = {
   DEFAULT_AUTO_TOKEN_PATTERN,
+  assessScale,
   autoScaleFallbackNote,
   discoverTokenPackages,
   resolveAutoScale,

package/src/utils/token-packages.json

@@ -43,6 +43,13 @@
         "dist/css/global-vars.css"
       ],
       "note": "--spectrum-spacing-* in px"
+    },
+    {
+      "name": "@carbon/layout",
+      "files": [
+        "scss/generated/_spacing.scss"
+      ],
+      "note": "$spacing-01..13 in rem, Sass variables; Carbon's styles package forwards them from here"
     }
   ]
 }

package/src/utils/token-sources.js

@@ -38,7 +38,7 @@ const TOKEN_KIND_PATTERNS = Object.freeze({
   // --spacing) but never letter-/word-spacing. Sass names must start with the scale word
   // (an optional `system-` prefix allowed): $spacer, $spacers.3, $spacing-01, $system-spacing.
   // Component variables such as $dropdown-spacer or $card-spacer-y are not scale tokens.
-  spacing: /^(?:\$(?:system-)?(?:space|spacing|spacer)s?(?:-|$|\.)|--(?:[\w-]*-)?(?<!letter-)(?<!word-)(?:space|spacing)(?:-|$))/,
+  spacing: /^(?:\$(?:system-)?(?:space|spacing|spacer)s?(?:-|$|\.)|--(?:[\w-]*-)?(?<!letter-)(?<!word-)(?:space|spacing|spacer)(?:-|$))/,
   typography: /^--(?:font|font-size|line-height|leading|tracking|typography)-/,
 });
 
@@ -193,7 +193,8 @@ function normalizeTokenSource(source) {
 }
 
 function detectSourceFormat(filePath) {
-  if (path.extname(filePath).toLowerCase() === '.css') {
+  // .scss token files are read by the CSS collector too: custom properties plus Sass variables and maps.
+  if (['.css', '.scss'].includes(path.extname(filePath).toLowerCase())) {
     return 'css';
   }
 
@@ -283,16 +284,40 @@ function collectScssTokens(source, matchesKind) {
   };
 
   const tokens = [];
-  const push = (tokenName, value) => {
-    if (!value || !matchesKind(tokenName)) {
+  const push = (tokenName, value, force = false) => {
+    if (!value || (!force && !matchesKind(tokenName))) {
       return;
     }
-    tokens.push({ token: tokenName, value: formatScssValue(value) });
+    const formatted = formatScssValue(value);
+    // A unitless number is a multiplier or a map index, not a length. Zero is fine.
+    if (/^-?\d*\.?\d+$/.test(formatted) && parseFloat(formatted) !== 0) {
+      return;
+    }
+    tokens.push({ token: tokenName, value: formatted });
   };
+  // Namespaced maps such as GOV.UK's $govuk-spacing-points are only accepted
+  // for the spacing kind, and only when they hold a real ladder (issue #86).
+  const spacingKind = matchesKind('$spacing-probe');
 
   for (const [name, raw] of declarations) {
     const tokenName = `$${name}`;
     if (isScssMap(raw)) {
+      if (!matchesKind(tokenName) && spacingKind && NAMESPACED_SPACING_MAP.test(tokenName)) {
+        const entries = [];
+        walkScssMap(raw, [tokenName], (pathName, expression) => {
+          const value = evaluateScssExpression(expression, resolveVariable, new Set());
+          if (value) {
+            entries.push([pathName, value]);
+          }
+        });
+        const distinct = new Set(entries.map(([, value]) => formatScssValue(value)).filter((value) => /^-?\d*\.?\d+(?:px|rem|em)$/.test(value) && parseFloat(value) !== 0));
+        if (distinct.size >= MIN_NAMESPACED_MAP_LENGTHS) {
+          for (const [pathName, value] of entries) {
+            push(pathName, value, true);
+          }
+        }
+        continue;
+      }
       walkScssMap(raw, [tokenName], (pathName, expression) => {
         push(pathName, evaluateScssExpression(expression, resolveVariable, new Set()));
       });
@@ -304,6 +329,10 @@ function collectScssTokens(source, matchesKind) {
   return tokens;
 }
 
+/** `$<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;
+
 function stripScssComments(source) {
   return source
     .replace(/\/\*[\s\S]*?\*\//g, '')

package/types/audit.d.ts

@@ -27,7 +27,9 @@ export interface AuditOptions {
   configPath?: string;
   dir?: string;
   failOnNewDrift?: boolean;
-  format?: "json" | "json-v1" | "markdown" | "text" | "html" | "github";
+  /** Badge value when `format` is "badge": drift percent or off-scale count. */
+  badgeMetric?: "drift" | "findings";
+  format?: "json" | "json-v1" | "markdown" | "text" | "html" | "github" | "badge";
   ignorePath?: string;
   ignorePatterns?: string[];
   includeMotion?: boolean;
@@ -96,9 +98,19 @@ export interface AuditBaselineComparison {
 
 export type AuditScaleSource = "default" | "explicit" | "fallback" | "scanned-css" | "token-package" | "token-sources";
 
+export interface AuditScaleRejected {
+  files?: string[];
+  /** Why the inferred set was not accepted as a scale, for example "no common step". */
+  reasons: string[];
+  source: AuditScaleSource;
+  values: Array<number | string>;
+}
+
 export interface AuditScale {
   /** Files the scale was derived from (token sources or scanned stylesheets). Empty for explicit, default and fallback. */
   files: string[];
+  /** Present when `source` is "fallback" because an inferred scale failed the plausibility check. */
+  rejected?: AuditScaleRejected | null;
   source: AuditScaleSource;
   tokenCount: number;
   values: Array<number | string>;
@@ -137,6 +149,7 @@ export interface AuditContractReport {
       files: string[];
       offScaleProperties?: Record<string, number>;
       offScaleValues?: unknown;
+      rejected: AuditScaleRejected | null;
       source: AuditScaleSource;
       tokenOpportunities?: unknown;
       values: Array<number | string> | null;