npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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.

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.

npm version npm downloads License: MIT

<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-rhythmguard

You 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, with parser: tseslint.parser and files: ['**/*.{ts,tsx}']. JSX in .tsx needs no ecmaFeatures there.
  • Vue: vue-eslint-parser, usually through eslint-plugin-vue's flat configs. The rule checks static class attributes 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 through eslint-plugin-svelte's flat configs. The rule checks the static text of class attributes (class="p-[13px] {extra}"), the strings in class={...}, and class strings in <script>.
  • Astro: astro-eslint-parser, usually through eslint-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, class and *ClassName attributes, and object properties with those names: className="p-[13px]"
  • Arguments of cn, clsx, classnames, cx, cva, tv, twMerge and twJoin, with nested arrays, object keys and conditionals: cn("p-[13px]", condition && "m-[7px]"), cva("base", { variants: { size: { sm: "p-[5px]" } } })
  • tw tagged 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 rhythmguard

This 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.