diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts
index 73e4673e0a..37e79dcd67 100644
--- a/2nd-gen/packages/swc/.storybook/preview.ts
+++ b/2nd-gen/packages/swc/.storybook/preview.ts
@@ -330,7 +330,10 @@ const preview = {
'Rendering and styling migration analysis',
],
'Action button',
- ['Rendering and styling migration analysis'],
+ [
+ 'Accessibility migration analysis',
+ 'Rendering and styling migration analysis',
+ ],
'Action group',
['Rendering and styling migration analysis'],
'Action menu',
@@ -360,9 +363,14 @@ const preview = {
'Rendering and styling migration analysis',
],
'Button group',
- ['Rendering and styling migration analysis'],
+ [
+ 'Accessibility migration analysis',
+ 'Rendering and styling migration analysis',
+ ],
'Checkbox',
['Rendering and styling migration analysis'],
+ 'Close button',
+ ['Accessibility migration analysis'],
'Color field',
['Rendering and styling migration analysis'],
'Color loupe',
@@ -397,6 +405,7 @@ const preview = {
'Link',
[
'Accessibility migration analysis',
+ 'Migration plan',
'Rendering and styling migration analysis',
],
'Menu',
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
index b95254558c..035e3ef2a5 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
@@ -52,6 +52,8 @@
- [Checkbox migration roadmap](checkbox/rendering-and-styling-migration-analysis.md)
- Close Button
- [Close button accessibility migration analysis](close-button/accessibility-migration-analysis.md)
+ - [Close button migration plan](close-button/migration-plan.md)
+ - [Close button migration roadmap](close-button/rendering-and-styling-migration-analysis.md)
- Color Field
- [Color field migration roadmap](color-field/rendering-and-styling-migration-analysis.md)
- Color Loupe
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/migration-plan.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/migration-plan.md
new file mode 100644
index 0000000000..e88a596b33
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/migration-plan.md
@@ -0,0 +1,281 @@
+
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Components](../README.md) / Close Button / Close button migration plan
+
+
+
+# Close button migration plan
+
+
+
+
+In this doc
+
+- [TL;DR](#tldr)
+ - [Most blocking open questions](#most-blocking-open-questions)
+- [1st-gen API surface](#1st-gen-api-surface)
+ - [Properties / attributes](#properties--attributes)
+ - [Methods](#methods)
+ - [Events](#events)
+ - [Slots](#slots)
+ - [CSS custom properties](#css-custom-properties)
+ - [Shadow DOM output (rendered HTML)](#shadow-dom-output-rendered-html)
+- [Dependencies](#dependencies)
+- [Migration sequencing and prerequisites](#migration-sequencing-and-prerequisites)
+- [Changes overview](#changes-overview)
+ - [Must ship — breaking or a11y-required](#must-ship--breaking-or-a11y-required)
+ - [Additive — ships when ready, zero breakage for consumers already on 2nd-gen](#additive--ships-when-ready-zero-breakage-for-consumers-already-on-2nd-gen)
+- [2nd-gen API decisions](#2nd-gen-api-decisions)
+ - [Public API](#public-api)
+ - [Behavioral semantics](#behavioral-semantics)
+ - [Accessibility semantics notes (2nd-gen)](#accessibility-semantics-notes-2nd-gen)
+- [Architecture: core vs SWC split](#architecture-core-vs-swc-split)
+- [Migration checklist](#migration-checklist)
+ - [Preparation (this ticket)](#preparation-this-ticket)
+ - [Setup](#setup)
+ - [API](#api)
+ - [Styling](#styling)
+ - [Accessibility](#accessibility)
+ - [Testing](#testing)
+ - [Documentation](#documentation)
+ - [Review](#review)
+- [Blockers and open questions](#blockers-and-open-questions)
+ - [Design](#design)
+ - [Architecture and behavior](#architecture-and-behavior)
+ - [Scope and prerequisites](#scope-and-prerequisites)
+- [References](#references)
+
+
+
+
+
+> **Epic SWC-2087** · Planning output. Must be reviewed before implementation begins.
+
+---
+
+## TL;DR
+
+- `swc-close-button` should ship as a dedicated 2nd-gen component in both `core` and `swc` layers, not as an extension point buried inside `swc-button`.
+- API should align with modern button conventions: `accessible-label` (consumer-facing), `static-color`, and `size` (`s|m|l|xl`).
+- Variant aliases from 1st-gen (`variant="white|black"`) should be deprecated in favor of `static-color`.
+- Styling source of truth is Spectrum CSS `spectrum-two` `components/closebutton`; 2nd-gen should not re-expose the 1st-gen `--mod-closebutton-*` surface.
+- Accessibility is must-ship: real inner `