The brand-agnostic contract and the per-brand configurations that feed every downstream projection. This epic must lead — nothing else can land until the schema exists.
Sprint 1
Define canonical semantic contract — color roles
Schema for text.*, surface.*, border.*, action.*.background, etc. Versioned JSON schema, committed to repo.
Sprint 1
Define canonical semantic contract — typography roles
Font family, weight, size, line-height roles. Same schema file.
Sprint 1
Define canonical semantic contract — surface, border, spacing roles
Round out the contract so Sprint 2 refactors aren't blocked mid-flight.
Sprint 1
Document semantic layer ownership and change process
Who owns the schema, how changes are proposed, how versioning works.
Sprint 1
Create Brand A mapping config
Brand A values mapped to semantic roles. Hand-authored, no AI.
Sprint 1
Create Brand B mapping config
Brand B values mapped to semantic roles. Stress-test the schema — schema bugs surface here get fixed in the schema, not worked around.
Sprint 1
Define mapping provenance schema
Every mapping entry carries provenance: human-authored | ai-suggested | human-confirmed. Nothing ships at ai-suggested.
Sprint 1
Define mapping review workflow
How AI-suggested mappings move to human-confirmed. Who reviews, what the gate looks like.
Sprint 1
Validate semantic layer projects to current modern token package without drift
Generate the existing modern token package from the semantic layer. Diff against current hand-authored output. Any deltas must be explainable. This is the "we didn't break anything" gate and must pass before Sprint 2 starts.
Sprint 4
Add CI validation for semantic mapping completeness
Every required semantic role has a mapping for every brand, or the build fails.
The adapter, the CSS custom properties output, and the integration into the shared base library. This is the spine that makes legacy capable of receiving brand values at all.
Sprint 1
Inventory repeated hardcoded values across pilot legacy apps and base library
Combined investigation — feeds both the manifest (Epic 3) and the override hotspot map. Color first, then spacing/typography.
Sprint 1
Identify shared base library styling entry points
Where in the base library do styles get authored, and which downstream apps consume them.
Sprint 1
Scaffold legacy CSS variable adapter
The projection from semantic layer → flat :root { --brand-* } stylesheet.
Sprint 1
Generate initial legacy CSS variable output for both brands
Smoke test the adapter end-to-end.
Sprint 2
Wire legacy CSS variables into pilot app shell — smoke test
End-to-end proof the pipeline works on one app before any base library refactor begins. Lands first as a go/no-go gate.
Sprint 2
Integrate legacy CSS variables into shared base library
Sprint 2
Refactor shared button styles to consume brand CSS vars
Sprint 2
Refactor shared text styles to consume brand CSS vars
Sprint 2
Refactor shared surface and border styles to consume brand CSS vars
Sprint 2
Apply shared base library updates to core legacy app 1
Sprint 2
Apply shared base library updates to core legacy app 2
Sprint 2
Apply shared base library updates to core legacy app 3
Sprint 4
Finalize legacy brand variable naming and scoping rules
Sprint 4
Add snapshot tests for generated legacy CSS variables
Lock the output shape so unintended changes are caught.
The mechanical rewrite path. Strictly bounded by the known-values manifest, gated by dry-run review, fallback-safe by construction.
Sprint 3
Build exact-match known-values manifest from semantic layer
The only data the plugin is allowed to act on. Generated, not hand-authored.
Sprint 3
Implement PostCSS legacy color-to-var rewrite plugin
Two modes: report-only and commit. Emits var(--token, <original-value>) so the original value remains the fallback. Hand-reviewed code, not AI-merged.
Sprint 3
Run plugin in report-only mode against pilot apps and triage miss-report
Required gate before any commit-mode run. Triage into: add to manifest, fix at source, accept as legitimate hardcode.
Sprint 3
Apply safe color rewrite to core legacy app 1
Commit mode, visual-diff gated.
Sprint 3
Apply safe color rewrite to core legacy app 2
Commit mode, visual-diff gated.
Sprint 3
Apply safe color rewrite to core legacy app 3
Commit mode, visual-diff gated.
Sprint 3
Triage unresolved hardcoded color hotspots
What makes it into the downstream debt report.
Sprint 3
Patch high-impact local overrides blocking brand uptake
Surgical, only where they block pilot success.
Sprint 3
AI-assisted mapping suggestions for long-tail miss-report entries
Claude proposes mappings with confidence scores → review queue → human flip to human-confirmed. Nothing auto-merges.
The safety net, the rehearsal, and the handoff artifacts that make the work durable past Spectrum Day.
Sprint 1
Set up visual QA baseline for pilot legacy surfaces
Sprint 2
Wire visual diff as merge-blocking CI gate above pixel threshold
Without this, visual diff is documentation, not a safety net.
Sprint 2
Create regression screenshots for both incoming brands
Sprint 2
QA shared component rendering across pilot legacy apps
Sprint 3
Validate brand swap — rebuild pilot app under Brand B and diff against Brand A baseline
The actual rebrand rehearsal. Proves the swap works before Spectrum Day relies on it.
Sprint 3
Expand visual regression coverage for legacy flows
Sprint 3
QA automated replacements and fallback behavior
Specifically test the var(--token, <original>) fallback by intentionally breaking the variable bundle load.
Sprint 4
Run cross-brand regression pass on pilot legacy apps
Sprint 4
Run browser and responsive QA sweep for shared legacy surfaces
Sprint 4
Fix QA defects from pilot rollout
Sprint 4
Document and rehearse rollback procedure for legacy brand variable bundle
Hard-date deadline — rollback story will be asked about by someone senior. Have an answer.
Sprint 4
Document legacy consumption pattern for downstream teams
Sprint 4
Publish unresolved legacy debt report by app
Converts the "we're not fixing all of legacy" promise into a tangible artifact each downstream team owns.
Sprint 4
Create rollout guide for additional legacy apps
Sprint 4
Sign off pilot legacy rollout and downstream handoff
Critical Path / Gates
Three hard gates, in order. Missing any of them means stop and reassess, not push forward.
Gate 1
End of Sprint 1 — Semantic layer projects to current modern token package without unexplained drift
If this fails, the IR design is wrong.
Gate 2
Early Sprint 2 — Pilot app shell smoke test renders correctly under both brands
If this fails, the legacy delivery path is wrong.
Gate 3
Mid Sprint 3 — PostCSS report-only run produces a triagable miss-report with no surprises
If the miss-report is unmanageable, scope the manifest more tightly before committing any rewrites.