Token governance for CSS and Tailwind. Enforce spacing scales, require design tokens, and catch arbitrary values before they ship.

Rhythmguard enforces scale and token discipline across spacing, radius, typography, size, and motion offsets — in CSS declarations and Tailwind class strings.

Built for teams that want:

• zero random spacing values in production
• token-first workflows with autofix migration
• Tailwind arbitrary value governance (p-[13px] → p-[12px])
• consistent layout rhythm across components and pages

Quick Start: Next.js + Tailwind

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

.stylelintrc.json:

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

eslint.config.js (for Tailwind class-string governance):

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] }
      ],
    },
  },
];

This gives you spacing governance in both CSS files and JSX/TSX templates.

Rule Matrix

Demo

I built Rhythmguard after 20 years of watching teams ignore spacing scales and ship arbitrary pixel values everywhere.

Try It in Your Browser

petrilahdelma.github.io/stylelint-plugin-rhythmguard — paste CSS, see violations and token opportunities live. No install, no config.

Installation

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

Drop-In for Existing Projects (Recommended)

If your project already uses Stylelint, you only need one command and one config block:

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

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

Quick Start

Tailwind config

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

Recommended config

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

Strict config

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

strict intentionally delegates transform translation enforcement to rhythmguard/no-offscale-transform to reduce overlapping warnings from use-scale.

Expanded config

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

expanded enables scale enforcement for spacing + radius + typography + size property groups.

Logical config

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

logical composes Rhythmguard strict mode with stylelint-plugin-logical-css recommended rules.

Migration config

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

migration keeps on-scale numeric values temporarily while auto-building token mappings from CSS custom properties and optional Tailwind spacing config.

React / Next.js + Tailwind config

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

react-tailwind extends the tailwind config with CSS Modules overrides (spacing + radius enforcement) and ignores Next.js build directories.

Stable shared config entry points:

• stylelint-plugin-rhythmguard/configs/recommended
• stylelint-plugin-rhythmguard/configs/strict
• stylelint-plugin-rhythmguard/configs/tailwind
• stylelint-plugin-rhythmguard/configs/react-tailwind
• stylelint-plugin-rhythmguard/configs/expanded
• stylelint-plugin-rhythmguard/configs/logical
• stylelint-plugin-rhythmguard/configs/migration

Framework-specific setup for Vue, Lit, Astro, and SvelteKit: docs/FRAMEWORKS.md

Comparison and Migration Recipes

• Side-by-side tool fit guide with migration snippets: docs/COMPARISON.md
• Real-world before/after excerpts from public repos: docs/ADOPTION_DIFFS.md
• Distribution submissions to Stylelint discovery surfaces: docs/DISTRIBUTION.md

Full custom setup

{
  "plugins": ["stylelint-plugin-rhythmguard"],
  "rules": {
    "rhythmguard/use-scale": [
      true,
      {
        "preset": "rhythmic-4",
        "propertyGroups": ["spacing", "radius"],
        "propertyScales": {
          "font-size": [12, 14, 16, 20, 24]
        },
        "units": ["px", "rem", "em"],
        "unitStrategy": "convert",
        "baseFontSize": 16,
        "tokenPattern": "^--space-",
        "tokenFunctions": ["var", "theme", "token"],
        "allowNegative": true,
        "allowPercentages": true,
        "fixToScale": true,
        "enforceInsideMathFunctions": true,
        "mathFunctionArguments": {
          "clamp": [1, 3]
        }
      }
    ],
    "rhythmguard/prefer-token": [
      true,
      {
        "tokenPattern": "^--space-",
        "allowNumericScale": false,
        "tokenMapFromCssCustomProperties": true,
        "tokenMapFromTailwindSpacing": true,
        "tailwindConfigPath": "./tailwind.config.mjs",
        "tokenMap": {
          "4px": "var(--space-1)",
          "8px": "var(--space-2)",
          "12px": "var(--space-3)",
          "16px": "var(--space-4)"
        }
      }
    ],
    "rhythmguard/no-offscale-transform": [
      true,
      {
        "scale": [0, 4, 8, 12, 16, 24, 32]
      }
    ]
  }
}

Presets and custom scales

Preset-based setup:

{
  "rules": {
    "rhythmguard/use-scale": [true, { "preset": "fibonacci" }]
  }
}

Custom scale setup:

{
  "rules": {
    "rhythmguard/use-scale": [true, { "customScale": [0, 6, 12, 18, 24, 36, 48] }]
  }
}

Scale resolution precedence:

1. customScale (highest priority)
2. scale
3. preset
4. default rhythmic-4 scale

Option Validation

Rhythmguard validates secondaryOptions for each rule before linting declarations.

• Unknown option names fail fast with Stylelint invalid option warnings.
• Invalid option shapes fail fast (for example string vs array mismatches).
• properties string entries are validated against supported scale-targetable CSS property names.
• propertyGroups values are validated against built-in groups: spacing, radius, typography, and size.
• Math function argument maps are validated per function (calc, clamp, min, max) and positive 1-based argument indexes.

Example typo that now fails immediately:

{
  "rules": {
    "rhythmguard/use-scale": [true, { "sevverity": "warning" }]
  }
}

Built-in Scale Presets

Aliases:

• 4pt → rhythmic-4
• 8pt → rhythmic-8
• material → product-material-8dp
• atlassian-8 → product-atlassian-8px
• carbon → product-carbon-2x
• baseline-4 → editorial-baseline-4
• baseline-6 → editorial-baseline-6
• golden → golden-ratio
• major-second → modular-major-second
• minor-third → modular-minor-third
• major-third → modular-major-third
• augmented-fourth → modular-augmented-fourth
• perfect-fourth → modular-perfect-fourth
• perfect-fifth → modular-perfect-fifth

Preset Rationale

• Product presets are based on widely-used design-system spacing frameworks.
• Editorial presets model baseline-grid cadence used in long-form typography and column layouts.
• Theory presets expose mathematically-derived modular scales from design theory and typographic proportion systems.
• Full research notes and sources are documented in docs/SCALE_RESEARCH.md.

Community Scale Registry

Rhythmguard supports community-contributed scale presets from scales/community/*.json.

Current community scales

Contribute a scale

1. Scaffold a new scale file:

npm run scales:add -- --name my-team-scale --base 8 --steps 0,4,8,12,16,24,32

2. Validate:

npm run scales:validate

3. Open a PR with your scale JSON.

Full specification and policy: docs/COMMUNITY_SCALES.md.

If your scale is private or very niche, keep it in your project config with customScale instead of contributing it to the shared registry.

Rule Details

rhythmguard/use-scale

Enforces spacing literals to stay on a configured numeric scale.

Checks:

• margin*, padding*
• gap, row-gap, column-gap
• inset*, scroll-margin*, scroll-padding*
• translate, translate-x, translate-y, translate-z
• transform translation functions (translate, translateX, translateY, translateZ, translate3d)
• optional property groups:
  • radius (border-radius*, corner radii, outline-offset)
  • typography (font-size, line-height, letter-spacing, word-spacing)
  • size (width, height, min/max size, logical inline-size/block-size)

Example:

/* ❌ Off-scale */
.card {
  margin: 13px;
  transform: translateY(18px);
}

/* ✅ On-scale */
.card {
  margin: 12px;
  transform: translateY(16px);
}

Options:

rhythmguard/prefer-token

Enforces token usage for spacing declarations. This is ideal once your token system is stable.

Example:

/* ❌ Raw literals */
.stack {
  gap: 12px;
  padding: 16px;
}

/* ✅ Tokenized */
.stack {
  gap: var(--space-3);
  padding: var(--space-4);
}

Options:

rhythmguard/no-offscale-transform

Specialized guardrail for motion spacing consistency in translation transforms.

Example:

/* ❌ Off-scale motion */
.toast {
  transform: translateY(18px) scale(1);
}

/* ✅ Motion on spacing scale */
.toast {
  transform: translateY(16px) scale(1);
}

Options:

rhythmguard/no-offscale-transform accepts the same scale options as rhythmguard/use-scale (including unitStrategy, math argument targeting, and deterministic autofix), but only for transform translation properties. Its secondary options are also validated for unknown keys and invalid value shapes.

Tailwind CSS Integration

Rhythmguard works well in Tailwind projects, but it enforces what Stylelint can parse: CSS declarations.

What Rhythmguard covers in Tailwind projects

• custom CSS in globals.css, components.css, utilities.css
• CSS Modules (for example *.module.css)
• declarations inside @layer blocks

Tailwind v4 @theme tokens

The tailwind config preset automatically extracts spacing tokens from Tailwind v4 @theme blocks and uses them for prefer-token enforcement. Raw values like padding: 16px are autofixed to padding: var(--spacing-4).

See docs/TAILWIND.md for full setup.

What Rhythmguard does not cover

• Tailwind class strings in templates/JSX/TSX, for example:
  • class="p-4 gap-2"
  • class="p-[13px] translate-y-[18px]"

Those are not Stylelint declaration nodes, so they are outside Stylelint rule scope.

Companion ESLint layer for class strings

Rhythmguard now ships an ESLint companion export for class-string governance:

// eslint.config.js (flat config)
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] }],
    },
  },
];

This rule targets arbitrary spacing utilities such as p-[13px], gap-[18px], translate-x-[10px], and autofixes to the nearest configured scale value.

Supported patterns

The rule checks every string literal in your code, so it works automatically with common utility functions:

• cn("p-[13px]") / cn("p-[13px]", condition && "m-[7px]")
• clsx("p-[13px]", "gap-[18px]")
• twMerge("p-[13px]", otherClasses)
• cva("base", { variants: { size: { sm: "p-[5px]" } } })
• <div className={cn("p-[13px]")} />

No extra config needed — if the string contains an arbitrary spacing value, it gets caught and autofixed.

Recommended stack for full Tailwind enforcement

Use both layers:

1. Stylelint + Rhythmguard for CSS declaration governance.
2. Tailwind-aware class-string linting/formatting for template utility usage.

Suggested setup:

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

Then pair with:

• stylelint-plugin-rhythmguard/eslint for arbitrary spacing class-string scale enforcement.
• eslint-plugin-tailwindcss for broader class-string linting and conventions.
• prettier-plugin-tailwindcss for deterministic class ordering.

Detailed setup reference: docs/TAILWIND.md.

Tailwind token function support

By default, tokenFunctions includes theme, so values like theme(spacing.4) are treated as tokenized values.

This keeps CSS declaration enforcement and template class-string enforcement separated but coordinated.

Programmatic Presets

const rhythmguard = require('stylelint-plugin-rhythmguard');

console.log(rhythmguard.presets.listScalePresetNames());
console.log(rhythmguard.presets.listCommunityScalePresetNames());
console.log(rhythmguard.presets.getCommunityScaleMetadata('product-decimal-10'));
console.log(rhythmguard.presets.scales['rhythmic-4']);
console.log(Object.keys(rhythmguard.eslint.rules));

Token File Formats

The tokenMapFile option supports multiple JSON formats:

Flat token-to-value:

{ "--spacing-4": "16px", "--spacing-3": "12px" }

Style Dictionary:

{ "--spacing-4": { "value": "16px" } }

W3C DTCG (Design Token Community Group):

{
  "spacing": {
    "4": { "$value": "16px", "$type": "dimension" },
    "2": { "$value": "8px", "$type": "dimension" }
  }
}

Nested DTCG groups are walked recursively. The key path becomes the CSS variable name: spacing.4 → var(--spacing-4). Non-length values (colors, fonts) are ignored automatically.

Autofix Philosophy

Rhythmguard only applies deterministic fixes:

• nearest scale value for numeric off-scale literals
• explicit tokenMap replacements for token migration

It will not guess token mappings without your map.

Compatibility

• Stylelint: ^16.0.0 || ^17.0.0
• Node.js: >=18.18.0
• Module format: dual require + import entry points (CommonJS + ESM wrappers)
• Note: Stylelint 16.0.0 has known autofix/API behavior differences; CI enforces floor compatibility and runs non-blocking full-suite observability on the floor version.

Development

npm install
npm run lint
npm test
npm run test:coverage

Performance Benchmarking

Compare runtime against stylelint-scales on a deterministic spacing corpus:

npm run bench:perf

Benchmark with autofix enabled:

npm run bench:perf:fix

Detailed methodology and custom args are documented in docs/BENCHMARKING.md.

Article

• Dev.to: Enforcing your spacing standards with Rhythmguard

Used by and Community Examples

Public codebases currently used for production migration examples:

• PetriLahdelma/digitaltableteur-nextjs
• PetriLahdelma/digitaltableteur

Want your team listed here?

1. Open an issue with used-by in the title.
2. Include one before/after diff and your Rhythmguard config.
3. Add migration notes (false positives, rules enabled, rollout phase).

Release Workflow

1. Create a GitHub release.
2. release.yml runs the Node/Stylelint matrix validation.
3. A tarball smoke test validates package exports and install behavior.
4. If NPM_TOKEN is configured in repository secrets, the package is published to npm with provenance (npm publish --provenance).
5. If NPM_TOKEN is not configured, publish is skipped with an explicit workflow notice.
6. post-publish-smoke.yml verifies the published npm version can be installed and run in a clean project (and skips cleanly if the version is not on npm).

Support and Bug Reports

• Open an issue: https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/issues
• Security reports and direct contact: hello@petrilahdelma.com

License

MIT. See LICENSE.