Tailwind Default Migration Phase 2 Implementation Plan

Execution note: Use executing-plans to implement this plan task-by-task.

Goal: Finish migrating remaining raw token utility classes toward default Tailwind classes without breaking theme behavior or brand intent.

Architecture: Keep docs/**/*.html and assets/js/**/*.js as source-safe text targets. Continue using the exact-only auto lane for deterministic mappings, and use explicit review lanes for theme-dependent neutrals, brand colors, and alpha overlays. Never auto-apply approximate mappings until the lane policy is approved.

Tech Stack: Node.js scripts, Tailwind v4 runtime bundle, DOL DS token subset, palette remap CSS.

---

Task 1: Keep the migration report as the single source of truth

Files:

• Modify: tools/tailwind-default-migration-core.mjs
• Modify: tools/report-tailwind-default-migration.mjs
• Verify: reports/styling/tailwind-default-migration.json
• Verify: reports/styling/tailwind-default-migration.md

Step 1: Refresh the migration inventory

Run: npm run styles:migrate:tailwind:report

Expected:

• exact = 0
• approx = 33
• unresolved = 15
• lane summary is present in markdown/json

Step 2: Confirm lane distribution

Current lanes:

• theme-neutral-review: 16 utilities, 231 occurrences
• alpha-manual: 15 utilities, 56 occurrences
• extended-family-review: 15 utilities, 27 occurrences
• external-brand-review: 2 utilities, 7 occurrences

Step 3: Reject unsafe auto-apply

Hard rule:

• do not run apply for any lane unless the report shows confidence = exact

---

Task 2: Decide the neutral lane policy before touching source

Files:

• Review: reports/styling/tailwind-default-migration.md
• Potential future modify: tools/tailwind-default-migration-core.mjs

Step 1: Review the neutral lane

Representative utilities:

• bg-(--neutral-n00) -> bg-white
• bg-(--bg-color-ele-neutral-primary) -> bg-white
• bg-(--bg-color-body-neutral-subtle) -> bg-slate-50

Step 2: Pick one policy and keep it consistent

Recommended policy:

• keep this lane manual for now

Reason:

• these tokens are theme-dependent in DOL
• auto-converting to white or slate-50 is visually plausible in light mode but changes dark-mode semantics

Step 3: Only after approval, implement one of two strategies

Option A:

• keep the remaining neutral token utilities as-is

Option B:

• add a curated approximation manifest for approved light-first mappings
• apply only the approved tokens, not the whole lane

---

Task 3: Use the approved brand manifest as the reference pattern

Files:

• Review: reports/styling/tailwind-default-migration.md
• Review: tools/tailwind-default-migration-manifest.mjs
• Potential future modify: tools/tailwind-default-migration-core.mjs

Step 1: Treat brand-primary as the completed baseline

Current state:

• approved mappings live in tools/tailwind-default-migration-manifest.mjs
• the former brand-primary-review lane has been migrated out of source
• this manifest is now the pattern for future approved approximate lanes

Step 2: Reuse the same model for future lanes

Reason:

• color distance is close, but brand intent is stronger than numerical similarity

Step 3: Only add future approved approximations through the manifest

Preferred future shape:

• one manifest entry per approved token utility
• report treats them as exact-safe and keeps the approval reason/lane in metadata
• apply lane writes only approved entries

---

Task 4: Keep alpha overlays manual unless opacity mapping is explicitly designed

Files:

• Review: reports/styling/tailwind-default-migration.md
• Modify only if policy changes: tools/tailwind-default-migration-core.mjs

Step 1: Keep current unresolved behavior

Representative utilities:

• border-(--neutral-alpha-na05)
• bg-(--neutral-inverse-alpha-nia60)
• bg-(--neutral-alpha-na10)

Step 2: Do not approximate these by nearest RGB

Reason:

• alpha overlays are compositional
• nearest solid Tailwind color is misleading

Step 3: Only migrate if an opacity-safe contract exists

Acceptable future migration target:

• bg-white/60
• border-slate-900/5

Not acceptable:

• arbitrary nearest solid replacement

---

Task 5: Execute future lanes in fixed order

Files:

• Modify future batches in docs/**/*.html
• Modify future batches in assets/js/**/*.js

Step 1: Run report

Run: npm run styles:migrate:tailwind:report

Step 2: Select one lane only

Order:

1. approved exact lane
2. approved neutral lane
3. extended-family lane
4. external-brand lane
5. alpha lane last

Step 3: Apply smallest possible batch

Run pattern:

• node tools/apply-tailwind-default-migration.mjs --confidence exact --match='<lane-regex>'

Step 4: Verify after every batch

Run:

• npm run styles:gen:docs
• npm run styles:guard:all
• npm run styles:migrate:tailwind:report

Expected:

• no old exact-safe utilities remain for the executed lane
• no new guard failure

---

Task 6: Definition of Done for the full migration program

Hard gates:

• styles:guard:all passes
• migration report shows exact = 0
• no lane is auto-applied from approx or unresolved without an approved manifest/policy

Target end state:

• only intentional semantic holdouts remain
• all remaining non-default Tailwind classes are either documented exceptions or approved approximations