From 432f56c0a98cad35cf9f5a543bbb20bfda97e0ea Mon Sep 17 00:00:00 2001
From: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com>
Date: Thu, 14 May 2026 15:29:26 -0500
Subject: [PATCH 01/56] docs(accordion): refine planning docs (#6269)

Co-authored-by: Nikki Massaro <massaro@adobe.com>
---
 .../03_components/README.md                   |   1 -
 .../accessibility-migration-analysis.md       |  62 ++++-
 .../03_components/accordion/migration-plan.md |  38 +--
 ...endering-and-styling-migration-analysis.md | 225 ------------------
 4 files changed, 77 insertions(+), 249 deletions(-)
 delete mode 100644 CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/rendering-and-styling-migration-analysis.md

diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
index b9bfa27ea3..467337fe38 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
@@ -21,7 +21,6 @@
 - Accordion
     - [Accordion accessibility migration analysis](accordion/accessibility-migration-analysis.md)
     - [Accordion migration plan](accordion/migration-plan.md)
-    - [Accordion migration roadmap](accordion/rendering-and-styling-migration-analysis.md)
 - Action Button
     - [Action button migration roadmap](action-button/rendering-and-styling-migration-analysis.md)
 - Action Group
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/accessibility-migration-analysis.md
index daf1ef1006..1ff4994bb1 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/accessibility-migration-analysis.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/accessibility-migration-analysis.md
@@ -23,6 +23,7 @@
 - [Related 1st-gen accessibility (Jira)](#related-1st-gen-accessibility-jira)
 - [Recommendations: `<swc-accordion>` / `<swc-accordion-item>`](#recommendations-swc-accordion--swc-accordion-item)
     - [ARIA roles, states, and properties](#aria-roles-states-and-properties)
+    - [Header label, optional actions, and Figma vs React Spectrum](#header-label-optional-actions-and-figma-vs-react-spectrum)
     - [Shadow DOM and cross-root ARIA Issues](#shadow-dom-and-cross-root-aria-issues)
     - [Accessibility tree expectations](#accessibility-tree-expectations)
     - [Keyboard and focus](#keyboard-and-focus)
@@ -37,14 +38,16 @@
 
 ## Overview
 
-This doc explains how **`swc-accordion`** and **`swc-accordion-item`** should behave for **accessibility**. The target is **WCAG 2.2 Level AA**. It complements the accordion **rendering-and-styling** migration doc and reflects the **accordion** pattern in the [ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/), Deque’s **single** vs **multiselect** examples, and [Heydon Pickering’s collapsible sections](https://inclusive-components.design/collapsible-sections/) guidance (**`<button>`** inside a real **`<h*>`**; do not put **`role="button"`** on the heading element). The **preferred** implementation uses a **slot for heading text** and a **`heading-level`** property so shadow DOM can render **`<h*>` > `<button>`** with Spectrum styling.
+This doc explains how **`swc-accordion`** and **`swc-accordion-item`** should behave for **accessibility**. The target is **WCAG 2.2 Level AA**. It complements the [accordion migration plan](./migration-plan.md) and reflects the **accordion** pattern in the [ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/), Deque’s **single** vs **multiselect** examples, and [Heydon Pickering’s collapsible sections](https://inclusive-components.design/collapsible-sections/) guidance (**`<button>`** inside a real **`<h*>`**; do not put **`role="button"`** on the heading element). The **preferred** implementation uses a **slot for the section label** (into the disclosure **`<button>`**) plus a **`heading-level`** property so shadow DOM can render **`<h*>` > `<button>`** with Spectrum styling. **Optional** header **direct actions** use a **second** slot—**working name `slot="actions"`**, **final slot name not frozen**—see [Header label, optional actions, and Figma vs React Spectrum](#header-label-optional-actions-and-figma-vs-react-spectrum).
 
 ### Also read
 
-[Accordion migration roadmap](./rendering-and-styling-migration-analysis.md) for DOM and styling migration.
+[Accordion migration plan](./migration-plan.md) for DOM, styling, API decisions, and sequencing.
 
 [Illustrated message migration roadmap](../illustrated-message/rendering-and-styling-migration-analysis.md) — when aligning **heading / title** APIs across components. A **card** migration roadmap should be treated the same way once it exists under this section.
 
+Spectrum 2 **accordion** visuals (including direct actions): [S2 — Web (desktop scale): Accordion (Figma)](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Web--Desktop-scale-?node-id=124732-6479).
+
 ### What an accordion is
 
 - A set of **sections** where each section has a **header control** that expands or collapses a **panel** of content. Only one section may be open, or **multiple** sections may be open, depending on configuration ([Deque: Accordion (Single)](https://dequeuniversity.com/library/aria/accordion-single), [Deque: Accordion (Multiselect)](https://dequeuniversity.com/library/aria/accordion-multi)).
@@ -110,12 +113,49 @@ It is also **risky** to handle **ArrowUp** / **ArrowDown** (or **Home** / **End*
 | **Disabled item** | **Header** **button:** set **`aria-disabled="true"`** and **block** **activation** in script. **Do** **not** use the HTML **`disabled`** **attribute** on the **header** **button** as the **sole** **disabled** **mechanism**—native **`disabled`** often **excludes** the **control** from the **Tab** order, which can **hide** the **item** from **screen** **reader** **users** in **focus** (virtual **cursor**) **mode**. **`aria-disabled`** **keeps** the **header** **focusable** and **exposes** the **disabled** state. **Panel** **root** (content **container** for the **item**): set the **`inert`** **attribute** so the **panel** and its **descendants** in the **flat** **tree** are [inert](https://html.spec.whatwg.org/multipage/interaction.html#the-inert-attribute) (no **focus**, no **pointer**-**target** for **that** **subtree**). **Do** **not** use **`tabindex="-1"`** **instead** of **`aria-disabled`** / **`inert`**—for **example** **`tabindex="-1"`** on the **header** **removes** it from **sequential** **focus** **navigation**, and **`tabindex="-1"`** on **children** is **not** a **substitute** for **`inert`** on the **panel** (which **inerts** the **whole** **subtree**). See **Accessibility** **tree** **expectations** below. |
 | **Single vs multiple open** | **`swc-accordion`** should support **at most one** expanded item or **multiple** expanded items ([Deque single](https://dequeuniversity.com/library/aria/accordion-single) vs [Deque multiselect](https://dequeuniversity.com/library/aria/accordion-multi)). Behavior must match documented props (e.g. analogous to **`allow-multiple`** on **`sp-accordion`**). |
 | **Heading shape (a11y)** | Shadow DOM renders the heading element (`<h2>`–`<h6>` per `level`) wrapping a native **`<button>`** so screen readers get **heading level + button** without **`role="button"`** on the heading ([Inclusive Components](https://inclusive-components.design/collapsible-sections/)). Consumers do not pass a full `<h*>` in light DOM; they supply text and set `level` for the outline. **`heading-level`** / **`level`** property accepts **`2`–`6`** (mirror 1st-gen **`level`** on **`sp-accordion-item`**). |
-| **Heading API (1st-gen → 2nd-gen, breaking)** | 1st-gen exposes a string **`label`** attribute (`AccordionItem.label`) rendered into shadow DOM. **2nd-gen decision (clean break, same posture as other migrated components):** ship **no** **`label`** on **`swc-accordion-item`** — heading copy **only** via the **heading slot** (exact slot name at API freeze). **Do not** add a deprecated **`label`** path or dual-source precedence; document migration as **`label="…"` → slotted heading** in the migration guide and Storybook so later phases do not reintroduce **`label`**. Remaining decisions before implementation: (1) Accepted slot content (text only vs allowing inline phrasing such as `<strong>` / `<code>`). (2) Slot-change handling: re-evaluate accessible name; no focusable descendants are expected inside the label. |
+| **Heading API (1st-gen → 2nd-gen, breaking)** | 1st-gen exposes a string **`label`** attribute (`AccordionItem.label`) rendered into shadow DOM. **2nd-gen decision (clean break, same posture as other migrated components):** ship **no** **`label`** on **`swc-accordion-item`** — heading copy **only** via the **heading / label slot** (exact slot name at API freeze). **Do not** add a deprecated **`label`** path or dual-source precedence; document migration as **`label="…"` → slotted heading** in the migration guide and Storybook so later phases do not reintroduce **`label`**. Remaining decisions before implementation: (1) Accepted slot content (text only vs allowing inline phrasing such as `<strong>` / `<code>`). (2) Slot-change handling: re-evaluate accessible name; **no** **focusable** descendants inside the **label** slot—interactive controls belong in the **optional header affordance** slot (**working name `actions`**—see [Header label, optional actions, and Figma vs React Spectrum](#header-label-optional-actions-and-figma-vs-react-spectrum)). (3) Disabled / **`inert`** interaction with slotted actions per [migration plan](./migration-plan.md). |
 | **Consistency** | Align **`heading-level`** / **`level`** naming, range, and **default** with **[Illustrated message](../illustrated-message/rendering-and-styling-migration-analysis.md)** and **card** (once specified) so teams use **one** mental model for section titles. |
 | **Keyboard — Space** | On **`keydown`** / **`keyup`** for **Space** while focus is on the header **`button`**, **`preventDefault()`** so the browser does **not** scroll the page or an **overflow** container; then **toggle** open/closed per APG ([SWC-1487](https://jira.corp.adobe.com/browse/SWC-1487)). |
 | **Keyboard — Tab** | Rely on the **normal** **Tab** / **Shift+Tab** order only ([APG example](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/examples/accordion/)). **Do not** use **roving** **`tabindex`** on header **buttons** and **do not** implement **arrow**-key (or **Home** / **End**) moves **only** between **headers**; both conflict with **focus** **inside** **open** **panels** and with **scrolling** when **`preventDefault`** is misapplied to **arrows** on a **header**. |
 | **Do not** | Put **`role="button"`** on a **heading** instead of using a **`<button>`** inside the heading ([Inclusive Components](https://inclusive-components.design/collapsible-sections/)). |
 
+### Header label, optional actions, and Figma vs React Spectrum
+
+**Product / API shape**
+
+- **Figma** ([S2 — Accordion](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Web--Desktop-scale-?node-id=124732-6479)) shows **direct actions** as **explicit** toggles such as **show direct actions**, **show switch**, and **show action button**—a fixed matrix for **design exploration**. In practice **show direct actions** reads as the **general** “**stuff beside the title**” region, while the other toggles control **which** control appears in that region.
+- **React Spectrum** exposes **[`AccordionItemHeader`](https://react-spectrum.adobe.com/Accordion#accordionitemheader)** with **open-ended** children (any **ReactNode**)—see [React Spectrum — Accordion](https://react-spectrum.adobe.com/Accordion). **[`AccordionItemPanel`](https://react-spectrum.adobe.com/Accordion#accordionitempanel)** documents optional **`aria-describedby`** / **`aria-labelledby`** on the panel when authors need richer panel labeling.
+
+**Design / engineering consensus (accessibility)**
+
+- **Spectrum design + accessibility engineering** align that **SWC** should **own** optional **direct actions** in the **DOM** for **ARIA** and **focus** reasons: interactive affordances (**Edit**, **switch**, etc.) must live **outside** the disclosure **`<button>`** (and **not** inside the same **click** / **keyboard** target as **expand/collapse**). Putting them **inside** the heading **button** mangles **names**, **roles**, and **activation**, and adds **awkward** **tab** stops **before** the **panel** in ways that are hard to explain to screen reader users.
+- Some **Spectrum CSS** reference markup places affordances **inside** a **heading** tag for **layout** only; **SWC** must **not** copy that if it would put **focusable** widgets **inside** the disclosure **`<button>`**. Prefer this shadow DOM shape: **`<h*>`** wrapping **only** the disclosure **`<button>`** (named from the **label** slot), with the actions container as a **sibling to `<h*>`** (not inside it) so the heading's accessible name stays clean:
+
+  ```html
+  <h3><button id="header" aria-expanded="..." aria-controls="content">...</button></h3>
+  <div class="actions"><slot name="actions"></slot></div>
+  <div id="content" role="region" aria-labelledby="header"><slot></slot></div>
+  ```
+
+  Any content inside `<h*>` — including a sibling div to the button — can bleed into the heading's accessible name, so the actions container must live outside the heading element entirely. **Tab** order stays **disclosure** → **slotted actions** → **panel** when expanded, matching intent from the design thread.
+- **Slots:** one for the **section label** (projected into the disclosure **`<button>`**—**no** **focusable** descendants in that slot) and a **second** slot for **optional** chrome beside the title. **Working slot name `actions`**; final name is not frozen ([migration plan](./migration-plan.md#open--api-and-scope)).
+
+**`aria-describedby` in consumer docs (Storybook) — required**
+
+- **Consumer-facing** Storybook (and usage docs) **must** include an example where the **label** region exposes a stable **`id`** and the **optional** slot’s **wrapper** uses **`aria-describedby`** pointing at that **`id`**, so screen reader users hear how **“Edit”** (or a **switch**) relates to **“Bellows”** / the section title. Keep **`id`** values **unique** in the document. **`slot="actions"`** below is **illustrative** until the slot name is frozen:
+
+```html
+<swc-accordion-item>
+  <div id="bellows-heading" slot="label">Bellows</div>
+  <div slot="actions" aria-describedby="bellows-heading">
+    <button type="button">Edit</button>
+  </div>
+  <div>The bellows is the expandable section in the middle of the accordion.</div>
+</swc-accordion-item>
+```
+
+- If **`aria-describedby`** targets live in **light DOM** and the disclosure **`<button>`** stays in **shadow DOM**, the same **cross-root** **IDREF** caveats as other components apply—prefer wiring **descriptions** where **id** and **referrer** share a **root**, or document supported patterns explicitly.
+
 ### Shadow DOM and cross-root ARIA Issues
 
 - Under the **preferred** pattern (**heading text** slot + **`heading-level`**), the **`<h*>`**, **`<button>`**, and **`role="region"`** panel usually live in the **same** shadow root with **stable internal ids**. **`aria-controls`** and **`aria-labelledby`** should resolve **without** cross-root **IDREF** wiring, matching the APG accordion example shape.
@@ -126,7 +166,8 @@ It is also **risky** to handle **ArrowUp** / **ArrowDown** (or **Home** / **End*
 **Per expanded item**
 
 - **Heading:** **heading** role at **level** from **`heading-level`** / **`level`**; **button** nested inside (Inclusive / APG shape).
-- **Trigger:** **button**, name from slotted **label** text (and optional icon **decorative**).
+- **Trigger:** **button**, name from slotted **label** text (and optional **decorative** icon on the disclosure control only).
+- **Optional slotted header actions:** If the second slot (**working name `actions`**, **final name TBD**) hosts **buttons**, **switches**, or other widgets, each keeps its **own** **role** and **accessible name**—**not** merged into the disclosure **button**. **Tab** order follows **DOM** order; document the expected order (disclosure vs actions vs panel) in Storybook. Do **not** place those widgets **inside** the disclosure **`<button>`**.
 - **`aria-expanded`:** **`true`** when panel is shown, **`false`** when hidden.
 - **Panel:** **`role="region"`**, named via **`aria-labelledby`** to the trigger (APG). When the panel is not visible, it must **not** expose interactive descendants in the tab order ([Collapsible sections](https://inclusive-components.design/collapsible-sections/)).
 
@@ -165,9 +206,9 @@ Pick one mechanism per state. **Do not** mix `tabindex="-1"` sweeps with the val
 | Kind of test | What to check |
 |--------------|----------------|
 | **Unit** | **`aria-expanded`** toggles with open state; **`aria-controls`** id matches panel; panel **`role`** and **`aria-labelledby`**; **disabled** items: **`aria-disabled`** on **header** **`button`**, **`inert`** on **panel** (assert **no** **`tabindex="-1"`** **substitute** for that **pair**); **activation** blocked; **Space** on enabled header calls **`preventDefault()`** and toggles without unintended scroll. |
-| **aXe + Storybook** | **WCAG 2.x** rules on accordion stories (single vs multiple open, disabled item). |
-| **Playwright ARIA snapshots** | Snapshot **tree** for open/closed items; **`heading`** role **level** changes when **`heading-level`** / **`level`** changes. |
-| **Keyboard** | **Tab** / **Shift+Tab** through all focusables; **no** roving `tabindex` on headers; **no** default **arrow**-key “header-only” **navigation** that could **interfere** with **scroll**; **Space** on header **`preventDefault`** + **toggle** per [SWC-1487](https://jira.corp.adobe.com/browse/SWC-1487); **Enter** per APG. |
+| **aXe + Storybook** | **WCAG 2.x** rules on accordion stories (single vs multiple open, disabled item, **`quiet`**, host **`disabled`**). Include at least one story with **optional header actions** (e.g. **Edit** **button**, **switch**) and verify **Tab** order + **`aria-describedby`** example from [Header label, optional actions, and Figma vs React Spectrum](#header-label-optional-actions-and-figma-vs-react-spectrum). |
+| **Playwright ARIA snapshots** | Snapshot **tree** for open/closed items; **`heading`** role **level** changes when **`heading-level`** / **`level`** changes; when header actions exist, disclosure **`button`** name is **separate** from slotted **action** controls. |
+| **Keyboard** | **Tab** / **Shift+Tab** through all focusables including slotted header **actions** before panel content when DOM order places them there; **no** roving `tabindex` on headers; **no** default **arrow**-key “header-only” **navigation** that could **interfere** with **scroll**; **Space** on header **`preventDefault`** + **toggle** per [SWC-1487](https://jira.corp.adobe.com/browse/SWC-1487); **Enter** per APG. |
 
 ---
 
@@ -179,6 +220,7 @@ Pick one mechanism per state. **Do not** mix `tabindex="-1"` sweeps with the val
 - [ ] No **`role="button"`** on the heading element; shadow DOM uses **`<button>`** inside **`<h2>`–`<h6>`**.
 - [ ] **Keyboard** and **disabled** behavior covered by tests and docs; **Space** on the header **`preventDefault()`** + **toggle** (no spurious scroll in overflow layouts). **No** roving `tabindex` on headers; **no** default arrow-key / Home / End “next header” behavior that blocks scroll; **Tab** is the main way to move between headers and in-panel focusables, matching the [APG accordion example](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/examples/accordion/).
 - [ ] **Disabled** **items:** **header** uses **`aria-disabled="true"`** (focusable, no toggle); **panel** **container** uses **`inert`** so **subtree** is inert; **no** **`tabindex="-1"`** **instead** of that **pair**; verify with **screen** **reader** **focus** **mode** and **unit** / **aXe** where **applicable**.
+- [ ] **Optional header actions** (second slot—**working name `actions`**, **final name not frozen**): disclosure **`button`** stays **separate** from slotted widgets; **consumer** Storybook **must** include the **`aria-describedby`** pattern tying the affordance wrapper to the **label** **`id`** ([Header label, optional actions, and Figma vs React Spectrum](#header-label-optional-actions-and-figma-vs-react-spectrum)); **Tab** / snapshots cover **switch** + **button** cases.
 - [ ] **References** below include APG, Deque, and Inclusive Components links used in this doc.
 
 ---
@@ -190,10 +232,14 @@ Pick one mechanism per state. **Do not** mix `tabindex="-1"` sweeps with the val
 - [Deque University: Accordion (Single)](https://dequeuniversity.com/library/aria/accordion-single)
 - [Deque University: Accordion (Multiselect)](https://dequeuniversity.com/library/aria/accordion-multi)
 - [Inclusive Components: Collapsible sections](https://inclusive-components.design/collapsible-sections/)
+- [Inclusive Components: Cards — pseudo content trick](https://inclusive-components.design/cards/#thepseudocontenttrick) (header affordances beside title)
+- [React Spectrum — Accordion](https://react-spectrum.adobe.com/Accordion), [`AccordionItemHeader`](https://react-spectrum.adobe.com/Accordion#accordionitemheader), and [`AccordionItemPanel`](https://react-spectrum.adobe.com/Accordion#accordionitempanel)
+- [Spectrum CSS — Accordion story (actions + switches)](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/story/components-accordion--default&args=hasActionButtons:!true;hasSwitches:!true) (layout reference; verify **a11y** in SWC)
+- [S2 — Web (desktop scale): Accordion (Figma)](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Web--Desktop-scale-?node-id=124732-6479)
 - [WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/)
 - [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
 - [Using ARIA (read this first)](https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/)
 - [WAI-ARIA 1.2: `aria-disabled` (state)](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled)
 - [HTML: the `inert` attribute](https://html.spec.whatwg.org/multipage/interaction.html#the-inert-attribute)
-- [Accordion migration roadmap](./rendering-and-styling-migration-analysis.md)
+- [Accordion migration plan](./migration-plan.md)
 - [Illustrated message migration roadmap](../illustrated-message/rendering-and-styling-migration-analysis.md)
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/migration-plan.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/migration-plan.md
index 233c92b90f..c4e8684501 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/migration-plan.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/migration-plan.md
@@ -56,13 +56,12 @@
 
 - **No 2nd-gen accordion** package exists yet under `2nd-gen/packages/`; Setup phase creates core + SWC scaffolds.
 - **Accessibility migration analysis** is the behavioral contract for WCAG 2.2 AA; 2nd-gen diverges from 1st-gen on keyboard (no `FocusGroupController` arrow/Home/End on the host, no roving `tabindex` between item hosts), disabled header semantics (`aria-disabled` + panel `inert`), closed-panel hiding (`hidden` vs `display: none` only), heading **API** (**slotted** heading text **only** — **no** string **`label`**, clean break vs 1st-gen), and **Space** handling (**SWC-1487**).
-- **Rendering-and-styling migration analysis** is **in progress** — 1st-gen inventory and DOM summary are in [rendering-and-styling migration analysis](./rendering-and-styling-migration-analysis.md); finish S2 selector/token pass before Phase 4, with **spectrum-css** in the [same workspace](../../02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#workspace-setup).
 - **React Spectrum S2 parity (planning):** Align public surface where authors expect cross-product parity — **`quiet`** on the accordion (from RS **`isQuiet`**) and **`disabled`** on the accordion host (**accordion-wide** disable, from RS **`isDisabled`** on **`Accordion`**), in addition to per-item **`disabled`**. Details: [React Spectrum alignment considerations](#react-spectrum-alignment-considerations).
 - **Severity:** **Normal** for migration planning. Escalate to **Major** only if Spectrum 2 accordion CSS is missing or core infrastructure blocks a core/SWC split (not observed today).
 
 ### Most blocking open questions
 
-None for **starting** implementation, provided the rendering roadmap is expanded before styling work. **`label` vs slot** is **decided:** slotted heading only — **no** 2nd-gen **`label`** (see [accessibility migration analysis](./accessibility-migration-analysis.md)). Still resolve **final slot names** (heading vs panel), and **toggle event naming** before API freeze (see [Open — API and scope](#open--api-and-scope)). After [rendering-and-styling migration analysis](./rendering-and-styling-migration-analysis.md) is completed with the [analyze rendering and styling](../../02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md) workflow, do a **consistency pass** on this plan and remove stale draft placeholders.
+None for **starting** implementation. **`label` vs slot** is **decided:** slotted heading only — **no** 2nd-gen **`label`** (see [accessibility migration analysis](./accessibility-migration-analysis.md)). Still resolve **final slot names** (heading vs panel), and **toggle event naming** before API freeze (see [Open — API and scope](#open--api-and-scope)).
 
 ---
 
@@ -141,16 +140,23 @@ Inherited: `SizedMixin(Focusable)` — `tabIndex` / `focus` / `blur` / `click` d
 
 1st-gen accordion pulls Spectrum 1 styles from [`spectrum-accordion.css`](../../../../1st-gen/packages/accordion/src/spectrum-accordion.css), [`spectrum-accordion-item.css`](../../../../1st-gen/packages/accordion/src/spectrum-accordion-item.css), and related files; authors could reach a **broad** **`--spectrum-accordion-*`** / **`--mod-*`** surface for overrides.
 
-**2nd-gen:** This full modifier surface **will not** be carried forward. Replace with S2 tokens and a **narrow**, reviewed customization story (see [rendering-and-styling migration analysis](./rendering-and-styling-migration-analysis.md) and Phase 4 mapping). 
+**2nd-gen:** This full modifier surface **will not** be carried forward. Replace with S2 tokens and a **narrow**, reviewed customization story (see Phase 4 mapping).
+
 ### Shadow DOM output (rendered HTML)
 
 **`sp-accordion-item` (conceptual):**
 
 ```html
 <h2 id="heading">
-  <!-- optional chevron (2nd-gen: prefer swc-icon) + -->
-  <button id="header" aria-expanded="..." aria-controls="content">...</button>
+  <button id="header" aria-expanded="..." aria-controls="content">
+    <!-- swc-icon chevron, first child inside the button; 1st-gen placed this in a span before the button, outside it -->
+    <span class="spectrum-Accordion-itemTitle"><!-- slotted heading text; 1st-gen rendered label as a bare text node --></span>
+  </button>
 </h2>
+<!-- actions container is a sibling to <h*>, NOT inside it — keeps heading accessible name clean -->
+<div class="actions" hidden>
+  <slot name="actions"></slot>
+</div>
 <div id="content" role="region" aria-labelledby="header">
   <slot></slot>
 </div>
@@ -182,7 +188,7 @@ Inherited: `SizedMixin(Focusable)` — `tabIndex` / `focus` / `blur` / `click` d
 |---|---|
 | **Upstream 2nd-gen components** | Accordion does not require another incomplete 2nd-gen composite; it uses **core** + **base** + **icons** patterns. Follow the [badge migration reference](../../02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#reference-badge-migration) for core/SWC layout. |
 | **Cross-component API alignment** | **`level`** / heading naming should stay aligned with **illustrated message** and **card** when those specs exist ([accessibility migration analysis](./accessibility-migration-analysis.md)). **`quiet`** / host **`disabled`** naming should match other 2nd-gen components that expose the same Spectrum concepts ([React Spectrum alignment considerations](#react-spectrum-alignment-considerations)). |
-| **Step 1 (analyze rendering and styling)** | [Rendering roadmap](./rendering-and-styling-migration-analysis.md) is **in progress** — finish S2 selector and token pass with **spectrum-css** `spectrum-two` beside this repo before treating Step 1 as complete. |
+| **Step 1 (analyze rendering and styling)** | Complete — key findings and DOM changes are captured in this plan. |
 
 ---
 
@@ -227,18 +233,20 @@ No 2nd-gen package yet — this section records **planned** decisions from analy
 |---|---|---|
 | Accordion | `allow-multiple` (or aligned name), **public** **`level`** (`2`–`6`), **`density`**, `size` | **`level`** is the **only** author-facing control for heading depth for all items. **`size`** propagates to assigned items (same as 1st-gen). See **`density`** row. |
 | Accordion — `density` | Reflected string **`compact`** \| **`regular`** \| **`spacious`** | Align with [React Spectrum **`density`**](https://react-spectrum.adobe.com/Accordion) and S2: **`regular`** is the default spacing (1st-gen **omitted** / legacy default maps here). **TypeScript** and docs should list **all three** values even though **`regular`** is default. **Dev warning** when the attribute is **omitted** is **recommended** (same spirit as Badge **`variant`**) so authors stay explicit—confirm at API freeze. Host-only (1st-gen does **not** assign **`density`** on **`AccordionItem`** in script). |
-| Accordion — `quiet` | Boolean; reflected attribute **`quiet`** | Parity with [React Spectrum **`isQuiet`**](https://react-spectrum.adobe.com/Accordion). **Accordion host only** — propagate effective quiet styling to assigned items internally. **Do not** expose **per-item** **`quiet`**: quiet removes dividers between rows; mixing styles per item is **visually chaotic** and **contradicts** Figma usage guidance ([rendering-and-styling migration analysis — Figma](./rendering-and-styling-migration-analysis.md#figma--s2-web-desktop-scale)). |
+| Accordion — `quiet` | Boolean; reflected attribute **`quiet`** | Parity with [React Spectrum **`isQuiet`**](https://react-spectrum.adobe.com/Accordion). **Accordion host only** — propagate effective quiet styling to assigned items internally. **Do not** expose **per-item** **`quiet`**: mixing default and quiet items is **visually incompatible**; the quiet hover state uses rounded corners, which creates corner gaps when placed inside a default accordion that uses dividers. Prefer one style family per accordion instance. |
 | Accordion — `disabled` | Boolean; reflected attribute **`disabled`** | Parity with RS **`isDisabled`** on **`Accordion`**: **accordion-wide** disable — every item non-interactive (no expand/collapse), same **a11y** posture as item-level disable ([accessibility migration analysis](./accessibility-migration-analysis.md): header **`aria-disabled`**, panel **`inert`**). When the host is **`disabled`**, that gate **wins** over per-item **`disabled`** being false. When the host clears **`disabled`**, each item’s own **`disabled`** applies again unchanged. For **visual** disabled state on descendants, prefer **container queries** or host-driven styling so you do **not** reflect host **`disabled`** onto every child **solely** for CSS—only use per-item flags where behavior or a11y requires it. |
 | Item | `open`, `disabled` | Same semantics as today unless renamed for consistency. **No** public **`quiet`** on the item. |
 | Item (implementation) | **`protected` `heading`** (`2`–`6`) | **Not** public API—not reflected, not set by consumers. Parent **`level`** assigns **`heading`** on each slotted item (core/SWC lifecycle). |
 | Heading text | Slotted (see [Shadow DOM output](#shadow-dom-output-rendered-html)) | **Rationale:** a string **`label`** cannot mirror phrasing content (`<strong>`, `<code>`) into the header’s accessible name the way slotted light DOM can; matches [accessibility migration analysis](./accessibility-migration-analysis.md). **Breaking** vs 1st-gen **`label`**: **clean break** — 2nd-gen does **not** expose **`label`**; authors migrate markup to the heading slot only. |
 | Events | Renamed toggle event | Exact string TBD. |
+| Direct actions (item header affordances) | `slot="actions"` on `swc-accordion-item` (working name — not frozen); open-ended, any content may be slotted | (spectrum-css container class `.spectrum-Accordion-itemDirectActions`) rendered as a **sibling to the `<h*>` element** (not inside it); placing it inside `<h*>` would bleed its text content into the heading's accessible name. `slotchange` observer hides the container when empty. `stopPropagation` on the container prevents slot clicks from toggling the accordion. Specific supported content (`swc-action-button`, `swc-switch`) are open questions; see [Open — API and scope](#open--api-and-scope). |
+| `noInlinePadding` modifier | Not a public attribute | The spectrum-css modifier class `.spectrum-Accordion--noInlinePadding` controls inline padding removal (new in S2). **Not** exposed as an API attribute — expose the relevant padding via `--swc-accordion-*` custom properties so consumers can remove or adjust inline padding directly. |
 
 ### React Spectrum alignment considerations
 
 [React Spectrum S2 — Accordion](https://react-spectrum.adobe.com/Accordion) exposes **`isQuiet`** and **`isDisabled`** on the **`Accordion`** root (and **`isQuiet`** / **`isDisabled`** on **`AccordionItem`**). 1st-gen **`sp-accordion`** has **neither** host **`quiet`** nor host **`disabled`**; only **`sp-accordion-item`** supports **`disabled`**. For 2nd-gen, treat the following as **API planning targets** so Spectrum authors can mirror React examples in markup:
 
-1. **`quiet`:** Map RS **`isQuiet`** to boolean **`quiet`** on **`swc-accordion`** (Spectrum 2 CSS uses the same name). Propagate styling to items **internally**; **do not** add a public **per-item** **`quiet`** API ([rendering-and-styling migration analysis](./rendering-and-styling-migration-analysis.md#figma--s2-web-desktop-scale)).
+1. **`quiet`:** Map RS **`isQuiet`** to boolean **`quiet`** on **`swc-accordion`** (Spectrum 2 CSS uses the same name). Propagate styling to items **internally**; **do not** add a public **per-item** **`quiet`** API.
 
 2. **Accordion-wide `disabled`:** Map RS **`isDisabled`** on **`Accordion`** to **`disabled`** on **`swc-accordion`**. Implementation should drive the same behavior as “every item disabled” without authors having to set **`disabled`** on each item: block toggles, apply quiet/disabled visuals per design, and apply the **disabled item** a11y matrix on **every** header/panel pair. **Controlled-mode** authors who set **`open`** on items should not be able to expand while the host stays **`disabled`** (treat like item-level guardrails today, extended to the whole set).
 
@@ -269,7 +277,6 @@ For **`allow-multiple` false**, the parent must keep **at most one** item **`ope
 | Document | Use |
 |---|---|
 | [Accessibility migration analysis](./accessibility-migration-analysis.md) | WCAG 2.2 AA target, disabled matrix, keyboard, testing expectations. |
-| [Rendering-and-styling migration analysis](./rendering-and-styling-migration-analysis.md) | S2 CSS and token mapping — **in progress**; complete S2 sections before Phase 4. |
 | [Washing machine workflow](../../02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md) | Phase order and quality gates. |
 
 ---
@@ -294,7 +301,7 @@ Gates align with [01_washing-machine-workflow.md](../../02_workstreams/02_2nd-ge
 ### Preparation (this ticket)
 
 - [ ] Preparation inputs tracked (Figma, epic id, S2 rendering pass) per team process—no separate contributor prep doc for accordion
-- [ ] This plan + accessibility analysis + expanded rendering roadmap reviewed
+- [ ] This plan + accessibility analysis reviewed
 - [ ] Breaking changes and consumer migration notes agreed
 - [ ] Open questions in [Blockers and open questions](#blockers-and-open-questions) resolved or ticketed
 - [ ] Plan reviewed by at least one other engineer
@@ -313,7 +320,7 @@ Gates align with [01_washing-machine-workflow.md](../../02_workstreams/02_2nd-ge
 ### Styling
 
 - [ ] S2 CSS integrated; stylelint clean
-- [ ] Document token / `--mod-*` → S2 (or `--swc-*`) mapping for consumers; include **`density` × `size`** matrix ([rendering-and-styling migration analysis](./rendering-and-styling-migration-analysis.md#summary-of-changes))
+- [ ] Document token / `--mod-*` → S2 (or `--swc-*`) mapping for consumers; include **`density` × `size`** matrix
 
 ### Accessibility
 
@@ -329,7 +336,8 @@ Gates align with [01_washing-machine-workflow.md](../../02_workstreams/02_2nd-ge
 
 ### Documentation
 
-- [ ] JSDoc, usage docs, Storybook stories (include a spacing / **custom properties** story for “no inline padding” style parity—**no** **`show paddings`**-style attribute; see [rendering roadmap — Figma](./rendering-and-styling-migration-analysis.md#figma--s2-web-desktop-scale))
+- [ ] JSDoc, usage docs, Storybook stories (include a spacing / **custom properties** story for “no inline padding” style parity; **no** `noInlinePadding`-style attribute)
+- [ ] Add a Storybook story demonstrating inline padding customization via `--swc-accordion-*` custom properties (no `noInlinePadding`-style attribute)
 - [ ] Do not document arrow-key navigation between headers for 2nd-gen (contrast with legacy README)
 
 ### Review
@@ -348,11 +356,12 @@ Gates align with [01_washing-machine-workflow.md](../../02_workstreams/02_2nd-ge
 | **Standalone item** | **Direction:** **`swc-accordion-item`** without a parent stays **supported** with reasonable defaults (**`protected` `heading`** defaults to **`3`**, same as today’s accordion default)—matches existing tests and story patterns. Ticket any change if product requires parent-only usage. |
 | Heading slot content | Text-only vs inline phrasing (`<strong>`, `<code>`) in heading slot. |
 | Toggle event | Exact `swc-*` event name. |
-| Rendering doc | Who expands [rendering-and-styling migration analysis](./rendering-and-styling-migration-analysis.md) with S2 paths before Phase 4? |
 | Chevron / disclosure icon | Prefer **`swc-icon`** internally; finalize icon asset/name against S2. |
 | Accordion host **`disabled`** | Confirm **controlled** **`open`** cannot expand while host **`disabled`**; prefer **container-query** / host styling for descendant disabled visuals ([Public API](#public-api) **`disabled`** note). |
 | **`density`** dev warning | Confirm **omit-attribute** warning ships with accordion (recommended; same spirit as Badge **`variant`**). |
-| **`RadioController`** scope | Ship **inside** `AccordionBase` first vs extract to **core** for **radio group**, **`role="menuitemradio"`** menus, **tabs**, and/or coordinate with a **refactor** of **`FocusgroupNavigationController`** (split “selection flags” vs “focus roving”)? **Depends on** menu / radio / tabs migration timing and whether teams want one shared **selection-sync** API vs local loops per component. |
+| **Direct actions — disabled state** | **Decided:** Do **not** propagate `disabled` to slotted actions content. The actions slot may hold affordances whose purpose is precisely to explain or resolve why the item is disabled (e.g., an “Upgrade” button, or an action button attached to a popover describing deprecation). Coupling disablement would remove those affordances exactly when they are most needed. |
+| **Direct actions — content constraints** | Slot is open-ended by design. Confirm whether to add a dev-mode warning for unsupported content types when `swc-action-button` and `swc-switch` are available, or leave fully unrestricted. |
+| **`RadioController`** scope | Ship **inside** `AccordionBase` first vs extract to **core** for **radio group**, **`role=”menuitemradio”`** menus, **tabs**, and/or coordinate with a **refactor** of **`FocusgroupNavigationController`** (split “selection flags” vs “focus roving”)? **Depends on** menu / radio / tabs migration timing and whether teams want one shared **selection-sync** API vs local loops per component. |
 
 **Not a blocker:** Missing 2nd-gen package before implementation starts is expected.
 
@@ -370,7 +379,6 @@ Gates align with [01_washing-machine-workflow.md](../../02_workstreams/02_2nd-ge
 - [Washing machine workflow](../../02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md)
 - [Migration project planning (epics / tickets)](../../02_workstreams/02_2nd-gen-component-migration/03_migration-project-planning.md)
 - [Accessibility migration analysis](./accessibility-migration-analysis.md)
-- [Rendering and styling migration analysis](./rendering-and-styling-migration-analysis.md)
 - [1st-gen source — `Accordion.ts`](../../../../1st-gen/packages/accordion/src/Accordion.ts)
 - [1st-gen source — `AccordionItem.ts`](../../../../1st-gen/packages/accordion/src/AccordionItem.ts)
 - [1st-gen tests directory](../../../../1st-gen/packages/accordion/test/)
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/rendering-and-styling-migration-analysis.md
deleted file mode 100644
index 5f32eaa712..0000000000
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/rendering-and-styling-migration-analysis.md
+++ /dev/null
@@ -1,225 +0,0 @@
-<!-- Generated breadcrumbs - DO NOT EDIT -->
-
-[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Components](../README.md) / Accordion / Accordion migration roadmap
-
-<!-- Document title (editable) -->
-
-# Accordion migration roadmap
-
-<!-- Generated TOC - DO NOT EDIT -->
-
-<details open>
-<summary><strong>In this doc</strong></summary>
-
-- [Component specifications](#component-specifications)
-    - [CSS (1st-gen / Spectrum 1)](#css-1st-gen--spectrum-1)
-    - [Figma — S2 Web (desktop scale)](#figma--s2-web-desktop-scale)
-    - [SWC (1st-gen)](#swc-1st-gen)
-- [Comparison](#comparison)
-    - [DOM structure changes](#dom-structure-changes)
-    - [CSS => SWC mapping](#css--swc-mapping)
-- [Summary of changes](#summary-of-changes)
-- [Resources](#resources)
-
-</details>
-
-<!-- Document content (editable) -->
-
-Spectrum 2 CSS-to-SWC migration notes for **`swc-accordion`** and **`swc-accordion-item`**. For accessibility behavior (APG accordion pattern, headings, keyboard), see [Accordion accessibility migration analysis](./accessibility-migration-analysis.md).
-
-**Status:** Phase 1 prep — 1st-gen inventory captured below. **Next:** With **spectrum-css** checked out on **`spectrum-two`** beside this repo, complete selector extraction from component `metadata.json`, three-way DOM comparison, and token mapping per [Analyze rendering and styling](../../02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md).
-
----
-
-## Component specifications
-
-### CSS (1st-gen / Spectrum 1)
-
-1st-gen packages import generated Spectrum CSS:
-
-- [`1st-gen/packages/accordion/src/spectrum-accordion.css`](../../../../1st-gen/packages/accordion/src/spectrum-accordion.css) — host tokens, size/density variants, `--spectrum-logical-rotation` for disclosure.
-- [`1st-gen/packages/accordion/src/spectrum-accordion-item.css`](../../../../1st-gen/packages/accordion/src/spectrum-accordion-item.css) — `:host`, `#heading`, `#header`, `#content`, `.iconContainer`, state variants (`[open]`, `[disabled]`, hover, focus-visible).
-
-<details>
-<summary>Modifier highlights (`--mod-*` / `--spectrum-accordion-*`)</summary>
-
-Representative tokens consumed in 1st-gen (not exhaustive — extract full list from Spectrum CSS when completing this doc):
-
-- `--mod-accordion-item-width`, `--mod-accordion-item-height`, `--mod-accordion-min-block-size`
-- `--mod-accordion-divider-color`, `--mod-accordion-divider-thickness`
-- `--mod-accordion-disclosure-indicator-height`, `--mod-accordion-edge-to-disclosure-indicator-space`, `--mod-accordion-disclosure-indicator-to-text-space`, `--mod-accordion-edge-to-text-space`
-- `--mod-accordion-item-header-*` (padding, font, line-height, colors)
-- `--mod-accordion-item-content-*` (padding, font, color)
-- `--mod-accordion-background-color-*`, `--mod-accordion-corner-radius`, `--mod-accordion-focus-indicator-*`
-- System overrides in [`accordion-overrides.css`](../../../../1st-gen/packages/accordion/src/accordion-overrides.css)
-
-</details>
-
-**TBD (Spectrum 2):** Mirror this section from `spectrum-css` **`spectrum-two`** accordion component (`metadata.json`, `index.css`, stories template) when the sibling checkout is available. Use [Figma — S2 Web (desktop scale)](#figma--s2-web-desktop-scale) below as the **design** source until that extraction is complete; reconcile any delta with `metadata.json` line by line (do not assume Figma and CSS stay in lockstep without verification).
-
-### Figma — S2 Web (desktop scale)
-
-**Canonical link (dev mode):** [S2 — Web (Desktop scale) — Accordion](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Web--Desktop-scale-?node-id=39469-5419&p=f&m=dev) (`node-id=39469-5419`).
-
-The following is transcribed from the **published Accordion** page in that file (export reviewed May 2025; doc stamp **Last updated May 16, 2025** / Kami F.). Treat Figma as **visual and variant inventory**; **coded** selectors and tokens still come from **spectrum-css** `spectrum-two` when available.
-
-#### Definition
-
-An accordion shows a list of items that can be expanded or collapsed to reveal more content. The pattern can support **zero, one, or multiple** expanded items at a time (aligns quantity-of-open with product API such as [`allowsMultipleExpanded`](https://react-spectrum.adobe.com/Accordion), not with “quiet vs default” styling).
-
-<details>
-<summary>Accordion (root) — properties in Figma</summary>
-
-| Figma property | Role (from doc copy) |
-|---|---|
-| **Quiet** | Boolean — change appearance / communication of status |
-| **Variant** | Variant control on the accordion set (see item matrix for spacing/style family) |
-
-Figma defaults shown in the property table include **Quiet = False** for the accordion-level control where listed.
-
-</details>
-
-<details>
-<summary>Accordion item — properties in Figma</summary>
-
-| Figma property | Role (from doc copy) |
-|---|---|
-| **State** | **Open** (and interactive states shown in grids — **Hover**, **Down**, **Disabled**) |
-| **Quiet** | Boolean — aligns with accordion “quiet” visual family |
-| **Density** | **Compact**, **Regular**, **Spacious** — “change density” between items |
-| **Show paddings** | Toggle — show/hide padding guides (design-tool only; corresponds to **no inline padding** style in Spectrum CSS — **not** a public SWC prop) |
-| **Show direct actions** | Toggle — show/hide **direct actions** region (optional chrome next to title) |
-| **Show switch** | Toggle — show/hide **switch** in the header row |
-| **Show action button** | Toggle — show/hide **action button** |
-| **@ Title** | Text — title string |
-| **Instance swap** | Local component swaps where applicable |
-
-**Migration implication:** Optional header affordances (**direct actions**, **switch**, **action button**) match the direction of richer headers in React Spectrum S2 (**`AccordionItemHeader`**, action controls). 1st-gen SWC uses a single header label + chevron only; **2nd-gen** may need **named slots** or internal structure once S2 template and a11y review land (see [migration plan](./migration-plan.md) and [accessibility analysis](./accessibility-migration-analysis.md)).
-
-**Density note:** Figma places **Density** on the **item** component with three steps (**Compact** / **Regular** / **Spacious**). 1st-gen reflects **`density`** on **`sp-accordion`** only (`compact` \| `spacious` \| unset). Reconcile host vs item during Step 1 when comparing `metadata.json` to this file — [migration plan — `density`](./migration-plan.md#public-api) defines reflected **`regular`** and full typing parity with React Spectrum.
-
-**Show paddings:** Treat as documentation and **CSS custom-property** coverage only ([migration plan](./migration-plan.md) — spacing overrides + a dedicated Storybook story, **no** component attribute).
-
-</details>
-
-<details>
-<summary>Sizes, states, and styles (Figma matrices)</summary>
-
-- **Sizes:** **S**, **M**, **L**, **XL** (maps to existing SWC **`size`** scale).
-- **States (interactive):** **Default**, **Hover**, **Down**, **Disabled** across the published grids.
-- **Style families:** **Default** vs **Quiet**, crossed with **open/closed** and **density** rows (**Compact**, **Regular**, **Spacious**) in the canvases.
-
-**Figma caveat:** Keyboard **focus** state is **not** represented in the file; the spec points authors to Spectrum **coded** components and site docs for focus treatment.
-
-</details>
-
-#### Usage guidelines (from Figma — do not mix)
-
-- **Do not mix default and quiet accordion items inside one accordion.** Default accordions must not contain quiet items, and quiet accordions must not contain default items — the doc states this avoids **conflicting interaction behaviors**.
-- **Quiet hover and dividers:** The quiet accordion item hover state uses **rounded corners**. Using that inside a **default** accordion (with dividers) produces **gaps at corners** that the default divider treatment does not fill; only **keyboard focus** outline is expected to read similarly against dividers. **Prefer one style family per accordion** for both UX and markup/CSS predictability.
-
-This reinforces **accordion-wide `quiet`** (and consistent items) as the primary authoring model for 2nd-gen; avoid advertising **per-item `quiet`** that could violate this guidance unless Spectrum explicitly documents an exception ([migration plan](./migration-plan.md)).
-
-### SWC (1st-gen)
-
-<details>
-<summary>Attributes / properties (`sp-accordion`)</summary>
-
-- `allow-multiple` (boolean)
-- `density` (`compact` | `spacious`)
-- `level` (number, default 3)
-- `size` (`s` | `m` | `l` | `xl`)
-
-</details>
-
-<details>
-<summary>Attributes / properties (`sp-accordion-item`)</summary>
-
-- `open` (boolean)
-- `label` (string)
-- `disabled` (boolean)
-- `level` (number — overwritten by parent when slotted)
-- `size` (from parent)
-
-</details>
-
-<details>
-<summary>Slots</summary>
-
-- **`sp-accordion`:** default — `sp-accordion-item` children.
-- **`sp-accordion-item`:** default — panel body.
-
-</details>
-
-<details>
-<summary>Nested components / assets</summary>
-
-- 1st-gen: `sp-icon-chevron100` from `@spectrum-web-components/icons-ui` and chevron styles from `@spectrum-web-components/icon`
-- 2nd-gen: prefer **`swc-icon`** internally for the disclosure indicator ([migration plan](./migration-plan.md))
-
-</details>
-
----
-
-## Comparison
-
-### DOM structure changes
-
-<details>
-<summary>Spectrum Web Components (1st-gen `AccordionItem`)</summary>
-
-Conceptual shadow output:
-
-```html
-<h2 id="heading">
-  <!-- optional: .iconContainer + sp-icon-chevron100 -->
-  <button id="header" aria-expanded="..." aria-controls="content">...</button>
-</h2>
-<div id="content" role="region" aria-labelledby="header">
-  <slot></slot>
-</div>
-```
-
-**`sp-accordion`:** single default `<slot>`; parent coordinates items via events and assigned nodes.
-
-</details>
-
-<details>
-<summary>Spectrum 2 (TBD — CSS template)</summary>
-
-Paste or link the S2 template markup from **spectrum-css** `spectrum-two` when available. Compare heading/button/slot structure and class names to the above.
-
-**Design reference (until template is pasted):** [Figma — S2 Web (desktop scale)](#figma--s2-web-desktop-scale) — sizes **S–XL**, **Default/Quiet**, **Compact/Regular/Spacious** density, optional header actions/switch/button, and **do-not-mix** quiet vs default usage.
-
-</details>
-
-### CSS => SWC mapping
-
-**TBD.** Populate during Step 1 QA: map S2 selectors and `--mod-*` successors to 2nd-gen host parts, internal nodes, and any supported `--swc-accordion-*` surface per [component custom property exposure](../../../02_style-guide/01_css/02_custom-properties.md#component-custom-property-exposure).
-
----
-
-## Summary of changes
-
-| Area | 1st-gen today | 2nd-gen direction (high level) |
-|---|---|---|
-| Styling source | Spectrum 1 generated CSS in package | Spectrum 2 tokens from **spectrum-css** `spectrum-two`; narrow public customization. |
-| DOM | `#heading` / `#header` / `#content`, optional chevron wrapper | Align with S2 template; preserve APG shape from [accessibility migration analysis](./accessibility-migration-analysis.md). |
-| Quiet vs default | No `quiet` on accordion or item | **Figma / S2:** accordion-level **Quiet** and item-level quiet must **not** be mixed with the opposite style inside one accordion ([Figma section](#figma--s2-web-desktop-scale)). Implement **`quiet`** as a single family per instance ([migration plan](./migration-plan.md)). |
-| Header chrome | Title + chevron only | **Figma** shows optional **direct actions**, **switch**, **action button** toggles — likely **slots** or subregions; align with [React Spectrum `AccordionItemHeader`](https://react-spectrum.adobe.com/Accordion) when scoping Phase 5/7. |
-| Density / size | `density` + `size` on accordion, chevron scales by size | **Figma** item **Density:** **Compact** / **Regular** / **Spacious**; sizes **S–XL**. Reconcile host vs item propagation with `metadata.json` + [migration plan `density`](./migration-plan.md#public-api). |
-| States | `open`, `disabled`, hover/focus in CSS | Match **Default / Hover / Down / Disabled** from Figma; **focus-visible** not in Figma — follow APG + [accessibility analysis](./accessibility-migration-analysis.md). |
-| Custom properties | Broad `--spectrum-accordion-*` / `--mod-*` | Replace with S2 equivalents; document breaking token renames in [migration plan](./migration-plan.md). |
-
----
-
-## Resources
-
-| Resource | Link |
-|---|---|
-| Figma — S2 Web (Desktop scale), Accordion | [figma.com/design/Mngz9H7WZLbrCvGQf3GnsY](https://www.figma.com/design/Mngz9H7WZLbrCvGQf3GnsY/S2---Web--Desktop-scale-?node-id=39469-5419&p=f&m=dev) |
-| 1st-gen accordion package | [`1st-gen/packages/accordion/`](../../../../1st-gen/packages/accordion/) |
-| Migration plan | [migration-plan.md](./migration-plan.md) |
-| Accessibility analysis | [accessibility-migration-analysis.md](./accessibility-migration-analysis.md) |
-| Analyze rendering and styling (workflow) | [README](../../02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md) |
-| Spectrum CSS (external) | [github.com/adobe/spectrum-css](https://github.com/adobe/spectrum-css) — use **`spectrum-two`** branch |

From 09cd821f13ce48cc20589509f4fc41d7b6ca2f8b Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:40:56 -0500
Subject: [PATCH 02/56] chore: scaffold core package

---
 .../components/accordion/Accordion.types.ts   | 19 +++++++++++++++++++
 .../components/accordion/AccordionBase.ts     | 15 +++++++++++++++
 .../accordion/AccordionItem.types.ts          | 13 +++++++++++++
 .../components/accordion/AccordionItemBase.ts | 15 +++++++++++++++
 .../core/components/accordion/index.ts        | 15 +++++++++++++++
 5 files changed, 77 insertions(+)
 create mode 100644 2nd-gen/packages/core/components/accordion/Accordion.types.ts
 create mode 100644 2nd-gen/packages/core/components/accordion/AccordionBase.ts
 create mode 100644 2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
 create mode 100644 2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
 create mode 100644 2nd-gen/packages/core/components/accordion/index.ts

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.types.ts b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
new file mode 100644
index 0000000000..44b0aba7eb
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
@@ -0,0 +1,19 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export const ACCORDION_VALID_SIZES = ['s', 'm', 'l', 'xl'] as const;
+export type AccordionSize = (typeof ACCORDION_VALID_SIZES)[number];
+
+export const ACCORDION_DENSITIES = ['compact', 'regular', 'spacious'] as const;
+export type AccordionDensity = (typeof ACCORDION_DENSITIES)[number];
+
+export const SWC_ACCORDION_ITEM_TOGGLE_EVENT = 'swc-accordion-item-toggle';
diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
new file mode 100644
index 0000000000..3b35a08de9
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -0,0 +1,15 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
+
+export abstract class AccordionBase extends SpectrumElement {}
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
new file mode 100644
index 0000000000..349458211e
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
@@ -0,0 +1,13 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Item-specific types go here as the accordion item API is defined in subsequent commits.
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
new file mode 100644
index 0000000000..5d2a344f87
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -0,0 +1,15 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
+
+export abstract class AccordionItemBase extends SpectrumElement {}
diff --git a/2nd-gen/packages/core/components/accordion/index.ts b/2nd-gen/packages/core/components/accordion/index.ts
new file mode 100644
index 0000000000..a725fdc5fe
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/index.ts
@@ -0,0 +1,15 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export * from './AccordionBase.js';
+export * from './AccordionItemBase.js';
+export * from './Accordion.types.js';

From bba2e18c90056a0a95d0e79adb1f8acd3cb1d4cf Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:48:07 -0500
Subject: [PATCH 03/56] chore: scaffold swc package

---
 .../swc/components/accordion/Accordion.ts     | 38 +++++++++++++++++++
 .../swc/components/accordion/AccordionItem.ts | 36 ++++++++++++++++++
 .../swc/components/accordion/accordion.css    | 13 +++++++
 .../swc/components/accordion/index.ts         | 14 +++++++
 .../accordion/swc-accordion-item.ts           | 23 +++++++++++
 .../swc/components/accordion/swc-accordion.ts | 23 +++++++++++
 6 files changed, 147 insertions(+)
 create mode 100644 2nd-gen/packages/swc/components/accordion/Accordion.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/AccordionItem.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/accordion.css
 create mode 100644 2nd-gen/packages/swc/components/accordion/index.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/swc-accordion-item.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/swc-accordion.ts

diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
new file mode 100644
index 0000000000..3f15bb156e
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -0,0 +1,38 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { CSSResultArray, html, TemplateResult } from 'lit';
+
+import { AccordionBase } from '@spectrum-web-components/core/components/accordion';
+
+import styles from './accordion.css';
+
+/**
+ * An accordion component that groups expandable content sections.
+ *
+ * @element swc-accordion
+ * @since 2.0.0
+ *
+ * @example
+ * <swc-accordion>
+ *   <swc-accordion-item>Content</swc-accordion-item>
+ * </swc-accordion>
+ */
+export class Accordion extends AccordionBase {
+  public static override get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  protected override render(): TemplateResult {
+    return html``;
+  }
+}
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
new file mode 100644
index 0000000000..b59479c7ae
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -0,0 +1,36 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { CSSResultArray, html, TemplateResult } from 'lit';
+
+import { AccordionItemBase } from '@spectrum-web-components/core/components/accordion';
+
+import styles from './accordion.css';
+
+/**
+ * An accordion item component that wraps a single expandable content section.
+ *
+ * @element swc-accordion-item
+ * @since 2.0.0
+ *
+ * @example
+ * <swc-accordion-item>Content</swc-accordion-item>
+ */
+export class AccordionItem extends AccordionItemBase {
+  public static override get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  protected override render(): TemplateResult {
+    return html``;
+  }
+}
diff --git a/2nd-gen/packages/swc/components/accordion/accordion.css b/2nd-gen/packages/swc/components/accordion/accordion.css
new file mode 100644
index 0000000000..40f33594a2
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/accordion.css
@@ -0,0 +1,13 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/* S2 token imports and selector definitions land here in Phase 4. */
diff --git a/2nd-gen/packages/swc/components/accordion/index.ts b/2nd-gen/packages/swc/components/accordion/index.ts
new file mode 100644
index 0000000000..f8f7131062
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/index.ts
@@ -0,0 +1,14 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export * from './Accordion.js';
+export * from './AccordionItem.js';
diff --git a/2nd-gen/packages/swc/components/accordion/swc-accordion-item.ts b/2nd-gen/packages/swc/components/accordion/swc-accordion-item.ts
new file mode 100644
index 0000000000..cd9853027e
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/swc-accordion-item.ts
@@ -0,0 +1,23 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { defineElement } from '@spectrum-web-components/core/element/index.js';
+
+import { AccordionItem } from './AccordionItem.js';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'swc-accordion-item': AccordionItem;
+  }
+}
+
+defineElement('swc-accordion-item', AccordionItem);
diff --git a/2nd-gen/packages/swc/components/accordion/swc-accordion.ts b/2nd-gen/packages/swc/components/accordion/swc-accordion.ts
new file mode 100644
index 0000000000..d51f7f1b1e
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/swc-accordion.ts
@@ -0,0 +1,23 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { defineElement } from '@spectrum-web-components/core/element/index.js';
+
+import { Accordion } from './Accordion.js';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'swc-accordion': Accordion;
+  }
+}
+
+defineElement('swc-accordion', Accordion);

From 87bdc5e9ae0d18701ca97108b84f98aa6bcd403c Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:54:09 -0500
Subject: [PATCH 04/56] chore: add Chevron300Icon for xl accordion

---
 .../icon/elements/Chevron300Icon.ts           | 22 +++++++++++++++++++
 .../swc/components/icon/elements/index.ts     |  1 +
 2 files changed, 23 insertions(+)
 create mode 100644 2nd-gen/packages/swc/components/icon/elements/Chevron300Icon.ts

diff --git a/2nd-gen/packages/swc/components/icon/elements/Chevron300Icon.ts b/2nd-gen/packages/swc/components/icon/elements/Chevron300Icon.ts
new file mode 100644
index 0000000000..72956bf4b1
--- /dev/null
+++ b/2nd-gen/packages/swc/components/icon/elements/Chevron300Icon.ts
@@ -0,0 +1,22 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { html, TemplateResult } from 'lit';
+
+export const Chevron300Icon = (): TemplateResult => {
+  return html`
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 14">
+      <path
+        d="M10.639 7a.95.95 0 0 0-.278-.671l-.003-.002-5.33-5.33a.95.95 0 0 0-1.342 1.342L8.346 7l-4.661 4.66a.95.95 0 1 0 1.342 1.343l5.33-5.33.003-.001A.95.95 0 0 0 10.64 7z"
+      />
+    </svg>
+  `;
+};
diff --git a/2nd-gen/packages/swc/components/icon/elements/index.ts b/2nd-gen/packages/swc/components/icon/elements/index.ts
index b30f66ddd2..8d6cf638b2 100644
--- a/2nd-gen/packages/swc/components/icon/elements/index.ts
+++ b/2nd-gen/packages/swc/components/icon/elements/index.ts
@@ -20,6 +20,7 @@ export * from './Chevron50Icon.js';
 export * from './Chevron75Icon.js';
 export * from './Chevron100Icon.js';
 export * from './Chevron200Icon.js';
+export * from './Chevron300Icon.js';
 export * from './CornerTriangle300Icon.js';
 export * from './Cross75Icon.js';
 export * from './Cross100Icon.js';

From 570c1381b74ce1e335bd207a75618c090e5f087e Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:58:12 -0500
Subject: [PATCH 05/56] chore: set up storybook story

---
 .../accordion/stories/accordion.stories.ts    | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts

diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
new file mode 100644
index 0000000000..a6f2c6bb15
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -0,0 +1,65 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { html } from 'lit';
+import type { Meta, StoryObj as Story } from '@storybook/web-components';
+
+import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
+import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
+
+// ────────────────
+//    METADATA
+// ────────────────
+
+/**
+ * An accordion groups related content sections, each behind a header that can
+ * be expanded or collapsed. Args, argTypes, and controls are added in a later commit
+ * once the component API is defined.
+ */
+const meta: Meta = {
+  title: 'Accordion',
+  component: 'swc-accordion',
+  parameters: {
+    docs: {
+      subtitle: 'Groups related content sections behind expandable headers.',
+    },
+  },
+  tags: ['migrated'],
+};
+
+export default meta;
+
+// ────────────────────
+//    AUTODOCS STORY
+// ────────────────────
+
+export const Playground: Story = {
+  render: () => html`
+    <swc-accordion>
+      <swc-accordion-item>Sample content</swc-accordion-item>
+    </swc-accordion>
+  `,
+  tags: ['autodocs', 'dev'],
+};
+
+// ──────────────────────────
+//    OVERVIEW STORY
+// ──────────────────────────
+
+export const Overview: Story = {
+  render: () => html`
+    <swc-accordion>
+      <swc-accordion-item>Sample content</swc-accordion-item>
+    </swc-accordion>
+  `,
+  tags: ['overview'],
+};

From 6e71c8db2f2fb162f2b72ce7e2bc79544ee76234 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:58:31 -0500
Subject: [PATCH 06/56] chore: commit preview.ts updates

---
 2nd-gen/packages/swc/.storybook/preview.ts | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts
index 66d2cc73e7..4d0ec66f80 100644
--- a/2nd-gen/packages/swc/.storybook/preview.ts
+++ b/2nd-gen/packages/swc/.storybook/preview.ts
@@ -321,11 +321,7 @@ const preview = {
               'Components',
               [
                 'Accordion',
-                [
-                  'Accessibility migration analysis',
-                  'Migration plan',
-                  'Rendering and styling migration analysis',
-                ],
+                ['Accessibility migration analysis', 'Migration plan'],
                 'Action button',
                 ['Rendering and styling migration analysis'],
                 'Action group',

From bc7bf870daba2a71c8f2cbf7edd73e3f425663c4 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 17:12:40 -0500
Subject: [PATCH 07/56] feat: implement AccordionItem API and render template

---
 .../components/accordion/AccordionItemBase.ts | 73 +++++++++++++++++-
 .../swc/components/accordion/AccordionItem.ts | 77 ++++++++++++++++++-
 2 files changed, 147 insertions(+), 3 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
index 5d2a344f87..3aa2f07483 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -10,6 +10,77 @@
  * governing permissions and limitations under the License.
  */
 
+import { property } from 'lit/decorators.js';
+
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
 
-export abstract class AccordionItemBase extends SpectrumElement {}
+import {
+  type AccordionSize,
+  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+} from './Accordion.types.js';
+
+/**
+ * Base class for accordion item components. Manages open/disabled state,
+ * heading level (set by the parent accordion), and the toggle event.
+ *
+ * @slot label - The heading text for this accordion item.
+ * @slot actions - Optional actions rendered adjacent to the heading, outside
+ *   the toggle button so they remain independently interactive.
+ * @slot - The panel content revealed when the item is open.
+ */
+export abstract class AccordionItemBase extends SpectrumElement {
+  // ──────────────────
+  //     PUBLIC API
+  // ──────────────────
+
+  /**
+   * Whether the accordion item panel is expanded.
+   */
+  @property({ type: Boolean, reflect: true })
+  public open: boolean = false;
+
+  /**
+   * Whether the accordion item is disabled. A disabled item keeps its header
+   * in the tab order but blocks toggling.
+   */
+  @property({ type: Boolean, reflect: true })
+  public disabled: boolean = false;
+
+  /**
+   * The size of the item. Inherited from the parent accordion; controls which
+   * chevron icon is displayed. Has no effect when the item is used standalone.
+   */
+  @property({ type: String, reflect: true })
+  public size?: AccordionSize;
+
+  // ──────────────────────
+  //     INTERNAL STATE
+  // ──────────────────────
+
+  /**
+   * @internal
+   * Heading level (2–6) propagated by the parent accordion. Defaults to 3
+   * for standalone items. Used by the concrete render() to emit the correct
+   * <h*> element; made reactive in a later commit.
+   */
+  protected heading: number = 3;
+
+  // ──────────────────────
+  //     IMPLEMENTATION
+  // ──────────────────────
+
+  /**
+   * @internal
+   * Dispatches the toggle event. The concrete class wires this to the
+   * header button's click handler and adds open-state management.
+   */
+  protected toggle(): void {
+    this.dispatchEvent(
+      new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+  }
+}
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index b59479c7ae..61cd39872c 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -14,6 +14,13 @@ import { CSSResultArray, html, TemplateResult } from 'lit';
 
 import { AccordionItemBase } from '@spectrum-web-components/core/components/accordion';
 
+import '../icon/swc-icon.js';
+
+import { Chevron75Icon } from '../icon/elements/Chevron75Icon.js';
+import { Chevron100Icon } from '../icon/elements/Chevron100Icon.js';
+import { Chevron200Icon } from '../icon/elements/Chevron200Icon.js';
+import { Chevron300Icon } from '../icon/elements/Chevron300Icon.js';
+
 import styles from './accordion.css';
 
 /**
@@ -23,14 +30,80 @@ import styles from './accordion.css';
  * @since 2.0.0
  *
  * @example
- * <swc-accordion-item>Content</swc-accordion-item>
+ * <swc-accordion-item>
+ *   <span slot="label">Section heading</span>
+ *   Panel content goes here.
+ * </swc-accordion-item>
  */
 export class AccordionItem extends AccordionItemBase {
+  // ──────────────────────────────
+  //     RENDERING & STYLING
+  // ──────────────────────────────
+
   public static override get styles(): CSSResultArray {
     return [styles];
   }
 
+  private chevronForSize(): TemplateResult {
+    switch (this.size) {
+      case 's':
+        return Chevron75Icon();
+      case 'l':
+        return Chevron200Icon();
+      case 'xl':
+        return Chevron300Icon();
+      case 'm':
+      default:
+        return Chevron100Icon();
+    }
+  }
+
+  private handleActionsSlotChange(event: Event): void {
+    const slot = event.target as HTMLSlotElement;
+    const container = slot.parentElement as HTMLElement | null;
+    if (container) {
+      container.hidden = slot.assignedNodes({ flatten: true }).length === 0;
+    }
+  }
+
+  private handleActionsContainerInteraction(event: Event): void {
+    event.stopPropagation();
+  }
+
   protected override render(): TemplateResult {
-    return html``;
+    // <h3> is a static stub; the heading level becomes dynamic in a later commit.
+    return html`
+      <h3>
+        <button
+          id="header"
+          type="button"
+          aria-expanded="false"
+          aria-controls="content"
+        >
+          <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
+            ${this.chevronForSize()}
+          </swc-icon>
+          <span class="spectrum-Accordion-itemTitle">
+            <slot name="label"></slot>
+          </span>
+        </button>
+      </h3>
+      <div
+        class="spectrum-Accordion-itemDirectActions"
+        hidden
+        @click=${this.handleActionsContainerInteraction}
+        @keydown=${this.handleActionsContainerInteraction}
+      >
+        <slot name="actions" @slotchange=${this.handleActionsSlotChange}></slot>
+      </div>
+      <div
+        id="content"
+        class="spectrum-Accordion-itemContent"
+        role="region"
+        aria-labelledby="header"
+      >
+        <slot></slot>
+      </div>
+    `;
   }
 }

From f94b6ce650218fcc701ae3c5cd1613e48538e582 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 08:10:12 -0500
Subject: [PATCH 08/56] feat: implement Accordion API and propagation

---
 .../components/accordion/AccordionBase.ts     | 112 +++++++++++++++++-
 .../components/accordion/AccordionItemBase.ts |   5 +-
 .../swc/components/accordion/Accordion.ts     |  13 +-
 3 files changed, 120 insertions(+), 10 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
index 3b35a08de9..9d7521f595 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -10,6 +10,116 @@
  * governing permissions and limitations under the License.
  */
 
+import { html, PropertyValues, TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
 
-export abstract class AccordionBase extends SpectrumElement {}
+import {
+  type AccordionDensity,
+  type AccordionSize,
+} from './Accordion.types.js';
+import { AccordionItemBase } from './AccordionItemBase.js';
+
+/**
+ * Base class for accordion components. Manages item propagation, heading
+ * level, density, and the exclusive-open constraint.
+ *
+ * @slot - One or more `swc-accordion-item` elements.
+ */
+export abstract class AccordionBase extends SpectrumElement {
+  // ──────────────────
+  //     PUBLIC API
+  // ──────────────────
+
+  /**
+   * When set, multiple items may be open at the same time. By default only
+   * one item can be open.
+   */
+  @property({ type: Boolean, reflect: true, attribute: 'allow-multiple' })
+  public allowMultiple: boolean = false;
+
+  /**
+   * Heading level applied to every item header (2–6). Defaults to 3.
+   * Values outside that range are clamped.
+   */
+  @property({ type: Number, reflect: true })
+  public level: number = 3;
+
+  /**
+   * Size applied to all items. When set, overrides any size set on individual
+   * items.
+   */
+  @property({ type: String, reflect: true })
+  public size?: AccordionSize;
+
+  /**
+   * Controls vertical spacing between items.
+   *
+   * @default regular
+   */
+  @property({ type: String, reflect: true })
+  public density: AccordionDensity = 'regular';
+
+  /**
+   * Renders the accordion in its quiet (no-border) visual variant.
+   */
+  @property({ type: Boolean, reflect: true })
+  public quiet: boolean = false;
+
+  /**
+   * Disables all items in the accordion. Individual items may also be
+   * disabled independently.
+   */
+  @property({ type: Boolean, reflect: true })
+  public disabled: boolean = false;
+
+  // ──────────────────────
+  //     IMPLEMENTATION
+  // ──────────────────────
+
+  private updateItems(): void {
+    const slot = this.shadowRoot?.querySelector('slot');
+    if (!slot) {
+      return;
+    }
+    const items = slot
+      .assignedElements({ flatten: true })
+      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
+    for (const item of items) {
+      item.heading = this.level;
+      item.size = this.size;
+    }
+  }
+
+  protected override update(changedProperties: PropertyValues): void {
+    if (changedProperties.has('level')) {
+      const clamped = Math.min(6, Math.max(2, this.level));
+      if (this.level !== clamped) {
+        this.level = clamped;
+      }
+    }
+    if (changedProperties.has('level') || changedProperties.has('size')) {
+      this.updateItems();
+    }
+    super.update(changedProperties);
+  }
+
+  protected override firstUpdated(changedProperties: PropertyValues): void {
+    super.firstUpdated(changedProperties);
+    if (window.__swc?.DEBUG && !this.hasAttribute('density')) {
+      window.__swc.warn(
+        this,
+        `<${this.localName}> should have an explicit "density" attribute set. Defaulting to "regular", which corresponds to the 1st-gen default.`,
+        'https://opensource.adobe.com/spectrum-web-components/components/accordion/',
+        { type: 'api', level: 'low' }
+      );
+    }
+  }
+
+  protected override render(): TemplateResult {
+    return html`
+      <slot @slotchange=${this.updateItems}></slot>
+    `;
+  }
+}
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
index 3aa2f07483..f13a014039 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -61,9 +61,10 @@ export abstract class AccordionItemBase extends SpectrumElement {
    * @internal
    * Heading level (2–6) propagated by the parent accordion. Defaults to 3
    * for standalone items. Used by the concrete render() to emit the correct
-   * <h*> element; made reactive in a later commit.
+   * <h*> element; made reactive in a later commit. Public so AccordionBase
+   * can write to instances without a type assertion.
    */
-  protected heading: number = 3;
+  public heading: number = 3;
 
   // ──────────────────────
   //     IMPLEMENTATION
diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
index 3f15bb156e..f89f575f90 100644
--- a/2nd-gen/packages/swc/components/accordion/Accordion.ts
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { CSSResultArray, html, TemplateResult } from 'lit';
+import { CSSResultArray } from 'lit';
 
 import { AccordionBase } from '@spectrum-web-components/core/components/accordion';
 
@@ -23,16 +23,15 @@ import styles from './accordion.css';
  * @since 2.0.0
  *
  * @example
- * <swc-accordion>
- *   <swc-accordion-item>Content</swc-accordion-item>
+ * <swc-accordion density="regular">
+ *   <swc-accordion-item>
+ *     <span slot="label">Section heading</span>
+ *     Panel content goes here.
+ *   </swc-accordion-item>
  * </swc-accordion>
  */
 export class Accordion extends AccordionBase {
   public static override get styles(): CSSResultArray {
     return [styles];
   }
-
-  protected override render(): TemplateResult {
-    return html``;
-  }
 }

From 3a4454bfed348f60b23af1efb5f7c9478ff6b2dc Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 09:56:59 -0500
Subject: [PATCH 09/56] feat: implement open and toggle logic

---
 .../components/accordion/AccordionBase.ts     | 43 ++++++++++
 .../swc/components/accordion/AccordionItem.ts | 45 +++++++++-
 .../accordion/stories/accordion.stories.ts    | 86 ++++++++++++++++---
 3 files changed, 159 insertions(+), 15 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
index 9d7521f595..7692e48d45 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -18,6 +18,7 @@ import { SpectrumElement } from '@spectrum-web-components/core/element/index.js'
 import {
   type AccordionDensity,
   type AccordionSize,
+  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
 } from './Accordion.types.js';
 import { AccordionItemBase } from './AccordionItemBase.js';
 
@@ -78,6 +79,32 @@ export abstract class AccordionBase extends SpectrumElement {
   //     IMPLEMENTATION
   // ──────────────────────
 
+  private handleItemToggle = (event: Event): void => {
+    if (this.disabled) {
+      event.preventDefault();
+      return;
+    }
+    if (this.allowMultiple) {
+      return;
+    }
+    const toggling = event.target;
+    if (!(toggling instanceof AccordionItemBase) || !toggling.open) {
+      return;
+    }
+    const slot = this.shadowRoot?.querySelector('slot');
+    if (!slot) {
+      return;
+    }
+    const items = slot
+      .assignedElements({ flatten: true })
+      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
+    for (const item of items) {
+      if (item !== toggling) {
+        item.open = false;
+      }
+    }
+  };
+
   private updateItems(): void {
     const slot = this.shadowRoot?.querySelector('slot');
     if (!slot) {
@@ -92,6 +119,22 @@ export abstract class AccordionBase extends SpectrumElement {
     }
   }
 
+  public override connectedCallback(): void {
+    super.connectedCallback();
+    this.addEventListener(
+      SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+      this.handleItemToggle
+    );
+  }
+
+  public override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.removeEventListener(
+      SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+      this.handleItemToggle
+    );
+  }
+
   protected override update(changedProperties: PropertyValues): void {
     if (changedProperties.has('level')) {
       const clamped = Math.min(6, Math.max(2, this.level));
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 61cd39872c..293a883ec1 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -12,7 +12,10 @@
 
 import { CSSResultArray, html, TemplateResult } from 'lit';
 
-import { AccordionItemBase } from '@spectrum-web-components/core/components/accordion';
+import {
+  AccordionItemBase,
+  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+} from '@spectrum-web-components/core/components/accordion';
 
 import '../icon/swc-icon.js';
 
@@ -37,13 +40,48 @@ import styles from './accordion.css';
  */
 export class AccordionItem extends AccordionItemBase {
   // ──────────────────────────────
-  //     RENDERING & STYLING
+  //     STYLING
   // ──────────────────────────────
 
   public static override get styles(): CSSResultArray {
     return [styles];
   }
 
+  // ──────────────────────────────
+  //     DELEGATION
+  // ──────────────────────────────
+
+  public override focus(options?: FocusOptions): void {
+    this.shadowRoot?.getElementById('header')?.focus(options);
+  }
+
+  public override click(): void {
+    this.shadowRoot?.getElementById('header')?.click();
+  }
+
+  // ──────────────────────────────
+  //     TOGGLE BEHAVIOR
+  // ──────────────────────────────
+
+  protected override toggle(): void {
+    if (this.disabled) {
+      return;
+    }
+    this.open = !this.open;
+    const event = new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+    });
+    if (!this.dispatchEvent(event)) {
+      this.open = !this.open;
+    }
+  }
+
+  // ──────────────────────────────
+  //     RENDERING
+  // ──────────────────────────────
+
   private chevronForSize(): TemplateResult {
     switch (this.size) {
       case 's':
@@ -77,8 +115,9 @@ export class AccordionItem extends AccordionItemBase {
         <button
           id="header"
           type="button"
-          aria-expanded="false"
+          aria-expanded=${this.open ? 'true' : 'false'}
           aria-controls="content"
+          @click=${this.toggle}
         >
           <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
             ${this.chevronForSize()}
diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index a6f2c6bb15..4284e11925 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -12,23 +12,89 @@
 
 import { html } from 'lit';
 import type { Meta, StoryObj as Story } from '@storybook/web-components';
+import { getStorybookHelpers } from '@wc-toolkit/storybook-helpers';
 
 import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
 import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
 
+import {
+  ACCORDION_DENSITIES,
+  ACCORDION_VALID_SIZES,
+  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+} from '../../../../core/components/accordion/Accordion.types.js';
+
 // ────────────────
 //    METADATA
 // ────────────────
 
+const { args, argTypes, template } = getStorybookHelpers('swc-accordion');
+
+argTypes.density = {
+  ...argTypes.density,
+  control: { type: 'select' },
+  options: [...ACCORDION_DENSITIES],
+  table: {
+    ...argTypes.density?.table,
+    category: 'attributes',
+    defaultValue: { summary: 'regular' },
+  },
+};
+
+argTypes.size = {
+  ...argTypes.size,
+  control: { type: 'select' },
+  options: ['', ...ACCORDION_VALID_SIZES],
+  table: {
+    ...argTypes.size?.table,
+    category: 'attributes',
+  },
+};
+
+argTypes.level = {
+  ...argTypes.level,
+  control: { type: 'number', min: 2, max: 6 },
+  table: {
+    ...argTypes.level?.table,
+    category: 'attributes',
+    defaultValue: { summary: '3' },
+  },
+};
+
+const defaultItems = html`
+  <swc-accordion-item>
+    <span slot="label">Alchemy</span>
+    Alchemy is an ancient branch of natural philosophy, a philosophical and
+    protoscientific tradition that was historically practiced in China, India,
+    the Muslim world, and Europe.
+  </swc-accordion-item>
+  <swc-accordion-item>
+    <span slot="label">Astrology</span>
+    Astrology is a range of divinatory practices, recognized as pseudoscientific
+    since the 18th century, that propose that information about human affairs
+    and terrestrial events may be discerned by studying the apparent positions
+    of celestial objects.
+  </swc-accordion-item>
+  <swc-accordion-item open>
+    <span slot="label">Natural magic</span>
+    Natural magic in the context of early modern Europe was a branch of
+    philosophy that treated occult forces as resulting from natural causes, not
+    from divine or demonic intervention.
+  </swc-accordion-item>
+`;
+
 /**
  * An accordion groups related content sections, each behind a header that can
- * be expanded or collapsed. Args, argTypes, and controls are added in a later commit
- * once the component API is defined.
+ * be expanded or collapsed. Only one section is open at a time by default;
+ * set `allow-multiple` to let any number of sections be open simultaneously.
  */
 const meta: Meta = {
   title: 'Accordion',
   component: 'swc-accordion',
+  args,
+  argTypes,
+  render: (args) => template(args, defaultItems),
   parameters: {
+    actions: { handles: [SWC_ACCORDION_ITEM_TOGGLE_EVENT] },
     docs: {
       subtitle: 'Groups related content sections behind expandable headers.',
     },
@@ -43,11 +109,9 @@ export default meta;
 // ────────────────────
 
 export const Playground: Story = {
-  render: () => html`
-    <swc-accordion>
-      <swc-accordion-item>Sample content</swc-accordion-item>
-    </swc-accordion>
-  `,
+  args: {
+    density: 'regular',
+  },
   tags: ['autodocs', 'dev'],
 };
 
@@ -56,10 +120,8 @@ export const Playground: Story = {
 // ──────────────────────────
 
 export const Overview: Story = {
-  render: () => html`
-    <swc-accordion>
-      <swc-accordion-item>Sample content</swc-accordion-item>
-    </swc-accordion>
-  `,
+  args: {
+    density: 'regular',
+  },
   tags: ['overview'],
 };

From 16dc6899a632546bbeadadc537d1b7cfd46bb334 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 10:29:03 -0500
Subject: [PATCH 10/56] feat: wire up dynamic heading levels

---
 .../components/accordion/AccordionItemBase.ts |  8 +--
 .../swc/components/accordion/AccordionItem.ts | 59 +++++++++++++------
 2 files changed, 46 insertions(+), 21 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
index f13a014039..df9d859aef 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
 
@@ -60,10 +60,10 @@ export abstract class AccordionItemBase extends SpectrumElement {
   /**
    * @internal
    * Heading level (2–6) propagated by the parent accordion. Defaults to 3
-   * for standalone items. Used by the concrete render() to emit the correct
-   * <h*> element; made reactive in a later commit. Public so AccordionBase
-   * can write to instances without a type assertion.
+   * for standalone items. Public so AccordionBase can write to instances
+   * without a type assertion.
    */
+  @state()
   public heading: number = 3;
 
   // ──────────────────────
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 293a883ec1..0a299a8b83 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -108,25 +108,50 @@ export class AccordionItem extends AccordionItemBase {
     event.stopPropagation();
   }
 
+  private renderHeadingWrapper(content: TemplateResult): TemplateResult {
+    switch (this.heading) {
+      case 2:
+        return html`
+          <h2>${content}</h2>
+        `;
+      case 4:
+        return html`
+          <h4>${content}</h4>
+        `;
+      case 5:
+        return html`
+          <h5>${content}</h5>
+        `;
+      case 6:
+        return html`
+          <h6>${content}</h6>
+        `;
+      default:
+        return html`
+          <h3>${content}</h3>
+        `;
+    }
+  }
+
   protected override render(): TemplateResult {
-    // <h3> is a static stub; the heading level becomes dynamic in a later commit.
+    const button = html`
+      <button
+        id="header"
+        type="button"
+        aria-expanded=${this.open ? 'true' : 'false'}
+        aria-controls="content"
+        @click=${this.toggle}
+      >
+        <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
+          ${this.chevronForSize()}
+        </swc-icon>
+        <span class="spectrum-Accordion-itemTitle">
+          <slot name="label"></slot>
+        </span>
+      </button>
+    `;
     return html`
-      <h3>
-        <button
-          id="header"
-          type="button"
-          aria-expanded=${this.open ? 'true' : 'false'}
-          aria-controls="content"
-          @click=${this.toggle}
-        >
-          <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
-            ${this.chevronForSize()}
-          </swc-icon>
-          <span class="spectrum-Accordion-itemTitle">
-            <slot name="label"></slot>
-          </span>
-        </button>
-      </h3>
+      ${this.renderHeadingWrapper(button)}
       <div
         class="spectrum-Accordion-itemDirectActions"
         hidden

From 9b7ebc4edbc9751a2502ccff7305fc3a24408b59 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 11:22:27 -0500
Subject: [PATCH 11/56] feat: implement disabled item functionality

---
 .../core/components/accordion/AccordionBase.ts         |  7 ++++++-
 .../core/components/accordion/AccordionItemBase.ts     | 10 ++++++++++
 .../packages/swc/components/accordion/AccordionItem.ts |  7 ++++++-
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
index 7692e48d45..755f768b15 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -116,6 +116,7 @@ export abstract class AccordionBase extends SpectrumElement {
     for (const item of items) {
       item.heading = this.level;
       item.size = this.size;
+      item.parentDisabled = this.disabled;
     }
   }
 
@@ -142,7 +143,11 @@ export abstract class AccordionBase extends SpectrumElement {
         this.level = clamped;
       }
     }
-    if (changedProperties.has('level') || changedProperties.has('size')) {
+    if (
+      changedProperties.has('level') ||
+      changedProperties.has('size') ||
+      changedProperties.has('disabled')
+    ) {
       this.updateItems();
     }
     super.update(changedProperties);
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
index df9d859aef..4cff207560 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -66,6 +66,16 @@ export abstract class AccordionItemBase extends SpectrumElement {
   @state()
   public heading: number = 3;
 
+  /**
+   * @internal
+   * Set by the parent accordion when its own `disabled` is true. Causes the
+   * item to render as disabled (aria-disabled + inert panel) without clobbering
+   * the item's own `disabled` property, so the per-item state is preserved
+   * when the accordion is re-enabled.
+   */
+  @state()
+  public parentDisabled: boolean = false;
+
   // ──────────────────────
   //     IMPLEMENTATION
   // ──────────────────────
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 0a299a8b83..4d5c6a5d1e 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -11,6 +11,7 @@
  */
 
 import { CSSResultArray, html, TemplateResult } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
 
 import {
   AccordionItemBase,
@@ -64,7 +65,7 @@ export class AccordionItem extends AccordionItemBase {
   // ──────────────────────────────
 
   protected override toggle(): void {
-    if (this.disabled) {
+    if (this.disabled || this.parentDisabled) {
       return;
     }
     this.open = !this.open;
@@ -140,6 +141,9 @@ export class AccordionItem extends AccordionItemBase {
         type="button"
         aria-expanded=${this.open ? 'true' : 'false'}
         aria-controls="content"
+        aria-disabled=${ifDefined(
+          this.disabled || this.parentDisabled ? 'true' : undefined
+        )}
         @click=${this.toggle}
       >
         <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
@@ -165,6 +169,7 @@ export class AccordionItem extends AccordionItemBase {
         class="spectrum-Accordion-itemContent"
         role="region"
         aria-labelledby="header"
+        .inert=${this.disabled || this.parentDisabled}
       >
         <slot></slot>
       </div>

From e2ce2a7d12c0777e39e4551b8ef195a544fb8b46 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 11:50:56 -0500
Subject: [PATCH 12/56] fix: handle space keyboard behavior (SWC-1487)

---
 .../packages/swc/components/accordion/AccordionItem.ts    | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 4d5c6a5d1e..8312fc7e44 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -109,6 +109,13 @@ export class AccordionItem extends AccordionItemBase {
     event.stopPropagation();
   }
 
+  private handleHeaderKeydown(event: Event): void {
+    if ((event as KeyboardEvent).key === ' ') {
+      event.preventDefault();
+      this.toggle();
+    }
+  }
+
   private renderHeadingWrapper(content: TemplateResult): TemplateResult {
     switch (this.heading) {
       case 2:
@@ -145,6 +152,7 @@ export class AccordionItem extends AccordionItemBase {
           this.disabled || this.parentDisabled ? 'true' : undefined
         )}
         @click=${this.toggle}
+        @keydown=${this.handleHeaderKeydown}
       >
         <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
           ${this.chevronForSize()}

From 24dd4bfe6b2c00eeb361aec0f1a0a930b1cb8e07 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 13:54:52 -0500
Subject: [PATCH 13/56] refactor: address missing migration-setup items

---
 .../core/components/accordion/AccordionBase.ts       | 12 +++---------
 2nd-gen/packages/core/package.json                   |  7 +++++++
 .../packages/swc/components/accordion/Accordion.ts   |  8 +++++++-
 .../packages/swc/components/accordion/test/.gitkeep  |  1 +
 4 files changed, 18 insertions(+), 10 deletions(-)
 create mode 100644 2nd-gen/packages/swc/components/accordion/test/.gitkeep

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
index 755f768b15..21f27b87a2 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { html, PropertyValues, TemplateResult } from 'lit';
+import { PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
 
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
@@ -105,8 +105,8 @@ export abstract class AccordionBase extends SpectrumElement {
     }
   };
 
-  private updateItems(): void {
-    const slot = this.shadowRoot?.querySelector('slot');
+  protected updateItems(): void {
+    const slot = this.renderRoot?.querySelector('slot');
     if (!slot) {
       return;
     }
@@ -164,10 +164,4 @@ export abstract class AccordionBase extends SpectrumElement {
       );
     }
   }
-
-  protected override render(): TemplateResult {
-    return html`
-      <slot @slotchange=${this.updateItems}></slot>
-    `;
-  }
 }
diff --git a/2nd-gen/packages/core/package.json b/2nd-gen/packages/core/package.json
index 86b4009e99..b4626a67e8 100644
--- a/2nd-gen/packages/core/package.json
+++ b/2nd-gen/packages/core/package.json
@@ -19,6 +19,10 @@
       "types": "./dist/components/alert-banner/index.d.ts",
       "import": "./dist/components/alert-banner/index.js"
     },
+    "./components/accordion": {
+      "types": "./dist/components/accordion/index.d.ts",
+      "import": "./dist/components/accordion/index.js"
+    },
     "./components/asset": {
       "types": "./dist/components/asset/index.d.ts",
       "import": "./dist/components/asset/index.js"
@@ -148,6 +152,9 @@
       "components/alert-banner": [
         "dist/components/alert-banner/index.d.ts"
       ],
+      "components/accordion": [
+        "dist/components/accordion/index.d.ts"
+      ],
       "components/asset": [
         "dist/components/asset/index.d.ts"
       ],
diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
index f89f575f90..43f4039dc4 100644
--- a/2nd-gen/packages/swc/components/accordion/Accordion.ts
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { CSSResultArray } from 'lit';
+import { CSSResultArray, html, TemplateResult } from 'lit';
 
 import { AccordionBase } from '@spectrum-web-components/core/components/accordion';
 
@@ -34,4 +34,10 @@ export class Accordion extends AccordionBase {
   public static override get styles(): CSSResultArray {
     return [styles];
   }
+
+  protected override render(): TemplateResult {
+    return html`
+      <slot @slotchange=${this.updateItems}></slot>
+    `;
+  }
 }
diff --git a/2nd-gen/packages/swc/components/accordion/test/.gitkeep b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
@@ -0,0 +1 @@
+

From 5d4c20984b644092232e58bcd60838e40117a1fc Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 16:19:52 -0500
Subject: [PATCH 14/56] refactor: rename methods, align file names

---
 .../{AccordionBase.ts => Accordion.base.ts}   | 19 ++++++++-------
 .../components/accordion/Accordion.types.ts   |  3 +++
 ...rdionItemBase.ts => AccordionItem.base.ts} | 24 +++++++++++++++----
 .../accordion/AccordionItem.types.ts          | 13 ----------
 .../core/components/accordion/index.ts        |  4 ++--
 .../swc/components/accordion/Accordion.ts     |  2 +-
 .../swc/components/accordion/AccordionItem.ts | 15 +++++++-----
 7 files changed, 45 insertions(+), 35 deletions(-)
 rename 2nd-gen/packages/core/components/accordion/{AccordionBase.ts => Accordion.base.ts} (91%)
 rename 2nd-gen/packages/core/components/accordion/{AccordionItemBase.ts => AccordionItem.base.ts} (85%)
 delete mode 100644 2nd-gen/packages/core/components/accordion/AccordionItem.types.ts

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
similarity index 91%
rename from 2nd-gen/packages/core/components/accordion/AccordionBase.ts
rename to 2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 21f27b87a2..96b37850f7 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -17,10 +17,11 @@ import { SpectrumElement } from '@spectrum-web-components/core/element/index.js'
 
 import {
   type AccordionDensity,
+  type AccordionHeadingLevel,
   type AccordionSize,
   SWC_ACCORDION_ITEM_TOGGLE_EVENT,
 } from './Accordion.types.js';
-import { AccordionItemBase } from './AccordionItemBase.js';
+import { AccordionItemBase } from './AccordionItem.base.js';
 
 /**
  * Base class for accordion components. Manages item propagation, heading
@@ -79,7 +80,7 @@ export abstract class AccordionBase extends SpectrumElement {
   //     IMPLEMENTATION
   // ──────────────────────
 
-  private handleItemToggle = (event: Event): void => {
+  private closeSiblingsOnOpen = (event: Event): void => {
     if (this.disabled) {
       event.preventDefault();
       return;
@@ -105,7 +106,7 @@ export abstract class AccordionBase extends SpectrumElement {
     }
   };
 
-  protected updateItems(): void {
+  protected syncAccordionItems(): void {
     const slot = this.renderRoot?.querySelector('slot');
     if (!slot) {
       return;
@@ -114,9 +115,9 @@ export abstract class AccordionBase extends SpectrumElement {
       .assignedElements({ flatten: true })
       .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
     for (const item of items) {
-      item.heading = this.level;
+      item.setManagedHeading(this.level as AccordionHeadingLevel);
       item.size = this.size;
-      item.parentDisabled = this.disabled;
+      item.setManagedParentDisabled(this.disabled);
     }
   }
 
@@ -124,7 +125,7 @@ export abstract class AccordionBase extends SpectrumElement {
     super.connectedCallback();
     this.addEventListener(
       SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-      this.handleItemToggle
+      this.closeSiblingsOnOpen
     );
   }
 
@@ -132,7 +133,7 @@ export abstract class AccordionBase extends SpectrumElement {
     super.disconnectedCallback();
     this.removeEventListener(
       SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-      this.handleItemToggle
+      this.closeSiblingsOnOpen
     );
   }
 
@@ -148,7 +149,7 @@ export abstract class AccordionBase extends SpectrumElement {
       changedProperties.has('size') ||
       changedProperties.has('disabled')
     ) {
-      this.updateItems();
+      this.syncAccordionItems();
     }
     super.update(changedProperties);
   }
@@ -158,7 +159,7 @@ export abstract class AccordionBase extends SpectrumElement {
     if (window.__swc?.DEBUG && !this.hasAttribute('density')) {
       window.__swc.warn(
         this,
-        `<${this.localName}> should have an explicit "density" attribute set. Defaulting to "regular", which corresponds to the 1st-gen default.`,
+        `<${this.localName}> should have an explicit "density" attribute set. Defaulting to "regular".`,
         'https://opensource.adobe.com/spectrum-web-components/components/accordion/',
         { type: 'api', level: 'low' }
       );
diff --git a/2nd-gen/packages/core/components/accordion/Accordion.types.ts b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
index 44b0aba7eb..e3f16db9ec 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.types.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
@@ -16,4 +16,7 @@ export type AccordionSize = (typeof ACCORDION_VALID_SIZES)[number];
 export const ACCORDION_DENSITIES = ['compact', 'regular', 'spacious'] as const;
 export type AccordionDensity = (typeof ACCORDION_DENSITIES)[number];
 
+export const ACCORDION_HEADING_LEVELS = [2, 3, 4, 5, 6] as const;
+export type AccordionHeadingLevel = (typeof ACCORDION_HEADING_LEVELS)[number];
+
 export const SWC_ACCORDION_ITEM_TOGGLE_EVENT = 'swc-accordion-item-toggle';
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
similarity index 85%
rename from 2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
rename to 2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
index 4cff207560..9fd6f11e91 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
@@ -15,6 +15,7 @@ import { property, state } from 'lit/decorators.js';
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
 
 import {
+  type AccordionHeadingLevel,
   type AccordionSize,
   SWC_ACCORDION_ITEM_TOGGLE_EVENT,
 } from './Accordion.types.js';
@@ -60,11 +61,10 @@ export abstract class AccordionItemBase extends SpectrumElement {
   /**
    * @internal
    * Heading level (2–6) propagated by the parent accordion. Defaults to 3
-   * for standalone items. Public so AccordionBase can write to instances
-   * without a type assertion.
+   * for standalone items.
    */
   @state()
-  public heading: number = 3;
+  protected headingLevel: AccordionHeadingLevel = 3;
 
   /**
    * @internal
@@ -74,7 +74,7 @@ export abstract class AccordionItemBase extends SpectrumElement {
    * when the accordion is re-enabled.
    */
   @state()
-  public parentDisabled: boolean = false;
+  protected parentDisabled: boolean = false;
 
   // ──────────────────────
   //     IMPLEMENTATION
@@ -94,4 +94,20 @@ export abstract class AccordionItemBase extends SpectrumElement {
       })
     );
   }
+
+  /**
+   * @internal
+   * Synchronizes parent-managed heading level onto the item.
+   */
+  public setManagedHeading(heading: AccordionHeadingLevel): void {
+    this.headingLevel = heading;
+  }
+
+  /**
+   * @internal
+   * Synchronizes parent-managed disabled state onto the item.
+   */
+  public setManagedParentDisabled(disabled: boolean): void {
+    this.parentDisabled = disabled;
+  }
 }
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
deleted file mode 100644
index 349458211e..0000000000
--- a/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-/**
- * Copyright 2026 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-
-// Item-specific types go here as the accordion item API is defined in subsequent commits.
diff --git a/2nd-gen/packages/core/components/accordion/index.ts b/2nd-gen/packages/core/components/accordion/index.ts
index a725fdc5fe..058e18a567 100644
--- a/2nd-gen/packages/core/components/accordion/index.ts
+++ b/2nd-gen/packages/core/components/accordion/index.ts
@@ -10,6 +10,6 @@
  * governing permissions and limitations under the License.
  */
 
-export * from './AccordionBase.js';
-export * from './AccordionItemBase.js';
+export * from './Accordion.base.js';
+export * from './AccordionItem.base.js';
 export * from './Accordion.types.js';
diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
index 43f4039dc4..02463a4b89 100644
--- a/2nd-gen/packages/swc/components/accordion/Accordion.ts
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -37,7 +37,7 @@ export class Accordion extends AccordionBase {
 
   protected override render(): TemplateResult {
     return html`
-      <slot @slotchange=${this.updateItems}></slot>
+      <slot @slotchange=${this.syncAccordionItems}></slot>
     `;
   }
 }
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 8312fc7e44..855e3e28ed 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -97,7 +97,7 @@ export class AccordionItem extends AccordionItemBase {
     }
   }
 
-  private handleActionsSlotChange(event: Event): void {
+  private syncActionsContainerVisibility(event: Event): void {
     const slot = event.target as HTMLSlotElement;
     const container = slot.parentElement as HTMLElement | null;
     if (container) {
@@ -105,7 +105,7 @@ export class AccordionItem extends AccordionItemBase {
     }
   }
 
-  private handleActionsContainerInteraction(event: Event): void {
+  private stopActionsContainerPropagation(event: Event): void {
     event.stopPropagation();
   }
 
@@ -117,7 +117,7 @@ export class AccordionItem extends AccordionItemBase {
   }
 
   private renderHeadingWrapper(content: TemplateResult): TemplateResult {
-    switch (this.heading) {
+    switch (this.headingLevel) {
       case 2:
         return html`
           <h2>${content}</h2>
@@ -167,10 +167,13 @@ export class AccordionItem extends AccordionItemBase {
       <div
         class="spectrum-Accordion-itemDirectActions"
         hidden
-        @click=${this.handleActionsContainerInteraction}
-        @keydown=${this.handleActionsContainerInteraction}
+        @click=${this.stopActionsContainerPropagation}
+        @keydown=${this.stopActionsContainerPropagation}
       >
-        <slot name="actions" @slotchange=${this.handleActionsSlotChange}></slot>
+        <slot
+          name="actions"
+          @slotchange=${this.syncActionsContainerVisibility}
+        ></slot>
       </div>
       <div
         id="content"

From 56ad095b31941d7b4a2db3d00283c775357b0146 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 08:47:41 -0500
Subject: [PATCH 15/56] refactor: typing, heading rendering, sizing

---
 .../components/accordion/Accordion.base.ts    | 22 ++++++++++------
 .../components/accordion/Accordion.types.ts   |  9 ++++++-
 .../swc/components/accordion/AccordionItem.ts | 25 +++----------------
 3 files changed, 25 insertions(+), 31 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.base.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 96b37850f7..0d1722da31 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.base.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -14,8 +14,10 @@ import { PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
 
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
+import { SizedMixin } from '@spectrum-web-components/core/mixins/index.js';
 
 import {
+  ACCORDION_VALID_SIZES,
   type AccordionDensity,
   type AccordionHeadingLevel,
   type AccordionSize,
@@ -29,7 +31,10 @@ import { AccordionItemBase } from './AccordionItem.base.js';
  *
  * @slot - One or more `swc-accordion-item` elements.
  */
-export abstract class AccordionBase extends SpectrumElement {
+export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
+  validSizes: ACCORDION_VALID_SIZES,
+  defaultSize: 'm',
+}) {
   // ──────────────────
   //     PUBLIC API
   // ──────────────────
@@ -46,14 +51,12 @@ export abstract class AccordionBase extends SpectrumElement {
    * Values outside that range are clamped.
    */
   @property({ type: Number, reflect: true })
-  public level: number = 3;
+  public level: AccordionHeadingLevel = 3;
 
   /**
-   * Size applied to all items. When set, overrides any size set on individual
-   * items.
+   * Size applied to all items. Defaults to `m`.
    */
-  @property({ type: String, reflect: true })
-  public size?: AccordionSize;
+  declare public size: AccordionSize;
 
   /**
    * Controls vertical spacing between items.
@@ -115,7 +118,7 @@ export abstract class AccordionBase extends SpectrumElement {
       .assignedElements({ flatten: true })
       .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
     for (const item of items) {
-      item.setManagedHeading(this.level as AccordionHeadingLevel);
+      item.setManagedHeading(this.level);
       item.size = this.size;
       item.setManagedParentDisabled(this.disabled);
     }
@@ -139,7 +142,10 @@ export abstract class AccordionBase extends SpectrumElement {
 
   protected override update(changedProperties: PropertyValues): void {
     if (changedProperties.has('level')) {
-      const clamped = Math.min(6, Math.max(2, this.level));
+      const clamped = Math.min(
+        6,
+        Math.max(2, this.level)
+      ) as AccordionHeadingLevel;
       if (this.level !== clamped) {
         this.level = clamped;
       }
diff --git a/2nd-gen/packages/core/components/accordion/Accordion.types.ts b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
index e3f16db9ec..cc61783113 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.types.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
@@ -10,7 +10,14 @@
  * governing permissions and limitations under the License.
  */
 
-export const ACCORDION_VALID_SIZES = ['s', 'm', 'l', 'xl'] as const;
+import type { ElementSize } from '@spectrum-web-components/core/mixins/index.js';
+
+export const ACCORDION_VALID_SIZES = [
+  's',
+  'm',
+  'l',
+  'xl',
+] as const satisfies readonly ElementSize[];
 export type AccordionSize = (typeof ACCORDION_VALID_SIZES)[number];
 
 export const ACCORDION_DENSITIES = ['compact', 'regular', 'spacious'] as const;
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 855e3e28ed..08f733e66d 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -12,6 +12,7 @@
 
 import { CSSResultArray, html, TemplateResult } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
+import { html as staticHtml, unsafeStatic } from 'lit/static-html.js';
 
 import {
   AccordionItemBase,
@@ -117,28 +118,8 @@ export class AccordionItem extends AccordionItemBase {
   }
 
   private renderHeadingWrapper(content: TemplateResult): TemplateResult {
-    switch (this.headingLevel) {
-      case 2:
-        return html`
-          <h2>${content}</h2>
-        `;
-      case 4:
-        return html`
-          <h4>${content}</h4>
-        `;
-      case 5:
-        return html`
-          <h5>${content}</h5>
-        `;
-      case 6:
-        return html`
-          <h6>${content}</h6>
-        `;
-      default:
-        return html`
-          <h3>${content}</h3>
-        `;
-    }
+    const tag = unsafeStatic(`h${this.headingLevel}`);
+    return staticHtml`<${tag}>${content}</${tag}>`;
   }
 
   protected override render(): TemplateResult {

From fee852f1854df181bdf77cb82b420066b7a7093a Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 10:44:36 -0500
Subject: [PATCH 16/56] refactor: move toggle() into base, smooth a11y behavior

---
 .../components/accordion/Accordion.base.ts    | 58 +++++++++++++++----
 .../accordion/AccordionItem.base.ts           | 23 +++++---
 .../swc/components/accordion/AccordionItem.ts | 29 ++--------
 3 files changed, 68 insertions(+), 42 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.base.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 0d1722da31..2163f10c80 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.base.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -92,10 +92,34 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
       return;
     }
     const toggling = event.target;
-    if (!(toggling instanceof AccordionItemBase) || !toggling.open) {
+    if (!(toggling instanceof AccordionItemBase)) {
       return;
     }
-    const slot = this.shadowRoot?.querySelector('slot');
+    // Defer until after dispatch returns so that a canceled toggle (where the
+    // item reverts open back to false) does not incorrectly close siblings.
+    queueMicrotask(() => {
+      if (!toggling.open) {
+        return;
+      }
+      const slot = this.shadowRoot?.querySelector('slot');
+      if (!slot) {
+        return;
+      }
+      const items = slot
+        .assignedElements({ flatten: true })
+        .filter(
+          (el): el is AccordionItemBase => el instanceof AccordionItemBase
+        );
+      for (const item of items) {
+        if (item !== toggling) {
+          item.open = false;
+        }
+      }
+    });
+  };
+
+  protected syncAccordionItems(): void {
+    const slot = this.renderRoot?.querySelector('slot');
     if (!slot) {
       return;
     }
@@ -103,13 +127,13 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
       .assignedElements({ flatten: true })
       .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
     for (const item of items) {
-      if (item !== toggling) {
-        item.open = false;
-      }
+      item.setManagedHeading(this.level);
+      item.size = this.size;
+      item.setManagedParentDisabled(this.disabled);
     }
-  };
+  }
 
-  protected syncAccordionItems(): void {
+  private enforceExclusiveOpen(): void {
     const slot = this.renderRoot?.querySelector('slot');
     if (!slot) {
       return;
@@ -117,10 +141,15 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
     const items = slot
       .assignedElements({ flatten: true })
       .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
+    let foundOpen = false;
     for (const item of items) {
-      item.setManagedHeading(this.level);
-      item.size = this.size;
-      item.setManagedParentDisabled(this.disabled);
+      if (item.open) {
+        if (foundOpen) {
+          item.open = false;
+        } else {
+          foundOpen = true;
+        }
+      }
     }
   }
 
@@ -157,6 +186,15 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
     ) {
       this.syncAccordionItems();
     }
+    // changedProperties.get() returns the previous value; this fires only when
+    // disabled transitions from true → false (re-enable).
+    if (
+      changedProperties.has('disabled') &&
+      changedProperties.get('disabled') === true &&
+      !this.allowMultiple
+    ) {
+      this.enforceExclusiveOpen();
+    }
     super.update(changedProperties);
   }
 
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
index 9fd6f11e91..d44c4e6f97 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
@@ -82,17 +82,22 @@ export abstract class AccordionItemBase extends SpectrumElement {
 
   /**
    * @internal
-   * Dispatches the toggle event. The concrete class wires this to the
-   * header button's click handler and adds open-state management.
+   * Toggles the item open state. Guards for disabled, flips `open`, dispatches
+   * the toggle event, and reverts if the event is canceled.
    */
   protected toggle(): void {
-    this.dispatchEvent(
-      new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
-        bubbles: true,
-        composed: true,
-        cancelable: true,
-      })
-    );
+    if (this.disabled || this.parentDisabled) {
+      return;
+    }
+    this.open = !this.open;
+    const event = new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+    });
+    if (!this.dispatchEvent(event)) {
+      this.open = !this.open;
+    }
   }
 
   /**
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 08f733e66d..5c8558398e 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -14,10 +14,7 @@ import { CSSResultArray, html, TemplateResult } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { html as staticHtml, unsafeStatic } from 'lit/static-html.js';
 
-import {
-  AccordionItemBase,
-  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-} from '@spectrum-web-components/core/components/accordion';
+import { AccordionItemBase } from '@spectrum-web-components/core/components/accordion';
 
 import '../icon/swc-icon.js';
 
@@ -61,25 +58,6 @@ export class AccordionItem extends AccordionItemBase {
     this.shadowRoot?.getElementById('header')?.click();
   }
 
-  // ──────────────────────────────
-  //     TOGGLE BEHAVIOR
-  // ──────────────────────────────
-
-  protected override toggle(): void {
-    if (this.disabled || this.parentDisabled) {
-      return;
-    }
-    this.open = !this.open;
-    const event = new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
-      bubbles: true,
-      composed: true,
-      cancelable: true,
-    });
-    if (!this.dispatchEvent(event)) {
-      this.open = !this.open;
-    }
-  }
-
   // ──────────────────────────────
   //     RENDERING
   // ──────────────────────────────
@@ -112,6 +90,10 @@ export class AccordionItem extends AccordionItemBase {
 
   private handleHeaderKeydown(event: Event): void {
     if ((event as KeyboardEvent).key === ' ') {
+      // Space requires preventDefault to suppress page scroll; toggle is then
+      // called explicitly. Enter is not handled here — the browser's native
+      // button activation fires a click event, which calls toggle() via the
+      // @click binding.
       event.preventDefault();
       this.toggle();
     }
@@ -161,6 +143,7 @@ export class AccordionItem extends AccordionItemBase {
         class="spectrum-Accordion-itemContent"
         role="region"
         aria-labelledby="header"
+        ?hidden=${!this.open}
         .inert=${this.disabled || this.parentDisabled}
       >
         <slot></slot>

From e8ed70df539de8461af6bf3613d74786218b5538 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 11:29:27 -0500
Subject: [PATCH 17/56] refactor: use assignedItems() helper

---
 .../components/accordion/Accordion.base.ts    | 39 +++++++------------
 1 file changed, 13 insertions(+), 26 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.base.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 2163f10c80..904e721ddd 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.base.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -83,6 +83,16 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
   //     IMPLEMENTATION
   // ──────────────────────
 
+  private assignedItems(): AccordionItemBase[] {
+    const slot = this.renderRoot?.querySelector('slot');
+    if (!slot) {
+      return [];
+    }
+    return slot
+      .assignedElements({ flatten: true })
+      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
+  }
+
   private closeSiblingsOnOpen = (event: Event): void => {
     if (this.disabled) {
       event.preventDefault();
@@ -101,16 +111,7 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
       if (!toggling.open) {
         return;
       }
-      const slot = this.shadowRoot?.querySelector('slot');
-      if (!slot) {
-        return;
-      }
-      const items = slot
-        .assignedElements({ flatten: true })
-        .filter(
-          (el): el is AccordionItemBase => el instanceof AccordionItemBase
-        );
-      for (const item of items) {
+      for (const item of this.assignedItems()) {
         if (item !== toggling) {
           item.open = false;
         }
@@ -119,14 +120,7 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
   };
 
   protected syncAccordionItems(): void {
-    const slot = this.renderRoot?.querySelector('slot');
-    if (!slot) {
-      return;
-    }
-    const items = slot
-      .assignedElements({ flatten: true })
-      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
-    for (const item of items) {
+    for (const item of this.assignedItems()) {
       item.setManagedHeading(this.level);
       item.size = this.size;
       item.setManagedParentDisabled(this.disabled);
@@ -134,15 +128,8 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
   }
 
   private enforceExclusiveOpen(): void {
-    const slot = this.renderRoot?.querySelector('slot');
-    if (!slot) {
-      return;
-    }
-    const items = slot
-      .assignedElements({ flatten: true })
-      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
     let foundOpen = false;
-    for (const item of items) {
+    for (const item of this.assignedItems()) {
       if (item.open) {
         if (foundOpen) {
           item.open = false;

From f2d505669a9b223308d6048e801d61f4a67f48a1 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 12:06:35 -0500
Subject: [PATCH 18/56] test: add a11y tests

---
 .../swc/components/accordion/test/.gitkeep    |   1 -
 .../accordion/test/accordion.test.ts          | 584 ++++++++++++++++++
 2 files changed, 584 insertions(+), 1 deletion(-)
 delete mode 100644 2nd-gen/packages/swc/components/accordion/test/.gitkeep
 create mode 100644 2nd-gen/packages/swc/components/accordion/test/accordion.test.ts

diff --git a/2nd-gen/packages/swc/components/accordion/test/.gitkeep b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
deleted file mode 100644
index 8b13789179..0000000000
--- a/2nd-gen/packages/swc/components/accordion/test/.gitkeep
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
new file mode 100644
index 0000000000..7ef3846e33
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
@@ -0,0 +1,584 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { html } from 'lit';
+import { expect } from '@storybook/test';
+import type { Meta, StoryObj as Story } from '@storybook/web-components';
+
+import { Accordion, AccordionItem } from '@adobe/spectrum-wc/accordion';
+
+import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
+import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
+
+import { SWC_ACCORDION_ITEM_TOGGLE_EVENT } from '../../../../core/components/accordion/Accordion.types.js';
+import { getComponent, getComponents } from '../../../utils/test-utils.js';
+import meta, { Overview } from '../stories/accordion.stories.js';
+
+export default {
+  ...meta,
+  title: 'Accordion/Tests',
+  parameters: {
+    ...meta.parameters,
+    docs: { disable: true, page: null },
+  },
+  tags: ['!autodocs', 'dev'],
+} as Meta;
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Defaults
+// ──────────────────────────────────────────────────────────────
+
+export const OverviewTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const items = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+
+    await step('renders three items', async () => {
+      expect(items.length, 'three accordion items are rendered').toBe(3);
+    });
+
+    await step('third item is open by default', async () => {
+      expect(items[2]?.open, 'third item open property is true').toBe(true);
+    });
+
+    await step('first two items are closed by default', async () => {
+      expect(items[0]?.open, 'first item open property is false').toBe(false);
+      expect(items[1]?.open, 'second item open property is false').toBe(false);
+    });
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: ARIA contract
+// ──────────────────────────────────────────────────────────────
+
+export const AriaContractTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const items = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const closedItem = items[0] as AccordionItem;
+    const openItem = items[2] as AccordionItem;
+
+    const closedButton = closedItem.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const closedPanel = closedItem.shadowRoot?.getElementById(
+      'content'
+    ) as HTMLElement;
+    const openButton = openItem.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const openPanel = openItem.shadowRoot?.getElementById(
+      'content'
+    ) as HTMLElement;
+
+    await step('aria-expanded reflects open state', async () => {
+      expect(
+        closedButton.getAttribute('aria-expanded'),
+        'closed item button has aria-expanded="false"'
+      ).toBe('false');
+      expect(
+        openButton.getAttribute('aria-expanded'),
+        'open item button has aria-expanded="true"'
+      ).toBe('true');
+    });
+
+    await step('aria-controls value matches the panel id', async () => {
+      expect(
+        closedButton.getAttribute('aria-controls'),
+        'aria-controls is "content"'
+      ).toBe('content');
+      expect(closedPanel.id, 'panel id is "content"').toBe('content');
+    });
+
+    await step(
+      'panel has role="region" and aria-labelledby="header"',
+      async () => {
+        expect(closedPanel.getAttribute('role'), 'panel role is "region"').toBe(
+          'region'
+        );
+        expect(
+          closedPanel.getAttribute('aria-labelledby'),
+          'panel aria-labelledby is "header"'
+        ).toBe('header');
+      }
+    );
+
+    await step(
+      'closed panel has hidden attribute; open panel does not',
+      async () => {
+        expect(
+          closedPanel.hasAttribute('hidden'),
+          'closed panel has hidden attribute'
+        ).toBe(true);
+        expect(
+          openPanel.hasAttribute('hidden'),
+          'open panel does not have hidden attribute'
+        ).toBe(false);
+      }
+    );
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Open / close
+// ──────────────────────────────────────────────────────────────
+
+export const ToggleTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const items = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const item = items[0] as AccordionItem;
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step('clicking the header button opens a closed item', async () => {
+      expect(item.open, 'item starts closed').toBe(false);
+
+      button.click();
+      await new Promise<void>((resolve) => queueMicrotask(resolve));
+      await item.updateComplete;
+
+      expect(item.open, 'item is now open').toBe(true);
+      expect(
+        button.getAttribute('aria-expanded'),
+        'aria-expanded is "true" after open'
+      ).toBe('true');
+      expect(
+        panel.hasAttribute('hidden'),
+        'hidden attribute is removed when panel is open'
+      ).toBe(false);
+    });
+
+    await step('clicking the header button again closes the item', async () => {
+      button.click();
+      await new Promise<void>((resolve) => queueMicrotask(resolve));
+      await item.updateComplete;
+
+      expect(item.open, 'item is closed again').toBe(false);
+      expect(
+        button.getAttribute('aria-expanded'),
+        'aria-expanded is "false" after close'
+      ).toBe('false');
+      expect(
+        panel.hasAttribute('hidden'),
+        'hidden attribute is restored when panel is closed'
+      ).toBe(true);
+    });
+  },
+};
+
+export const ToggleEventTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const item = (
+      await getComponents<AccordionItem>(canvasElement, 'swc-accordion-item')
+    )[0] as AccordionItem;
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+
+    await step(
+      'clicking the header button dispatches the toggle event',
+      async () => {
+        let toggleFired = false;
+        item.addEventListener(
+          SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+          () => {
+            toggleFired = true;
+          },
+          { once: true }
+        );
+
+        button.click();
+        await item.updateComplete;
+
+        expect(toggleFired, 'toggle event was dispatched').toBe(true);
+      }
+    );
+
+    await step(
+      'toggle event is cancelable; canceling reverts open state',
+      async () => {
+        const wasOpen = item.open;
+        item.addEventListener(
+          SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+          (event) => {
+            event.preventDefault();
+          },
+          { once: true }
+        );
+
+        button.click();
+        await item.updateComplete;
+
+        expect(item.open, 'open state is reverted when event is canceled').toBe(
+          wasOpen
+        );
+      }
+    );
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Disabled item
+// ──────────────────────────────────────────────────────────────
+
+export const DisabledItemTest: Story = {
+  render: () => html`
+    <swc-accordion density="regular">
+      <swc-accordion-item disabled>
+        <span slot="label">Disabled item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step('disabled item button has aria-disabled="true"', async () => {
+      expect(
+        button.getAttribute('aria-disabled'),
+        'aria-disabled is "true"'
+      ).toBe('true');
+    });
+
+    await step(
+      'disabled item button does not have native disabled attribute',
+      async () => {
+        expect(
+          button.hasAttribute('disabled'),
+          'native disabled attribute is absent'
+        ).toBe(false);
+      }
+    );
+
+    await step('disabled item button remains in the tab order', async () => {
+      expect(button.tabIndex, 'tabIndex is not -1').not.toBe(-1);
+    });
+
+    await step('disabled item panel is inert', async () => {
+      expect(panel.inert, 'panel inert property is true').toBe(true);
+    });
+
+    await step('clicking a disabled item does not open it', async () => {
+      button.click();
+      await item.updateComplete;
+
+      expect(item.open, 'item remains closed after click').toBe(false);
+    });
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Host disabled
+// ──────────────────────────────────────────────────────────────
+
+export const HostDisabledTest: Story = {
+  render: () => html`
+    <swc-accordion disabled density="regular">
+      <swc-accordion-item>
+        <span slot="label">Item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const accordion = await getComponent<Accordion>(
+      canvasElement,
+      'swc-accordion'
+    );
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step(
+      'item button has aria-disabled when the host accordion is disabled',
+      async () => {
+        expect(
+          button.getAttribute('aria-disabled'),
+          'aria-disabled is "true" via host disabled'
+        ).toBe('true');
+      }
+    );
+
+    await step(
+      'item button does not have native disabled when host is disabled',
+      async () => {
+        expect(
+          button.hasAttribute('disabled'),
+          'native disabled attribute is absent'
+        ).toBe(false);
+      }
+    );
+
+    await step('item panel is inert when host is disabled', async () => {
+      expect(panel.inert, 'panel inert is true').toBe(true);
+    });
+
+    await step(
+      'clicking an item does not open it when the host is disabled',
+      async () => {
+        button.click();
+        await item.updateComplete;
+
+        expect(
+          item.open,
+          'item remains closed after click on host-disabled accordion'
+        ).toBe(false);
+      }
+    );
+
+    await step('clearing host disabled allows the item to open', async () => {
+      accordion.disabled = false;
+      await accordion.updateComplete;
+      await item.updateComplete;
+
+      expect(
+        button.getAttribute('aria-disabled'),
+        'aria-disabled is removed after host re-enabled'
+      ).toBeNull();
+      expect(panel.inert, 'panel is no longer inert').toBe(false);
+
+      button.click();
+      await item.updateComplete;
+
+      expect(item.open, 'item opens after host is re-enabled').toBe(true);
+    });
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Keyboard
+// ──────────────────────────────────────────────────────────────
+
+export const SpaceKeyTest: Story = {
+  render: () => html`
+    <swc-accordion density="regular">
+      <swc-accordion-item>
+        <span slot="label">Item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+
+    await step(
+      'Space on the header button calls preventDefault and opens the item',
+      async () => {
+        const event = new KeyboardEvent('keydown', {
+          key: ' ',
+          bubbles: true,
+          cancelable: true,
+        });
+        button.dispatchEvent(event);
+        await item.updateComplete;
+
+        expect(
+          event.defaultPrevented,
+          'Space keydown default is prevented'
+        ).toBe(true);
+        expect(item.open, 'item is open after Space').toBe(true);
+      }
+    );
+
+    await step(
+      'Space on a disabled header button prevents default but does not toggle',
+      async () => {
+        item.disabled = true;
+        await item.updateComplete;
+
+        const event = new KeyboardEvent('keydown', {
+          key: ' ',
+          bubbles: true,
+          cancelable: true,
+        });
+        button.dispatchEvent(event);
+        await item.updateComplete;
+
+        expect(
+          event.defaultPrevented,
+          'Space keydown default is still prevented on disabled item'
+        ).toBe(true);
+        expect(
+          item.open,
+          'open state does not change when item is disabled'
+        ).toBe(true);
+      }
+    );
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Exclusive open (allow-multiple: false)
+// ──────────────────────────────────────────────────────────────
+
+export const ExclusiveOpenTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const items = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const item1 = items[0] as AccordionItem;
+    const item3 = items[2] as AccordionItem;
+    const button1 = item1.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+
+    await step('opening one item closes the previously open item', async () => {
+      expect(item3.open, 'third item starts open').toBe(true);
+
+      button1.click();
+      // closeSiblingsOnOpen defers via queueMicrotask; wait for it to run.
+      await new Promise<void>((resolve) => queueMicrotask(resolve));
+      await item1.updateComplete;
+      await item3.updateComplete;
+
+      expect(item1.open, 'first item is now open').toBe(true);
+      expect(item3.open, 'third item is now closed').toBe(false);
+    });
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Allow-multiple
+// ──────────────────────────────────────────────────────────────
+
+export const AllowMultipleTest: Story = {
+  render: () => html`
+    <swc-accordion allow-multiple density="regular">
+      <swc-accordion-item>
+        <span slot="label">Alchemy</span>
+        Alchemy content
+      </swc-accordion-item>
+      <swc-accordion-item open>
+        <span slot="label">Astrology</span>
+        Astrology content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const [item1, item2] = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button1 = (item1 as AccordionItem).shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+
+    await step(
+      'opening one item does not close others when allow-multiple is set',
+      async () => {
+        expect((item2 as AccordionItem).open, 'second item starts open').toBe(
+          true
+        );
+
+        button1.click();
+        await new Promise<void>((resolve) => queueMicrotask(resolve));
+        await (item1 as AccordionItem).updateComplete;
+        await (item2 as AccordionItem).updateComplete;
+
+        expect((item1 as AccordionItem).open, 'first item is now open').toBe(
+          true
+        );
+        expect((item2 as AccordionItem).open, 'second item is still open').toBe(
+          true
+        );
+      }
+    );
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Heading level
+// ──────────────────────────────────────────────────────────────
+
+export const HeadingLevelTest: Story = {
+  render: () => html`
+    <swc-accordion level="4" density="regular">
+      <swc-accordion-item>
+        <span slot="label">Item</span>
+        Content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const accordion = await getComponent<Accordion>(
+      canvasElement,
+      'swc-accordion'
+    );
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    await item.updateComplete;
+
+    await step(
+      'item renders the heading tag matching the accordion level',
+      async () => {
+        expect(
+          item.shadowRoot?.querySelector('h4'),
+          'h4 element is in the item shadow DOM'
+        ).toBeTruthy();
+      }
+    );
+
+    await step(
+      'heading tag updates when the accordion level changes',
+      async () => {
+        accordion.level = 2;
+        await accordion.updateComplete;
+        await item.updateComplete;
+
+        expect(
+          item.shadowRoot?.querySelector('h4'),
+          'h4 is no longer present after level change'
+        ).toBeNull();
+        expect(
+          item.shadowRoot?.querySelector('h2'),
+          'h2 element is in the item shadow DOM'
+        ).toBeTruthy();
+      }
+    );
+  },
+};

From 12da5fca960c207dcf6526c0ff46e088c49c1a87 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 13:23:43 -0500
Subject: [PATCH 19/56] docs: add a11y docs

---
 .../accordion/stories/accordion.stories.ts    | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index 4284e11925..b8f71a4dd7 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -125,3 +125,69 @@ export const Overview: Story = {
   },
   tags: ['overview'],
 };
+
+// ────────────────────────────────
+//    ACCESSIBILITY STORIES
+// ────────────────────────────────
+
+/**
+ * ### Features
+ *
+ * The `<swc-accordion>` and `<swc-accordion-item>` elements implement the
+ * [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/):
+ *
+ * #### Keyboard navigation
+ *
+ * - <kbd>Tab</kbd>: Moves focus into and between item header buttons
+ * - <kbd>Enter</kbd>: Activates the focused header button (browser-native click behavior)
+ * - <kbd>Space</kbd>: Toggles the focused item and prevents page scroll
+ *
+ * #### ARIA implementation
+ *
+ * 1. **Heading wrapper**: Each header button is wrapped in an `h2`–`h6` element matching
+ *    the accordion's `level` attribute
+ * 2. **`aria-expanded`**: Set to `"true"` on open items, `"false"` on closed items
+ * 3. **`aria-controls`**: Points from the header button to the panel (`id="content"`)
+ * 4. **Panel role**: The panel has `role="region"` and `aria-labelledby` pointing to the
+ *    header button, making it a labeled landmark
+ * 5. **`aria-disabled`**: Set on the header button (not the native `disabled` attribute)
+ *    so disabled items remain keyboard-reachable
+ * 6. **`hidden`**: Added to closed panels to remove them from the accessibility tree
+ * 7. **`inert`**: Added to disabled-item panels to block interaction with their contents
+ *
+ * ### Best practices
+ *
+ * - Set a `level` that continues the existing page heading hierarchy without skipping levels
+ * - Provide meaningful, unique label text for each item so screen reader users can
+ *   navigate the heading list
+ * - When using the `actions` slot, include the item subject in the action's accessible
+ *   name (e.g., "Edit Alchemy" rather than "Edit") so it is unambiguous out of context
+ * - Always set `density` explicitly; use `regular` when unsure
+ */
+export const Accessibility: Story = {
+  render: () => html`
+    <swc-accordion level="3" density="regular">
+      <swc-accordion-item open>
+        <span slot="label">Alchemy</span>
+        <button slot="actions" aria-label="Edit Alchemy">Edit</button>
+        Alchemy is an ancient branch of natural philosophy, a philosophical and
+        protoscientific tradition that was historically practiced in China,
+        India, the Muslim world, and Europe.
+      </swc-accordion-item>
+      <swc-accordion-item>
+        <span slot="label">Astrology</span>
+        <button slot="actions" aria-label="Edit Astrology">Edit</button>
+        Astrology is a range of divinatory practices, recognized as
+        pseudoscientific since the 18th century, that propose that information
+        about human affairs and terrestrial events may be discerned by studying
+        the apparent positions of celestial objects.
+      </swc-accordion-item>
+      <swc-accordion-item disabled>
+        <span slot="label">Natural magic (disabled)</span>
+        Natural magic in the context of early modern Europe was a branch of
+        philosophy that treated occult forces as resulting from natural causes.
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  tags: ['a11y'],
+};

From 65b949b3ec5097e783aa3bd24474caa4bdf84f28 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 14:49:17 -0500
Subject: [PATCH 20/56] fix: freeze accordion open state when disabled

---
 .../accordion/AccordionItem.base.ts           |  34 ++++-
 .../accordion/test/accordion.test.ts          | 118 ++++++++++++++++++
 2 files changed, 150 insertions(+), 2 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
index d44c4e6f97..c22793ad7b 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
@@ -38,7 +38,26 @@ export abstract class AccordionItemBase extends SpectrumElement {
    * Whether the accordion item panel is expanded.
    */
   @property({ type: Boolean, reflect: true })
-  public open: boolean = false;
+  public get open(): boolean {
+    return this._open;
+  }
+
+  public set open(value: boolean) {
+    if (this.hasUpdated && !this.mayExpand() && value !== this._open) {
+      return;
+    }
+    if (value === this._open) {
+      return;
+    }
+    const oldValue = this._open;
+    this._open = value;
+    if (value) {
+      this.setAttribute('open', '');
+    } else {
+      this.removeAttribute('open');
+    }
+    this.requestUpdate('open', oldValue);
+  }
 
   /**
    * Whether the accordion item is disabled. A disabled item keeps its header
@@ -54,6 +73,8 @@ export abstract class AccordionItemBase extends SpectrumElement {
   @property({ type: String, reflect: true })
   public size?: AccordionSize;
 
+  private _open = false;
+
   // ──────────────────────
   //     INTERNAL STATE
   // ──────────────────────
@@ -80,13 +101,22 @@ export abstract class AccordionItemBase extends SpectrumElement {
   //     IMPLEMENTATION
   // ──────────────────────
 
+  /**
+   * @internal
+   * Whether the item may change `open` (expand or collapse). When false, the
+   * `open` setter and `toggle()` leave state unchanged.
+   */
+  protected mayExpand(): boolean {
+    return !this.disabled && !this.parentDisabled;
+  }
+
   /**
    * @internal
    * Toggles the item open state. Guards for disabled, flips `open`, dispatches
    * the toggle event, and reverts if the event is canceled.
    */
   protected toggle(): void {
-    if (this.disabled || this.parentDisabled) {
+    if (!this.mayExpand()) {
       return;
     }
     this.open = !this.open;
diff --git a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
index 7ef3846e33..ab40b3dca8 100644
--- a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
+++ b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
@@ -294,6 +294,63 @@ export const DisabledItemTest: Story = {
 
       expect(item.open, 'item remains closed after click').toBe(false);
     });
+
+    await step(
+      'setting open on a closed disabled item does not expand it',
+      async () => {
+        item.open = true;
+        await item.updateComplete;
+
+        expect(item.open, 'open property stays false').toBe(false);
+        expect(
+          panel.hasAttribute('hidden'),
+          'panel stays hidden after imperative open'
+        ).toBe(true);
+      }
+    );
+  },
+};
+
+export const DisabledOpenItemTest: Story = {
+  render: () => html`
+    <swc-accordion density="regular">
+      <swc-accordion-item disabled open>
+        <span slot="label">Disabled open item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step('disabled open item starts expanded', async () => {
+      expect(item.open, 'item starts open').toBe(true);
+    });
+
+    await step(
+      'setting open to false on a disabled item does not collapse it',
+      async () => {
+        item.open = false;
+        await item.updateComplete;
+
+        expect(item.open, 'open property stays true').toBe(true);
+        expect(
+          panel.hasAttribute('hidden'),
+          'panel stays visible after imperative close'
+        ).toBe(false);
+        expect(
+          button.getAttribute('aria-expanded'),
+          'aria-expanded stays true'
+        ).toBe('true');
+      }
+    );
   },
 };
 
@@ -361,6 +418,24 @@ export const HostDisabledTest: Story = {
       }
     );
 
+    await step(
+      'setting open on a closed item does not expand it when the host is disabled',
+      async () => {
+        item.open = true;
+        await item.updateComplete;
+
+        expect(item.open, 'open property stays false').toBe(false);
+        expect(
+          panel.hasAttribute('hidden'),
+          'panel stays hidden after imperative open'
+        ).toBe(true);
+        expect(
+          button.getAttribute('aria-expanded'),
+          'aria-expanded stays false'
+        ).toBe('false');
+      }
+    );
+
     await step('clearing host disabled allows the item to open', async () => {
       accordion.disabled = false;
       await accordion.updateComplete;
@@ -380,6 +455,49 @@ export const HostDisabledTest: Story = {
   },
 };
 
+export const HostDisabledOpenItemTest: Story = {
+  render: () => html`
+    <swc-accordion disabled density="regular">
+      <swc-accordion-item open>
+        <span slot="label">Item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step('open item stays expanded while host is disabled', async () => {
+      expect(item.open, 'item starts open').toBe(true);
+    });
+
+    await step(
+      'setting open to false does not collapse the item when the host is disabled',
+      async () => {
+        item.open = false;
+        await item.updateComplete;
+
+        expect(item.open, 'open property stays true').toBe(true);
+        expect(
+          panel.hasAttribute('hidden'),
+          'panel stays visible after imperative close'
+        ).toBe(false);
+        expect(
+          button.getAttribute('aria-expanded'),
+          'aria-expanded stays true'
+        ).toBe('true');
+      }
+    );
+  },
+};
+
 // ──────────────────────────────────────────────────────────────
 // TEST: Keyboard
 // ──────────────────────────────────────────────────────────────

From c8033e68fbf74a20e88c3e7faeb600217a4b7b55 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 15:37:32 -0500
Subject: [PATCH 21/56] feat: 1st-gen deprecation warnings/tests

---
 1st-gen/packages/accordion/src/Accordion.ts   |  33 ++++-
 .../packages/accordion/src/AccordionItem.ts   |  20 ++-
 .../accordion/test/deprecation.test.ts        | 134 ++++++++++++++++++
 .../packages/accordion/test/dev-mode.test.ts  |  39 ++++-
 1st-gen/tools/base/src/version.d.ts           |   4 +-
 5 files changed, 221 insertions(+), 9 deletions(-)
 create mode 100644 1st-gen/packages/accordion/test/deprecation.test.ts

diff --git a/1st-gen/packages/accordion/src/Accordion.ts b/1st-gen/packages/accordion/src/Accordion.ts
index 6ec2dae9ad..4b8b9ee93e 100644
--- a/1st-gen/packages/accordion/src/Accordion.ts
+++ b/1st-gen/packages/accordion/src/Accordion.ts
@@ -27,6 +27,9 @@ import { FocusGroupController } from '@spectrum-web-components/reactive-controll
 import styles from './accordion.css.js';
 import { AccordionItem } from './AccordionItem.js';
 
+const ACCORDION_MIGRATION_DOC_URL =
+  'https://opensource.adobe.com/spectrum-web-components/components/accordion/';
+
 /**
  * @element sp-accordion
  * @slot - The sp-accordion-item children to display.
@@ -72,7 +75,19 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     isFocusableElement: (el: AccordionItem) => !el.disabled,
   });
 
+  /**
+   * @deprecated `focus()` on `<sp-accordion>` is deprecated and will be removed
+   * in Spectrum 2. Focus the header button inside `<sp-accordion-item>` instead.
+   */
   public override focus(): void {
+    if (window.__swc?.DEBUG) {
+      window.__swc.warn(
+        this,
+        `<${this.localName}> focus() is deprecated and will be removed in Spectrum 2. Focus the header button inside <sp-accordion-item> instead.`,
+        ACCORDION_MIGRATION_DOC_URL,
+        { level: 'deprecation' }
+      );
+    }
     this.focusGroupController.focus();
   }
 
@@ -99,11 +114,23 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     });
   }
 
+  private syncAssignedItem(item: AccordionItem): void {
+    if (window.__swc?.DEBUG && item.level !== this.level) {
+      window.__swc.warn(
+        item,
+        `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
+        ACCORDION_MIGRATION_DOC_URL,
+        { level: 'deprecation' }
+      );
+    }
+    item.size = this.size;
+    item.level = this.level;
+  }
+
   private handleSlotchange(): void {
     this.focusGroupController.clearElementCache();
     this.items.forEach((item) => {
-      item.size = this.size;
-      item.level = this.level;
+      this.syncAssignedItem(item);
     });
   }
 
@@ -116,7 +143,7 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     }
     if (changed.has('level')) {
       this.items.forEach((item) => {
-        item.level = this.level;
+        this.syncAssignedItem(item);
       });
     }
   }
diff --git a/1st-gen/packages/accordion/src/AccordionItem.ts b/1st-gen/packages/accordion/src/AccordionItem.ts
index 80dd83bbe2..3857ce908d 100644
--- a/1st-gen/packages/accordion/src/AccordionItem.ts
+++ b/1st-gen/packages/accordion/src/AccordionItem.ts
@@ -61,10 +61,13 @@ const chevronIcon: Record<string, () => TemplateResult> = {
   `,
 };
 
+const ACCORDION_MIGRATION_DOC_URL =
+  'https://opensource.adobe.com/spectrum-web-components/components/accordion/';
+
 /**
  * @element sp-accordion-item
  * @slot - The content of the item that is hidden when the item is not open
- * @fires sp-accordion-item-toggle - Announce that an accordion item has been toggled while allowing the event to be cancelled.
+ * @fires sp-accordion-item-toggle - Announce that an accordion item has been toggled while allowing the event to be cancelled. In Spectrum 2, this event is renamed to `swc-accordion-item-toggle`.
  */
 export class AccordionItem extends SizedMixin(Focusable, {
   noDefaultSize: true,
@@ -76,6 +79,10 @@ export class AccordionItem extends SizedMixin(Focusable, {
   @property({ type: Boolean, reflect: true })
   public open = false;
 
+  /**
+   * @deprecated The `label` attribute is deprecated and will be removed in
+   * Spectrum 2.
+   */
   @property({ type: String, reflect: true })
   public label = '';
 
@@ -86,6 +93,9 @@ export class AccordionItem extends SizedMixin(Focusable, {
    * The heading level (2-6) to use for the accordion item title.
    * This property is set by the parent sp-accordion element.
    * Defaults to 3.
+   *
+   * @deprecated The `level` attribute on accordion items is deprecated and will
+   * be removed in Spectrum 2. Use `level` on `<sp-accordion>` instead.
    */
   @property({ type: Number, reflect: true })
   public level: number = 3;
@@ -182,5 +192,13 @@ export class AccordionItem extends SizedMixin(Focusable, {
         this.removeAttribute('aria-disabled');
       }
     }
+    if (window.__swc?.DEBUG && changes.has('label') && this.label) {
+      window.__swc.warn(
+        this,
+        `<${this.localName}> the "label" attribute is deprecated and will be removed in Spectrum 2.`,
+        ACCORDION_MIGRATION_DOC_URL,
+        { level: 'deprecation' }
+      );
+    }
   }
 }
diff --git a/1st-gen/packages/accordion/test/deprecation.test.ts b/1st-gen/packages/accordion/test/deprecation.test.ts
new file mode 100644
index 0000000000..dab3a9e5d4
--- /dev/null
+++ b/1st-gen/packages/accordion/test/deprecation.test.ts
@@ -0,0 +1,134 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { elementUpdated, expect, fixture, html } from '@open-wc/testing';
+import { SinonSpyCall, SinonStub, stub } from 'sinon';
+
+import { Accordion, AccordionItem } from '@spectrum-web-components/accordion';
+
+import '@spectrum-web-components/accordion/sp-accordion.js';
+import '@spectrum-web-components/accordion/sp-accordion-item.js';
+
+describe('Accordion - deprecation warnings', () => {
+  let consoleWarnStub!: SinonStub;
+
+  before(() => {
+    consoleWarnStub = stub(console, 'warn');
+  });
+
+  afterEach(() => {
+    consoleWarnStub.resetHistory();
+  });
+
+  after(() => {
+    consoleWarnStub.restore();
+  });
+
+  const deprecationCalls = (): SinonSpyCall[] =>
+    consoleWarnStub
+      .getCalls()
+      .filter(
+        (call) =>
+          (call.args[call.args.length - 1] as { data?: { level?: string } })
+            ?.data?.level === 'deprecation'
+      );
+
+  const expectDeprecationData = (
+    call: SinonSpyCall,
+    localName: 'sp-accordion' | 'sp-accordion-item'
+  ): void => {
+    expect(
+      call.args[call.args.length - 1],
+      'confirm `data` shape'
+    ).to.deep.equal({
+      data: {
+        localName,
+        type: 'api',
+        level: 'deprecation',
+      },
+    });
+  };
+
+  it('warns about deprecated "label" attribute', async () => {
+    const item = await fixture<AccordionItem>(html`
+      <sp-accordion-item label="Section"></sp-accordion-item>
+    `);
+
+    await elementUpdated(item);
+
+    expect(consoleWarnStub.called).to.be.true;
+    const labelCall = deprecationCalls().find((call) =>
+      String(call.args[0]).includes('"label"')
+    );
+    expect(labelCall, 'label deprecation warn fired').to.exist;
+    expect(
+      String(labelCall!.args[0]).includes('deprecated'),
+      'confirm deprecation message'
+    ).to.be.true;
+    expect(
+      String(labelCall!.args[0]).includes('Spectrum 2'),
+      'confirm Spectrum 2 timeline'
+    ).to.be.true;
+    expectDeprecationData(labelCall!, 'sp-accordion-item');
+  });
+
+  it('does not warn when label is empty', async () => {
+    const item = await fixture<AccordionItem>(html`
+      <sp-accordion-item></sp-accordion-item>
+    `);
+
+    await elementUpdated(item);
+
+    expect(deprecationCalls().length).to.equal(0);
+  });
+
+  it('warns when focus() is called on the accordion host', async () => {
+    const accordion = await fixture<Accordion>(html`
+      <sp-accordion>
+        <sp-accordion-item label="Section">Panel</sp-accordion-item>
+      </sp-accordion>
+    `);
+
+    await elementUpdated(accordion);
+    consoleWarnStub.resetHistory();
+    accordion.focus();
+
+    const focusCall = deprecationCalls().find((call) =>
+      String(call.args[0]).includes('focus()')
+    );
+    expect(focusCall, 'focus deprecation warn fired').to.exist;
+    expect(
+      String(focusCall!.args[0]).includes('deprecated'),
+      'confirm deprecation message'
+    ).to.be.true;
+    expect(
+      String(focusCall!.args[0]).includes('Spectrum 2'),
+      'confirm Spectrum 2 timeline'
+    ).to.be.true;
+    expectDeprecationData(focusCall!, 'sp-accordion');
+  });
+
+  it('does not warn when focus() is not called on the accordion host', async () => {
+    const accordion = await fixture<Accordion>(html`
+      <sp-accordion>
+        <sp-accordion-item>Panel</sp-accordion-item>
+      </sp-accordion>
+    `);
+
+    await elementUpdated(accordion);
+
+    const focusWarnings = deprecationCalls().filter((call) =>
+      String(call.args[0]).includes('focus()')
+    );
+    expect(focusWarnings.length).to.equal(0);
+  });
+});
diff --git a/1st-gen/packages/accordion/test/dev-mode.test.ts b/1st-gen/packages/accordion/test/dev-mode.test.ts
index ab09e698da..4091093e4e 100644
--- a/1st-gen/packages/accordion/test/dev-mode.test.ts
+++ b/1st-gen/packages/accordion/test/dev-mode.test.ts
@@ -10,13 +10,46 @@
  * governing permissions and limitations under the License.
  */
 
-import { fixture } from '@open-wc/testing';
+import { elementUpdated, expect, fixture } from '@open-wc/testing';
+import { SinonStub, stub } from 'sinon';
 
 import { Accordion } from '@spectrum-web-components/accordion';
 
-import { testForLitDevWarnings } from '../../../test/testing-helpers.js';
 import { Default } from '../stories/accordion.stories.js';
 
 describe('Accordion - dev mode', () => {
-  testForLitDevWarnings(async () => await fixture<Accordion>(Default()));
+  describe('lit dev mode', () => {
+    let consoleWarnStub!: SinonStub;
+
+    before(() => {
+      consoleWarnStub = stub(console, 'warn');
+    });
+
+    afterEach(() => {
+      consoleWarnStub.resetHistory();
+    });
+
+    after(() => {
+      consoleWarnStub.restore();
+    });
+
+    it('does not emit non-deprecation warnings', async () => {
+      const el = await fixture<Accordion>(Default());
+
+      await elementUpdated(el);
+
+      const nonDeprecationCalls = consoleWarnStub
+        .getCalls()
+        .filter(
+          (call) =>
+            (call.args[call.args.length - 1] as { data?: { level?: string } })
+              ?.data?.level !== 'deprecation'
+        );
+
+      expect(
+        nonDeprecationCalls.length > 0,
+        nonDeprecationCalls[0]?.args.join(', ')
+      ).to.be.false;
+    });
+  });
 });
diff --git a/1st-gen/tools/base/src/version.d.ts b/1st-gen/tools/base/src/version.d.ts
index 6644135be1..aec04fff48 100644
--- a/1st-gen/tools/base/src/version.d.ts
+++ b/1st-gen/tools/base/src/version.d.ts
@@ -12,8 +12,8 @@
 /**
  * The version of the 1st-gen Spectrum Web Components library.
  */
-export declare const version = "1.11.2";
+export declare const version = "1.12.0";
 /**
  * The version of the core base package.
  */
-export declare const coreVersion = "0.0.4";
+export declare const coreVersion = "0.1.0";

From 737bd627fe036057f33e20c332f99c210375f62a Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 15:56:57 -0500
Subject: [PATCH 22/56] docs: jsdoc comments

---
 .../packages/core/components/accordion/Accordion.base.ts | 9 +++++++++
 .../core/components/accordion/AccordionItem.base.ts      | 5 +++++
 .../packages/swc/components/accordion/AccordionItem.ts   | 3 +++
 3 files changed, 17 insertions(+)

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.base.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 904e721ddd..883ad39f1e 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.base.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -29,6 +29,15 @@ import { AccordionItemBase } from './AccordionItem.base.js';
  * Base class for accordion components. Manages item propagation, heading
  * level, density, and the exclusive-open constraint.
  *
+ * @attribute {boolean} allowMultiple - Reflected as `allow-multiple`. When set,
+ *   multiple items may be open at the same time.
+ * @attribute {number} level - Heading level (2–6) applied to every item header.
+ *   Values outside that range are clamped.
+ * @attribute {AccordionSize} size - Size applied to all items.
+ * @attribute {AccordionDensity} density - Vertical spacing between items.
+ * @attribute {boolean} quiet - Renders the accordion in its quiet visual variant.
+ * @attribute {boolean} disabled - Disables all items in the accordion.
+ *
  * @slot - One or more `swc-accordion-item` elements.
  */
 export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
index c22793ad7b..92612b6e84 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
@@ -24,6 +24,11 @@ import {
  * Base class for accordion item components. Manages open/disabled state,
  * heading level (set by the parent accordion), and the toggle event.
  *
+ * @attribute {boolean} open - Whether the accordion item panel is expanded.
+ * @attribute {boolean} disabled - Whether the accordion item is disabled.
+ * @attribute {AccordionSize} size - Size of the item. Inherited from the parent
+ *   accordion when slotted; controls the chevron icon when used standalone.
+ *
  * @slot label - The heading text for this accordion item.
  * @slot actions - Optional actions rendered adjacent to the heading, outside
  *   the toggle button so they remain independently interactive.
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 5c8558398e..174047b716 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -31,6 +31,9 @@ import styles from './accordion.css';
  * @element swc-accordion-item
  * @since 2.0.0
  *
+ * @fires swc-accordion-item-toggle - Dispatched when the item open state is
+ *   toggled. Cancelable; `preventDefault()` reverts the change.
+ *
  * @example
  * <swc-accordion-item>
  *   <span slot="label">Section heading</span>

From 1975d7ee8bacc8f575735b29482c62dd7b8e294a Mon Sep 17 00:00:00 2001
From: Miwha Bonini <mbonini@adobe.com>
Date: Mon, 18 May 2026 15:25:27 -0600
Subject: [PATCH 23/56] chore(accordion): full fidelity feature update

---
 .../swc/components/accordion/AccordionItem.ts |   2 +-
 .../components/accordion/accordion-item.css   | 264 ++++++++++
 .../swc/components/accordion/accordion.css    |  36 +-
 .../accordion/stories/accordion.stories.ts    | 460 +++++++++++++++++-
 4 files changed, 744 insertions(+), 18 deletions(-)
 create mode 100644 2nd-gen/packages/swc/components/accordion/accordion-item.css

diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 08f733e66d..ac5fe2db9c 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -26,7 +26,7 @@ import { Chevron100Icon } from '../icon/elements/Chevron100Icon.js';
 import { Chevron200Icon } from '../icon/elements/Chevron200Icon.js';
 import { Chevron300Icon } from '../icon/elements/Chevron300Icon.js';
 
-import styles from './accordion.css';
+import styles from './accordion-item.css';
 
 /**
  * An accordion item component that wraps a single expandable content section.
diff --git a/2nd-gen/packages/swc/components/accordion/accordion-item.css b/2nd-gen/packages/swc/components/accordion/accordion-item.css
new file mode 100644
index 0000000000..0928199755
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/accordion-item.css
@@ -0,0 +1,264 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+:host {
+  --_swc-accordion-corner-radius: token("corner-radius-medium-size-medium");
+  --_swc-accordion-header-bg: transparent;
+  --_swc-accordion-header-text-color: token("neutral-content-color-default");
+
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  inline-size: 100%;
+  border-block-end: token("border-width-100") solid var(--swc-accordion-item-divider-color, var(--_swc-accordion-item-border-color, token("gray-200")));
+}
+
+:host(:first-child) {
+  border-block-start: token("border-width-100") solid var(--swc-accordion-item-divider-color, var(--_swc-accordion-item-border-color, token("gray-200")));
+}
+
+* {
+  box-sizing: border-box;
+}
+
+/* Unnamed slots default to display:contents, which makes slotted elements
+   participate directly in the host's flex layout. Setting display:block
+   keeps the accordion's slotted items in normal vertical flow. */
+slot:not([name]) {
+  display: block;
+  inline-size: 100%;
+}
+
+/* ── Heading reset (h2–h6 wrapping the button) ──────────────────────── */
+
+:is(h2, h3, h4, h5, h6) {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+  padding: 0;
+  margin: 0;
+  font: inherit;
+}
+
+/* ── Header button ──────────────────────────────────────────────────── */
+
+#header {
+  display: flex;
+  gap: token("accordion-disclosure-indicator-to-text-medium");
+  align-items: center;
+  inline-size: 100%;
+  padding-block: var(--_swc-accordion-pad-top-m, token("accordion-top-to-text-medium")) var(--_swc-accordion-pad-bottom-m, token("accordion-bottom-to-text-medium"));
+  padding-inline: token("accordion-edge-to-content-area-medium") token("accordion-edge-to-text");
+  font-family: token("sans-serif-font");
+  font-size: token("font-size-200");
+  font-weight: token("bold-font-weight");
+  line-height: token("line-height-100");
+  color: var(--_swc-accordion-header-text-color);
+  text-align: start;
+  background-color: var(--_swc-accordion-header-bg);
+  border: 0;
+  border-radius: var(--_swc-accordion-header-corner-radius, 0);
+  appearance: none;
+  cursor: pointer;
+}
+
+#header:focus {
+  outline: none;
+}
+
+/* The container sets the color tokens so they cascade into #header; the
+   outline and border-radius stay on the button so the focus ring matches
+   the hover footprint (toggle area only, independent of the actions slot). */
+:host:has(#header:focus-visible) {
+  --_swc-accordion-header-bg: token("transparent-black-100");
+  --_swc-accordion-header-text-color: token("neutral-content-color-key-focus");
+}
+
+#header:focus-visible {
+  border-radius: var(--_swc-accordion-corner-radius, token("corner-radius-medium-size-medium"));
+  outline: token("focus-indicator-thickness") solid token("focus-indicator-color");
+  outline-offset: calc(token("accordion-focus-indicator-gap") * -1);
+}
+
+@media (hover: hover) {
+  :host:has(#header:hover) {
+    --_swc-accordion-header-bg: token("transparent-black-100");
+    --_swc-accordion-header-text-color: token("neutral-content-color-hover");
+  }
+}
+
+:host:has(#header:active) {
+  --_swc-accordion-header-bg: token("transparent-black-300");
+  --_swc-accordion-header-text-color: token("neutral-content-color-down");
+}
+
+:host:has(#header[aria-disabled="true"]),
+:host:has(#header[aria-disabled="true"]:hover) {
+  --_swc-accordion-header-bg: transparent;
+  --_swc-accordion-header-text-color: token("disabled-content-color");
+}
+
+#header[aria-disabled="true"],
+#header[aria-disabled="true"]:hover {
+  cursor: default;
+}
+
+/* ── Disclosure indicator (chevron) ─────────────────────────────────── */
+
+/* Default size (m) — Chevron100 viewBox is 10×10 */
+.spectrum-Accordion-itemIndicator {
+  --swc-icon-inline-size: 10px;
+  --swc-icon-block-size: 10px;
+
+  flex-shrink: 0;
+  rotate: 0deg;
+  transition: rotate token("animation-duration-100") token("animation-ease-in-out");
+}
+
+/* Mirror for RTL so the chevron points left */
+:dir(rtl) .spectrum-Accordion-itemIndicator {
+  scale: -1 1;
+}
+
+/* Size: small — Chevron75 viewBox is 10×10 */
+:host([size="s"]) .spectrum-Accordion-itemIndicator {
+  --swc-icon-inline-size: 10px;
+  --swc-icon-block-size: 10px;
+}
+
+/* Size: large — Chevron200 viewBox is 12×12 */
+:host([size="l"]) .spectrum-Accordion-itemIndicator {
+  --swc-icon-inline-size: 12px;
+  --swc-icon-block-size: 12px;
+}
+
+/* Size: extra-large — Chevron300 viewBox is 14×14 */
+:host([size="xl"]) .spectrum-Accordion-itemIndicator {
+  --swc-icon-inline-size: 14px;
+  --swc-icon-block-size: 14px;
+}
+
+:host([open]) .spectrum-Accordion-itemIndicator {
+  rotate: 90deg;
+}
+
+/* RTL + open: rotate the opposite direction */
+:host([open]):dir(rtl) .spectrum-Accordion-itemIndicator {
+  rotate: -90deg;
+}
+
+/* ── Item title (heading slot wrapper) ──────────────────────────────── */
+
+.spectrum-Accordion-itemTitle {
+  flex: 1;
+}
+
+/* ── Direct actions (inline with heading, outside the toggle area) ───── */
+
+.spectrum-Accordion-itemDirectActions {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  align-self: center;
+}
+
+/* ── Content panel ──────────────────────────────────────────────────── */
+
+.spectrum-Accordion-itemContent {
+  display: none;
+  flex: 0 0 100%;
+  padding-block: token("accordion-content-area-top-to-content") token("accordion-content-area-bottom-to-content");
+  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-medium"));
+  font-family: token("sans-serif-font");
+  font-size: token("font-size-100");
+  font-weight: token("regular-font-weight");
+  line-height: token("line-height-100");
+  color: token("neutral-subdued-content-color-default");
+}
+
+:host([open]) .spectrum-Accordion-itemContent {
+  display: block;
+}
+
+/* ── Size: small ────────────────────────────────────────────────────── */
+
+:host([size="s"]) {
+  --_swc-accordion-corner-radius: token("corner-radius-medium-size-small");
+}
+
+:host([size="s"]) #header {
+  gap: token("accordion-disclosure-indicator-to-text-small");
+  padding-block: var(--_swc-accordion-pad-top-s, token("accordion-top-to-text-small")) var(--_swc-accordion-pad-bottom-s, token("accordion-bottom-to-text-small"));
+  padding-inline-start: token("accordion-edge-to-content-area-small");
+  font-size: token("font-size-100");
+}
+
+:host([size="s"]) .spectrum-Accordion-itemContent {
+  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-small"));
+}
+
+/* ── Size: large ────────────────────────────────────────────────────── */
+
+:host([size="l"]) {
+  --_swc-accordion-corner-radius: token("corner-radius-medium-size-large");
+}
+
+:host([size="l"]) #header {
+  gap: token("accordion-disclosure-indicator-to-text-large");
+  padding-block: var(--_swc-accordion-pad-top-l, token("accordion-top-to-text-large")) var(--_swc-accordion-pad-bottom-l, token("accordion-bottom-to-text-large"));
+  padding-inline-start: token("accordion-edge-to-content-area-large");
+  font-size: token("font-size-300");
+}
+
+:host([size="l"]) .spectrum-Accordion-itemContent {
+  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-large"));
+}
+
+/* ── Size: extra-large ──────────────────────────────────────────────── */
+
+:host([size="xl"]) {
+  --_swc-accordion-corner-radius: token("corner-radius-medium-size-extra-large");
+}
+
+:host([size="xl"]) #header {
+  gap: token("accordion-disclosure-indicator-to-text-extra-large");
+  padding-block: var(--_swc-accordion-pad-top-xl, token("accordion-top-to-text-extra-large")) var(--_swc-accordion-pad-bottom-xl, token("accordion-bottom-to-text-extra-large"));
+  padding-inline-start: token("accordion-edge-to-content-area-extra-large");
+  font-size: token("font-size-400");
+}
+
+:host([size="xl"]) .spectrum-Accordion-itemContent {
+  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-extra-large"));
+}
+
+/* ── Forced colors ──────────────────────────────────────────────────── */
+
+@media (forced-colors: active) {
+  :host {
+    /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
+    border-color: ButtonText;
+  }
+
+  #header {
+    /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
+    color: ButtonText;
+  }
+
+  #header:focus-visible {
+    /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
+    outline-color: Highlight;
+  }
+
+  #header[aria-disabled="true"] {
+    /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
+    color: GrayText;
+  }
+}
diff --git a/2nd-gen/packages/swc/components/accordion/accordion.css b/2nd-gen/packages/swc/components/accordion/accordion.css
index 40f33594a2..94dcc5913a 100644
--- a/2nd-gen/packages/swc/components/accordion/accordion.css
+++ b/2nd-gen/packages/swc/components/accordion/accordion.css
@@ -10,4 +10,38 @@
  * governing permissions and limitations under the License.
  */
 
-/* S2 token imports and selector definitions land here in Phase 4. */
+:host {
+  display: block;
+  inline-size: 100%;
+  min-inline-size: var(--swc-accordion-min-inline-size, token("accordion-minimum-width"));
+}
+
+/* Compact density — overrides cascade to child items */
+:host([density="compact"]) {
+  --_swc-accordion-pad-top-s: token("accordion-top-to-text-compact-small");
+  --_swc-accordion-pad-top-m: token("accordion-top-to-text-compact-medium");
+  --_swc-accordion-pad-top-l: token("accordion-top-to-text-compact-large");
+  --_swc-accordion-pad-top-xl: token("accordion-top-to-text-compact-extra-large");
+  --_swc-accordion-pad-bottom-s: token("accordion-bottom-to-text-compact-small");
+  --_swc-accordion-pad-bottom-m: token("accordion-bottom-to-text-compact-medium");
+  --_swc-accordion-pad-bottom-l: token("accordion-bottom-to-text-compact-large");
+  --_swc-accordion-pad-bottom-xl: token("accordion-bottom-to-text-compact-extra-large");
+}
+
+/* Spacious density — overrides cascade to child items */
+:host([density="spacious"]) {
+  --_swc-accordion-pad-top-s: token("accordion-top-to-text-spacious-small");
+  --_swc-accordion-pad-top-m: token("accordion-top-to-text-spacious-medium");
+  --_swc-accordion-pad-top-l: token("accordion-top-to-text-spacious-large");
+  --_swc-accordion-pad-top-xl: token("accordion-top-to-text-spacious-extra-large");
+  --_swc-accordion-pad-bottom-s: token("accordion-bottom-to-text-spacious-small");
+  --_swc-accordion-pad-bottom-m: token("accordion-bottom-to-text-spacious-medium");
+  --_swc-accordion-pad-bottom-l: token("accordion-bottom-to-text-spacious-large");
+  --_swc-accordion-pad-bottom-xl: token("accordion-bottom-to-text-spacious-extra-large");
+}
+
+/* Quiet — removes dividers and enables rounded corners on hover */
+:host([quiet]) {
+  --_swc-accordion-item-border-color: transparent;
+  --_swc-accordion-header-corner-radius: var(--_swc-accordion-corner-radius);
+}
diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index 4284e11925..49c5f49913 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -16,6 +16,7 @@ import { getStorybookHelpers } from '@wc-toolkit/storybook-helpers';
 
 import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
 import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
+import '@adobe/spectrum-wc/components/button/swc-button.js';
 
 import {
   ACCORDION_DENSITIES,
@@ -60,25 +61,26 @@ argTypes.level = {
   },
 };
 
+const content = {
+  personal: 'Manage your name, email address, and contact details.',
+  billing:
+    'Your billing address is used to verify your payment method and calculate taxes.',
+  shipping: 'Physical products and documents are sent to this address.',
+  payment: 'Contact your administrator to update payment information.',
+};
+
 const defaultItems = html`
   <swc-accordion-item>
-    <span slot="label">Alchemy</span>
-    Alchemy is an ancient branch of natural philosophy, a philosophical and
-    protoscientific tradition that was historically practiced in China, India,
-    the Muslim world, and Europe.
-  </swc-accordion-item>
-  <swc-accordion-item>
-    <span slot="label">Astrology</span>
-    Astrology is a range of divinatory practices, recognized as pseudoscientific
-    since the 18th century, that propose that information about human affairs
-    and terrestrial events may be discerned by studying the apparent positions
-    of celestial objects.
+    <span slot="label">Personal information</span>
+    ${content.personal}
   </swc-accordion-item>
   <swc-accordion-item open>
-    <span slot="label">Natural magic</span>
-    Natural magic in the context of early modern Europe was a branch of
-    philosophy that treated occult forces as resulting from natural causes, not
-    from divine or demonic intervention.
+    <span slot="label">Billing address</span>
+    ${content.billing}
+  </swc-accordion-item>
+  <swc-accordion-item>
+    <span slot="label">Shipping address</span>
+    ${content.shipping}
   </swc-accordion-item>
 `;
 
@@ -86,14 +88,23 @@ const defaultItems = html`
  * An accordion groups related content sections, each behind a header that can
  * be expanded or collapsed. Only one section is open at a time by default;
  * set `allow-multiple` to let any number of sections be open simultaneously.
+ *
+ * Items support an **`actions` slot** for placing interactive controls — such
+ * as an edit button — directly in the header row, outside the toggle button so
+ * they remain independently clickable.
  */
 const meta: Meta = {
   title: 'Accordion',
   component: 'swc-accordion',
   args,
   argTypes,
-  render: (args) => template(args, defaultItems),
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template(args, defaultItems)}
+    </div>
+  `,
   parameters: {
+    layout: 'centered',
     actions: { handles: [SWC_ACCORDION_ITEM_TOGGLE_EVENT] },
     docs: {
       subtitle: 'Groups related content sections behind expandable headers.',
@@ -125,3 +136,420 @@ export const Overview: Story = {
   },
   tags: ['overview'],
 };
+
+// ──────────────────────────
+//    ANATOMY STORIES
+// ──────────────────────────
+
+const anatomyItems = html`
+  <swc-accordion-item open>
+    <span slot="label">Personal information</span>
+    ${content.personal}
+  </swc-accordion-item>
+  <swc-accordion-item>
+    <span slot="label">Billing address</span>
+    <swc-button
+      slot="actions"
+      variant="secondary"
+      fill-style="outline"
+      size="s"
+    >
+      Edit
+    </swc-button>
+    ${content.billing}
+  </swc-accordion-item>
+`;
+
+/**
+ * A `<swc-accordion>` item exposes three content surfaces:
+ *
+ * - **`label` slot**: The heading text shown in the collapsed and expanded header
+ * - **`actions` slot**: Optional interactive controls placed outside the toggle
+ *   button so they remain independently clickable (see the second item below)
+ * - **Default slot**: The panel body revealed when the item expands
+ */
+export const Anatomy: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template(args, anatomyItems)}
+    </div>
+  `,
+  tags: ['anatomy'],
+};
+
+// ──────────────────────────
+//    OPTIONS STORIES
+// ──────────────────────────
+
+/**
+ * Accordions come in four sizes to fit different layout contexts.
+ */
+export const Sizes: Story = {
+  render: (args) => html`
+    <div
+      style="display: flex; flex-direction: column; gap: 16px; inline-size: 720px; max-inline-size: 100%;"
+    >
+      ${ACCORDION_VALID_SIZES.map(
+        (size) => html`
+          ${template(
+            { ...args, size },
+            html`
+              <swc-accordion-item>
+                <span slot="label">Personal information (size=${size})</span>
+                ${content.personal}
+              </swc-accordion-item>
+            `
+          )}
+        `
+      )}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['options'],
+  parameters: { 'section-order': 1 },
+};
+
+/**
+ * Density controls the vertical spacing between items and within each header.
+ *
+ * - **Compact**: Tighter spacing for data-dense interfaces
+ * - **Regular**: The default, suitable for most contexts
+ * - **Spacious**: More breathing room for content-focused layouts
+ */
+export const Density: Story = {
+  render: (args) => html`
+    <div
+      style="display: flex; flex-direction: column; gap: 16px; inline-size: 720px; max-inline-size: 100%;"
+    >
+      ${ACCORDION_DENSITIES.map(
+        (density) => html`
+          ${template(
+            { ...args, density },
+            html`
+              <swc-accordion-item>
+                <span slot="label">
+                  Personal information (density=${density})
+                </span>
+                ${content.personal}
+              </swc-accordion-item>
+            `
+          )}
+        `
+      )}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['options'],
+  parameters: { 'section-order': 2 },
+};
+
+/**
+ * The `quiet` variant removes the divider borders for a lighter visual style,
+ * and adds rounded corners on hover for a contained feel.
+ */
+export const Quiet: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template({ ...args, quiet: true }, defaultItems)}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['options'],
+  parameters: { 'section-order': 3 },
+};
+
+/**
+ * The `level` attribute sets the heading level (h2–h6) applied to every item
+ * header. Use it to fit the accordion into the surrounding page heading
+ * hierarchy without changing the visual style.
+ */
+export const HeadingLevel: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template({ ...args, level: 2 }, defaultItems)}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['options'],
+  parameters: { 'section-order': 4 },
+};
+
+// ──────────────────────────
+//    STATES STORIES
+// ──────────────────────────
+
+const stateItems = html`
+  <swc-accordion-item>
+    <span slot="label">Personal information</span>
+    ${content.personal}
+  </swc-accordion-item>
+  <swc-accordion-item open>
+    <span slot="label">Billing address</span>
+    ${content.billing}
+  </swc-accordion-item>
+  <swc-accordion-item disabled>
+    <span slot="label">Payment method</span>
+    ${content.payment}
+  </swc-accordion-item>
+`;
+
+/**
+ * Items can be in a default (collapsed), open (expanded), or disabled state.
+ * A disabled item remains in the tab order but its toggle is blocked.
+ */
+export const ItemStates: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template({ ...args, 'allow-multiple': true }, stateItems)}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['states'],
+  parameters: { 'section-order': 1 },
+};
+
+/**
+ * Setting `disabled` on the `<swc-accordion>` parent disables all items at
+ * once without overwriting individual item disabled state. Re-enabling the
+ * accordion restores each item's original state.
+ */
+export const DisabledAccordion: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template({ ...args, disabled: true }, defaultItems)}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['states'],
+  parameters: { 'section-order': 2 },
+};
+
+/**
+ * When the accordion host is `disabled`, all items become non-interactive
+ * regardless of their individual `disabled` state. Per-item `disabled` is
+ * preserved underneath: toggle the **disabled** control off and the third
+ * item remains disabled while the first two become interactive again.
+ *
+ * This separation means an item that was already disabled before the
+ * host was disabled does not silently become enabled when the host
+ * is re-enabled.
+ */
+export const MixedDisabledStates: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template(
+        { ...args, disabled: true, 'allow-multiple': true },
+        html`
+          <swc-accordion-item open>
+            <span slot="label">Personal information</span>
+            ${content.personal}
+          </swc-accordion-item>
+          <swc-accordion-item>
+            <span slot="label">Billing address</span>
+            ${content.billing}
+          </swc-accordion-item>
+          <swc-accordion-item disabled>
+            <span slot="label">Payment method</span>
+            ${content.payment}
+          </swc-accordion-item>
+        `
+      )}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['states'],
+  parameters: { 'section-order': 3 },
+};
+
+// ──────────────────────────────
+//    BEHAVIORS STORIES
+// ──────────────────────────────
+
+const directActionsItems = html`
+  <swc-accordion-item open>
+    <span id="label-personal" slot="label">Personal information</span>
+    <swc-button
+      slot="actions"
+      variant="secondary"
+      fill-style="outline"
+      size="s"
+      aria-describedby="label-personal"
+    >
+      Edit
+    </swc-button>
+    ${content.personal}
+  </swc-accordion-item>
+  <swc-accordion-item>
+    <span id="label-billing" slot="label">Billing address</span>
+    <swc-button
+      slot="actions"
+      variant="secondary"
+      fill-style="outline"
+      size="s"
+      aria-describedby="label-billing"
+    >
+      Edit
+    </swc-button>
+    ${content.billing}
+  </swc-accordion-item>
+  <swc-accordion-item>
+    <span id="label-shipping" slot="label">Shipping address</span>
+    <swc-button
+      slot="actions"
+      variant="secondary"
+      fill-style="outline"
+      size="s"
+      aria-describedby="label-shipping"
+    >
+      Edit
+    </swc-button>
+    ${content.shipping}
+  </swc-accordion-item>
+`;
+
+/**
+ * Place interactive controls in the **`actions` slot** to render them inline
+ * with the heading, outside the toggle button. This keeps them independently
+ * clickable without expanding or collapsing the item.
+ *
+ * The component automatically stops click and keydown propagation from the
+ * actions container so action buttons never accidentally trigger the toggle.
+ */
+export const DirectActions: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template(args, directActionsItems)}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['behaviors'],
+  parameters: { 'section-order': 1 },
+};
+
+const allowMultipleItems = html`
+  <swc-accordion-item open>
+    <span slot="label">Personal information</span>
+    ${content.personal}
+  </swc-accordion-item>
+  <swc-accordion-item open>
+    <span slot="label">Billing address</span>
+    ${content.billing}
+  </swc-accordion-item>
+  <swc-accordion-item>
+    <span slot="label">Shipping address</span>
+    ${content.shipping}
+  </swc-accordion-item>
+`;
+
+/**
+ * By default only one item may be open at a time; opening a new item closes
+ * the previously open one. Set `allow-multiple` to allow any number of items
+ * to be open simultaneously.
+ */
+export const AllowMultiple: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template({ ...args, 'allow-multiple': true }, allowMultipleItems)}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['behaviors'],
+  parameters: { 'section-order': 2 },
+};
+
+/**
+ * Every expand or collapse dispatches a `swc-accordion-item-toggle` event from
+ * the item. The event bubbles and is composed, so a single listener on the
+ * `<swc-accordion>` can observe all items. It is cancelable; calling
+ * `preventDefault()` reverts the open state.
+ *
+ * Open the **Actions** panel in Storybook to observe events as you interact
+ * with the accordion below.
+ */
+export const ToggleEvent: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template(args, defaultItems)}
+    </div>
+  `,
+  args: { density: 'regular' },
+  tags: ['behaviors'],
+  parameters: { 'section-order': 3 },
+};
+
+// ────────────────────────────────
+//    ACCESSIBILITY STORIES
+// ────────────────────────────────
+
+const a11yItems = html`
+  <swc-accordion-item open>
+    <span id="a11y-label-personal" slot="label">Personal information</span>
+    <swc-button
+      slot="actions"
+      variant="secondary"
+      fill-style="outline"
+      size="s"
+      aria-describedby="a11y-label-personal"
+    >
+      Edit
+    </swc-button>
+    ${content.personal}
+  </swc-accordion-item>
+  <swc-accordion-item>
+    <span slot="label">Billing address</span>
+    ${content.billing}
+  </swc-accordion-item>
+  <swc-accordion-item disabled>
+    <span slot="label">Payment method</span>
+    ${content.payment}
+  </swc-accordion-item>
+`;
+
+/**
+ * ### Features
+ *
+ * The `<swc-accordion>` and `<swc-accordion-item>` elements implement several
+ * accessibility features:
+ *
+ * #### Keyboard navigation
+ *
+ * - <kbd>Tab</kbd>: Moves focus to the next focusable element; header buttons
+ *   and `actions` slot controls each have their own tab stop
+ * - <kbd>Enter</kbd> or <kbd>Space</kbd>: Expands or collapses the focused header
+ * - <kbd>Tab</kbd> past an actions button: Continues to the next item header
+ *   without affecting accordion state
+ *
+ * #### ARIA implementation
+ *
+ * 1. **Role**: Each header is a `<button>` inside a heading element (`h2`–`h6`,
+ *    controlled by the `level` attribute), satisfying the disclosure widget pattern
+ * 2. **Expanded state**: `aria-expanded="true/false"` on the header button
+ *    announces open or closed to screen readers
+ * 3. **Panel region**: The content `<div>` carries `role="region"` and
+ *    `aria-labelledby` pointing to its header button, naming the region for
+ *    landmark navigation
+ * 4. **Disabled state**: `aria-disabled="true"` is set instead of the native
+ *    `disabled` attribute, keeping the header in the tab order while blocking
+ *    toggle interactions
+ * 5. **Actions isolation**: Clicks and keydown events on the actions container
+ *    are stopped from propagating, so action buttons never accidentally trigger
+ *    the accordion toggle
+ *
+ * ### Best practices
+ *
+ * - Set the `level` attribute to match the surrounding page heading hierarchy
+ *   so the structure makes sense to screen reader users navigating by headings
+ * - Provide a descriptive `label` slot value that identifies the section
+ *   content; avoid generic labels like "Section 1"
+ * - When using the `actions` slot, give each button a visible label or
+ *   `aria-label` that conveys its purpose independent of the heading text
+ */
+export const Accessibility: Story = {
+  render: (args) => html`
+    <div style="inline-size: 720px; max-inline-size: 100%;">
+      ${template(args, a11yItems)}
+    </div>
+  `,
+  args: { density: 'regular', level: 3 },
+  tags: ['a11y'],
+};

From c6495a58cc09b4882006565193fcc0999fab3775 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 20:27:38 -0500
Subject: [PATCH 24/56] chore: changeset

---
 .changeset/accordion-2nd-gen-and-deprecations.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 .changeset/accordion-2nd-gen-and-deprecations.md

diff --git a/.changeset/accordion-2nd-gen-and-deprecations.md b/.changeset/accordion-2nd-gen-and-deprecations.md
new file mode 100644
index 0000000000..0a7e503041
--- /dev/null
+++ b/.changeset/accordion-2nd-gen-and-deprecations.md
@@ -0,0 +1,15 @@
+---
+'@adobe/spectrum-wc': minor
+'@spectrum-web-components/accordion': patch
+---
+
+**feat(accordion):** Add 2nd-gen `<swc-accordion>` and `<swc-accordion-item>` with Spectrum 2-oriented behavior. Key changes from 1st-gen `<sp-accordion>` / `<sp-accordion-item>`:
+
+- Core `AccordionBase` / `AccordionItemBase` with public API: `allow-multiple`, `level`, `size`, `density`, `quiet`, host `disabled`, item `open` / `disabled`, slotted heading (`slot="label"`), optional `slot="actions"`, and cancellable `swc-accordion-item-toggle`
+- APG-aligned accessibility: `<h*>` wrapping a native header `<button>`, `aria-expanded` / `aria-controls`, `role="region"` + `aria-labelledby`, closed panels use `hidden`, disabled items use `aria-disabled` on the header and `inert` on the panel (no roving `tabindex` or arrow-key header navigation)
+- Space on the header calls `preventDefault()` and toggles without scrolling overflow containers (SWC-1487)
+- Controlled `open` is frozen while the host or item is disabled (imperative assignment cannot expand or collapse)
+- Storybook play tests for ARIA contract, toggle/cancel, exclusive open, host and item disabled, Space, and heading level propagation
+- `Chevron300Icon` for `xl` item sizing
+
+**chore(accordion):** Add Spectrum 2 deprecation warnings in dev mode on 1st-gen accordion for `label`, item `level`, and host `focus()`, with matching tests.

From 329b428b4de91ec5fdb4f5081f9bbb8556b2d155 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 20:28:56 -0500
Subject: [PATCH 25/56] fix: revert 1st-gen refactor work

---
 1st-gen/packages/accordion/src/Accordion.ts | 34 ++++++++++++---------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/1st-gen/packages/accordion/src/Accordion.ts b/1st-gen/packages/accordion/src/Accordion.ts
index 4b8b9ee93e..c92a4d13b1 100644
--- a/1st-gen/packages/accordion/src/Accordion.ts
+++ b/1st-gen/packages/accordion/src/Accordion.ts
@@ -114,23 +114,19 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     });
   }
 
-  private syncAssignedItem(item: AccordionItem): void {
-    if (window.__swc?.DEBUG && item.level !== this.level) {
-      window.__swc.warn(
-        item,
-        `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
-        ACCORDION_MIGRATION_DOC_URL,
-        { level: 'deprecation' }
-      );
-    }
-    item.size = this.size;
-    item.level = this.level;
-  }
-
   private handleSlotchange(): void {
     this.focusGroupController.clearElementCache();
     this.items.forEach((item) => {
-      this.syncAssignedItem(item);
+      if (window.__swc?.DEBUG && item.level !== this.level) {
+        window.__swc.warn(
+          item,
+          `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
+          ACCORDION_MIGRATION_DOC_URL,
+          { level: 'deprecation' }
+        );
+      }
+      item.size = this.size;
+      item.level = this.level;
     });
   }
 
@@ -143,7 +139,15 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     }
     if (changed.has('level')) {
       this.items.forEach((item) => {
-        this.syncAssignedItem(item);
+        if (window.__swc?.DEBUG && item.level !== this.level) {
+          window.__swc.warn(
+            item,
+            `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
+            ACCORDION_MIGRATION_DOC_URL,
+            { level: 'deprecation' }
+          );
+        }
+        item.level = this.level;
       });
     }
   }

From c6341e304802e85d3782300c3a07a18bb6094831 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Tue, 19 May 2026 09:46:12 -0500
Subject: [PATCH 26/56] chore(accordion): defer tests, deprecations, and
 changeset to part two

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../accordion-2nd-gen-and-deprecations.md     |  15 -
 1st-gen/packages/accordion/src/Accordion.ts   |  31 -
 .../packages/accordion/src/AccordionItem.ts   |  20 +-
 .../accordion/test/deprecation.test.ts        | 134 ----
 .../packages/accordion/test/dev-mode.test.ts  |  39 +-
 1st-gen/tools/base/src/version.d.ts           |   4 +-
 .../accordion/stories/accordion.stories.ts    |  66 --
 .../swc/components/accordion/test/.gitkeep    |   1 +
 .../accordion/test/accordion.test.ts          | 702 ------------------
 9 files changed, 7 insertions(+), 1005 deletions(-)
 delete mode 100644 .changeset/accordion-2nd-gen-and-deprecations.md
 delete mode 100644 1st-gen/packages/accordion/test/deprecation.test.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/test/.gitkeep
 delete mode 100644 2nd-gen/packages/swc/components/accordion/test/accordion.test.ts

diff --git a/.changeset/accordion-2nd-gen-and-deprecations.md b/.changeset/accordion-2nd-gen-and-deprecations.md
deleted file mode 100644
index 0a7e503041..0000000000
--- a/.changeset/accordion-2nd-gen-and-deprecations.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-'@adobe/spectrum-wc': minor
-'@spectrum-web-components/accordion': patch
----
-
-**feat(accordion):** Add 2nd-gen `<swc-accordion>` and `<swc-accordion-item>` with Spectrum 2-oriented behavior. Key changes from 1st-gen `<sp-accordion>` / `<sp-accordion-item>`:
-
-- Core `AccordionBase` / `AccordionItemBase` with public API: `allow-multiple`, `level`, `size`, `density`, `quiet`, host `disabled`, item `open` / `disabled`, slotted heading (`slot="label"`), optional `slot="actions"`, and cancellable `swc-accordion-item-toggle`
-- APG-aligned accessibility: `<h*>` wrapping a native header `<button>`, `aria-expanded` / `aria-controls`, `role="region"` + `aria-labelledby`, closed panels use `hidden`, disabled items use `aria-disabled` on the header and `inert` on the panel (no roving `tabindex` or arrow-key header navigation)
-- Space on the header calls `preventDefault()` and toggles without scrolling overflow containers (SWC-1487)
-- Controlled `open` is frozen while the host or item is disabled (imperative assignment cannot expand or collapse)
-- Storybook play tests for ARIA contract, toggle/cancel, exclusive open, host and item disabled, Space, and heading level propagation
-- `Chevron300Icon` for `xl` item sizing
-
-**chore(accordion):** Add Spectrum 2 deprecation warnings in dev mode on 1st-gen accordion for `label`, item `level`, and host `focus()`, with matching tests.
diff --git a/1st-gen/packages/accordion/src/Accordion.ts b/1st-gen/packages/accordion/src/Accordion.ts
index c92a4d13b1..6ec2dae9ad 100644
--- a/1st-gen/packages/accordion/src/Accordion.ts
+++ b/1st-gen/packages/accordion/src/Accordion.ts
@@ -27,9 +27,6 @@ import { FocusGroupController } from '@spectrum-web-components/reactive-controll
 import styles from './accordion.css.js';
 import { AccordionItem } from './AccordionItem.js';
 
-const ACCORDION_MIGRATION_DOC_URL =
-  'https://opensource.adobe.com/spectrum-web-components/components/accordion/';
-
 /**
  * @element sp-accordion
  * @slot - The sp-accordion-item children to display.
@@ -75,19 +72,7 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     isFocusableElement: (el: AccordionItem) => !el.disabled,
   });
 
-  /**
-   * @deprecated `focus()` on `<sp-accordion>` is deprecated and will be removed
-   * in Spectrum 2. Focus the header button inside `<sp-accordion-item>` instead.
-   */
   public override focus(): void {
-    if (window.__swc?.DEBUG) {
-      window.__swc.warn(
-        this,
-        `<${this.localName}> focus() is deprecated and will be removed in Spectrum 2. Focus the header button inside <sp-accordion-item> instead.`,
-        ACCORDION_MIGRATION_DOC_URL,
-        { level: 'deprecation' }
-      );
-    }
     this.focusGroupController.focus();
   }
 
@@ -117,14 +102,6 @@ export class Accordion extends SizedMixin(SpectrumElement, {
   private handleSlotchange(): void {
     this.focusGroupController.clearElementCache();
     this.items.forEach((item) => {
-      if (window.__swc?.DEBUG && item.level !== this.level) {
-        window.__swc.warn(
-          item,
-          `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
-          ACCORDION_MIGRATION_DOC_URL,
-          { level: 'deprecation' }
-        );
-      }
       item.size = this.size;
       item.level = this.level;
     });
@@ -139,14 +116,6 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     }
     if (changed.has('level')) {
       this.items.forEach((item) => {
-        if (window.__swc?.DEBUG && item.level !== this.level) {
-          window.__swc.warn(
-            item,
-            `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
-            ACCORDION_MIGRATION_DOC_URL,
-            { level: 'deprecation' }
-          );
-        }
         item.level = this.level;
       });
     }
diff --git a/1st-gen/packages/accordion/src/AccordionItem.ts b/1st-gen/packages/accordion/src/AccordionItem.ts
index 3857ce908d..80dd83bbe2 100644
--- a/1st-gen/packages/accordion/src/AccordionItem.ts
+++ b/1st-gen/packages/accordion/src/AccordionItem.ts
@@ -61,13 +61,10 @@ const chevronIcon: Record<string, () => TemplateResult> = {
   `,
 };
 
-const ACCORDION_MIGRATION_DOC_URL =
-  'https://opensource.adobe.com/spectrum-web-components/components/accordion/';
-
 /**
  * @element sp-accordion-item
  * @slot - The content of the item that is hidden when the item is not open
- * @fires sp-accordion-item-toggle - Announce that an accordion item has been toggled while allowing the event to be cancelled. In Spectrum 2, this event is renamed to `swc-accordion-item-toggle`.
+ * @fires sp-accordion-item-toggle - Announce that an accordion item has been toggled while allowing the event to be cancelled.
  */
 export class AccordionItem extends SizedMixin(Focusable, {
   noDefaultSize: true,
@@ -79,10 +76,6 @@ export class AccordionItem extends SizedMixin(Focusable, {
   @property({ type: Boolean, reflect: true })
   public open = false;
 
-  /**
-   * @deprecated The `label` attribute is deprecated and will be removed in
-   * Spectrum 2.
-   */
   @property({ type: String, reflect: true })
   public label = '';
 
@@ -93,9 +86,6 @@ export class AccordionItem extends SizedMixin(Focusable, {
    * The heading level (2-6) to use for the accordion item title.
    * This property is set by the parent sp-accordion element.
    * Defaults to 3.
-   *
-   * @deprecated The `level` attribute on accordion items is deprecated and will
-   * be removed in Spectrum 2. Use `level` on `<sp-accordion>` instead.
    */
   @property({ type: Number, reflect: true })
   public level: number = 3;
@@ -192,13 +182,5 @@ export class AccordionItem extends SizedMixin(Focusable, {
         this.removeAttribute('aria-disabled');
       }
     }
-    if (window.__swc?.DEBUG && changes.has('label') && this.label) {
-      window.__swc.warn(
-        this,
-        `<${this.localName}> the "label" attribute is deprecated and will be removed in Spectrum 2.`,
-        ACCORDION_MIGRATION_DOC_URL,
-        { level: 'deprecation' }
-      );
-    }
   }
 }
diff --git a/1st-gen/packages/accordion/test/deprecation.test.ts b/1st-gen/packages/accordion/test/deprecation.test.ts
deleted file mode 100644
index dab3a9e5d4..0000000000
--- a/1st-gen/packages/accordion/test/deprecation.test.ts
+++ /dev/null
@@ -1,134 +0,0 @@
-/**
- * Copyright 2026 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-
-import { elementUpdated, expect, fixture, html } from '@open-wc/testing';
-import { SinonSpyCall, SinonStub, stub } from 'sinon';
-
-import { Accordion, AccordionItem } from '@spectrum-web-components/accordion';
-
-import '@spectrum-web-components/accordion/sp-accordion.js';
-import '@spectrum-web-components/accordion/sp-accordion-item.js';
-
-describe('Accordion - deprecation warnings', () => {
-  let consoleWarnStub!: SinonStub;
-
-  before(() => {
-    consoleWarnStub = stub(console, 'warn');
-  });
-
-  afterEach(() => {
-    consoleWarnStub.resetHistory();
-  });
-
-  after(() => {
-    consoleWarnStub.restore();
-  });
-
-  const deprecationCalls = (): SinonSpyCall[] =>
-    consoleWarnStub
-      .getCalls()
-      .filter(
-        (call) =>
-          (call.args[call.args.length - 1] as { data?: { level?: string } })
-            ?.data?.level === 'deprecation'
-      );
-
-  const expectDeprecationData = (
-    call: SinonSpyCall,
-    localName: 'sp-accordion' | 'sp-accordion-item'
-  ): void => {
-    expect(
-      call.args[call.args.length - 1],
-      'confirm `data` shape'
-    ).to.deep.equal({
-      data: {
-        localName,
-        type: 'api',
-        level: 'deprecation',
-      },
-    });
-  };
-
-  it('warns about deprecated "label" attribute', async () => {
-    const item = await fixture<AccordionItem>(html`
-      <sp-accordion-item label="Section"></sp-accordion-item>
-    `);
-
-    await elementUpdated(item);
-
-    expect(consoleWarnStub.called).to.be.true;
-    const labelCall = deprecationCalls().find((call) =>
-      String(call.args[0]).includes('"label"')
-    );
-    expect(labelCall, 'label deprecation warn fired').to.exist;
-    expect(
-      String(labelCall!.args[0]).includes('deprecated'),
-      'confirm deprecation message'
-    ).to.be.true;
-    expect(
-      String(labelCall!.args[0]).includes('Spectrum 2'),
-      'confirm Spectrum 2 timeline'
-    ).to.be.true;
-    expectDeprecationData(labelCall!, 'sp-accordion-item');
-  });
-
-  it('does not warn when label is empty', async () => {
-    const item = await fixture<AccordionItem>(html`
-      <sp-accordion-item></sp-accordion-item>
-    `);
-
-    await elementUpdated(item);
-
-    expect(deprecationCalls().length).to.equal(0);
-  });
-
-  it('warns when focus() is called on the accordion host', async () => {
-    const accordion = await fixture<Accordion>(html`
-      <sp-accordion>
-        <sp-accordion-item label="Section">Panel</sp-accordion-item>
-      </sp-accordion>
-    `);
-
-    await elementUpdated(accordion);
-    consoleWarnStub.resetHistory();
-    accordion.focus();
-
-    const focusCall = deprecationCalls().find((call) =>
-      String(call.args[0]).includes('focus()')
-    );
-    expect(focusCall, 'focus deprecation warn fired').to.exist;
-    expect(
-      String(focusCall!.args[0]).includes('deprecated'),
-      'confirm deprecation message'
-    ).to.be.true;
-    expect(
-      String(focusCall!.args[0]).includes('Spectrum 2'),
-      'confirm Spectrum 2 timeline'
-    ).to.be.true;
-    expectDeprecationData(focusCall!, 'sp-accordion');
-  });
-
-  it('does not warn when focus() is not called on the accordion host', async () => {
-    const accordion = await fixture<Accordion>(html`
-      <sp-accordion>
-        <sp-accordion-item>Panel</sp-accordion-item>
-      </sp-accordion>
-    `);
-
-    await elementUpdated(accordion);
-
-    const focusWarnings = deprecationCalls().filter((call) =>
-      String(call.args[0]).includes('focus()')
-    );
-    expect(focusWarnings.length).to.equal(0);
-  });
-});
diff --git a/1st-gen/packages/accordion/test/dev-mode.test.ts b/1st-gen/packages/accordion/test/dev-mode.test.ts
index 4091093e4e..ab09e698da 100644
--- a/1st-gen/packages/accordion/test/dev-mode.test.ts
+++ b/1st-gen/packages/accordion/test/dev-mode.test.ts
@@ -10,46 +10,13 @@
  * governing permissions and limitations under the License.
  */
 
-import { elementUpdated, expect, fixture } from '@open-wc/testing';
-import { SinonStub, stub } from 'sinon';
+import { fixture } from '@open-wc/testing';
 
 import { Accordion } from '@spectrum-web-components/accordion';
 
+import { testForLitDevWarnings } from '../../../test/testing-helpers.js';
 import { Default } from '../stories/accordion.stories.js';
 
 describe('Accordion - dev mode', () => {
-  describe('lit dev mode', () => {
-    let consoleWarnStub!: SinonStub;
-
-    before(() => {
-      consoleWarnStub = stub(console, 'warn');
-    });
-
-    afterEach(() => {
-      consoleWarnStub.resetHistory();
-    });
-
-    after(() => {
-      consoleWarnStub.restore();
-    });
-
-    it('does not emit non-deprecation warnings', async () => {
-      const el = await fixture<Accordion>(Default());
-
-      await elementUpdated(el);
-
-      const nonDeprecationCalls = consoleWarnStub
-        .getCalls()
-        .filter(
-          (call) =>
-            (call.args[call.args.length - 1] as { data?: { level?: string } })
-              ?.data?.level !== 'deprecation'
-        );
-
-      expect(
-        nonDeprecationCalls.length > 0,
-        nonDeprecationCalls[0]?.args.join(', ')
-      ).to.be.false;
-    });
-  });
+  testForLitDevWarnings(async () => await fixture<Accordion>(Default()));
 });
diff --git a/1st-gen/tools/base/src/version.d.ts b/1st-gen/tools/base/src/version.d.ts
index aec04fff48..6644135be1 100644
--- a/1st-gen/tools/base/src/version.d.ts
+++ b/1st-gen/tools/base/src/version.d.ts
@@ -12,8 +12,8 @@
 /**
  * The version of the 1st-gen Spectrum Web Components library.
  */
-export declare const version = "1.12.0";
+export declare const version = "1.11.2";
 /**
  * The version of the core base package.
  */
-export declare const coreVersion = "0.1.0";
+export declare const coreVersion = "0.0.4";
diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index b8f71a4dd7..4284e11925 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -125,69 +125,3 @@ export const Overview: Story = {
   },
   tags: ['overview'],
 };
-
-// ────────────────────────────────
-//    ACCESSIBILITY STORIES
-// ────────────────────────────────
-
-/**
- * ### Features
- *
- * The `<swc-accordion>` and `<swc-accordion-item>` elements implement the
- * [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/):
- *
- * #### Keyboard navigation
- *
- * - <kbd>Tab</kbd>: Moves focus into and between item header buttons
- * - <kbd>Enter</kbd>: Activates the focused header button (browser-native click behavior)
- * - <kbd>Space</kbd>: Toggles the focused item and prevents page scroll
- *
- * #### ARIA implementation
- *
- * 1. **Heading wrapper**: Each header button is wrapped in an `h2`–`h6` element matching
- *    the accordion's `level` attribute
- * 2. **`aria-expanded`**: Set to `"true"` on open items, `"false"` on closed items
- * 3. **`aria-controls`**: Points from the header button to the panel (`id="content"`)
- * 4. **Panel role**: The panel has `role="region"` and `aria-labelledby` pointing to the
- *    header button, making it a labeled landmark
- * 5. **`aria-disabled`**: Set on the header button (not the native `disabled` attribute)
- *    so disabled items remain keyboard-reachable
- * 6. **`hidden`**: Added to closed panels to remove them from the accessibility tree
- * 7. **`inert`**: Added to disabled-item panels to block interaction with their contents
- *
- * ### Best practices
- *
- * - Set a `level` that continues the existing page heading hierarchy without skipping levels
- * - Provide meaningful, unique label text for each item so screen reader users can
- *   navigate the heading list
- * - When using the `actions` slot, include the item subject in the action's accessible
- *   name (e.g., "Edit Alchemy" rather than "Edit") so it is unambiguous out of context
- * - Always set `density` explicitly; use `regular` when unsure
- */
-export const Accessibility: Story = {
-  render: () => html`
-    <swc-accordion level="3" density="regular">
-      <swc-accordion-item open>
-        <span slot="label">Alchemy</span>
-        <button slot="actions" aria-label="Edit Alchemy">Edit</button>
-        Alchemy is an ancient branch of natural philosophy, a philosophical and
-        protoscientific tradition that was historically practiced in China,
-        India, the Muslim world, and Europe.
-      </swc-accordion-item>
-      <swc-accordion-item>
-        <span slot="label">Astrology</span>
-        <button slot="actions" aria-label="Edit Astrology">Edit</button>
-        Astrology is a range of divinatory practices, recognized as
-        pseudoscientific since the 18th century, that propose that information
-        about human affairs and terrestrial events may be discerned by studying
-        the apparent positions of celestial objects.
-      </swc-accordion-item>
-      <swc-accordion-item disabled>
-        <span slot="label">Natural magic (disabled)</span>
-        Natural magic in the context of early modern Europe was a branch of
-        philosophy that treated occult forces as resulting from natural causes.
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  tags: ['a11y'],
-};
diff --git a/2nd-gen/packages/swc/components/accordion/test/.gitkeep b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
deleted file mode 100644
index ab40b3dca8..0000000000
--- a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
+++ /dev/null
@@ -1,702 +0,0 @@
-/**
- * Copyright 2026 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-
-import { html } from 'lit';
-import { expect } from '@storybook/test';
-import type { Meta, StoryObj as Story } from '@storybook/web-components';
-
-import { Accordion, AccordionItem } from '@adobe/spectrum-wc/accordion';
-
-import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
-import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
-
-import { SWC_ACCORDION_ITEM_TOGGLE_EVENT } from '../../../../core/components/accordion/Accordion.types.js';
-import { getComponent, getComponents } from '../../../utils/test-utils.js';
-import meta, { Overview } from '../stories/accordion.stories.js';
-
-export default {
-  ...meta,
-  title: 'Accordion/Tests',
-  parameters: {
-    ...meta.parameters,
-    docs: { disable: true, page: null },
-  },
-  tags: ['!autodocs', 'dev'],
-} as Meta;
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Defaults
-// ──────────────────────────────────────────────────────────────
-
-export const OverviewTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const items = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-
-    await step('renders three items', async () => {
-      expect(items.length, 'three accordion items are rendered').toBe(3);
-    });
-
-    await step('third item is open by default', async () => {
-      expect(items[2]?.open, 'third item open property is true').toBe(true);
-    });
-
-    await step('first two items are closed by default', async () => {
-      expect(items[0]?.open, 'first item open property is false').toBe(false);
-      expect(items[1]?.open, 'second item open property is false').toBe(false);
-    });
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: ARIA contract
-// ──────────────────────────────────────────────────────────────
-
-export const AriaContractTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const items = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const closedItem = items[0] as AccordionItem;
-    const openItem = items[2] as AccordionItem;
-
-    const closedButton = closedItem.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const closedPanel = closedItem.shadowRoot?.getElementById(
-      'content'
-    ) as HTMLElement;
-    const openButton = openItem.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const openPanel = openItem.shadowRoot?.getElementById(
-      'content'
-    ) as HTMLElement;
-
-    await step('aria-expanded reflects open state', async () => {
-      expect(
-        closedButton.getAttribute('aria-expanded'),
-        'closed item button has aria-expanded="false"'
-      ).toBe('false');
-      expect(
-        openButton.getAttribute('aria-expanded'),
-        'open item button has aria-expanded="true"'
-      ).toBe('true');
-    });
-
-    await step('aria-controls value matches the panel id', async () => {
-      expect(
-        closedButton.getAttribute('aria-controls'),
-        'aria-controls is "content"'
-      ).toBe('content');
-      expect(closedPanel.id, 'panel id is "content"').toBe('content');
-    });
-
-    await step(
-      'panel has role="region" and aria-labelledby="header"',
-      async () => {
-        expect(closedPanel.getAttribute('role'), 'panel role is "region"').toBe(
-          'region'
-        );
-        expect(
-          closedPanel.getAttribute('aria-labelledby'),
-          'panel aria-labelledby is "header"'
-        ).toBe('header');
-      }
-    );
-
-    await step(
-      'closed panel has hidden attribute; open panel does not',
-      async () => {
-        expect(
-          closedPanel.hasAttribute('hidden'),
-          'closed panel has hidden attribute'
-        ).toBe(true);
-        expect(
-          openPanel.hasAttribute('hidden'),
-          'open panel does not have hidden attribute'
-        ).toBe(false);
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Open / close
-// ──────────────────────────────────────────────────────────────
-
-export const ToggleTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const items = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const item = items[0] as AccordionItem;
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step('clicking the header button opens a closed item', async () => {
-      expect(item.open, 'item starts closed').toBe(false);
-
-      button.click();
-      await new Promise<void>((resolve) => queueMicrotask(resolve));
-      await item.updateComplete;
-
-      expect(item.open, 'item is now open').toBe(true);
-      expect(
-        button.getAttribute('aria-expanded'),
-        'aria-expanded is "true" after open'
-      ).toBe('true');
-      expect(
-        panel.hasAttribute('hidden'),
-        'hidden attribute is removed when panel is open'
-      ).toBe(false);
-    });
-
-    await step('clicking the header button again closes the item', async () => {
-      button.click();
-      await new Promise<void>((resolve) => queueMicrotask(resolve));
-      await item.updateComplete;
-
-      expect(item.open, 'item is closed again').toBe(false);
-      expect(
-        button.getAttribute('aria-expanded'),
-        'aria-expanded is "false" after close'
-      ).toBe('false');
-      expect(
-        panel.hasAttribute('hidden'),
-        'hidden attribute is restored when panel is closed'
-      ).toBe(true);
-    });
-  },
-};
-
-export const ToggleEventTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const item = (
-      await getComponents<AccordionItem>(canvasElement, 'swc-accordion-item')
-    )[0] as AccordionItem;
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-
-    await step(
-      'clicking the header button dispatches the toggle event',
-      async () => {
-        let toggleFired = false;
-        item.addEventListener(
-          SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-          () => {
-            toggleFired = true;
-          },
-          { once: true }
-        );
-
-        button.click();
-        await item.updateComplete;
-
-        expect(toggleFired, 'toggle event was dispatched').toBe(true);
-      }
-    );
-
-    await step(
-      'toggle event is cancelable; canceling reverts open state',
-      async () => {
-        const wasOpen = item.open;
-        item.addEventListener(
-          SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-          (event) => {
-            event.preventDefault();
-          },
-          { once: true }
-        );
-
-        button.click();
-        await item.updateComplete;
-
-        expect(item.open, 'open state is reverted when event is canceled').toBe(
-          wasOpen
-        );
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Disabled item
-// ──────────────────────────────────────────────────────────────
-
-export const DisabledItemTest: Story = {
-  render: () => html`
-    <swc-accordion density="regular">
-      <swc-accordion-item disabled>
-        <span slot="label">Disabled item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step('disabled item button has aria-disabled="true"', async () => {
-      expect(
-        button.getAttribute('aria-disabled'),
-        'aria-disabled is "true"'
-      ).toBe('true');
-    });
-
-    await step(
-      'disabled item button does not have native disabled attribute',
-      async () => {
-        expect(
-          button.hasAttribute('disabled'),
-          'native disabled attribute is absent'
-        ).toBe(false);
-      }
-    );
-
-    await step('disabled item button remains in the tab order', async () => {
-      expect(button.tabIndex, 'tabIndex is not -1').not.toBe(-1);
-    });
-
-    await step('disabled item panel is inert', async () => {
-      expect(panel.inert, 'panel inert property is true').toBe(true);
-    });
-
-    await step('clicking a disabled item does not open it', async () => {
-      button.click();
-      await item.updateComplete;
-
-      expect(item.open, 'item remains closed after click').toBe(false);
-    });
-
-    await step(
-      'setting open on a closed disabled item does not expand it',
-      async () => {
-        item.open = true;
-        await item.updateComplete;
-
-        expect(item.open, 'open property stays false').toBe(false);
-        expect(
-          panel.hasAttribute('hidden'),
-          'panel stays hidden after imperative open'
-        ).toBe(true);
-      }
-    );
-  },
-};
-
-export const DisabledOpenItemTest: Story = {
-  render: () => html`
-    <swc-accordion density="regular">
-      <swc-accordion-item disabled open>
-        <span slot="label">Disabled open item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step('disabled open item starts expanded', async () => {
-      expect(item.open, 'item starts open').toBe(true);
-    });
-
-    await step(
-      'setting open to false on a disabled item does not collapse it',
-      async () => {
-        item.open = false;
-        await item.updateComplete;
-
-        expect(item.open, 'open property stays true').toBe(true);
-        expect(
-          panel.hasAttribute('hidden'),
-          'panel stays visible after imperative close'
-        ).toBe(false);
-        expect(
-          button.getAttribute('aria-expanded'),
-          'aria-expanded stays true'
-        ).toBe('true');
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Host disabled
-// ──────────────────────────────────────────────────────────────
-
-export const HostDisabledTest: Story = {
-  render: () => html`
-    <swc-accordion disabled density="regular">
-      <swc-accordion-item>
-        <span slot="label">Item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const accordion = await getComponent<Accordion>(
-      canvasElement,
-      'swc-accordion'
-    );
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step(
-      'item button has aria-disabled when the host accordion is disabled',
-      async () => {
-        expect(
-          button.getAttribute('aria-disabled'),
-          'aria-disabled is "true" via host disabled'
-        ).toBe('true');
-      }
-    );
-
-    await step(
-      'item button does not have native disabled when host is disabled',
-      async () => {
-        expect(
-          button.hasAttribute('disabled'),
-          'native disabled attribute is absent'
-        ).toBe(false);
-      }
-    );
-
-    await step('item panel is inert when host is disabled', async () => {
-      expect(panel.inert, 'panel inert is true').toBe(true);
-    });
-
-    await step(
-      'clicking an item does not open it when the host is disabled',
-      async () => {
-        button.click();
-        await item.updateComplete;
-
-        expect(
-          item.open,
-          'item remains closed after click on host-disabled accordion'
-        ).toBe(false);
-      }
-    );
-
-    await step(
-      'setting open on a closed item does not expand it when the host is disabled',
-      async () => {
-        item.open = true;
-        await item.updateComplete;
-
-        expect(item.open, 'open property stays false').toBe(false);
-        expect(
-          panel.hasAttribute('hidden'),
-          'panel stays hidden after imperative open'
-        ).toBe(true);
-        expect(
-          button.getAttribute('aria-expanded'),
-          'aria-expanded stays false'
-        ).toBe('false');
-      }
-    );
-
-    await step('clearing host disabled allows the item to open', async () => {
-      accordion.disabled = false;
-      await accordion.updateComplete;
-      await item.updateComplete;
-
-      expect(
-        button.getAttribute('aria-disabled'),
-        'aria-disabled is removed after host re-enabled'
-      ).toBeNull();
-      expect(panel.inert, 'panel is no longer inert').toBe(false);
-
-      button.click();
-      await item.updateComplete;
-
-      expect(item.open, 'item opens after host is re-enabled').toBe(true);
-    });
-  },
-};
-
-export const HostDisabledOpenItemTest: Story = {
-  render: () => html`
-    <swc-accordion disabled density="regular">
-      <swc-accordion-item open>
-        <span slot="label">Item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step('open item stays expanded while host is disabled', async () => {
-      expect(item.open, 'item starts open').toBe(true);
-    });
-
-    await step(
-      'setting open to false does not collapse the item when the host is disabled',
-      async () => {
-        item.open = false;
-        await item.updateComplete;
-
-        expect(item.open, 'open property stays true').toBe(true);
-        expect(
-          panel.hasAttribute('hidden'),
-          'panel stays visible after imperative close'
-        ).toBe(false);
-        expect(
-          button.getAttribute('aria-expanded'),
-          'aria-expanded stays true'
-        ).toBe('true');
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Keyboard
-// ──────────────────────────────────────────────────────────────
-
-export const SpaceKeyTest: Story = {
-  render: () => html`
-    <swc-accordion density="regular">
-      <swc-accordion-item>
-        <span slot="label">Item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-
-    await step(
-      'Space on the header button calls preventDefault and opens the item',
-      async () => {
-        const event = new KeyboardEvent('keydown', {
-          key: ' ',
-          bubbles: true,
-          cancelable: true,
-        });
-        button.dispatchEvent(event);
-        await item.updateComplete;
-
-        expect(
-          event.defaultPrevented,
-          'Space keydown default is prevented'
-        ).toBe(true);
-        expect(item.open, 'item is open after Space').toBe(true);
-      }
-    );
-
-    await step(
-      'Space on a disabled header button prevents default but does not toggle',
-      async () => {
-        item.disabled = true;
-        await item.updateComplete;
-
-        const event = new KeyboardEvent('keydown', {
-          key: ' ',
-          bubbles: true,
-          cancelable: true,
-        });
-        button.dispatchEvent(event);
-        await item.updateComplete;
-
-        expect(
-          event.defaultPrevented,
-          'Space keydown default is still prevented on disabled item'
-        ).toBe(true);
-        expect(
-          item.open,
-          'open state does not change when item is disabled'
-        ).toBe(true);
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Exclusive open (allow-multiple: false)
-// ──────────────────────────────────────────────────────────────
-
-export const ExclusiveOpenTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const items = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const item1 = items[0] as AccordionItem;
-    const item3 = items[2] as AccordionItem;
-    const button1 = item1.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-
-    await step('opening one item closes the previously open item', async () => {
-      expect(item3.open, 'third item starts open').toBe(true);
-
-      button1.click();
-      // closeSiblingsOnOpen defers via queueMicrotask; wait for it to run.
-      await new Promise<void>((resolve) => queueMicrotask(resolve));
-      await item1.updateComplete;
-      await item3.updateComplete;
-
-      expect(item1.open, 'first item is now open').toBe(true);
-      expect(item3.open, 'third item is now closed').toBe(false);
-    });
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Allow-multiple
-// ──────────────────────────────────────────────────────────────
-
-export const AllowMultipleTest: Story = {
-  render: () => html`
-    <swc-accordion allow-multiple density="regular">
-      <swc-accordion-item>
-        <span slot="label">Alchemy</span>
-        Alchemy content
-      </swc-accordion-item>
-      <swc-accordion-item open>
-        <span slot="label">Astrology</span>
-        Astrology content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const [item1, item2] = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button1 = (item1 as AccordionItem).shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-
-    await step(
-      'opening one item does not close others when allow-multiple is set',
-      async () => {
-        expect((item2 as AccordionItem).open, 'second item starts open').toBe(
-          true
-        );
-
-        button1.click();
-        await new Promise<void>((resolve) => queueMicrotask(resolve));
-        await (item1 as AccordionItem).updateComplete;
-        await (item2 as AccordionItem).updateComplete;
-
-        expect((item1 as AccordionItem).open, 'first item is now open').toBe(
-          true
-        );
-        expect((item2 as AccordionItem).open, 'second item is still open').toBe(
-          true
-        );
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Heading level
-// ──────────────────────────────────────────────────────────────
-
-export const HeadingLevelTest: Story = {
-  render: () => html`
-    <swc-accordion level="4" density="regular">
-      <swc-accordion-item>
-        <span slot="label">Item</span>
-        Content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const accordion = await getComponent<Accordion>(
-      canvasElement,
-      'swc-accordion'
-    );
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    await item.updateComplete;
-
-    await step(
-      'item renders the heading tag matching the accordion level',
-      async () => {
-        expect(
-          item.shadowRoot?.querySelector('h4'),
-          'h4 element is in the item shadow DOM'
-        ).toBeTruthy();
-      }
-    );
-
-    await step(
-      'heading tag updates when the accordion level changes',
-      async () => {
-        accordion.level = 2;
-        await accordion.updateComplete;
-        await item.updateComplete;
-
-        expect(
-          item.shadowRoot?.querySelector('h4'),
-          'h4 is no longer present after level change'
-        ).toBeNull();
-        expect(
-          item.shadowRoot?.querySelector('h2'),
-          'h2 element is in the item shadow DOM'
-        ).toBeTruthy();
-      }
-    );
-  },
-};

From bede72f9e0e9d9d583b5ba88a5f1d4949105411b Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:40:56 -0500
Subject: [PATCH 27/56] chore: scaffold core package

---
 .../components/accordion/Accordion.types.ts   | 19 +++++++++++++++++++
 .../components/accordion/AccordionBase.ts     | 15 +++++++++++++++
 .../accordion/AccordionItem.types.ts          | 13 +++++++++++++
 .../components/accordion/AccordionItemBase.ts | 15 +++++++++++++++
 .../core/components/accordion/index.ts        | 15 +++++++++++++++
 5 files changed, 77 insertions(+)
 create mode 100644 2nd-gen/packages/core/components/accordion/Accordion.types.ts
 create mode 100644 2nd-gen/packages/core/components/accordion/AccordionBase.ts
 create mode 100644 2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
 create mode 100644 2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
 create mode 100644 2nd-gen/packages/core/components/accordion/index.ts

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.types.ts b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
new file mode 100644
index 0000000000..44b0aba7eb
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
@@ -0,0 +1,19 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export const ACCORDION_VALID_SIZES = ['s', 'm', 'l', 'xl'] as const;
+export type AccordionSize = (typeof ACCORDION_VALID_SIZES)[number];
+
+export const ACCORDION_DENSITIES = ['compact', 'regular', 'spacious'] as const;
+export type AccordionDensity = (typeof ACCORDION_DENSITIES)[number];
+
+export const SWC_ACCORDION_ITEM_TOGGLE_EVENT = 'swc-accordion-item-toggle';
diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
new file mode 100644
index 0000000000..3b35a08de9
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -0,0 +1,15 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
+
+export abstract class AccordionBase extends SpectrumElement {}
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
new file mode 100644
index 0000000000..349458211e
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
@@ -0,0 +1,13 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Item-specific types go here as the accordion item API is defined in subsequent commits.
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
new file mode 100644
index 0000000000..5d2a344f87
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -0,0 +1,15 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
+
+export abstract class AccordionItemBase extends SpectrumElement {}
diff --git a/2nd-gen/packages/core/components/accordion/index.ts b/2nd-gen/packages/core/components/accordion/index.ts
new file mode 100644
index 0000000000..a725fdc5fe
--- /dev/null
+++ b/2nd-gen/packages/core/components/accordion/index.ts
@@ -0,0 +1,15 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export * from './AccordionBase.js';
+export * from './AccordionItemBase.js';
+export * from './Accordion.types.js';

From 79b82b32349b41dedcce95466da759cd05a3556a Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:48:07 -0500
Subject: [PATCH 28/56] chore: scaffold swc package

---
 .../swc/components/accordion/Accordion.ts     | 38 +++++++++++++++++++
 .../swc/components/accordion/AccordionItem.ts | 36 ++++++++++++++++++
 .../swc/components/accordion/accordion.css    | 13 +++++++
 .../swc/components/accordion/index.ts         | 14 +++++++
 .../accordion/swc-accordion-item.ts           | 23 +++++++++++
 .../swc/components/accordion/swc-accordion.ts | 23 +++++++++++
 6 files changed, 147 insertions(+)
 create mode 100644 2nd-gen/packages/swc/components/accordion/Accordion.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/AccordionItem.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/accordion.css
 create mode 100644 2nd-gen/packages/swc/components/accordion/index.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/swc-accordion-item.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/swc-accordion.ts

diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
new file mode 100644
index 0000000000..3f15bb156e
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -0,0 +1,38 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { CSSResultArray, html, TemplateResult } from 'lit';
+
+import { AccordionBase } from '@spectrum-web-components/core/components/accordion';
+
+import styles from './accordion.css';
+
+/**
+ * An accordion component that groups expandable content sections.
+ *
+ * @element swc-accordion
+ * @since 2.0.0
+ *
+ * @example
+ * <swc-accordion>
+ *   <swc-accordion-item>Content</swc-accordion-item>
+ * </swc-accordion>
+ */
+export class Accordion extends AccordionBase {
+  public static override get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  protected override render(): TemplateResult {
+    return html``;
+  }
+}
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
new file mode 100644
index 0000000000..b59479c7ae
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -0,0 +1,36 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { CSSResultArray, html, TemplateResult } from 'lit';
+
+import { AccordionItemBase } from '@spectrum-web-components/core/components/accordion';
+
+import styles from './accordion.css';
+
+/**
+ * An accordion item component that wraps a single expandable content section.
+ *
+ * @element swc-accordion-item
+ * @since 2.0.0
+ *
+ * @example
+ * <swc-accordion-item>Content</swc-accordion-item>
+ */
+export class AccordionItem extends AccordionItemBase {
+  public static override get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  protected override render(): TemplateResult {
+    return html``;
+  }
+}
diff --git a/2nd-gen/packages/swc/components/accordion/accordion.css b/2nd-gen/packages/swc/components/accordion/accordion.css
new file mode 100644
index 0000000000..40f33594a2
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/accordion.css
@@ -0,0 +1,13 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/* S2 token imports and selector definitions land here in Phase 4. */
diff --git a/2nd-gen/packages/swc/components/accordion/index.ts b/2nd-gen/packages/swc/components/accordion/index.ts
new file mode 100644
index 0000000000..f8f7131062
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/index.ts
@@ -0,0 +1,14 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export * from './Accordion.js';
+export * from './AccordionItem.js';
diff --git a/2nd-gen/packages/swc/components/accordion/swc-accordion-item.ts b/2nd-gen/packages/swc/components/accordion/swc-accordion-item.ts
new file mode 100644
index 0000000000..cd9853027e
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/swc-accordion-item.ts
@@ -0,0 +1,23 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { defineElement } from '@spectrum-web-components/core/element/index.js';
+
+import { AccordionItem } from './AccordionItem.js';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'swc-accordion-item': AccordionItem;
+  }
+}
+
+defineElement('swc-accordion-item', AccordionItem);
diff --git a/2nd-gen/packages/swc/components/accordion/swc-accordion.ts b/2nd-gen/packages/swc/components/accordion/swc-accordion.ts
new file mode 100644
index 0000000000..d51f7f1b1e
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/swc-accordion.ts
@@ -0,0 +1,23 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { defineElement } from '@spectrum-web-components/core/element/index.js';
+
+import { Accordion } from './Accordion.js';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'swc-accordion': Accordion;
+  }
+}
+
+defineElement('swc-accordion', Accordion);

From 8c69ece14f064b62d1557013618839b351cd9ba0 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:54:09 -0500
Subject: [PATCH 29/56] chore: add Chevron300Icon for xl accordion

---
 .../icon/elements/Chevron300Icon.ts           | 22 +++++++++++++++++++
 .../swc/components/icon/elements/index.ts     |  1 +
 2 files changed, 23 insertions(+)
 create mode 100644 2nd-gen/packages/swc/components/icon/elements/Chevron300Icon.ts

diff --git a/2nd-gen/packages/swc/components/icon/elements/Chevron300Icon.ts b/2nd-gen/packages/swc/components/icon/elements/Chevron300Icon.ts
new file mode 100644
index 0000000000..72956bf4b1
--- /dev/null
+++ b/2nd-gen/packages/swc/components/icon/elements/Chevron300Icon.ts
@@ -0,0 +1,22 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { html, TemplateResult } from 'lit';
+
+export const Chevron300Icon = (): TemplateResult => {
+  return html`
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 14">
+      <path
+        d="M10.639 7a.95.95 0 0 0-.278-.671l-.003-.002-5.33-5.33a.95.95 0 0 0-1.342 1.342L8.346 7l-4.661 4.66a.95.95 0 1 0 1.342 1.343l5.33-5.33.003-.001A.95.95 0 0 0 10.64 7z"
+      />
+    </svg>
+  `;
+};
diff --git a/2nd-gen/packages/swc/components/icon/elements/index.ts b/2nd-gen/packages/swc/components/icon/elements/index.ts
index b30f66ddd2..8d6cf638b2 100644
--- a/2nd-gen/packages/swc/components/icon/elements/index.ts
+++ b/2nd-gen/packages/swc/components/icon/elements/index.ts
@@ -20,6 +20,7 @@ export * from './Chevron50Icon.js';
 export * from './Chevron75Icon.js';
 export * from './Chevron100Icon.js';
 export * from './Chevron200Icon.js';
+export * from './Chevron300Icon.js';
 export * from './CornerTriangle300Icon.js';
 export * from './Cross75Icon.js';
 export * from './Cross100Icon.js';

From cb55ae1246fd39e3db839d34e4e79aa506843836 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:58:12 -0500
Subject: [PATCH 30/56] chore: set up storybook story

---
 .../accordion/stories/accordion.stories.ts    | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts

diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
new file mode 100644
index 0000000000..a6f2c6bb15
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -0,0 +1,65 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { html } from 'lit';
+import type { Meta, StoryObj as Story } from '@storybook/web-components';
+
+import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
+import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
+
+// ────────────────
+//    METADATA
+// ────────────────
+
+/**
+ * An accordion groups related content sections, each behind a header that can
+ * be expanded or collapsed. Args, argTypes, and controls are added in a later commit
+ * once the component API is defined.
+ */
+const meta: Meta = {
+  title: 'Accordion',
+  component: 'swc-accordion',
+  parameters: {
+    docs: {
+      subtitle: 'Groups related content sections behind expandable headers.',
+    },
+  },
+  tags: ['migrated'],
+};
+
+export default meta;
+
+// ────────────────────
+//    AUTODOCS STORY
+// ────────────────────
+
+export const Playground: Story = {
+  render: () => html`
+    <swc-accordion>
+      <swc-accordion-item>Sample content</swc-accordion-item>
+    </swc-accordion>
+  `,
+  tags: ['autodocs', 'dev'],
+};
+
+// ──────────────────────────
+//    OVERVIEW STORY
+// ──────────────────────────
+
+export const Overview: Story = {
+  render: () => html`
+    <swc-accordion>
+      <swc-accordion-item>Sample content</swc-accordion-item>
+    </swc-accordion>
+  `,
+  tags: ['overview'],
+};

From 8c616872ff9b74695c477f8a3171a05cb8e911e7 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 15:58:31 -0500
Subject: [PATCH 31/56] chore: commit preview.ts updates

---
 2nd-gen/packages/swc/.storybook/preview.ts | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts
index 73e4673e0a..68e75baf54 100644
--- a/2nd-gen/packages/swc/.storybook/preview.ts
+++ b/2nd-gen/packages/swc/.storybook/preview.ts
@@ -324,11 +324,7 @@ const preview = {
               'Components',
               [
                 'Accordion',
-                [
-                  'Accessibility migration analysis',
-                  'Migration plan',
-                  'Rendering and styling migration analysis',
-                ],
+                ['Accessibility migration analysis', 'Migration plan'],
                 'Action button',
                 ['Rendering and styling migration analysis'],
                 'Action group',

From 629c23389167173af47969d057ddf225c1414b1e Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Thu, 14 May 2026 17:12:40 -0500
Subject: [PATCH 32/56] feat: implement AccordionItem API and render template

---
 .../components/accordion/AccordionItemBase.ts | 73 +++++++++++++++++-
 .../swc/components/accordion/AccordionItem.ts | 77 ++++++++++++++++++-
 2 files changed, 147 insertions(+), 3 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
index 5d2a344f87..3aa2f07483 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -10,6 +10,77 @@
  * governing permissions and limitations under the License.
  */
 
+import { property } from 'lit/decorators.js';
+
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
 
-export abstract class AccordionItemBase extends SpectrumElement {}
+import {
+  type AccordionSize,
+  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+} from './Accordion.types.js';
+
+/**
+ * Base class for accordion item components. Manages open/disabled state,
+ * heading level (set by the parent accordion), and the toggle event.
+ *
+ * @slot label - The heading text for this accordion item.
+ * @slot actions - Optional actions rendered adjacent to the heading, outside
+ *   the toggle button so they remain independently interactive.
+ * @slot - The panel content revealed when the item is open.
+ */
+export abstract class AccordionItemBase extends SpectrumElement {
+  // ──────────────────
+  //     PUBLIC API
+  // ──────────────────
+
+  /**
+   * Whether the accordion item panel is expanded.
+   */
+  @property({ type: Boolean, reflect: true })
+  public open: boolean = false;
+
+  /**
+   * Whether the accordion item is disabled. A disabled item keeps its header
+   * in the tab order but blocks toggling.
+   */
+  @property({ type: Boolean, reflect: true })
+  public disabled: boolean = false;
+
+  /**
+   * The size of the item. Inherited from the parent accordion; controls which
+   * chevron icon is displayed. Has no effect when the item is used standalone.
+   */
+  @property({ type: String, reflect: true })
+  public size?: AccordionSize;
+
+  // ──────────────────────
+  //     INTERNAL STATE
+  // ──────────────────────
+
+  /**
+   * @internal
+   * Heading level (2–6) propagated by the parent accordion. Defaults to 3
+   * for standalone items. Used by the concrete render() to emit the correct
+   * <h*> element; made reactive in a later commit.
+   */
+  protected heading: number = 3;
+
+  // ──────────────────────
+  //     IMPLEMENTATION
+  // ──────────────────────
+
+  /**
+   * @internal
+   * Dispatches the toggle event. The concrete class wires this to the
+   * header button's click handler and adds open-state management.
+   */
+  protected toggle(): void {
+    this.dispatchEvent(
+      new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+  }
+}
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index b59479c7ae..61cd39872c 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -14,6 +14,13 @@ import { CSSResultArray, html, TemplateResult } from 'lit';
 
 import { AccordionItemBase } from '@spectrum-web-components/core/components/accordion';
 
+import '../icon/swc-icon.js';
+
+import { Chevron75Icon } from '../icon/elements/Chevron75Icon.js';
+import { Chevron100Icon } from '../icon/elements/Chevron100Icon.js';
+import { Chevron200Icon } from '../icon/elements/Chevron200Icon.js';
+import { Chevron300Icon } from '../icon/elements/Chevron300Icon.js';
+
 import styles from './accordion.css';
 
 /**
@@ -23,14 +30,80 @@ import styles from './accordion.css';
  * @since 2.0.0
  *
  * @example
- * <swc-accordion-item>Content</swc-accordion-item>
+ * <swc-accordion-item>
+ *   <span slot="label">Section heading</span>
+ *   Panel content goes here.
+ * </swc-accordion-item>
  */
 export class AccordionItem extends AccordionItemBase {
+  // ──────────────────────────────
+  //     RENDERING & STYLING
+  // ──────────────────────────────
+
   public static override get styles(): CSSResultArray {
     return [styles];
   }
 
+  private chevronForSize(): TemplateResult {
+    switch (this.size) {
+      case 's':
+        return Chevron75Icon();
+      case 'l':
+        return Chevron200Icon();
+      case 'xl':
+        return Chevron300Icon();
+      case 'm':
+      default:
+        return Chevron100Icon();
+    }
+  }
+
+  private handleActionsSlotChange(event: Event): void {
+    const slot = event.target as HTMLSlotElement;
+    const container = slot.parentElement as HTMLElement | null;
+    if (container) {
+      container.hidden = slot.assignedNodes({ flatten: true }).length === 0;
+    }
+  }
+
+  private handleActionsContainerInteraction(event: Event): void {
+    event.stopPropagation();
+  }
+
   protected override render(): TemplateResult {
-    return html``;
+    // <h3> is a static stub; the heading level becomes dynamic in a later commit.
+    return html`
+      <h3>
+        <button
+          id="header"
+          type="button"
+          aria-expanded="false"
+          aria-controls="content"
+        >
+          <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
+            ${this.chevronForSize()}
+          </swc-icon>
+          <span class="spectrum-Accordion-itemTitle">
+            <slot name="label"></slot>
+          </span>
+        </button>
+      </h3>
+      <div
+        class="spectrum-Accordion-itemDirectActions"
+        hidden
+        @click=${this.handleActionsContainerInteraction}
+        @keydown=${this.handleActionsContainerInteraction}
+      >
+        <slot name="actions" @slotchange=${this.handleActionsSlotChange}></slot>
+      </div>
+      <div
+        id="content"
+        class="spectrum-Accordion-itemContent"
+        role="region"
+        aria-labelledby="header"
+      >
+        <slot></slot>
+      </div>
+    `;
   }
 }

From 176c95aa3271846ce2656bdb195254094135c4ea Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 08:10:12 -0500
Subject: [PATCH 33/56] feat: implement Accordion API and propagation

---
 .../components/accordion/AccordionBase.ts     | 112 +++++++++++++++++-
 .../components/accordion/AccordionItemBase.ts |   5 +-
 .../swc/components/accordion/Accordion.ts     |  13 +-
 3 files changed, 120 insertions(+), 10 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
index 3b35a08de9..9d7521f595 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -10,6 +10,116 @@
  * governing permissions and limitations under the License.
  */
 
+import { html, PropertyValues, TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
 
-export abstract class AccordionBase extends SpectrumElement {}
+import {
+  type AccordionDensity,
+  type AccordionSize,
+} from './Accordion.types.js';
+import { AccordionItemBase } from './AccordionItemBase.js';
+
+/**
+ * Base class for accordion components. Manages item propagation, heading
+ * level, density, and the exclusive-open constraint.
+ *
+ * @slot - One or more `swc-accordion-item` elements.
+ */
+export abstract class AccordionBase extends SpectrumElement {
+  // ──────────────────
+  //     PUBLIC API
+  // ──────────────────
+
+  /**
+   * When set, multiple items may be open at the same time. By default only
+   * one item can be open.
+   */
+  @property({ type: Boolean, reflect: true, attribute: 'allow-multiple' })
+  public allowMultiple: boolean = false;
+
+  /**
+   * Heading level applied to every item header (2–6). Defaults to 3.
+   * Values outside that range are clamped.
+   */
+  @property({ type: Number, reflect: true })
+  public level: number = 3;
+
+  /**
+   * Size applied to all items. When set, overrides any size set on individual
+   * items.
+   */
+  @property({ type: String, reflect: true })
+  public size?: AccordionSize;
+
+  /**
+   * Controls vertical spacing between items.
+   *
+   * @default regular
+   */
+  @property({ type: String, reflect: true })
+  public density: AccordionDensity = 'regular';
+
+  /**
+   * Renders the accordion in its quiet (no-border) visual variant.
+   */
+  @property({ type: Boolean, reflect: true })
+  public quiet: boolean = false;
+
+  /**
+   * Disables all items in the accordion. Individual items may also be
+   * disabled independently.
+   */
+  @property({ type: Boolean, reflect: true })
+  public disabled: boolean = false;
+
+  // ──────────────────────
+  //     IMPLEMENTATION
+  // ──────────────────────
+
+  private updateItems(): void {
+    const slot = this.shadowRoot?.querySelector('slot');
+    if (!slot) {
+      return;
+    }
+    const items = slot
+      .assignedElements({ flatten: true })
+      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
+    for (const item of items) {
+      item.heading = this.level;
+      item.size = this.size;
+    }
+  }
+
+  protected override update(changedProperties: PropertyValues): void {
+    if (changedProperties.has('level')) {
+      const clamped = Math.min(6, Math.max(2, this.level));
+      if (this.level !== clamped) {
+        this.level = clamped;
+      }
+    }
+    if (changedProperties.has('level') || changedProperties.has('size')) {
+      this.updateItems();
+    }
+    super.update(changedProperties);
+  }
+
+  protected override firstUpdated(changedProperties: PropertyValues): void {
+    super.firstUpdated(changedProperties);
+    if (window.__swc?.DEBUG && !this.hasAttribute('density')) {
+      window.__swc.warn(
+        this,
+        `<${this.localName}> should have an explicit "density" attribute set. Defaulting to "regular", which corresponds to the 1st-gen default.`,
+        'https://opensource.adobe.com/spectrum-web-components/components/accordion/',
+        { type: 'api', level: 'low' }
+      );
+    }
+  }
+
+  protected override render(): TemplateResult {
+    return html`
+      <slot @slotchange=${this.updateItems}></slot>
+    `;
+  }
+}
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
index 3aa2f07483..f13a014039 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -61,9 +61,10 @@ export abstract class AccordionItemBase extends SpectrumElement {
    * @internal
    * Heading level (2–6) propagated by the parent accordion. Defaults to 3
    * for standalone items. Used by the concrete render() to emit the correct
-   * <h*> element; made reactive in a later commit.
+   * <h*> element; made reactive in a later commit. Public so AccordionBase
+   * can write to instances without a type assertion.
    */
-  protected heading: number = 3;
+  public heading: number = 3;
 
   // ──────────────────────
   //     IMPLEMENTATION
diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
index 3f15bb156e..f89f575f90 100644
--- a/2nd-gen/packages/swc/components/accordion/Accordion.ts
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { CSSResultArray, html, TemplateResult } from 'lit';
+import { CSSResultArray } from 'lit';
 
 import { AccordionBase } from '@spectrum-web-components/core/components/accordion';
 
@@ -23,16 +23,15 @@ import styles from './accordion.css';
  * @since 2.0.0
  *
  * @example
- * <swc-accordion>
- *   <swc-accordion-item>Content</swc-accordion-item>
+ * <swc-accordion density="regular">
+ *   <swc-accordion-item>
+ *     <span slot="label">Section heading</span>
+ *     Panel content goes here.
+ *   </swc-accordion-item>
  * </swc-accordion>
  */
 export class Accordion extends AccordionBase {
   public static override get styles(): CSSResultArray {
     return [styles];
   }
-
-  protected override render(): TemplateResult {
-    return html``;
-  }
 }

From 5896710b896a1e5661c48c86a15c3e309166dc74 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 09:56:59 -0500
Subject: [PATCH 34/56] feat: implement open and toggle logic

---
 .../components/accordion/AccordionBase.ts     | 43 ++++++++++
 .../swc/components/accordion/AccordionItem.ts | 45 +++++++++-
 .../accordion/stories/accordion.stories.ts    | 86 ++++++++++++++++---
 3 files changed, 159 insertions(+), 15 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
index 9d7521f595..7692e48d45 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -18,6 +18,7 @@ import { SpectrumElement } from '@spectrum-web-components/core/element/index.js'
 import {
   type AccordionDensity,
   type AccordionSize,
+  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
 } from './Accordion.types.js';
 import { AccordionItemBase } from './AccordionItemBase.js';
 
@@ -78,6 +79,32 @@ export abstract class AccordionBase extends SpectrumElement {
   //     IMPLEMENTATION
   // ──────────────────────
 
+  private handleItemToggle = (event: Event): void => {
+    if (this.disabled) {
+      event.preventDefault();
+      return;
+    }
+    if (this.allowMultiple) {
+      return;
+    }
+    const toggling = event.target;
+    if (!(toggling instanceof AccordionItemBase) || !toggling.open) {
+      return;
+    }
+    const slot = this.shadowRoot?.querySelector('slot');
+    if (!slot) {
+      return;
+    }
+    const items = slot
+      .assignedElements({ flatten: true })
+      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
+    for (const item of items) {
+      if (item !== toggling) {
+        item.open = false;
+      }
+    }
+  };
+
   private updateItems(): void {
     const slot = this.shadowRoot?.querySelector('slot');
     if (!slot) {
@@ -92,6 +119,22 @@ export abstract class AccordionBase extends SpectrumElement {
     }
   }
 
+  public override connectedCallback(): void {
+    super.connectedCallback();
+    this.addEventListener(
+      SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+      this.handleItemToggle
+    );
+  }
+
+  public override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.removeEventListener(
+      SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+      this.handleItemToggle
+    );
+  }
+
   protected override update(changedProperties: PropertyValues): void {
     if (changedProperties.has('level')) {
       const clamped = Math.min(6, Math.max(2, this.level));
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 61cd39872c..293a883ec1 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -12,7 +12,10 @@
 
 import { CSSResultArray, html, TemplateResult } from 'lit';
 
-import { AccordionItemBase } from '@spectrum-web-components/core/components/accordion';
+import {
+  AccordionItemBase,
+  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+} from '@spectrum-web-components/core/components/accordion';
 
 import '../icon/swc-icon.js';
 
@@ -37,13 +40,48 @@ import styles from './accordion.css';
  */
 export class AccordionItem extends AccordionItemBase {
   // ──────────────────────────────
-  //     RENDERING & STYLING
+  //     STYLING
   // ──────────────────────────────
 
   public static override get styles(): CSSResultArray {
     return [styles];
   }
 
+  // ──────────────────────────────
+  //     DELEGATION
+  // ──────────────────────────────
+
+  public override focus(options?: FocusOptions): void {
+    this.shadowRoot?.getElementById('header')?.focus(options);
+  }
+
+  public override click(): void {
+    this.shadowRoot?.getElementById('header')?.click();
+  }
+
+  // ──────────────────────────────
+  //     TOGGLE BEHAVIOR
+  // ──────────────────────────────
+
+  protected override toggle(): void {
+    if (this.disabled) {
+      return;
+    }
+    this.open = !this.open;
+    const event = new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+    });
+    if (!this.dispatchEvent(event)) {
+      this.open = !this.open;
+    }
+  }
+
+  // ──────────────────────────────
+  //     RENDERING
+  // ──────────────────────────────
+
   private chevronForSize(): TemplateResult {
     switch (this.size) {
       case 's':
@@ -77,8 +115,9 @@ export class AccordionItem extends AccordionItemBase {
         <button
           id="header"
           type="button"
-          aria-expanded="false"
+          aria-expanded=${this.open ? 'true' : 'false'}
           aria-controls="content"
+          @click=${this.toggle}
         >
           <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
             ${this.chevronForSize()}
diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index a6f2c6bb15..4284e11925 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -12,23 +12,89 @@
 
 import { html } from 'lit';
 import type { Meta, StoryObj as Story } from '@storybook/web-components';
+import { getStorybookHelpers } from '@wc-toolkit/storybook-helpers';
 
 import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
 import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
 
+import {
+  ACCORDION_DENSITIES,
+  ACCORDION_VALID_SIZES,
+  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+} from '../../../../core/components/accordion/Accordion.types.js';
+
 // ────────────────
 //    METADATA
 // ────────────────
 
+const { args, argTypes, template } = getStorybookHelpers('swc-accordion');
+
+argTypes.density = {
+  ...argTypes.density,
+  control: { type: 'select' },
+  options: [...ACCORDION_DENSITIES],
+  table: {
+    ...argTypes.density?.table,
+    category: 'attributes',
+    defaultValue: { summary: 'regular' },
+  },
+};
+
+argTypes.size = {
+  ...argTypes.size,
+  control: { type: 'select' },
+  options: ['', ...ACCORDION_VALID_SIZES],
+  table: {
+    ...argTypes.size?.table,
+    category: 'attributes',
+  },
+};
+
+argTypes.level = {
+  ...argTypes.level,
+  control: { type: 'number', min: 2, max: 6 },
+  table: {
+    ...argTypes.level?.table,
+    category: 'attributes',
+    defaultValue: { summary: '3' },
+  },
+};
+
+const defaultItems = html`
+  <swc-accordion-item>
+    <span slot="label">Alchemy</span>
+    Alchemy is an ancient branch of natural philosophy, a philosophical and
+    protoscientific tradition that was historically practiced in China, India,
+    the Muslim world, and Europe.
+  </swc-accordion-item>
+  <swc-accordion-item>
+    <span slot="label">Astrology</span>
+    Astrology is a range of divinatory practices, recognized as pseudoscientific
+    since the 18th century, that propose that information about human affairs
+    and terrestrial events may be discerned by studying the apparent positions
+    of celestial objects.
+  </swc-accordion-item>
+  <swc-accordion-item open>
+    <span slot="label">Natural magic</span>
+    Natural magic in the context of early modern Europe was a branch of
+    philosophy that treated occult forces as resulting from natural causes, not
+    from divine or demonic intervention.
+  </swc-accordion-item>
+`;
+
 /**
  * An accordion groups related content sections, each behind a header that can
- * be expanded or collapsed. Args, argTypes, and controls are added in a later commit
- * once the component API is defined.
+ * be expanded or collapsed. Only one section is open at a time by default;
+ * set `allow-multiple` to let any number of sections be open simultaneously.
  */
 const meta: Meta = {
   title: 'Accordion',
   component: 'swc-accordion',
+  args,
+  argTypes,
+  render: (args) => template(args, defaultItems),
   parameters: {
+    actions: { handles: [SWC_ACCORDION_ITEM_TOGGLE_EVENT] },
     docs: {
       subtitle: 'Groups related content sections behind expandable headers.',
     },
@@ -43,11 +109,9 @@ export default meta;
 // ────────────────────
 
 export const Playground: Story = {
-  render: () => html`
-    <swc-accordion>
-      <swc-accordion-item>Sample content</swc-accordion-item>
-    </swc-accordion>
-  `,
+  args: {
+    density: 'regular',
+  },
   tags: ['autodocs', 'dev'],
 };
 
@@ -56,10 +120,8 @@ export const Playground: Story = {
 // ──────────────────────────
 
 export const Overview: Story = {
-  render: () => html`
-    <swc-accordion>
-      <swc-accordion-item>Sample content</swc-accordion-item>
-    </swc-accordion>
-  `,
+  args: {
+    density: 'regular',
+  },
   tags: ['overview'],
 };

From 7318895bf59e9b90744a39a76a03618c01e7e17a Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 10:29:03 -0500
Subject: [PATCH 35/56] feat: wire up dynamic heading levels

---
 .../components/accordion/AccordionItemBase.ts |  8 +--
 .../swc/components/accordion/AccordionItem.ts | 59 +++++++++++++------
 2 files changed, 46 insertions(+), 21 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
index f13a014039..df9d859aef 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
 
@@ -60,10 +60,10 @@ export abstract class AccordionItemBase extends SpectrumElement {
   /**
    * @internal
    * Heading level (2–6) propagated by the parent accordion. Defaults to 3
-   * for standalone items. Used by the concrete render() to emit the correct
-   * <h*> element; made reactive in a later commit. Public so AccordionBase
-   * can write to instances without a type assertion.
+   * for standalone items. Public so AccordionBase can write to instances
+   * without a type assertion.
    */
+  @state()
   public heading: number = 3;
 
   // ──────────────────────
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 293a883ec1..0a299a8b83 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -108,25 +108,50 @@ export class AccordionItem extends AccordionItemBase {
     event.stopPropagation();
   }
 
+  private renderHeadingWrapper(content: TemplateResult): TemplateResult {
+    switch (this.heading) {
+      case 2:
+        return html`
+          <h2>${content}</h2>
+        `;
+      case 4:
+        return html`
+          <h4>${content}</h4>
+        `;
+      case 5:
+        return html`
+          <h5>${content}</h5>
+        `;
+      case 6:
+        return html`
+          <h6>${content}</h6>
+        `;
+      default:
+        return html`
+          <h3>${content}</h3>
+        `;
+    }
+  }
+
   protected override render(): TemplateResult {
-    // <h3> is a static stub; the heading level becomes dynamic in a later commit.
+    const button = html`
+      <button
+        id="header"
+        type="button"
+        aria-expanded=${this.open ? 'true' : 'false'}
+        aria-controls="content"
+        @click=${this.toggle}
+      >
+        <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
+          ${this.chevronForSize()}
+        </swc-icon>
+        <span class="spectrum-Accordion-itemTitle">
+          <slot name="label"></slot>
+        </span>
+      </button>
+    `;
     return html`
-      <h3>
-        <button
-          id="header"
-          type="button"
-          aria-expanded=${this.open ? 'true' : 'false'}
-          aria-controls="content"
-          @click=${this.toggle}
-        >
-          <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
-            ${this.chevronForSize()}
-          </swc-icon>
-          <span class="spectrum-Accordion-itemTitle">
-            <slot name="label"></slot>
-          </span>
-        </button>
-      </h3>
+      ${this.renderHeadingWrapper(button)}
       <div
         class="spectrum-Accordion-itemDirectActions"
         hidden

From 1221bee2e929d5b1c8b9e68d3a74d066e9583fdc Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 11:22:27 -0500
Subject: [PATCH 36/56] feat: implement disabled item functionality

---
 .../core/components/accordion/AccordionBase.ts         |  7 ++++++-
 .../core/components/accordion/AccordionItemBase.ts     | 10 ++++++++++
 .../packages/swc/components/accordion/AccordionItem.ts |  7 ++++++-
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
index 7692e48d45..755f768b15 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -116,6 +116,7 @@ export abstract class AccordionBase extends SpectrumElement {
     for (const item of items) {
       item.heading = this.level;
       item.size = this.size;
+      item.parentDisabled = this.disabled;
     }
   }
 
@@ -142,7 +143,11 @@ export abstract class AccordionBase extends SpectrumElement {
         this.level = clamped;
       }
     }
-    if (changedProperties.has('level') || changedProperties.has('size')) {
+    if (
+      changedProperties.has('level') ||
+      changedProperties.has('size') ||
+      changedProperties.has('disabled')
+    ) {
       this.updateItems();
     }
     super.update(changedProperties);
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
index df9d859aef..4cff207560 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
@@ -66,6 +66,16 @@ export abstract class AccordionItemBase extends SpectrumElement {
   @state()
   public heading: number = 3;
 
+  /**
+   * @internal
+   * Set by the parent accordion when its own `disabled` is true. Causes the
+   * item to render as disabled (aria-disabled + inert panel) without clobbering
+   * the item's own `disabled` property, so the per-item state is preserved
+   * when the accordion is re-enabled.
+   */
+  @state()
+  public parentDisabled: boolean = false;
+
   // ──────────────────────
   //     IMPLEMENTATION
   // ──────────────────────
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 0a299a8b83..4d5c6a5d1e 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -11,6 +11,7 @@
  */
 
 import { CSSResultArray, html, TemplateResult } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
 
 import {
   AccordionItemBase,
@@ -64,7 +65,7 @@ export class AccordionItem extends AccordionItemBase {
   // ──────────────────────────────
 
   protected override toggle(): void {
-    if (this.disabled) {
+    if (this.disabled || this.parentDisabled) {
       return;
     }
     this.open = !this.open;
@@ -140,6 +141,9 @@ export class AccordionItem extends AccordionItemBase {
         type="button"
         aria-expanded=${this.open ? 'true' : 'false'}
         aria-controls="content"
+        aria-disabled=${ifDefined(
+          this.disabled || this.parentDisabled ? 'true' : undefined
+        )}
         @click=${this.toggle}
       >
         <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
@@ -165,6 +169,7 @@ export class AccordionItem extends AccordionItemBase {
         class="spectrum-Accordion-itemContent"
         role="region"
         aria-labelledby="header"
+        .inert=${this.disabled || this.parentDisabled}
       >
         <slot></slot>
       </div>

From d4d945d3f1b95bcc4374ca74b3fb0c96bd8b1524 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 11:50:56 -0500
Subject: [PATCH 37/56] fix: handle space keyboard behavior (SWC-1487)

---
 .../packages/swc/components/accordion/AccordionItem.ts    | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 4d5c6a5d1e..8312fc7e44 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -109,6 +109,13 @@ export class AccordionItem extends AccordionItemBase {
     event.stopPropagation();
   }
 
+  private handleHeaderKeydown(event: Event): void {
+    if ((event as KeyboardEvent).key === ' ') {
+      event.preventDefault();
+      this.toggle();
+    }
+  }
+
   private renderHeadingWrapper(content: TemplateResult): TemplateResult {
     switch (this.heading) {
       case 2:
@@ -145,6 +152,7 @@ export class AccordionItem extends AccordionItemBase {
           this.disabled || this.parentDisabled ? 'true' : undefined
         )}
         @click=${this.toggle}
+        @keydown=${this.handleHeaderKeydown}
       >
         <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
           ${this.chevronForSize()}

From b26f30f806c26a0b9696a2f14535e8a473c5e21f Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 13:54:52 -0500
Subject: [PATCH 38/56] refactor: address missing migration-setup items

---
 .../core/components/accordion/AccordionBase.ts       | 12 +++---------
 2nd-gen/packages/core/package.json                   |  7 +++++++
 .../packages/swc/components/accordion/Accordion.ts   |  8 +++++++-
 .../packages/swc/components/accordion/test/.gitkeep  |  1 +
 4 files changed, 18 insertions(+), 10 deletions(-)
 create mode 100644 2nd-gen/packages/swc/components/accordion/test/.gitkeep

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
index 755f768b15..21f27b87a2 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionBase.ts
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { html, PropertyValues, TemplateResult } from 'lit';
+import { PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
 
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
@@ -105,8 +105,8 @@ export abstract class AccordionBase extends SpectrumElement {
     }
   };
 
-  private updateItems(): void {
-    const slot = this.shadowRoot?.querySelector('slot');
+  protected updateItems(): void {
+    const slot = this.renderRoot?.querySelector('slot');
     if (!slot) {
       return;
     }
@@ -164,10 +164,4 @@ export abstract class AccordionBase extends SpectrumElement {
       );
     }
   }
-
-  protected override render(): TemplateResult {
-    return html`
-      <slot @slotchange=${this.updateItems}></slot>
-    `;
-  }
 }
diff --git a/2nd-gen/packages/core/package.json b/2nd-gen/packages/core/package.json
index 86b4009e99..b4626a67e8 100644
--- a/2nd-gen/packages/core/package.json
+++ b/2nd-gen/packages/core/package.json
@@ -19,6 +19,10 @@
       "types": "./dist/components/alert-banner/index.d.ts",
       "import": "./dist/components/alert-banner/index.js"
     },
+    "./components/accordion": {
+      "types": "./dist/components/accordion/index.d.ts",
+      "import": "./dist/components/accordion/index.js"
+    },
     "./components/asset": {
       "types": "./dist/components/asset/index.d.ts",
       "import": "./dist/components/asset/index.js"
@@ -148,6 +152,9 @@
       "components/alert-banner": [
         "dist/components/alert-banner/index.d.ts"
       ],
+      "components/accordion": [
+        "dist/components/accordion/index.d.ts"
+      ],
       "components/asset": [
         "dist/components/asset/index.d.ts"
       ],
diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
index f89f575f90..43f4039dc4 100644
--- a/2nd-gen/packages/swc/components/accordion/Accordion.ts
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import { CSSResultArray } from 'lit';
+import { CSSResultArray, html, TemplateResult } from 'lit';
 
 import { AccordionBase } from '@spectrum-web-components/core/components/accordion';
 
@@ -34,4 +34,10 @@ export class Accordion extends AccordionBase {
   public static override get styles(): CSSResultArray {
     return [styles];
   }
+
+  protected override render(): TemplateResult {
+    return html`
+      <slot @slotchange=${this.updateItems}></slot>
+    `;
+  }
 }
diff --git a/2nd-gen/packages/swc/components/accordion/test/.gitkeep b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
@@ -0,0 +1 @@
+

From 4ee7d20c70bef8230d86649eef11ce4ee3eba130 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Fri, 15 May 2026 16:19:52 -0500
Subject: [PATCH 39/56] refactor: rename methods, align file names

---
 .../{AccordionBase.ts => Accordion.base.ts}   | 19 ++++++++-------
 .../components/accordion/Accordion.types.ts   |  3 +++
 ...rdionItemBase.ts => AccordionItem.base.ts} | 24 +++++++++++++++----
 .../accordion/AccordionItem.types.ts          | 13 ----------
 .../core/components/accordion/index.ts        |  4 ++--
 .../swc/components/accordion/Accordion.ts     |  2 +-
 .../swc/components/accordion/AccordionItem.ts | 15 +++++++-----
 7 files changed, 45 insertions(+), 35 deletions(-)
 rename 2nd-gen/packages/core/components/accordion/{AccordionBase.ts => Accordion.base.ts} (91%)
 rename 2nd-gen/packages/core/components/accordion/{AccordionItemBase.ts => AccordionItem.base.ts} (85%)
 delete mode 100644 2nd-gen/packages/core/components/accordion/AccordionItem.types.ts

diff --git a/2nd-gen/packages/core/components/accordion/AccordionBase.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
similarity index 91%
rename from 2nd-gen/packages/core/components/accordion/AccordionBase.ts
rename to 2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 21f27b87a2..96b37850f7 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionBase.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -17,10 +17,11 @@ import { SpectrumElement } from '@spectrum-web-components/core/element/index.js'
 
 import {
   type AccordionDensity,
+  type AccordionHeadingLevel,
   type AccordionSize,
   SWC_ACCORDION_ITEM_TOGGLE_EVENT,
 } from './Accordion.types.js';
-import { AccordionItemBase } from './AccordionItemBase.js';
+import { AccordionItemBase } from './AccordionItem.base.js';
 
 /**
  * Base class for accordion components. Manages item propagation, heading
@@ -79,7 +80,7 @@ export abstract class AccordionBase extends SpectrumElement {
   //     IMPLEMENTATION
   // ──────────────────────
 
-  private handleItemToggle = (event: Event): void => {
+  private closeSiblingsOnOpen = (event: Event): void => {
     if (this.disabled) {
       event.preventDefault();
       return;
@@ -105,7 +106,7 @@ export abstract class AccordionBase extends SpectrumElement {
     }
   };
 
-  protected updateItems(): void {
+  protected syncAccordionItems(): void {
     const slot = this.renderRoot?.querySelector('slot');
     if (!slot) {
       return;
@@ -114,9 +115,9 @@ export abstract class AccordionBase extends SpectrumElement {
       .assignedElements({ flatten: true })
       .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
     for (const item of items) {
-      item.heading = this.level;
+      item.setManagedHeading(this.level as AccordionHeadingLevel);
       item.size = this.size;
-      item.parentDisabled = this.disabled;
+      item.setManagedParentDisabled(this.disabled);
     }
   }
 
@@ -124,7 +125,7 @@ export abstract class AccordionBase extends SpectrumElement {
     super.connectedCallback();
     this.addEventListener(
       SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-      this.handleItemToggle
+      this.closeSiblingsOnOpen
     );
   }
 
@@ -132,7 +133,7 @@ export abstract class AccordionBase extends SpectrumElement {
     super.disconnectedCallback();
     this.removeEventListener(
       SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-      this.handleItemToggle
+      this.closeSiblingsOnOpen
     );
   }
 
@@ -148,7 +149,7 @@ export abstract class AccordionBase extends SpectrumElement {
       changedProperties.has('size') ||
       changedProperties.has('disabled')
     ) {
-      this.updateItems();
+      this.syncAccordionItems();
     }
     super.update(changedProperties);
   }
@@ -158,7 +159,7 @@ export abstract class AccordionBase extends SpectrumElement {
     if (window.__swc?.DEBUG && !this.hasAttribute('density')) {
       window.__swc.warn(
         this,
-        `<${this.localName}> should have an explicit "density" attribute set. Defaulting to "regular", which corresponds to the 1st-gen default.`,
+        `<${this.localName}> should have an explicit "density" attribute set. Defaulting to "regular".`,
         'https://opensource.adobe.com/spectrum-web-components/components/accordion/',
         { type: 'api', level: 'low' }
       );
diff --git a/2nd-gen/packages/core/components/accordion/Accordion.types.ts b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
index 44b0aba7eb..e3f16db9ec 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.types.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
@@ -16,4 +16,7 @@ export type AccordionSize = (typeof ACCORDION_VALID_SIZES)[number];
 export const ACCORDION_DENSITIES = ['compact', 'regular', 'spacious'] as const;
 export type AccordionDensity = (typeof ACCORDION_DENSITIES)[number];
 
+export const ACCORDION_HEADING_LEVELS = [2, 3, 4, 5, 6] as const;
+export type AccordionHeadingLevel = (typeof ACCORDION_HEADING_LEVELS)[number];
+
 export const SWC_ACCORDION_ITEM_TOGGLE_EVENT = 'swc-accordion-item-toggle';
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
similarity index 85%
rename from 2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
rename to 2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
index 4cff207560..9fd6f11e91 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItemBase.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
@@ -15,6 +15,7 @@ import { property, state } from 'lit/decorators.js';
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
 
 import {
+  type AccordionHeadingLevel,
   type AccordionSize,
   SWC_ACCORDION_ITEM_TOGGLE_EVENT,
 } from './Accordion.types.js';
@@ -60,11 +61,10 @@ export abstract class AccordionItemBase extends SpectrumElement {
   /**
    * @internal
    * Heading level (2–6) propagated by the parent accordion. Defaults to 3
-   * for standalone items. Public so AccordionBase can write to instances
-   * without a type assertion.
+   * for standalone items.
    */
   @state()
-  public heading: number = 3;
+  protected headingLevel: AccordionHeadingLevel = 3;
 
   /**
    * @internal
@@ -74,7 +74,7 @@ export abstract class AccordionItemBase extends SpectrumElement {
    * when the accordion is re-enabled.
    */
   @state()
-  public parentDisabled: boolean = false;
+  protected parentDisabled: boolean = false;
 
   // ──────────────────────
   //     IMPLEMENTATION
@@ -94,4 +94,20 @@ export abstract class AccordionItemBase extends SpectrumElement {
       })
     );
   }
+
+  /**
+   * @internal
+   * Synchronizes parent-managed heading level onto the item.
+   */
+  public setManagedHeading(heading: AccordionHeadingLevel): void {
+    this.headingLevel = heading;
+  }
+
+  /**
+   * @internal
+   * Synchronizes parent-managed disabled state onto the item.
+   */
+  public setManagedParentDisabled(disabled: boolean): void {
+    this.parentDisabled = disabled;
+  }
 }
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
deleted file mode 100644
index 349458211e..0000000000
--- a/2nd-gen/packages/core/components/accordion/AccordionItem.types.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-/**
- * Copyright 2026 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-
-// Item-specific types go here as the accordion item API is defined in subsequent commits.
diff --git a/2nd-gen/packages/core/components/accordion/index.ts b/2nd-gen/packages/core/components/accordion/index.ts
index a725fdc5fe..058e18a567 100644
--- a/2nd-gen/packages/core/components/accordion/index.ts
+++ b/2nd-gen/packages/core/components/accordion/index.ts
@@ -10,6 +10,6 @@
  * governing permissions and limitations under the License.
  */
 
-export * from './AccordionBase.js';
-export * from './AccordionItemBase.js';
+export * from './Accordion.base.js';
+export * from './AccordionItem.base.js';
 export * from './Accordion.types.js';
diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
index 43f4039dc4..02463a4b89 100644
--- a/2nd-gen/packages/swc/components/accordion/Accordion.ts
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -37,7 +37,7 @@ export class Accordion extends AccordionBase {
 
   protected override render(): TemplateResult {
     return html`
-      <slot @slotchange=${this.updateItems}></slot>
+      <slot @slotchange=${this.syncAccordionItems}></slot>
     `;
   }
 }
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 8312fc7e44..855e3e28ed 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -97,7 +97,7 @@ export class AccordionItem extends AccordionItemBase {
     }
   }
 
-  private handleActionsSlotChange(event: Event): void {
+  private syncActionsContainerVisibility(event: Event): void {
     const slot = event.target as HTMLSlotElement;
     const container = slot.parentElement as HTMLElement | null;
     if (container) {
@@ -105,7 +105,7 @@ export class AccordionItem extends AccordionItemBase {
     }
   }
 
-  private handleActionsContainerInteraction(event: Event): void {
+  private stopActionsContainerPropagation(event: Event): void {
     event.stopPropagation();
   }
 
@@ -117,7 +117,7 @@ export class AccordionItem extends AccordionItemBase {
   }
 
   private renderHeadingWrapper(content: TemplateResult): TemplateResult {
-    switch (this.heading) {
+    switch (this.headingLevel) {
       case 2:
         return html`
           <h2>${content}</h2>
@@ -167,10 +167,13 @@ export class AccordionItem extends AccordionItemBase {
       <div
         class="spectrum-Accordion-itemDirectActions"
         hidden
-        @click=${this.handleActionsContainerInteraction}
-        @keydown=${this.handleActionsContainerInteraction}
+        @click=${this.stopActionsContainerPropagation}
+        @keydown=${this.stopActionsContainerPropagation}
       >
-        <slot name="actions" @slotchange=${this.handleActionsSlotChange}></slot>
+        <slot
+          name="actions"
+          @slotchange=${this.syncActionsContainerVisibility}
+        ></slot>
       </div>
       <div
         id="content"

From 885c98ab7b650913ea612baf7c6ad15991f386b7 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 08:47:41 -0500
Subject: [PATCH 40/56] refactor: typing, heading rendering, sizing

---
 .../components/accordion/Accordion.base.ts    | 22 ++++++++++------
 .../components/accordion/Accordion.types.ts   |  9 ++++++-
 .../swc/components/accordion/AccordionItem.ts | 25 +++----------------
 3 files changed, 25 insertions(+), 31 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.base.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 96b37850f7..0d1722da31 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.base.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -14,8 +14,10 @@ import { PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
 
 import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
+import { SizedMixin } from '@spectrum-web-components/core/mixins/index.js';
 
 import {
+  ACCORDION_VALID_SIZES,
   type AccordionDensity,
   type AccordionHeadingLevel,
   type AccordionSize,
@@ -29,7 +31,10 @@ import { AccordionItemBase } from './AccordionItem.base.js';
  *
  * @slot - One or more `swc-accordion-item` elements.
  */
-export abstract class AccordionBase extends SpectrumElement {
+export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
+  validSizes: ACCORDION_VALID_SIZES,
+  defaultSize: 'm',
+}) {
   // ──────────────────
   //     PUBLIC API
   // ──────────────────
@@ -46,14 +51,12 @@ export abstract class AccordionBase extends SpectrumElement {
    * Values outside that range are clamped.
    */
   @property({ type: Number, reflect: true })
-  public level: number = 3;
+  public level: AccordionHeadingLevel = 3;
 
   /**
-   * Size applied to all items. When set, overrides any size set on individual
-   * items.
+   * Size applied to all items. Defaults to `m`.
    */
-  @property({ type: String, reflect: true })
-  public size?: AccordionSize;
+  declare public size: AccordionSize;
 
   /**
    * Controls vertical spacing between items.
@@ -115,7 +118,7 @@ export abstract class AccordionBase extends SpectrumElement {
       .assignedElements({ flatten: true })
       .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
     for (const item of items) {
-      item.setManagedHeading(this.level as AccordionHeadingLevel);
+      item.setManagedHeading(this.level);
       item.size = this.size;
       item.setManagedParentDisabled(this.disabled);
     }
@@ -139,7 +142,10 @@ export abstract class AccordionBase extends SpectrumElement {
 
   protected override update(changedProperties: PropertyValues): void {
     if (changedProperties.has('level')) {
-      const clamped = Math.min(6, Math.max(2, this.level));
+      const clamped = Math.min(
+        6,
+        Math.max(2, this.level)
+      ) as AccordionHeadingLevel;
       if (this.level !== clamped) {
         this.level = clamped;
       }
diff --git a/2nd-gen/packages/core/components/accordion/Accordion.types.ts b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
index e3f16db9ec..cc61783113 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.types.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.types.ts
@@ -10,7 +10,14 @@
  * governing permissions and limitations under the License.
  */
 
-export const ACCORDION_VALID_SIZES = ['s', 'm', 'l', 'xl'] as const;
+import type { ElementSize } from '@spectrum-web-components/core/mixins/index.js';
+
+export const ACCORDION_VALID_SIZES = [
+  's',
+  'm',
+  'l',
+  'xl',
+] as const satisfies readonly ElementSize[];
 export type AccordionSize = (typeof ACCORDION_VALID_SIZES)[number];
 
 export const ACCORDION_DENSITIES = ['compact', 'regular', 'spacious'] as const;
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 855e3e28ed..08f733e66d 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -12,6 +12,7 @@
 
 import { CSSResultArray, html, TemplateResult } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
+import { html as staticHtml, unsafeStatic } from 'lit/static-html.js';
 
 import {
   AccordionItemBase,
@@ -117,28 +118,8 @@ export class AccordionItem extends AccordionItemBase {
   }
 
   private renderHeadingWrapper(content: TemplateResult): TemplateResult {
-    switch (this.headingLevel) {
-      case 2:
-        return html`
-          <h2>${content}</h2>
-        `;
-      case 4:
-        return html`
-          <h4>${content}</h4>
-        `;
-      case 5:
-        return html`
-          <h5>${content}</h5>
-        `;
-      case 6:
-        return html`
-          <h6>${content}</h6>
-        `;
-      default:
-        return html`
-          <h3>${content}</h3>
-        `;
-    }
+    const tag = unsafeStatic(`h${this.headingLevel}`);
+    return staticHtml`<${tag}>${content}</${tag}>`;
   }
 
   protected override render(): TemplateResult {

From e2cb7d3861d37c0cf339161b3c58cf6facc813d5 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 10:44:36 -0500
Subject: [PATCH 41/56] refactor: move toggle() into base, smooth a11y behavior

---
 .../components/accordion/Accordion.base.ts    | 58 +++++++++++++++----
 .../accordion/AccordionItem.base.ts           | 23 +++++---
 .../swc/components/accordion/AccordionItem.ts | 29 ++--------
 3 files changed, 68 insertions(+), 42 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.base.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 0d1722da31..2163f10c80 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.base.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -92,10 +92,34 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
       return;
     }
     const toggling = event.target;
-    if (!(toggling instanceof AccordionItemBase) || !toggling.open) {
+    if (!(toggling instanceof AccordionItemBase)) {
       return;
     }
-    const slot = this.shadowRoot?.querySelector('slot');
+    // Defer until after dispatch returns so that a canceled toggle (where the
+    // item reverts open back to false) does not incorrectly close siblings.
+    queueMicrotask(() => {
+      if (!toggling.open) {
+        return;
+      }
+      const slot = this.shadowRoot?.querySelector('slot');
+      if (!slot) {
+        return;
+      }
+      const items = slot
+        .assignedElements({ flatten: true })
+        .filter(
+          (el): el is AccordionItemBase => el instanceof AccordionItemBase
+        );
+      for (const item of items) {
+        if (item !== toggling) {
+          item.open = false;
+        }
+      }
+    });
+  };
+
+  protected syncAccordionItems(): void {
+    const slot = this.renderRoot?.querySelector('slot');
     if (!slot) {
       return;
     }
@@ -103,13 +127,13 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
       .assignedElements({ flatten: true })
       .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
     for (const item of items) {
-      if (item !== toggling) {
-        item.open = false;
-      }
+      item.setManagedHeading(this.level);
+      item.size = this.size;
+      item.setManagedParentDisabled(this.disabled);
     }
-  };
+  }
 
-  protected syncAccordionItems(): void {
+  private enforceExclusiveOpen(): void {
     const slot = this.renderRoot?.querySelector('slot');
     if (!slot) {
       return;
@@ -117,10 +141,15 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
     const items = slot
       .assignedElements({ flatten: true })
       .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
+    let foundOpen = false;
     for (const item of items) {
-      item.setManagedHeading(this.level);
-      item.size = this.size;
-      item.setManagedParentDisabled(this.disabled);
+      if (item.open) {
+        if (foundOpen) {
+          item.open = false;
+        } else {
+          foundOpen = true;
+        }
+      }
     }
   }
 
@@ -157,6 +186,15 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
     ) {
       this.syncAccordionItems();
     }
+    // changedProperties.get() returns the previous value; this fires only when
+    // disabled transitions from true → false (re-enable).
+    if (
+      changedProperties.has('disabled') &&
+      changedProperties.get('disabled') === true &&
+      !this.allowMultiple
+    ) {
+      this.enforceExclusiveOpen();
+    }
     super.update(changedProperties);
   }
 
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
index 9fd6f11e91..d44c4e6f97 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
@@ -82,17 +82,22 @@ export abstract class AccordionItemBase extends SpectrumElement {
 
   /**
    * @internal
-   * Dispatches the toggle event. The concrete class wires this to the
-   * header button's click handler and adds open-state management.
+   * Toggles the item open state. Guards for disabled, flips `open`, dispatches
+   * the toggle event, and reverts if the event is canceled.
    */
   protected toggle(): void {
-    this.dispatchEvent(
-      new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
-        bubbles: true,
-        composed: true,
-        cancelable: true,
-      })
-    );
+    if (this.disabled || this.parentDisabled) {
+      return;
+    }
+    this.open = !this.open;
+    const event = new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+    });
+    if (!this.dispatchEvent(event)) {
+      this.open = !this.open;
+    }
   }
 
   /**
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 08f733e66d..5c8558398e 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -14,10 +14,7 @@ import { CSSResultArray, html, TemplateResult } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { html as staticHtml, unsafeStatic } from 'lit/static-html.js';
 
-import {
-  AccordionItemBase,
-  SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-} from '@spectrum-web-components/core/components/accordion';
+import { AccordionItemBase } from '@spectrum-web-components/core/components/accordion';
 
 import '../icon/swc-icon.js';
 
@@ -61,25 +58,6 @@ export class AccordionItem extends AccordionItemBase {
     this.shadowRoot?.getElementById('header')?.click();
   }
 
-  // ──────────────────────────────
-  //     TOGGLE BEHAVIOR
-  // ──────────────────────────────
-
-  protected override toggle(): void {
-    if (this.disabled || this.parentDisabled) {
-      return;
-    }
-    this.open = !this.open;
-    const event = new Event(SWC_ACCORDION_ITEM_TOGGLE_EVENT, {
-      bubbles: true,
-      composed: true,
-      cancelable: true,
-    });
-    if (!this.dispatchEvent(event)) {
-      this.open = !this.open;
-    }
-  }
-
   // ──────────────────────────────
   //     RENDERING
   // ──────────────────────────────
@@ -112,6 +90,10 @@ export class AccordionItem extends AccordionItemBase {
 
   private handleHeaderKeydown(event: Event): void {
     if ((event as KeyboardEvent).key === ' ') {
+      // Space requires preventDefault to suppress page scroll; toggle is then
+      // called explicitly. Enter is not handled here — the browser's native
+      // button activation fires a click event, which calls toggle() via the
+      // @click binding.
       event.preventDefault();
       this.toggle();
     }
@@ -161,6 +143,7 @@ export class AccordionItem extends AccordionItemBase {
         class="spectrum-Accordion-itemContent"
         role="region"
         aria-labelledby="header"
+        ?hidden=${!this.open}
         .inert=${this.disabled || this.parentDisabled}
       >
         <slot></slot>

From 365577aaf76835f4531e4fa14b299b9cd0e1c26a Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 11:29:27 -0500
Subject: [PATCH 42/56] refactor: use assignedItems() helper

---
 .../components/accordion/Accordion.base.ts    | 39 +++++++------------
 1 file changed, 13 insertions(+), 26 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.base.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 2163f10c80..904e721ddd 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.base.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -83,6 +83,16 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
   //     IMPLEMENTATION
   // ──────────────────────
 
+  private assignedItems(): AccordionItemBase[] {
+    const slot = this.renderRoot?.querySelector('slot');
+    if (!slot) {
+      return [];
+    }
+    return slot
+      .assignedElements({ flatten: true })
+      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
+  }
+
   private closeSiblingsOnOpen = (event: Event): void => {
     if (this.disabled) {
       event.preventDefault();
@@ -101,16 +111,7 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
       if (!toggling.open) {
         return;
       }
-      const slot = this.shadowRoot?.querySelector('slot');
-      if (!slot) {
-        return;
-      }
-      const items = slot
-        .assignedElements({ flatten: true })
-        .filter(
-          (el): el is AccordionItemBase => el instanceof AccordionItemBase
-        );
-      for (const item of items) {
+      for (const item of this.assignedItems()) {
         if (item !== toggling) {
           item.open = false;
         }
@@ -119,14 +120,7 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
   };
 
   protected syncAccordionItems(): void {
-    const slot = this.renderRoot?.querySelector('slot');
-    if (!slot) {
-      return;
-    }
-    const items = slot
-      .assignedElements({ flatten: true })
-      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
-    for (const item of items) {
+    for (const item of this.assignedItems()) {
       item.setManagedHeading(this.level);
       item.size = this.size;
       item.setManagedParentDisabled(this.disabled);
@@ -134,15 +128,8 @@ export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
   }
 
   private enforceExclusiveOpen(): void {
-    const slot = this.renderRoot?.querySelector('slot');
-    if (!slot) {
-      return;
-    }
-    const items = slot
-      .assignedElements({ flatten: true })
-      .filter((el): el is AccordionItemBase => el instanceof AccordionItemBase);
     let foundOpen = false;
-    for (const item of items) {
+    for (const item of this.assignedItems()) {
       if (item.open) {
         if (foundOpen) {
           item.open = false;

From 12d576048c80e80dea27f827b6ba6f273c6b469e Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 12:06:35 -0500
Subject: [PATCH 43/56] test: add a11y tests

---
 .../swc/components/accordion/test/.gitkeep    |   1 -
 .../accordion/test/accordion.test.ts          | 584 ++++++++++++++++++
 2 files changed, 584 insertions(+), 1 deletion(-)
 delete mode 100644 2nd-gen/packages/swc/components/accordion/test/.gitkeep
 create mode 100644 2nd-gen/packages/swc/components/accordion/test/accordion.test.ts

diff --git a/2nd-gen/packages/swc/components/accordion/test/.gitkeep b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
deleted file mode 100644
index 8b13789179..0000000000
--- a/2nd-gen/packages/swc/components/accordion/test/.gitkeep
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
new file mode 100644
index 0000000000..7ef3846e33
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
@@ -0,0 +1,584 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { html } from 'lit';
+import { expect } from '@storybook/test';
+import type { Meta, StoryObj as Story } from '@storybook/web-components';
+
+import { Accordion, AccordionItem } from '@adobe/spectrum-wc/accordion';
+
+import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
+import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
+
+import { SWC_ACCORDION_ITEM_TOGGLE_EVENT } from '../../../../core/components/accordion/Accordion.types.js';
+import { getComponent, getComponents } from '../../../utils/test-utils.js';
+import meta, { Overview } from '../stories/accordion.stories.js';
+
+export default {
+  ...meta,
+  title: 'Accordion/Tests',
+  parameters: {
+    ...meta.parameters,
+    docs: { disable: true, page: null },
+  },
+  tags: ['!autodocs', 'dev'],
+} as Meta;
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Defaults
+// ──────────────────────────────────────────────────────────────
+
+export const OverviewTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const items = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+
+    await step('renders three items', async () => {
+      expect(items.length, 'three accordion items are rendered').toBe(3);
+    });
+
+    await step('third item is open by default', async () => {
+      expect(items[2]?.open, 'third item open property is true').toBe(true);
+    });
+
+    await step('first two items are closed by default', async () => {
+      expect(items[0]?.open, 'first item open property is false').toBe(false);
+      expect(items[1]?.open, 'second item open property is false').toBe(false);
+    });
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: ARIA contract
+// ──────────────────────────────────────────────────────────────
+
+export const AriaContractTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const items = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const closedItem = items[0] as AccordionItem;
+    const openItem = items[2] as AccordionItem;
+
+    const closedButton = closedItem.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const closedPanel = closedItem.shadowRoot?.getElementById(
+      'content'
+    ) as HTMLElement;
+    const openButton = openItem.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const openPanel = openItem.shadowRoot?.getElementById(
+      'content'
+    ) as HTMLElement;
+
+    await step('aria-expanded reflects open state', async () => {
+      expect(
+        closedButton.getAttribute('aria-expanded'),
+        'closed item button has aria-expanded="false"'
+      ).toBe('false');
+      expect(
+        openButton.getAttribute('aria-expanded'),
+        'open item button has aria-expanded="true"'
+      ).toBe('true');
+    });
+
+    await step('aria-controls value matches the panel id', async () => {
+      expect(
+        closedButton.getAttribute('aria-controls'),
+        'aria-controls is "content"'
+      ).toBe('content');
+      expect(closedPanel.id, 'panel id is "content"').toBe('content');
+    });
+
+    await step(
+      'panel has role="region" and aria-labelledby="header"',
+      async () => {
+        expect(closedPanel.getAttribute('role'), 'panel role is "region"').toBe(
+          'region'
+        );
+        expect(
+          closedPanel.getAttribute('aria-labelledby'),
+          'panel aria-labelledby is "header"'
+        ).toBe('header');
+      }
+    );
+
+    await step(
+      'closed panel has hidden attribute; open panel does not',
+      async () => {
+        expect(
+          closedPanel.hasAttribute('hidden'),
+          'closed panel has hidden attribute'
+        ).toBe(true);
+        expect(
+          openPanel.hasAttribute('hidden'),
+          'open panel does not have hidden attribute'
+        ).toBe(false);
+      }
+    );
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Open / close
+// ──────────────────────────────────────────────────────────────
+
+export const ToggleTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const items = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const item = items[0] as AccordionItem;
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step('clicking the header button opens a closed item', async () => {
+      expect(item.open, 'item starts closed').toBe(false);
+
+      button.click();
+      await new Promise<void>((resolve) => queueMicrotask(resolve));
+      await item.updateComplete;
+
+      expect(item.open, 'item is now open').toBe(true);
+      expect(
+        button.getAttribute('aria-expanded'),
+        'aria-expanded is "true" after open'
+      ).toBe('true');
+      expect(
+        panel.hasAttribute('hidden'),
+        'hidden attribute is removed when panel is open'
+      ).toBe(false);
+    });
+
+    await step('clicking the header button again closes the item', async () => {
+      button.click();
+      await new Promise<void>((resolve) => queueMicrotask(resolve));
+      await item.updateComplete;
+
+      expect(item.open, 'item is closed again').toBe(false);
+      expect(
+        button.getAttribute('aria-expanded'),
+        'aria-expanded is "false" after close'
+      ).toBe('false');
+      expect(
+        panel.hasAttribute('hidden'),
+        'hidden attribute is restored when panel is closed'
+      ).toBe(true);
+    });
+  },
+};
+
+export const ToggleEventTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const item = (
+      await getComponents<AccordionItem>(canvasElement, 'swc-accordion-item')
+    )[0] as AccordionItem;
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+
+    await step(
+      'clicking the header button dispatches the toggle event',
+      async () => {
+        let toggleFired = false;
+        item.addEventListener(
+          SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+          () => {
+            toggleFired = true;
+          },
+          { once: true }
+        );
+
+        button.click();
+        await item.updateComplete;
+
+        expect(toggleFired, 'toggle event was dispatched').toBe(true);
+      }
+    );
+
+    await step(
+      'toggle event is cancelable; canceling reverts open state',
+      async () => {
+        const wasOpen = item.open;
+        item.addEventListener(
+          SWC_ACCORDION_ITEM_TOGGLE_EVENT,
+          (event) => {
+            event.preventDefault();
+          },
+          { once: true }
+        );
+
+        button.click();
+        await item.updateComplete;
+
+        expect(item.open, 'open state is reverted when event is canceled').toBe(
+          wasOpen
+        );
+      }
+    );
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Disabled item
+// ──────────────────────────────────────────────────────────────
+
+export const DisabledItemTest: Story = {
+  render: () => html`
+    <swc-accordion density="regular">
+      <swc-accordion-item disabled>
+        <span slot="label">Disabled item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step('disabled item button has aria-disabled="true"', async () => {
+      expect(
+        button.getAttribute('aria-disabled'),
+        'aria-disabled is "true"'
+      ).toBe('true');
+    });
+
+    await step(
+      'disabled item button does not have native disabled attribute',
+      async () => {
+        expect(
+          button.hasAttribute('disabled'),
+          'native disabled attribute is absent'
+        ).toBe(false);
+      }
+    );
+
+    await step('disabled item button remains in the tab order', async () => {
+      expect(button.tabIndex, 'tabIndex is not -1').not.toBe(-1);
+    });
+
+    await step('disabled item panel is inert', async () => {
+      expect(panel.inert, 'panel inert property is true').toBe(true);
+    });
+
+    await step('clicking a disabled item does not open it', async () => {
+      button.click();
+      await item.updateComplete;
+
+      expect(item.open, 'item remains closed after click').toBe(false);
+    });
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Host disabled
+// ──────────────────────────────────────────────────────────────
+
+export const HostDisabledTest: Story = {
+  render: () => html`
+    <swc-accordion disabled density="regular">
+      <swc-accordion-item>
+        <span slot="label">Item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const accordion = await getComponent<Accordion>(
+      canvasElement,
+      'swc-accordion'
+    );
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step(
+      'item button has aria-disabled when the host accordion is disabled',
+      async () => {
+        expect(
+          button.getAttribute('aria-disabled'),
+          'aria-disabled is "true" via host disabled'
+        ).toBe('true');
+      }
+    );
+
+    await step(
+      'item button does not have native disabled when host is disabled',
+      async () => {
+        expect(
+          button.hasAttribute('disabled'),
+          'native disabled attribute is absent'
+        ).toBe(false);
+      }
+    );
+
+    await step('item panel is inert when host is disabled', async () => {
+      expect(panel.inert, 'panel inert is true').toBe(true);
+    });
+
+    await step(
+      'clicking an item does not open it when the host is disabled',
+      async () => {
+        button.click();
+        await item.updateComplete;
+
+        expect(
+          item.open,
+          'item remains closed after click on host-disabled accordion'
+        ).toBe(false);
+      }
+    );
+
+    await step('clearing host disabled allows the item to open', async () => {
+      accordion.disabled = false;
+      await accordion.updateComplete;
+      await item.updateComplete;
+
+      expect(
+        button.getAttribute('aria-disabled'),
+        'aria-disabled is removed after host re-enabled'
+      ).toBeNull();
+      expect(panel.inert, 'panel is no longer inert').toBe(false);
+
+      button.click();
+      await item.updateComplete;
+
+      expect(item.open, 'item opens after host is re-enabled').toBe(true);
+    });
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Keyboard
+// ──────────────────────────────────────────────────────────────
+
+export const SpaceKeyTest: Story = {
+  render: () => html`
+    <swc-accordion density="regular">
+      <swc-accordion-item>
+        <span slot="label">Item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+
+    await step(
+      'Space on the header button calls preventDefault and opens the item',
+      async () => {
+        const event = new KeyboardEvent('keydown', {
+          key: ' ',
+          bubbles: true,
+          cancelable: true,
+        });
+        button.dispatchEvent(event);
+        await item.updateComplete;
+
+        expect(
+          event.defaultPrevented,
+          'Space keydown default is prevented'
+        ).toBe(true);
+        expect(item.open, 'item is open after Space').toBe(true);
+      }
+    );
+
+    await step(
+      'Space on a disabled header button prevents default but does not toggle',
+      async () => {
+        item.disabled = true;
+        await item.updateComplete;
+
+        const event = new KeyboardEvent('keydown', {
+          key: ' ',
+          bubbles: true,
+          cancelable: true,
+        });
+        button.dispatchEvent(event);
+        await item.updateComplete;
+
+        expect(
+          event.defaultPrevented,
+          'Space keydown default is still prevented on disabled item'
+        ).toBe(true);
+        expect(
+          item.open,
+          'open state does not change when item is disabled'
+        ).toBe(true);
+      }
+    );
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Exclusive open (allow-multiple: false)
+// ──────────────────────────────────────────────────────────────
+
+export const ExclusiveOpenTest: Story = {
+  ...Overview,
+  play: async ({ canvasElement, step }) => {
+    const items = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const item1 = items[0] as AccordionItem;
+    const item3 = items[2] as AccordionItem;
+    const button1 = item1.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+
+    await step('opening one item closes the previously open item', async () => {
+      expect(item3.open, 'third item starts open').toBe(true);
+
+      button1.click();
+      // closeSiblingsOnOpen defers via queueMicrotask; wait for it to run.
+      await new Promise<void>((resolve) => queueMicrotask(resolve));
+      await item1.updateComplete;
+      await item3.updateComplete;
+
+      expect(item1.open, 'first item is now open').toBe(true);
+      expect(item3.open, 'third item is now closed').toBe(false);
+    });
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Allow-multiple
+// ──────────────────────────────────────────────────────────────
+
+export const AllowMultipleTest: Story = {
+  render: () => html`
+    <swc-accordion allow-multiple density="regular">
+      <swc-accordion-item>
+        <span slot="label">Alchemy</span>
+        Alchemy content
+      </swc-accordion-item>
+      <swc-accordion-item open>
+        <span slot="label">Astrology</span>
+        Astrology content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const [item1, item2] = await getComponents<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button1 = (item1 as AccordionItem).shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+
+    await step(
+      'opening one item does not close others when allow-multiple is set',
+      async () => {
+        expect((item2 as AccordionItem).open, 'second item starts open').toBe(
+          true
+        );
+
+        button1.click();
+        await new Promise<void>((resolve) => queueMicrotask(resolve));
+        await (item1 as AccordionItem).updateComplete;
+        await (item2 as AccordionItem).updateComplete;
+
+        expect((item1 as AccordionItem).open, 'first item is now open').toBe(
+          true
+        );
+        expect((item2 as AccordionItem).open, 'second item is still open').toBe(
+          true
+        );
+      }
+    );
+  },
+};
+
+// ──────────────────────────────────────────────────────────────
+// TEST: Heading level
+// ──────────────────────────────────────────────────────────────
+
+export const HeadingLevelTest: Story = {
+  render: () => html`
+    <swc-accordion level="4" density="regular">
+      <swc-accordion-item>
+        <span slot="label">Item</span>
+        Content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const accordion = await getComponent<Accordion>(
+      canvasElement,
+      'swc-accordion'
+    );
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    await item.updateComplete;
+
+    await step(
+      'item renders the heading tag matching the accordion level',
+      async () => {
+        expect(
+          item.shadowRoot?.querySelector('h4'),
+          'h4 element is in the item shadow DOM'
+        ).toBeTruthy();
+      }
+    );
+
+    await step(
+      'heading tag updates when the accordion level changes',
+      async () => {
+        accordion.level = 2;
+        await accordion.updateComplete;
+        await item.updateComplete;
+
+        expect(
+          item.shadowRoot?.querySelector('h4'),
+          'h4 is no longer present after level change'
+        ).toBeNull();
+        expect(
+          item.shadowRoot?.querySelector('h2'),
+          'h2 element is in the item shadow DOM'
+        ).toBeTruthy();
+      }
+    );
+  },
+};

From e10e351dcf424b783a8d50d1baa20d7f2139fe20 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 13:23:43 -0500
Subject: [PATCH 44/56] docs: add a11y docs

---
 .../accordion/stories/accordion.stories.ts    | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index 4284e11925..b8f71a4dd7 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -125,3 +125,69 @@ export const Overview: Story = {
   },
   tags: ['overview'],
 };
+
+// ────────────────────────────────
+//    ACCESSIBILITY STORIES
+// ────────────────────────────────
+
+/**
+ * ### Features
+ *
+ * The `<swc-accordion>` and `<swc-accordion-item>` elements implement the
+ * [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/):
+ *
+ * #### Keyboard navigation
+ *
+ * - <kbd>Tab</kbd>: Moves focus into and between item header buttons
+ * - <kbd>Enter</kbd>: Activates the focused header button (browser-native click behavior)
+ * - <kbd>Space</kbd>: Toggles the focused item and prevents page scroll
+ *
+ * #### ARIA implementation
+ *
+ * 1. **Heading wrapper**: Each header button is wrapped in an `h2`–`h6` element matching
+ *    the accordion's `level` attribute
+ * 2. **`aria-expanded`**: Set to `"true"` on open items, `"false"` on closed items
+ * 3. **`aria-controls`**: Points from the header button to the panel (`id="content"`)
+ * 4. **Panel role**: The panel has `role="region"` and `aria-labelledby` pointing to the
+ *    header button, making it a labeled landmark
+ * 5. **`aria-disabled`**: Set on the header button (not the native `disabled` attribute)
+ *    so disabled items remain keyboard-reachable
+ * 6. **`hidden`**: Added to closed panels to remove them from the accessibility tree
+ * 7. **`inert`**: Added to disabled-item panels to block interaction with their contents
+ *
+ * ### Best practices
+ *
+ * - Set a `level` that continues the existing page heading hierarchy without skipping levels
+ * - Provide meaningful, unique label text for each item so screen reader users can
+ *   navigate the heading list
+ * - When using the `actions` slot, include the item subject in the action's accessible
+ *   name (e.g., "Edit Alchemy" rather than "Edit") so it is unambiguous out of context
+ * - Always set `density` explicitly; use `regular` when unsure
+ */
+export const Accessibility: Story = {
+  render: () => html`
+    <swc-accordion level="3" density="regular">
+      <swc-accordion-item open>
+        <span slot="label">Alchemy</span>
+        <button slot="actions" aria-label="Edit Alchemy">Edit</button>
+        Alchemy is an ancient branch of natural philosophy, a philosophical and
+        protoscientific tradition that was historically practiced in China,
+        India, the Muslim world, and Europe.
+      </swc-accordion-item>
+      <swc-accordion-item>
+        <span slot="label">Astrology</span>
+        <button slot="actions" aria-label="Edit Astrology">Edit</button>
+        Astrology is a range of divinatory practices, recognized as
+        pseudoscientific since the 18th century, that propose that information
+        about human affairs and terrestrial events may be discerned by studying
+        the apparent positions of celestial objects.
+      </swc-accordion-item>
+      <swc-accordion-item disabled>
+        <span slot="label">Natural magic (disabled)</span>
+        Natural magic in the context of early modern Europe was a branch of
+        philosophy that treated occult forces as resulting from natural causes.
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  tags: ['a11y'],
+};

From b16028bc9557cc5920abbf85119ad3dbc3217e55 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 14:49:17 -0500
Subject: [PATCH 45/56] fix: freeze accordion open state when disabled

---
 .../accordion/AccordionItem.base.ts           |  34 ++++-
 .../accordion/test/accordion.test.ts          | 118 ++++++++++++++++++
 2 files changed, 150 insertions(+), 2 deletions(-)

diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
index d44c4e6f97..c22793ad7b 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
@@ -38,7 +38,26 @@ export abstract class AccordionItemBase extends SpectrumElement {
    * Whether the accordion item panel is expanded.
    */
   @property({ type: Boolean, reflect: true })
-  public open: boolean = false;
+  public get open(): boolean {
+    return this._open;
+  }
+
+  public set open(value: boolean) {
+    if (this.hasUpdated && !this.mayExpand() && value !== this._open) {
+      return;
+    }
+    if (value === this._open) {
+      return;
+    }
+    const oldValue = this._open;
+    this._open = value;
+    if (value) {
+      this.setAttribute('open', '');
+    } else {
+      this.removeAttribute('open');
+    }
+    this.requestUpdate('open', oldValue);
+  }
 
   /**
    * Whether the accordion item is disabled. A disabled item keeps its header
@@ -54,6 +73,8 @@ export abstract class AccordionItemBase extends SpectrumElement {
   @property({ type: String, reflect: true })
   public size?: AccordionSize;
 
+  private _open = false;
+
   // ──────────────────────
   //     INTERNAL STATE
   // ──────────────────────
@@ -80,13 +101,22 @@ export abstract class AccordionItemBase extends SpectrumElement {
   //     IMPLEMENTATION
   // ──────────────────────
 
+  /**
+   * @internal
+   * Whether the item may change `open` (expand or collapse). When false, the
+   * `open` setter and `toggle()` leave state unchanged.
+   */
+  protected mayExpand(): boolean {
+    return !this.disabled && !this.parentDisabled;
+  }
+
   /**
    * @internal
    * Toggles the item open state. Guards for disabled, flips `open`, dispatches
    * the toggle event, and reverts if the event is canceled.
    */
   protected toggle(): void {
-    if (this.disabled || this.parentDisabled) {
+    if (!this.mayExpand()) {
       return;
     }
     this.open = !this.open;
diff --git a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
index 7ef3846e33..ab40b3dca8 100644
--- a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
+++ b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
@@ -294,6 +294,63 @@ export const DisabledItemTest: Story = {
 
       expect(item.open, 'item remains closed after click').toBe(false);
     });
+
+    await step(
+      'setting open on a closed disabled item does not expand it',
+      async () => {
+        item.open = true;
+        await item.updateComplete;
+
+        expect(item.open, 'open property stays false').toBe(false);
+        expect(
+          panel.hasAttribute('hidden'),
+          'panel stays hidden after imperative open'
+        ).toBe(true);
+      }
+    );
+  },
+};
+
+export const DisabledOpenItemTest: Story = {
+  render: () => html`
+    <swc-accordion density="regular">
+      <swc-accordion-item disabled open>
+        <span slot="label">Disabled open item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step('disabled open item starts expanded', async () => {
+      expect(item.open, 'item starts open').toBe(true);
+    });
+
+    await step(
+      'setting open to false on a disabled item does not collapse it',
+      async () => {
+        item.open = false;
+        await item.updateComplete;
+
+        expect(item.open, 'open property stays true').toBe(true);
+        expect(
+          panel.hasAttribute('hidden'),
+          'panel stays visible after imperative close'
+        ).toBe(false);
+        expect(
+          button.getAttribute('aria-expanded'),
+          'aria-expanded stays true'
+        ).toBe('true');
+      }
+    );
   },
 };
 
@@ -361,6 +418,24 @@ export const HostDisabledTest: Story = {
       }
     );
 
+    await step(
+      'setting open on a closed item does not expand it when the host is disabled',
+      async () => {
+        item.open = true;
+        await item.updateComplete;
+
+        expect(item.open, 'open property stays false').toBe(false);
+        expect(
+          panel.hasAttribute('hidden'),
+          'panel stays hidden after imperative open'
+        ).toBe(true);
+        expect(
+          button.getAttribute('aria-expanded'),
+          'aria-expanded stays false'
+        ).toBe('false');
+      }
+    );
+
     await step('clearing host disabled allows the item to open', async () => {
       accordion.disabled = false;
       await accordion.updateComplete;
@@ -380,6 +455,49 @@ export const HostDisabledTest: Story = {
   },
 };
 
+export const HostDisabledOpenItemTest: Story = {
+  render: () => html`
+    <swc-accordion disabled density="regular">
+      <swc-accordion-item open>
+        <span slot="label">Item</span>
+        Panel content
+      </swc-accordion-item>
+    </swc-accordion>
+  `,
+  play: async ({ canvasElement, step }) => {
+    const item = await getComponent<AccordionItem>(
+      canvasElement,
+      'swc-accordion-item'
+    );
+    const button = item.shadowRoot?.getElementById(
+      'header'
+    ) as HTMLButtonElement;
+    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
+
+    await step('open item stays expanded while host is disabled', async () => {
+      expect(item.open, 'item starts open').toBe(true);
+    });
+
+    await step(
+      'setting open to false does not collapse the item when the host is disabled',
+      async () => {
+        item.open = false;
+        await item.updateComplete;
+
+        expect(item.open, 'open property stays true').toBe(true);
+        expect(
+          panel.hasAttribute('hidden'),
+          'panel stays visible after imperative close'
+        ).toBe(false);
+        expect(
+          button.getAttribute('aria-expanded'),
+          'aria-expanded stays true'
+        ).toBe('true');
+      }
+    );
+  },
+};
+
 // ──────────────────────────────────────────────────────────────
 // TEST: Keyboard
 // ──────────────────────────────────────────────────────────────

From b102a889b52f729a4561f15d8a72469b4a37bcfb Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 15:37:32 -0500
Subject: [PATCH 46/56] feat: 1st-gen deprecation warnings/tests

---
 1st-gen/packages/accordion/src/Accordion.ts   |  33 ++++-
 .../packages/accordion/src/AccordionItem.ts   |  20 ++-
 .../accordion/test/deprecation.test.ts        | 134 ++++++++++++++++++
 .../packages/accordion/test/dev-mode.test.ts  |  39 ++++-
 1st-gen/tools/base/src/version.d.ts           |   4 +-
 5 files changed, 221 insertions(+), 9 deletions(-)
 create mode 100644 1st-gen/packages/accordion/test/deprecation.test.ts

diff --git a/1st-gen/packages/accordion/src/Accordion.ts b/1st-gen/packages/accordion/src/Accordion.ts
index 6ec2dae9ad..4b8b9ee93e 100644
--- a/1st-gen/packages/accordion/src/Accordion.ts
+++ b/1st-gen/packages/accordion/src/Accordion.ts
@@ -27,6 +27,9 @@ import { FocusGroupController } from '@spectrum-web-components/reactive-controll
 import styles from './accordion.css.js';
 import { AccordionItem } from './AccordionItem.js';
 
+const ACCORDION_MIGRATION_DOC_URL =
+  'https://opensource.adobe.com/spectrum-web-components/components/accordion/';
+
 /**
  * @element sp-accordion
  * @slot - The sp-accordion-item children to display.
@@ -72,7 +75,19 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     isFocusableElement: (el: AccordionItem) => !el.disabled,
   });
 
+  /**
+   * @deprecated `focus()` on `<sp-accordion>` is deprecated and will be removed
+   * in Spectrum 2. Focus the header button inside `<sp-accordion-item>` instead.
+   */
   public override focus(): void {
+    if (window.__swc?.DEBUG) {
+      window.__swc.warn(
+        this,
+        `<${this.localName}> focus() is deprecated and will be removed in Spectrum 2. Focus the header button inside <sp-accordion-item> instead.`,
+        ACCORDION_MIGRATION_DOC_URL,
+        { level: 'deprecation' }
+      );
+    }
     this.focusGroupController.focus();
   }
 
@@ -99,11 +114,23 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     });
   }
 
+  private syncAssignedItem(item: AccordionItem): void {
+    if (window.__swc?.DEBUG && item.level !== this.level) {
+      window.__swc.warn(
+        item,
+        `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
+        ACCORDION_MIGRATION_DOC_URL,
+        { level: 'deprecation' }
+      );
+    }
+    item.size = this.size;
+    item.level = this.level;
+  }
+
   private handleSlotchange(): void {
     this.focusGroupController.clearElementCache();
     this.items.forEach((item) => {
-      item.size = this.size;
-      item.level = this.level;
+      this.syncAssignedItem(item);
     });
   }
 
@@ -116,7 +143,7 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     }
     if (changed.has('level')) {
       this.items.forEach((item) => {
-        item.level = this.level;
+        this.syncAssignedItem(item);
       });
     }
   }
diff --git a/1st-gen/packages/accordion/src/AccordionItem.ts b/1st-gen/packages/accordion/src/AccordionItem.ts
index 80dd83bbe2..3857ce908d 100644
--- a/1st-gen/packages/accordion/src/AccordionItem.ts
+++ b/1st-gen/packages/accordion/src/AccordionItem.ts
@@ -61,10 +61,13 @@ const chevronIcon: Record<string, () => TemplateResult> = {
   `,
 };
 
+const ACCORDION_MIGRATION_DOC_URL =
+  'https://opensource.adobe.com/spectrum-web-components/components/accordion/';
+
 /**
  * @element sp-accordion-item
  * @slot - The content of the item that is hidden when the item is not open
- * @fires sp-accordion-item-toggle - Announce that an accordion item has been toggled while allowing the event to be cancelled.
+ * @fires sp-accordion-item-toggle - Announce that an accordion item has been toggled while allowing the event to be cancelled. In Spectrum 2, this event is renamed to `swc-accordion-item-toggle`.
  */
 export class AccordionItem extends SizedMixin(Focusable, {
   noDefaultSize: true,
@@ -76,6 +79,10 @@ export class AccordionItem extends SizedMixin(Focusable, {
   @property({ type: Boolean, reflect: true })
   public open = false;
 
+  /**
+   * @deprecated The `label` attribute is deprecated and will be removed in
+   * Spectrum 2.
+   */
   @property({ type: String, reflect: true })
   public label = '';
 
@@ -86,6 +93,9 @@ export class AccordionItem extends SizedMixin(Focusable, {
    * The heading level (2-6) to use for the accordion item title.
    * This property is set by the parent sp-accordion element.
    * Defaults to 3.
+   *
+   * @deprecated The `level` attribute on accordion items is deprecated and will
+   * be removed in Spectrum 2. Use `level` on `<sp-accordion>` instead.
    */
   @property({ type: Number, reflect: true })
   public level: number = 3;
@@ -182,5 +192,13 @@ export class AccordionItem extends SizedMixin(Focusable, {
         this.removeAttribute('aria-disabled');
       }
     }
+    if (window.__swc?.DEBUG && changes.has('label') && this.label) {
+      window.__swc.warn(
+        this,
+        `<${this.localName}> the "label" attribute is deprecated and will be removed in Spectrum 2.`,
+        ACCORDION_MIGRATION_DOC_URL,
+        { level: 'deprecation' }
+      );
+    }
   }
 }
diff --git a/1st-gen/packages/accordion/test/deprecation.test.ts b/1st-gen/packages/accordion/test/deprecation.test.ts
new file mode 100644
index 0000000000..dab3a9e5d4
--- /dev/null
+++ b/1st-gen/packages/accordion/test/deprecation.test.ts
@@ -0,0 +1,134 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { elementUpdated, expect, fixture, html } from '@open-wc/testing';
+import { SinonSpyCall, SinonStub, stub } from 'sinon';
+
+import { Accordion, AccordionItem } from '@spectrum-web-components/accordion';
+
+import '@spectrum-web-components/accordion/sp-accordion.js';
+import '@spectrum-web-components/accordion/sp-accordion-item.js';
+
+describe('Accordion - deprecation warnings', () => {
+  let consoleWarnStub!: SinonStub;
+
+  before(() => {
+    consoleWarnStub = stub(console, 'warn');
+  });
+
+  afterEach(() => {
+    consoleWarnStub.resetHistory();
+  });
+
+  after(() => {
+    consoleWarnStub.restore();
+  });
+
+  const deprecationCalls = (): SinonSpyCall[] =>
+    consoleWarnStub
+      .getCalls()
+      .filter(
+        (call) =>
+          (call.args[call.args.length - 1] as { data?: { level?: string } })
+            ?.data?.level === 'deprecation'
+      );
+
+  const expectDeprecationData = (
+    call: SinonSpyCall,
+    localName: 'sp-accordion' | 'sp-accordion-item'
+  ): void => {
+    expect(
+      call.args[call.args.length - 1],
+      'confirm `data` shape'
+    ).to.deep.equal({
+      data: {
+        localName,
+        type: 'api',
+        level: 'deprecation',
+      },
+    });
+  };
+
+  it('warns about deprecated "label" attribute', async () => {
+    const item = await fixture<AccordionItem>(html`
+      <sp-accordion-item label="Section"></sp-accordion-item>
+    `);
+
+    await elementUpdated(item);
+
+    expect(consoleWarnStub.called).to.be.true;
+    const labelCall = deprecationCalls().find((call) =>
+      String(call.args[0]).includes('"label"')
+    );
+    expect(labelCall, 'label deprecation warn fired').to.exist;
+    expect(
+      String(labelCall!.args[0]).includes('deprecated'),
+      'confirm deprecation message'
+    ).to.be.true;
+    expect(
+      String(labelCall!.args[0]).includes('Spectrum 2'),
+      'confirm Spectrum 2 timeline'
+    ).to.be.true;
+    expectDeprecationData(labelCall!, 'sp-accordion-item');
+  });
+
+  it('does not warn when label is empty', async () => {
+    const item = await fixture<AccordionItem>(html`
+      <sp-accordion-item></sp-accordion-item>
+    `);
+
+    await elementUpdated(item);
+
+    expect(deprecationCalls().length).to.equal(0);
+  });
+
+  it('warns when focus() is called on the accordion host', async () => {
+    const accordion = await fixture<Accordion>(html`
+      <sp-accordion>
+        <sp-accordion-item label="Section">Panel</sp-accordion-item>
+      </sp-accordion>
+    `);
+
+    await elementUpdated(accordion);
+    consoleWarnStub.resetHistory();
+    accordion.focus();
+
+    const focusCall = deprecationCalls().find((call) =>
+      String(call.args[0]).includes('focus()')
+    );
+    expect(focusCall, 'focus deprecation warn fired').to.exist;
+    expect(
+      String(focusCall!.args[0]).includes('deprecated'),
+      'confirm deprecation message'
+    ).to.be.true;
+    expect(
+      String(focusCall!.args[0]).includes('Spectrum 2'),
+      'confirm Spectrum 2 timeline'
+    ).to.be.true;
+    expectDeprecationData(focusCall!, 'sp-accordion');
+  });
+
+  it('does not warn when focus() is not called on the accordion host', async () => {
+    const accordion = await fixture<Accordion>(html`
+      <sp-accordion>
+        <sp-accordion-item>Panel</sp-accordion-item>
+      </sp-accordion>
+    `);
+
+    await elementUpdated(accordion);
+
+    const focusWarnings = deprecationCalls().filter((call) =>
+      String(call.args[0]).includes('focus()')
+    );
+    expect(focusWarnings.length).to.equal(0);
+  });
+});
diff --git a/1st-gen/packages/accordion/test/dev-mode.test.ts b/1st-gen/packages/accordion/test/dev-mode.test.ts
index ab09e698da..4091093e4e 100644
--- a/1st-gen/packages/accordion/test/dev-mode.test.ts
+++ b/1st-gen/packages/accordion/test/dev-mode.test.ts
@@ -10,13 +10,46 @@
  * governing permissions and limitations under the License.
  */
 
-import { fixture } from '@open-wc/testing';
+import { elementUpdated, expect, fixture } from '@open-wc/testing';
+import { SinonStub, stub } from 'sinon';
 
 import { Accordion } from '@spectrum-web-components/accordion';
 
-import { testForLitDevWarnings } from '../../../test/testing-helpers.js';
 import { Default } from '../stories/accordion.stories.js';
 
 describe('Accordion - dev mode', () => {
-  testForLitDevWarnings(async () => await fixture<Accordion>(Default()));
+  describe('lit dev mode', () => {
+    let consoleWarnStub!: SinonStub;
+
+    before(() => {
+      consoleWarnStub = stub(console, 'warn');
+    });
+
+    afterEach(() => {
+      consoleWarnStub.resetHistory();
+    });
+
+    after(() => {
+      consoleWarnStub.restore();
+    });
+
+    it('does not emit non-deprecation warnings', async () => {
+      const el = await fixture<Accordion>(Default());
+
+      await elementUpdated(el);
+
+      const nonDeprecationCalls = consoleWarnStub
+        .getCalls()
+        .filter(
+          (call) =>
+            (call.args[call.args.length - 1] as { data?: { level?: string } })
+              ?.data?.level !== 'deprecation'
+        );
+
+      expect(
+        nonDeprecationCalls.length > 0,
+        nonDeprecationCalls[0]?.args.join(', ')
+      ).to.be.false;
+    });
+  });
 });
diff --git a/1st-gen/tools/base/src/version.d.ts b/1st-gen/tools/base/src/version.d.ts
index 6644135be1..aec04fff48 100644
--- a/1st-gen/tools/base/src/version.d.ts
+++ b/1st-gen/tools/base/src/version.d.ts
@@ -12,8 +12,8 @@
 /**
  * The version of the 1st-gen Spectrum Web Components library.
  */
-export declare const version = "1.11.2";
+export declare const version = "1.12.0";
 /**
  * The version of the core base package.
  */
-export declare const coreVersion = "0.0.4";
+export declare const coreVersion = "0.1.0";

From b9b7d88b61091e3b920cf1de19b41d1f1e41d9e4 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 15:56:57 -0500
Subject: [PATCH 47/56] docs: jsdoc comments

---
 .../packages/core/components/accordion/Accordion.base.ts | 9 +++++++++
 .../core/components/accordion/AccordionItem.base.ts      | 5 +++++
 .../packages/swc/components/accordion/AccordionItem.ts   | 3 +++
 3 files changed, 17 insertions(+)

diff --git a/2nd-gen/packages/core/components/accordion/Accordion.base.ts b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
index 904e721ddd..883ad39f1e 100644
--- a/2nd-gen/packages/core/components/accordion/Accordion.base.ts
+++ b/2nd-gen/packages/core/components/accordion/Accordion.base.ts
@@ -29,6 +29,15 @@ import { AccordionItemBase } from './AccordionItem.base.js';
  * Base class for accordion components. Manages item propagation, heading
  * level, density, and the exclusive-open constraint.
  *
+ * @attribute {boolean} allowMultiple - Reflected as `allow-multiple`. When set,
+ *   multiple items may be open at the same time.
+ * @attribute {number} level - Heading level (2–6) applied to every item header.
+ *   Values outside that range are clamped.
+ * @attribute {AccordionSize} size - Size applied to all items.
+ * @attribute {AccordionDensity} density - Vertical spacing between items.
+ * @attribute {boolean} quiet - Renders the accordion in its quiet visual variant.
+ * @attribute {boolean} disabled - Disables all items in the accordion.
+ *
  * @slot - One or more `swc-accordion-item` elements.
  */
 export abstract class AccordionBase extends SizedMixin(SpectrumElement, {
diff --git a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
index c22793ad7b..92612b6e84 100644
--- a/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
+++ b/2nd-gen/packages/core/components/accordion/AccordionItem.base.ts
@@ -24,6 +24,11 @@ import {
  * Base class for accordion item components. Manages open/disabled state,
  * heading level (set by the parent accordion), and the toggle event.
  *
+ * @attribute {boolean} open - Whether the accordion item panel is expanded.
+ * @attribute {boolean} disabled - Whether the accordion item is disabled.
+ * @attribute {AccordionSize} size - Size of the item. Inherited from the parent
+ *   accordion when slotted; controls the chevron icon when used standalone.
+ *
  * @slot label - The heading text for this accordion item.
  * @slot actions - Optional actions rendered adjacent to the heading, outside
  *   the toggle button so they remain independently interactive.
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 5c8558398e..174047b716 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -31,6 +31,9 @@ import styles from './accordion.css';
  * @element swc-accordion-item
  * @since 2.0.0
  *
+ * @fires swc-accordion-item-toggle - Dispatched when the item open state is
+ *   toggled. Cancelable; `preventDefault()` reverts the change.
+ *
  * @example
  * <swc-accordion-item>
  *   <span slot="label">Section heading</span>

From cf3c2a5893a43c7d87100a5d2c5ca6b7530d9c57 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 20:27:38 -0500
Subject: [PATCH 48/56] chore: changeset

---
 .changeset/accordion-2nd-gen-and-deprecations.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 .changeset/accordion-2nd-gen-and-deprecations.md

diff --git a/.changeset/accordion-2nd-gen-and-deprecations.md b/.changeset/accordion-2nd-gen-and-deprecations.md
new file mode 100644
index 0000000000..0a7e503041
--- /dev/null
+++ b/.changeset/accordion-2nd-gen-and-deprecations.md
@@ -0,0 +1,15 @@
+---
+'@adobe/spectrum-wc': minor
+'@spectrum-web-components/accordion': patch
+---
+
+**feat(accordion):** Add 2nd-gen `<swc-accordion>` and `<swc-accordion-item>` with Spectrum 2-oriented behavior. Key changes from 1st-gen `<sp-accordion>` / `<sp-accordion-item>`:
+
+- Core `AccordionBase` / `AccordionItemBase` with public API: `allow-multiple`, `level`, `size`, `density`, `quiet`, host `disabled`, item `open` / `disabled`, slotted heading (`slot="label"`), optional `slot="actions"`, and cancellable `swc-accordion-item-toggle`
+- APG-aligned accessibility: `<h*>` wrapping a native header `<button>`, `aria-expanded` / `aria-controls`, `role="region"` + `aria-labelledby`, closed panels use `hidden`, disabled items use `aria-disabled` on the header and `inert` on the panel (no roving `tabindex` or arrow-key header navigation)
+- Space on the header calls `preventDefault()` and toggles without scrolling overflow containers (SWC-1487)
+- Controlled `open` is frozen while the host or item is disabled (imperative assignment cannot expand or collapse)
+- Storybook play tests for ARIA contract, toggle/cancel, exclusive open, host and item disabled, Space, and heading level propagation
+- `Chevron300Icon` for `xl` item sizing
+
+**chore(accordion):** Add Spectrum 2 deprecation warnings in dev mode on 1st-gen accordion for `label`, item `level`, and host `focus()`, with matching tests.

From c940abb72377bc41ba8a05479309593b1e866ccc Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Mon, 18 May 2026 20:28:56 -0500
Subject: [PATCH 49/56] fix: revert 1st-gen refactor work

---
 1st-gen/packages/accordion/src/Accordion.ts | 34 ++++++++++++---------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/1st-gen/packages/accordion/src/Accordion.ts b/1st-gen/packages/accordion/src/Accordion.ts
index 4b8b9ee93e..c92a4d13b1 100644
--- a/1st-gen/packages/accordion/src/Accordion.ts
+++ b/1st-gen/packages/accordion/src/Accordion.ts
@@ -114,23 +114,19 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     });
   }
 
-  private syncAssignedItem(item: AccordionItem): void {
-    if (window.__swc?.DEBUG && item.level !== this.level) {
-      window.__swc.warn(
-        item,
-        `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
-        ACCORDION_MIGRATION_DOC_URL,
-        { level: 'deprecation' }
-      );
-    }
-    item.size = this.size;
-    item.level = this.level;
-  }
-
   private handleSlotchange(): void {
     this.focusGroupController.clearElementCache();
     this.items.forEach((item) => {
-      this.syncAssignedItem(item);
+      if (window.__swc?.DEBUG && item.level !== this.level) {
+        window.__swc.warn(
+          item,
+          `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
+          ACCORDION_MIGRATION_DOC_URL,
+          { level: 'deprecation' }
+        );
+      }
+      item.size = this.size;
+      item.level = this.level;
     });
   }
 
@@ -143,7 +139,15 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     }
     if (changed.has('level')) {
       this.items.forEach((item) => {
-        this.syncAssignedItem(item);
+        if (window.__swc?.DEBUG && item.level !== this.level) {
+          window.__swc.warn(
+            item,
+            `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
+            ACCORDION_MIGRATION_DOC_URL,
+            { level: 'deprecation' }
+          );
+        }
+        item.level = this.level;
       });
     }
   }

From e63c363dc0b7a7cac2f89d586cfc4711e5f2513e Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Tue, 19 May 2026 09:46:12 -0500
Subject: [PATCH 50/56] chore(accordion): defer tests, deprecations, and
 changeset to part two

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../accordion-2nd-gen-and-deprecations.md     |  15 -
 1st-gen/packages/accordion/src/Accordion.ts   |  31 -
 .../packages/accordion/src/AccordionItem.ts   |  20 +-
 .../accordion/test/deprecation.test.ts        | 134 ----
 .../packages/accordion/test/dev-mode.test.ts  |  39 +-
 1st-gen/tools/base/src/version.d.ts           |   4 +-
 .../accordion/stories/accordion.stories.ts    |  66 --
 .../swc/components/accordion/test/.gitkeep    |   1 +
 .../accordion/test/accordion.test.ts          | 702 ------------------
 9 files changed, 7 insertions(+), 1005 deletions(-)
 delete mode 100644 .changeset/accordion-2nd-gen-and-deprecations.md
 delete mode 100644 1st-gen/packages/accordion/test/deprecation.test.ts
 create mode 100644 2nd-gen/packages/swc/components/accordion/test/.gitkeep
 delete mode 100644 2nd-gen/packages/swc/components/accordion/test/accordion.test.ts

diff --git a/.changeset/accordion-2nd-gen-and-deprecations.md b/.changeset/accordion-2nd-gen-and-deprecations.md
deleted file mode 100644
index 0a7e503041..0000000000
--- a/.changeset/accordion-2nd-gen-and-deprecations.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-'@adobe/spectrum-wc': minor
-'@spectrum-web-components/accordion': patch
----
-
-**feat(accordion):** Add 2nd-gen `<swc-accordion>` and `<swc-accordion-item>` with Spectrum 2-oriented behavior. Key changes from 1st-gen `<sp-accordion>` / `<sp-accordion-item>`:
-
-- Core `AccordionBase` / `AccordionItemBase` with public API: `allow-multiple`, `level`, `size`, `density`, `quiet`, host `disabled`, item `open` / `disabled`, slotted heading (`slot="label"`), optional `slot="actions"`, and cancellable `swc-accordion-item-toggle`
-- APG-aligned accessibility: `<h*>` wrapping a native header `<button>`, `aria-expanded` / `aria-controls`, `role="region"` + `aria-labelledby`, closed panels use `hidden`, disabled items use `aria-disabled` on the header and `inert` on the panel (no roving `tabindex` or arrow-key header navigation)
-- Space on the header calls `preventDefault()` and toggles without scrolling overflow containers (SWC-1487)
-- Controlled `open` is frozen while the host or item is disabled (imperative assignment cannot expand or collapse)
-- Storybook play tests for ARIA contract, toggle/cancel, exclusive open, host and item disabled, Space, and heading level propagation
-- `Chevron300Icon` for `xl` item sizing
-
-**chore(accordion):** Add Spectrum 2 deprecation warnings in dev mode on 1st-gen accordion for `label`, item `level`, and host `focus()`, with matching tests.
diff --git a/1st-gen/packages/accordion/src/Accordion.ts b/1st-gen/packages/accordion/src/Accordion.ts
index c92a4d13b1..6ec2dae9ad 100644
--- a/1st-gen/packages/accordion/src/Accordion.ts
+++ b/1st-gen/packages/accordion/src/Accordion.ts
@@ -27,9 +27,6 @@ import { FocusGroupController } from '@spectrum-web-components/reactive-controll
 import styles from './accordion.css.js';
 import { AccordionItem } from './AccordionItem.js';
 
-const ACCORDION_MIGRATION_DOC_URL =
-  'https://opensource.adobe.com/spectrum-web-components/components/accordion/';
-
 /**
  * @element sp-accordion
  * @slot - The sp-accordion-item children to display.
@@ -75,19 +72,7 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     isFocusableElement: (el: AccordionItem) => !el.disabled,
   });
 
-  /**
-   * @deprecated `focus()` on `<sp-accordion>` is deprecated and will be removed
-   * in Spectrum 2. Focus the header button inside `<sp-accordion-item>` instead.
-   */
   public override focus(): void {
-    if (window.__swc?.DEBUG) {
-      window.__swc.warn(
-        this,
-        `<${this.localName}> focus() is deprecated and will be removed in Spectrum 2. Focus the header button inside <sp-accordion-item> instead.`,
-        ACCORDION_MIGRATION_DOC_URL,
-        { level: 'deprecation' }
-      );
-    }
     this.focusGroupController.focus();
   }
 
@@ -117,14 +102,6 @@ export class Accordion extends SizedMixin(SpectrumElement, {
   private handleSlotchange(): void {
     this.focusGroupController.clearElementCache();
     this.items.forEach((item) => {
-      if (window.__swc?.DEBUG && item.level !== this.level) {
-        window.__swc.warn(
-          item,
-          `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
-          ACCORDION_MIGRATION_DOC_URL,
-          { level: 'deprecation' }
-        );
-      }
       item.size = this.size;
       item.level = this.level;
     });
@@ -139,14 +116,6 @@ export class Accordion extends SizedMixin(SpectrumElement, {
     }
     if (changed.has('level')) {
       this.items.forEach((item) => {
-        if (window.__swc?.DEBUG && item.level !== this.level) {
-          window.__swc.warn(
-            item,
-            `<${item.localName}> the "level" attribute is deprecated on accordion items and will be removed in Spectrum 2. Use "level" on <${this.localName}> instead.`,
-            ACCORDION_MIGRATION_DOC_URL,
-            { level: 'deprecation' }
-          );
-        }
         item.level = this.level;
       });
     }
diff --git a/1st-gen/packages/accordion/src/AccordionItem.ts b/1st-gen/packages/accordion/src/AccordionItem.ts
index 3857ce908d..80dd83bbe2 100644
--- a/1st-gen/packages/accordion/src/AccordionItem.ts
+++ b/1st-gen/packages/accordion/src/AccordionItem.ts
@@ -61,13 +61,10 @@ const chevronIcon: Record<string, () => TemplateResult> = {
   `,
 };
 
-const ACCORDION_MIGRATION_DOC_URL =
-  'https://opensource.adobe.com/spectrum-web-components/components/accordion/';
-
 /**
  * @element sp-accordion-item
  * @slot - The content of the item that is hidden when the item is not open
- * @fires sp-accordion-item-toggle - Announce that an accordion item has been toggled while allowing the event to be cancelled. In Spectrum 2, this event is renamed to `swc-accordion-item-toggle`.
+ * @fires sp-accordion-item-toggle - Announce that an accordion item has been toggled while allowing the event to be cancelled.
  */
 export class AccordionItem extends SizedMixin(Focusable, {
   noDefaultSize: true,
@@ -79,10 +76,6 @@ export class AccordionItem extends SizedMixin(Focusable, {
   @property({ type: Boolean, reflect: true })
   public open = false;
 
-  /**
-   * @deprecated The `label` attribute is deprecated and will be removed in
-   * Spectrum 2.
-   */
   @property({ type: String, reflect: true })
   public label = '';
 
@@ -93,9 +86,6 @@ export class AccordionItem extends SizedMixin(Focusable, {
    * The heading level (2-6) to use for the accordion item title.
    * This property is set by the parent sp-accordion element.
    * Defaults to 3.
-   *
-   * @deprecated The `level` attribute on accordion items is deprecated and will
-   * be removed in Spectrum 2. Use `level` on `<sp-accordion>` instead.
    */
   @property({ type: Number, reflect: true })
   public level: number = 3;
@@ -192,13 +182,5 @@ export class AccordionItem extends SizedMixin(Focusable, {
         this.removeAttribute('aria-disabled');
       }
     }
-    if (window.__swc?.DEBUG && changes.has('label') && this.label) {
-      window.__swc.warn(
-        this,
-        `<${this.localName}> the "label" attribute is deprecated and will be removed in Spectrum 2.`,
-        ACCORDION_MIGRATION_DOC_URL,
-        { level: 'deprecation' }
-      );
-    }
   }
 }
diff --git a/1st-gen/packages/accordion/test/deprecation.test.ts b/1st-gen/packages/accordion/test/deprecation.test.ts
deleted file mode 100644
index dab3a9e5d4..0000000000
--- a/1st-gen/packages/accordion/test/deprecation.test.ts
+++ /dev/null
@@ -1,134 +0,0 @@
-/**
- * Copyright 2026 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-
-import { elementUpdated, expect, fixture, html } from '@open-wc/testing';
-import { SinonSpyCall, SinonStub, stub } from 'sinon';
-
-import { Accordion, AccordionItem } from '@spectrum-web-components/accordion';
-
-import '@spectrum-web-components/accordion/sp-accordion.js';
-import '@spectrum-web-components/accordion/sp-accordion-item.js';
-
-describe('Accordion - deprecation warnings', () => {
-  let consoleWarnStub!: SinonStub;
-
-  before(() => {
-    consoleWarnStub = stub(console, 'warn');
-  });
-
-  afterEach(() => {
-    consoleWarnStub.resetHistory();
-  });
-
-  after(() => {
-    consoleWarnStub.restore();
-  });
-
-  const deprecationCalls = (): SinonSpyCall[] =>
-    consoleWarnStub
-      .getCalls()
-      .filter(
-        (call) =>
-          (call.args[call.args.length - 1] as { data?: { level?: string } })
-            ?.data?.level === 'deprecation'
-      );
-
-  const expectDeprecationData = (
-    call: SinonSpyCall,
-    localName: 'sp-accordion' | 'sp-accordion-item'
-  ): void => {
-    expect(
-      call.args[call.args.length - 1],
-      'confirm `data` shape'
-    ).to.deep.equal({
-      data: {
-        localName,
-        type: 'api',
-        level: 'deprecation',
-      },
-    });
-  };
-
-  it('warns about deprecated "label" attribute', async () => {
-    const item = await fixture<AccordionItem>(html`
-      <sp-accordion-item label="Section"></sp-accordion-item>
-    `);
-
-    await elementUpdated(item);
-
-    expect(consoleWarnStub.called).to.be.true;
-    const labelCall = deprecationCalls().find((call) =>
-      String(call.args[0]).includes('"label"')
-    );
-    expect(labelCall, 'label deprecation warn fired').to.exist;
-    expect(
-      String(labelCall!.args[0]).includes('deprecated'),
-      'confirm deprecation message'
-    ).to.be.true;
-    expect(
-      String(labelCall!.args[0]).includes('Spectrum 2'),
-      'confirm Spectrum 2 timeline'
-    ).to.be.true;
-    expectDeprecationData(labelCall!, 'sp-accordion-item');
-  });
-
-  it('does not warn when label is empty', async () => {
-    const item = await fixture<AccordionItem>(html`
-      <sp-accordion-item></sp-accordion-item>
-    `);
-
-    await elementUpdated(item);
-
-    expect(deprecationCalls().length).to.equal(0);
-  });
-
-  it('warns when focus() is called on the accordion host', async () => {
-    const accordion = await fixture<Accordion>(html`
-      <sp-accordion>
-        <sp-accordion-item label="Section">Panel</sp-accordion-item>
-      </sp-accordion>
-    `);
-
-    await elementUpdated(accordion);
-    consoleWarnStub.resetHistory();
-    accordion.focus();
-
-    const focusCall = deprecationCalls().find((call) =>
-      String(call.args[0]).includes('focus()')
-    );
-    expect(focusCall, 'focus deprecation warn fired').to.exist;
-    expect(
-      String(focusCall!.args[0]).includes('deprecated'),
-      'confirm deprecation message'
-    ).to.be.true;
-    expect(
-      String(focusCall!.args[0]).includes('Spectrum 2'),
-      'confirm Spectrum 2 timeline'
-    ).to.be.true;
-    expectDeprecationData(focusCall!, 'sp-accordion');
-  });
-
-  it('does not warn when focus() is not called on the accordion host', async () => {
-    const accordion = await fixture<Accordion>(html`
-      <sp-accordion>
-        <sp-accordion-item>Panel</sp-accordion-item>
-      </sp-accordion>
-    `);
-
-    await elementUpdated(accordion);
-
-    const focusWarnings = deprecationCalls().filter((call) =>
-      String(call.args[0]).includes('focus()')
-    );
-    expect(focusWarnings.length).to.equal(0);
-  });
-});
diff --git a/1st-gen/packages/accordion/test/dev-mode.test.ts b/1st-gen/packages/accordion/test/dev-mode.test.ts
index 4091093e4e..ab09e698da 100644
--- a/1st-gen/packages/accordion/test/dev-mode.test.ts
+++ b/1st-gen/packages/accordion/test/dev-mode.test.ts
@@ -10,46 +10,13 @@
  * governing permissions and limitations under the License.
  */
 
-import { elementUpdated, expect, fixture } from '@open-wc/testing';
-import { SinonStub, stub } from 'sinon';
+import { fixture } from '@open-wc/testing';
 
 import { Accordion } from '@spectrum-web-components/accordion';
 
+import { testForLitDevWarnings } from '../../../test/testing-helpers.js';
 import { Default } from '../stories/accordion.stories.js';
 
 describe('Accordion - dev mode', () => {
-  describe('lit dev mode', () => {
-    let consoleWarnStub!: SinonStub;
-
-    before(() => {
-      consoleWarnStub = stub(console, 'warn');
-    });
-
-    afterEach(() => {
-      consoleWarnStub.resetHistory();
-    });
-
-    after(() => {
-      consoleWarnStub.restore();
-    });
-
-    it('does not emit non-deprecation warnings', async () => {
-      const el = await fixture<Accordion>(Default());
-
-      await elementUpdated(el);
-
-      const nonDeprecationCalls = consoleWarnStub
-        .getCalls()
-        .filter(
-          (call) =>
-            (call.args[call.args.length - 1] as { data?: { level?: string } })
-              ?.data?.level !== 'deprecation'
-        );
-
-      expect(
-        nonDeprecationCalls.length > 0,
-        nonDeprecationCalls[0]?.args.join(', ')
-      ).to.be.false;
-    });
-  });
+  testForLitDevWarnings(async () => await fixture<Accordion>(Default()));
 });
diff --git a/1st-gen/tools/base/src/version.d.ts b/1st-gen/tools/base/src/version.d.ts
index aec04fff48..6644135be1 100644
--- a/1st-gen/tools/base/src/version.d.ts
+++ b/1st-gen/tools/base/src/version.d.ts
@@ -12,8 +12,8 @@
 /**
  * The version of the 1st-gen Spectrum Web Components library.
  */
-export declare const version = "1.12.0";
+export declare const version = "1.11.2";
 /**
  * The version of the core base package.
  */
-export declare const coreVersion = "0.1.0";
+export declare const coreVersion = "0.0.4";
diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index b8f71a4dd7..4284e11925 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -125,69 +125,3 @@ export const Overview: Story = {
   },
   tags: ['overview'],
 };
-
-// ────────────────────────────────
-//    ACCESSIBILITY STORIES
-// ────────────────────────────────
-
-/**
- * ### Features
- *
- * The `<swc-accordion>` and `<swc-accordion-item>` elements implement the
- * [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/):
- *
- * #### Keyboard navigation
- *
- * - <kbd>Tab</kbd>: Moves focus into and between item header buttons
- * - <kbd>Enter</kbd>: Activates the focused header button (browser-native click behavior)
- * - <kbd>Space</kbd>: Toggles the focused item and prevents page scroll
- *
- * #### ARIA implementation
- *
- * 1. **Heading wrapper**: Each header button is wrapped in an `h2`–`h6` element matching
- *    the accordion's `level` attribute
- * 2. **`aria-expanded`**: Set to `"true"` on open items, `"false"` on closed items
- * 3. **`aria-controls`**: Points from the header button to the panel (`id="content"`)
- * 4. **Panel role**: The panel has `role="region"` and `aria-labelledby` pointing to the
- *    header button, making it a labeled landmark
- * 5. **`aria-disabled`**: Set on the header button (not the native `disabled` attribute)
- *    so disabled items remain keyboard-reachable
- * 6. **`hidden`**: Added to closed panels to remove them from the accessibility tree
- * 7. **`inert`**: Added to disabled-item panels to block interaction with their contents
- *
- * ### Best practices
- *
- * - Set a `level` that continues the existing page heading hierarchy without skipping levels
- * - Provide meaningful, unique label text for each item so screen reader users can
- *   navigate the heading list
- * - When using the `actions` slot, include the item subject in the action's accessible
- *   name (e.g., "Edit Alchemy" rather than "Edit") so it is unambiguous out of context
- * - Always set `density` explicitly; use `regular` when unsure
- */
-export const Accessibility: Story = {
-  render: () => html`
-    <swc-accordion level="3" density="regular">
-      <swc-accordion-item open>
-        <span slot="label">Alchemy</span>
-        <button slot="actions" aria-label="Edit Alchemy">Edit</button>
-        Alchemy is an ancient branch of natural philosophy, a philosophical and
-        protoscientific tradition that was historically practiced in China,
-        India, the Muslim world, and Europe.
-      </swc-accordion-item>
-      <swc-accordion-item>
-        <span slot="label">Astrology</span>
-        <button slot="actions" aria-label="Edit Astrology">Edit</button>
-        Astrology is a range of divinatory practices, recognized as
-        pseudoscientific since the 18th century, that propose that information
-        about human affairs and terrestrial events may be discerned by studying
-        the apparent positions of celestial objects.
-      </swc-accordion-item>
-      <swc-accordion-item disabled>
-        <span slot="label">Natural magic (disabled)</span>
-        Natural magic in the context of early modern Europe was a branch of
-        philosophy that treated occult forces as resulting from natural causes.
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  tags: ['a11y'],
-};
diff --git a/2nd-gen/packages/swc/components/accordion/test/.gitkeep b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/2nd-gen/packages/swc/components/accordion/test/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts b/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
deleted file mode 100644
index ab40b3dca8..0000000000
--- a/2nd-gen/packages/swc/components/accordion/test/accordion.test.ts
+++ /dev/null
@@ -1,702 +0,0 @@
-/**
- * Copyright 2026 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-
-import { html } from 'lit';
-import { expect } from '@storybook/test';
-import type { Meta, StoryObj as Story } from '@storybook/web-components';
-
-import { Accordion, AccordionItem } from '@adobe/spectrum-wc/accordion';
-
-import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
-import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
-
-import { SWC_ACCORDION_ITEM_TOGGLE_EVENT } from '../../../../core/components/accordion/Accordion.types.js';
-import { getComponent, getComponents } from '../../../utils/test-utils.js';
-import meta, { Overview } from '../stories/accordion.stories.js';
-
-export default {
-  ...meta,
-  title: 'Accordion/Tests',
-  parameters: {
-    ...meta.parameters,
-    docs: { disable: true, page: null },
-  },
-  tags: ['!autodocs', 'dev'],
-} as Meta;
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Defaults
-// ──────────────────────────────────────────────────────────────
-
-export const OverviewTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const items = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-
-    await step('renders three items', async () => {
-      expect(items.length, 'three accordion items are rendered').toBe(3);
-    });
-
-    await step('third item is open by default', async () => {
-      expect(items[2]?.open, 'third item open property is true').toBe(true);
-    });
-
-    await step('first two items are closed by default', async () => {
-      expect(items[0]?.open, 'first item open property is false').toBe(false);
-      expect(items[1]?.open, 'second item open property is false').toBe(false);
-    });
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: ARIA contract
-// ──────────────────────────────────────────────────────────────
-
-export const AriaContractTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const items = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const closedItem = items[0] as AccordionItem;
-    const openItem = items[2] as AccordionItem;
-
-    const closedButton = closedItem.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const closedPanel = closedItem.shadowRoot?.getElementById(
-      'content'
-    ) as HTMLElement;
-    const openButton = openItem.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const openPanel = openItem.shadowRoot?.getElementById(
-      'content'
-    ) as HTMLElement;
-
-    await step('aria-expanded reflects open state', async () => {
-      expect(
-        closedButton.getAttribute('aria-expanded'),
-        'closed item button has aria-expanded="false"'
-      ).toBe('false');
-      expect(
-        openButton.getAttribute('aria-expanded'),
-        'open item button has aria-expanded="true"'
-      ).toBe('true');
-    });
-
-    await step('aria-controls value matches the panel id', async () => {
-      expect(
-        closedButton.getAttribute('aria-controls'),
-        'aria-controls is "content"'
-      ).toBe('content');
-      expect(closedPanel.id, 'panel id is "content"').toBe('content');
-    });
-
-    await step(
-      'panel has role="region" and aria-labelledby="header"',
-      async () => {
-        expect(closedPanel.getAttribute('role'), 'panel role is "region"').toBe(
-          'region'
-        );
-        expect(
-          closedPanel.getAttribute('aria-labelledby'),
-          'panel aria-labelledby is "header"'
-        ).toBe('header');
-      }
-    );
-
-    await step(
-      'closed panel has hidden attribute; open panel does not',
-      async () => {
-        expect(
-          closedPanel.hasAttribute('hidden'),
-          'closed panel has hidden attribute'
-        ).toBe(true);
-        expect(
-          openPanel.hasAttribute('hidden'),
-          'open panel does not have hidden attribute'
-        ).toBe(false);
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Open / close
-// ──────────────────────────────────────────────────────────────
-
-export const ToggleTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const items = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const item = items[0] as AccordionItem;
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step('clicking the header button opens a closed item', async () => {
-      expect(item.open, 'item starts closed').toBe(false);
-
-      button.click();
-      await new Promise<void>((resolve) => queueMicrotask(resolve));
-      await item.updateComplete;
-
-      expect(item.open, 'item is now open').toBe(true);
-      expect(
-        button.getAttribute('aria-expanded'),
-        'aria-expanded is "true" after open'
-      ).toBe('true');
-      expect(
-        panel.hasAttribute('hidden'),
-        'hidden attribute is removed when panel is open'
-      ).toBe(false);
-    });
-
-    await step('clicking the header button again closes the item', async () => {
-      button.click();
-      await new Promise<void>((resolve) => queueMicrotask(resolve));
-      await item.updateComplete;
-
-      expect(item.open, 'item is closed again').toBe(false);
-      expect(
-        button.getAttribute('aria-expanded'),
-        'aria-expanded is "false" after close'
-      ).toBe('false');
-      expect(
-        panel.hasAttribute('hidden'),
-        'hidden attribute is restored when panel is closed'
-      ).toBe(true);
-    });
-  },
-};
-
-export const ToggleEventTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const item = (
-      await getComponents<AccordionItem>(canvasElement, 'swc-accordion-item')
-    )[0] as AccordionItem;
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-
-    await step(
-      'clicking the header button dispatches the toggle event',
-      async () => {
-        let toggleFired = false;
-        item.addEventListener(
-          SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-          () => {
-            toggleFired = true;
-          },
-          { once: true }
-        );
-
-        button.click();
-        await item.updateComplete;
-
-        expect(toggleFired, 'toggle event was dispatched').toBe(true);
-      }
-    );
-
-    await step(
-      'toggle event is cancelable; canceling reverts open state',
-      async () => {
-        const wasOpen = item.open;
-        item.addEventListener(
-          SWC_ACCORDION_ITEM_TOGGLE_EVENT,
-          (event) => {
-            event.preventDefault();
-          },
-          { once: true }
-        );
-
-        button.click();
-        await item.updateComplete;
-
-        expect(item.open, 'open state is reverted when event is canceled').toBe(
-          wasOpen
-        );
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Disabled item
-// ──────────────────────────────────────────────────────────────
-
-export const DisabledItemTest: Story = {
-  render: () => html`
-    <swc-accordion density="regular">
-      <swc-accordion-item disabled>
-        <span slot="label">Disabled item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step('disabled item button has aria-disabled="true"', async () => {
-      expect(
-        button.getAttribute('aria-disabled'),
-        'aria-disabled is "true"'
-      ).toBe('true');
-    });
-
-    await step(
-      'disabled item button does not have native disabled attribute',
-      async () => {
-        expect(
-          button.hasAttribute('disabled'),
-          'native disabled attribute is absent'
-        ).toBe(false);
-      }
-    );
-
-    await step('disabled item button remains in the tab order', async () => {
-      expect(button.tabIndex, 'tabIndex is not -1').not.toBe(-1);
-    });
-
-    await step('disabled item panel is inert', async () => {
-      expect(panel.inert, 'panel inert property is true').toBe(true);
-    });
-
-    await step('clicking a disabled item does not open it', async () => {
-      button.click();
-      await item.updateComplete;
-
-      expect(item.open, 'item remains closed after click').toBe(false);
-    });
-
-    await step(
-      'setting open on a closed disabled item does not expand it',
-      async () => {
-        item.open = true;
-        await item.updateComplete;
-
-        expect(item.open, 'open property stays false').toBe(false);
-        expect(
-          panel.hasAttribute('hidden'),
-          'panel stays hidden after imperative open'
-        ).toBe(true);
-      }
-    );
-  },
-};
-
-export const DisabledOpenItemTest: Story = {
-  render: () => html`
-    <swc-accordion density="regular">
-      <swc-accordion-item disabled open>
-        <span slot="label">Disabled open item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step('disabled open item starts expanded', async () => {
-      expect(item.open, 'item starts open').toBe(true);
-    });
-
-    await step(
-      'setting open to false on a disabled item does not collapse it',
-      async () => {
-        item.open = false;
-        await item.updateComplete;
-
-        expect(item.open, 'open property stays true').toBe(true);
-        expect(
-          panel.hasAttribute('hidden'),
-          'panel stays visible after imperative close'
-        ).toBe(false);
-        expect(
-          button.getAttribute('aria-expanded'),
-          'aria-expanded stays true'
-        ).toBe('true');
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Host disabled
-// ──────────────────────────────────────────────────────────────
-
-export const HostDisabledTest: Story = {
-  render: () => html`
-    <swc-accordion disabled density="regular">
-      <swc-accordion-item>
-        <span slot="label">Item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const accordion = await getComponent<Accordion>(
-      canvasElement,
-      'swc-accordion'
-    );
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step(
-      'item button has aria-disabled when the host accordion is disabled',
-      async () => {
-        expect(
-          button.getAttribute('aria-disabled'),
-          'aria-disabled is "true" via host disabled'
-        ).toBe('true');
-      }
-    );
-
-    await step(
-      'item button does not have native disabled when host is disabled',
-      async () => {
-        expect(
-          button.hasAttribute('disabled'),
-          'native disabled attribute is absent'
-        ).toBe(false);
-      }
-    );
-
-    await step('item panel is inert when host is disabled', async () => {
-      expect(panel.inert, 'panel inert is true').toBe(true);
-    });
-
-    await step(
-      'clicking an item does not open it when the host is disabled',
-      async () => {
-        button.click();
-        await item.updateComplete;
-
-        expect(
-          item.open,
-          'item remains closed after click on host-disabled accordion'
-        ).toBe(false);
-      }
-    );
-
-    await step(
-      'setting open on a closed item does not expand it when the host is disabled',
-      async () => {
-        item.open = true;
-        await item.updateComplete;
-
-        expect(item.open, 'open property stays false').toBe(false);
-        expect(
-          panel.hasAttribute('hidden'),
-          'panel stays hidden after imperative open'
-        ).toBe(true);
-        expect(
-          button.getAttribute('aria-expanded'),
-          'aria-expanded stays false'
-        ).toBe('false');
-      }
-    );
-
-    await step('clearing host disabled allows the item to open', async () => {
-      accordion.disabled = false;
-      await accordion.updateComplete;
-      await item.updateComplete;
-
-      expect(
-        button.getAttribute('aria-disabled'),
-        'aria-disabled is removed after host re-enabled'
-      ).toBeNull();
-      expect(panel.inert, 'panel is no longer inert').toBe(false);
-
-      button.click();
-      await item.updateComplete;
-
-      expect(item.open, 'item opens after host is re-enabled').toBe(true);
-    });
-  },
-};
-
-export const HostDisabledOpenItemTest: Story = {
-  render: () => html`
-    <swc-accordion disabled density="regular">
-      <swc-accordion-item open>
-        <span slot="label">Item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-    const panel = item.shadowRoot?.getElementById('content') as HTMLElement;
-
-    await step('open item stays expanded while host is disabled', async () => {
-      expect(item.open, 'item starts open').toBe(true);
-    });
-
-    await step(
-      'setting open to false does not collapse the item when the host is disabled',
-      async () => {
-        item.open = false;
-        await item.updateComplete;
-
-        expect(item.open, 'open property stays true').toBe(true);
-        expect(
-          panel.hasAttribute('hidden'),
-          'panel stays visible after imperative close'
-        ).toBe(false);
-        expect(
-          button.getAttribute('aria-expanded'),
-          'aria-expanded stays true'
-        ).toBe('true');
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Keyboard
-// ──────────────────────────────────────────────────────────────
-
-export const SpaceKeyTest: Story = {
-  render: () => html`
-    <swc-accordion density="regular">
-      <swc-accordion-item>
-        <span slot="label">Item</span>
-        Panel content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button = item.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-
-    await step(
-      'Space on the header button calls preventDefault and opens the item',
-      async () => {
-        const event = new KeyboardEvent('keydown', {
-          key: ' ',
-          bubbles: true,
-          cancelable: true,
-        });
-        button.dispatchEvent(event);
-        await item.updateComplete;
-
-        expect(
-          event.defaultPrevented,
-          'Space keydown default is prevented'
-        ).toBe(true);
-        expect(item.open, 'item is open after Space').toBe(true);
-      }
-    );
-
-    await step(
-      'Space on a disabled header button prevents default but does not toggle',
-      async () => {
-        item.disabled = true;
-        await item.updateComplete;
-
-        const event = new KeyboardEvent('keydown', {
-          key: ' ',
-          bubbles: true,
-          cancelable: true,
-        });
-        button.dispatchEvent(event);
-        await item.updateComplete;
-
-        expect(
-          event.defaultPrevented,
-          'Space keydown default is still prevented on disabled item'
-        ).toBe(true);
-        expect(
-          item.open,
-          'open state does not change when item is disabled'
-        ).toBe(true);
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Exclusive open (allow-multiple: false)
-// ──────────────────────────────────────────────────────────────
-
-export const ExclusiveOpenTest: Story = {
-  ...Overview,
-  play: async ({ canvasElement, step }) => {
-    const items = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const item1 = items[0] as AccordionItem;
-    const item3 = items[2] as AccordionItem;
-    const button1 = item1.shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-
-    await step('opening one item closes the previously open item', async () => {
-      expect(item3.open, 'third item starts open').toBe(true);
-
-      button1.click();
-      // closeSiblingsOnOpen defers via queueMicrotask; wait for it to run.
-      await new Promise<void>((resolve) => queueMicrotask(resolve));
-      await item1.updateComplete;
-      await item3.updateComplete;
-
-      expect(item1.open, 'first item is now open').toBe(true);
-      expect(item3.open, 'third item is now closed').toBe(false);
-    });
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Allow-multiple
-// ──────────────────────────────────────────────────────────────
-
-export const AllowMultipleTest: Story = {
-  render: () => html`
-    <swc-accordion allow-multiple density="regular">
-      <swc-accordion-item>
-        <span slot="label">Alchemy</span>
-        Alchemy content
-      </swc-accordion-item>
-      <swc-accordion-item open>
-        <span slot="label">Astrology</span>
-        Astrology content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const [item1, item2] = await getComponents<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    const button1 = (item1 as AccordionItem).shadowRoot?.getElementById(
-      'header'
-    ) as HTMLButtonElement;
-
-    await step(
-      'opening one item does not close others when allow-multiple is set',
-      async () => {
-        expect((item2 as AccordionItem).open, 'second item starts open').toBe(
-          true
-        );
-
-        button1.click();
-        await new Promise<void>((resolve) => queueMicrotask(resolve));
-        await (item1 as AccordionItem).updateComplete;
-        await (item2 as AccordionItem).updateComplete;
-
-        expect((item1 as AccordionItem).open, 'first item is now open').toBe(
-          true
-        );
-        expect((item2 as AccordionItem).open, 'second item is still open').toBe(
-          true
-        );
-      }
-    );
-  },
-};
-
-// ──────────────────────────────────────────────────────────────
-// TEST: Heading level
-// ──────────────────────────────────────────────────────────────
-
-export const HeadingLevelTest: Story = {
-  render: () => html`
-    <swc-accordion level="4" density="regular">
-      <swc-accordion-item>
-        <span slot="label">Item</span>
-        Content
-      </swc-accordion-item>
-    </swc-accordion>
-  `,
-  play: async ({ canvasElement, step }) => {
-    const accordion = await getComponent<Accordion>(
-      canvasElement,
-      'swc-accordion'
-    );
-    const item = await getComponent<AccordionItem>(
-      canvasElement,
-      'swc-accordion-item'
-    );
-    await item.updateComplete;
-
-    await step(
-      'item renders the heading tag matching the accordion level',
-      async () => {
-        expect(
-          item.shadowRoot?.querySelector('h4'),
-          'h4 element is in the item shadow DOM'
-        ).toBeTruthy();
-      }
-    );
-
-    await step(
-      'heading tag updates when the accordion level changes',
-      async () => {
-        accordion.level = 2;
-        await accordion.updateComplete;
-        await item.updateComplete;
-
-        expect(
-          item.shadowRoot?.querySelector('h4'),
-          'h4 is no longer present after level change'
-        ).toBeNull();
-        expect(
-          item.shadowRoot?.querySelector('h2'),
-          'h2 element is in the item shadow DOM'
-        ).toBeTruthy();
-      }
-    );
-  },
-};

From a7c9f25a09dd32e52d646b681fa7654d685c4aa2 Mon Sep 17 00:00:00 2001
From: Miwha Bonini <mbonini@adobe.com>
Date: Wed, 20 May 2026 09:42:42 -0600
Subject: [PATCH 51/56] fix(accordion): update css font

---
 .../swc/components/accordion/accordion-item.css   | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/2nd-gen/packages/swc/components/accordion/accordion-item.css b/2nd-gen/packages/swc/components/accordion/accordion-item.css
index 0928199755..31e021b1a2 100644
--- a/2nd-gen/packages/swc/components/accordion/accordion-item.css
+++ b/2nd-gen/packages/swc/components/accordion/accordion-item.css
@@ -57,7 +57,6 @@ slot:not([name]) {
   inline-size: 100%;
   padding-block: var(--_swc-accordion-pad-top-m, token("accordion-top-to-text-medium")) var(--_swc-accordion-pad-bottom-m, token("accordion-bottom-to-text-medium"));
   padding-inline: token("accordion-edge-to-content-area-medium") token("accordion-edge-to-text");
-  font-family: token("sans-serif-font");
   font-size: token("font-size-200");
   font-weight: token("bold-font-weight");
   line-height: token("line-height-100");
@@ -161,6 +160,19 @@ slot:not([name]) {
   flex: 1;
 }
 
+/*
+ * Override light-DOM heading styles (browser defaults, host-document resets)
+ * that would otherwise win over the inherited header font. Applies to
+ * phrasing content like <strong> or <code> slotted into the label.
+ * The :not([class]) guard leaves intentionally-classed elements untouched.
+ * !important is required to win over any light-DOM styles targeting the
+ * slotted element (e.g. global h* resets from the host document).
+ */
+::slotted([slot="label"]:not([class])) {
+  margin: 0 !important;
+  font: inherit !important;
+}
+
 /* ── Direct actions (inline with heading, outside the toggle area) ───── */
 
 .spectrum-Accordion-itemDirectActions {
@@ -177,7 +189,6 @@ slot:not([name]) {
   flex: 0 0 100%;
   padding-block: token("accordion-content-area-top-to-content") token("accordion-content-area-bottom-to-content");
   padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-medium"));
-  font-family: token("sans-serif-font");
   font-size: token("font-size-100");
   font-weight: token("regular-font-weight");
   line-height: token("line-height-100");

From e8dc485084916570272ad63f09f55abbf3a50e75 Mon Sep 17 00:00:00 2001
From: Rise Erpelding <rise@heysparkbox.com>
Date: Wed, 20 May 2026 15:59:51 -0500
Subject: [PATCH 52/56] fix: class selectors

---
 .../swc/components/accordion/Accordion.ts     |  4 +-
 .../swc/components/accordion/AccordionItem.ts | 51 ++++++++++---------
 2 files changed, 30 insertions(+), 25 deletions(-)

diff --git a/2nd-gen/packages/swc/components/accordion/Accordion.ts b/2nd-gen/packages/swc/components/accordion/Accordion.ts
index 02463a4b89..92d112150e 100644
--- a/2nd-gen/packages/swc/components/accordion/Accordion.ts
+++ b/2nd-gen/packages/swc/components/accordion/Accordion.ts
@@ -37,7 +37,9 @@ export class Accordion extends AccordionBase {
 
   protected override render(): TemplateResult {
     return html`
-      <slot @slotchange=${this.syncAccordionItems}></slot>
+      <div class="swc-Accordion">
+        <slot @slotchange=${this.syncAccordionItems}></slot>
+      </div>
     `;
   }
 }
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index 174047b716..358a50f192 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -104,13 +104,14 @@ export class AccordionItem extends AccordionItemBase {
 
   private renderHeadingWrapper(content: TemplateResult): TemplateResult {
     const tag = unsafeStatic(`h${this.headingLevel}`);
-    return staticHtml`<${tag}>${content}</${tag}>`;
+    return staticHtml`<${tag} class="swc-AccordionItem-heading">${content}</${tag}>`;
   }
 
   protected override render(): TemplateResult {
     const button = html`
       <button
         id="header"
+        class="swc-AccordionItem-header"
         type="button"
         aria-expanded=${this.open ? 'true' : 'false'}
         aria-controls="content"
@@ -120,36 +121,38 @@ export class AccordionItem extends AccordionItemBase {
         @click=${this.toggle}
         @keydown=${this.handleHeaderKeydown}
       >
-        <swc-icon class="spectrum-Accordion-itemIndicator" aria-hidden="true">
+        <swc-icon class="swc-AccordionItem-indicator" aria-hidden="true">
           ${this.chevronForSize()}
         </swc-icon>
-        <span class="spectrum-Accordion-itemTitle">
+        <span class="swc-AccordionItem-label">
           <slot name="label"></slot>
         </span>
       </button>
     `;
     return html`
-      ${this.renderHeadingWrapper(button)}
-      <div
-        class="spectrum-Accordion-itemDirectActions"
-        hidden
-        @click=${this.stopActionsContainerPropagation}
-        @keydown=${this.stopActionsContainerPropagation}
-      >
-        <slot
-          name="actions"
-          @slotchange=${this.syncActionsContainerVisibility}
-        ></slot>
-      </div>
-      <div
-        id="content"
-        class="spectrum-Accordion-itemContent"
-        role="region"
-        aria-labelledby="header"
-        ?hidden=${!this.open}
-        .inert=${this.disabled || this.parentDisabled}
-      >
-        <slot></slot>
+      <div class="swc-AccordionItem">
+        ${this.renderHeadingWrapper(button)}
+        <div
+          class="swc-AccordionItem-actions"
+          hidden
+          @click=${this.stopActionsContainerPropagation}
+          @keydown=${this.stopActionsContainerPropagation}
+        >
+          <slot
+            name="actions"
+            @slotchange=${this.syncActionsContainerVisibility}
+          ></slot>
+        </div>
+        <div
+          id="content"
+          class="swc-AccordionItem-content"
+          role="region"
+          aria-labelledby="header"
+          ?hidden=${!this.open}
+          .inert=${this.disabled || this.parentDisabled}
+        >
+          <slot></slot>
+        </div>
       </div>
     `;
   }

From 1fc9f472ee98261778f493251b5135f2501901ea Mon Sep 17 00:00:00 2001
From: Miwha Bonini <mbonini@adobe.com>
Date: Thu, 21 May 2026 15:08:16 -0600
Subject: [PATCH 53/56] fix(accordion): address PR review feedback on CSS and
 stories

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .ai/rules/code-conformance.md                 |   1 +
 .ai/skills/migration-styling/SKILL.md         |   2 +
 .../tldr-component-css-guidelines.md          |  17 +-
 .../swc/components/accordion/AccordionItem.ts |  24 +--
 .../components/accordion/accordion-item.css   | 147 +++++++----------
 .../swc/components/accordion/accordion.css    |  72 +++++---
 .../accordion/stories/accordion.stories.ts    | 154 +++++++++---------
 .../02_style-guide/01_css/01_component-css.md |  18 +-
 .../02_style-guide/01_css/05_anti-patterns.md |  28 ++++
 .../03_components/accordion/migration-plan.md |  52 +++++-
 10 files changed, 301 insertions(+), 214 deletions(-)

diff --git a/.ai/rules/code-conformance.md b/.ai/rules/code-conformance.md
index 555d57e117..0f2e58f904 100644
--- a/.ai/rules/code-conformance.md
+++ b/.ai/rules/code-conformance.md
@@ -70,6 +70,7 @@ Reference: [Linting tools](../../CONTRIBUTOR-DOCS/02_style-guide/03_linting-tool
 - Forced-colors media query is present and correct (if applicable)
 - High-contrast and other media queries are sorted to the bottom of the file
 - No hard-coded values where design tokens are available
+- Every class selector in CSS files (`.swc-*`) has a matching `class="..."` in the component's `render()` method; orphaned selectors mean styles are silently dead. Cross-check both directions: CSS → template and template → CSS. Use `grep -oE '\.[a-z][a-zA-Z-]+'` on the CSS and `grep -oE 'class="[^"]*"'` on the TypeScript to produce lists to compare.
 
 ## Test files
 
diff --git a/.ai/skills/migration-styling/SKILL.md b/.ai/skills/migration-styling/SKILL.md
index 8d2f1ea906..0ad008cd23 100644
--- a/.ai/skills/migration-styling/SKILL.md
+++ b/.ai/skills/migration-styling/SKILL.md
@@ -66,4 +66,6 @@ Common case: confirming that subcomponent class names follow the single-hyphen s
 
 If a rename is needed, make the template change first, confirm the component still renders correctly in Storybook, then write the CSS.
 
+**Step 3b — Audit `:host` for visual styles.** After aligning class names, scan every declaration you plan to put on `:host` against Rule 1 of the tldr. Ask for each property: is this layout-participation (how the host fits into its parent's flow) or visual (how the component looks)? If a visual style has no internal wrapper to move it to, add one to `render()` before writing CSS.
+
 **Step 4 — Execute the phase.** Follow **[Phase 5: Styling](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-5-styling)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.
diff --git a/.ai/skills/migration-styling/references/tldr-component-css-guidelines.md b/.ai/skills/migration-styling/references/tldr-component-css-guidelines.md
index 2d3f2a3336..e36a5c4ebb 100644
--- a/.ai/skills/migration-styling/references/tldr-component-css-guidelines.md
+++ b/.ai/skills/migration-styling/references/tldr-component-css-guidelines.md
@@ -72,7 +72,19 @@
 
 ### 1. `:host` vs Component Class
 
-Put only layout-participation styles on `:host`. Put actual visuals on `.swcComponentName` or internal parts.
+Put only layout-participation styles on `:host`. Put actual visuals on `.swc-ComponentName` or internal parts.
+
+Put layout-participation styles on `:host` (`display`, `inline-size`, `min-*`/`max-*`, `position`, custom property definitions). Put visual styles on `.swc-ComponentName` or an internal part.
+
+Two non-obvious cases to flag explicitly:
+
+- **`padding` on `:host`** — feels like layout but is visual spacing; move it to the internal class.
+- **`cursor: pointer`** — do not set it anywhere; the project relies on browser defaults.
+
+Also check that `display: flex` or `display: grid` on `:host` is actually laying out **direct children of `:host`**, not internal children already wrapped inside a container element. Flex/grid properties (`flex: 1 1 auto`, `align-self`) only activate when their **immediate parent** is the flex/grid container — if the element is inside a wrapper div, the flex context must be on that wrapper, not on `:host`.
+
+**`:host:has()` is unreliable across browsers.** Safari and Firefox do not consistently support `:has()` relative to a shadow host boundary. Move all `:has()` selectors to the internal wrapper: `.swc-Component:has(...)` instead of `:host:has(...)`. Custom properties cascade identically either way. See [01_component-css#state-implementation-patterns](../../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md#state-implementation-patterns).
+
 → See [01_component-css](../../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md)
 
 ### 2. Stylesheet Order
@@ -124,4 +136,7 @@ Keep selector specificity at or below `(0,1,0)`. If you need a compounded select
 ### 7. Forced colors
 
 Only add `@media (forced-colors: active)` if browser defaults are not conveying correct semantic intent, and always put it at the end of the component stylesheet.
+
+Semantic HTML elements (`<button>`, `<input>`, `<a>`) get correct forced-colors treatment automatically — `ButtonText`, focus `Highlight`, disabled `GrayText` — without any CSS override. Only non-semantic elements (a decorative `<div>` or a `<span>` using `background-color` as a visual indicator) need explicit overrides. Do not carry over forced-colors rules from 1st-gen Spectrum CSS without first verifying the 2nd-gen component uses non-semantic markup that requires them.
+
 → See [01_component-css#forced-colors-requirements](../../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md#forced-colors-requirements)
diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index e485985e5f..fe0e81199c 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -131,17 +131,19 @@ export class AccordionItem extends AccordionItemBase {
     `;
     return html`
       <div class="swc-AccordionItem">
-        ${this.renderHeadingWrapper(button)}
-        <div
-          class="swc-AccordionItem-actions"
-          hidden
-          @click=${this.stopActionsContainerPropagation}
-          @keydown=${this.stopActionsContainerPropagation}
-        >
-          <slot
-            name="actions"
-            @slotchange=${this.syncActionsContainerVisibility}
-          ></slot>
+        <div class="swc-AccordionItem-row">
+          ${this.renderHeadingWrapper(button)}
+          <div
+            class="swc-AccordionItem-actions"
+            hidden
+            @click=${this.stopActionsContainerPropagation}
+            @keydown=${this.stopActionsContainerPropagation}
+          >
+            <slot
+              name="actions"
+              @slotchange=${this.syncActionsContainerVisibility}
+            ></slot>
+          </div>
         </div>
         <div
           id="content"
diff --git a/2nd-gen/packages/swc/components/accordion/accordion-item.css b/2nd-gen/packages/swc/components/accordion/accordion-item.css
index 31e021b1a2..6481edd47c 100644
--- a/2nd-gen/packages/swc/components/accordion/accordion-item.css
+++ b/2nd-gen/packages/swc/components/accordion/accordion-item.css
@@ -15,27 +15,30 @@
   --_swc-accordion-header-bg: transparent;
   --_swc-accordion-header-text-color: token("neutral-content-color-default");
 
-  display: flex;
-  flex-wrap: wrap;
-  align-items: flex-start;
+  display: block;
   inline-size: 100%;
-  border-block-end: token("border-width-100") solid var(--swc-accordion-item-divider-color, var(--_swc-accordion-item-border-color, token("gray-200")));
-}
-
-:host(:first-child) {
-  border-block-start: token("border-width-100") solid var(--swc-accordion-item-divider-color, var(--_swc-accordion-item-border-color, token("gray-200")));
 }
 
 * {
   box-sizing: border-box;
 }
 
-/* Unnamed slots default to display:contents, which makes slotted elements
-   participate directly in the host's flex layout. Setting display:block
-   keeps the accordion's slotted items in normal vertical flow. */
-slot:not([name]) {
-  display: block;
+/* ── Item wrapper ───────────────────────────────────────────────────── */
+
+.swc-AccordionItem {
   inline-size: 100%;
+  border-block-end: token("border-width-100") solid var(--swc-accordion-item-divider-color, var(--_swc-accordion-item-border-color, token("gray-200")));
+}
+
+:host(:first-child) .swc-AccordionItem {
+  border-block-start: token("border-width-100") solid var(--swc-accordion-item-divider-color, var(--_swc-accordion-item-border-color, token("gray-200")));
+}
+
+/* ── Header row (heading + actions) ─────────────────────────────────── */
+
+.swc-AccordionItem-row {
+  display: flex;
+  align-items: center;
 }
 
 /* ── Heading reset (h2–h6 wrapping the button) ──────────────────────── */
@@ -50,13 +53,14 @@ slot:not([name]) {
 
 /* ── Header button ──────────────────────────────────────────────────── */
 
-#header {
+.swc-AccordionItem-header {
   display: flex;
   gap: token("accordion-disclosure-indicator-to-text-medium");
   align-items: center;
   inline-size: 100%;
-  padding-block: var(--_swc-accordion-pad-top-m, token("accordion-top-to-text-medium")) var(--_swc-accordion-pad-bottom-m, token("accordion-bottom-to-text-medium"));
+  padding-block: var(--_swc-accordion-pad-top-m, token("component-padding-vertical-100")) var(--_swc-accordion-pad-bottom-m, token("component-padding-vertical-100"));
   padding-inline: token("accordion-edge-to-content-area-medium") token("accordion-edge-to-text");
+  font-family: inherit;
   font-size: token("font-size-200");
   font-weight: token("bold-font-weight");
   line-height: token("line-height-100");
@@ -66,56 +70,46 @@ slot:not([name]) {
   border: 0;
   border-radius: var(--_swc-accordion-header-corner-radius, 0);
   appearance: none;
-  cursor: pointer;
-}
-
-#header:focus {
-  outline: none;
 }
 
-/* The container sets the color tokens so they cascade into #header; the
+/* The container sets the color tokens so they cascade into .swc-AccordionItem-header; the
    outline and border-radius stay on the button so the focus ring matches
    the hover footprint (toggle area only, independent of the actions slot). */
-:host:has(#header:focus-visible) {
+.swc-AccordionItem:has(.swc-AccordionItem-header:focus-visible) {
   --_swc-accordion-header-bg: token("transparent-black-100");
   --_swc-accordion-header-text-color: token("neutral-content-color-key-focus");
 }
 
-#header:focus-visible {
+.swc-AccordionItem-header:focus-visible {
   border-radius: var(--_swc-accordion-corner-radius, token("corner-radius-medium-size-medium"));
   outline: token("focus-indicator-thickness") solid token("focus-indicator-color");
   outline-offset: calc(token("accordion-focus-indicator-gap") * -1);
 }
 
 @media (hover: hover) {
-  :host:has(#header:hover) {
+  .swc-AccordionItem:has(.swc-AccordionItem-header:hover) {
     --_swc-accordion-header-bg: token("transparent-black-100");
     --_swc-accordion-header-text-color: token("neutral-content-color-hover");
   }
 }
 
-:host:has(#header:active) {
+.swc-AccordionItem:has(.swc-AccordionItem-header:active) {
   --_swc-accordion-header-bg: token("transparent-black-300");
   --_swc-accordion-header-text-color: token("neutral-content-color-down");
 }
 
-:host:has(#header[aria-disabled="true"]),
-:host:has(#header[aria-disabled="true"]:hover) {
+.swc-AccordionItem:has(.swc-AccordionItem-header[aria-disabled="true"]),
+.swc-AccordionItem:has(.swc-AccordionItem-header[aria-disabled="true"]:hover) {
   --_swc-accordion-header-bg: transparent;
   --_swc-accordion-header-text-color: token("disabled-content-color");
 }
 
-#header[aria-disabled="true"],
-#header[aria-disabled="true"]:hover {
-  cursor: default;
-}
-
 /* ── Disclosure indicator (chevron) ─────────────────────────────────── */
 
-/* Default size (m) — Chevron100 viewBox is 10×10 */
-.spectrum-Accordion-itemIndicator {
-  --swc-icon-inline-size: 10px;
-  --swc-icon-block-size: 10px;
+/* Default size (m): Chevron100 */
+.swc-AccordionItem-indicator {
+  --swc-icon-inline-size: token("chevron-icon-size-100");
+  --swc-icon-block-size: token("chevron-icon-size-100");
 
   flex-shrink: 0;
   rotate: 0deg;
@@ -123,40 +117,40 @@ slot:not([name]) {
 }
 
 /* Mirror for RTL so the chevron points left */
-:dir(rtl) .spectrum-Accordion-itemIndicator {
+:dir(rtl) .swc-AccordionItem-indicator {
   scale: -1 1;
 }
 
-/* Size: small — Chevron75 viewBox is 10×10 */
-:host([size="s"]) .spectrum-Accordion-itemIndicator {
-  --swc-icon-inline-size: 10px;
-  --swc-icon-block-size: 10px;
+/* Size: small, Chevron75 */
+:host([size="s"]) .swc-AccordionItem-indicator {
+  --swc-icon-inline-size: token("chevron-icon-size-75");
+  --swc-icon-block-size: token("chevron-icon-size-75");
 }
 
-/* Size: large — Chevron200 viewBox is 12×12 */
-:host([size="l"]) .spectrum-Accordion-itemIndicator {
-  --swc-icon-inline-size: 12px;
-  --swc-icon-block-size: 12px;
+/* Size: large, Chevron200 */
+:host([size="l"]) .swc-AccordionItem-indicator {
+  --swc-icon-inline-size: token("chevron-icon-size-200");
+  --swc-icon-block-size: token("chevron-icon-size-200");
 }
 
-/* Size: extra-large — Chevron300 viewBox is 14×14 */
-:host([size="xl"]) .spectrum-Accordion-itemIndicator {
-  --swc-icon-inline-size: 14px;
-  --swc-icon-block-size: 14px;
+/* Size: extra-large, Chevron300 */
+:host([size="xl"]) .swc-AccordionItem-indicator {
+  --swc-icon-inline-size: token("chevron-icon-size-300");
+  --swc-icon-block-size: token("chevron-icon-size-300");
 }
 
-:host([open]) .spectrum-Accordion-itemIndicator {
+:host([open]) .swc-AccordionItem-indicator {
   rotate: 90deg;
 }
 
 /* RTL + open: rotate the opposite direction */
-:host([open]):dir(rtl) .spectrum-Accordion-itemIndicator {
+:host([open]):dir(rtl) .swc-AccordionItem-indicator {
   rotate: -90deg;
 }
 
 /* ── Item title (heading slot wrapper) ──────────────────────────────── */
 
-.spectrum-Accordion-itemTitle {
+.swc-AccordionItem-label {
   flex: 1;
 }
 
@@ -175,18 +169,16 @@ slot:not([name]) {
 
 /* ── Direct actions (inline with heading, outside the toggle area) ───── */
 
-.spectrum-Accordion-itemDirectActions {
+.swc-AccordionItem-actions {
   display: flex;
   flex: 0 0 auto;
   align-items: center;
-  align-self: center;
 }
 
 /* ── Content panel ──────────────────────────────────────────────────── */
 
-.spectrum-Accordion-itemContent {
+.swc-AccordionItem-content {
   display: none;
-  flex: 0 0 100%;
   padding-block: token("accordion-content-area-top-to-content") token("accordion-content-area-bottom-to-content");
   padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-medium"));
   font-size: token("font-size-100");
@@ -195,7 +187,7 @@ slot:not([name]) {
   color: token("neutral-subdued-content-color-default");
 }
 
-:host([open]) .spectrum-Accordion-itemContent {
+:host([open]) .swc-AccordionItem-content {
   display: block;
 }
 
@@ -205,14 +197,14 @@ slot:not([name]) {
   --_swc-accordion-corner-radius: token("corner-radius-medium-size-small");
 }
 
-:host([size="s"]) #header {
+:host([size="s"]) .swc-AccordionItem-header {
   gap: token("accordion-disclosure-indicator-to-text-small");
-  padding-block: var(--_swc-accordion-pad-top-s, token("accordion-top-to-text-small")) var(--_swc-accordion-pad-bottom-s, token("accordion-bottom-to-text-small"));
+  padding-block: var(--_swc-accordion-pad-top-s, token("component-padding-vertical-75")) var(--_swc-accordion-pad-bottom-s, token("component-padding-vertical-75"));
   padding-inline-start: token("accordion-edge-to-content-area-small");
   font-size: token("font-size-100");
 }
 
-:host([size="s"]) .spectrum-Accordion-itemContent {
+:host([size="s"]) .swc-AccordionItem-content {
   padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-small"));
 }
 
@@ -222,14 +214,14 @@ slot:not([name]) {
   --_swc-accordion-corner-radius: token("corner-radius-medium-size-large");
 }
 
-:host([size="l"]) #header {
+:host([size="l"]) .swc-AccordionItem-header {
   gap: token("accordion-disclosure-indicator-to-text-large");
-  padding-block: var(--_swc-accordion-pad-top-l, token("accordion-top-to-text-large")) var(--_swc-accordion-pad-bottom-l, token("accordion-bottom-to-text-large"));
+  padding-block: var(--_swc-accordion-pad-top-l, token("component-padding-vertical-200")) var(--_swc-accordion-pad-bottom-l, token("component-padding-vertical-200"));
   padding-inline-start: token("accordion-edge-to-content-area-large");
   font-size: token("font-size-300");
 }
 
-:host([size="l"]) .spectrum-Accordion-itemContent {
+:host([size="l"]) .swc-AccordionItem-content {
   padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-large"));
 }
 
@@ -239,37 +231,14 @@ slot:not([name]) {
   --_swc-accordion-corner-radius: token("corner-radius-medium-size-extra-large");
 }
 
-:host([size="xl"]) #header {
+:host([size="xl"]) .swc-AccordionItem-header {
   gap: token("accordion-disclosure-indicator-to-text-extra-large");
-  padding-block: var(--_swc-accordion-pad-top-xl, token("accordion-top-to-text-extra-large")) var(--_swc-accordion-pad-bottom-xl, token("accordion-bottom-to-text-extra-large"));
+  padding-block: var(--_swc-accordion-pad-top-xl, token("component-padding-vertical-300")) var(--_swc-accordion-pad-bottom-xl, token("component-padding-vertical-300"));
   padding-inline-start: token("accordion-edge-to-content-area-extra-large");
   font-size: token("font-size-400");
 }
 
-:host([size="xl"]) .spectrum-Accordion-itemContent {
+:host([size="xl"]) .swc-AccordionItem-content {
   padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-extra-large"));
 }
 
-/* ── Forced colors ──────────────────────────────────────────────────── */
-
-@media (forced-colors: active) {
-  :host {
-    /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
-    border-color: ButtonText;
-  }
-
-  #header {
-    /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
-    color: ButtonText;
-  }
-
-  #header:focus-visible {
-    /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
-    outline-color: Highlight;
-  }
-
-  #header[aria-disabled="true"] {
-    /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
-    color: GrayText;
-  }
-}
diff --git a/2nd-gen/packages/swc/components/accordion/accordion.css b/2nd-gen/packages/swc/components/accordion/accordion.css
index 94dcc5913a..5561301f6c 100644
--- a/2nd-gen/packages/swc/components/accordion/accordion.css
+++ b/2nd-gen/packages/swc/components/accordion/accordion.css
@@ -12,36 +12,54 @@
 
 :host {
   display: block;
-  inline-size: 100%;
   min-inline-size: var(--swc-accordion-min-inline-size, token("accordion-minimum-width"));
 }
 
-/* Compact density — overrides cascade to child items */
-:host([density="compact"]) {
-  --_swc-accordion-pad-top-s: token("accordion-top-to-text-compact-small");
-  --_swc-accordion-pad-top-m: token("accordion-top-to-text-compact-medium");
-  --_swc-accordion-pad-top-l: token("accordion-top-to-text-compact-large");
-  --_swc-accordion-pad-top-xl: token("accordion-top-to-text-compact-extra-large");
-  --_swc-accordion-pad-bottom-s: token("accordion-bottom-to-text-compact-small");
-  --_swc-accordion-pad-bottom-m: token("accordion-bottom-to-text-compact-medium");
-  --_swc-accordion-pad-bottom-l: token("accordion-bottom-to-text-compact-large");
-  --_swc-accordion-pad-bottom-xl: token("accordion-bottom-to-text-compact-extra-large");
-}
-
-/* Spacious density — overrides cascade to child items */
-:host([density="spacious"]) {
-  --_swc-accordion-pad-top-s: token("accordion-top-to-text-spacious-small");
-  --_swc-accordion-pad-top-m: token("accordion-top-to-text-spacious-medium");
-  --_swc-accordion-pad-top-l: token("accordion-top-to-text-spacious-large");
-  --_swc-accordion-pad-top-xl: token("accordion-top-to-text-spacious-extra-large");
-  --_swc-accordion-pad-bottom-s: token("accordion-bottom-to-text-spacious-small");
-  --_swc-accordion-pad-bottom-m: token("accordion-bottom-to-text-spacious-medium");
-  --_swc-accordion-pad-bottom-l: token("accordion-bottom-to-text-spacious-large");
-  --_swc-accordion-pad-bottom-xl: token("accordion-bottom-to-text-spacious-extra-large");
-}
-
-/* Quiet — removes dividers and enables rounded corners on hover */
-:host([quiet]) {
+.swc-Accordion {
+  --_swc-accordion-corner-radius: token("corner-radius-medium-size-medium");
+}
+
+/* Corner radius per size: cascades to child items so quiet mode resolves correctly */
+:host([size="s"]) .swc-Accordion {
+  --_swc-accordion-corner-radius: token("corner-radius-medium-size-small");
+}
+
+:host([size="l"]) .swc-Accordion {
+  --_swc-accordion-corner-radius: token("corner-radius-medium-size-large");
+}
+
+:host([size="xl"]) .swc-Accordion {
+  --_swc-accordion-corner-radius: token("corner-radius-medium-size-extra-large");
+}
+
+/* Compact density: overrides cascade to child items */
+:host([density="compact"]) .swc-Accordion {
+  --_swc-accordion-pad-top-s: token("component-padding-vertical-50");
+  --_swc-accordion-pad-top-m: token("component-padding-vertical-75");
+  --_swc-accordion-pad-top-l: token("component-padding-vertical-100");
+  --_swc-accordion-pad-top-xl: token("component-padding-vertical-200");
+  --_swc-accordion-pad-bottom-s: token("component-padding-vertical-50");
+  --_swc-accordion-pad-bottom-m: token("component-padding-vertical-75");
+  --_swc-accordion-pad-bottom-l: token("component-padding-vertical-100");
+  --_swc-accordion-pad-bottom-xl: token("component-padding-vertical-200");
+}
+
+/* Spacious density: overrides cascade to child items */
+:host([density="spacious"]) .swc-Accordion {
+  --_swc-accordion-pad-top-s: token("component-padding-vertical-100");
+  --_swc-accordion-pad-top-m: token("component-padding-vertical-200");
+
+  /* +3px offset because component-padding-vertical-300 (13px) is the highest available scale; replace with a higher-scale token once one is added to the token set */
+  --_swc-accordion-pad-top-l: calc(token("component-padding-vertical-300") + 3px);
+  --_swc-accordion-pad-top-xl: calc(token("component-padding-vertical-300") + 3px);
+  --_swc-accordion-pad-bottom-s: token("component-padding-vertical-100");
+  --_swc-accordion-pad-bottom-m: token("component-padding-vertical-200");
+  --_swc-accordion-pad-bottom-l: calc(token("component-padding-vertical-300") + 3px);
+  --_swc-accordion-pad-bottom-xl: calc(token("component-padding-vertical-300") + 3px);
+}
+
+/* Quiet: removes dividers and rounds header corners (visible on hover and focus) */
+:host([quiet]) .swc-Accordion {
   --_swc-accordion-item-border-color: transparent;
   --_swc-accordion-header-corner-radius: var(--_swc-accordion-corner-radius);
 }
diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index 4f02650a14..4e5b5ec28c 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -89,8 +89,8 @@ const defaultItems = html`
  * be expanded or collapsed. Only one section is open at a time by default;
  * set `allow-multiple` to let any number of sections be open simultaneously.
  *
- * Items support an **`actions` slot** for placing interactive controls — such
- * as an edit button — directly in the header row, outside the toggle button so
+ * Items support an **`actions` slot** for placing interactive controls (such
+ * as an edit button) directly in the header row, outside the toggle button so
  * they remain independently clickable.
  */
 const meta: Meta = {
@@ -98,13 +98,9 @@ const meta: Meta = {
   component: 'swc-accordion',
   args,
   argTypes,
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template(args, defaultItems)}
-    </div>
-  `,
+  render: (args) => template(args, defaultItems),
   parameters: {
-    layout: 'centered',
+    layout: 'padded',
     actions: { handles: [SWC_ACCORDION_ITEM_TOGGLE_EVENT] },
     docs: {
       subtitle: 'Groups related content sections behind expandable headers.',
@@ -169,11 +165,7 @@ const anatomyItems = html`
  * - **Default slot**: The panel body revealed when the item expands
  */
 export const Anatomy: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template(args, anatomyItems)}
-    </div>
-  `,
+  render: (args) => template(args, anatomyItems),
   tags: ['anatomy'],
 };
 
@@ -186,9 +178,7 @@ export const Anatomy: Story = {
  */
 export const Sizes: Story = {
   render: (args) => html`
-    <div
-      style="display: flex; flex-direction: column; gap: 16px; inline-size: 720px; max-inline-size: 100%;"
-    >
+    <div style="display: flex; flex-direction: column; gap: 16px;">
       ${ACCORDION_VALID_SIZES.map(
         (size) => html`
           ${template(
@@ -218,9 +208,7 @@ export const Sizes: Story = {
  */
 export const Density: Story = {
   render: (args) => html`
-    <div
-      style="display: flex; flex-direction: column; gap: 16px; inline-size: 720px; max-inline-size: 100%;"
-    >
+    <div style="display: flex; flex-direction: column; gap: 16px;">
       ${ACCORDION_DENSITIES.map(
         (density) => html`
           ${template(
@@ -248,11 +236,7 @@ export const Density: Story = {
  * and adds rounded corners on hover for a contained feel.
  */
 export const Quiet: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template({ ...args, quiet: true }, defaultItems)}
-    </div>
-  `,
+  render: (args) => template({ ...args, quiet: true }, defaultItems),
   args: { density: 'regular' },
   tags: ['options'],
   parameters: { 'section-order': 3 },
@@ -264,11 +248,7 @@ export const Quiet: Story = {
  * hierarchy without changing the visual style.
  */
 export const HeadingLevel: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template({ ...args, level: 2 }, defaultItems)}
-    </div>
-  `,
+  render: (args) => template({ ...args, level: 2 }, defaultItems),
   args: { density: 'regular' },
   tags: ['options'],
   parameters: { 'section-order': 4 },
@@ -298,11 +278,7 @@ const stateItems = html`
  * A disabled item remains in the tab order but its toggle is blocked.
  */
 export const ItemStates: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template({ ...args, 'allow-multiple': true }, stateItems)}
-    </div>
-  `,
+  render: (args) => template({ ...args, 'allow-multiple': true }, stateItems),
   args: { density: 'regular' },
   tags: ['states'],
   parameters: { 'section-order': 1 },
@@ -314,11 +290,7 @@ export const ItemStates: Story = {
  * accordion restores each item's original state.
  */
 export const DisabledAccordion: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template({ ...args, disabled: true }, defaultItems)}
-    </div>
-  `,
+  render: (args) => template({ ...args, disabled: true }, defaultItems),
   args: { density: 'regular' },
   tags: ['states'],
   parameters: { 'section-order': 2 },
@@ -335,27 +307,24 @@ export const DisabledAccordion: Story = {
  * is re-enabled.
  */
 export const MixedDisabledStates: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template(
-        { ...args, disabled: true, 'allow-multiple': true },
-        html`
-          <swc-accordion-item open>
-            <span slot="label">Personal information</span>
-            ${content.personal}
-          </swc-accordion-item>
-          <swc-accordion-item>
-            <span slot="label">Billing address</span>
-            ${content.billing}
-          </swc-accordion-item>
-          <swc-accordion-item disabled>
-            <span slot="label">Payment method</span>
-            ${content.payment}
-          </swc-accordion-item>
-        `
-      )}
-    </div>
-  `,
+  render: (args) =>
+    template(
+      { ...args, disabled: true, 'allow-multiple': true },
+      html`
+        <swc-accordion-item open>
+          <span slot="label">Personal information</span>
+          ${content.personal}
+        </swc-accordion-item>
+        <swc-accordion-item>
+          <span slot="label">Billing address</span>
+          ${content.billing}
+        </swc-accordion-item>
+        <swc-accordion-item disabled>
+          <span slot="label">Payment method</span>
+          ${content.payment}
+        </swc-accordion-item>
+      `
+    ),
   args: { density: 'regular' },
   tags: ['states'],
   parameters: { 'section-order': 3 },
@@ -416,11 +385,7 @@ const directActionsItems = html`
  * actions container so action buttons never accidentally trigger the toggle.
  */
 export const DirectActions: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template(args, directActionsItems)}
-    </div>
-  `,
+  render: (args) => template(args, directActionsItems),
   args: { density: 'regular' },
   tags: ['behaviors'],
   parameters: { 'section-order': 1 },
@@ -447,11 +412,8 @@ const allowMultipleItems = html`
  * to be open simultaneously.
  */
 export const AllowMultiple: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template({ ...args, 'allow-multiple': true }, allowMultipleItems)}
-    </div>
-  `,
+  render: (args) =>
+    template({ ...args, 'allow-multiple': true }, allowMultipleItems),
   args: { density: 'regular' },
   tags: ['behaviors'],
   parameters: { 'section-order': 2 },
@@ -467,16 +429,52 @@ export const AllowMultiple: Story = {
  * with the accordion below.
  */
 export const ToggleEvent: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template(args, defaultItems)}
-    </div>
-  `,
+  render: (args) => template(args, defaultItems),
   args: { density: 'regular' },
   tags: ['behaviors'],
   parameters: { 'section-order': 3 },
 };
 
+/**
+ * Set `--swc-accordion-content-padding-inline` on the accordion to remove the
+ * default inline padding from every panel body. This is useful when panel
+ * content (such as a data table or an image) should extend edge to edge
+ * inside the item.
+ *
+ * Setting the property to `0` removes all inline padding. Any valid CSS length
+ * value is accepted.
+ */
+export const ContentPaddingInline: Story = {
+  render: (args) =>
+    template(
+      { ...args, 'allow-multiple': true },
+      html`
+        <swc-accordion-item open>
+          <span slot="label">Personal information</span>
+          <div
+            style="background: var(--spectrum-gray-100); padding: 12px 16px;"
+          >
+            ${content.personal}
+          </div>
+        </swc-accordion-item>
+        <swc-accordion-item open>
+          <span slot="label">Billing address</span>
+          <div
+            style="background: var(--spectrum-gray-100); padding: 12px 16px;"
+          >
+            ${content.billing}
+          </div>
+        </swc-accordion-item>
+      `
+    ),
+  args: { density: 'regular' },
+  tags: ['behaviors'],
+  parameters: {
+    'section-order': 4,
+    styles: { '--swc-accordion-content-padding-inline': '0' },
+  },
+};
+
 // ────────────────────────────────
 //    ACCESSIBILITY STORIES
 // ────────────────────────────────
@@ -540,11 +538,7 @@ const a11yItems = html`
  * - Always set `density` explicitly; use `regular` when unsure
  */
 export const Accessibility: Story = {
-  render: (args) => html`
-    <div style="inline-size: 720px; max-inline-size: 100%;">
-      ${template(args, a11yItems)}
-    </div>
-  `,
+  render: (args) => template(args, a11yItems),
   args: { density: 'regular', level: 3 },
   tags: ['a11y'],
 };
diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md b/CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md
index 02e071e8cf..0fc350c495 100644
--- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md
+++ b/CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md
@@ -279,6 +279,22 @@ States reflect user interaction or component condition. Attach them to `:host` w
 
 **Derived states are not on `:host`**: If a state is computed from slot content (e.g. icon-only), it is not a consumer-settable attribute and must not appear in the state table above. Express it as a class modifier on the internal element via `classMap`. See [When to use classes vs attributes](#when-to-use-classes-vs-attributes).
 
+**`:host:has()` cross-browser compatibility**: Avoid `:host:has(.some-internal-selector)`. This selector pattern has inconsistent behavior in shadow DOM across Safari and Firefox — the browser must evaluate `:has()` relative to a shadow host boundary, which is not yet uniformly supported. Move the `:has()` to the internal wrapper instead:
+
+```css
+/* ❌ Avoid — :has() relative to :host is unreliable across browsers */
+:host:has(.swc-Component-header:hover) {
+  --_swc-component-bg: token("transparent-black-100");
+}
+
+/* ✅ Use — :has() on the internal wrapper works consistently */
+.swc-Component:has(.swc-Component-header:hover) {
+  --_swc-component-bg: token("transparent-black-100");
+}
+```
+
+Custom properties set on the internal wrapper still cascade correctly to its descendants, so the behavior is identical.
+
 ## Size variant patterns
 
 Size variants (s, m, l, xl) use `:host([size="..."])` and update custom properties. Do not add size classes to `render()`.
@@ -368,7 +384,7 @@ Forced colors mode (Windows High Contrast, etc.) replaces colors with system val
 
 **Rules**:
 
-1. **Check first**: Do not add forced-colors styles if the browser already makes the component visible.
+1. **Check first**: Do not add forced-colors styles if the browser already makes the component visible. Semantic HTML elements (`<button>`, `<input>`, `<a>`, etc.) receive correct system colors automatically in forced-colors mode — `ButtonText`, `Highlight` on focus, `GrayText` when disabled — without any CSS override. Only non-semantic elements (e.g. a decorative `<div>` or a `<span>` using `background-color` as a visual indicator) need explicit overrides because the browser cannot infer their role.
 2. **Place last**: Put `@media (forced-colors: active)` at the end of the stylesheet so it overrides other styles.
 3. **Use internal selectors**: Target `.swc-ComponentName` or internal elements, not `:host`. This prevents accidental consumer overrides from breaking accessibility.
 4. **Reuse custom properties**: Override component custom properties (e.g. `--swc-status-light-content-color`) so the rest of the stylesheet still works.
diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md b/CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md
index a0ca1c44d9..40de1313a9 100644
--- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md
+++ b/CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md
@@ -56,6 +56,11 @@
     - [Specificity escalation → `:where()`](#specificity-escalation--where)
     - [Size classes in render → `:host([size])`](#size-classes-in-render--hostsize)
     - [`--mod-*` chain → single property](#--mod--chain--single-property)
+- [9. Suppressing focus outlines with `:focus { outline: none }`](#9-suppressing-focus-outlines-with-focus--outline-none-)
+    - [❌ Anti-Pattern](#-anti-pattern)
+    - [Why This Happens](#why-this-happens)
+    - [Why This Is a Problem](#why-this-is-a-problem)
+    - [✅ Correct Approach](#-correct-approach)
 - [Final Reminder](#final-reminder)
 
 </details>
@@ -419,6 +424,29 @@ After migration, Badge relies solely on `.swc-Badge` and attributes.
 | ------------------------------------------------------- | -------------------------------------------------------- |
 | `var(--mod-badge-height, var(--spectrum-badge-height))` | `var(--swc-badge-height, token("component-height-100"))` |
 
+## 9. Suppressing focus outlines with `:focus { outline: none }`
+
+### ❌ Anti-Pattern
+
+```css
+.swc-Component-header:focus {
+  outline: none;
+}
+```
+
+### Why This Happens
+
+- Carried over from 1st-gen Spectrum CSS, which managed focus rings through its own system
+
+### Why This Is a Problem
+
+- Removes the focus indicator for keyboard users — an accessibility violation (WCAG 2.4.7)
+- The component already has a `:focus-visible` rule; the `:focus` suppression just interferes with it
+
+### ✅ Correct Approach
+
+- Remove the rule entirely. `:focus-visible` already handles when to show the ring; no explicit suppression is needed.
+
 ## Final Reminder
 
 If you find yourself:
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/migration-plan.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/migration-plan.md
index c4e8684501..c9036deeab 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/migration-plan.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/accordion/migration-plan.md
@@ -30,6 +30,9 @@
     - [Selection sync — `RadioController` pattern (consider)](#selection-sync--radiocontroller-pattern-consider)
     - [Analysis inputs](#analysis-inputs)
 - [Architecture: core vs SWC split](#architecture-core-vs-swc-split)
+- [CSS custom property migration reference](#css-custom-property-migration-reference)
+    - [`--mod-*` to `--swc-*` mapping](#--mod--to---swc--mapping)
+    - [Density × size padding matrix](#density--size-padding-matrix)
 - [Migration checklist](#migration-checklist)
     - [Preparation (this ticket)](#preparation-this-ticket)
     - [Setup](#setup)
@@ -294,6 +297,45 @@ Follow the [washing machine — core vs SWC](../../02_workstreams/02_2nd-gen-com
 
 ---
 
+## CSS custom property migration reference
+
+### `--mod-*` to `--swc-*` mapping
+
+2nd-gen exposes a narrower customization surface than 1st-gen. Most visual values are driven by Spectrum 2 design tokens internally and are not overridable via custom properties.
+
+| 1st-gen property | 2nd-gen property | Notes |
+|---|---|---|
+| `--mod-accordion-item-width` | `--swc-accordion-min-inline-size` | Renamed; sets the minimum inline size of the accordion host |
+| `--mod-accordion-divider-color` | `--swc-accordion-item-divider-color` | Renamed; controls the border color of each item's top and bottom dividers |
+| `--mod-accordion-component-edge-to-text` | `--swc-accordion-content-padding-inline` | Renamed; controls the inline padding of the panel body. Set to `0` for edge-to-edge content |
+| `--mod-accordion-background-color-*` | Not exposed | Driven by internal tokens via `:has()` state selectors |
+| `--mod-accordion-corner-radius` | Not exposed | Driven by `--_swc-accordion-corner-radius` (private; size-scaled) |
+| `--mod-accordion-item-header-color-*` | Not exposed | Driven by internal tokens via `:has()` state selectors |
+| `--mod-accordion-focus-indicator-*` | Not exposed | Driven by global focus indicator tokens |
+| `--mod-accordion-item-content-*` (typography) | Not exposed | Driven by global typography tokens |
+| `--mod-accordion-item-header-*` (typography) | Not exposed | Driven by global typography tokens |
+| `--mod-accordion-disclosure-indicator-*` | Not exposed | Controlled internally by `--swc-icon-*` on the chevron element |
+| `--mod-accordion-divider-thickness` | Not exposed | Driven by `token("border-width-100")` |
+| `--mod-accordion-min-block-size` | Not exposed | Minimum height is set by block-padding tokens and content height |
+| `--mod-accordion-edge-to-*-space` | Not exposed | Padding is token-driven per size; use `--swc-accordion-content-padding-inline` for the panel content area only |
+| `--mod-accordion-item-content-area-*-to-content` | Not exposed | Driven by `token("accordion-content-area-top-to-content")` and `token("accordion-content-area-bottom-to-content")` |
+
+### Density × size padding matrix
+
+Header block padding is determined by `density` (on the accordion host) and `size` (set on the host and propagated to items). Density tokens override the default size tokens via CSS custom properties cascaded from the host.
+
+| Density | Size s | Size m (default) | Size l | Size xl |
+|---|---|---|---|---|
+| **regular** | `accordion-top/bottom-to-text-small` | `accordion-top/bottom-to-text-medium` | `accordion-top/bottom-to-text-large` | `accordion-top/bottom-to-text-extra-large` |
+| **compact** | `accordion-top/bottom-to-text-compact-small` | `accordion-top/bottom-to-text-compact-medium` | `accordion-top/bottom-to-text-compact-large` | `accordion-top/bottom-to-text-compact-extra-large` |
+| **spacious** | `accordion-top/bottom-to-text-spacious-small` | `accordion-top/bottom-to-text-spacious-medium` | `accordion-top/bottom-to-text-spacious-large` | `accordion-top/bottom-to-text-spacious-extra-large` |
+
+> `top/bottom` is shorthand; each cell represents two tokens: `accordion-top-to-text-*` and `accordion-bottom-to-text-*`.
+
+Regular density uses the base size tokens directly. Compact and spacious densities override the values by setting `--_swc-accordion-pad-top-{s|m|l|xl}` and `--_swc-accordion-pad-bottom-{s|m|l|xl}` on the `:host` of `swc-accordion`. These are internal private properties and are not part of the public API.
+
+---
+
 ## Migration checklist
 
 Gates align with [01_washing-machine-workflow.md](../../02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md).
@@ -319,8 +361,8 @@ Gates align with [01_washing-machine-workflow.md](../../02_workstreams/02_2nd-ge
 
 ### Styling
 
-- [ ] S2 CSS integrated; stylelint clean
-- [ ] Document token / `--mod-*` → S2 (or `--swc-*`) mapping for consumers; include **`density` × `size`** matrix
+- [x] S2 CSS integrated; stylelint clean
+- [x] Document token / `--mod-*` → S2 (or `--swc-*`) mapping for consumers; include **`density` × `size`** matrix
 
 ### Accessibility
 
@@ -336,9 +378,9 @@ Gates align with [01_washing-machine-workflow.md](../../02_workstreams/02_2nd-ge
 
 ### Documentation
 
-- [ ] JSDoc, usage docs, Storybook stories (include a spacing / **custom properties** story for “no inline padding” style parity; **no** `noInlinePadding`-style attribute)
-- [ ] Add a Storybook story demonstrating inline padding customization via `--swc-accordion-*` custom properties (no `noInlinePadding`-style attribute)
-- [ ] Do not document arrow-key navigation between headers for 2nd-gen (contrast with legacy README)
+- [x] JSDoc, usage docs, Storybook stories (include a spacing / **custom properties** story for “no inline padding” style parity; **no** `noInlinePadding`-style attribute)
+- [x] Add a Storybook story demonstrating inline padding customization via `--swc-accordion-*` custom properties (no `noInlinePadding`-style attribute)
+- [x] Do not document arrow-key navigation between headers for 2nd-gen (contrast with legacy README)
 
 ### Review
 

From 89636296399af278574a643fb71f949581b2aa5d Mon Sep 17 00:00:00 2001
From: Miwha Bonini <mbonini@adobe.com>
Date: Thu, 21 May 2026 15:35:19 -0600
Subject: [PATCH 54/56] fix(accordion): restore row wrapper and register
 swc-button in stories

---
 .../swc/components/accordion/AccordionItem.ts | 20 ++++++++++---------
 .../accordion/stories/accordion.stories.ts    |  1 +
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
index bda52d9d34..60e7880d3b 100644
--- a/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
+++ b/2nd-gen/packages/swc/components/accordion/AccordionItem.ts
@@ -124,15 +124,17 @@ export class AccordionItem extends AccordionItemBase {
     `;
     return html`
       <div class="swc-AccordionItem">
-        ${this.renderHeadingWrapper(button)}
-        ${when(
-          this.slotContentIsPresent,
-          () => html`
-            <div class="swc-AccordionItem-actions">
-              <slot name="actions"></slot>
-            </div>
-          `
-        )}
+        <div class="swc-AccordionItem-row">
+          ${this.renderHeadingWrapper(button)}
+          ${when(
+            this.slotContentIsPresent,
+            () => html`
+              <div class="swc-AccordionItem-actions">
+                <slot name="actions"></slot>
+              </div>
+            `
+          )}
+        </div>
         <div
           id="content"
           class="swc-AccordionItem-content"
diff --git a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
index 9e828a42df..4e5b5ec28c 100644
--- a/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
+++ b/2nd-gen/packages/swc/components/accordion/stories/accordion.stories.ts
@@ -16,6 +16,7 @@ import { getStorybookHelpers } from '@wc-toolkit/storybook-helpers';
 
 import '@adobe/spectrum-wc/components/accordion/swc-accordion.js';
 import '@adobe/spectrum-wc/components/accordion/swc-accordion-item.js';
+import '@adobe/spectrum-wc/components/button/swc-button.js';
 
 import {
   ACCORDION_DENSITIES,

From ae634d46d542c7b82cce04640354c2ba165dc85a Mon Sep 17 00:00:00 2001
From: Miwha Bonini <mbonini@adobe.com>
Date: Fri, 22 May 2026 09:25:00 -0600
Subject: [PATCH 55/56] fix(accordion): change ceiling amount to spacing-300

---
 .../packages/swc/components/accordion/accordion.css    | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/2nd-gen/packages/swc/components/accordion/accordion.css b/2nd-gen/packages/swc/components/accordion/accordion.css
index 5561301f6c..32898ed822 100644
--- a/2nd-gen/packages/swc/components/accordion/accordion.css
+++ b/2nd-gen/packages/swc/components/accordion/accordion.css
@@ -49,13 +49,13 @@
   --_swc-accordion-pad-top-s: token("component-padding-vertical-100");
   --_swc-accordion-pad-top-m: token("component-padding-vertical-200");
 
-  /* +3px offset because component-padding-vertical-300 (13px) is the highest available scale; replace with a higher-scale token once one is added to the token set */
-  --_swc-accordion-pad-top-l: calc(token("component-padding-vertical-300") + 3px);
-  --_swc-accordion-pad-top-xl: calc(token("component-padding-vertical-300") + 3px);
+  /* spacing-300 (16px) used here as component-padding-vertical tops out at 300 (13px); switch to a component-padding-vertical token once a higher scale is added */
+  --_swc-accordion-pad-top-l: token("spacing-300");
+  --_swc-accordion-pad-top-xl: token("spacing-300");
   --_swc-accordion-pad-bottom-s: token("component-padding-vertical-100");
   --_swc-accordion-pad-bottom-m: token("component-padding-vertical-200");
-  --_swc-accordion-pad-bottom-l: calc(token("component-padding-vertical-300") + 3px);
-  --_swc-accordion-pad-bottom-xl: calc(token("component-padding-vertical-300") + 3px);
+  --_swc-accordion-pad-bottom-l: token("spacing-300");
+  --_swc-accordion-pad-bottom-xl: token("spacing-300");
 }
 
 /* Quiet: removes dividers and rounds header corners (visible on hover and focus) */

From c934067e2bfc3ff30b5351a3860f7c417a4cc652 Mon Sep 17 00:00:00 2001
From: Miwha Bonini <mbonini@adobe.com>
Date: Fri, 22 May 2026 13:49:37 -0600
Subject: [PATCH 56/56] fix(accordion): fix token names for header and content
 sections

---
 .../components/accordion/accordion-item.css   | 17 +++++-----
 .../swc/components/accordion/accordion.css    | 34 +++++++++----------
 2 files changed, 24 insertions(+), 27 deletions(-)

diff --git a/2nd-gen/packages/swc/components/accordion/accordion-item.css b/2nd-gen/packages/swc/components/accordion/accordion-item.css
index 6481edd47c..c22564dd6c 100644
--- a/2nd-gen/packages/swc/components/accordion/accordion-item.css
+++ b/2nd-gen/packages/swc/components/accordion/accordion-item.css
@@ -58,7 +58,7 @@
   gap: token("accordion-disclosure-indicator-to-text-medium");
   align-items: center;
   inline-size: 100%;
-  padding-block: var(--_swc-accordion-pad-top-m, token("component-padding-vertical-100")) var(--_swc-accordion-pad-bottom-m, token("component-padding-vertical-100"));
+  padding-block: var(--_swc-accordion-pad-top-m, token("accordion-top-to-text-medium")) var(--_swc-accordion-pad-bottom-m, token("accordion-bottom-to-text-medium"));
   padding-inline: token("accordion-edge-to-content-area-medium") token("accordion-edge-to-text");
   font-family: inherit;
   font-size: token("font-size-200");
@@ -180,7 +180,7 @@
 .swc-AccordionItem-content {
   display: none;
   padding-block: token("accordion-content-area-top-to-content") token("accordion-content-area-bottom-to-content");
-  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-medium"));
+  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-content-area-edge-to-content-medium"));
   font-size: token("font-size-100");
   font-weight: token("regular-font-weight");
   line-height: token("line-height-100");
@@ -199,13 +199,13 @@
 
 :host([size="s"]) .swc-AccordionItem-header {
   gap: token("accordion-disclosure-indicator-to-text-small");
-  padding-block: var(--_swc-accordion-pad-top-s, token("component-padding-vertical-75")) var(--_swc-accordion-pad-bottom-s, token("component-padding-vertical-75"));
+  padding-block: var(--_swc-accordion-pad-top-s, token("accordion-top-to-text-small")) var(--_swc-accordion-pad-bottom-s, token("accordion-bottom-to-text-small"));
   padding-inline-start: token("accordion-edge-to-content-area-small");
   font-size: token("font-size-100");
 }
 
 :host([size="s"]) .swc-AccordionItem-content {
-  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-small"));
+  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-content-area-edge-to-content-small"));
 }
 
 /* ── Size: large ────────────────────────────────────────────────────── */
@@ -216,13 +216,13 @@
 
 :host([size="l"]) .swc-AccordionItem-header {
   gap: token("accordion-disclosure-indicator-to-text-large");
-  padding-block: var(--_swc-accordion-pad-top-l, token("component-padding-vertical-200")) var(--_swc-accordion-pad-bottom-l, token("component-padding-vertical-200"));
+  padding-block: var(--_swc-accordion-pad-top-l, token("accordion-top-to-text-large")) var(--_swc-accordion-pad-bottom-l, token("accordion-bottom-to-text-large"));
   padding-inline-start: token("accordion-edge-to-content-area-large");
   font-size: token("font-size-300");
 }
 
 :host([size="l"]) .swc-AccordionItem-content {
-  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-large"));
+  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-content-area-edge-to-content-large"));
 }
 
 /* ── Size: extra-large ──────────────────────────────────────────────── */
@@ -233,12 +233,11 @@
 
 :host([size="xl"]) .swc-AccordionItem-header {
   gap: token("accordion-disclosure-indicator-to-text-extra-large");
-  padding-block: var(--_swc-accordion-pad-top-xl, token("component-padding-vertical-300")) var(--_swc-accordion-pad-bottom-xl, token("component-padding-vertical-300"));
+  padding-block: var(--_swc-accordion-pad-top-xl, token("accordion-top-to-text-extra-large")) var(--_swc-accordion-pad-bottom-xl, token("accordion-bottom-to-text-extra-large"));
   padding-inline-start: token("accordion-edge-to-content-area-extra-large");
   font-size: token("font-size-400");
 }
 
 :host([size="xl"]) .swc-AccordionItem-content {
-  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-edge-to-content-area-extra-large"));
+  padding-inline: var(--swc-accordion-content-padding-inline, token("accordion-content-area-edge-to-content-extra-large"));
 }
-
diff --git a/2nd-gen/packages/swc/components/accordion/accordion.css b/2nd-gen/packages/swc/components/accordion/accordion.css
index 32898ed822..29c990d3c2 100644
--- a/2nd-gen/packages/swc/components/accordion/accordion.css
+++ b/2nd-gen/packages/swc/components/accordion/accordion.css
@@ -34,28 +34,26 @@
 
 /* Compact density: overrides cascade to child items */
 :host([density="compact"]) .swc-Accordion {
-  --_swc-accordion-pad-top-s: token("component-padding-vertical-50");
-  --_swc-accordion-pad-top-m: token("component-padding-vertical-75");
-  --_swc-accordion-pad-top-l: token("component-padding-vertical-100");
-  --_swc-accordion-pad-top-xl: token("component-padding-vertical-200");
-  --_swc-accordion-pad-bottom-s: token("component-padding-vertical-50");
-  --_swc-accordion-pad-bottom-m: token("component-padding-vertical-75");
-  --_swc-accordion-pad-bottom-l: token("component-padding-vertical-100");
-  --_swc-accordion-pad-bottom-xl: token("component-padding-vertical-200");
+  --_swc-accordion-pad-top-s: token("accordion-top-to-text-compact-small");
+  --_swc-accordion-pad-top-m: token("accordion-top-to-text-compact-medium");
+  --_swc-accordion-pad-top-l: token("accordion-top-to-text-compact-large");
+  --_swc-accordion-pad-top-xl: token("accordion-top-to-text-compact-extra-large");
+  --_swc-accordion-pad-bottom-s: token("accordion-bottom-to-text-compact-small");
+  --_swc-accordion-pad-bottom-m: token("accordion-bottom-to-text-compact-medium");
+  --_swc-accordion-pad-bottom-l: token("accordion-bottom-to-text-compact-large");
+  --_swc-accordion-pad-bottom-xl: token("accordion-bottom-to-text-compact-extra-large");
 }
 
 /* Spacious density: overrides cascade to child items */
 :host([density="spacious"]) .swc-Accordion {
-  --_swc-accordion-pad-top-s: token("component-padding-vertical-100");
-  --_swc-accordion-pad-top-m: token("component-padding-vertical-200");
-
-  /* spacing-300 (16px) used here as component-padding-vertical tops out at 300 (13px); switch to a component-padding-vertical token once a higher scale is added */
-  --_swc-accordion-pad-top-l: token("spacing-300");
-  --_swc-accordion-pad-top-xl: token("spacing-300");
-  --_swc-accordion-pad-bottom-s: token("component-padding-vertical-100");
-  --_swc-accordion-pad-bottom-m: token("component-padding-vertical-200");
-  --_swc-accordion-pad-bottom-l: token("spacing-300");
-  --_swc-accordion-pad-bottom-xl: token("spacing-300");
+  --_swc-accordion-pad-top-s: token("accordion-top-to-text-spacious-small");
+  --_swc-accordion-pad-top-m: token("accordion-top-to-text-spacious-medium");
+  --_swc-accordion-pad-top-l: token("accordion-top-to-text-spacious-large");
+  --_swc-accordion-pad-top-xl: token("accordion-top-to-text-spacious-extra-large");
+  --_swc-accordion-pad-bottom-s: token("accordion-bottom-to-text-spacious-small");
+  --_swc-accordion-pad-bottom-m: token("accordion-bottom-to-text-spacious-medium");
+  --_swc-accordion-pad-bottom-l: token("accordion-bottom-to-text-spacious-large");
+  --_swc-accordion-pad-bottom-xl: token("accordion-bottom-to-text-spacious-extra-large");
 }
 
 /* Quiet: removes dividers and rounds header corners (visible on hover and focus) */