124 lines
4 KiB
Markdown
124 lines
4 KiB
Markdown
|
# 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)`
|