veza/scripts/README_TAILWIND_MIGRATION.md

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:

# 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:

# 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:

python3 scripts/generate_tailwind_list.py

Recommended Workflow

1. Test with dry-run first:

   python3 scripts/auto_migrate_tailwind_colors_batch.py --dry-run --batch-size 10
   

2. Run migration in small batches:

   # Start with 5 files per batch for safety
   python3 scripts/auto_migrate_tailwind_colors_batch.py --batch-size 5
   

3. Verify after migration:

   python3 scripts/auto_migrate_tailwind_colors.py --verify
   

4. If issues found, regenerate list:

   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)