stylelint-plugin-rhythmguard 1.4.2 → 1.6.0

package/CHANGELOG.md

@@ -6,6 +6,14 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-05-19
+
+### Added
+
+- `rhythmguard audit` now reports design-system drift across CSS declarations and Tailwind arbitrary spacing class strings.
+- Added `--format markdown` / `--markdown` audit output for PR-ready design-system health reports.
+- Audit JSON now includes format version, CSS findings, Tailwind class-string findings, scan counts, top affected files, and summary totals while preserving existing top-level count fields.
+
 ## [1.4.2] - 2026-02-21
 
 ### Changed

package/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/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,25 +12,48 @@ 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="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>
+- 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
 
@@ -44,6 +67,44 @@ 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.
+
+## Try It in Your Browser
+
+**[petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/)** — paste CSS, see violations and token opportunities live. No install, no config.
+
+## Audit Before You Enforce
+
+Use the audit CLI to create a design-system drift report before turning rules into hard CI gates:
+
+```bash
+npx rhythmguard audit ./src
+npx rhythmguard audit ./src --format markdown
+npx rhythmguard audit ./src --json
+```
+
+The report covers authored CSS declarations and Tailwind arbitrary spacing values in common template/source files. Markdown output is PR-ready for UX developers, UX designers, and design-system owners:
+
+```md
+# Rhythmguard Design-System Audit
+
+| Metric | Value |
+| --- | ---: |
+| CSS files scanned | 47 |
+| Template files scanned | 83 |
+| Files with issues | 12 |
+| Total findings | 52 |
+| Scale cleanliness | 91% |
+```
+
 ## Installation
 
 ```bash
@@ -66,32 +127,32 @@ npm install --save-dev stylelint-plugin-rhythmguard
 
 ## Quick Start
 
-### Recommended config
+### Tailwind config
 
 ```json
 {
-  "extends": ["stylelint-plugin-rhythmguard/configs/recommended"]
+  "extends": ["stylelint-plugin-rhythmguard/configs/tailwind"]
 }
 ```
 
-### Strict config
+### Recommended config
 
 ```json
 {
-  "extends": ["stylelint-plugin-rhythmguard/configs/strict"]
+  "extends": ["stylelint-plugin-rhythmguard/configs/recommended"]
 }
 ```
 
-`strict` intentionally delegates transform translation enforcement to `rhythmguard/no-offscale-transform` to reduce overlapping warnings from `use-scale`.
-
-### Tailwind config
+### 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
@@ -122,18 +183,32 @@ npm install --save-dev 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)
+- Audit 2.0 validation and roadmap: [`docs/AUDIT_2_VALIDATION.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/AUDIT_2_VALIDATION.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)
 
@@ -409,7 +484,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`) |
@@ -450,13 +525,19 @@ Rhythmguard works well in Tailwind projects, but it enforces what Stylelint can
 - CSS Modules (for example `*.module.css`)
 - declarations inside `@layer` blocks
 
-### What Rhythmguard does not cover
+### 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 the Stylelint layer 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.
+Those are not Stylelint declaration nodes, so they are outside Stylelint rule scope. Use the ESLint companion rule below for scale-aware class-string enforcement.
 
 ### Companion ESLint layer for class strings
 
@@ -480,6 +561,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:
@@ -498,7 +591,7 @@ Suggested setup:
 Then pair with:
 
 - `stylelint-plugin-rhythmguard/eslint` for arbitrary spacing class-string scale enforcement.
-- `eslint-plugin-tailwindcss` for broader class-string linting and conventions.
+- `eslint-plugin-tailwindcss` for broader class-string linting and conventions. If your policy is to ban every arbitrary value, enable its `tailwindcss/no-arbitrary-value` rule; use Rhythmguard when you want spacing-specific scale checks and nearest-value fixes.
 - `prettier-plugin-tailwindcss` for deterministic class ordering.
 
 Detailed setup reference: [`docs/TAILWIND.md`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/TAILWIND.md).
@@ -521,6 +614,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:
@@ -565,8 +687,6 @@ 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
 

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "1.4.2",
-  "description": "Stylelint plugin for spacing scale, token enforcement, and Tailwind class-string governance",
+  "version": "1.6.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"
@@ -92,7 +99,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/petrilahdelma/stylelint-plugin-rhythmguard.git"
+    "url": "https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard"
   },
   "homepage": "https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#readme",
   "bugs": {