# Automated Tailwind Color Migration Scripts

This directory contains scripts to automatically migrate Tailwind default colors to the Kodo design system.

## Scripts

### 1. `auto_migrate_tailwind_colors.py`
Single-file migration script with verification.

**Usage:**
```bash
# Dry run (test without modifying files)
python3 scripts/auto_migrate_tailwind_colors.py --dry-run

# Migrate all files
python3 scripts/auto_migrate_tailwind_colors.py

# Migrate first 10 files only
python3 scripts/auto_migrate_tailwind_colors.py --limit 10

# Verify files only (check for remaining instances)
python3 scripts/auto_migrate_tailwind_colors.py --verify
```

### 2. `auto_migrate_tailwind_colors_batch.py` ⭐ **RECOMMENDED**
Batch migration script that processes files in batches and commits after each batch.

**Usage:**
```bash
# Dry run with batches of 10 files
python3 scripts/auto_migrate_tailwind_colors_batch.py --dry-run --batch-size 10

# Migrate all files in batches of 10 (auto-commits each batch)
python3 scripts/auto_migrate_tailwind_colors_batch.py --batch-size 10

# Migrate with smaller batches (more commits, safer)
python3 scripts/auto_migrate_tailwind_colors_batch.py --batch-size 5
```

### 3. `generate_tailwind_list.py`
Regenerates the full instance list from the codebase.

**Usage:**
```bash
python3 scripts/generate_tailwind_list.py
```

## Recommended Workflow

1. **Test with dry-run first:**
   ```bash
   python3 scripts/auto_migrate_tailwind_colors_batch.py --dry-run --batch-size 10
   ```

2. **Run migration in small batches:**
   ```bash
   # Start with 5 files per batch for safety
   python3 scripts/auto_migrate_tailwind_colors_batch.py --batch-size 5
   ```

3. **Verify after migration:**
   ```bash
   python3 scripts/auto_migrate_tailwind_colors.py --verify
   ```

4. **If issues found, regenerate list:**
   ```bash
   python3 scripts/generate_tailwind_list.py
   ```

## What the Scripts Do

1. **Read** `apps/web/docs/TAILWIND_INSTANCES_FULL_LIST.md` to find all instances
2. **Parse** each file and find Tailwind default color classes
3. **Replace** with Kodo design system colors based on mapping:
   - `text-gray-400` → `text-kodo-content-dim`
   - `bg-gray-700` → `bg-kodo-steel`
   - `border-gray-600` → `border-kodo-steel`
   - `text-blue-600` → `text-kodo-cyan`
   - etc.
4. **Verify** each file has no remaining Tailwind default colors
5. **Commit** changes in batches (batch script only)

## Color Mappings

The scripts use the following mappings (see `TAILWIND_COLORS_AUDIT.md` for full details):

- **Gray text**: `text-gray-400/500/600` → `text-kodo-content-dim`
- **Gray text (dark)**: `text-gray-300/700/800/900` → `text-kodo-text-main`
- **Gray backgrounds**: `bg-gray-*` → `bg-kodo-void/ink/graphite/slate/steel`
- **Gray borders**: `border-gray-*` → `border-kodo-steel`
- **Blue colors**: `text-blue-*` → `text-kodo-cyan`
- **Red colors**: `text-red-*` → `text-kodo-red`
- **Green colors**: `text-green-*` → `text-kodo-lime`

## Safety Features

- ✅ Dry-run mode to preview changes
- ✅ Verification after each file
- ✅ Batch processing with commits
- ✅ Detailed logging of all changes
- ✅ Error handling for file I/O issues

## Troubleshooting

**Script finds instances but doesn't migrate them:**
- Check if the color class is in the `COLOR_MAPPINGS` dictionary
- Some edge cases (conditional classes, template strings) may need manual review

**Verification fails after migration:**
- Some instances might be in comments or strings (not actual classes)
- Check the file manually and fix any remaining issues

**Git commit fails:**
- Ensure you're in the repository root
- Check git status for uncommitted changes
- The script will continue even if commit fails (you can commit manually)

## Notes

- The scripts exclude test files (`*.test.tsx`, `*.test.ts`) and backup files (`ui.backup/`)
- Dark mode classes (e.g., `dark:bg-gray-900`) are handled automatically
- The batch script commits with format: `consistency: auto-migrate Tailwind default colors (Batch N, X instances)`