@versini/ui-styles 8.0.1 → 8.1.1

package/README.md

@@ -11,6 +11,7 @@ This package provides the core TailwindCSS configuration, custom styles, and des
 - [Features](#features)
 - [Installation](#installation)
 - [Usage](#usage)
+- [CLI Tools](#cli-tools)
 
 ## Features
 
@@ -19,6 +20,7 @@ This package provides the core TailwindCSS configuration, custom styles, and des
 - **🎭 Theme Support**: Built-in light, dark, and system theme support
 - **📐 Typography**: Optimized typography scales and spacing
 - **🌈 Color Tokens**: Semantic color tokens for consistent theming
+- **🩺 ui-doctor CLI**: Detect raw Tailwind color classes and suggest design tokens
 
 ## Installation
 
@@ -72,3 +74,93 @@ module.exports = {
 
 @import "@versini/ui-styles/dist/styles.css";
 ```
+
+## CLI Tools
+
+### ui-doctor
+
+A CLI tool to detect raw Tailwind CSS color classes (like `bg-slate-500`, `text-red-400`) and suggest semantic design tokens from the `@versini/ui-styles` package.
+
+#### Usage
+
+```bash
+# Scan current directory
+npx ui-doctor
+
+# Scan a specific directory
+npx ui-doctor ./src
+
+# Scan with specific file extensions
+npx ui-doctor -e tsx,ts
+
+# Output in JSON format (for CI/CD integration)
+npx ui-doctor --json
+
+# Combine options
+npx ui-doctor ./src --json -e tsx,ts
+```
+
+#### Options
+
+| Option                | Alias | Description                        | Default                        |
+| --------------------- | ----- | ---------------------------------- | ------------------------------ |
+| `--path <path>`       | `-p`  | Path to scan                       | `.` (current directory)        |
+| `--extensions <ext>`  | `-e`  | Comma-separated file extensions    | `js,jsx,ts,tsx`                |
+| `--ignore <patterns>` | `-i`  | Comma-separated patterns to ignore | `node_modules,dist,build,.git` |
+| `--json`              |       | Output in JSON format              | `false`                        |
+| `--help`              | `-h`  | Show help message                  |                                |
+| `--version`           | `-v`  | Show version number                |                                |
+
+#### Example Output
+
+```
+ui-doctor - Scanning for raw Tailwind color classes...
+
+✗ src/components/Button.tsx:15
+  <div className="bg-slate-500 text-white">
+  Found: bg-slate-500
+  Suggestion: Use 'bg-surface-medium'
+
+✗ src/components/Card.tsx:23
+  <p className="text-red-400">Error</p>
+  Found: text-red-400
+  Suggestion: Use 'text-copy-error-light'
+  Other options: text-border-danger-medium
+
+──────────────────────────────────────────────────
+Summary: 2 violations found in 2 files
+Scanned 50 files in 25ms
+```
+
+#### JSON Output
+
+When using `--json`, the output is formatted for CI/CD integration:
+
+```json
+{
+  "filesScanned": 50,
+  "totalViolations": 2,
+  "duration": 25,
+  "violations": [
+    {
+      "file": "src/components/Button.tsx",
+      "issues": [
+        {
+          "line": 15,
+          "column": 12,
+          "class": "bg-slate-500",
+          "prefix": "bg",
+          "color": "slate",
+          "shade": "500",
+          "suggestions": ["bg-surface-medium"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### Exit Codes
+
+- `0` - No violations found
+- `1` - Violations found or error occurred

package/dist/cli/tokens.ts

@@ -0,0 +1,137 @@
+import colors from "tailwindcss/colors";
+
+const errorColorLight = "#ff3f3f";
+const accentColor = colors.violet[300];
+
+export default {
+	colors: {
+		/**
+		 * Action tokens.
+		 * To be used for background color for interactive elements
+		 * like buttons, links, etc.
+		 * @example bg-action-dark, hover:bg-action-dark-hover
+		 */
+		"action-dark": colors.slate[600],
+		"action-dark-hover": colors.slate[700],
+		"action-dark-active": colors.slate[800],
+
+		"action-light": accentColor,
+		"action-light-hover": colors.violet[400],
+		"action-light-active": colors.violet[500],
+
+		"action-danger-dark": colors.red[900],
+		"action-danger-dark-hover": colors.red[700],
+		"action-danger-dark-active": colors.red[600],
+
+		"action-danger-light": colors.red[900],
+		"action-danger-light-hover": colors.red[700],
+		"action-danger-light-active": colors.red[600],
+
+		"action-selected-dark": colors.green[700],
+		"action-selected-dark-hover": colors.green[600],
+		"action-selected-dark-active": colors.green[500],
+
+		/**
+		 * Surface tokens.
+		 * To be used for background colors of containers, cards, modals, etc.
+		 * @example bg-surface-medium
+		 */
+		"surface-darker": colors.slate[900],
+		"surface-dark": colors.slate[700],
+		"surface-medium": colors.slate[500],
+		"surface-light": colors.slate[300],
+		"surface-lighter": colors.slate[200],
+		"surface-lightest": colors.slate[100],
+		"surface-accent": "#0071EB",
+		"surface-information": colors.violet[200],
+		"surface-success": colors.green[200],
+		"surface-warning": colors.orange[200],
+		"surface-error": colors.red[200],
+
+		/**
+		 * Typography tokens.
+		 * To be used for text colors.
+		 * @example text-copy-light, hover:text-copy-light-hover
+		 */
+		"copy-dark": colors.slate[900],
+		"copy-dark-hover": colors.slate[900],
+		"copy-dark-active": colors.slate[900],
+
+		"copy-medium": colors.slate[400],
+		"copy-medium-hover": colors.slate[400],
+		"copy-medium-active": colors.slate[400],
+
+		"copy-light": colors.slate[200],
+		"copy-light-hover": colors.slate[200],
+		"copy-light-active": colors.slate[200],
+
+		"copy-lighter": colors.white,
+		"copy-lighter-hover": colors.white,
+		"copy-lighter-active": colors.white,
+
+		"copy-error": colors.red[800],
+		"copy-error-dark": colors.red[700],
+		"copy-error-light": colors.red[500],
+
+		"copy-success": colors.green[800],
+		"copy-success-light": colors.green[500],
+
+		"copy-information": colors.violet[800],
+		"copy-warning": colors.orange[800],
+
+		"copy-accent": "#a9b9ad",
+		"copy-accent-dark": "#cde8d4",
+
+		/**
+		 * Border tokens.
+		 * To be used for border colors.
+		 * @example border-border-medium
+		 */
+		"border-dark": colors.slate[900],
+		"border-medium": colors.slate[400],
+		"border-light": colors.slate[300],
+		"border-accent": accentColor,
+
+		"border-danger-dark": colors.red[900],
+		"border-danger-medium": colors.red[400],
+		"border-danger-light": colors.red[300],
+
+		"border-selected-dark": colors.green[800],
+		"border-selected-medium": colors.green[400],
+		"border-selected-light": colors.green[300],
+
+		"border-white": colors.white,
+		"border-error-dark": colors.red[700],
+		"border-error-light": errorColorLight,
+
+		"border-information": colors.violet[400],
+		"border-success": colors.green[400],
+		"border-warning": colors.orange[400],
+		"border-error": colors.red[400],
+
+		/**
+		 * Focus tokens.
+		 * To be used for focus outlines and rings.
+		 * @example outline-focus-dark, focus:ring-focus-dark
+		 */
+		"focus-dark": colors.slate[400],
+		"focus-light": colors.slate[400],
+		"focus-error-dark": colors.red[700],
+		"focus-error-light": errorColorLight,
+
+		/**
+		 * Table tokens
+		 * To be used for table row and header backgrounds.
+		 * @example bg-table-dark-odd
+		 */
+		"table-head-dark": colors.gray[950],
+		"table-dark": colors.gray[700],
+		"table-dark-odd": colors.gray[800],
+		"table-dark-even": colors.gray[900],
+
+		"table-head-light": colors.gray[100],
+		"table-light": colors.gray[100],
+		"table-light-odd": colors.gray[200],
+		"table-light-even": colors.gray[300],
+	},
+};

package/dist/cli/ui-doctor.js

@@ -0,0 +1,630 @@
+#!/usr/bin/env node
+import fs, { readFileSync, existsSync } from "node:fs";
+import path, { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const TAILWIND_COLOR_PALETTES = [
+  "red",
+  "orange",
+  "amber",
+  "yellow",
+  "lime",
+  "green",
+  "emerald",
+  "teal",
+  "cyan",
+  "sky",
+  "blue",
+  "indigo",
+  "violet",
+  "purple",
+  "fuchsia",
+  "pink",
+  "rose",
+  "slate",
+  "gray",
+  "zinc",
+  "neutral",
+  "stone"
+];
+const TAILWIND_SHADES = [
+  "50",
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900",
+  "950"
+];
+const COLOR_UTILITY_PREFIXES = [
+  "bg",
+  "text",
+  "border",
+  "border-t",
+  "border-b",
+  "border-l",
+  "border-r",
+  "border-x",
+  "border-y",
+  "outline",
+  "ring",
+  "shadow",
+  "accent",
+  "caret",
+  "fill",
+  "stroke",
+  "decoration",
+  "divide",
+  "from",
+  "via",
+  "to",
+  "placeholder"
+];
+function buildColorPattern() {
+  const prefixes = COLOR_UTILITY_PREFIXES.join("|");
+  const colors2 = TAILWIND_COLOR_PALETTES.join("|");
+  const shades = TAILWIND_SHADES.join("|");
+  const pattern = `(?:^|[\\s"'\`{])(((?:[a-zA-Z0-9_-]+:)*)(${prefixes})-(${colors2})-(${shades}))(?:/(\\d+(?:\\.\\d+)?%?))?(?=$|[\\s"'\`}])`;
+  return new RegExp(pattern, "g");
+}
+function findColorClassesInLine(line, lineNumber) {
+  const matches = [];
+  const pattern = buildColorPattern();
+  let match = pattern.exec(line);
+  while (match !== null) {
+    const fullMatch = match[1];
+    const variantString = match[2] || "";
+    const prefix = match[3];
+    const color = match[4];
+    const shade = match[5];
+    const opacity = match[6];
+    const variants = variantString ? variantString.split(":").filter((v) => v.length > 0) : [];
+    matches.push({
+      fullMatch: opacity ? `${fullMatch}/${opacity}` : fullMatch,
+      variants,
+      prefix,
+      color,
+      shade,
+      opacity,
+      line: lineNumber,
+      column: match.index + 1,
+      lineContent: line
+    });
+    match = pattern.exec(line);
+  }
+  return matches;
+}
+function findColorClasses(content) {
+  const lines = content.split("\n");
+  const allMatches = [];
+  for (let i = 0; i < lines.length; i++) {
+    const lineMatches = findColorClassesInLine(lines[i], i + 1);
+    allMatches.push(...lineMatches);
+  }
+  return allMatches;
+}
+const DEFAULT_EXTENSIONS = ["js", "jsx", "ts", "tsx"];
+const DEFAULT_IGNORE = [
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  "coverage",
+  ".next",
+  ".rslib",
+  "tmp"
+];
+function shouldIgnore(filePath, ignorePatterns) {
+  const parts = filePath.split(path.sep);
+  return parts.some((part) => ignorePatterns.includes(part));
+}
+function hasAllowedExtension(filePath, extensions) {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  return extensions.includes(ext);
+}
+function scanDirectory(dirPath, rootPath, options, results) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    const relativePath = path.relative(rootPath, fullPath);
+    if (shouldIgnore(relativePath, options.ignore)) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      scanDirectory(fullPath, rootPath, options, results);
+    } else if (entry.isFile() && hasAllowedExtension(entry.name, options.extensions)) {
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        results.push({
+          absolutePath: fullPath,
+          relativePath,
+          content
+        });
+      } catch {
+      }
+    }
+  }
+}
+function scanFiles(targetPath, options) {
+  const resolvedPath = path.resolve(targetPath);
+  const fullOptions = {
+    extensions: options?.extensions || DEFAULT_EXTENSIONS,
+    ignore: options?.ignore || DEFAULT_IGNORE
+  };
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`Path does not exist: ${resolvedPath}`);
+  }
+  const stats = fs.statSync(resolvedPath);
+  const results = [];
+  if (stats.isFile()) {
+    if (hasAllowedExtension(resolvedPath, fullOptions.extensions)) {
+      const content = fs.readFileSync(resolvedPath, "utf-8");
+      results.push({
+        absolutePath: resolvedPath,
+        relativePath: path.basename(resolvedPath),
+        content
+      });
+    }
+  } else if (stats.isDirectory()) {
+    scanDirectory(resolvedPath, resolvedPath, fullOptions, results);
+  }
+  return results;
+}
+function getDefaultScanOptions() {
+  return {
+    extensions: [...DEFAULT_EXTENSIONS],
+    ignore: [...DEFAULT_IGNORE]
+  };
+}
+const colors = {
+  reset: "\x1B[0m",
+  bright: "\x1B[1m",
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m"
+};
+function truncateLine(line, maxLength) {
+  if (line.length <= maxLength) {
+    return line;
+  }
+  return `${line.slice(0, maxLength - 3)}...`;
+}
+function formatConsoleReport(report) {
+  const lines = [];
+  lines.push("");
+  lines.push(
+    `${colors.cyan}${colors.bright}ui-doctor${colors.reset} - Scanning for raw Tailwind color classes...`
+  );
+  lines.push("");
+  if (report.filesWithViolations.length === 0) {
+    lines.push(
+      `${colors.green}✓${colors.reset} No raw Tailwind color classes found!`
+    );
+    lines.push(
+      `${colors.dim}  Scanned ${report.filesScanned} files in ${report.duration}ms${colors.reset}`
+    );
+    lines.push("");
+    return lines.join("\n");
+  }
+  for (const fileViolation of report.filesWithViolations) {
+    for (const violation of fileViolation.violations) {
+      const { match, suggestions } = violation;
+      lines.push(
+        `${colors.red}✗${colors.reset} ${colors.cyan}${fileViolation.filePath}${colors.reset}:${colors.yellow}${match.line}${colors.reset}`
+      );
+      const linePreview = truncateLine(match.lineContent.trim(), 80);
+      lines.push(`  ${colors.dim}${linePreview}${colors.reset}`);
+      lines.push(
+        `  ${colors.red}Found:${colors.reset} ${colors.bright}${match.fullMatch}${colors.reset}`
+      );
+      if (suggestions.length > 0) {
+        const topSuggestion = suggestions[0];
+        lines.push(
+          `  ${colors.green}Suggestion:${colors.reset} Use '${colors.green}${topSuggestion.suggestedClass}${colors.reset}'`
+        );
+        if (suggestions.length > 1) {
+          const otherSuggestions = suggestions.slice(1, 4).map((s) => s.suggestedClass).join(", ");
+          lines.push(
+            `  ${colors.dim}Other options: ${otherSuggestions}${colors.reset}`
+          );
+        }
+      } else {
+        lines.push(
+          `  ${colors.yellow}No token available${colors.reset} for this color combination`
+        );
+      }
+      lines.push("");
+    }
+  }
+  lines.push(`${colors.dim}${"─".repeat(50)}${colors.reset}`);
+  const fileCount = report.filesWithViolations.length;
+  const violationWord = report.totalViolations === 1 ? "violation" : "violations";
+  const fileWord = fileCount === 1 ? "file" : "files";
+  lines.push(
+    `${colors.red}${colors.bright}Summary:${colors.reset} ${report.totalViolations} ${violationWord} found in ${fileCount} ${fileWord}`
+  );
+  lines.push(
+    `${colors.dim}Scanned ${report.filesScanned} files in ${report.duration}ms${colors.reset}`
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function formatJsonReport(report) {
+  const jsonReport = {
+    filesScanned: report.filesScanned,
+    totalViolations: report.totalViolations,
+    duration: report.duration,
+    violations: report.filesWithViolations.map((fv) => ({
+      file: fv.filePath,
+      issues: fv.violations.map((v) => ({
+        line: v.match.line,
+        column: v.match.column,
+        class: v.match.fullMatch,
+        prefix: v.match.prefix,
+        color: v.match.color,
+        shade: v.match.shade,
+        suggestions: v.suggestions.map((s) => s.suggestedClass)
+      }))
+    }))
+  };
+  return JSON.stringify(jsonReport, null, 2);
+}
+function printReport(report, json = false) {
+  if (json) {
+    console.log(formatJsonReport(report));
+  } else {
+    console.log(formatConsoleReport(report));
+  }
+}
+function getTokensFilePath() {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  const prodPath = resolve(__dirname, "tokens.ts");
+  if (existsSync(prodPath)) {
+    return prodPath;
+  }
+  const devPath = resolve(__dirname, "../plugins/tailwindcss/tokens.ts");
+  if (existsSync(devPath)) {
+    return devPath;
+  }
+  return devPath;
+}
+function parseVariables(content) {
+  const variables = /* @__PURE__ */ new Map();
+  const constPattern = /const\s+(\w+)\s*=\s*([^;]+);/g;
+  const matches = content.matchAll(constPattern);
+  for (const match of matches) {
+    const varName = match[1];
+    const varValue = match[2].trim();
+    const colorMatch = varValue.match(/colors\.(\w+)\[(\d+)\]/);
+    if (colorMatch) {
+      variables.set(varName, `colors.${colorMatch[1]}[${colorMatch[2]}]`);
+    } else if (varValue.startsWith('"') || varValue.startsWith("'")) {
+      variables.set(varName, varValue.replace(/["']/g, ""));
+    }
+  }
+  return variables;
+}
+function resolveTokenValue(value, variables) {
+  if (value.match(/colors\.\w+\[\d+\]/)) {
+    return value;
+  }
+  const resolved = variables.get(value);
+  if (resolved) {
+    return resolved;
+  }
+  return value;
+}
+function parseColorsObject(content, variables) {
+  const colors2 = {};
+  const colorsMatch = content.match(/colors:\s*\{([\s\S]*?)\n\t\}/);
+  if (!colorsMatch) {
+    return colors2;
+  }
+  const colorsContent = colorsMatch[1];
+  const tokenPattern = /"([^"]+)":\s*([^,\n]+)/g;
+  const matches = colorsContent.matchAll(tokenPattern);
+  for (const match of matches) {
+    const tokenName = match[1];
+    let tokenValue = match[2].trim();
+    tokenValue = tokenValue.replace(/,$/, "").trim();
+    const resolved = resolveTokenValue(tokenValue, variables);
+    colors2[tokenName] = resolved;
+  }
+  return colors2;
+}
+function parseTokensFile(filePath) {
+  const errors = [];
+  const tokens = { colors: {} };
+  const tokensPath = getTokensFilePath();
+  let content;
+  try {
+    content = readFileSync(tokensPath, "utf-8");
+  } catch (_error) {
+    errors.push(`Failed to read tokens file: ${tokensPath}`);
+    return { tokens, errors };
+  }
+  const variables = parseVariables(content);
+  tokens.colors = parseColorsObject(content, variables);
+  if (Object.keys(tokens.colors).length === 0) {
+    errors.push("No tokens found in the colors object");
+  }
+  return { tokens, errors };
+}
+function loadTokenDefinitions() {
+  const result = parseTokensFile();
+  if (result.errors.length > 0) {
+    throw new Error(`Token parsing errors: ${result.errors.join(", ")}`);
+  }
+  return result.tokens;
+}
+const PREFIX_TO_TOKEN_CATEGORY = {
+  bg: ["surface", "action", "table"],
+  text: ["copy"],
+  border: ["border"],
+  "border-t": ["border"],
+  "border-b": ["border"],
+  "border-l": ["border"],
+  "border-r": ["border"],
+  "border-x": ["border"],
+  "border-y": ["border"],
+  outline: ["border", "focus"],
+  ring: ["focus", "border"],
+  shadow: ["surface"],
+  accent: ["action", "surface"],
+  caret: ["copy"],
+  fill: ["copy", "surface"],
+  stroke: ["copy", "border"],
+  decoration: ["copy"],
+  divide: ["border"],
+  from: ["surface", "action"],
+  via: ["surface", "action"],
+  to: ["surface", "action"],
+  placeholder: ["copy"]
+};
+function buildColorKey(color, shade) {
+  return `${color}-${shade}`;
+}
+function parseTokenValue(value) {
+  const match = value.match(/colors\.(\w+)\[(\d+)\]/);
+  if (match) {
+    const color = match[1];
+    const shade = match[2];
+    return { color, shade };
+  }
+  return null;
+}
+class TokenMapper {
+  colorToTokens;
+  tokenDefinitions;
+  constructor(tokenDefinitions) {
+    this.tokenDefinitions = tokenDefinitions;
+    this.colorToTokens = /* @__PURE__ */ new Map();
+    this.buildLookupTable();
+  }
+  /**
+   * Build the reverse lookup table from colors to tokens.
+   */
+  buildLookupTable() {
+    for (const [tokenName, colorRef] of Object.entries(
+      this.tokenDefinitions.colors
+    )) {
+      const parsed = parseTokenValue(colorRef);
+      if (parsed) {
+        const key = buildColorKey(parsed.color, parsed.shade);
+        const existing = this.colorToTokens.get(key) || [];
+        existing.push({
+          tokenName,
+          colorReference: colorRef,
+          suggestedClass: "",
+          // Will be filled when suggesting
+          isExactMatch: true
+        });
+        this.colorToTokens.set(key, existing);
+      }
+    }
+  }
+  /**
+   * Get token suggestions for a raw color class match.
+   * Only returns tokens from semantically appropriate categories.
+   */
+  getSuggestions(match) {
+    const key = buildColorKey(match.color, match.shade);
+    const tokens = this.colorToTokens.get(key);
+    if (!tokens || tokens.length === 0) {
+      return [];
+    }
+    const preferredCategories = PREFIX_TO_TOKEN_CATEGORY[match.prefix] || [];
+    const variantPrefix = match.variants.length > 0 ? `${match.variants.join(":")}:` : "";
+    const suggestions = tokens.filter((token) => {
+      if (preferredCategories.length === 0) {
+        return true;
+      }
+      const category = this.getTokenCategory(token.tokenName);
+      return preferredCategories.includes(category);
+    }).map((token) => ({
+      ...token,
+      suggestedClass: `${variantPrefix}${match.prefix}-${token.tokenName}`
+    })).sort((a, b) => {
+      const aCategory = this.getTokenCategory(a.tokenName);
+      const bCategory = this.getTokenCategory(b.tokenName);
+      const aIndex = preferredCategories.indexOf(aCategory);
+      const bIndex = preferredCategories.indexOf(bCategory);
+      if (aIndex !== bIndex) {
+        return aIndex - bIndex;
+      }
+      return a.tokenName.localeCompare(b.tokenName);
+    });
+    return suggestions;
+  }
+  /**
+   * Get the category of a token (first part of the name).
+   */
+  getTokenCategory(tokenName) {
+    const parts = tokenName.split("-");
+    return parts[0];
+  }
+  /**
+   * Get all available tokens.
+   */
+  getAllTokens() {
+    return Object.keys(this.tokenDefinitions.colors);
+  }
+}
+function createTokenMapper() {
+  const tokenDefinitions = loadTokenDefinitions();
+  return new TokenMapper(tokenDefinitions);
+}
+const VERSION = "1.0.0";
+function parseArgs(args) {
+  const defaults = getDefaultScanOptions();
+  const options = {
+    path: ".",
+    extensions: defaults.extensions,
+    ignore: defaults.ignore,
+    json: false,
+    help: false,
+    version: false
+  };
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    switch (arg) {
+      case "-h":
+      case "--help":
+        options.help = true;
+        break;
+      case "-v":
+      case "--version":
+        options.version = true;
+        break;
+      case "--json":
+        options.json = true;
+        break;
+      case "-p":
+      case "--path":
+        i++;
+        if (i < args.length) {
+          options.path = args[i];
+        }
+        break;
+      case "-e":
+      case "--extensions":
+        i++;
+        if (i < args.length) {
+          options.extensions = args[i].split(",").map((e) => e.trim());
+        }
+        break;
+      case "-i":
+      case "--ignore":
+        i++;
+        if (i < args.length) {
+          options.ignore = args[i].split(",").map((p) => p.trim());
+        }
+        break;
+      default:
+        if (!arg.startsWith("-")) {
+          options.path = arg;
+        }
+        break;
+    }
+    i++;
+  }
+  return options;
+}
+function printHelp() {
+  console.log(`
+ui-doctor v${VERSION}
+
+A CLI tool to detect raw Tailwind CSS color classes and suggest
+semantic design tokens from @versini/ui-styles.
+
+Usage:
+  ui-doctor [path] [options]
+
+Arguments:
+  path                      Path to scan (default: current directory)
+
+Options:
+  -p, --path <path>         Path to scan (alternative to positional argument)
+  -e, --extensions <ext>    Comma-separated file extensions (default: js,jsx,ts,tsx)
+  -i, --ignore <patterns>   Comma-separated patterns to ignore
+                            (default: node_modules,dist,build,.git)
+  --json                    Output in JSON format for CI/CD integration
+  -h, --help                Show this help message
+  -v, --version             Show version number
+
+Examples:
+  ui-doctor                 Scan current directory
+  ui-doctor ./src           Scan the src directory
+  ui-doctor -e tsx,ts       Only scan TypeScript files
+  ui-doctor --json          Output results as JSON
+  ui-doctor ./src --json    Scan src and output as JSON
+`);
+}
+function printVersion() {
+  console.log(`ui-doctor v${VERSION}`);
+}
+function main() {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+  if (options.help) {
+    printHelp();
+    process.exit(0);
+  }
+  if (options.version) {
+    printVersion();
+    process.exit(0);
+  }
+  const startTime = Date.now();
+  let files;
+  try {
+    files = scanFiles(options.path, {
+      extensions: options.extensions,
+      ignore: options.ignore
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+  const tokenMapper = createTokenMapper();
+  const filesWithViolations = [];
+  let totalViolations = 0;
+  for (const file of files) {
+    const matches = findColorClasses(file.content);
+    if (matches.length > 0) {
+      const violations = matches.map((match) => ({
+        match,
+        suggestions: tokenMapper.getSuggestions(match)
+      }));
+      filesWithViolations.push({
+        filePath: file.relativePath,
+        violations
+      });
+      totalViolations += violations.length;
+    }
+  }
+  const duration = Date.now() - startTime;
+  const report = {
+    filesScanned: files.length,
+    totalViolations,
+    filesWithViolations,
+    duration
+  };
+  printReport(report, options.json);
+  if (totalViolations > 0) {
+    process.exit(1);
+  }
+}
+main();

package/dist/index.js

@@ -1,12 +1,12 @@
 /*!
-  @versini/ui-styles v8.0.1
+  @versini/ui-styles v8.1.1
   © 2025 gizmette.com
 */
 try {
   if (!window.__VERSINI_UI_STYLES__) {
     window.__VERSINI_UI_STYLES__ = {
-      version: "8.0.1",
-      buildTime: "12/15/2025 07:43 PM EST",
+      version: "8.1.1",
+      buildTime: "12/21/2025 04:51 PM EST",
       homepage: "https://www.npmjs.com/package/@versini/ui-styles",
       license: "MIT",
     };
@@ -109,6 +109,7 @@ import colors from "tailwindcss/colors";
     "@versini/ui-button",
     "@versini/ui-card",
     "@versini/ui-debug-overlay",
+    "@versini/ui-dialog",
     "@versini/ui-dropdown",
     "@versini/ui-fingerprint",
     "@versini/ui-footer",
@@ -117,6 +118,7 @@ import colors from "tailwindcss/colors";
     "@versini/ui-icons",
     "@versini/ui-liveregion",
     "@versini/ui-main",
+    "@versini/ui-modal",
     "@versini/ui-panel",
     "@versini/ui-pill",
     "@versini/ui-spinner",
@@ -129,7 +131,8 @@ import colors from "tailwindcss/colors";
     "@versini/ui-togglegroup",
     "@versini/ui-tooltip",
     "@versini/ui-truncate",
-    "@versini/ui-types"
+    "@versini/ui-types",
+    "@versini/ui-utilities"
 ];
 
 ;// CONCATENATED MODULE: external "culori"
@@ -144,6 +147,9 @@ const accentColor = colors.violet["300"];
     colors: {
         /**
 		 * Action tokens.
+		 * To be used for background color for interactive elements
+		 * like buttons, links, etc.
+		 * @example bg-action-dark, hover:bg-action-dark-hover
 		 */ "action-dark": colors.slate["600"],
         "action-dark-hover": colors.slate["700"],
         "action-dark-active": colors.slate["800"],
@@ -161,6 +167,8 @@ const accentColor = colors.violet["300"];
         "action-selected-dark-active": colors.green["500"],
         /**
 		 * Surface tokens.
+		 * To be used for background colors of containers, cards, modals, etc.
+		 * @example bg-surface-medium
 		 */ "surface-darker": colors.slate["900"],
         "surface-dark": colors.slate["700"],
         "surface-medium": colors.slate["500"],
@@ -174,6 +182,8 @@ const accentColor = colors.violet["300"];
         "surface-error": colors.red["200"],
         /**
 		 * Typography tokens.
+		 * To be used for text colors.
+		 * @example text-copy-light, hover:text-copy-light-hover
 		 */ "copy-dark": colors.slate["900"],
         "copy-dark-hover": colors.slate["900"],
         "copy-dark-active": colors.slate["900"],
@@ -186,16 +196,19 @@ const accentColor = colors.violet["300"];
         "copy-lighter": colors.white,
         "copy-lighter-hover": colors.white,
         "copy-lighter-active": colors.white,
+        "copy-error": colors.red["800"],
         "copy-error-dark": colors.red["700"],
         "copy-error-light": colors.red["500"],
-        "copy-information": colors.violet["800"],
         "copy-success": colors.green["800"],
+        "copy-success-light": colors.green["500"],
+        "copy-information": colors.violet["800"],
         "copy-warning": colors.orange["800"],
-        "copy-error": colors.red["800"],
         "copy-accent": "#a9b9ad",
         "copy-accent-dark": "#cde8d4",
         /**
 		 * Border tokens.
+		 * To be used for border colors.
+		 * @example border-border-medium
 		 */ "border-dark": colors.slate["900"],
         "border-medium": colors.slate["400"],
         "border-light": colors.slate["300"],
@@ -215,12 +228,16 @@ const accentColor = colors.violet["300"];
         "border-error": colors.red["400"],
         /**
 		 * Focus tokens.
+		 * To be used for focus outlines and rings.
+		 * @example outline-focus-dark, focus:ring-focus-dark
 		 */ "focus-dark": colors.slate["400"],
         "focus-light": colors.slate["400"],
         "focus-error-dark": colors.red["700"],
         "focus-error-light": errorColorLight,
         /**
 		 * Table tokens
+		 * To be used for table row and header backgrounds.
+		 * @example bg-table-dark-odd
 		 */ "table-head-dark": colors.gray["950"],
         "table-dark": colors.gray["700"],
         "table-dark-odd": colors.gray["800"],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@versini/ui-styles",
-	"version": "8.0.1",
+	"version": "8.1.1",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
@@ -14,16 +14,20 @@
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
+	"bin": {
+		"ui-doctor": "dist/cli/ui-doctor.js"
+	},
 	"files": [
 		"dist",
 		"README.md"
 	],
 	"scripts": {
 		"build:check": "tsc",
+		"build:cli": "vite build --config vite.cli.config.ts",
 		"build:js": "rslib build",
 		"build:types": "echo 'Types now built with rslib'",
 		"build:list": "node lib/buildComponentsList.js",
-		"build": "npm-run-all --serial clean build:list build:check build:js",
+		"build": "npm-run-all --serial clean build:list build:check build:js build:cli",
 		"clean": "rimraf dist tmp",
 		"dev:js": "rslib build --watch",
 		"dev:types": "echo 'Types now watched with rslib'",
@@ -39,8 +43,11 @@
 		"@tailwindcss/container-queries": "0.1.1",
 		"@tailwindcss/typography": "0.5.19",
 		"culori": "4.0.2",
-		"fs-extra": "11.3.2",
+		"fs-extra": "11.3.3",
 		"tailwindcss": "4.1.18"
 	},
-	"gitHead": "699b13029f1d14089c1875bc50f049c1c7b9859a"
+	"devDependencies": {
+		"rollup-plugin-copy": "3.5.0"
+	},
+	"gitHead": "72dae70f6fb65a797e1abbca1afd471af34b804e"
 }