omgkit 2.29.0 → 2.31.0

package/lib/theme.js

@@ -9,6 +9,15 @@ import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync } from
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
+// V2 imports (lazy-loaded to avoid circular deps)
+let themeV2Module = null;
+async function getThemeV2Module() {
+  if (!themeV2Module) {
+    themeV2Module = await import('./theme-v2.js');
+  }
+  return themeV2Module;
+}
+
 // Package root detection
 let PACKAGE_ROOT;
 
@@ -89,6 +98,57 @@ export const OPTIONAL_COLORS = [
   'sidebar-border', 'sidebar-ring'
 ];
 
+/**
+ * V2 extended tokens (new in v2 schema)
+ */
+export const V2_EXTENDED_TOKENS = [
+  'surface', 'surface-hover', 'surface-active',
+  'primary-hover', 'secondary-hover', 'accent-hover',
+  'border-hover', 'input-hover',
+  'ring-offset', 'panel', 'panel-translucent', 'overlay'
+];
+
+/**
+ * V2 status colors
+ */
+export const V2_STATUS_COLORS = [
+  'success', 'success-foreground',
+  'warning', 'warning-foreground',
+  'info', 'info-foreground'
+];
+
+/**
+ * Detect theme schema version
+ * @param {Object} theme - Theme object
+ * @returns {'1.0' | '2.0'} Theme version
+ */
+export function detectThemeVersion(theme) {
+  if (!theme) return '1.0';
+
+  // Explicit version check
+  if (theme.version === '2.0' || theme.version === 2) return '2.0';
+
+  // V2 indicators (any of these marks it as v2)
+  if (theme.scales) return '2.0';
+  if (theme.semanticTokens) return '2.0';
+  if (theme.effects) return '2.0';
+  if (theme.animations) return '2.0';
+  if (theme.colorSystem) return '2.0';
+  if (theme.statusColors) return '2.0';
+
+  // Default to v1
+  return '1.0';
+}
+
+/**
+ * Check if theme is v2 format
+ * @param {Object} theme - Theme object
+ * @returns {boolean} True if v2 theme
+ */
+export function isV2Theme(theme) {
+  return detectThemeVersion(theme) === '2.0';
+}
+
 /**
  * Load all available themes from templates/design/themes
  * @returns {Object} Themes grouped by category
@@ -203,11 +263,13 @@ export function validateTheme(theme) {
 }
 
 /**
- * Generate CSS variables from theme
+ * Generate CSS variables from theme (sync version, v1 only)
  * @param {Object} theme - Theme object
  * @returns {string} CSS content with variables
  */
 export function generateThemeCSS(theme) {
+  // Check if v2 theme - if so, use simple generation for compatibility
+  // For full v2 features, use generateThemeCSSAsync or processTheme from theme-v2.js
   const generateColorVars = (colors) => {
     let css = '';
     for (const [key, value] of Object.entries(colors)) {
@@ -216,17 +278,24 @@ export function generateThemeCSS(theme) {
     return css;
   };
 
-  const lightVars = generateColorVars(theme.colors.light);
-  const darkVars = generateColorVars(theme.colors.dark);
+  // Handle v2 themes with semanticTokens
+  const lightColors = theme.colors?.light || theme.semanticTokens?.light || {};
+  const darkColors = theme.colors?.dark || theme.semanticTokens?.dark || {};
+
+  const lightVars = generateColorVars(lightColors);
+  const darkVars = generateColorVars(darkColors);
+
+  const version = isV2Theme(theme) ? '2.0' : '1.0';
 
   return `/* OMGKIT Theme: ${theme.name} */
 /* Theme ID: ${theme.id} */
 /* Category: ${theme.category} */
+/* Version: ${version} */
 /* Generated by OMGKIT Design System */
 
 @layer base {
   :root {
-${lightVars}  --radius: ${theme.radius || '0.5rem'};
+${lightVars}  --radius: ${theme.spacing?.radius || theme.radius || '0.5rem'};
   }
 
   .dark {
@@ -244,6 +313,30 @@ ${darkVars}  }
 `;
 }
 
+/**
+ * Generate CSS variables from theme (async version, full v2 support)
+ * @param {Object} theme - Theme object (v1 or v2)
+ * @returns {Promise<string>} CSS content with all v2 features
+ */
+export async function generateThemeCSSAsync(theme) {
+  if (isV2Theme(theme)) {
+    const v2 = await getThemeV2Module();
+    return v2.generateV2ThemeCSS(theme);
+  }
+  return generateThemeCSS(theme);
+}
+
+/**
+ * Process theme with unified processor (async)
+ * @param {Object} theme - Theme object (v1 or v2)
+ * @param {Object} options - Processing options
+ * @returns {Promise<Object>} Processed theme result
+ */
+export async function processThemeUnified(theme, options = {}) {
+  const v2 = await getThemeV2Module();
+  return v2.processTheme(theme, options);
+}
+
 /**
  * Generate components.json for shadcn
  * @param {Object} theme - Theme object
@@ -569,3 +662,652 @@ export function hslToHex(hsl) {
 
   return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase();
 }
+
+// ============================================================================
+// THEME REBUILD & ROLLBACK FUNCTIONS
+// ============================================================================
+
+/**
+ * Directories to scan for color references (standard React/Next.js paths)
+ */
+export const SCAN_DIRECTORIES = ['app', 'components', 'src', 'pages'];
+
+/**
+ * File extensions to scan
+ */
+export const SCAN_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js'];
+
+/**
+ * Directories to always exclude from scanning
+ */
+export const EXCLUDE_DIRS = ['node_modules', '.git', '.omgkit', 'dist', 'build', '.next', 'out'];
+
+/**
+ * Color patterns to detect non-compliant colors
+ */
+export const COLOR_PATTERNS = {
+  // Tailwind default colors (should use theme vars)
+  tailwindDefaults: /\b(bg|text|border|ring|fill|stroke|outline|divide|from|via|to|shadow|decoration)-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|white|black)-(\d{2,3})\b/g,
+
+  // Hardcoded hex colors in className or style
+  hexColors: /#([0-9A-Fa-f]{3}){1,2}\b/g,
+
+  // Hardcoded RGB/HSL in styles
+  rgbHsl: /\b(rgb|hsl)a?\([^)]+\)/g
+};
+
+/**
+ * Mapping of hardcoded Tailwind colors to theme variables
+ */
+export const THEME_VAR_MAP = {
+  // Background mappings
+  'bg-white': 'bg-background',
+  'bg-gray-50': 'bg-muted',
+  'bg-gray-100': 'bg-muted',
+  'bg-gray-200': 'bg-muted',
+  'bg-gray-900': 'bg-foreground',
+  'bg-slate-50': 'bg-muted',
+  'bg-slate-100': 'bg-muted',
+  'bg-slate-900': 'bg-foreground',
+  'bg-zinc-50': 'bg-muted',
+  'bg-zinc-100': 'bg-muted',
+  'bg-zinc-900': 'bg-foreground',
+
+  // Text mappings
+  'text-black': 'text-foreground',
+  'text-white': 'text-background',
+  'text-gray-900': 'text-foreground',
+  'text-gray-800': 'text-foreground',
+  'text-gray-700': 'text-foreground',
+  'text-gray-600': 'text-muted-foreground',
+  'text-gray-500': 'text-muted-foreground',
+  'text-gray-400': 'text-muted-foreground',
+  'text-slate-900': 'text-foreground',
+  'text-slate-600': 'text-muted-foreground',
+  'text-slate-500': 'text-muted-foreground',
+  'text-zinc-900': 'text-foreground',
+  'text-zinc-600': 'text-muted-foreground',
+  'text-zinc-500': 'text-muted-foreground',
+
+  // Border mappings
+  'border-gray-100': 'border-border',
+  'border-gray-200': 'border-border',
+  'border-gray-300': 'border-input',
+  'border-slate-200': 'border-border',
+  'border-slate-300': 'border-input',
+  'border-zinc-200': 'border-border',
+  'border-zinc-300': 'border-input',
+
+  // Primary/accent colors (common patterns)
+  'bg-blue-500': 'bg-primary',
+  'bg-blue-600': 'bg-primary',
+  'bg-blue-700': 'bg-primary',
+  'text-blue-500': 'text-primary',
+  'text-blue-600': 'text-primary',
+  'text-blue-700': 'text-primary',
+  'ring-blue-500': 'ring-ring',
+  'ring-blue-600': 'ring-ring',
+
+  // Destructive
+  'bg-red-500': 'bg-destructive',
+  'bg-red-600': 'bg-destructive',
+  'text-red-500': 'text-destructive',
+  'text-red-600': 'text-destructive',
+  'border-red-500': 'border-destructive',
+
+  // Secondary/accent patterns
+  'bg-gray-100': 'bg-secondary',
+  'bg-slate-100': 'bg-secondary',
+  'hover:bg-gray-100': 'hover:bg-accent',
+  'hover:bg-slate-100': 'hover:bg-accent'
+};
+
+/**
+ * Recursively get all files in a directory
+ * @param {string} dir - Directory to scan
+ * @param {string[]} extensions - File extensions to include
+ * @param {string[]} excludeDirs - Directories to exclude
+ * @returns {string[]} Array of file paths
+ */
+function getFilesRecursive(dir, extensions, excludeDirs) {
+  const files = [];
+  if (!existsSync(dir)) return files;
+
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!excludeDirs.includes(entry.name)) {
+        files.push(...getFilesRecursive(fullPath, extensions, excludeDirs));
+      }
+    } else if (entry.isFile()) {
+      const ext = '.' + entry.name.split('.').pop();
+      if (extensions.includes(ext)) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Scan project for files with non-compliant color references
+ * @param {string} projectDir - Project root directory
+ * @returns {Object} { files: [], totalReferences: number, nonCompliant: [], compliant: number }
+ */
+export function scanProjectColors(projectDir) {
+  const result = {
+    files: [],
+    totalReferences: 0,
+    nonCompliant: [],
+    compliant: 0,
+    scannedFiles: 0
+  };
+
+  // Find all files to scan
+  const filesToScan = [];
+  for (const scanDir of SCAN_DIRECTORIES) {
+    const fullPath = join(projectDir, scanDir);
+    if (existsSync(fullPath)) {
+      filesToScan.push(...getFilesRecursive(fullPath, SCAN_EXTENSIONS, EXCLUDE_DIRS));
+    }
+  }
+
+  result.scannedFiles = filesToScan.length;
+
+  // Scan each file
+  for (const filePath of filesToScan) {
+    try {
+      const content = readFileSync(filePath, 'utf8');
+      const lines = content.split('\n');
+      const relativePath = filePath.replace(projectDir + '/', '');
+      const fileMatches = [];
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+
+        // Check for Tailwind default colors
+        let match;
+        const pattern = new RegExp(COLOR_PATTERNS.tailwindDefaults.source, 'g');
+        while ((match = pattern.exec(line)) !== null) {
+          result.totalReferences++;
+          const fullMatch = match[0];
+
+          // Check if this has a theme-compliant mapping
+          const mapping = THEME_VAR_MAP[fullMatch];
+          if (mapping) {
+            fileMatches.push({
+              file: relativePath,
+              line: lineNum,
+              column: match.index,
+              match: fullMatch,
+              suggestion: mapping,
+              type: 'tailwind-default',
+              fixable: true
+            });
+            result.nonCompliant.push({
+              file: relativePath,
+              line: lineNum,
+              match: fullMatch,
+              suggestion: mapping
+            });
+          } else {
+            // Unmapped color - warn only
+            fileMatches.push({
+              file: relativePath,
+              line: lineNum,
+              column: match.index,
+              match: fullMatch,
+              suggestion: null,
+              type: 'unmapped',
+              fixable: false
+            });
+            result.nonCompliant.push({
+              file: relativePath,
+              line: lineNum,
+              match: fullMatch,
+              suggestion: null
+            });
+          }
+        }
+
+        // Check for hex colors in className or style attributes
+        const hexPattern = new RegExp(COLOR_PATTERNS.hexColors.source, 'g');
+        while ((match = hexPattern.exec(line)) !== null) {
+          // Only flag if it appears to be in className or style context
+          const before = line.slice(0, match.index);
+          if (before.includes('className') || before.includes('style') || before.includes('bg-[') || before.includes('text-[')) {
+            result.totalReferences++;
+            fileMatches.push({
+              file: relativePath,
+              line: lineNum,
+              column: match.index,
+              match: match[0],
+              suggestion: 'Use CSS variable (e.g., bg-background)',
+              type: 'hex-color',
+              fixable: false
+            });
+            result.nonCompliant.push({
+              file: relativePath,
+              line: lineNum,
+              match: match[0],
+              suggestion: 'Use CSS variable'
+            });
+          }
+        }
+      }
+
+      if (fileMatches.length > 0) {
+        result.files.push({
+          path: relativePath,
+          matches: fileMatches
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be read
+    }
+  }
+
+  result.compliant = result.totalReferences - result.nonCompliant.length;
+
+  return result;
+}
+
+/**
+ * Create a theme backup before rebuild
+ * @param {string} projectDir - Project root directory
+ * @param {string} newThemeId - ID of new theme being applied
+ * @returns {Object} { success, backupId, backupPath, error }
+ */
+export function createThemeBackup(projectDir, newThemeId = 'unknown') {
+  const designDir = join(projectDir, '.omgkit', 'design');
+  const backupsDir = join(designDir, 'backups');
+
+  // Create backups directory
+  mkdirSync(backupsDir, { recursive: true });
+
+  // Generate backup ID
+  const now = new Date();
+  const timestamp = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const backupId = `${timestamp}-${newThemeId}`;
+  const backupPath = join(backupsDir, backupId);
+
+  try {
+    mkdirSync(backupPath, { recursive: true });
+
+    // Get current theme
+    const currentTheme = getProjectTheme(projectDir);
+    const previousThemeId = currentTheme?.id || 'none';
+
+    // Create manifest
+    const manifest = {
+      id: backupId,
+      previousTheme: previousThemeId,
+      newTheme: newThemeId,
+      timestamp: now.toISOString(),
+      changedFiles: []
+    };
+
+    // Backup theme.json if exists
+    const themeJsonPath = join(designDir, 'theme.json');
+    if (existsSync(themeJsonPath)) {
+      const content = readFileSync(themeJsonPath, 'utf8');
+      writeFileSync(join(backupPath, 'theme.json.bak'), content);
+      manifest.changedFiles.push({ path: '.omgkit/design/theme.json', backup: 'theme.json.bak' });
+    }
+
+    // Backup theme.css if exists
+    const themeCssPath = join(designDir, 'theme.css');
+    if (existsSync(themeCssPath)) {
+      const content = readFileSync(themeCssPath, 'utf8');
+      writeFileSync(join(backupPath, 'theme.css.bak'), content);
+      manifest.changedFiles.push({ path: '.omgkit/design/theme.css', backup: 'theme.css.bak' });
+    }
+
+    // Backup tailwind.config.ts if exists
+    const tailwindConfigPath = join(projectDir, 'tailwind.config.ts');
+    if (existsSync(tailwindConfigPath)) {
+      const content = readFileSync(tailwindConfigPath, 'utf8');
+      writeFileSync(join(backupPath, 'tailwind.config.ts.bak'), content);
+      manifest.changedFiles.push({ path: 'tailwind.config.ts', backup: 'tailwind.config.ts.bak' });
+    }
+
+    // Also check for .js version
+    const tailwindConfigJsPath = join(projectDir, 'tailwind.config.js');
+    if (existsSync(tailwindConfigJsPath)) {
+      const content = readFileSync(tailwindConfigJsPath, 'utf8');
+      writeFileSync(join(backupPath, 'tailwind.config.js.bak'), content);
+      manifest.changedFiles.push({ path: 'tailwind.config.js', backup: 'tailwind.config.js.bak' });
+    }
+
+    // Write manifest
+    writeFileSync(join(backupPath, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+    return { success: true, backupId, backupPath, manifest };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * List available theme backups
+ * @param {string} projectDir - Project root directory
+ * @returns {Array} Array of backup info objects
+ */
+export function listThemeBackups(projectDir) {
+  const backupsDir = join(projectDir, '.omgkit', 'design', 'backups');
+  if (!existsSync(backupsDir)) return [];
+
+  const backups = [];
+  const entries = readdirSync(backupsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const manifestPath = join(backupsDir, entry.name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      backups.push({
+        id: manifest.id,
+        previousTheme: manifest.previousTheme,
+        newTheme: manifest.newTheme,
+        timestamp: manifest.timestamp,
+        date: new Date(manifest.timestamp).toLocaleString(),
+        filesChanged: manifest.changedFiles.length,
+        path: join(backupsDir, entry.name)
+      });
+    } catch {
+      // Skip invalid backup
+    }
+  }
+
+  // Sort by timestamp descending (newest first)
+  return backups.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+}
+
+/**
+ * Rollback to a previous theme state
+ * @param {string} projectDir - Project root directory
+ * @param {string} backupId - Backup ID to restore (optional, defaults to latest)
+ * @returns {Object} { success, restoredTheme, restoredFiles, error }
+ */
+export function rollbackTheme(projectDir, backupId = null) {
+  const backups = listThemeBackups(projectDir);
+
+  if (backups.length === 0) {
+    return { success: false, error: 'No theme backups found' };
+  }
+
+  // Find backup to restore
+  let backup;
+  if (backupId) {
+    backup = backups.find(b => b.id === backupId);
+    if (!backup) {
+      return { success: false, error: `Backup not found: ${backupId}` };
+    }
+  } else {
+    backup = backups[0]; // Latest
+  }
+
+  try {
+    const manifestPath = join(backup.path, 'manifest.json');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const restoredFiles = [];
+
+    // Create a new backup before rollback (safety)
+    createThemeBackup(projectDir, `rollback-from-${manifest.newTheme}`);
+
+    // Restore each file
+    for (const file of manifest.changedFiles) {
+      const backupFilePath = join(backup.path, file.backup);
+      const targetPath = join(projectDir, file.path);
+
+      if (existsSync(backupFilePath)) {
+        const content = readFileSync(backupFilePath, 'utf8');
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, content);
+        restoredFiles.push(file.path);
+      }
+    }
+
+    return {
+      success: true,
+      restoredTheme: manifest.previousTheme,
+      restoredFiles,
+      backupUsed: backup.id
+    };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * Update file replacing hardcoded colors with theme variables
+ * @param {string} filePath - File to update
+ * @param {string} projectDir - Project root directory
+ * @returns {Object} { changed, replacements, content }
+ */
+export function updateFileColors(filePath, projectDir) {
+  const fullPath = join(projectDir, filePath);
+  if (!existsSync(fullPath)) {
+    return { changed: false, replacements: [], error: 'File not found' };
+  }
+
+  let content = readFileSync(fullPath, 'utf8');
+  const replacements = [];
+  let changed = false;
+
+  // Apply theme variable mappings
+  for (const [pattern, replacement] of Object.entries(THEME_VAR_MAP)) {
+    // Escape special regex characters in pattern
+    const escapedPattern = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`\\b${escapedPattern}\\b`, 'g');
+
+    const matches = content.match(regex);
+    if (matches && matches.length > 0) {
+      content = content.replace(regex, replacement);
+      replacements.push({
+        from: pattern,
+        to: replacement,
+        count: matches.length
+      });
+      changed = true;
+    }
+  }
+
+  return { changed, replacements, content };
+}
+
+/**
+ * Update project's tailwind.config file with new theme
+ * @param {Object} theme - Theme object
+ * @param {string} projectDir - Project root directory
+ * @returns {Object} { success, path, error }
+ */
+export function updateProjectTailwindConfig(theme, projectDir) {
+  // Check for tailwind.config.ts first, then .js
+  let configPath = join(projectDir, 'tailwind.config.ts');
+  let isTs = true;
+
+  if (!existsSync(configPath)) {
+    configPath = join(projectDir, 'tailwind.config.js');
+    isTs = false;
+    if (!existsSync(configPath)) {
+      // Create new config
+      configPath = join(projectDir, 'tailwind.config.ts');
+      isTs = true;
+    }
+  }
+
+  try {
+    const newConfig = generateTailwindConfig(theme);
+    writeFileSync(configPath, newConfig);
+    return { success: true, path: configPath, isTs };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * Ensure globals.css imports theme.css
+ * @param {string} projectDir - Project root directory
+ * @returns {Object} { updated, path, alreadyImported }
+ */
+export function ensureThemeImport(projectDir) {
+  // Look for globals.css in common locations
+  const possiblePaths = [
+    join(projectDir, 'app', 'globals.css'),
+    join(projectDir, 'src', 'app', 'globals.css'),
+    join(projectDir, 'styles', 'globals.css'),
+    join(projectDir, 'src', 'styles', 'globals.css')
+  ];
+
+  let globalsPath = null;
+  for (const p of possiblePaths) {
+    if (existsSync(p)) {
+      globalsPath = p;
+      break;
+    }
+  }
+
+  if (!globalsPath) {
+    return { updated: false, path: null, error: 'globals.css not found' };
+  }
+
+  let content = readFileSync(globalsPath, 'utf8');
+  const themeImport = "@import '../.omgkit/design/theme.css';";
+  const altThemeImport = "@import '../../.omgkit/design/theme.css';";
+
+  // Check if already imported
+  if (content.includes('.omgkit/design/theme.css')) {
+    return { updated: false, path: globalsPath, alreadyImported: true };
+  }
+
+  // Add import at the beginning
+  const relativePath = globalsPath.includes('/src/') ? altThemeImport : themeImport;
+  content = `${relativePath}\n${content}`;
+
+  writeFileSync(globalsPath, content);
+  return { updated: true, path: globalsPath, alreadyImported: false };
+}
+
+/**
+ * Rebuild entire project with a new theme
+ * @param {string} projectDir - Project root directory
+ * @param {string} themeId - New theme ID
+ * @param {Object} options - { dryRun, force, fixColors }
+ * @returns {Object} { success, backupPath, changedFiles, warnings, error }
+ */
+export function rebuildProjectTheme(projectDir, themeId, options = {}) {
+  const { dryRun = false, force = false, fixColors = true } = options;
+
+  // Validate project has .omgkit
+  if (!existsSync(join(projectDir, '.omgkit'))) {
+    return { success: false, error: 'Not an OMGKIT project. Run: omgkit init' };
+  }
+
+  // Get new theme
+  const newTheme = getThemeById(themeId);
+  if (!newTheme) {
+    return { success: false, error: `Theme not found: ${themeId}. Run /design:themes to see available themes.` };
+  }
+
+  // Validate theme
+  const validation = validateTheme(newTheme);
+  if (!validation.valid) {
+    return { success: false, error: `Invalid theme: ${validation.errors.join(', ')}` };
+  }
+
+  const result = {
+    success: true,
+    newTheme: themeId,
+    backupId: null,
+    backupPath: null,
+    changedFiles: [],
+    fixedColors: [],
+    warnings: [],
+    dryRun
+  };
+
+  // Step 1: Create backup (unless dry-run)
+  if (!dryRun) {
+    const backup = createThemeBackup(projectDir, themeId);
+    if (!backup.success) {
+      return { success: false, error: `Failed to create backup: ${backup.error}` };
+    }
+    result.backupId = backup.backupId;
+    result.backupPath = backup.backupPath;
+  }
+
+  // Step 2: Apply new theme
+  if (!dryRun) {
+    const applied = applyThemeToProject(newTheme, projectDir);
+    result.changedFiles.push(applied.themeJson.replace(projectDir + '/', ''));
+    result.changedFiles.push(applied.themeCss.replace(projectDir + '/', ''));
+  } else {
+    result.changedFiles.push('.omgkit/design/theme.json');
+    result.changedFiles.push('.omgkit/design/theme.css');
+  }
+
+  // Step 3: Update tailwind config
+  if (!dryRun) {
+    const tailwindResult = updateProjectTailwindConfig(newTheme, projectDir);
+    if (tailwindResult.success) {
+      result.changedFiles.push(tailwindResult.path.replace(projectDir + '/', ''));
+    }
+  } else {
+    result.changedFiles.push('tailwind.config.ts');
+  }
+
+  // Step 4: Ensure theme import in globals.css
+  if (!dryRun) {
+    const importResult = ensureThemeImport(projectDir);
+    if (importResult.updated) {
+      result.changedFiles.push(importResult.path.replace(projectDir + '/', ''));
+    }
+  }
+
+  // Step 5: Scan and fix colors (if enabled)
+  if (fixColors) {
+    const scanResult = scanProjectColors(projectDir);
+
+    for (const fileInfo of scanResult.files) {
+      const fixableMatches = fileInfo.matches.filter(m => m.fixable);
+
+      if (fixableMatches.length > 0) {
+        if (!dryRun) {
+          const updateResult = updateFileColors(fileInfo.path, projectDir);
+          if (updateResult.changed) {
+            // Write updated content
+            writeFileSync(join(projectDir, fileInfo.path), updateResult.content);
+            result.changedFiles.push(fileInfo.path);
+            result.fixedColors.push({
+              file: fileInfo.path,
+              replacements: updateResult.replacements
+            });
+          }
+        } else {
+          // Dry run - just report what would be changed
+          result.fixedColors.push({
+            file: fileInfo.path,
+            replacements: fixableMatches.map(m => ({ from: m.match, to: m.suggestion }))
+          });
+        }
+      }
+
+      // Add warnings for unfixable colors
+      const unfixable = fileInfo.matches.filter(m => !m.fixable);
+      for (const u of unfixable) {
+        result.warnings.push(`${u.file}:${u.line} - ${u.match} (manual review needed)`);
+      }
+    }
+  }
+
+  return result;
+}