Component Deprecation Notice

When to Use

• Retiring a component in favor of a new one
• Removing a variant or prop from an existing component
• Communicating breaking changes to consuming teams
• Planning end-of-life for legacy components

The Prompt

Write a deprecation notice for a design system component.

Details:
- **Component being deprecated:** [name]
- **Replacement component:** [name or "none"]
- **Reason for deprecation:** [why]
- **Deprecation date:** [when it's marked deprecated]
- **Removal date:** [when it will be deleted]
- **Products/teams affected:** [list]

Include:
1. **Summary** — One-paragraph explanation, empathetic and clear.
2. **Migration guide** — Step-by-step instructions with before/after code examples.
3. **Prop mapping** — Table mapping old props to new props (if replacement exists).
4. **Timeline** — Key dates: deprecation warning, soft removal, hard removal.
5. **FAQ** — 3-4 anticipated questions and answers.
6. **Support** — Where to ask questions or report issues.

Tone: Professional but human. Acknowledge the effort required to migrate.

Example Output

# Deprecation Notice: AlertBanner

## Summary
AlertBanner is deprecated as of March 2026 and will be removed in June 2026.
Please migrate to the new Banner component, which supports richer content,
better accessibility, and all existing AlertBanner use cases.

## Migration Guide

**Before:**
<AlertBanner type="warning" message="Save failed" dismissable />

**After:**
<Banner intent="warning" dismissible>
  <Banner.Content>Save failed</Banner.Content>
</Banner>

## Prop Mapping
| AlertBanner Prop | Banner Prop        | Notes                          |
|------------------|--------------------|--------------------------------|
| type             | intent             | Same values                    |
| message          | children           | Use Banner.Content wrapper     |
| dismissable      | dismissible        | Fixed typo in prop name        |
| onDismiss        | onDismiss          | No change                      |
| icon             | (automatic)        | Icon inferred from intent      |

## Timeline
- March 26, 2026: Deprecation warning added (console.warn)
- April 30, 2026: Soft removal (hidden from docs, still functional)
- June 30, 2026: Hard removal from package

## FAQ
**Q: Can I keep using AlertBanner until removal?**
A: Yes. It will work until June 30 but will show a console warning.

**Q: What if Banner doesn't cover my use case?**
A: Open an issue with your use case. We'll add it to Banner before removal.

**Q: Is there a codemod?**
A: Run `npx @acme/codemods deprecate-alert-banner` for automatic migration.