stylelint-plugin-rhythmguard 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-02-17
+
+### Added
+
+- Tailwind integration guidance in README:
+  - exact enforcement boundary (CSS declarations vs class strings)
+  - recommended layered setup with `stylelint-config-tailwindcss`, `eslint-plugin-tailwindcss`, and `prettier-plugin-tailwindcss`
+  - architecture direction for thorough Tailwind coverage.
+- New shared config entry point: `stylelint-plugin-rhythmguard/configs/tailwind`.
+- Tailwind-oriented test coverage for transform token functions and nested translate values.
+
+### Changed
+
+- Hardened transform translate parsing to handle nested function values consistently.
+- `use-scale` and `no-offscale-transform` now respect `enforceInsideMathFunctions` in transform translation contexts.
+
 ## [1.1.0] - 2026-02-17
 
 ### Added

package/README.md

@@ -61,10 +61,20 @@ npm install --save-dev stylelint stylelint-plugin-rhythmguard
 }
 ```
 
+### Tailwind config
+
+```json
+{
+  "plugins": ["stylelint-plugin-rhythmguard"],
+  "extends": ["stylelint-plugin-rhythmguard/configs/tailwind"]
+}
+```
+
 Stable shared config entry points:
 
 - `stylelint-plugin-rhythmguard/configs/recommended`
 - `stylelint-plugin-rhythmguard/configs/strict`
+- `stylelint-plugin-rhythmguard/configs/tailwind`
 
 ### Full custom setup
 
@@ -317,6 +327,59 @@ Options:
 
 `rhythmguard/no-offscale-transform` accepts the same scale options as `rhythmguard/use-scale`, but only for transform translation properties.
 
+## Tailwind CSS Integration
+
+Rhythmguard works well in Tailwind projects, but it enforces what Stylelint can parse: CSS declarations.
+
+### What Rhythmguard covers in Tailwind projects
+
+- custom CSS in `globals.css`, `components.css`, `utilities.css`
+- CSS Modules (for example `*.module.css`)
+- declarations inside `@layer` blocks
+
+### What Rhythmguard 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 this plugin's scope.
+
+### Recommended stack for full Tailwind enforcement
+
+Use both layers:
+
+1. Stylelint + Rhythmguard for CSS declaration governance.
+2. Tailwind-aware class-string linting/formatting for template utility usage.
+
+Suggested setup:
+
+```json
+{
+  "extends": ["stylelint-plugin-rhythmguard/configs/tailwind"]
+}
+```
+
+Then pair with:
+
+- `eslint-plugin-tailwindcss` for class-string rules (including arbitrary-value governance).
+- `prettier-plugin-tailwindcss` for deterministic class ordering.
+
+Detailed setup reference: [`docs/TAILWIND.md`](./docs/TAILWIND.md).
+
+### Tailwind token function support
+
+By default, `tokenFunctions` includes `theme`, so values like `theme(spacing.4)` are treated as tokenized values.
+
+### Product direction
+
+We should extend Tailwind coverage thoroughly, but in the right architecture:
+
+- keep `stylelint-plugin-rhythmguard` focused on CSS declaration enforcement
+- add a complementary Tailwind class-string layer (ESLint/plugin side) for utility classes
+
+This avoids brittle parsing hacks and gives full coverage without compromising rule quality.
+
 ## Programmatic Presets
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Stylelint plugin for spacing scale and token enforcement",
   "keywords": [
     "stylelint",
@@ -18,6 +18,7 @@
     ".": "./src/index.js",
     "./configs/recommended": "./src/configs/recommended.js",
     "./configs/strict": "./src/configs/strict.js",
+    "./configs/tailwind": "./src/configs/tailwind.js",
     "./presets": "./src/presets/index.js",
     "./rules/use-scale": "./src/rules/use-scale/index.js",
     "./rules/prefer-token": "./src/rules/prefer-token/index.js",
@@ -59,6 +60,9 @@
   "peerDependencies": {
     "stylelint": "^16.0.0"
   },
+  "dependencies": {
+    "stylelint-config-tailwindcss": "^1.0.1"
+  },
   "devDependencies": {
     "@eslint/js": "^9.22.0",
     "c8": "^10.1.3",

package/src/configs/tailwind.js

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = {
+  extends: [
+    'stylelint-config-tailwindcss',
+    'stylelint-plugin-rhythmguard/configs/strict',
+  ],
+};

package/src/index.js

@@ -15,5 +15,6 @@ module.exports.rules = {
 module.exports.configs = {
   recommended: require('./configs/recommended'),
   strict: require('./configs/strict'),
+  tailwind: require('./configs/tailwind'),
 };
 module.exports.presets = require('./presets');

package/src/rules/no-offscale-transform/index.js

@@ -14,6 +14,8 @@ const {
 const { buildScaleOptions } = require('../../utils/options');
 const {
   declarationValueIndex,
+  isMathFunction,
+  walkRootValueNodes,
   walkTransformTranslateNodes,
 } = require('../../utils/value-utils');
 
@@ -138,15 +140,55 @@ const ruleFunction = (primary, secondaryOptions) => {
       };
 
       if (prop === 'transform') {
-        walkTransformTranslateNodes(parsed, (node) => {
+        walkTransformTranslateNodes(parsed, (node, parentFunctionName) => {
+          if (node.type === 'function') {
+            if (isMathFunction(node.value) && !options.enforceInsideMathFunctions) {
+              return true;
+            }
+
+            return false;
+          }
+
+          if (node.type !== 'word') {
+            return false;
+          }
+
+          if (
+            parentFunctionName &&
+            isMathFunction(parentFunctionName) &&
+            !options.enforceInsideMathFunctions
+          ) {
+            return false;
+          }
+
           checkNode(node);
+          return false;
         });
       } else {
-        for (const node of parsed.nodes) {
-          if (node.type === 'word') {
-            checkNode(node);
+        walkRootValueNodes(parsed, (node, parentFunctionName) => {
+          if (node.type === 'function') {
+            if (isMathFunction(node.value) && !options.enforceInsideMathFunctions) {
+              return true;
+            }
+
+            return false;
           }
-        }
+
+          if (node.type !== 'word') {
+            return false;
+          }
+
+          if (
+            parentFunctionName &&
+            isMathFunction(parentFunctionName) &&
+            !options.enforceInsideMathFunctions
+          ) {
+            return false;
+          }
+
+          checkNode(node);
+          return false;
+        });
       }
 
       if (changed) {

package/src/rules/prefer-token/index.js

@@ -142,8 +142,25 @@ const ruleFunction = (primary, secondaryOptions) => {
       };
 
       if (prop === 'transform') {
-        walkTransformTranslateNodes(parsed, (node) => {
-          changed = checkWordNode(node) || changed;
+        walkTransformTranslateNodes(parsed, (node, parentFunctionName) => {
+          if (node.type === 'function') {
+            if (isTokenFunction(node, options.tokenFunctions, tokenRegex)) {
+              return true;
+            }
+
+            if (isMathFunction(node.value)) {
+              return true;
+            }
+
+            return false;
+          }
+
+          if (node.type !== 'word') {
+            return false;
+          }
+
+          changed = checkWordNode(node, parentFunctionName) || changed;
+          return false;
         });
       } else {
         walkRootValueNodes(parsed, (node, parentFunctionName) => {

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

@@ -170,7 +170,35 @@ const ruleFunction = (primary, secondaryOptions) => {
       let changed = false;
 
       if (prop === 'transform') {
-        walkTransformTranslateNodes(parsed, (node) => {
+        walkTransformTranslateNodes(parsed, (node, parentFunctionName) => {
+          if (node.type === 'function') {
+            if (isTokenFunction(node, options.tokenFunctions, tokenRegex)) {
+              return true;
+            }
+
+            if (isMathFunction(node.value) && !options.enforceInsideMathFunctions) {
+              return true;
+            }
+
+            return false;
+          }
+
+          if (node.type !== 'word') {
+            return false;
+          }
+
+          if (isKeyword(node.value, options.ignoreValues)) {
+            return false;
+          }
+
+          if (
+            parentFunctionName &&
+            isMathFunction(parentFunctionName) &&
+            !options.enforceInsideMathFunctions
+          ) {
+            return false;
+          }
+
           changed =
             checkLengthValue({
               decl,
@@ -179,6 +207,8 @@ const ruleFunction = (primary, secondaryOptions) => {
               report,
               scalePx,
             }) || changed;
+
+          return false;
         });
       } else {
         walkRootValueNodes(parsed, (node, parentFunctionName) => {

package/src/utils/value-utils.js

@@ -77,6 +77,23 @@ function walkRootValueNodes(parsed, walkNode, state) {
 }
 
 function walkTransformTranslateNodes(parsed, walkNode) {
+  const walkNodes = (nodes, parentFunctionName) => {
+    for (const node of nodes) {
+      if (node.type === 'function') {
+        const fnName = node.value.toLowerCase();
+        const skipChildren = walkNode(node, parentFunctionName);
+        if (skipChildren) {
+          continue;
+        }
+
+        walkNodes(node.nodes, fnName);
+        continue;
+      }
+
+      walkNode(node, parentFunctionName);
+    }
+  };
+
   for (const node of parsed.nodes) {
     if (node.type !== 'function') {
       continue;
@@ -86,11 +103,7 @@ function walkTransformTranslateNodes(parsed, walkNode) {
       continue;
     }
 
-    for (const child of node.nodes) {
-      if (child.type === 'word') {
-        walkNode(child, node.value.toLowerCase());
-      }
-    }
+    walkNodes(node.nodes, node.value.toLowerCase());
   }
 }