stylelint-plugin-rhythmguard 1.4.2 → 1.5.0

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
+
+```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';
 
-It is built for teams that want:
+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,16 @@ 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.
+
 ## Installation
 
 ```bash
@@ -66,32 +99,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,15 +155,28 @@ 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)
@@ -409,7 +455,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,6 +496,12 @@ Rhythmguard works well in Tailwind projects, but it enforces what Stylelint can
 - CSS Modules (for example `*.module.css`)
 - declarations inside `@layer` blocks
 
+### 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 Rhythmguard does not cover
 
 - Tailwind class strings in templates/JSX/TSX, for example:
@@ -480,6 +532,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:
@@ -521,6 +585,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:

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.5.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"

package/src/cli/audit.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = process.argv.slice(3);
+const jsonMode = args.includes('--json');
+const dir = args.find((a) => !a.startsWith('-'));
+
+if (!dir) {
+  process.stderr.write('Usage: rhythmguard audit <dir> [--json]\n');
+  process.exit(1);
+}
+
+const resolvedDir = path.resolve(dir);
+
+if (!fs.existsSync(resolvedDir)) {
+  process.stderr.write(`Directory not found: ${dir}\n`);
+  process.exit(1);
+}
+
+const GLOB_PATTERN = `${resolvedDir}/**/*.{css,module.css}`;
+
+const pluginPath = path.resolve(__dirname, '..', 'index.js');
+
+async function run() {
+  const { default: stylelint } = await import('stylelint');
+
+  let result;
+  try {
+    result = await stylelint.lint({
+      files: GLOB_PATTERN,
+      config: {
+        plugins: [pluginPath],
+        rules: {
+          'rhythmguard/use-scale': [true, { severity: 'warning' }],
+          'rhythmguard/prefer-token': [
+            true,
+            {
+              tokenMapFromCssCustomProperties: true,
+              severity: 'warning',
+            },
+          ],
+        },
+      },
+    });
+  } catch (err) {
+    process.stderr.write(`Lint error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const fileResults = result.results || [];
+  const totalFiles = fileResults.length;
+
+  const offScaleValues = {};
+  const tokenOpportunities = {};
+  let filesWithIssues = 0;
+  let totalWarnings = 0;
+
+  for (const fileResult of fileResults) {
+    const warnings = fileResult.warnings || [];
+    if (warnings.length > 0) {
+      filesWithIssues++;
+    }
+
+    for (const warning of warnings) {
+      totalWarnings++;
+      const text = warning.text || '';
+
+      // Extract off-scale values from use-scale messages
+      // Format: Unexpected off-scale value "13px". Use scale values (nearest: 12px or 16px).
+      const offScaleMatch = text.match(
+        /Unexpected off-scale value "([^"]+)"/,
+      );
+      if (offScaleMatch) {
+        const value = offScaleMatch[1];
+        offScaleValues[value] = (offScaleValues[value] || 0) + 1;
+      }
+
+      // Extract token opportunities from prefer-token messages
+      // Format: Unexpected raw scale value "16px". Use design tokens for scale decisions.
+      const tokenMatch = text.match(
+        /Unexpected raw scale value "([^"]+)"/,
+      );
+      if (tokenMatch) {
+        const value = tokenMatch[1];
+        tokenOpportunities[value] = (tokenOpportunities[value] || 0) + 1;
+      }
+    }
+  }
+
+  const sortedOffScale = Object.entries(offScaleValues)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
+
+  const sortedTokenOps = Object.entries(tokenOpportunities)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
+
+  if (jsonMode) {
+    const output = {
+      directory: dir,
+      totalFiles,
+      filesWithIssues,
+      totalWarnings,
+      offScaleValues: Object.fromEntries(sortedOffScale),
+      tokenOpportunities: Object.fromEntries(sortedTokenOps),
+    };
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    return;
+  }
+
+  // Human-readable output
+  const pct = totalFiles > 0
+    ? Math.round((filesWithIssues / totalFiles) * 100)
+    : 0;
+
+  const lines = [
+    '',
+    `Rhythmguard Audit: ${dir}`,
+    '',
+    `Files scanned:     ${totalFiles}`,
+    `Files with issues: ${filesWithIssues} (${pct}%)`,
+    '',
+  ];
+
+  if (sortedOffScale.length > 0) {
+    const offScaleTotal = Object.values(offScaleValues).reduce(
+      (a, b) => a + b,
+      0,
+    );
+    lines.push(`Off-scale values: ${offScaleTotal}`);
+    for (const [value, count] of sortedOffScale) {
+      lines.push(`  ${value.padEnd(10)} ×${count}`);
+    }
+    lines.push('');
+  }
+
+  if (sortedTokenOps.length > 0) {
+    const tokenTotal = Object.values(tokenOpportunities).reduce(
+      (a, b) => a + b,
+      0,
+    );
+    lines.push(`Token opportunities: ${tokenTotal}`);
+    for (const [value, count] of sortedTokenOps) {
+      lines.push(`  ${value.padEnd(10)} ×${count}`);
+    }
+    lines.push('');
+  }
+
+  if (totalWarnings === 0) {
+    lines.push('No issues found. Your spacing is on scale.');
+  } else {
+    lines.push('Run "npx stylelint --fix" to auto-correct.');
+  }
+
+  lines.push('');
+  process.stdout.write(lines.join('\n'));
+}
+
+run();

package/src/cli/doctor.js

@@ -0,0 +1,231 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const cwd = process.cwd();
+let issues = 0;
+
+function pass(msg) {
+  process.stdout.write(`✓ ${msg}\n`);
+}
+
+function fail(msg, fix) {
+  issues++;
+  process.stdout.write(`✗ ${msg}\n`);
+  if (fix) {
+    process.stdout.write(`  → ${fix}\n`);
+  }
+}
+
+function skip(msg) {
+  process.stdout.write(`- ${msg}\n`);
+}
+
+// Check 1: Stylelint installed
+function checkStylelint() {
+  try {
+    const stylelintPkg = require.resolve('stylelint/package.json', {
+      paths: [cwd],
+    });
+    const version = require(stylelintPkg).version;
+    pass(`stylelint installed (v${version})`);
+    return true;
+  } catch {
+    fail(
+      'stylelint not installed',
+      'Run: npm install --save-dev stylelint',
+    );
+    return false;
+  }
+}
+
+// Check 2: Config found
+function findConfig() {
+  const configFiles = [
+    '.stylelintrc',
+    '.stylelintrc.json',
+    '.stylelintrc.js',
+    '.stylelintrc.cjs',
+    '.stylelintrc.mjs',
+    '.stylelintrc.yml',
+    '.stylelintrc.yaml',
+    'stylelint.config.js',
+    'stylelint.config.cjs',
+    'stylelint.config.mjs',
+  ];
+
+  for (const file of configFiles) {
+    const fullPath = path.join(cwd, file);
+    if (fs.existsSync(fullPath)) {
+      pass(`config found (${file})`);
+      return fullPath;
+    }
+  }
+
+  // Check package.json
+  const pkgPath = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.stylelint) {
+        pass('config found (package.json stylelint key)');
+        return pkgPath;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  fail(
+    'no Stylelint config found',
+    'Run: npx rhythmguard init',
+  );
+  return null;
+}
+
+// Check 3: Config references Rhythmguard
+function checkConfigReferences(configPath) {
+  if (!configPath) {
+    skip('config reference check skipped (no config)');
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf8');
+
+    if (content.includes('rhythmguard')) {
+      pass('config references rhythmguard');
+      return content;
+    }
+
+    // Check package.json stylelint key
+    if (configPath.endsWith('package.json')) {
+      const pkg = JSON.parse(content);
+      const stylelintConfig = JSON.stringify(pkg.stylelint || {});
+      if (stylelintConfig.includes('rhythmguard')) {
+        pass('config references rhythmguard');
+        return stylelintConfig;
+      }
+    }
+
+    fail(
+      'config does not reference rhythmguard',
+      'Add: "extends": ["stylelint-plugin-rhythmguard/configs/recommended"]',
+    );
+    return content;
+  } catch {
+    fail(
+      'could not read config file',
+      `Check permissions on ${configPath}`,
+    );
+    return null;
+  }
+}
+
+// Check 4: Token pattern valid
+function checkTokenPattern(configContent) {
+  if (!configContent) {
+    skip('token pattern check skipped (no config content)');
+    return;
+  }
+
+  const patternMatch = configContent.match(
+    /tokenPattern['":\s]+['"]([^'"]+)['"]/,
+  );
+
+  if (!patternMatch) {
+    skip('token pattern check skipped (not configured)');
+    return;
+  }
+
+  try {
+    new RegExp(patternMatch[1]);
+    pass(`token pattern valid (${patternMatch[1]})`);
+  } catch {
+    fail(
+      `token pattern invalid: ${patternMatch[1]}`,
+      'Fix the regex in tokenPattern option',
+    );
+  }
+}
+
+// Check 5: Tailwind config exists
+function checkTailwindConfig(configContent) {
+  if (!configContent) {
+    skip('tailwind config check skipped (no config content)');
+    return;
+  }
+
+  const tailwindPathMatch = configContent.match(
+    /tailwindConfigPath['":\s]+['"]([^'"]+)['"]/,
+  );
+
+  if (!tailwindPathMatch) {
+    skip('tailwind config check skipped (not configured)');
+    return;
+  }
+
+  const tailwindPath = path.resolve(cwd, tailwindPathMatch[1]);
+  if (fs.existsSync(tailwindPath)) {
+    pass(`tailwind config found (${tailwindPathMatch[1]})`);
+  } else {
+    fail(
+      `tailwind config not found at ${tailwindPathMatch[1]}`,
+      'Update tailwindConfigPath or remove tokenMapFromTailwindSpacing',
+    );
+  }
+}
+
+// Check 6: Custom syntax installed
+function checkCustomSyntax(configContent) {
+  if (!configContent) {
+    skip('custom syntax check skipped (no config content)');
+    return;
+  }
+
+  const syntaxMatch = configContent.match(
+    /customSyntax['":\s]+['"]([^'"]+)['"]/,
+  );
+
+  if (!syntaxMatch) {
+    skip('custom syntax check skipped (not configured)');
+    return;
+  }
+
+  const pkg = syntaxMatch[1];
+  try {
+    require.resolve(pkg, { paths: [cwd] });
+    pass(`custom syntax installed (${pkg})`);
+  } catch {
+    fail(
+      `custom syntax package not installed: ${pkg}`,
+      `Run: npm install --save-dev ${pkg}`,
+    );
+  }
+}
+
+function run() {
+  process.stdout.write('\nRhythmguard Doctor\n\n');
+
+  const stylelintOk = checkStylelint();
+  const configPath = findConfig();
+  const configContent = checkConfigReferences(configPath);
+  checkTokenPattern(configContent);
+  checkTailwindConfig(configContent);
+  checkCustomSyntax(configContent);
+
+  process.stdout.write('\n');
+
+  if (issues === 0) {
+    process.stdout.write('All checks passed.\n\n');
+  } else {
+    process.stdout.write(
+      `${issues} issue${issues === 1 ? '' : 's'} found.\n\n`,
+    );
+  }
+
+  process.exit(stylelintOk && issues === 0 ? 0 : 1);
+}
+
+run();

package/src/cli/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+'use strict';
+
+const command = process.argv[2];
+
+const HELP = `Usage: rhythmguard <command>
+
+Commands:
+  audit <dir>   Report scale drift and token opportunities
+  init          Scaffold a Rhythmguard config for your project
+  doctor        Validate your Rhythmguard setup
+
+Options:
+  --help        Show this help message
+
+Examples:
+  npx rhythmguard audit ./src
+  npx rhythmguard audit ./src --json
+  npx rhythmguard init
+  npx rhythmguard doctor
+`;
+
+if (!command || command === '--help' || command === '-h') {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+if (command === 'audit') {
+  require('./audit');
+} else if (command === 'init') {
+  require('./init');
+} else if (command === 'doctor') {
+  require('./doctor');
+} else {
+  process.stderr.write(`Unknown command: ${command}\n\n`);
+  process.stdout.write(HELP);
+  process.exit(1);
+}

package/src/cli/init.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+function detect() {
+  const cwd = process.cwd();
+  const pkgPath = path.join(cwd, 'package.json');
+
+  let pkg = {};
+  if (fs.existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch {
+      // ignore
+    }
+  }
+
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  };
+
+  const hasTailwindConfig =
+    fs.existsSync(path.join(cwd, 'tailwind.config.js')) ||
+    fs.existsSync(path.join(cwd, 'tailwind.config.cjs')) ||
+    fs.existsSync(path.join(cwd, 'tailwind.config.mjs')) ||
+    fs.existsSync(path.join(cwd, 'tailwind.config.ts'));
+
+  const hasTailwindDep = Boolean(
+    allDeps.tailwindcss || allDeps['@tailwindcss/postcss'],
+  );
+
+  const hasNextConfig =
+    fs.existsSync(path.join(cwd, 'next.config.js')) ||
+    fs.existsSync(path.join(cwd, 'next.config.mjs')) ||
+    fs.existsSync(path.join(cwd, 'next.config.ts'));
+
+  const hasExistingConfig =
+    fs.existsSync(path.join(cwd, '.stylelintrc')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.json')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.js')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.cjs')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.mjs')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.yml')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.yaml')) ||
+    fs.existsSync(path.join(cwd, 'stylelint.config.js')) ||
+    fs.existsSync(path.join(cwd, 'stylelint.config.cjs')) ||
+    fs.existsSync(path.join(cwd, 'stylelint.config.mjs')) ||
+    Boolean(pkg.stylelint);
+
+  const tailwind = hasTailwindConfig || hasTailwindDep;
+  const nextjs = hasNextConfig;
+
+  return { tailwind, nextjs, hasExistingConfig };
+}
+
+function selectProfile(stack) {
+  if (stack.nextjs && stack.tailwind) {
+    return 'react-tailwind';
+  }
+  if (stack.tailwind) {
+    return 'tailwind';
+  }
+  return 'recommended';
+}
+
+async function run() {
+  process.stdout.write('\nRhythmguard Init\n\n');
+
+  const stack = detect();
+
+  // Report detection
+  const detected = [];
+  if (stack.tailwind) detected.push('Tailwind CSS');
+  if (stack.nextjs) detected.push('Next.js');
+  if (detected.length > 0) {
+    process.stdout.write(`Detected: ${detected.join(', ')}\n`);
+  } else {
+    process.stdout.write('Detected: plain CSS project\n');
+  }
+
+  // Warn about existing config
+  if (stack.hasExistingConfig) {
+    process.stdout.write('\n⚠ Existing Stylelint config found.\n');
+    const answer = await ask('Overwrite? (y/n) ');
+    if (answer !== 'y' && answer !== 'yes') {
+      process.stdout.write('Aborted.\n');
+      process.exit(0);
+    }
+  }
+
+  const profile = selectProfile(stack);
+  process.stdout.write(`\nProfile: ${profile}\n`);
+
+  const answer = await ask('Write .stylelintrc.json? (y/n) ');
+  if (answer !== 'y' && answer !== 'yes') {
+    process.stdout.write('Aborted.\n');
+    process.exit(0);
+  }
+
+  const config = {
+    extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
+  };
+
+  const configPath = path.join(process.cwd(), '.stylelintrc.json');
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  process.stdout.write(`\n✓ Wrote ${configPath}\n`);
+  process.stdout.write(`\nNext steps:\n`);
+  process.stdout.write(`  npx stylelint "src/**/*.css"\n\n`);
+}
+
+run();

package/src/configs/react-tailwind.js

@@ -0,0 +1,25 @@
+'use strict';
+
+module.exports = {
+  extends: [
+    'stylelint-plugin-rhythmguard/configs/tailwind',
+  ],
+  ignoreFiles: [
+    '.next/**',
+    'out/**',
+    'node_modules/**',
+  ],
+  overrides: [
+    {
+      files: ['**/*.module.css'],
+      rules: {
+        'rhythmguard/use-scale': [
+          true,
+          {
+            propertyGroups: ['spacing', 'radius'],
+          },
+        ],
+      },
+    },
+  ],
+};

package/src/configs/react-tailwind.mjs

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

package/src/configs/tailwind.js

@@ -5,4 +5,13 @@ module.exports = {
     'stylelint-config-tailwindcss',
     'stylelint-plugin-rhythmguard/configs/strict',
   ],
+  rules: {
+    'rhythmguard/prefer-token': [
+      true,
+      {
+        tokenPattern: '^--spacing-',
+        tokenMapFromCssCustomProperties: true,
+      },
+    ],
+  },
 };

package/src/utils/token-map.js

@@ -79,6 +79,31 @@ function mergeExplicitTokenMap(target, source) {
   return target;
 }
 
+function walkTokenGroup(map, group, prefix, baseFontSize) {
+  for (const [key, value] of Object.entries(group)) {
+    const tokenName = `${prefix}-${key}`;
+
+    if (!isPlainObject(value)) {
+      continue;
+    }
+
+    // Leaf node with $value (DTCG)
+    if (typeof value.$value === 'string') {
+      addLengthValueMapping(map, value.$value, tokenName, baseFontSize);
+      continue;
+    }
+
+    // Leaf node with value (Style Dictionary)
+    if (typeof value.value === 'string') {
+      addLengthValueMapping(map, value.value, tokenName, baseFontSize);
+      continue;
+    }
+
+    // Nested group — recurse deeper
+    walkTokenGroup(map, value, tokenName, baseFontSize);
+  }
+}
+
 function mergeTokenMapFromFile({
   baseFontSize,
   currentMap,
@@ -130,8 +155,21 @@ function mergeTokenMapFromFile({
       continue;
     }
 
-    if (isPlainObject(entryValue) && typeof entryValue.value === 'string') {
-      addLengthValueMapping(nextMap, entryValue.value, entryKey, baseFontSize);
+    if (isPlainObject(entryValue)) {
+      // Style Dictionary format: { value: "16px" }
+      if (typeof entryValue.value === 'string') {
+        addLengthValueMapping(nextMap, entryValue.value, entryKey, baseFontSize);
+        continue;
+      }
+
+      // W3C DTCG format: { $value: "16px", $type: "dimension" }
+      if (typeof entryValue.$value === 'string') {
+        addLengthValueMapping(nextMap, entryValue.$value, entryKey, baseFontSize);
+        continue;
+      }
+
+      // Nested group — recurse (e.g. { spacing: { 4: { $value: "16px" } } })
+      walkTokenGroup(nextMap, entryValue, entryKey, baseFontSize);
     }
   }
 
@@ -324,7 +362,7 @@ function buildEffectiveTokenMap({
   root,
   tokenRegex,
 }) {
-  let tokenMap = mergeExplicitTokenMap({}, options.tokenMap);
+  let tokenMap = {};
 
   if (options.tokenMapFile) {
     tokenMap = mergeTokenMapFromFile({
@@ -350,6 +388,9 @@ function buildEffectiveTokenMap({
     });
   }
 
+  // Explicit tokenMap applied last so it takes precedence over auto-derived tokens
+  tokenMap = mergeExplicitTokenMap(tokenMap, options.tokenMap);
+
   return tokenMap;
 }