Designsystem-Komponenten migrieren

Design System Migration

Adopting a new or updated design-system component across an existing product succeeds when executed incrementally — screen by screen or primitive by primitive — rather than through an unverified 200-file search-and-replace that breaks subtle layout assumptions.

1. Incremental Rollout Strategy (Pilot -> Expand -> Retire)

Follow a disciplined three-phase adoption flow:

1. Pilot on 2–3 Representative Screens:
   • Pick one simple screen, one dense/complex screen (e.g., a table, filter bar or settings form) and one modal/overlay flow.
   • Replace the legacy element with the shared design-system primitive and verify layout, spacing, responsive reflow, keyboard focus and dark mode in the browser.
   • If the pilot reveals a genuine gap in the shared component's API, refine the component before migrating the rest of the codebase.
2. Batch Migration by Feature or Component Type:
   • Migrate remaining call sites in small, reviewable batches (or use deterministic AST codemods when prop mappings are 1:1).
   • Remove per-screen CSS overrides (!important, negative margin hacks, duplicate token definitions) that were compensating for the old component's flaws.
3. Retire Legacy Primitives & Dead CSS:
   • Once zero call sites reference the legacy component or outdated CSS class, delete the dead implementation and its orphaned styles so developers cannot accidentally import it again.

2. Managing Breaking Component API Changes

When an existing shared component (Button, Modal, Select) needs a breaking prop or slot change:

• Bridge compatibility where blast radius is large:
  • Support deprecated props temporarily as aliases that map to the new API (logging a dev-mode warning or marking @deprecated in TypeScript with JSDoc instructions: @deprecated Use variant="danger" instead of destructive={true}. Remove after all call sites migrate.).
• Define an explicit removal condition: every temporary bridge or compatibility alias must state what call sites remain and when the bridge will be removed.
• Never silently change default behavior: if a component previously defaulted to size="md" or closeOnBackdropClick={true}, changing that default silently breaks every consumer that relied on the implicit default. Audit all callers first!

3. Preventing Regression to One-Off Styles

• Replace recurring inline styles and magic values with semantic tokens during migration.
• Where appropriate, add lint rules or type constraints (e.g., disallowing raw hex colors in feature CSS or restricting deprecated component imports) so migrated areas stay aligned with the system.