Migrate design system components

Replaces legacy interface elements in reviewable batches and retires old implementations after verified adoption.

design-system-migration

Workflow agents using this skill

AgentPrism

See how it helps

When is it useful?

Use when shared buttons, dialogs or selects must be introduced across existing screens.

What does it help you do?

Tests simple, dense and overlay screens before expanding the migration.
Maps changed properties and removes obsolete per-screen styling workarounds.
Checks remaining call sites before removing legacy components and styles.

Try asking this

Migrate our old modal across settings, a dense editor and a simple confirmation, preserving keyboard behavior and responsive layouts. Open all three migrated dialogs with long translations and keyboard input. Compare focus restoration and content overflow before removing the old modal implementation.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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:

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.
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.
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.

Included files 1

SKILL.md