stylelint-plugin-rhythmguard 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [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

@@ -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.2.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,9 @@
     "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"
   },
   "repository": {
     "type": "git",
@@ -125,8 +128,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 +148,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/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/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/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;