stylelint-plugin-rhythmguard 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -6,6 +6,14 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-05-19
+
+### Added
+
+- `rhythmguard audit` now reports design-system drift across CSS declarations and Tailwind arbitrary spacing class strings.
+- Added `--format markdown` / `--markdown` audit output for PR-ready design-system health reports.
+- Audit JSON now includes format version, CSS findings, Tailwind class-string findings, scan counts, top affected files, and summary totals while preserving existing top-level count fields.
+
 ## [1.4.2] - 2026-02-21
 
 ### Changed

package/README.md

@@ -77,6 +77,34 @@ This gives you spacing governance in both CSS files and JSX/TSX templates.
 
 I built Rhythmguard after 20 years of watching teams ignore spacing scales and ship arbitrary pixel values everywhere.
 
+## Try It in Your Browser
+
+**[petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/)** — paste CSS, see violations and token opportunities live. No install, no config.
+
+## Audit Before You Enforce
+
+Use the audit CLI to create a design-system drift report before turning rules into hard CI gates:
+
+```bash
+npx rhythmguard audit ./src
+npx rhythmguard audit ./src --format markdown
+npx rhythmguard audit ./src --json
+```
+
+The report covers authored CSS declarations and Tailwind arbitrary spacing values in common template/source files. Markdown output is PR-ready for UX developers, UX designers, and design-system owners:
+
+```md
+# Rhythmguard Design-System Audit
+
+| Metric | Value |
+| --- | ---: |
+| CSS files scanned | 47 |
+| Template files scanned | 83 |
+| Files with issues | 12 |
+| Total findings | 52 |
+| Scale cleanliness | 91% |
+```
+
 ## Installation
 
 ```bash
@@ -180,6 +208,7 @@ Framework-specific setup for Vue, Lit, Astro, and SvelteKit: [`docs/FRAMEWORKS.m
 ## 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)
+- Audit 2.0 validation and roadmap: [`docs/AUDIT_2_VALIDATION.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/AUDIT_2_VALIDATION.md)
 - Real-world before/after excerpts from public repos: [`docs/ADOPTION_DIFFS.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/ADOPTION_DIFFS.md)
 - Distribution submissions to Stylelint discovery surfaces: [`docs/DISTRIBUTION.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/DISTRIBUTION.md)
 
@@ -502,13 +531,13 @@ The `tailwind` config preset automatically extracts spacing tokens from Tailwind
 
 See [`docs/TAILWIND.md`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/TAILWIND.md) for full setup.
 
-### What Rhythmguard does not cover
+### What the Stylelint layer 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 Stylelint rule scope.
+Those are not Stylelint declaration nodes, so they are outside Stylelint rule scope. Use the ESLint companion rule below for scale-aware class-string enforcement.
 
 ### Companion ESLint layer for class strings
 
@@ -562,7 +591,7 @@ Suggested setup:
 Then pair with:
 
 - `stylelint-plugin-rhythmguard/eslint` for arbitrary spacing class-string scale enforcement.
-- `eslint-plugin-tailwindcss` for broader class-string linting and conventions.
+- `eslint-plugin-tailwindcss` for broader class-string linting and conventions. If your policy is to ban every arbitrary value, enable its `tailwindcss/no-arbitrary-value` rule; use Rhythmguard when you want spacing-specific scale checks and nearest-value fixes.
 - `prettier-plugin-tailwindcss` for deterministic class ordering.
 
 Detailed setup reference: [`docs/TAILWIND.md`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/TAILWIND.md).
@@ -658,8 +687,6 @@ Detailed methodology and custom args are documented in [`docs/BENCHMARKING.md`](
 ## Article
 
 - Dev.to: [Enforcing your spacing standards with Rhythmguard](https://dev.to/petrilahdelma/enforcing-your-spacing-standards-with-rhythmguard-a-custom-stylelint-plugin-1ojj)
-- Original article update note (Feb 21, 2026): [`docs/DEVTO_ORIGINAL_UPDATE_NOTE_2026-02-21.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/DEVTO_ORIGINAL_UPDATE_NOTE_2026-02-21.md)
-- Continuation draft (ready to publish): [`docs/DEVTO_CONTINUATION_2026-02-21.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/DEVTO_CONTINUATION_2026-02-21.md)
 
 ## Used by and Community Examples
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Token governance for CSS and Tailwind — enforce spacing scales, require design tokens, catch arbitrary values",
   "bin": {
-    "rhythmguard": "./src/cli/index.js"
+    "rhythmguard": "src/cli/index.js"
   },
   "keywords": [
     "stylelint",
@@ -99,7 +99,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/petrilahdelma/stylelint-plugin-rhythmguard.git"
+    "url": "https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard"
   },
   "homepage": "https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#readme",
   "bugs": {

package/src/cli/audit.js

@@ -3,159 +3,643 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { formatLength } = require('../utils/length');
+const { createTailwindClassAnalyzer } = require('../utils/tailwind-class-analysis');
+
 const args = process.argv.slice(3);
-const jsonMode = args.includes('--json');
-const dir = args.find((a) => !a.startsWith('-'));
+const pluginPath = path.resolve(__dirname, '..', 'index.js');
+
+const DEFAULT_SCALE = [0, 4, 8, 12, 16, 24, 32];
+const DEFAULT_BASE_FONT_SIZE = 16;
+const VALID_FORMATS = new Set(['text', 'json', 'markdown']);
+const SKIP_DIRS = new Set([
+  '.git',
+  '.next',
+  '.nuxt',
+  '.omx',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'out',
+]);
+const TEMPLATE_EXTENSIONS = new Set([
+  '.astro',
+  '.cjs',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.svelte',
+  '.ts',
+  '.tsx',
+  '.vue',
+]);
+
+const HELP = `Usage: rhythmguard audit <dir> [options]
+
+Options:
+  --format <text|json|markdown>  Output format (default: text)
+  --json                         Alias for --format json
+  --markdown                     Alias for --format markdown
+  --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)
+`;
+
+function parseArgs(argv) {
+  const parsed = {
+    baseFontSize: DEFAULT_BASE_FONT_SIZE,
+    dir: null,
+    format: 'text',
+    scale: DEFAULT_SCALE,
+  };
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+      continue;
+    }
+
+    if (arg === '--json') {
+      parsed.format = 'json';
+      continue;
+    }
+
+    if (arg === '--markdown') {
+      parsed.format = 'markdown';
+      continue;
+    }
+
+    if (arg === '--format') {
+      parsed.format = String(argv[++index] || '').toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith('--format=')) {
+      parsed.format = arg.slice('--format='.length).toLowerCase();
+      continue;
+    }
+
+    if (arg === '--scale') {
+      parsed.scale = parseScale(argv[++index]);
+      continue;
+    }
+
+    if (arg.startsWith('--scale=')) {
+      parsed.scale = parseScale(arg.slice('--scale='.length));
+      continue;
+    }
+
+    if (arg === '--base-font-size') {
+      parsed.baseFontSize = parseBaseFontSize(argv[++index]);
+      continue;
+    }
+
+    if (arg.startsWith('--base-font-size=')) {
+      parsed.baseFontSize = parseBaseFontSize(arg.slice('--base-font-size='.length));
+      continue;
+    }
+
+    if (!arg.startsWith('-') && !parsed.dir) {
+      parsed.dir = arg;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (!VALID_FORMATS.has(parsed.format)) {
+    throw new Error(`Invalid format "${parsed.format}". Expected text, json, or markdown.`);
+  }
 
-if (!dir) {
-  process.stderr.write('Usage: rhythmguard audit <dir> [--json]\n');
-  process.exit(1);
+  return parsed;
 }
 
-const resolvedDir = path.resolve(dir);
+function parseScale(raw) {
+  if (!raw) {
+    throw new Error('Missing value for --scale.');
+  }
+
+  const scale = raw.split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => {
+      const numeric = Number(part);
+      return Number.isFinite(numeric) && !/[a-z%]/i.test(part) ? numeric : part;
+    });
+
+  if (scale.length === 0) {
+    throw new Error('Scale must include at least one value.');
+  }
 
-if (!fs.existsSync(resolvedDir)) {
-  process.stderr.write(`Directory not found: ${dir}\n`);
-  process.exit(1);
+  return scale;
 }
 
-const GLOB_PATTERN = `${resolvedDir}/**/*.{css,module.css}`;
+function parseBaseFontSize(raw) {
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error('--base-font-size must be a positive number.');
+  }
 
-const pluginPath = path.resolve(__dirname, '..', 'index.js');
+  return value;
+}
 
-async function run() {
-  const { default: stylelint } = await import('stylelint');
+function assertDirectory(dir) {
+  if (!dir) {
+    process.stderr.write(HELP);
+    process.exit(1);
+  }
 
-  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`);
+  const resolvedDir = path.resolve(dir);
+  if (!fs.existsSync(resolvedDir)) {
+    process.stderr.write(`Directory not found: ${dir}\n`);
     process.exit(1);
   }
 
-  const fileResults = result.results || [];
-  const totalFiles = fileResults.length;
+  return resolvedDir;
+}
 
-  const offScaleValues = {};
-  const tokenOpportunities = {};
-  let filesWithIssues = 0;
-  let totalWarnings = 0;
+function walkFiles(rootDir) {
+  const files = [];
 
-  for (const fileResult of fileResults) {
-    const warnings = fileResult.warnings || [];
-    if (warnings.length > 0) {
-      filesWithIssues++;
+  function walk(currentDir) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) {
+          walk(path.join(currentDir, entry.name));
+        }
+        continue;
+      }
+
+      if (entry.isFile()) {
+        files.push(path.join(currentDir, entry.name));
+      }
     }
+  }
 
-    for (const warning of warnings) {
-      totalWarnings++;
-      const text = warning.text || '';
+  walk(rootDir);
+  return files;
+}
+
+function isCssFile(filePath) {
+  return filePath.endsWith('.css');
+}
+
+function isTemplateFile(filePath) {
+  return TEMPLATE_EXTENSIONS.has(path.extname(filePath));
+}
 
-      // Extract off-scale values from use-scale messages
-      // Format: Unexpected off-scale value "13px". Use scale values (nearest: 12px or 16px).
+async function runStylelintAudit(cssFiles, options) {
+  if (cssFiles.length === 0) {
+    return [];
+  }
+
+  const { default: stylelint } = await import('stylelint');
+
+  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)-',
+          },
+        ],
+      },
+    },
+  });
+
+  return result.results || [];
+}
+
+function collectCssFindings(fileResults) {
+  const findings = [];
+
+  for (const fileResult of fileResults) {
+    for (const warning of fileResult.warnings || []) {
+      const text = warning.text || '';
       const offScaleMatch = text.match(
-        /Unexpected off-scale value "([^"]+)"/,
+        /Unexpected (?:off-scale value|transform translation 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;
+
+      findings.push({
+        column: warning.column || 1,
+        file: formatPath(fileResult.source),
+        line: warning.line || 1,
+        rule: warning.rule || 'rhythmguard',
+        text,
+        type: tokenMatch ? 'token-opportunity' : 'off-scale',
+        value: tokenMatch ? tokenMatch[1] : offScaleMatch ? offScaleMatch[1] : null,
+      });
+    }
+  }
+
+  return findings;
+}
+
+function collectTailwindFindings(templateFiles, options) {
+  const analyzer = createTailwindClassAnalyzer(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: formatLength(analysis.nearest.lower, 'px'),
+              upper: formatLength(analysis.nearest.upper, 'px'),
+            }
+            : null,
+          rawValue: analysis.rawValue,
+          rule: 'rhythmguard-tailwind/tailwind-class-use-scale',
+          text: analysis.reason === 'negative'
+            ? `Unexpected Tailwind arbitrary spacing value "${segment.token}". Negative values are disabled for this rule.`
+            : `Unexpected Tailwind arbitrary spacing value "${segment.token}". Use scale values.`,
+          token: segment.token,
+          type: 'tailwind-arbitrary-spacing',
+          utility: analysis.utility,
+        });
       }
     }
   }
 
-  const sortedOffScale = Object.entries(offScaleValues)
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 10);
+  return findings;
+}
 
-  const sortedTokenOps = Object.entries(tokenOpportunities)
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 10);
+function findStringLiterals(source) {
+  const literals = [];
+  const literalPattern = /(["'`])((?:\\[\s\S]|(?!\1)[\s\S])*?)\1/g;
+  let match;
+
+  while ((match = literalPattern.exec(source)) !== null) {
+    literals.push({
+      quote: match[1],
+      value: match[2],
+      valueStart: match.index + 1,
+    });
+  }
+
+  return literals;
+}
+
+function getLineStarts(source) {
+  const starts = [0];
+
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === '\n') {
+      starts.push(index + 1);
+    }
+  }
+
+  return starts;
+}
 
-  if (jsonMode) {
-    const output = {
-      directory: dir,
+function offsetToLineColumn(lineStarts, offset) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (lineStarts[mid] <= offset) {
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  const lineIndex = Math.max(0, high);
+  return {
+    column: offset - lineStarts[lineIndex] + 1,
+    line: lineIndex + 1,
+  };
+}
+
+function buildReport({
+  cssFiles,
+  cssFindings,
+  dir,
+  templateFiles,
+  tailwindFindings,
+}) {
+  const offScaleValues = countByValue(cssFindings
+    .filter((finding) => finding.type === 'off-scale' && finding.value)
+    .map((finding) => finding.value));
+  const tokenOpportunities = countByValue(cssFindings
+    .filter((finding) => finding.type === 'token-opportunity' && finding.value)
+    .map((finding) => finding.value));
+  const tailwindArbitraryValues = countByValue(tailwindFindings
+    .map((finding) => finding.rawValue));
+  const issueFiles = new Set([
+    ...cssFindings.map((finding) => finding.file),
+    ...tailwindFindings.map((finding) => finding.file),
+  ]);
+  const topAffectedFiles = sortCountMap(countByValue([
+    ...cssFindings.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 filesWithIssues = issueFiles.size;
+  const scaleCleanliness = totalFiles > 0
+    ? Math.max(0, Math.round(((totalFiles - filesWithIssues) / totalFiles) * 100))
+    : 100;
+
+  return {
+    cssFilesScanned: cssFiles.length,
+    directory: dir,
+    filesWithIssues,
+    findings: {
+      css: cssFindings,
+      tailwind: tailwindFindings,
+    },
+    formatVersion: 2,
+    offScaleValues: Object.fromEntries(sortCountMap(offScaleValues).slice(0, 10)),
+    scaleCleanliness,
+    scanned: {
+      cssFiles: cssFiles.length,
+      templateFiles: templateFiles.length,
       totalFiles,
+    },
+    summary: {
+      cssWarnings: cssFindings.length,
       filesWithIssues,
-      totalWarnings,
-      offScaleValues: Object.fromEntries(sortedOffScale),
-      tokenOpportunities: Object.fromEntries(sortedTokenOps),
-    };
-    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+      scaleCleanliness,
+      tailwindArbitrarySpacing: tailwindFindings.length,
+      tokenOpportunities: sumCounts(tokenOpportunities),
+      totalFindings: totalWarnings,
+    },
+    tailwindArbitraryValues: Object.fromEntries(sortCountMap(tailwindArbitraryValues).slice(0, 10)),
+    templateFilesScanned: templateFiles.length,
+    tokenOpportunities: Object.fromEntries(sortCountMap(tokenOpportunities).slice(0, 10)),
+    topAffectedFiles: topAffectedFiles.map(([file, count]) => ({ count, file })),
+    totalFiles,
+    totalWarnings,
+  };
+}
+
+function countByValue(values) {
+  const counts = {};
+
+  for (const value of values) {
+    if (value) {
+      counts[value] = (counts[value] || 0) + 1;
+    }
+  }
+
+  return counts;
+}
+
+function sortCountMap(counts) {
+  return Object.entries(counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}
+
+function sumCounts(counts) {
+  return Object.values(counts).reduce((total, count) => total + count, 0);
+}
+
+function renderText(report) {
+  const lines = [
+    '',
+    '  ┌─ RHYTHMGUARD DESIGN-SYSTEM AUDIT ─────────────────────────┐',
+    `  │  ${report.directory.padEnd(58)}│`,
+    '  └─────────────────────────────────────────────────────────────┘',
+    '',
+    `  CSS files scanned        ${String(report.cssFilesScanned).padStart(4)}`,
+    `  Template files scanned   ${String(report.templateFilesScanned).padStart(4)}`,
+    `  Files with issues        ${String(report.filesWithIssues).padStart(4)}`,
+    `  Scale cleanliness        ${scoreBar(report.scaleCleanliness)}  ${report.scaleCleanliness}%`,
+    '',
+  ];
+
+  appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
+  appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
+  appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);
+
+  if (report.topAffectedFiles.length > 0) {
+    lines.push('  ── TOP AFFECTED FILES ──');
+    lines.push('');
+    const maxCount = Math.max(...report.topAffectedFiles.map(({ count }) => count));
+    for (const { file, count } of report.topAffectedFiles) {
+      lines.push(`  ${truncate(file, 34).padEnd(36)} ${histBar(count, maxCount)} ${count}`);
+    }
+    lines.push('');
+  }
+
+  if (report.totalWarnings === 0) {
+    lines.push('  ✓ No issues found. Your design-system rhythm is clean.');
+  } else {
+    lines.push('  → Run "npx stylelint --fix" for CSS declaration fixes.');
+    lines.push('  → Use "npx rhythmguard audit ./src --format markdown" for PR/design review.');
+  }
+  lines.push('');
+
+  return `${lines.join('\n')}\n`;
+}
+
+function appendHistogram(lines, title, counts) {
+  const entries = sortCountMap(counts);
+  const total = sumCounts(counts);
+
+  if (entries.length === 0) {
     return;
   }
 
-  // Human-readable output
-  const pct = totalFiles > 0
-    ? Math.round((filesWithIssues / totalFiles) * 100)
-    : 0;
+  lines.push(`  ── ${title} ──  ${total} total`);
+  lines.push('');
+  const maxCount = Math.max(...entries.map(([, count]) => count));
+  for (const [value, count] of entries) {
+    lines.push(`  ${value.padEnd(14)} ${histBar(count, maxCount)} ${count}`);
+  }
+  lines.push('');
+}
 
+function renderMarkdown(report) {
   const lines = [
+    '# Rhythmguard Design-System Audit',
+    '',
+    `Directory: \`${report.directory}\``,
     '',
-    `Rhythmguard Audit: ${dir}`,
+    '## Summary',
     '',
-    `Files scanned:     ${totalFiles}`,
-    `Files with issues: ${filesWithIssues} (${pct}%)`,
+    '| Metric | Value |',
+    '| --- | ---: |',
+    `| CSS files scanned | ${report.cssFilesScanned} |`,
+    `| Template files scanned | ${report.templateFilesScanned} |`,
+    `| Files with issues | ${report.filesWithIssues} |`,
+    `| Total findings | ${report.totalWarnings} |`,
+    `| Scale cleanliness | ${report.scaleCleanliness}% |`,
     '',
   ];
 
-  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}`);
+  appendMarkdownCounts(lines, 'CSS Off-Scale Values', report.offScaleValues);
+  appendMarkdownCounts(lines, 'CSS Token Opportunities', report.tokenOpportunities);
+  appendMarkdownCounts(lines, 'Tailwind Class-String Drift', report.tailwindArbitraryValues);
+
+  if (report.topAffectedFiles.length > 0) {
+    lines.push('## Top Affected Files');
+    lines.push('');
+    lines.push('| File | Findings |');
+    lines.push('| --- | ---: |');
+    for (const { file, count } of report.topAffectedFiles) {
+      lines.push(`| \`${escapeMarkdown(file)}\` | ${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}`);
+  if (report.findings.tailwind.length > 0) {
+    lines.push('## Tailwind Examples');
+    lines.push('');
+    lines.push('| File | Class | Suggested class |');
+    lines.push('| --- | --- | --- |');
+    for (const finding of report.findings.tailwind.slice(0, 10)) {
+      lines.push(`| \`${escapeMarkdown(`${finding.file}:${finding.line}`)}\` | \`${escapeMarkdown(finding.token)}\` | \`${escapeMarkdown(finding.fixedToken || 'n/a')}\` |`);
     }
     lines.push('');
   }
 
-  if (totalWarnings === 0) {
-    lines.push('No issues found. Your spacing is on scale.');
+  lines.push('## Recommended Next Actions');
+  lines.push('');
+  if (report.totalWarnings === 0) {
+    lines.push('- Keep Rhythmguard in CI to prevent new drift.');
   } else {
-    lines.push('Run "npx stylelint --fix" to auto-correct.');
+    lines.push('- Run deterministic autofix for CSS declarations where appropriate.');
+    lines.push('- Review Tailwind arbitrary spacing values with UX/design-system owners.');
+    lines.push('- Convert repeated raw on-scale values into existing design tokens.');
+  }
+  lines.push('');
+
+  return `${lines.join('\n')}\n`;
+}
+
+function appendMarkdownCounts(lines, title, counts) {
+  const entries = sortCountMap(counts);
+
+  if (entries.length === 0) {
+    return;
   }
 
+  lines.push(`## ${title}`);
+  lines.push('');
+  lines.push('| Value | Count |');
+  lines.push('| --- | ---: |');
+  for (const [value, count] of entries) {
+    lines.push(`| \`${escapeMarkdown(value)}\` | ${count} |`);
+  }
   lines.push('');
-  process.stdout.write(lines.join('\n'));
+}
+
+function histBar(count, maxCount) {
+  const width = 30;
+  const filled = Math.round((count / maxCount) * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function scoreBar(pct) {
+  const width = 20;
+  const filled = Math.round((pct / 100) * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function truncate(value, maxLength) {
+  if (value.length <= maxLength) {
+    return value;
+  }
+
+  return `…${value.slice(value.length - maxLength + 1)}`;
+}
+
+function escapeMarkdown(value) {
+  return String(value).replace(/\|/g, '\\|').replace(/`/g, '\\`');
+}
+
+function formatPath(filePath) {
+  return path.relative(process.cwd(), filePath).replace(/\\/g, '/');
+}
+
+async function run() {
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n\n${HELP}`);
+    process.exit(1);
+  }
+
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const resolvedDir = assertDirectory(parsed.dir);
+  const allFiles = walkFiles(resolvedDir);
+  const cssFiles = allFiles.filter(isCssFile);
+  const templateFiles = allFiles.filter(isTemplateFile);
+  const options = {
+    baseFontSize: parsed.baseFontSize,
+    scale: parsed.scale,
+  };
+
+  let cssResults;
+  try {
+    cssResults = await runStylelintAudit(cssFiles, options);
+  } catch (err) {
+    process.stderr.write(`Lint error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const report = buildReport({
+    cssFiles,
+    cssFindings: collectCssFindings(cssResults),
+    dir: parsed.dir,
+    tailwindFindings: collectTailwindFindings(templateFiles, options),
+    templateFiles,
+  });
+
+  if (parsed.format === 'json') {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (parsed.format === 'markdown') {
+    process.stdout.write(renderMarkdown(report));
+    return;
+  }
+
+  process.stdout.write(renderText(report));
 }
 
 run();

package/src/cli/index.js

@@ -6,7 +6,7 @@ const command = process.argv[2];
 const HELP = `Usage: rhythmguard <command>
 
 Commands:
-  audit <dir>   Report scale drift and token opportunities
+  audit <dir>   Report design-system drift across CSS and Tailwind class strings
   init          Scaffold a Rhythmguard config for your project
   doctor        Validate your Rhythmguard setup
 
@@ -16,6 +16,7 @@ Options:
 Examples:
   npx rhythmguard audit ./src
   npx rhythmguard audit ./src --json
+  npx rhythmguard audit ./src --format markdown
   npx rhythmguard init
   npx rhythmguard doctor
 `;

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

@@ -1,112 +1,11 @@
 'use strict';
 
-const {
-  formatLength,
-  nearestScaleValues,
-  normalizeScale,
-  numbersEqual,
-  parseLengthToken,
-  toPx,
-} = require('../../utils/length');
+const { formatLength } = require('../../utils/length');
+const { createTailwindClassAnalyzer } = require('../../utils/tailwind-class-analysis');
 
 const RULE_NAME = 'tailwind-class-use-scale';
 
-const ARBITRARY_SPACING_CLASS = /^(?<utility>-?(?:m(?:[trblxy])?|p(?:[trblxy])?|gap(?:-[xy])?|space-[xy]|inset(?:-[xy])?|top|right|bottom|left|translate-[xy]|scroll-(?:m|p)(?:[trblxy])?))-\[(?<rawValue>[^\]]+)\]$/;
-
-function getOptions(context) {
-  const option = context.options && context.options[0] ? context.options[0] : {};
-
-  return {
-    allowNegative: option.allowNegative !== false,
-    baseFontSize:
-      typeof option.baseFontSize === 'number' &&
-      Number.isFinite(option.baseFontSize) &&
-      option.baseFontSize > 0
-        ? option.baseFontSize
-        : 16,
-    scale: Array.isArray(option.scale)
-      ? option.scale
-      : [0, 4, 8, 12, 16, 24, 32],
-    units: Array.isArray(option.units)
-      ? option.units.map((unit) => String(unit).toLowerCase())
-      : ['px', 'rem', 'em'],
-  };
-}
-
-function findClassSegments(value) {
-  const segments = [];
-  const tokenRegex = /\S+/g;
-  let match;
-
-  while ((match = tokenRegex.exec(value)) !== null) {
-    segments.push({
-      start: match.index,
-      token: match[0],
-    });
-  }
-
-  return segments;
-}
-
-function analyzeToken(token, options, scalePx) {
-  const match = token.match(ARBITRARY_SPACING_CLASS);
-  if (!match || !match.groups) {
-    return null;
-  }
-
-  const parsedLength = parseLengthToken(match.groups.rawValue);
-  if (!parsedLength || parsedLength.number === 0 || parsedLength.unit === '') {
-    return null;
-  }
-
-  if (!options.allowNegative && parsedLength.number < 0) {
-    return {
-      nearest: null,
-      parsedLength,
-      reason: 'negative',
-    };
-  }
-
-  if (!options.units.includes(parsedLength.unit)) {
-    return null;
-  }
-
-  const pxValue = toPx(Math.abs(parsedLength.number), parsedLength.unit, options.baseFontSize);
-  if (pxValue === null) {
-    return null;
-  }
-
-  const isOnScale = scalePx.some((entry) => numbersEqual(entry, pxValue));
-  if (isOnScale) {
-    return null;
-  }
-
-  const nearest = nearestScaleValues(pxValue, scalePx);
-  if (!nearest) {
-    return null;
-  }
-
-  const signedNearest = parsedLength.number < 0
-    ? -Math.abs(nearest.nearest)
-    : nearest.nearest;
-
-  const replacementValuePx = signedNearest;
-  const replacementNumber = parsedLength.unit === 'px'
-    ? replacementValuePx
-    : replacementValuePx / options.baseFontSize;
-
-  const replacementValue = formatLength(replacementNumber, parsedLength.unit);
-  const fixedToken = token.replace(match.groups.rawValue, replacementValue);
-
-  return {
-    fixedToken,
-    nearest,
-    parsedLength,
-    reason: 'off-scale',
-  };
-}
-
-function maybeCheckNodeText(node, sourceCode, context, options, scalePx, allowFix) {
+function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
   const rawText = sourceCode.getText(node);
   let value = null;
   let quote = null;
@@ -124,16 +23,27 @@ function maybeCheckNodeText(node, sourceCode, context, options, scalePx, allowFi
     return;
   }
 
-  const segments = findClassSegments(value);
-  if (segments.length === 0) {
+  const findings = analyzer.analyzeClassString(value);
+  if (findings.length === 0) {
     return;
   }
-  for (const segment of segments) {
-    const analysis = analyzeToken(segment.token, options, scalePx);
-    if (!analysis) {
-      continue;
+
+  let fixedValue = value;
+  let fixedValueOffset = 0;
+
+  for (const { analysis, segment } of findings) {
+    if (allowFix && analysis.reason !== 'negative' && 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
       ? formatLength(analysis.nearest.lower, 'px')
       : 'n/a';
@@ -147,12 +57,8 @@ function maybeCheckNodeText(node, sourceCode, context, options, scalePx, allowFi
           : `Unexpected Tailwind arbitrary spacing value "${segment.token}". Use scale values (nearest: ${lower} or ${upper}).`,
       node,
       fix:
-        allowFix && analysis.reason !== 'negative' && node.type === 'Literal'
-          ? (fixer) => {
-            const nextValue = `${value.slice(0, segment.start)}${analysis.fixedToken}${value.slice(segment.start + segment.token.length)}`;
-            const escaped = nextValue.replace(new RegExp(quote, 'g'), `\\${quote}`);
-            return fixer.replaceText(node, `${quote}${escaped}${quote}`);
-          }
+        fixedText && analysis.reason !== 'negative'
+          ? (fixer) => fixer.replaceText(node, fixedText)
           : null,
     });
   }
@@ -189,16 +95,15 @@ module.exports = {
     ],
   },
   create(context) {
-    const options = getOptions(context);
-    const scalePx = normalizeScale(options.scale, options.baseFontSize);
+    const analyzer = createTailwindClassAnalyzer(context.options && context.options[0]);
     const sourceCode = context.sourceCode || context.getSourceCode();
 
     return {
       Literal(node) {
-        maybeCheckNodeText(node, sourceCode, context, options, scalePx, true);
+        maybeCheckNodeText(node, sourceCode, context, analyzer, true);
       },
       TemplateElement(node) {
-        maybeCheckNodeText(node, sourceCode, context, options, scalePx, false);
+        maybeCheckNodeText(node, sourceCode, context, analyzer, false);
       },
     };
   },

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

@@ -0,0 +1,221 @@
+'use strict';
+
+const {
+  formatLength,
+  nearestScaleValues,
+  normalizeScale,
+  numbersEqual,
+  parseLengthToken,
+  toPx,
+} = require('./length');
+
+const DEFAULT_SCALE = [0, 4, 8, 12, 16, 24, 32];
+const DEFAULT_UNITS = ['px', 'rem', 'em'];
+
+const ARBITRARY_SPACING_CLASS = /^(?<utility>-?(?:m(?:[trblxy])?|p(?:[trblxy])?|gap(?:-[xy])?|space-[xy]|inset(?:-[xy])?|top|right|bottom|left|translate-[xy]|scroll-(?:m|p)(?:[trblxy])?))-\[(?<rawValue>[^\]]+)\]$/;
+
+function normalizeTailwindClassOptions(option = {}) {
+  return {
+    allowNegative: option.allowNegative !== false,
+    baseFontSize:
+      typeof option.baseFontSize === 'number' &&
+      Number.isFinite(option.baseFontSize) &&
+      option.baseFontSize > 0
+        ? option.baseFontSize
+        : 16,
+    scale: Array.isArray(option.scale) ? option.scale : DEFAULT_SCALE,
+    units: Array.isArray(option.units)
+      ? option.units.map((unit) => String(unit).toLowerCase())
+      : DEFAULT_UNITS,
+  };
+}
+
+function findClassSegments(value) {
+  const segments = [];
+  const tokenRegex = /\S+/g;
+  let match;
+
+  while ((match = tokenRegex.exec(value)) !== null) {
+    segments.push({
+      start: match.index,
+      token: match[0],
+    });
+  }
+
+  return segments;
+}
+
+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 hasInvalidVariantPrefix(prefix) {
+  let bracketDepth = 0;
+
+  for (const character of prefix) {
+    if (character === '[') {
+      bracketDepth++;
+      continue;
+    }
+
+    if (character === ']' && bracketDepth > 0) {
+      bracketDepth--;
+      continue;
+    }
+
+    if (bracketDepth === 0 && /["'=<]/.test(character)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function analyzeClassToken(token, options, scalePx) {
+  const parsedToken = parseClassToken(token);
+  if (parsedToken.prefix && hasInvalidVariantPrefix(parsedToken.prefix)) {
+    return null;
+  }
+
+  const match = parsedToken.candidate.match(ARBITRARY_SPACING_CLASS);
+  if (!match || !match.groups) {
+    return null;
+  }
+
+  const parsedLength = parseLengthToken(match.groups.rawValue);
+  if (!parsedLength || parsedLength.number === 0 || parsedLength.unit === '') {
+    return null;
+  }
+
+  if (!options.allowNegative && parsedLength.number < 0) {
+    return {
+      fixedToken: null,
+      nearest: null,
+      parsedLength,
+      reason: 'negative',
+      rawValue: match.groups.rawValue,
+      utility: match.groups.utility,
+    };
+  }
+
+  if (!options.units.includes(parsedLength.unit)) {
+    return null;
+  }
+
+  const pxValue = toPx(Math.abs(parsedLength.number), parsedLength.unit, options.baseFontSize);
+  if (pxValue === null) {
+    return null;
+  }
+
+  const isOnScale = scalePx.some((entry) => numbersEqual(entry, pxValue));
+  if (isOnScale) {
+    return null;
+  }
+
+  const nearest = nearestScaleValues(pxValue, scalePx);
+  if (!nearest) {
+    return null;
+  }
+
+  const signedNearest = parsedLength.number < 0
+    ? -Math.abs(nearest.nearest)
+    : nearest.nearest;
+
+  const replacementNumber = parsedLength.unit === 'px'
+    ? signedNearest
+    : signedNearest / options.baseFontSize;
+
+  const replacementValue = formatLength(replacementNumber, parsedLength.unit);
+  const fixedCandidate = parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
+  const fixedToken = `${parsedToken.prefix}${parsedToken.leadingImportant}${fixedCandidate}${parsedToken.trailingImportant}`;
+
+  return {
+    fixedToken,
+    nearest,
+    parsedLength,
+    reason: 'off-scale',
+    rawValue: match.groups.rawValue,
+    utility: match.groups.utility,
+  };
+}
+
+function createTailwindClassAnalyzer(option = {}) {
+  const options = normalizeTailwindClassOptions(option);
+  const scalePx = normalizeScale(options.scale, options.baseFontSize);
+
+  return {
+    analyzeClassString(value) {
+      const findings = [];
+
+      for (const segment of findClassSegments(value)) {
+        const analysis = analyzeClassToken(segment.token, options, scalePx);
+        if (analysis) {
+          findings.push({ analysis, segment });
+        }
+      }
+
+      return findings;
+    },
+    analyzeToken(token) {
+      return analyzeClassToken(token, options, scalePx);
+    },
+    options,
+    scalePx,
+  };
+}
+
+module.exports = {
+  createTailwindClassAnalyzer,
+  findClassSegments,
+  normalizeTailwindClassOptions,
+};