stylelint-plugin-rhythmguard 1.8.0 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-05-23
+
+### Changed
+
+- `rhythmguard audit --format json` now emits the stable audit contract with `schemaVersion: "2.0"`.
+- Moved the pre-2.0 audit JSON shape to `--format json-v1` for migration compatibility.
+- Updated audit defaults to use the explicit spacing token pattern `^--(space|spacing)-`.
+
+### Added
+
+- Added `stylelint-plugin-rhythmguard/audit` with `createAuditReport`, `loadAuditConfig`, `parseTokenSources`, and `toAuditContractReport`.
+- Added `rhythmguard audit --format html`, `--output <file>`, and `--schema`.
+- Added `rhythmguard doctor` checks for `.rhythmguardrc.json`, configured token sources, motion audit config, and baseline files.
+- Added `docs/MIGRATING_TO_2.md`.
+
+## [1.9.0] - 2026-05-23
+
+### Added
+
+- Added opt-in `rhythmguard/use-motion-scale` for duration/delay scale enforcement and raw easing reporting.
+- Added `stylelint-plugin-rhythmguard/configs/motion`.
+- Added ESLint companion rule `rhythmguard-tailwind/tailwind-class-use-motion-scale` for Tailwind `duration-[...]`, `delay-[...]`, and `ease-[...]` arbitrary values.
+- Added `rhythmguard audit --include-motion` and `.rhythmguardrc.json` `includeMotion` support.
+
 ## [1.8.0] - 2026-05-23
 
 ### Added

package/README.md

@@ -66,6 +66,7 @@ This gives you spacing governance in both CSS files and JSX/TSX templates.
 | `rhythmguard/use-scale` | Enforces spacing values must be on your configured scale | Yes, nearest safe value |
 | `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 |
+| `rhythmguard/use-motion-scale` | Enforces opt-in duration/delay rhythm and flags raw easing curves | Yes, for duration/delay values |
 
 ## Demo
 
@@ -95,9 +96,12 @@ npx rhythmguard audit ./src --since-baseline --fail-on-new-drift
 npx rhythmguard audit ./src --staged --max-findings 0
 npx rhythmguard audit ./src --token-source ./tokens.json
 npx rhythmguard audit ./src --token-source ./theme.css --token-source-format css
+npx rhythmguard audit ./src --include-motion
+npx rhythmguard audit ./src --format html --output rhythmguard-report.html
+npx rhythmguard audit --schema
 ```
 
-The report covers authored CSS declarations, Tailwind arbitrary spacing values in common template/source files, and token-contract drift such as missing spacing tokens, unused spacing tokens, repeated raw values that deserve token review, raw values that match known tokens, and conflicting token values. Scan paths are scoped to the directory argument. Use `--ignore`, `.rhythmguardignore`, or `--ignore-path` for generated or legacy subtrees, then add baselines and CI thresholds when you are ready to gate new drift. Markdown output is PR-ready for UX developers, UX designers, and design-system owners:
+The report covers authored CSS declarations, Tailwind arbitrary spacing values in common template/source files, and token-contract drift such as missing spacing tokens, unused spacing tokens, repeated raw values that deserve token review, raw values that match known tokens, conflicting token values, and opt-in motion rhythm drift. Scan paths are scoped to the directory argument. Use `--ignore`, `.rhythmguardignore`, or `--ignore-path` for generated or legacy subtrees, then add baselines and CI thresholds when you are ready to gate new drift. Markdown output is PR-ready for UX developers, UX designers, and design-system owners:
 
 ```md
 # Rhythmguard Design-System Audit
@@ -125,6 +129,7 @@ For large codebases, put shared audit settings in `.rhythmguardrc.json`:
       { "path": "./src/theme.css", "format": "css" }
     ],
     "tokenKind": "spacing",
+    "includeMotion": false,
     "tokenCandidateMinCount": 2,
     "minCleanliness": 90
   }
@@ -133,6 +138,44 @@ For large codebases, put shared audit settings in `.rhythmguardrc.json`:
 
 `rhythmguard audit` loads `.rhythmguardrc.json` automatically when present. Use `--config <file>` for another config, `--no-config` to skip config discovery, and `--token-source <file>` for extra canonical token files. Token source paths in config files resolve from the config file directory; CLI token source paths resolve from the current working directory. Supported source formats are CSS custom properties and Tailwind v4 `@theme`, flat JSON maps, Style Dictionary JSON, and DTCG JSON.
 
+### Audit JSON 2.0 and API
+
+In Rhythmguard 2.0, `--format json` emits the stable audit contract:
+
+```json
+{
+  "schemaVersion": "2.0",
+  "command": { "directory": "./src", "scanScope": "full" },
+  "summary": { "totalFindings": 12, "scaleCleanliness": 94 },
+  "scanned": { "cssFiles": 10, "templateFiles": 20 },
+  "contracts": {
+    "scale": {},
+    "tokens": {},
+    "motion": {}
+  },
+  "findings": {
+    "css": [],
+    "tailwind": [],
+    "motion": []
+  },
+  "baseline": null
+}
+```
+
+Use `--format json-v1` for the pre-2.0 JSON shape during migration.
+
+Programmatic usage:
+
+```js
+const {
+  createAuditReport,
+  toAuditContractReport,
+} = require('stylelint-plugin-rhythmguard/audit');
+
+const report = await createAuditReport({ dir: './src', noConfig: true });
+const contract = toAuditContractReport(report);
+```
+
 ## Installation
 
 ```bash
@@ -221,6 +264,16 @@ npm install --save-dev stylelint-plugin-rhythmguard
 
 `react-tailwind` extends the tailwind config with CSS Modules overrides (spacing + radius enforcement) and ignores Next.js build directories.
 
+### Motion config
+
+```json
+{
+  "extends": ["stylelint-plugin-rhythmguard/configs/motion"]
+}
+```
+
+`motion` enables opt-in duration/delay rhythm checks with `rhythmguard/use-motion-scale`.
+
 Stable shared config entry points:
 
 - `stylelint-plugin-rhythmguard/configs/recommended`
@@ -230,6 +283,7 @@ Stable shared config entry points:
 - `stylelint-plugin-rhythmguard/configs/expanded`
 - `stylelint-plugin-rhythmguard/configs/logical`
 - `stylelint-plugin-rhythmguard/configs/migration`
+- `stylelint-plugin-rhythmguard/configs/motion`
 
 Framework-specific setup for Vue, Lit, Astro, and SvelteKit: [`docs/FRAMEWORKS.md`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/FRAMEWORKS.md)
 
@@ -471,7 +525,7 @@ Options:
 | `enforceInsideMathFunctions` | `boolean` | `false` | Lints `calc()/clamp()/min()/max()` internals |
 | `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 |
-| `propertyGroups` | `Array<'spacing' \| 'radius' \| 'typography' \| 'size'>` | `['spacing']` | Selects built-in property groups when `properties` is not provided |
+| `propertyGroups` | `Array<'spacing' \| 'radius' \| 'typography' \| 'size' \| 'motion'>` | `['spacing']` | Selects built-in property groups when `properties` is not provided |
 | `properties` | `Array<string|RegExp>` | built-in spacing patterns | Override targeted property set; string values may be supported property names or regex-like strings (`/pattern/flags`) |
 | `propertyScales` | `Record<propertyOrRegex, scaleOrPreset>` | `{}` | Per-property scale overrides (supports exact names or `/regex/flags` keys; stateful `g`/`y` flags are normalized for deterministic matching) |
 
@@ -543,6 +597,35 @@ 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.
 
+### `rhythmguard/use-motion-scale`
+
+Opt-in guardrail for duration, delay, and easing rhythm.
+
+Example:
+
+```css
+/* ❌ Off-scale timing + raw easing */
+.button {
+  transition: opacity 175ms cubic-bezier(.2, 0, 0, 1);
+}
+
+/* ✅ Timing on motion scale */
+.button {
+  transition: opacity 150ms var(--ease-snappy);
+}
+```
+
+Options:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `durationScale` | `number[]` | `[0,75,100,150,200,300,500,700,1000]` | Allowed duration and delay values in milliseconds |
+| `durationUnits` | `Array<'ms' \| 's'>` | `['ms','s']` | Time units considered by the rule |
+| `fixToScale` | `boolean` | `true` | Autofixes simple duration/delay values to the nearest scale value |
+| `easingTokenMap` | `Record<string,string>` | `{}` | Optional exact replacements for raw easing functions |
+
+Tailwind class strings can use the ESLint companion rule `rhythmguard-tailwind/tailwind-class-use-motion-scale` for `duration-[...]`, `delay-[...]`, and `ease-[...]` arbitrary values.
+
 ## Tailwind CSS Integration
 
 Rhythmguard works well in Tailwind projects, but it enforces what Stylelint can parse: CSS declarations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "Token governance for CSS and Tailwind — enforce spacing scales, require design tokens, catch arbitrary values",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -49,6 +49,10 @@
       "require": "./src/configs/migration.js",
       "import": "./src/configs/migration.mjs"
     },
+    "./configs/motion": {
+      "require": "./src/configs/motion.js",
+      "import": "./src/configs/motion.mjs"
+    },
     "./configs/react-tailwind": {
       "require": "./src/configs/react-tailwind.js",
       "import": "./src/configs/react-tailwind.mjs"
@@ -57,6 +61,10 @@
       "require": "./src/presets/index.js",
       "import": "./src/presets/index.mjs"
     },
+    "./audit": {
+      "require": "./src/audit/index.js",
+      "import": "./src/audit/index.mjs"
+    },
     "./rules/use-scale": {
       "require": "./src/rules/use-scale/index.js",
       "import": "./src/rules/use-scale/index.mjs"
@@ -69,6 +77,10 @@
       "require": "./src/rules/no-offscale-transform/index.js",
       "import": "./src/rules/no-offscale-transform/index.mjs"
     },
+    "./rules/use-motion-scale": {
+      "require": "./src/rules/use-motion-scale/index.js",
+      "import": "./src/rules/use-motion-scale/index.mjs"
+    },
     "./eslint": {
       "require": "./src/eslint/index.js",
       "import": "./src/eslint/index.mjs"

package/src/audit/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const {
+  AUDIT_JSON_SCHEMA,
+  createAuditReport,
+  loadAuditConfig,
+  toAuditContractReport,
+} = require('../cli/audit');
+const { parseTokenSources } = require('../utils/token-sources');
+
+module.exports = {
+  AUDIT_JSON_SCHEMA,
+  createAuditReport,
+  loadAuditConfig,
+  parseTokenSources,
+  toAuditContractReport,
+};

package/src/audit/index.mjs

@@ -0,0 +1,11 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const audit = require('./index.js');
+
+export default audit;
+export const AUDIT_JSON_SCHEMA = audit.AUDIT_JSON_SCHEMA;
+export const createAuditReport = audit.createAuditReport;
+export const loadAuditConfig = audit.loadAuditConfig;
+export const parseTokenSources = audit.parseTokenSources;
+export const toAuditContractReport = audit.toAuditContractReport;