stylelint-plugin-rhythmguard 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ 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

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,6 +96,7 @@ 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, 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:
@@ -125,6 +127,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
   }
@@ -221,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`
@@ -230,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)
 
@@ -471,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) |
 
@@ -543,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.8.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"

package/src/cli/audit.js

@@ -6,6 +6,8 @@ const path = require('node:path');
 
 const { formatLength } = require('../utils/length');
 const { createTailwindClassAnalyzer } = require('../utils/tailwind-class-analysis');
+const { createTailwindMotionAnalyzer } = require('../utils/tailwind-motion-analysis');
+const { formatTime } = require('../utils/time');
 const {
   addDefinition,
   createTokenKindMatcher,
@@ -69,9 +71,10 @@ Options:
   --min-cleanliness <percent>    Exit 1 when scale cleanliness is lower than this percent
   --since <git-ref>              Scan only changed files since a git ref
   --staged                       Scan only staged files
+  --include-motion               Include opt-in motion duration/easing drift
   --token-source <file>          External token source (repeatable, comma-separated)
   --token-source-format <format> Token source format: auto, css, flat-json, style-dictionary, dtcg (default: auto)
-  --token-kind <kind>            Token kind: spacing, radius, typography, size, all (default: spacing)
+  --token-kind <kind>            Token kind: spacing, radius, typography, size, motion, all (default: spacing)
   --token-candidate-min-count <n> Minimum repeated raw value count for token candidates (default: 2)
   --scale <values>               Comma-separated scale values (default: 0,4,8,12,16,24,32)
   --base-font-size <number>      px base for rem/em conversion (default: 16)
@@ -89,6 +92,7 @@ function parseArgs(argv) {
     format: 'text',
     ignorePath: DEFAULT_IGNORE_PATH,
     ignorePatterns: [],
+    includeMotion: false,
     maxFindings: null,
     minCleanliness: null,
     noConfig: false,
@@ -261,6 +265,12 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--include-motion') {
+      parsed.includeMotion = true;
+      parsed.cliOptions.add('includeMotion');
+      continue;
+    }
+
     if (arg === '--token-source') {
       parsed.tokenSources.push(...parseTokenSourcePaths(argv[++index]));
       parsed.cliOptions.add('tokenSources');
@@ -572,6 +582,7 @@ function applyAuditConfig(parsed, configResult) {
   applyConfigScalar(next, audit, cliOptions, 'tokenCandidateMinCount', 'tokenCandidateMinCount', parsePositiveInteger);
   applyConfigScalar(next, audit, cliOptions, 'tokenKind', 'tokenKind', normalizeTokenKind);
   applyConfigScalar(next, audit, cliOptions, 'baseFontSize', 'baseFontSize', parseBaseFontSize);
+  applyConfigScalar(next, audit, cliOptions, 'includeMotion', 'includeMotion', parseBooleanOption);
   applyConfigScalar(next, audit, cliOptions, 'scale', 'scale', (value) => {
     if (Array.isArray(value)) {
       return value;
@@ -591,6 +602,14 @@ function applyConfigScalar(target, audit, cliOptions, targetKey, configKey, pars
   target[targetKey] = parser(audit[configKey], configKey);
 }
 
+function parseBooleanOption(value, optionName) {
+  if (typeof value !== 'boolean') {
+    throw new Error(`${optionName} must be a boolean.`);
+  }
+
+  return value;
+}
+
 function normalizeCliTokenSources(sources, format) {
   return sources.map((sourcePath) => ({
     baseDir: process.cwd(),
@@ -866,31 +885,41 @@ async function runStylelintAudit(cssFiles, options) {
   }
 
   const { default: stylelint } = await import('stylelint');
+  const rules = {
+    'rhythmguard/use-scale': [
+      true,
+      {
+        baseFontSize: options.baseFontSize,
+        scale: options.scale,
+        severity: 'warning',
+      },
+    ],
+    'rhythmguard/prefer-token': [
+      true,
+      {
+        baseFontSize: options.baseFontSize,
+        scale: options.scale,
+        severity: 'warning',
+        tokenMapFromCssCustomProperties: true,
+        tokenPattern: '^--spac(e|ing)-',
+      },
+    ],
+  };
+
+  if (options.includeMotion) {
+    rules['rhythmguard/use-motion-scale'] = [
+      true,
+      {
+        severity: 'warning',
+      },
+    ];
+  }
 
   const result = await stylelint.lint({
     files: cssFiles,
     config: {
       plugins: [pluginPath],
-      rules: {
-        'rhythmguard/use-scale': [
-          true,
-          {
-            baseFontSize: options.baseFontSize,
-            scale: options.scale,
-            severity: 'warning',
-          },
-        ],
-        'rhythmguard/prefer-token': [
-          true,
-          {
-            baseFontSize: options.baseFontSize,
-            scale: options.scale,
-            severity: 'warning',
-            tokenMapFromCssCustomProperties: true,
-            tokenPattern: '^--spac(e|ing)-',
-          },
-        ],
-      },
+      rules,
     },
   });
 
@@ -909,6 +938,12 @@ function collectCssFindings(fileResults) {
       const tokenMatch = text.match(
         /Unexpected raw scale value "([^"]+)"/,
       );
+      const motionDurationMatch = text.match(
+        /Unexpected (?:motion duration|negative motion duration) "([^"]+)"/,
+      );
+      const motionEasingMatch = text.match(
+        /Unexpected raw motion easing "([^"]+)"/,
+      );
 
       findings.push({
         column: warning.column || 1,
@@ -916,8 +951,13 @@ function collectCssFindings(fileResults) {
         line: warning.line || 1,
         rule: warning.rule || 'rhythmguard',
         text,
-        type: tokenMatch ? 'token-opportunity' : 'off-scale',
-        value: tokenMatch ? tokenMatch[1] : offScaleMatch ? offScaleMatch[1] : null,
+        type: getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }),
+        value: getCssFindingValue({
+          motionDurationMatch,
+          motionEasingMatch,
+          offScaleMatch,
+          tokenMatch,
+        }),
       });
     }
   }
@@ -925,6 +965,47 @@ function collectCssFindings(fileResults) {
   return findings;
 }
 
+function getCssFindingValue({
+  motionDurationMatch,
+  motionEasingMatch,
+  offScaleMatch,
+  tokenMatch,
+}) {
+  if (tokenMatch) {
+    return tokenMatch[1];
+  }
+
+  if (offScaleMatch) {
+    return offScaleMatch[1];
+  }
+
+  if (motionDurationMatch) {
+    return motionDurationMatch[1];
+  }
+
+  if (motionEasingMatch) {
+    return motionEasingMatch[1];
+  }
+
+  return null;
+}
+
+function getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }) {
+  if (motionDurationMatch) {
+    return 'motion-duration';
+  }
+
+  if (motionEasingMatch) {
+    return 'motion-easing';
+  }
+
+  if (tokenMatch) {
+    return 'token-opportunity';
+  }
+
+  return 'off-scale';
+}
+
 function collectTailwindFindings(templateFiles, options) {
   const analyzer = createTailwindClassAnalyzer(options);
   const findings = [];
@@ -969,6 +1050,66 @@ function collectTailwindFindings(templateFiles, options) {
   return findings;
 }
 
+function collectTailwindMotionFindings(templateFiles, options) {
+  if (!options.includeMotion) {
+    return [];
+  }
+
+  const analyzer = createTailwindMotionAnalyzer(options);
+  const findings = [];
+
+  for (const filePath of templateFiles) {
+    let source = '';
+    try {
+      source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lineStarts = getLineStarts(source);
+
+    for (const literal of findStringLiterals(source)) {
+      for (const { analysis, segment } of analyzer.analyzeClassString(literal.value)) {
+        const position = offsetToLineColumn(lineStarts, literal.valueStart + segment.start);
+        findings.push({
+          column: position.column,
+          file: formatPath(filePath),
+          fixedToken: analysis.fixedToken,
+          line: position.line,
+          nearest: analysis.nearest
+            ? {
+              lower: formatTime(analysis.nearest.lower, 'ms'),
+              upper: formatTime(analysis.nearest.upper, 'ms'),
+            }
+            : null,
+          rawValue: analysis.rawValue,
+          rule: 'rhythmguard-tailwind/tailwind-class-use-motion-scale',
+          text: buildTailwindMotionFindingText(segment.token, analysis),
+          token: segment.token,
+          type: analysis.reason === 'easing'
+            ? 'tailwind-motion-easing'
+            : 'tailwind-motion-duration',
+          utility: analysis.utility,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function buildTailwindMotionFindingText(token, analysis) {
+  if (analysis.reason === 'easing') {
+    return `Unexpected Tailwind arbitrary motion easing "${token}". Use motion tokens for easing decisions.`;
+  }
+
+  if (analysis.reason === 'negative') {
+    return `Unexpected Tailwind arbitrary motion duration "${token}". Use non-negative duration values.`;
+  }
+
+  return `Unexpected Tailwind arbitrary motion duration "${token}". Use duration scale values.`;
+}
+
 function findStringLiterals(source) {
   const literals = [];
   const literalPattern = /(["'`])((?:\\[\s\S]|(?!\1)[\s\S])*?)\1/g;
@@ -1250,6 +1391,8 @@ function buildReport({
   cssFindings,
   dir,
   externalTokenDefinitions,
+  includeMotion,
+  motionFindings,
   scanScope,
   templateFiles,
   tailwindFindings,
@@ -1266,17 +1409,21 @@ function buildReport({
     .map((finding) => finding.value));
   const tailwindArbitraryValues = countByValue(tailwindFindings
     .map((finding) => finding.rawValue));
+  const motionValues = countByValue(motionFindings
+    .map((finding) => finding.value || finding.rawValue));
   const issueFiles = new Set([
     ...cssFindings.map((finding) => finding.file),
+    ...motionFindings.map((finding) => finding.file),
     ...tailwindFindings.map((finding) => finding.file),
   ]);
   const topAffectedFiles = sortCountMap(countByValue([
     ...cssFindings.map((finding) => finding.file),
+    ...motionFindings.map((finding) => finding.file),
     ...tailwindFindings.map((finding) => finding.file),
   ])).slice(0, 10);
 
   const totalFiles = cssFiles.length + templateFiles.length;
-  const totalWarnings = cssFindings.length + tailwindFindings.length;
+  const totalWarnings = cssFindings.length + motionFindings.length + tailwindFindings.length;
   const filesWithIssues = issueFiles.size;
   const scaleCleanliness = totalFiles > 0
     ? Math.max(0, Math.round(((totalFiles - filesWithIssues) / totalFiles) * 100))
@@ -1299,9 +1446,15 @@ function buildReport({
     filesWithIssues,
     findings: {
       css: cssFindings,
+      motion: motionFindings,
       tailwind: tailwindFindings,
     },
-    formatVersion: 4,
+    formatVersion: 5,
+    motion: {
+      enabled: includeMotion,
+      findings: motionFindings.length,
+      values: Object.fromEntries(sortCountMap(motionValues).slice(0, 10)),
+    },
     offScaleValues: Object.fromEntries(sortCountMap(offScaleValues).slice(0, 10)),
     scaleCleanliness,
     scanScope,
@@ -1313,6 +1466,7 @@ function buildReport({
     summary: {
       cssWarnings: cssFindings.length,
       filesWithIssues,
+      motionFindings: motionFindings.length,
       rawValueMatches: tokenContract.summary.rawValueMatches,
       missingTokens: tokenContract.summary.missingTokens,
       rawValueCandidates: tokenContract.summary.rawValueCandidates,
@@ -1405,6 +1559,7 @@ function writeBaseline(report, baselinePath) {
 function getAllFindings(report) {
   return [
     ...report.findings.css,
+    ...report.findings.motion,
     ...report.findings.tailwind,
   ];
 }
@@ -1470,6 +1625,7 @@ function renderText(report) {
   appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
   appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
   appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);
+  appendHistogram(lines, 'MOTION RHYTHM DRIFT', report.motion.values);
   appendTokenContractText(lines, report.tokenContract);
   appendBaselineText(lines, report);
 
@@ -1622,6 +1778,7 @@ function renderMarkdown(report) {
   appendMarkdownCounts(lines, 'CSS Off-Scale Values', report.offScaleValues);
   appendMarkdownCounts(lines, 'CSS Token Opportunities', report.tokenOpportunities);
   appendMarkdownCounts(lines, 'Tailwind Class-String Drift', report.tailwindArbitraryValues);
+  appendMarkdownCounts(lines, 'Motion Rhythm Drift', report.motion.values);
   appendTokenContractMarkdown(lines, report.tokenContract);
   appendBaselineMarkdown(lines, report);
 
@@ -1872,6 +2029,7 @@ async function run() {
   const { cssFiles, scanScope, templateFiles } = scanFiles;
   const options = {
     baseFontSize: parsed.baseFontSize,
+    includeMotion: parsed.includeMotion,
     scale: parsed.scale,
   };
 
@@ -1888,14 +2046,22 @@ async function run() {
     sources: parsed.tokenSources,
     tokenKind: parsed.tokenKind,
   });
+  const stylelintFindings = collectCssFindings(cssResults);
+  const cssFindings = stylelintFindings.filter((finding) => !finding.type.startsWith('motion-'));
+  const motionFindings = [
+    ...stylelintFindings.filter((finding) => finding.type.startsWith('motion-')),
+    ...collectTailwindMotionFindings(templateFiles, options),
+  ];
 
   const report = buildReport({
     baseFontSize: parsed.baseFontSize,
     config: parsed.config,
     cssFiles,
-    cssFindings: collectCssFindings(cssResults),
+    cssFindings,
     dir: parsed.dir,
     externalTokenDefinitions: tokenSourceResult.definitions,
+    includeMotion: parsed.includeMotion,
+    motionFindings,
     scanScope,
     tailwindFindings: collectTailwindFindings(templateFiles, options),
     templateFiles,

package/src/configs/motion.js

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = {
+  plugins: ['stylelint-plugin-rhythmguard'],
+  rules: {
+    'rhythmguard/use-motion-scale': [
+      true,
+      {
+        durationScale: [0, 75, 100, 150, 200, 300, 500, 700, 1000],
+      },
+    ],
+  },
+};

package/src/configs/motion.mjs

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const config = require('./motion.js');
+export default config;

package/src/eslint/index.js

@@ -1,15 +1,18 @@
 'use strict';
 
 const tailwindClassUseScale = require('./rules/tailwind-class-use-scale');
+const tailwindClassUseMotionScale = require('./rules/tailwind-class-use-motion-scale');
 
 module.exports = {
   rules: {
     'tailwind-class-use-scale': tailwindClassUseScale,
+    'tailwind-class-use-motion-scale': tailwindClassUseMotionScale,
   },
   configs: {
     recommended: {
       rules: {
         'rhythmguard-tailwind/tailwind-class-use-scale': 'warn',
+        'rhythmguard-tailwind/tailwind-class-use-motion-scale': 'off',
       },
     },
   },

package/src/eslint/rules/tailwind-class-use-motion-scale.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const { formatTime } = require('../../utils/time');
+const { createTailwindMotionAnalyzer } = require('../../utils/tailwind-motion-analysis');
+
+const RULE_NAME = 'tailwind-class-use-motion-scale';
+
+function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
+  const rawText = sourceCode.getText(node);
+  let value = null;
+  let quote = null;
+
+  if (node.type === 'Literal' && typeof node.value === 'string') {
+    value = node.value;
+    quote = rawText[0] === '"' || rawText[0] === "'" ? rawText[0] : '"';
+  }
+
+  if (node.type === 'TemplateElement') {
+    value = node.value.raw;
+  }
+
+  if (!value || typeof value !== 'string') {
+    return;
+  }
+
+  const findings = analyzer.analyzeClassString(value);
+  if (findings.length === 0) {
+    return;
+  }
+
+  let fixedValue = value;
+  let fixedValueOffset = 0;
+
+  for (const { analysis, segment } of findings) {
+    if (allowFix && analysis.reason === 'duration' && node.type === 'Literal') {
+      const replacementStart = segment.start + fixedValueOffset;
+      fixedValue = `${fixedValue.slice(0, replacementStart)}${analysis.fixedToken}${fixedValue.slice(replacementStart + segment.token.length)}`;
+      fixedValueOffset += analysis.fixedToken.length - segment.token.length;
+    }
+  }
+
+  const fixedText = allowFix && node.type === 'Literal' && fixedValue !== value
+    ? `${quote}${fixedValue.replace(new RegExp(quote, 'g'), `\\${quote}`)}${quote}`
+    : null;
+
+  for (const { analysis, segment } of findings) {
+    const lower = analysis.nearest
+      ? formatTime(analysis.nearest.lower, 'ms')
+      : 'n/a';
+    const upper = analysis.nearest
+      ? formatTime(analysis.nearest.upper, 'ms')
+      : 'n/a';
+    context.report({
+      message: buildMessage(analysis, segment, lower, upper),
+      node,
+      fix:
+        fixedText && analysis.reason === 'duration'
+          ? (fixer) => fixer.replaceText(node, fixedText)
+          : null,
+    });
+  }
+}
+
+function buildMessage(analysis, segment, lower, upper) {
+  if (analysis.reason === 'easing') {
+    return `Unexpected Tailwind arbitrary motion easing "${segment.token}". Use motion tokens for easing decisions.`;
+  }
+
+  if (analysis.reason === 'negative') {
+    return `Unexpected Tailwind arbitrary motion duration "${segment.token}". Use non-negative duration values.`;
+  }
+
+  return `Unexpected Tailwind arbitrary motion duration "${segment.token}". Use duration scale values (nearest: ${lower} or ${upper}).`;
+}
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Enforce duration scale for Tailwind arbitrary motion utilities in class strings',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          durationScale: {
+            items: { type: 'number' },
+            type: 'array',
+          },
+          durationUnits: {
+            items: {
+              enum: ['ms', 's'],
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+  },
+  create(context) {
+    const analyzer = createTailwindMotionAnalyzer(context.options && context.options[0]);
+    const sourceCode = context.sourceCode || context.getSourceCode();
+
+    return {
+      Literal(node) {
+        maybeCheckNodeText(node, sourceCode, context, analyzer, true);
+      },
+      TemplateElement(node) {
+        maybeCheckNodeText(node, sourceCode, context, analyzer, false);
+      },
+    };
+  },
+  ruleName: RULE_NAME,
+};

package/src/index.js

@@ -3,14 +3,16 @@
 const useScale = require('./rules/use-scale');
 const preferToken = require('./rules/prefer-token');
 const noOffscaleTransform = require('./rules/no-offscale-transform');
+const useMotionScale = require('./rules/use-motion-scale');
 
-const rules = [useScale, preferToken, noOffscaleTransform];
+const rules = [useScale, preferToken, noOffscaleTransform, useMotionScale];
 
 module.exports = rules;
 module.exports.rules = {
   [useScale.ruleName]: useScale,
   [preferToken.ruleName]: preferToken,
   [noOffscaleTransform.ruleName]: noOffscaleTransform,
+  [useMotionScale.ruleName]: useMotionScale,
 };
 module.exports.configs = {
   recommended: require('./configs/recommended'),
@@ -19,6 +21,7 @@ module.exports.configs = {
   expanded: require('./configs/expanded'),
   logical: require('./configs/logical'),
   migration: require('./configs/migration'),
+  motion: require('./configs/motion'),
 };
 module.exports.eslint = require('./eslint');
 module.exports.presets = require('./presets');

package/src/rules/use-motion-scale/index.js

@@ -0,0 +1,245 @@
+'use strict';
+
+const stylelint = require('stylelint');
+const valueParser = require('postcss-value-parser');
+const {
+  nearestScaleValues,
+  numbersEqual,
+} = require('../../utils/length');
+const {
+  declarationValueIndex,
+  walkRootValueNodes,
+} = require('../../utils/value-utils');
+const {
+  formatTime,
+  fromMs,
+  normalizeDurationScale,
+  normalizeDurationUnits,
+  parseTimeToken,
+  toMs,
+} = require('../../utils/time');
+
+const ruleName = 'rhythmguard/use-motion-scale';
+const DURATION_PROPERTIES = new Set([
+  'transition-duration',
+  'transition-delay',
+  'animation-duration',
+  'animation-delay',
+  'transition',
+  'animation',
+]);
+const EASING_PROPERTIES = new Set([
+  'transition-timing-function',
+  'animation-timing-function',
+  'transition',
+  'animation',
+]);
+const EASING_FUNCTIONS = new Set(['cubic-bezier', 'linear', 'steps']);
+
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  invalidDuration: (value) =>
+    `Unexpected negative motion duration "${value}". Use non-negative duration values.`,
+  rejectedDuration: (value, lower, upper) =>
+    `Unexpected motion duration "${value}". Use duration scale values (nearest: ${lower} or ${upper}).`,
+  rejectedEasing: (value) =>
+    `Unexpected raw motion easing "${value}". Use motion tokens for easing decisions.`,
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function buildOptions(rawOptions) {
+  const options = rawOptions || {};
+
+  return {
+    durationScale: normalizeDurationScale(options.durationScale),
+    durationUnits: normalizeDurationUnits(options.durationUnits),
+    easingTokenMap: isPlainObject(options.easingTokenMap) ? options.easingTokenMap : {},
+    fixToScale: options.fixToScale !== false,
+  };
+}
+
+function validateSecondaryOptions(result, secondaryOptions) {
+  return stylelint.utils.validateOptions(result, ruleName, {
+    actual: secondaryOptions,
+    optional: true,
+    possible: {
+      durationScale: [(value) =>
+        typeof value === 'number' &&
+        Number.isFinite(value) &&
+        value >= 0],
+      durationUnits: [(value) => value === 'ms' || value === 's'],
+      easingTokenMap: [(value) =>
+        isPlainObject(value) &&
+        Object.values(value).every((entry) =>
+          typeof entry === 'string' && entry.trim().length > 0,
+        )],
+      fixToScale: [true, false],
+    },
+  });
+}
+
+function getFixedNodeValue(parsedTime, nearestMs, options) {
+  if (!options.durationUnits.includes(parsedTime.unit)) {
+    return null;
+  }
+
+  const converted = fromMs(nearestMs, parsedTime.unit);
+  if (converted === null) {
+    return null;
+  }
+
+  return formatTime(converted, parsedTime.unit);
+}
+
+function functionToString(node) {
+  return valueParser.stringify(node);
+}
+
+const ruleFunction = (primary, secondaryOptions) => {
+  return (root, result) => {
+    const valid = stylelint.utils.validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    });
+
+    if (!valid || !validateSecondaryOptions(result, secondaryOptions)) {
+      return;
+    }
+
+    const options = buildOptions(secondaryOptions);
+
+    root.walkDecls((decl) => {
+      const prop = decl.prop.toLowerCase();
+      if (!DURATION_PROPERTIES.has(prop) && !EASING_PROPERTIES.has(prop)) {
+        return;
+      }
+
+      const parsed = valueParser(decl.value);
+      let changed = false;
+
+      const reportDuration = (node, nearest, fixedValue = null) => {
+        const index = declarationValueIndex(decl) + node.sourceIndex;
+        const payload = {
+          endIndex: index + node.value.length,
+          index,
+          message: nearest
+            ? messages.rejectedDuration(
+              node.value,
+              formatTime(nearest.lower, 'ms'),
+              formatTime(nearest.upper, 'ms'),
+            )
+            : messages.invalidDuration(node.value),
+          node: decl,
+          result,
+          ruleName,
+        };
+
+        if (fixedValue) {
+          payload.fix = () => {
+            node.value = fixedValue;
+            return true;
+          };
+        }
+
+        stylelint.utils.report(payload);
+      };
+
+      const reportEasing = (node, replacement = null) => {
+        const source = functionToString(node);
+        const index = declarationValueIndex(decl) + node.sourceIndex;
+        const payload = {
+          endIndex: index + source.length,
+          index,
+          message: messages.rejectedEasing(source),
+          node: decl,
+          result,
+          ruleName,
+        };
+
+        if (replacement) {
+          payload.fix = () => {
+            node.type = 'word';
+            node.value = replacement;
+            delete node.nodes;
+            return true;
+          };
+        }
+
+        stylelint.utils.report(payload);
+      };
+
+      walkRootValueNodes(parsed, (node) => {
+        if (node.type === 'function') {
+          const functionName = node.value.toLowerCase();
+          if (!EASING_PROPERTIES.has(prop) || !EASING_FUNCTIONS.has(functionName)) {
+            return false;
+          }
+
+          const source = functionToString(node);
+          reportEasing(node, options.easingTokenMap[source] || null);
+          changed = changed || Boolean(options.easingTokenMap[source]);
+          return true;
+        }
+
+        if (node.type !== 'word' || !DURATION_PROPERTIES.has(prop)) {
+          return false;
+        }
+
+        const parsedTime = parseTimeToken(node.value);
+        if (!parsedTime) {
+          return false;
+        }
+
+        if (parsedTime.number < 0) {
+          reportDuration(node, null);
+          return false;
+        }
+
+        if (!options.durationUnits.includes(parsedTime.unit)) {
+          return false;
+        }
+
+        const msValue = toMs(parsedTime.number, parsedTime.unit);
+        if (msValue === null) {
+          return false;
+        }
+
+        const isOnScale = options.durationScale.some((scaleValue) => numbersEqual(scaleValue, msValue));
+        if (isOnScale) {
+          return false;
+        }
+
+        const nearest = nearestScaleValues(msValue, options.durationScale);
+        if (!nearest) {
+          return false;
+        }
+
+        const fixedValue = options.fixToScale
+          ? getFixedNodeValue(parsedTime, nearest.nearest, options)
+          : null;
+
+        reportDuration(node, nearest, fixedValue);
+        changed = changed || Boolean(fixedValue);
+        return false;
+      });
+
+      if (changed) {
+        decl.value = parsed.toString();
+      }
+    });
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+ruleFunction.meta = {
+  fixable: true,
+  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguarduse-motion-scale',
+};
+
+module.exports = stylelint.createPlugin(ruleName, ruleFunction);
+module.exports.ruleName = ruleName;
+module.exports.messages = messages;
+module.exports.meta = ruleFunction.meta;

package/src/rules/use-motion-scale/index.mjs

@@ -0,0 +1,7 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const rule = require('./index.js');
+export default rule;
+export const ruleName = rule.ruleName;
+export const messages = rule.messages;
+export const meta = rule.meta;

package/src/utils/constants.js

@@ -35,6 +35,10 @@ const PROPERTY_GROUP_PATTERNS = Object.freeze({
     /^letter-spacing$/,
     /^word-spacing$/,
   ]),
+  motion: Object.freeze([
+    /^transition(?:-.+)?$/,
+    /^animation(?:-.+)?$/,
+  ]),
 });
 
 const DEFAULT_PROPERTY_GROUPS = Object.freeze(['spacing']);

package/src/utils/tailwind-motion-analysis.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const {
+  nearestScaleValues,
+  numbersEqual,
+} = require('./length');
+const {
+  formatTime,
+  fromMs,
+  normalizeDurationScale,
+  normalizeDurationUnits,
+  parseTimeToken,
+  toMs,
+} = require('./time');
+const { findClassSegments } = require('./tailwind-class-analysis');
+
+const ARBITRARY_MOTION_CLASS = /^(?<utility>duration|delay|ease)-\[(?<rawValue>[^\]]+)\]$/;
+
+function normalizeTailwindMotionOptions(option = {}) {
+  return {
+    durationScale: normalizeDurationScale(option.durationScale),
+    durationUnits: normalizeDurationUnits(option.durationUnits),
+  };
+}
+
+function findLastVariantSeparator(token) {
+  let bracketDepth = 0;
+  let separatorIndex = -1;
+
+  for (let index = 0; index < token.length; index++) {
+    const character = token[index];
+
+    if (character === '[') {
+      bracketDepth++;
+      continue;
+    }
+
+    if (character === ']' && bracketDepth > 0) {
+      bracketDepth--;
+      continue;
+    }
+
+    if (character === ':' && bracketDepth === 0) {
+      separatorIndex = index;
+    }
+  }
+
+  return separatorIndex;
+}
+
+function parseClassToken(token) {
+  const separatorIndex = findLastVariantSeparator(token);
+  const prefix = separatorIndex === -1
+    ? ''
+    : token.slice(0, separatorIndex + 1);
+  let candidate = separatorIndex === -1
+    ? token
+    : token.slice(separatorIndex + 1);
+  let leadingImportant = '';
+  let trailingImportant = '';
+
+  if (candidate.startsWith('!')) {
+    leadingImportant = '!';
+    candidate = candidate.slice(1);
+  }
+
+  if (candidate.endsWith('!')) {
+    trailingImportant = '!';
+    candidate = candidate.slice(0, -1);
+  }
+
+  return {
+    candidate,
+    leadingImportant,
+    prefix,
+    trailingImportant,
+  };
+}
+
+function analyzeMotionToken(token, options) {
+  const parsedToken = parseClassToken(token);
+  const match = parsedToken.candidate.match(ARBITRARY_MOTION_CLASS);
+  if (!match || !match.groups) {
+    return null;
+  }
+
+  if (match.groups.utility === 'ease') {
+    return {
+      fixedToken: null,
+      rawValue: match.groups.rawValue,
+      reason: 'easing',
+      utility: match.groups.utility,
+    };
+  }
+
+  const parsedTime = parseTimeToken(match.groups.rawValue);
+  if (!parsedTime) {
+    return null;
+  }
+
+  if (parsedTime.number < 0) {
+    return {
+      fixedToken: null,
+      nearest: null,
+      rawValue: match.groups.rawValue,
+      reason: 'negative',
+      utility: match.groups.utility,
+    };
+  }
+
+  if (!options.durationUnits.includes(parsedTime.unit)) {
+    return null;
+  }
+
+  const msValue = toMs(parsedTime.number, parsedTime.unit);
+  if (msValue === null) {
+    return null;
+  }
+
+  const isOnScale = options.durationScale.some((entry) => numbersEqual(entry, msValue));
+  if (isOnScale) {
+    return null;
+  }
+
+  const nearest = nearestScaleValues(msValue, options.durationScale);
+  if (!nearest) {
+    return null;
+  }
+
+  const converted = fromMs(nearest.nearest, parsedTime.unit);
+  if (converted === null) {
+    return null;
+  }
+
+  const replacementValue = formatTime(converted, parsedTime.unit);
+  const fixedCandidate = parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
+  const fixedToken = `${parsedToken.prefix}${parsedToken.leadingImportant}${fixedCandidate}${parsedToken.trailingImportant}`;
+
+  return {
+    fixedToken,
+    nearest,
+    rawValue: match.groups.rawValue,
+    reason: 'duration',
+    utility: match.groups.utility,
+  };
+}
+
+function createTailwindMotionAnalyzer(option = {}) {
+  const options = normalizeTailwindMotionOptions(option);
+
+  return {
+    analyzeClassString(value) {
+      const findings = [];
+
+      for (const segment of findClassSegments(value)) {
+        const analysis = analyzeMotionToken(segment.token, options);
+        if (analysis) {
+          findings.push({ analysis, segment });
+        }
+      }
+
+      return findings;
+    },
+    analyzeToken(token) {
+      return analyzeMotionToken(token, options);
+    },
+    options,
+  };
+}
+
+module.exports = {
+  createTailwindMotionAnalyzer,
+  normalizeTailwindMotionOptions,
+};

package/src/utils/time.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const TIME_RE = /^(-?(?:\d+|\d*\.\d+))(ms|s)$/i;
+
+function parseTimeToken(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const match = value.trim().match(TIME_RE);
+  if (!match) {
+    return null;
+  }
+
+  const number = Number(match[1]);
+  if (!Number.isFinite(number)) {
+    return null;
+  }
+
+  return {
+    number,
+    unit: match[2].toLowerCase(),
+  };
+}
+
+function toMs(number, unit) {
+  if (unit === 'ms') {
+    return number;
+  }
+
+  if (unit === 's') {
+    return number * 1000;
+  }
+
+  return null;
+}
+
+function fromMs(ms, unit) {
+  if (unit === 'ms') {
+    return ms;
+  }
+
+  if (unit === 's') {
+    return ms / 1000;
+  }
+
+  return null;
+}
+
+function formatTime(number, unit) {
+  const normalized = Object.is(number, -0) ? 0 : number;
+  if (Number.isInteger(normalized)) {
+    return `${normalized}${unit}`;
+  }
+
+  return `${Number(normalized.toFixed(4)).toString()}${unit}`;
+}
+
+function normalizeDurationScale(scale) {
+  const source = Array.isArray(scale) && scale.length > 0
+    ? scale
+    : [0, 75, 100, 150, 200, 300, 500, 700, 1000];
+
+  return [...new Set(source
+    .map((entry) => Number(entry))
+    .filter((entry) => Number.isFinite(entry) && entry >= 0))]
+    .sort((a, b) => a - b);
+}
+
+function normalizeDurationUnits(units) {
+  const source = Array.isArray(units) && units.length > 0
+    ? units
+    : ['ms', 's'];
+
+  const normalized = source
+    .map((unit) => String(unit).trim().toLowerCase())
+    .filter((unit) => unit === 'ms' || unit === 's');
+
+  return normalized.length > 0 ? [...new Set(normalized)] : ['ms', 's'];
+}
+
+module.exports = {
+  formatTime,
+  fromMs,
+  normalizeDurationScale,
+  normalizeDurationUnits,
+  parseTimeToken,
+  toMs,
+};

package/src/utils/token-sources.js

@@ -22,12 +22,14 @@ const VALID_TOKEN_KINDS = new Set([
   'radius',
   'typography',
   'size',
+  'motion',
   'all',
 ]);
 
 const TOKEN_KIND_PATTERNS = Object.freeze({
   all: /^--/,
   radius: /^--radius-/,
+  motion: /^--(?:motion|duration|delay|ease|easing)-/,
   size: /^--(?:size|width|height|container)-/,
   spacing: /^--(?:space|spacing)-/,
   typography: /^--(?:font|font-size|line-height|leading|tracking|typography)-/,
@@ -53,7 +55,7 @@ function normalizeTokenSourceFormat(format) {
 function normalizeTokenKind(kind) {
   const normalized = String(kind || 'spacing').trim().toLowerCase();
   if (!VALID_TOKEN_KINDS.has(normalized)) {
-    throw new Error(`Invalid token kind "${kind}". Expected spacing, radius, typography, size, or all.`);
+    throw new Error(`Invalid token kind "${kind}". Expected spacing, radius, typography, size, motion, or all.`);
   }
 
   return normalized;