Write component deprecation notices and migration paths

Produce clear deprecation notices and step-by-step replacement guides for UI components. Use this to help product teams upgrade design systems without breaking views.

You getDeprecation Summary, property Migration Map and step-by-Step Upgrade Guide

Prompt

Prompt
Act as a design system technical writer. Write a clear deprecation notice and upgrade migration guide for the component described below.

- Clearly explain why the component is deprecated.
- Give the exact replacement component and property-by-property mapping.
- Highlight breaking changes, including removed properties or behavior shifts.
- Keep tone helpful, direct, and actionable.

Output format:
- Deprecation Summary (Reason, Target Removal Date, Replacement)
- Property Migration Map (table with Old Prop, New Prop, Notes)
- Step-by-Step Upgrade Guide (3-4 numbered steps)
- What to Verify (bullet list of visual checks)

My component details are below:

Example output

Example for: replacing a legacy CardContainer component with the new modular Surface component

Deprecation Summary
  • Reason: CardContainer relies on hardcoded shadows and rigid padding that conflict with theme tokens.
  • Target Removal Date: Release 4.0.0 (October 31, 2025).
  • Replacement: Surface combined with Stack.
Property Migration Map
Old PropNew PropNotes
shadowLevel="high"elevation="raised"Now maps directly to theme shadow tokens
paddingSize="large"padding="6"Uses space token multiplier (24px) instead of string values
isClickableas="button" or onClickPass semantic button role or explicit click handler
cardHeaderTitleSurface.HeaderSubcomponent slot replaces hardcoded string prop
Step-by-Step Upgrade Guide
  1. Replace CardContainer imports with Surface from the core UI library.
  2. Map shadowLevel to the corresponding elevation token.
  3. Move plain text passed to cardHeaderTitle into the nested <Surface.Header> component.
  4. Remove manual border-radius overrides; Surface handles default radii automatically.
What to Verify
  • Confirm hover states still show on clickable surfaces.
  • Check that cards placed on grey backgrounds use elevation tokens with adequate contrast.
  • Verify child padding has not doubled if an inner wrapper container is present.
Written by AI from this prompt. Your results will vary.

Paste your old component name, its properties, and the new replacement component into ChatGPT, Claude, or Gemini. Follow up by asking for a template announcement message for your design system Slack channel.

Make it repeatable

Keep using this prompt without pasting it in every time.

Keep exploring

More in Design