stylelint-plugin-rhythmguard

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.

Rhythmguard is scale-aware rather than a blanket ban: values on your scale pass, values off it are reported with the two nearest steps, and tokens are only ever suggested from a map you control. It works on CSS and SCSS declarations through Stylelint and on Tailwind class strings through an ESLint companion, and it ships an audit CLI so you can measure drift and ratchet it down before enforcing anything.

What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). Pair it with a color linter if you need one; do not expect one tool to do both.

Start here

npx stylelint-plugin-rhythmguard

No install, no config. It detects your stack and token files, infers your spacing scale from your own tokens, audits the current directory, and prints the exact .stylelintrc.json (and ESLint snippet for Tailwind) to paste. This is the whole run on Bootstrap's v6-dev branch, unedited:

Then:

npm install --save-dev stylelint stylelint-plugin-rhythmguard

{
  "extends": ["stylelint-plugin-rhythmguard/configs/recommended"]
}

That enables rhythmguard/use-scale on spacing properties with the default 4px scale. Tailwind projects use the tailwind config instead, which also extracts spacing tokens from @theme:

{
  "extends": ["stylelint-plugin-rhythmguard/configs/tailwind"]
}

For class strings in JSX, TSX, Vue, Svelte or Astro, add the ESLint companion. It is the same rules under two names: stylelint-plugin-rhythmguard/eslint if you already have this package, or eslint-plugin-rhythmguard on its own.

// eslint.config.js
import rhythmguard from 'stylelint-plugin-rhythmguard/eslint';

export default [
  {
    plugins: { 'rhythmguard-tailwind': rhythmguard },
    rules: { 'rhythmguard-tailwind/tailwind-class-use-scale': ['error', { scale: [0, 4, 8, 12, 16, 24, 32] }] },
  },
];

Rules

| Rule | What it reports | Fix | | --- | --- | --- | | rhythmguard/use-scale | Length values off the configured scale | Nearest scale value | | rhythmguard/prefer-token | Raw literals where a design token exists | Token from your map | | rhythmguard/no-offscale-transform | Off-scale translate* offsets | Nearest scale value | | rhythmguard/use-motion-scale | Off-scale durations and raw easing curves. Opt-in, experimental | Nearest duration | | rhythmguard-tailwind/tailwind-class-use-scale | Off-scale Tailwind arbitrary spacing values (p-[13px]) in class strings | Nearest scale value | | rhythmguard-tailwind/tailwind-class-use-motion-scale | Off-scale duration-[...], delay-[...], raw ease-[...]. Opt-in | Nearest duration |

Every rule validates its options up front. Unknown option names and wrong shapes are reported, never ignored.

Configs

recommended, strict, tailwind, motion (experimental), and embed for authors of shared configs (see 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. Built-in and community scale presets are in docs/SCALE_PRESETS.md.

Audit before you enforce

npx rhythmguard audit ./src --format markdown
npx rhythmguard audit ./src --write-baseline
npx rhythmguard audit ./src --since-baseline --fail-on-new-drift
npx rhythmguard audit ./src --format github

The audit scans CSS declarations, Tailwind class strings and your token contract, prints a scale-cleanliness score, and supports baselines so legacy codebases can gate only new drift. Formats: text, Markdown, JSON 2.0, HTML, GitHub Actions annotations, and a shields.io badge document for your README. Full reference in docs/AUDIT.md, rollout recipe and the badge workflow in docs/CI_ADOPTION.md. In GitHub Actions, PetriLahdelma/rhythmguard-action@v1 runs the audit, annotates the diff, comments on the pull request and fails on new drift in one step.

npx rhythmguard audit ./src --plan turns the report into a proposed decisions section (adopt a value, allow it, or snap it), and npx rhythmguard fix ./src --value 10px --to "var(--space-sm)" --write executes one decision as one reviewable change; see decisions. npx rhythmguard init writes a starter config for your stack, and init --agents all installs the coding-agent instructions. npx rhythmguard doctor checks the setup.

Guides

• Tailwind integration, including v4 @theme tokens and what each layer covers
• Framework setup for Vue, Lit, Astro and SvelteKit
• Comparison with adjacent plugins and migration recipes
• Real before/after excerpts from public codebases
• For shared-config authors: the embed entry point and how inference works per consumer
• For coding agents: a paste-ready AGENTS.md block, installable with npx rhythmguard init --agents all for Claude Code, Cursor and Copilot
• Quiet benchmark: findings on public design systems, checked on every change
• State of Spacing: dated editions of the same data, ranked by drift density, with the values and properties that drifted
• Agent evals: does a finding get a coding agent to zero drift, in how many rounds, at what cost, against a rules-only control
• Architecture: the layers, the rule kit, the invariants and where each is enforced
• Product direction
• Browser playground: petrilahdelma.github.io/stylelint-plugin-rhythmguard runs the real rules, bundled for the browser, on CSS or SCSS you paste; scale: "auto", tokens and fixes included, and a test proves it reports what Stylelint reports

Compatibility

Stylelint 16 and 17. Node 20.19 or newer. Three runtime dependencies (known-css-properties, postcss, postcss-value-parser); postcss-scss, stylelint-config-tailwindcss and stylelint-plugin-logical-css are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x. Upgrading from 2.x: docs/MIGRATING_TO_3.md.

Contributing and support

Development setup, semver policy, benchmarking and the release process are in CONTRIBUTING.md. Bugs and feature requests: GitHub issues. Security: see SECURITY.md.

License

MIT. See LICENSE.