stylelint-plugin-rhythmguard 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [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
+
+- Added `.rhythmguardrc.json` audit config loading with `--config` and `--no-config`.
+- Added external audit token sources with `--token-source`, `--token-source-format`, and `--token-kind`.
+- Added token source parsing for CSS custom properties, Tailwind v4 `@theme`, flat JSON, Style Dictionary JSON, and DTCG JSON.
+- Expanded audit token-contract reporting with loaded source metadata, raw values that match known tokens, and conflicting token values.
+
 ## [1.7.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
 
@@ -93,9 +94,12 @@ npx rhythmguard audit . --ignore "apps/legacy/**" --ignore "vendor/**"
 npx rhythmguard audit ./src --write-baseline
 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
 ```
 
-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, and repeated raw values that deserve token review. 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, 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:
 
 ```md
 # Rhythmguard Design-System Audit
@@ -110,6 +114,28 @@ The report covers authored CSS declarations, Tailwind arbitrary spacing values i
 | New findings | 3 |
 ```
 
+### Audit config and external token sources
+
+For large codebases, put shared audit settings in `.rhythmguardrc.json`:
+
+```json
+{
+  "audit": {
+    "ignore": ["legacy/**", "generated/**"],
+    "tokenSources": [
+      "./tokens.json",
+      { "path": "./src/theme.css", "format": "css" }
+    ],
+    "tokenKind": "spacing",
+    "includeMotion": false,
+    "tokenCandidateMinCount": 2,
+    "minCleanliness": 90
+  }
+}
+```
+
+`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.
+
 ## Installation
 
 ```bash
@@ -198,6 +224,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`
@@ -207,6 +243,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)
 
@@ -448,7 +485,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) |
 
@@ -520,6 +557,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.7.0",
+  "version": "1.9.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"
@@ -69,6 +73,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"