stylelint-plugin-rhythmguard 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [1.4.2] - 2026-02-21
+
+### Changed
+
+- npm package artifact is now leaner by excluding non-runtime media assets from published files.
+- README media links now use absolute GitHub URLs so npm README rendering remains intact without bundling local media files.
+- Added a dedicated "Drop-In for Existing Projects" path with a single install command and a single config block.
+- Added comparison and migration guidance:
+  - `docs/COMPARISON.md` (`defensive-css` vs `logical-css` vs Rhythmguard + migration recipes)
+  - `docs/ADOPTION_DIFFS.md` (real before/after excerpts from public codebases)
+- Added Dev.to publishing assets:
+  - `docs/DEVTO_ORIGINAL_UPDATE_NOTE_2026-02-21.md`
+  - `docs/DEVTO_CONTINUATION_2026-02-21.md`
+
 ## [1.4.1] - 2026-02-21
 
 ### Fixed

package/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <img src="./assets/rhythmguard-banner.svg" width="100%" alt="Rhythmguard banner in Geist Pixel" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=3" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
 </p>
 
 # stylelint-plugin-rhythmguard
 
-High-precision spacing governance for CSS and design systems.
+Token governance for CSS and Tailwind. Enforce spacing scales, require design tokens, and catch arbitrary values before they ship.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/petrilahdelma/stylelint-plugin-rhythmguard/ci.yml?branch=main&label=ci)](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
@@ -12,30 +12,53 @@ High-precision spacing governance for CSS and design systems.
 [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18.18-black.svg)](https://nodejs.org/)
 
-`stylelint-plugin-rhythmguard` enforces scale and token discipline across spacing, radius, typography, size, and translate motion offsets.
+Rhythmguard enforces scale and token discipline across spacing, radius, typography, size, and motion offsets — in CSS declarations and Tailwind class strings.
 
-## Demo
+Built for teams that want:
 
-<p align="center">
-  <a href="./assets/rhythmguard-campaign-60s.webm">
-    <img src="./assets/rhythmguard-campaign-60s.gif" width="100%" alt="Rhythmguard 60-second demo" />
-  </a>
-</p>
+- 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
 
-I built Rhythmguard after 20 years of watching teams ignore spacing scales and ship arbitrary pixel values everywhere.
+## Quick Start: Next.js + Tailwind
 
-It is built for teams that want:
+```bash
+npm install --save-dev stylelint stylelint-plugin-rhythmguard
+```
+
+**.stylelintrc.json:**
+
+```json
+{
+  "extends": ["stylelint-plugin-rhythmguard/configs/tailwind"]
+}
+```
+
+**eslint.config.js** (for Tailwind class-string governance):
+
+```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] }
+      ],
+    },
+  },
+];
+```
 
-- zero random spacing values in production CSS
-- consistent numeric scales for radius, typography, and sizing primitives
-- token-first spacing workflows
-- predictable autofix behavior for large migrations
-- consistent layout rhythm across web surfaces
+This gives you spacing governance in both CSS files and JSX/TSX templates.
 
 ## Rule Matrix
 
 <p align="center">
-  <img src="./assets/rhythmguard-rules.svg" width="100%" alt="Rhythmguard rule matrix visual" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-rules.svg" width="100%" alt="Rhythmguard rule matrix visual" />
 </p>
 
 | Rule | What it does | Autofix |
@@ -44,15 +67,29 @@ It is built for teams that want:
 | `rhythmguard/prefer-token` | Enforces token usage over raw spacing literals | Yes, with `tokenMap` |
 | `rhythmguard/no-offscale-transform` | Enforces scale-aligned `translate*` motion offsets | Yes, nearest safe value |
 
+## Demo
+
+<p align="center">
+  <a href="https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/assets/rhythmguard-campaign-60s.webm">
+    <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-campaign-60s.gif" width="100%" alt="Rhythmguard 60-second demo" />
+  </a>
+</p>
+
+I built Rhythmguard after 20 years of watching teams ignore spacing scales and ship arbitrary pixel values everywhere.
+
 ## Installation
 
 ```bash
 npm install --save-dev stylelint stylelint-plugin-rhythmguard
 ```
 
-## Quick Start
+## Drop-In for Existing Projects (Recommended)
 
-### Recommended config
+If your project already uses Stylelint, you only need one command and one config block:
+
+```bash
+npm install --save-dev stylelint-plugin-rhythmguard
+```
 
 ```json
 {
@@ -60,24 +97,34 @@ npm install --save-dev stylelint stylelint-plugin-rhythmguard
 }
 ```
 
-### Strict config
+## Quick Start
+
+### Tailwind config
 
 ```json
 {
-  "extends": ["stylelint-plugin-rhythmguard/configs/strict"]
+  "extends": ["stylelint-plugin-rhythmguard/configs/tailwind"]
 }
 ```
 
-`strict` intentionally delegates transform translation enforcement to `rhythmguard/no-offscale-transform` to reduce overlapping warnings from `use-scale`.
+### Recommended config
 
-### Tailwind config
+```json
+{
+  "extends": ["stylelint-plugin-rhythmguard/configs/recommended"]
+}
+```
+
+### Strict config
 
 ```json
 {
-  "extends": ["stylelint-plugin-rhythmguard/configs/tailwind"]
+  "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
 
 ```json
@@ -108,15 +155,34 @@ npm install --save-dev stylelint stylelint-plugin-rhythmguard
 
 `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
+
+```json
+{
+  "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`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/FRAMEWORKS.md)
+
+## Comparison and Migration Recipes
+
+- Side-by-side tool fit guide with migration snippets: [`docs/COMPARISON.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/COMPARISON.md)
+- Real-world before/after excerpts from public repos: [`docs/ADOPTION_DIFFS.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/ADOPTION_DIFFS.md)
+- Distribution submissions to Stylelint discovery surfaces: [`docs/DISTRIBUTION.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/DISTRIBUTION.md)
+
 ### Full custom setup
 
 ```json
@@ -389,7 +455,7 @@ Options:
 | `mathFunctionArguments` | `Record<mathFn, number[]>` | `{}` | Restricts linting to specific 1-based argument indexes per math function |
 | `ignoreMathFunctionArguments` | `Record<mathFn, number[]>` | `{}` | Excludes specific 1-based argument indexes per math function |
 | `tokenMap` | `Record<string,string>` | `{}` | Enables autofix from raw value to token |
-| `tokenMapFile` | `string` | `null` | JSON file path to merge additional token mappings |
+| `tokenMapFile` | `string` | `null` | JSON file path to merge additional token mappings (supports flat, Style Dictionary, and W3C DTCG formats) |
 | `tokenMapFromCssCustomProperties` | `boolean` | `false` | Auto-builds mappings from matching custom property declarations in the same stylesheet |
 | `tokenMapFromTailwindSpacing` | `boolean` | `false` | Auto-builds mappings from `theme.spacing` and `theme.extend.spacing` in Tailwind config |
 | `tailwindConfigPath` | `string` | `null` | Path to Tailwind config used by `tokenMapFromTailwindSpacing` (`.js`, `.cjs`, `.mjs`) |
@@ -430,6 +496,12 @@ Rhythmguard works well in Tailwind projects, but it enforces what Stylelint can
 - 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`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/TAILWIND.md) for full setup.
+
 ### What Rhythmguard does not cover
 
 - Tailwind class strings in templates/JSX/TSX, for example:
@@ -460,6 +532,18 @@ export default [
 
 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:
@@ -501,6 +585,35 @@ 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:**
+
+```json
+{ "--spacing-4": "16px", "--spacing-3": "12px" }
+```
+
+**Style Dictionary:**
+
+```json
+{ "--spacing-4": { "value": "16px" } }
+```
+
+**W3C DTCG (Design Token Community Group):**
+
+```json
+{
+  "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:
@@ -545,6 +658,21 @@ Detailed methodology and custom args are documented in [`docs/BENCHMARKING.md`](
 ## Article
 
 - Dev.to: [Enforcing your spacing standards with Rhythmguard](https://dev.to/petrilahdelma/enforcing-your-spacing-standards-with-rhythmguard-a-custom-stylelint-plugin-1ojj)
+- Original article update note (Feb 21, 2026): [`docs/DEVTO_ORIGINAL_UPDATE_NOTE_2026-02-21.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/DEVTO_ORIGINAL_UPDATE_NOTE_2026-02-21.md)
+- Continuation draft (ready to publish): [`docs/DEVTO_CONTINUATION_2026-02-21.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/DEVTO_CONTINUATION_2026-02-21.md)
+
+## Used by and Community Examples
+
+Public codebases currently used for production migration examples:
+
+- [PetriLahdelma/digitaltableteur-nextjs](https://github.com/PetriLahdelma/digitaltableteur-nextjs)
+- [PetriLahdelma/digitaltableteur](https://github.com/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
 

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "1.4.1",
-  "description": "Stylelint plugin for spacing scale, token enforcement, and Tailwind class-string governance",
+  "version": "1.5.0",
+  "description": "Token governance for CSS and Tailwind — enforce spacing scales, require design tokens, catch arbitrary values",
+  "bin": {
+    "rhythmguard": "./src/cli/index.js"
+  },
   "keywords": [
     "stylelint",
     "stylelint-plugin",
@@ -46,6 +49,10 @@
       "require": "./src/configs/migration.js",
       "import": "./src/configs/migration.mjs"
     },
+    "./configs/react-tailwind": {
+      "require": "./src/configs/react-tailwind.js",
+      "import": "./src/configs/react-tailwind.mjs"
+    },
     "./presets": {
       "require": "./src/presets/index.js",
       "import": "./src/presets/index.mjs"
@@ -68,7 +75,6 @@
     }
   },
   "files": [
-    "assets",
     "scales",
     "schemas",
     "src",

package/src/cli/audit.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = process.argv.slice(3);
+const jsonMode = args.includes('--json');
+const dir = args.find((a) => !a.startsWith('-'));
+
+if (!dir) {
+  process.stderr.write('Usage: rhythmguard audit <dir> [--json]\n');
+  process.exit(1);
+}
+
+const resolvedDir = path.resolve(dir);
+
+if (!fs.existsSync(resolvedDir)) {
+  process.stderr.write(`Directory not found: ${dir}\n`);
+  process.exit(1);
+}
+
+const GLOB_PATTERN = `${resolvedDir}/**/*.{css,module.css}`;
+
+const pluginPath = path.resolve(__dirname, '..', 'index.js');
+
+async function run() {
+  const { default: stylelint } = await import('stylelint');
+
+  let result;
+  try {
+    result = await stylelint.lint({
+      files: GLOB_PATTERN,
+      config: {
+        plugins: [pluginPath],
+        rules: {
+          'rhythmguard/use-scale': [true, { severity: 'warning' }],
+          'rhythmguard/prefer-token': [
+            true,
+            {
+              tokenMapFromCssCustomProperties: true,
+              severity: 'warning',
+            },
+          ],
+        },
+      },
+    });
+  } catch (err) {
+    process.stderr.write(`Lint error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const fileResults = result.results || [];
+  const totalFiles = fileResults.length;
+
+  const offScaleValues = {};
+  const tokenOpportunities = {};
+  let filesWithIssues = 0;
+  let totalWarnings = 0;
+
+  for (const fileResult of fileResults) {
+    const warnings = fileResult.warnings || [];
+    if (warnings.length > 0) {
+      filesWithIssues++;
+    }
+
+    for (const warning of warnings) {
+      totalWarnings++;
+      const text = warning.text || '';
+
+      // Extract off-scale values from use-scale messages
+      // Format: Unexpected off-scale value "13px". Use scale values (nearest: 12px or 16px).
+      const offScaleMatch = text.match(
+        /Unexpected off-scale value "([^"]+)"/,
+      );
+      if (offScaleMatch) {
+        const value = offScaleMatch[1];
+        offScaleValues[value] = (offScaleValues[value] || 0) + 1;
+      }
+
+      // Extract token opportunities from prefer-token messages
+      // Format: Unexpected raw scale value "16px". Use design tokens for scale decisions.
+      const tokenMatch = text.match(
+        /Unexpected raw scale value "([^"]+)"/,
+      );
+      if (tokenMatch) {
+        const value = tokenMatch[1];
+        tokenOpportunities[value] = (tokenOpportunities[value] || 0) + 1;
+      }
+    }
+  }
+
+  const sortedOffScale = Object.entries(offScaleValues)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
+
+  const sortedTokenOps = Object.entries(tokenOpportunities)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
+
+  if (jsonMode) {
+    const output = {
+      directory: dir,
+      totalFiles,
+      filesWithIssues,
+      totalWarnings,
+      offScaleValues: Object.fromEntries(sortedOffScale),
+      tokenOpportunities: Object.fromEntries(sortedTokenOps),
+    };
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    return;
+  }
+
+  // Human-readable output
+  const pct = totalFiles > 0
+    ? Math.round((filesWithIssues / totalFiles) * 100)
+    : 0;
+
+  const lines = [
+    '',
+    `Rhythmguard Audit: ${dir}`,
+    '',
+    `Files scanned:     ${totalFiles}`,
+    `Files with issues: ${filesWithIssues} (${pct}%)`,
+    '',
+  ];
+
+  if (sortedOffScale.length > 0) {
+    const offScaleTotal = Object.values(offScaleValues).reduce(
+      (a, b) => a + b,
+      0,
+    );
+    lines.push(`Off-scale values: ${offScaleTotal}`);
+    for (const [value, count] of sortedOffScale) {
+      lines.push(`  ${value.padEnd(10)} ×${count}`);
+    }
+    lines.push('');
+  }
+
+  if (sortedTokenOps.length > 0) {
+    const tokenTotal = Object.values(tokenOpportunities).reduce(
+      (a, b) => a + b,
+      0,
+    );
+    lines.push(`Token opportunities: ${tokenTotal}`);
+    for (const [value, count] of sortedTokenOps) {
+      lines.push(`  ${value.padEnd(10)} ×${count}`);
+    }
+    lines.push('');
+  }
+
+  if (totalWarnings === 0) {
+    lines.push('No issues found. Your spacing is on scale.');
+  } else {
+    lines.push('Run "npx stylelint --fix" to auto-correct.');
+  }
+
+  lines.push('');
+  process.stdout.write(lines.join('\n'));
+}
+
+run();