eslint-plugin-rhythmguard
v3.20.1
Published
ESLint rules that keep Tailwind arbitrary spacing and motion values in class strings on your design scale. The ESLint companion of stylelint-plugin-rhythmguard, as its own package.
Maintainers
Readme
eslint-plugin-rhythmguard
Nobody chose 13px. This plugin catches off-scale Tailwind arbitrary spacing in class strings, tells you the utility classes for the nearest steps on your scale, and writes the right class when you run --fix.
<div className="p-[13px] md:gap-[18px]" />1:16 warning Unexpected Tailwind arbitrary spacing value "p-[13px]". Use "p-3" (12px) or "p-4" (16px)
1:16 warning Unexpected Tailwind arbitrary spacing value "md:gap-[18px]". Use "gap-4" (16px) or "gap-6" (24px)--fix writes p-3 and md:gap-4. Variants, negative signs and important markers are kept: md:-m-[13px]! becomes md:-m-3!.
Why this and not a ban
Most Tailwind lint rules either forbid arbitrary values outright or rewrite them to an equivalent class, and an equivalent of 13px is still 13px. This rule asks a different question: is the value one of the steps your design system allows? p-[12px] passes on a 4px scale, p-[13px] does not, and the finding names the two classes you probably meant.
The same TSX file through each tool, default Tailwind theme, scale [0, 4, 8, 12, 16, 24, 32] for Rhythmguard:
| Class | better-tailwindcss 4.10.0 | eslint-plugin-tailwindcss 4.4.0 | @shadcn/lint 0.2.5 | Rhythmguard |
| --- | --- | --- | --- | --- |
| p-[13px] | no finding | no finding | Use p-3.25 "(same value, on the scale)" | Use p-3 (12px) or p-4 (16px) |
| p-[0.8125rem] | Simplify to p-3.25 | Write as p-3.25 | Use a theme token or scale value | Use p-3 (12px) or p-4 (16px) |
| p-[12px] | no finding | Use p-3 | Use p-3 | no finding (on the scale) |
| p-3.25 | no finding | no finding | no finding | no finding |
The last row is the gap every tool shares, this one included: Tailwind v4 accepts any quarter step as a plain class, and nothing checks p-3.25 against a scale. Rhythmguard catches the value before it is rewritten. Rerun the comparison with node scripts/bench/tailwind-compare.mjs in the repository; full table.
Install
npm install --save-dev eslint eslint-plugin-rhythmguardYou do not need Stylelint. The plugin adds 8 packages to an ESLint install and no peer warnings; 3.15.0 also pulled in Stylelint, 101 packages. The rhythmguard audit command needs it only for stylesheets: in a project without Stylelint it audits your class strings, lists the stylesheets it could not read with npm install --save-dev stylelint, and fails any gate flag (--max-findings, --min-cleanliness, --fail-on-new-drift) rather than pass on a partial read.
Configure
// eslint.config.js
import rhythmguard from 'eslint-plugin-rhythmguard';
export default [
{
files: ['**/*.{js,jsx,mjs,cjs}'],
languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },
plugins: { 'rhythmguard-tailwind': rhythmguard },
rules: {
'rhythmguard-tailwind/tailwind-class-use-scale': ['error', { scale: [0, 4, 8, 12, 16, 24, 32] }],
},
},
];files and ecmaFeatures.jsx are what make ESLint lint .jsx: without them a flat config lints only .js, .mjs and .cjs, and JSX is a parsing error.
Or start from the recommended config, which turns the spacing rule on as a warning with the default scale:
import rhythmguard from 'eslint-plugin-rhythmguard';
export default [
{
files: ['**/*.{js,jsx,mjs,cjs}'],
languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },
plugins: { 'rhythmguard-tailwind': rhythmguard },
rules: rhythmguard.configs.recommended.rules,
},
];configs.recommended also registers the plugin, so it works as a config object of its own: export default [rhythmguard.configs.recommended] lints .js, .mjs and .cjs, and { ...rhythmguard.configs.recommended, files: ['**/*.{js,jsx,mjs,cjs}'], languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } } } adds JSX.
Other file types
Espree, ESLint's default parser, reads JavaScript and JSX only. Other files need their parser in languageOptions.parser, in a config block whose files matches them, with the plugin and rule added to that block:
- TypeScript (
.ts,.tsx):typescript-eslint, withparser: tseslint.parserandfiles: ['**/*.{ts,tsx}']. JSX in.tsxneeds noecmaFeaturesthere. - Vue:
vue-eslint-parser, usually througheslint-plugin-vue's flat configs. The rule checks staticclassattributes in<template>, the strings in bound classes (:class="{ 'p-[13px]': on }"), and class strings in<script>(see What gets checked). - Svelte:
svelte-eslint-parser, usually througheslint-plugin-svelte's flat configs. The rule checks the static text ofclassattributes (class="p-[13px] {extra}"), the strings inclass={...}, and class strings in<script>. - Astro:
astro-eslint-parser, usually througheslint-plugin-astro's flat configs.
Set scale to your design system's spacing steps in px. The rule does not read your Tailwind theme; the Stylelint plugin does that for stylesheets (see below).
Oxlint
The rules run unchanged through Oxlint's JS plugin support:
// .oxlintrc.json
{
"jsPlugins": [{ "name": "rhythmguard-tailwind", "specifier": "eslint-plugin-rhythmguard" }],
"rules": {
"rhythmguard-tailwind/tailwind-class-use-scale": ["error", { "scale": [0, 4, 8, 12, 16, 24, 32] }]
}
}CI runs this config on Oxlint 1.88.0, on TSX, for both findings and --fix. Oxlint's JS plugins are alpha, and Oxlint does not lint Vue or Svelte templates, so keep ESLint for those files.
Adopting it on an existing codebase
ESLint's bulk suppressions (ESLint 9.24 or newer) record today's findings so that CI fails only on new ones. You need no Rhythmguard baseline file:
npx eslint --suppress-rule rhythmguard-tailwind/tailwind-class-use-scale .That writes eslint-suppressions.json with a count per file and rule. Commit it. Later runs report a finding only when a file has more than its recorded count. When a fix brings a count down, npx eslint --prune-suppressions . lowers the record, so the old values cannot come back unnoticed.
Rules
| Rule | What it reports | Fix |
| --- | --- | --- |
| tailwind-class-use-scale | Off-scale arbitrary spacing values (p-[13px], gap-[18px], -m-[7px]) in class strings | The utility class for the nearest step; none for negative padding or gap, which Tailwind does not generate |
| tailwind-class-use-motion-scale | Off-scale duration-[...] and delay-[...], raw ease-[...]. Opt-in | Nearest duration |
What gets checked
Class strings, not every string, so --fix never rewrites a type union, an enum member, an aria-label or a title:
className,classand*ClassNameattributes, and object properties with those names:className="p-[13px]"- Arguments of
cn,clsx,classnames,cx,cva,tv,twMergeandtwJoin, with nested arrays, object keys and conditionals:cn("p-[13px]", condition && "m-[7px]"),cva("base", { variants: { size: { sm: "p-[5px]" } } }) twtagged templates:tw`p-[13px]`<div class="p-[13px]">in Vue and Svelte templates, with their parsers (see Other file types)- Any other string with two or more utility-shaped tokens:
const base = "flex p-[13px]"
Type positions (literal types, enum members, interface members) and every other attribute (aria-*, title, id, data-*, alt, placeholder, component props) are never checked. Add your own helpers and attributes with classFunctions and classContexts.
Padding, margin, gap, inset, space and translate utilities, with their axis and side variants and any variant prefix (md:, hover:, has-[>button]:). rem and em values are converted through baseFontSize.
Options for tailwind-class-use-scale
| Option | Default | What it does |
| --- | --- | --- |
| scale | Tailwind's default ladder | Allowed spacing values in px. Without it, the steps of Tailwind's default theme on spacingUnit (0, 2, 4, 6, 8, 10, 12, 14, 16, 20, ... 384 on a 16px root), and messages end with Scale: Tailwind default spacing. Before 3.20 the default stopped at 32. Set scale to your project's scale when it is not Tailwind's |
| units | ['px', 'rem', 'em'] | Units the rule checks |
| baseFontSize | 16 | Base for converting rem and em |
| classFunctions | [] | More function and tagged-template names whose arguments are class strings, added to cn, clsx, classnames, cx, cva, tv, twMerge, twJoin and tw |
| classContexts | [] | More JSX attribute and object property names whose values are class strings, added to class, className and *ClassName. A leading * matches by suffix |
| allowHairlines | true | Skips non-zero lengths of one CSS pixel or less (translate-y-[0.5px], -mt-[1px], p-[0.0625rem]), as the Stylelint rules do. false reports them |
| allowNegative | true | Whether negative arbitrary values (m-[-8px], -m-[8px]) are allowed |
| spacingUnit | baseFontSize / 4 (4) | Px per Tailwind spacing step (0.25rem), used to name and write classes. false keeps the fix in arbitrary form (p-[12px]) |
| note | none | A sentence added to every finding, such as "See docs/spacing.md for approved exceptions." Up to 200 characters |
Full reference, including how the fix chooses between p-3 and p-[12px]: rule docs.
The rest of Rhythmguard
Class strings are one place spacing drifts. stylelint-plugin-rhythmguard covers CSS, SCSS and CSS Modules, reads your scale from your own tokens (Tailwind @theme, custom properties, Sass maps, DTCG files), and ships an audit that measures drift across a codebase and fails CI only on new drift. Try it with no install:
npx rhythmguardThis package re-exports stylelint-plugin-rhythmguard/eslint, so the rules, options and messages are one implementation. If you already use the Stylelint plugin, that import works too.
Compatibility
ESLint 8 or newer with flat config; tested on ESLint 9 and checked on ESLint 10. Node 20.19 or newer. Stylelint is not required. TypeScript declarations included.
License
MIT. Issues and contributions: github.com/PetriLahdelma/stylelint-plugin-rhythmguard.
