From 677bf184bb5c364c2b8eb4684493d9ad0ad20efa Mon Sep 17 00:00:00 2001
From: Tarun Tomar <ttomar@adobe.com>
Date: Tue, 19 May 2026 16:45:13 +0530
Subject: [PATCH 1/2] chore(close-button): migration guide

---
 2nd-gen/packages/swc/.storybook/preview.ts    |  13 +-
 .../close-button/migration-guide.mdx          | 160 ++++++++++++++++++
 2 files changed, 171 insertions(+), 2 deletions(-)
 create mode 100644 2nd-gen/packages/swc/components/close-button/migration-guide.mdx

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/2nd-gen/packages/swc/components/close-button/migration-guide.mdx b/2nd-gen/packages/swc/components/close-button/migration-guide.mdx
new file mode 100644
index 0000000000..18a2344e0e
--- /dev/null
+++ b/2nd-gen/packages/swc/components/close-button/migration-guide.mdx
@@ -0,0 +1,160 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Close button/Migration guide" />
+
+# Close button migration guide
+
+Replace `<sp-close-button>` with `<swc-close-button>`, update the import, and rename `label` to `accessible-label`.
+
+## What changed
+
+### Renamed
+
+| Area             | Spectrum 1 (`sp-close-button`)                       | Spectrum 2 (`swc-close-button`)                                  |
+| ---------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Tag              | `sp-close-button`                                    | `swc-close-button`                                               |
+| Import path      | `@spectrum-web-components/button/sp-close-button.js` | `@adobe/spectrum-wc/components/close-button/swc-close-button.js` |
+| Accessible name  | `label="..."`                                        | `accessible-label="..."`                                         |
+| CSS custom props | `--mod-closebutton-*`                                | `--swc-close-button-*` (see [Styling](#styling))                 |
+
+### Added in Spectrum 2
+
+| Addition              | Notes                                                                                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `icon-size` attribute | `regular` (default) or `large`. Spectrum 1 used the large cross scale; set `icon-size="large"` to match. See [step 4](#4-optional-set-icon-size-large). |
+
+### Removed in Spectrum 2
+
+| Removed                                 | Replacement                                                                                          |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `variant="white"` / `variant="black"`   | `static-color="white"` / `static-color="black"` (see [step 3](#3-replace-variant-with-static-color)) |
+| `label` attribute                       | `accessible-label` instead                                                                           |
+| `--mod-closebutton-*` custom properties | `--swc-close-button-*` equivalents (see [Styling](#styling))                                         |
+
+## Update your code
+
+### 1. Update the import
+
+```js
+// Before
+import '@spectrum-web-components/button/sp-close-button.js';
+// After
+import '@adobe/spectrum-wc/components/close-button/swc-close-button.js';
+```
+
+### 2. Rename the tag and `label` attribute
+
+```html
+<!-- Before -->
+<sp-close-button label="Close"></sp-close-button>
+<sp-close-button>Close</sp-close-button>
+<!-- After -->
+<swc-close-button accessible-label="Close"></swc-close-button>
+<swc-close-button>Close</swc-close-button>
+```
+
+`size`, `disabled`, `static-color`, and `autofocus` are unchanged.
+
+### 3. Replace `variant` with `static-color`
+
+```html
+<!-- Before -->
+<sp-close-button variant="white" label="Close"></sp-close-button>
+<sp-close-button variant="black" label="Close"></sp-close-button>
+<!-- After -->
+<swc-close-button
+  static-color="white"
+  accessible-label="Close"
+></swc-close-button>
+<swc-close-button
+  static-color="black"
+  accessible-label="Close"
+></swc-close-button>
+```
+
+### 4. (Optional) Set `icon-size="large"`
+
+```html
+<!-- Before -->
+<sp-close-button size="m" label="Close"></sp-close-button>
+<!-- After -->
+<swc-close-button
+  size="m"
+  icon-size="large"
+  accessible-label="Close"
+></swc-close-button>
+```
+
+## Accessibility
+
+- **Accessible name is required.** Use `accessible-label` or default-slot text. See [step 2](#2-rename-the-tag-and-label-attribute).
+- **Match the action to the label.** Use **Close** or **Dismiss** for dismiss controls, not **Clear selection** (`<swc-clear-button>` clears field values).
+- **Do not use `<swc-close-button>` for general actions.** Use `<swc-button>` instead.
+
+## Styling
+
+Spectrum 2 exposes a new set of public CSS custom properties on `<swc-close-button>`.
+
+{/* @todo Replace the inline-styled callouts in this section with `<swc-inline-alert>` once it is migrated to Spectrum 2. */}
+
+<div
+  style={{
+    borderLeft: '4px solid #dba842',
+    background: 'rgba(219, 168, 66, 0.12)',
+    padding: '12px 16px',
+    margin: '16px 0',
+    borderRadius: '4px',
+  }}
+>
+  <strong>⚠️ Breaking change.</strong> Spectrum 1{' '}
+  <code>{'--mod-closebutton-*'}</code> properties <strong>do not apply</strong>{' '}
+  to <code>{'<swc-close-button>'}</code>. Remove or replace every{' '}
+  <code>{'--mod-closebutton-*'}</code> override with the{' '}
+  <code>{'--swc-close-button-*'}</code> equivalents below. Not every Spectrum 1
+  property has a 1:1 replacement, so read the list below carefully.
+</div>
+
+Public custom properties:
+
+{/* @todo Replace the Description column with the `@cssproperty` JSDoc descriptions from `<swc-close-button>`'s CEM entry once they are added in a follow-up PR. */}
+
+| Custom property                                | Description                                      |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `--swc-close-button-size`                      | Inline and block size of the control.            |
+| `--swc-close-button-border-radius`             | Corner radius of the hit target.                 |
+| `--swc-close-button-icon-color-default`        | Cross color in the default state.                |
+| `--swc-close-button-icon-color-hover`          | Cross color on hover.                            |
+| `--swc-close-button-icon-color-focus`          | Cross color when focused.                        |
+| `--swc-close-button-icon-color-down`           | Cross color when pressed.                        |
+| `--swc-close-button-icon-color-disabled`       | Cross color when disabled.                       |
+| `--swc-close-button-focus-indicator-gap`       | Gap between the control edge and the focus ring. |
+| `--swc-close-button-focus-indicator-thickness` | Thickness of the focus ring.                     |
+| `--swc-close-button-focus-indicator-color`     | Color of the focus ring.                         |
+| `--swc-close-button-background-color-default`  | Background in the default state.                 |
+| `--swc-close-button-background-color-hover`    | Background on hover.                             |
+| `--swc-close-button-background-color-focus`    | Background when focused.                         |
+| `--swc-close-button-background-color-down`     | Background when pressed.                         |
+
+<div
+  style={{
+    borderLeft: '4px solid #e34850',
+    background: 'rgba(227, 72, 80, 0.10)',
+    padding: '12px 16px',
+    margin: '16px 0',
+    borderRadius: '4px',
+  }}
+>
+  <strong>🚫 Do not target internals.</strong> Internal classes,{' '}
+  <code>{'--_swc-close-button-*'}</code> private properties, and shadow DOM are{' '}
+  <strong>not public API</strong>. Styling applied to them will break without
+  warning on minor releases.
+</div>
+
+## Checklist
+
+- [ ] Update imports from `@spectrum-web-components/button/sp-close-button.js` to `@adobe/spectrum-wc/components/close-button/swc-close-button.js`
+- [ ] Rename all `<sp-close-button>` to `<swc-close-button>`
+- [ ] Rename `label` to `accessible-label`
+- [ ] Replace `variant="white"` / `variant="black"` with `static-color`
+- [ ] Set `icon-size="large"` if you need Spectrum 1 cross icon scale
+- [ ] Replace `--mod-closebutton-*` CSS overrides with `--swc-close-button-*` equivalents

From f9b9450adce6b9c5bf23a84d6f350cbe01aac53d Mon Sep 17 00:00:00 2001
From: Tarun Tomar <ttomar@adobe.com>
Date: Wed, 20 May 2026 17:04:11 +0530
Subject: [PATCH 2/2] docs(close-button): replace consumer guide with migration
 planning docs

---
 .../close-button/migration-guide.mdx          | 160 ----------
 .../03_components/README.md                   |   2 +
 .../close-button/migration-plan.md            | 281 ++++++++++++++++++
 ...endering-and-styling-migration-analysis.md | 107 +++++++
 4 files changed, 390 insertions(+), 160 deletions(-)
 delete mode 100644 2nd-gen/packages/swc/components/close-button/migration-guide.mdx
 create mode 100644 CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/migration-plan.md
 create mode 100644 CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/rendering-and-styling-migration-analysis.md

diff --git a/2nd-gen/packages/swc/components/close-button/migration-guide.mdx b/2nd-gen/packages/swc/components/close-button/migration-guide.mdx
deleted file mode 100644
index 18a2344e0e..0000000000
--- a/2nd-gen/packages/swc/components/close-button/migration-guide.mdx
+++ /dev/null
@@ -1,160 +0,0 @@
-import { Meta } from '@storybook/addon-docs/blocks';
-
-<Meta title="Close button/Migration guide" />
-
-# Close button migration guide
-
-Replace `<sp-close-button>` with `<swc-close-button>`, update the import, and rename `label` to `accessible-label`.
-
-## What changed
-
-### Renamed
-
-| Area             | Spectrum 1 (`sp-close-button`)                       | Spectrum 2 (`swc-close-button`)                                  |
-| ---------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
-| Tag              | `sp-close-button`                                    | `swc-close-button`                                               |
-| Import path      | `@spectrum-web-components/button/sp-close-button.js` | `@adobe/spectrum-wc/components/close-button/swc-close-button.js` |
-| Accessible name  | `label="..."`                                        | `accessible-label="..."`                                         |
-| CSS custom props | `--mod-closebutton-*`                                | `--swc-close-button-*` (see [Styling](#styling))                 |
-
-### Added in Spectrum 2
-
-| Addition              | Notes                                                                                                                                                   |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `icon-size` attribute | `regular` (default) or `large`. Spectrum 1 used the large cross scale; set `icon-size="large"` to match. See [step 4](#4-optional-set-icon-size-large). |
-
-### Removed in Spectrum 2
-
-| Removed                                 | Replacement                                                                                          |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `variant="white"` / `variant="black"`   | `static-color="white"` / `static-color="black"` (see [step 3](#3-replace-variant-with-static-color)) |
-| `label` attribute                       | `accessible-label` instead                                                                           |
-| `--mod-closebutton-*` custom properties | `--swc-close-button-*` equivalents (see [Styling](#styling))                                         |
-
-## Update your code
-
-### 1. Update the import
-
-```js
-// Before
-import '@spectrum-web-components/button/sp-close-button.js';
-// After
-import '@adobe/spectrum-wc/components/close-button/swc-close-button.js';
-```
-
-### 2. Rename the tag and `label` attribute
-
-```html
-<!-- Before -->
-<sp-close-button label="Close"></sp-close-button>
-<sp-close-button>Close</sp-close-button>
-<!-- After -->
-<swc-close-button accessible-label="Close"></swc-close-button>
-<swc-close-button>Close</swc-close-button>
-```
-
-`size`, `disabled`, `static-color`, and `autofocus` are unchanged.
-
-### 3. Replace `variant` with `static-color`
-
-```html
-<!-- Before -->
-<sp-close-button variant="white" label="Close"></sp-close-button>
-<sp-close-button variant="black" label="Close"></sp-close-button>
-<!-- After -->
-<swc-close-button
-  static-color="white"
-  accessible-label="Close"
-></swc-close-button>
-<swc-close-button
-  static-color="black"
-  accessible-label="Close"
-></swc-close-button>
-```
-
-### 4. (Optional) Set `icon-size="large"`
-
-```html
-<!-- Before -->
-<sp-close-button size="m" label="Close"></sp-close-button>
-<!-- After -->
-<swc-close-button
-  size="m"
-  icon-size="large"
-  accessible-label="Close"
-></swc-close-button>
-```
-
-## Accessibility
-
-- **Accessible name is required.** Use `accessible-label` or default-slot text. See [step 2](#2-rename-the-tag-and-label-attribute).
-- **Match the action to the label.** Use **Close** or **Dismiss** for dismiss controls, not **Clear selection** (`<swc-clear-button>` clears field values).
-- **Do not use `<swc-close-button>` for general actions.** Use `<swc-button>` instead.
-
-## Styling
-
-Spectrum 2 exposes a new set of public CSS custom properties on `<swc-close-button>`.
-
-{/* @todo Replace the inline-styled callouts in this section with `<swc-inline-alert>` once it is migrated to Spectrum 2. */}
-
-<div
-  style={{
-    borderLeft: '4px solid #dba842',
-    background: 'rgba(219, 168, 66, 0.12)',
-    padding: '12px 16px',
-    margin: '16px 0',
-    borderRadius: '4px',
-  }}
->
-  <strong>⚠️ Breaking change.</strong> Spectrum 1{' '}
-  <code>{'--mod-closebutton-*'}</code> properties <strong>do not apply</strong>{' '}
-  to <code>{'<swc-close-button>'}</code>. Remove or replace every{' '}
-  <code>{'--mod-closebutton-*'}</code> override with the{' '}
-  <code>{'--swc-close-button-*'}</code> equivalents below. Not every Spectrum 1
-  property has a 1:1 replacement, so read the list below carefully.
-</div>
-
-Public custom properties:
-
-{/* @todo Replace the Description column with the `@cssproperty` JSDoc descriptions from `<swc-close-button>`'s CEM entry once they are added in a follow-up PR. */}
-
-| Custom property                                | Description                                      |
-| ---------------------------------------------- | ------------------------------------------------ |
-| `--swc-close-button-size`                      | Inline and block size of the control.            |
-| `--swc-close-button-border-radius`             | Corner radius of the hit target.                 |
-| `--swc-close-button-icon-color-default`        | Cross color in the default state.                |
-| `--swc-close-button-icon-color-hover`          | Cross color on hover.                            |
-| `--swc-close-button-icon-color-focus`          | Cross color when focused.                        |
-| `--swc-close-button-icon-color-down`           | Cross color when pressed.                        |
-| `--swc-close-button-icon-color-disabled`       | Cross color when disabled.                       |
-| `--swc-close-button-focus-indicator-gap`       | Gap between the control edge and the focus ring. |
-| `--swc-close-button-focus-indicator-thickness` | Thickness of the focus ring.                     |
-| `--swc-close-button-focus-indicator-color`     | Color of the focus ring.                         |
-| `--swc-close-button-background-color-default`  | Background in the default state.                 |
-| `--swc-close-button-background-color-hover`    | Background on hover.                             |
-| `--swc-close-button-background-color-focus`    | Background when focused.                         |
-| `--swc-close-button-background-color-down`     | Background when pressed.                         |
-
-<div
-  style={{
-    borderLeft: '4px solid #e34850',
-    background: 'rgba(227, 72, 80, 0.10)',
-    padding: '12px 16px',
-    margin: '16px 0',
-    borderRadius: '4px',
-  }}
->
-  <strong>🚫 Do not target internals.</strong> Internal classes,{' '}
-  <code>{'--_swc-close-button-*'}</code> private properties, and shadow DOM are{' '}
-  <strong>not public API</strong>. Styling applied to them will break without
-  warning on minor releases.
-</div>
-
-## Checklist
-
-- [ ] Update imports from `@spectrum-web-components/button/sp-close-button.js` to `@adobe/spectrum-wc/components/close-button/swc-close-button.js`
-- [ ] Rename all `<sp-close-button>` to `<swc-close-button>`
-- [ ] Rename `label` to `accessible-label`
-- [ ] Replace `variant="white"` / `variant="black"` with `static-color`
-- [ ] Set `icon-size="large"` if you need Spectrum 1 cross icon scale
-- [ ] Replace `--mod-closebutton-*` CSS overrides with `--swc-close-button-*` equivalents
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 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Components](../README.md) / Close Button / Close button migration plan
+
+<!-- Document title (editable) -->
+
+# Close button migration plan
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [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)
+
+</details>
+
+<!-- Document content (editable) -->
+
+> **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 `<button type="button">`, delegated focus, mandatory discernible name, and keyboard parity for Enter/Space.
+
+### Most blocking open questions
+
+- [Q2](#architecture-and-behavior): Confirm whether `icon-size` should be a public API in SWC or kept internal.
+
+---
+
+## 1st-gen API surface
+
+**Source:** [`1st-gen/packages/button/src/CloseButton.ts`](../../../../1st-gen/packages/button/src/CloseButton.ts)
+**Version:** `@spectrum-web-components/button@1.x`
+**Custom element tag:** `sp-close-button`
+
+### Properties / attributes
+
+| Property | Type | Default | Attribute | Notes |
+| --- | --- | --- | --- | --- |
+| `size` | `'s' \| 'm' \| 'l' \| 'xl'` | no reflected default (`noDefaultSize`) | `size` | Visual default behaves as medium when omitted. |
+| `variant` | `'white' \| 'black' \| ''` | `''` | `variant` | Legacy static-color alias. |
+| `staticColor` | `'white' \| 'black' \| undefined` | `undefined` | `static-color` | Preferred static color signal in 1st-gen. |
+| `label` | `string \| undefined` | `undefined` | `label` | Accessible name channel inherited from button base stack. |
+| `disabled` | `boolean` | `false` | `disabled` | Inherited interaction state. |
+
+### Methods
+
+No close-button-specific public methods.
+
+### Events
+
+No close-button-specific custom events.
+
+### Slots
+
+| Slot | Content | Notes |
+| --- | --- | --- |
+| default | Accessible text label | Rendered in a visually hidden span next to the cross icon. |
+| `icon` | Not consumer-authored | Internal cross icon is rendered by component code. |
+
+### CSS custom properties
+
+1st-gen styling depends on `--mod-closebutton-*` and related inherited `--mod-button-*` pass-throughs. This surface is not carried forward to 2nd-gen.
+
+### Shadow DOM output (rendered HTML)
+
+```html
+<sp-icon-cross300 slot="icon" class="icon spectrum-UIIcon-Cross300"></sp-icon-cross300>
+<span id="label" class="visually-hidden">
+  <slot></slot>
+</span>
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Role |
+| --- | --- | --- |
+| `@spectrum-web-components/base` | 1st-gen | Sized mixin and template base |
+| `@spectrum-web-components/button` | 1st-gen | `StyledButton`/`ButtonBase` inheritance |
+| `@spectrum-web-components/close-button` | 1st-gen | Close button CSS bundle |
+| `@spectrum-web-components/icons-ui` | 1st-gen | Cross icon set (200-500) |
+
+---
+
+## Migration sequencing and prerequisites
+
+`close-button` should follow this order:
+
+1. Finish this plan and rendering analysis.
+2. Scaffold 2nd-gen `core` and `swc` close-button files.
+3. Land API + accessibility behavior before visual parity.
+4. Land S2 styling and then tests/docs.
+
+Prerequisite dependency:
+
+- `ButtonBase` behavior in 2nd-gen button stack should be treated as the contract baseline for focus, naming, and disabled semantics.
+
+---
+
+## Changes overview
+
+### Must ship — breaking or a11y-required
+
+#### API and naming
+
+| # | What changes | 1st-gen behavior | 2nd-gen behavior | Consumer migration path |
+| --- | --- | --- | --- | --- |
+| B1 | Tag rename | `<sp-close-button>` | `<swc-close-button>` | Rename markup and import path. |
+| B2 | Accessible name channel rename | `label` | `accessible-label` | Rename attribute/property and keep semantics identical. |
+| B3 | Static color API cleanup | `variant="white|black"` and `static-color` both allowed | `static-color` is canonical; `variant` deprecated/removed | Replace `variant` with `static-color`. |
+
+#### Styling and visuals
+
+| # | What changes | 1st-gen behavior | 2nd-gen behavior | Consumer migration path |
+| --- | --- | --- | --- | --- |
+| B4 | Remove legacy modifier surface | `--mod-closebutton-*` overrides | Reviewed `--swc-close-button-*` only | Migrate to published 2nd-gen custom props. |
+| B5 | S2 token parity | Legacy token references and class stack | S2 token mapping from `spectrum-two` closebutton CSS | Visual diff review against S2 resources. |
+
+#### Accessibility and behavior
+
+| # | What changes | 1st-gen behavior | 2nd-gen behavior | Consumer migration path |
+| --- | --- | --- | --- | --- |
+| B6 | Semantic button implementation | Host-level semantics from legacy stack | Real inner `<button type="button">` + delegated focus | No API change; update tests asserting internals. |
+| B7 | Required discernible name | Can rely on hidden slot or label | Must always expose accessible name (`accessible-label` or slot text) | Ensure every usage has clear name text. |
+
+### Additive — ships when ready, zero breakage for consumers already on 2nd-gen
+
+| # | What is added | Notes |
+| --- | --- | --- |
+| A1 | Optional icon-scale API (`icon-size`) | Add only if design and implementation both require it. |
+| A2 | Expanded public custom property set | Keep minimal initially; expand only for proven consumer needs. |
+
+---
+
+## 2nd-gen API decisions
+
+### Public API
+
+| Property | Type | Default | Attribute | Confidence |
+| --- | --- | --- | --- | --- |
+| `size` | `'s' \| 'm' \| 'l' \| 'xl'` | `'m'` | `size` | Confirmed |
+| `staticColor` | `'white' \| 'black' \| undefined` | `undefined` | `static-color` | Confirmed |
+| `accessibleLabel` | `string \| undefined` | `undefined` | `accessible-label` | Confirmed |
+| `disabled` | `boolean` | `false` | `disabled` | Confirmed |
+
+### Behavioral semantics
+
+- Component must be a dismiss control, not a clear/reset control.
+- Enter and Space activate like native button behavior.
+- Focus-visible ring behavior must match S2 closebutton semantics including forced-colors compatibility.
+
+### Accessibility semantics notes (2nd-gen)
+
+- Apply recommendations in `accessibility-migration-analysis.md` for role/name/keyboard/focus.
+- Do not duplicate host `role="button"` if inner button is the real focus target.
+
+---
+
+## Architecture: core vs SWC split
+
+- `core`: `CloseButton.base.ts`, types, validations, semantic contracts.
+- `swc`: render template, CSS, element registration, stories, tests.
+- Reuse button-base patterns where possible, but keep close-button semantics distinct from clear-button.
+
+---
+
+## Migration checklist
+
+### Preparation (this ticket)
+- [x] Accessibility migration analysis exists.
+- [x] Rendering and styling migration analysis exists.
+- [x] Migration plan exists and is reviewable.
+
+### Setup
+- [ ] Create `2nd-gen/packages/core/components/close-button/`.
+- [ ] Create `2nd-gen/packages/swc/components/close-button/`.
+- [ ] Wire exports and package entrypoints.
+
+### API
+- [ ] Define `size`, `static-color`, `accessible-label`, `disabled`.
+- [ ] Add deprecation strategy for `variant="white|black"`.
+
+### Styling
+- [ ] Implement S2 closebutton selectors/tokens in SWC CSS.
+- [ ] Define minimal public `--swc-close-button-*` properties.
+
+### Accessibility
+- [ ] Real inner button with delegated focus.
+- [ ] Discernible name enforcement/warnings.
+- [ ] Keyboard and focus-visible parity.
+
+### Testing
+- [ ] Unit tests for API and DOM contract.
+- [ ] Playwright a11y snapshots and keyboard tests.
+- [ ] Storybook interaction coverage.
+
+### Documentation
+- [ ] Storybook docs complete.
+- [ ] Consumer migration guide reconciled to shipped API/CSS.
+- [ ] `@cssprop` docs match migration guide tables.
+
+### Review
+- [ ] Lint/tests/build pass.
+- [ ] Status doc updated.
+- [ ] Changeset included.
+- [ ] Two reviewer sign-off.
+
+---
+
+## Blockers and open questions
+
+### Design
+
+- **Resolved:** Visual sign-off sources are confirmed:
+  - [S2 Web Desktop scale (Figma)](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Web--Desktop-scale-?node-id=125265-577&t=99qlf018hYjRXRft-4)
+  - [S2 close-button anatomy](https://s2.spectrum.corp.adobe.com/page/close-button/#anatomy)
+  - `spectrum-css` `spectrum-two` `components/closebutton/index.css`
+
+### Architecture and behavior
+
+- **Q2:** Should `icon-size` be exposed in public API, or remain internal visual implementation detail?
+
+### Scope and prerequisites
+
+- No additional blockers currently.
+
+---
+
+## References
+
+- [`1st-gen/packages/button/src/CloseButton.ts`](../../../../1st-gen/packages/button/src/CloseButton.ts)
+- [`1st-gen/packages/button/test/close-button.test.ts`](../../../../1st-gen/packages/button/test/close-button.test.ts)
+- [Close button accessibility migration analysis](./accessibility-migration-analysis.md)
+- [Button migration plan](../button/migration-plan.md)
+- [Button migration roadmap](../button/rendering-and-styling-migration-analysis.md)
+- [S2 Web Desktop scale (Figma)](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Web--Desktop-scale-?node-id=125265-577&t=99qlf018hYjRXRft-4)
+- [S2 close-button anatomy](https://s2.spectrum.corp.adobe.com/page/close-button/#anatomy)
+- `spectrum-css` `spectrum-two` `components/closebutton/index.css`
+- `spectrum-css` `spectrum-two` `components/closebutton/dist/metadata.json`
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/rendering-and-styling-migration-analysis.md
new file mode 100644
index 0000000000..aa1ef4bb80
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/rendering-and-styling-migration-analysis.md
@@ -0,0 +1,107 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Components](../README.md) / Close Button / Close button migration roadmap
+
+<!-- Document title (editable) -->
+
+# Close button migration roadmap
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [Component specifications](#component-specifications)
+    - [CSS](#css)
+    - [SWC](#swc)
+- [Comparison](#comparison)
+    - [DOM structure changes](#dom-structure-changes)
+    - [CSS => SWC mapping](#css--swc-mapping)
+- [Summary of changes](#summary-of-changes)
+    - [CSS => SWC implementation gaps](#css--swc-implementation-gaps)
+    - [CSS Spectrum 2 changes](#css-spectrum-2-changes)
+- [Resources](#resources)
+
+</details>
+
+<!-- Document content (editable) -->
+
+## Component specifications
+
+### CSS
+
+**Source of truth for Spectrum 2 visual behavior:** `spectrum-css` `spectrum-two` branch, `components/closebutton/index.css`.
+
+Key selectors and modifiers:
+
+- Base: `.spectrum-CloseButton`
+- Sizes: `.spectrum-CloseButton--sizeS`, `--sizeL`, `--sizeXL` (`m` is base/default)
+- Static colors: `.spectrum-CloseButton--staticWhite`, `.spectrum-CloseButton--staticBlack`
+- States: `:hover`, `:active`, `:focus-visible`, `:disabled`
+- High contrast: `@media (forced-colors: active)`
+
+Primary token groups used by Spectrum CSS:
+
+- Size: `--spectrum-closebutton-size`
+- Icon colors: `--spectrum-closebutton-icon-color-*`
+- Background colors: `--spectrum-closebutton-background-color-*`
+- Focus ring: `--spectrum-closebutton-focus-indicator-*`
+
+### SWC
+
+**Current 1st-gen implementation source:** `1st-gen/packages/button/src/CloseButton.ts`
+
+Current behavior and structure:
+
+- Tag: `sp-close-button`
+- Extends `StyledButton` with `SizedMixin(..., { noDefaultSize: true })`
+- Variant surface: `variant` (`white`/`black`) plus `static-color`
+- Renders cross icon by size (`Cross200`..`Cross500`)
+- Renders visually hidden `<span id="label">` wrapping default slot text
+
+## Comparison
+
+### DOM structure changes
+
+| Area | 1st-gen | 2nd-gen target |
+| --- | --- | --- |
+| Host tag | `<sp-close-button>` | `<swc-close-button>` |
+| Interactive element | Host-level button-like behavior via `ButtonBase` | Real inner `<button type="button">` with delegated focus |
+| Labeling | `label` + hidden slot text | `accessible-label` + optional hidden/slot text fallback |
+| Visual class root | 1st-gen button/close-button class stack | `swc-CloseButton` class contract mapped to S2 selectors |
+
+### CSS => SWC mapping
+
+| Spectrum CSS contract | SWC expectation |
+| --- | --- |
+| `.spectrum-CloseButton` | `.swc-CloseButton` |
+| `--sizeS`, base(m), `--sizeL`, `--sizeXL` | `size="s|m|l|xl"` |
+| `--staticWhite`, `--staticBlack` | `static-color="white|black"` |
+| Focus ring vars + `:focus-visible::after` | Equivalent pseudo-element focus ring in SWC CSS |
+| Forced colors adjustments | Equivalent high-contrast overrides in SWC CSS |
+
+## Summary of changes
+
+### CSS => SWC implementation gaps
+
+- No 2nd-gen close-button component exists yet in `2nd-gen/packages/core` or `2nd-gen/packages/swc`.
+- No SWC close-button CSS exists yet, so no verified `--swc-close-button-*` public property list exists.
+- Migration guide content for close-button styling must remain provisional until SWC CSS and `@cssprop` JSDoc land.
+
+### CSS Spectrum 2 changes
+
+- Static color is modifier-based (`--staticWhite` / `--staticBlack`), not a standalone variant family.
+- Size is single-axis (`--spectrum-closebutton-size`) across both inline/block size.
+- Focus treatment is pseudo-element based and must remain visible in forced-colors mode.
+- S2 story templates include icon scale concepts (`regular` vs `large`); if SWC exposes this, it must be explicit and documented.
+
+## Resources
+
+- `1st-gen/packages/button/src/CloseButton.ts`
+- `1st-gen/packages/button/test/close-button.test.ts`
+- `CONTRIBUTOR-DOCS/03_project-planning/03_components/close-button/accessibility-migration-analysis.md`
+- `CONTRIBUTOR-DOCS/03_project-planning/03_components/button/migration-plan.md`
+- [S2 Web Desktop scale (Figma)](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Web--Desktop-scale-?node-id=125265-577&t=99qlf018hYjRXRft-4)
+- [S2 close-button anatomy](https://s2.spectrum.corp.adobe.com/page/close-button/#anatomy)
+- `spectrum-css (spectrum-two)/components/closebutton/index.css`
+- `spectrum-css (spectrum-two)/components/closebutton/dist/metadata.json`