Migration Playbook

Migrate consuming apps incrementally instead of doing a full rewrite.

1. Audit

• Inventory current UI surfaces (forms, nav, layout, tables).
• Map each surface to @gtcx/ui and @gtcx/templates equivalents.

2. Foundation

• Add GtcxConfigProvider at app root.
• Create token overrides.
• Add route-level feature flags for migrated views.

3. Incremental Replacement

1. Shared primitives first (buttons, inputs, overlays, navigation).
2. Route components second.
3. Page templates/layout wrappers last.

4. Verification Per Route

• Unit/integration tests pass
• Keyboard and focus flow pass
• Alt/progress labels are present
• Visual parity snapshots approved
• Performance budgets remain under threshold

5. Cutover

• Enable migrated route for all users
• Monitor for 24-48h
• Remove legacy code path once stable