Migration
Move existing consumers toward the actual token and component contracts without losing behavior, source context or user input.
Inventory before changing
Identify the consuming app, installed package versions, stylesheet imports, token overrides and actual interaction paths. Preserve dirty concurrent work and capture a reviewable baseline. A successful styleguide build does not prove every product consumer is unaffected.
- Search imports and component usage before renaming a prop or export.
- Inspect saved preferences, persisted values and source/review metadata contracts.
- Record the relevant route screenshots and keyboard behavior in both themes.
- Separate a documentation correction from an API or data migration.
Current migration register
| Older assumption | Current direction | Status |
|---|---|---|
| Public pnpm add @mobtranslate/ui | Private workspace:* dependency | Documentation corrected; no registry publication claimed |
| Package /tokens/tokens.css shorthand | Package /src/tokens/tokens.css and /src/components/components.css | Verified source paths; no clean subpath export map yet |
| Blue primary from older semanticColors | Generated semanticColors.primary matches the authored ochre CSS role | Regenerate from CSS; select darkColors explicitly or use live CSS variables |
| React 18-only peer manifest | Package peers and both consumers require ^19.2.7 | Matching runtime/types and frozen workspace installation verified; React 18 is outside this contract |
| Universal asChild recipe | Primitive render for Base UI parts; source-verified Button asChild contract | Button forwarding repaired; verify each consumer’s semantics and handlers |
| Dark class only | Explicit light/dark plus mt-theme and system handling | Controller shared with working navigation |
| Hand-copied developer snippet | Source-generated checked example | Drift check implemented |
Token migration procedure
- Replace role-like hardcoded palette values with the corresponding CSS role only when the meaning is the same.
- Keep foreground/background pairs and all state roles together. Verify contrast at the rendered boundary.
- Inspect local overrides and portalled content separately. A wrapper theme does not automatically reach body-mounted overlays.
- Do not mechanically recolor cultural/source/review metadata. Its meaning and publication authority must remain unchanged.
- Use the generated token reference for actual names and values. Do not migrate to nonexistent tokens such as --shadow-none.
Component and composition migration
- Compare the wrapper’s exported types with each old call site; do not assume current upstream Base UI options exist in the pinned release.
- Replace nested trigger buttons with a supported render composition.
- Preserve form names, native button type, labels, validation messages, refs and handler behavior.
- Keep controlled state controlled through the change. Verify reset, cancellation and persisted values.
- Test keyboard activation and focus return after the migration, not just the default screenshot.
Theme preference migration
This styleguide uses mt-theme with light/dark values and an absent key for system preference. Do not silently consume every generic theme key from unrelated applications. If a real product has an older preference key, design a bounded one-time migration for that product, then verify explicit light on a dark system.
Storage rejection should leave the current tab usable. State whether a choice is persisted or session-only when that difference matters to the product.
Validation and rollback
- Build and exercise the migrated consumer before switching its runtime.
- For real persisted-data migrations, preserve a verified recovery point and use the project’s non-destructive data policy.
- For style/API changes, keep a reviewable commit and the prior build available for rollback.
- Verify the visible route and actual submitted/stored values after cutover.
- A rollback must restore behavior and data compatibility, not merely the old color palette.
Verification checklist
- Imports resolve through the real workspace package and CSS is present.
- Both themes, saved preference, keyboard operation and narrow reflow work.
- Composed controls retain names, states, refs and handlers.
- Input values and source/review/consent records remain intact.
- Known migration gaps remain explicit until their implementation and validation pass.