From 9f418f74dc6d3ca667f04ba40d5651afad22269c Mon Sep 17 00:00:00 2001
From: Nikki Massaro <massaro@adobe.com>
Date: Wed, 8 Jul 2026 11:03:12 -0400
Subject: [PATCH 1/5] docs(icon): accessibility migration plan

---
 2nd-gen/packages/swc/.storybook/preview.ts    |   7 +-
 .../03_components/README.md                   |   2 +
 .../icon/accessibility-migration-analysis.md  | 197 ++++++++++++++++++
 .../03_project-planning/README.md             |   1 +
 4 files changed, 203 insertions(+), 4 deletions(-)
 create mode 100644 CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md

diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts
index 3750c3951ff..917f5e62205 100644
--- a/2nd-gen/packages/swc/.storybook/preview.ts
+++ b/2nd-gen/packages/swc/.storybook/preview.ts
@@ -422,6 +422,8 @@ const preview = {
                 ],
                 'Help text',
                 ['Rendering and styling migration analysis'],
+                'Icon',
+                ['Accessibility migration analysis'],
                 'Illustrated message',
                 [
                   'Accessibility migration analysis',
@@ -523,10 +525,7 @@ const preview = {
                   'Rendering and styling migration analysis',
                 ],
                 'Toast',
-                [
-                  'Accessibility migration analysis',
-                  'Rendering and styling migration analysis',
-                ],
+                ['Accessibility migration analysis'],
                 'Tooltip',
                 [
                   'Accessibility migration analysis',
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
index dd969c79971..071461d98c4 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
@@ -82,6 +82,8 @@
     - [Grid migration roadmap](grid/rendering-and-styling-migration-analysis.md)
 - Help Text
     - [Help text migration roadmap](help-text/rendering-and-styling-migration-analysis.md)
+- Icon
+    - [Icon accessibility migration analysis](icon/accessibility-migration-analysis.md)
 - Illustrated Message
     - [Illustrated message accessibility migration analysis](illustrated-message/accessibility-migration-analysis.md)
     - [`sp-illustrated-message` Migration Plan](illustrated-message/migration-plan.md)
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
new file mode 100644
index 00000000000..11875a6626c
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
@@ -0,0 +1,197 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Components](../README.md) / Icon / Icon accessibility migration analysis
+
+<!-- Document title (editable) -->
+
+# Icon accessibility migration analysis
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [Overview](#overview)
+    - [Also read](#also-read)
+    - [What an icon is](#what-an-icon-is)
+    - [What it is not](#what-it-is-not)
+    - [Related](#related)
+- [ARIA and WCAG context](#aria-and-wcag-context)
+    - [Pattern in the APG](#pattern-in-the-apg)
+    - [Guidelines that apply](#guidelines-that-apply)
+- [Related 1st-gen accessibility (Jira)](#related-1st-gen-accessibility-jira)
+- [Recommendations: `<swc-icon>`](#recommendations-swc-icon)
+    - [ARIA roles, states, and properties](#aria-roles-states-and-properties)
+    - [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)
+- [Testing](#testing)
+    - [Automated tests](#automated-tests)
+    - [Manual screen reader testing](#manual-screen-reader-testing)
+- [Summary checklist](#summary-checklist)
+- [References](#references)
+
+</details>
+
+<!-- Document content (editable) -->
+
+## Overview
+
+This document covers the accessibility requirements and recommendations for **`<swc-icon>`**, the 2nd-gen generic SVG wrapper frame. The target standard is **WCAG 2.2 Level AA**.
+
+`<swc-icon>` accepts an SVG in its default slot and controls whether that SVG is exposed to assistive technology (meaningful) or hidden from it (decorative). Per-icon workflow elements such as `<swc-icon-star>` extend the same base class (`IconBase`) and inherit the same accessibility behavior.
+
+### Also read
+
+[Icon migration roadmap](./rendering-and-styling-migration-analysis.md) for layout, CSS, and DOM changes.
+
+### What an icon is
+
+`<swc-icon>` is a **non-interactive SVG wrapper**. It operates in one of two modes:
+
+- **Decorative** (no `label`): the common case. The icon is inside an already-labeled control such as a button or menu item. Both host and SVG receive `aria-hidden="true"` so the icon does not generate a duplicate announcement.
+- **Meaningful** (with `label`): the icon stands alone as content. The slotted SVG is exposed as an image with the `label` value as its accessible name.
+
+### What it is not
+
+- A button, link, or interactive element. To add click behavior to an icon, wrap it in `<swc-button>` or another interactive control; do not add event listeners directly to `<swc-icon>`.
+- A font icon or CSS pseudo-element. It renders real SVG markup.
+- A replacement for per-icon workflow elements (`<swc-icon-star>`, etc.), which are the preferred approach for Spectrum workflow icons and extend the same base class.
+
+### Related
+
+- **Per-icon workflow elements** (`<swc-icon-star>`, etc.): generated wrappers that share `IconBase`; accessibility behavior is identical to `<swc-icon>`.
+- **UI icon functions** (internal): consumed directly by components such as `<swc-button>` and `<swc-menu-item>`; not slotted by authors.
+
+---
+
+## ARIA and WCAG context
+
+### Pattern in the APG
+
+The [APG](https://www.w3.org/WAI/ARIA/apg/) does not define a named pattern for a generic SVG icon wrapper. Relevant guidance comes from the APG's treatment of images and decorative content:
+
+- A **decorative** icon inside an already-labeled control must be hidden from assistive technology to prevent duplicate announcement.
+- A **standalone meaningful** icon needs `role="img"` and an accessible name (`aria-label`), because SVG elements do not have a reliable implicit ARIA role across all browsers and assistive technologies.
+- A **custom element** has no implicit ARIA role; `role="img"` must be applied explicitly to the element that carries the semantics.
+
+### Guidelines that apply
+
+| Idea | Plain meaning |
+|------|---------------|
+| [Non-text content (WCAG 1.1.1)](https://www.w3.org/TR/WCAG22/#non-text-content) | Every meaningful image needs a text alternative. Decorative images must be hidden from assistive technology. |
+| [Use of color (WCAG 1.4.1)](https://www.w3.org/TR/WCAG22/#use-of-color) | Color alone must not convey meaning. The accessible name, not the icon's color, must carry semantic intent. |
+| [Contrast — minimum (WCAG 1.4.3)](https://www.w3.org/TR/WCAG22/#contrast-minimum) | Text rendered inside SVG must meet 4.5:1 against its background. |
+| [Non-text contrast (WCAG 1.4.11)](https://www.w3.org/TR/WCAG22/#non-text-contrast) | The icon fill must meet 3:1 contrast against the adjacent background for UI components. |
+
+**Bottom line:** Every `<swc-icon>` is either explicitly decorative (hidden) or explicitly meaningful (named). Leaving `label` empty when an icon is the sole communication of meaning is an author error that fails WCAG 1.1.1.
+
+---
+
+## Related 1st-gen accessibility (Jira)
+
+| Jira | Type | Status (snapshot) | Resolution (snapshot) | Summary |
+|------|------|-------------------|------------------------|---------|
+| [SWC-875](https://jira.corp.adobe.com/browse/SWC-875) | Epic | Done | Fixed | Update icon components for accessibility |
+| [SWC-1337](https://jira.corp.adobe.com/browse/SWC-1337) | Bug | To Do | Unresolved | Different icons depending on import path — may deliver different SVG shapes, which changes what assistive technology announces |
+
+---
+
+## Recommendations: `<swc-icon>`
+
+### ARIA roles, states, and properties
+
+| Topic | What to do |
+|-------|------------|
+| **One semantic role** | `<swc-icon>` represents one thing: a static SVG image or a decorative glyph. **Do not** set `role="button"`, `role="link"`, or any interactive role on the host. For icon buttons, wrap `<swc-icon>` inside `<swc-button>` or a native `<button>`. |
+| **Host element role** | The host carries no explicit ARIA role; it is a transparent custom-element container. The slotted SVG in the light DOM is the semantic anchor for meaningful icons. This implementation differs from the RFC's stated "host owns semantics" intent: `role="img"` and `aria-label` are applied to the SVG rather than the host. Both approaches produce a correct accessibility tree; the SVG-centric approach avoids needing a separate step to hide the SVG when the host carries the role. The ARIA snapshot confirms the correct outcome: `img "Search"`. |
+| **Decorative (no `label`)** | `updateHostAccessibility()` sets `aria-hidden="true"` on the host. `updateSlottedIcon()` sets `aria-hidden="true"` on the SVG and removes `aria-label`. Both are hidden. This is the default and the common case. |
+| **Meaningful (with `label`)** | `updateSlottedIcon()` sets `role="img"` and `aria-label` equal to the `label` value on the SVG, then removes `aria-hidden` from the SVG. `updateHostAccessibility()` removes `aria-hidden` from the host. The host becomes a transparent container; the SVG carries the role and name. |
+| **Label is authoritative** | `updateSlottedIcon()` overwrites whatever ARIA attributes the slotted SVG already carries. If an icon function emits its own `aria-label` or `role`, the frame replaces them with the host's `label` value (or hides them when `label` is empty). This resolves the RFC's "A11y suppression mechanism" open question via overwrite-on-slot. |
+| **`size`** | Visual only. Not mapped to any ARIA state or property. |
+| **CSS custom properties** | `--swc-icon-color`, `--swc-icon-inline-size`, `--swc-icon-block-size` are visual only. No ARIA mapping. |
+| **Docs expectation** | Document that `label` is required when `<swc-icon>` is used as standalone content. Document that `size` and color properties carry no ARIA meaning. Do not list Tab, Space, or Enter as valid icon keys. |
+
+### Shadow DOM and cross-root ARIA Issues
+
+None. The slotted SVG is in the light DOM. ARIA attributes are set directly on it via `querySelector` within `updateSlottedIcon()`. No `aria-labelledby` or `aria-describedby` ID references cross shadow boundaries. `<swc-icon>` is not a form-associated element.
+
+### Accessibility tree expectations
+
+**Decorative icon (no `label`)**
+
+Host has `aria-hidden="true"` and is not in the accessibility tree. The SVG also has `aria-hidden="true"`. Assistive technology sees nothing for this element.
+
+**Meaningful icon (with `label`)**
+
+Host has no `aria-hidden` and no explicit role; it is a transparent container. The SVG has `role="img"` and `aria-label="<label value>"`. Assistive technology announces the image node with the label.
+
+Confirmed by `icon.a11y.spec.ts`:
+
+```
+- img "Search"
+```
+
+**Sizes story (`icon.a11y.spec.ts`):**
+
+```
+- img "Extra-small"
+- img "Small"
+- img "Medium"
+- img "Large"
+- img "Extra-large"
+```
+
+**Icon inside a labeled control (most common case)**
+
+When `<swc-icon>` is slotted inside a `<swc-button label="Close">`, the button owns the accessible name. The icon should have no `label` (decorative); the button label covers the announcement. Setting a `label` on the icon here produces redundant speech.
+
+### Keyboard and focus
+
+**Not focusable.** Keyboard navigation should skip this component and move to the next focusable element.
+
+---
+
+## Testing
+
+### Automated tests
+
+| Kind of test | What to check |
+|--------------|---------------|
+| **Unit (Storybook play functions)** | `SlottedSvgAccessibilityTest`: slotted SVG has `role="img"` and `aria-label` matching `label`. `NoLabelAriaHiddenTest`: both host and SVG have `aria-hidden="true"` when `label` is empty. `LabelTogglingTest`: ARIA attributes update correctly when `label` changes at runtime. |
+| **Playwright ARIA snapshots (`icon.a11y.spec.ts`)** | Labeled icons expose as `img "<label text>"`. Sizes story: each icon exposes with its size-appropriate label. |
+| **aXe + Storybook test-runner** | WCAG 2.x rules on icon stories. Decorative-only story instances must include a `label` to avoid name-required violations, or the story must be scoped to a context where the icon is already inside a labeled parent. |
+| **Color contrast** | Icon fill meets 3:1 against background per WCAG 1.4.11. Verify across semantic color variants and static-color stories. |
+
+### Manual screen reader testing
+
+`<swc-icon>` is not keyboard focusable. Screen reader users encounter it in **browse mode** (document or scan mode), not via Tab navigation. Manual testers must use browse mode to verify that meaningful icons announce their name, role, and state in reading order, and that decorative icons are silent.
+
+See the **Browse mode (document/scan mode)** section of the [2nd-gen Storybook screen reader testing guide](../../../../2nd-gen/packages/swc/.storybook/guides/accessibility-guides/screen_reader_testing.mdx) for setup and testing steps.
+
+---
+
+## Summary checklist
+
+- [ ] Decorative icons (no `label`) have `aria-hidden="true"` on both host and SVG.
+- [ ] Meaningful icons (`label` set) expose the slotted SVG as `img "<label value>"` in the accessibility tree.
+- [ ] `label` changes at runtime update ARIA attributes on both host and SVG correctly.
+- [ ] No ARIA role is set on the host; `role="img"` lives on the slotted SVG in the light DOM.
+- [ ] `<swc-icon>` is not in the Tab order; focus moves to the next focusable element.
+- [ ] `size` and CSS custom properties are documented as visual-only (no ARIA mapping).
+- [ ] ARIA snapshot tests (`icon.a11y.spec.ts`) cover labeled icons in the overview, anatomy, and sizes stories.
+- [ ] Manual screen reader testing uses browse mode per the Storybook guide.
+- [ ] aXe runs on icon stories; all story instances either include a `label` or are inside a labeled parent.
+- [ ] Per-icon workflow elements (`<swc-icon-star>`, etc.) share `IconBase` and are covered by the same test assertions.
+
+---
+
+## References
+
+- [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/)
+- [Non-text content (WCAG 1.1.1)](https://www.w3.org/TR/WCAG22/#non-text-content)
+- [Non-text contrast (WCAG 1.4.11)](https://www.w3.org/TR/WCAG22/#non-text-contrast)
+- [Icon migration roadmap](./rendering-and-styling-migration-analysis.md)
+- [2nd-gen Storybook: Screen reader testing](../../../../2nd-gen/packages/swc/.storybook/guides/accessibility-guides/screen_reader_testing.mdx)
diff --git a/CONTRIBUTOR-DOCS/03_project-planning/README.md b/CONTRIBUTOR-DOCS/03_project-planning/README.md
index f8ecf7844c4..a62e8d523bb 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/README.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/README.md
@@ -47,6 +47,7 @@
     - Field Label
     - Grid
     - Help Text
+    - Icon
     - Illustrated Message
     - Infield Button
     - Infield Progress Circle

From c887de4361c7b646323d927fb54b59edf82c37b3 Mon Sep 17 00:00:00 2001
From: Nikki Massaro <massaro@adobe.com>
Date: Wed, 8 Jul 2026 11:21:40 -0400
Subject: [PATCH 2/5] chore: updated a11y migration analysis skill to include
 an updated PR description template

---
 .../accessibility-migration-analysis/SKILL.md  | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/.ai/skills/accessibility-migration-analysis/SKILL.md b/.ai/skills/accessibility-migration-analysis/SKILL.md
index 7e305f52c75..0e0c7e0f4d4 100644
--- a/.ai/skills/accessibility-migration-analysis/SKILL.md
+++ b/.ai/skills/accessibility-migration-analysis/SKILL.md
@@ -246,20 +246,16 @@ In the **body**, point to the **Browse mode (document/scan mode)** section. Add
 
 ## Pull request
 
-When the analysis doc is complete and ready for review, generate a GitHub PR description using the template below.
+When the analysis doc is complete and ready for review, generate a GitHub PR description using the template below. Always output the filled-in description inside a single fenced `markdown` code block so the user can copy it in one action.
 
 ### Variable substitution rules
 
-| Placeholder                                | Value                                                                 | Example                          |
-| ------------------------------------------ | --------------------------------------------------------------------- | -------------------------------- |
-| `{{component-name}}`                       | Package name, kebab-case                                              | `dropzone`, `picker-button`      |
-| `{{branch-name}}`                          | GitHub branch, format `<username>/swc-<jira-number>-<component>-a11y` | `nikkimk/swc-2146-dropzone-a11y` |
-| `{{component-a11y-migration-JIRA-ticket}}` | Jira ID for this component's a11y migration analysis ticket           | `SWC-2146`                       |
-| `{{component-readable-name}}`              | Human-readable name, first letter capitalized                         | `Dropzone`, `Color handle`       |
-
-The description's first bullet ends "for the 2nd-gen color handle" in the source template — replace "color handle" with `{{component-readable-name}}` when filling in.
-
-The Manual review test cases section contains a fixed reference to the color handle PR (`nikkimk/swc-2138-color-handle-a11y`). Keep that reference as-is; it is an anchor PR that all reviewers in this migration wave are expected to read.
+| Placeholder                                | Value                                                                 | Example                 |
+| ------------------------------------------ | --------------------------------------------------------------------- | ----------------------- |
+| `{{component-name}}`                       | Package name, kebab-case                                              | `icon`, `picker-button` |
+| `{{branch-name}}`                          | GitHub branch, format `<username>/swc-<jira-number>-<component>-a11y` | `nikkimk/icon-a11y`     |
+| `{{component-a11y-migration-JIRA-ticket}}` | Jira ID for this component's a11y migration analysis ticket           | `SWC-2146`              |
+| `{{component-readable-name}}`              | Human-readable name, first letter capitalized                         | `Icon`, `Color handle`  |
 
 ### PR settings
 

From 11332ab9af03e31159a8176d020009224061fbeb Mon Sep 17 00:00:00 2001
From: Nikki Massaro <massaro@adobe.com>
Date: Wed, 8 Jul 2026 11:25:57 -0400
Subject: [PATCH 3/5] docs(icon): a11y migration plan updated to include
 workflow icons

---
 .../icon/accessibility-migration-analysis.md  | 96 ++++++++++++-------
 1 file changed, 61 insertions(+), 35 deletions(-)

diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
index 11875a6626c..066ed7b2c2f 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
@@ -13,14 +13,15 @@
 
 - [Overview](#overview)
     - [Also read](#also-read)
-    - [What an icon is](#what-an-icon-is)
+    - [The generic frame (`swc-icon`)](#the-generic-frame-swc-icon)
+    - [Per-icon workflow elements](#per-icon-workflow-elements)
     - [What it is not](#what-it-is-not)
     - [Related](#related)
 - [ARIA and WCAG context](#aria-and-wcag-context)
     - [Pattern in the APG](#pattern-in-the-apg)
     - [Guidelines that apply](#guidelines-that-apply)
 - [Related 1st-gen accessibility (Jira)](#related-1st-gen-accessibility-jira)
-- [Recommendations: `<swc-icon>`](#recommendations-swc-icon)
+- [Recommendations: `<swc-icon>` and workflow icons](#recommendations-swc-icon-and-workflow-icons)
     - [ARIA roles, states, and properties](#aria-roles-states-and-properties)
     - [Shadow DOM and cross-root ARIA Issues](#shadow-dom-and-cross-root-aria-issues)
     - [Accessibility tree expectations](#accessibility-tree-expectations)
@@ -37,31 +38,36 @@
 
 ## Overview
 
-This document covers the accessibility requirements and recommendations for **`<swc-icon>`**, the 2nd-gen generic SVG wrapper frame. The target standard is **WCAG 2.2 Level AA**.
-
-`<swc-icon>` accepts an SVG in its default slot and controls whether that SVG is exposed to assistive technology (meaningful) or hidden from it (decorative). Per-icon workflow elements such as `<swc-icon-star>` extend the same base class (`IconBase`) and inherit the same accessibility behavior.
+This document covers the accessibility requirements and recommendations for **`<swc-icon>`** (the generic SVG frame) and **per-icon workflow elements** such as `<swc-icon-star>`. Both are built on `IconBase` and share identical ARIA behavior. The target standard is **WCAG 2.2 Level AA**.
 
 ### Also read
 
 [Icon migration roadmap](./rendering-and-styling-migration-analysis.md) for layout, CSS, and DOM changes.
 
-### What an icon is
+### The generic frame (`swc-icon`)
 
-`<swc-icon>` is a **non-interactive SVG wrapper**. It operates in one of two modes:
+`<swc-icon>` accepts an SVG in its default slot and controls whether that SVG is exposed to assistive technology or hidden from it:
 
 - **Decorative** (no `label`): the common case. The icon is inside an already-labeled control such as a button or menu item. Both host and SVG receive `aria-hidden="true"` so the icon does not generate a duplicate announcement.
 - **Meaningful** (with `label`): the icon stands alone as content. The slotted SVG is exposed as an image with the `label` value as its accessible name.
 
+### Per-icon workflow elements
+
+Per-icon workflow elements (`<swc-icon-star>`, `<swc-icon-folder>`, etc.) extend `IconBase` and bake their SVG content in during element definition rather than accepting it via slot. From an accessibility standpoint, the behavior is identical to `<swc-icon>`:
+
+- `label` absent → decorative, both host and SVG are hidden.
+- `label` present → meaningful, SVG exposes as `img` with the label as its accessible name.
+
+One authoring difference matters for accessibility: **the element tag name describes shape, not function.** `<swc-icon-star>` tells the browser what shape to render; it says nothing about why the icon is there. The `label` must describe the function in context — `label="Add to favorites"`, not `label="Star"`. Decorative use (inside a labeled button) requires no `label` at all.
+
 ### What it is not
 
-- A button, link, or interactive element. To add click behavior to an icon, wrap it in `<swc-button>` or another interactive control; do not add event listeners directly to `<swc-icon>`.
-- A font icon or CSS pseudo-element. It renders real SVG markup.
-- A replacement for per-icon workflow elements (`<swc-icon-star>`, etc.), which are the preferred approach for Spectrum workflow icons and extend the same base class.
+- A button, link, or interactive element. To add click behavior to an icon, wrap it in `<swc-button>` or another interactive control; do not add event listeners directly to `<swc-icon>` or a per-icon workflow element.
+- A font icon or CSS pseudo-element. Both element types render real SVG markup.
 
 ### Related
 
-- **Per-icon workflow elements** (`<swc-icon-star>`, etc.): generated wrappers that share `IconBase`; accessibility behavior is identical to `<swc-icon>`.
-- **UI icon functions** (internal): consumed directly by components such as `<swc-button>` and `<swc-menu-item>`; not slotted by authors.
+- **UI icon functions** (internal): consumed directly by components such as `<swc-button>` and `<swc-menu-item>`; not used by authors. Accessibility is component-controlled.
 
 ---
 
@@ -84,7 +90,7 @@ The [APG](https://www.w3.org/WAI/ARIA/apg/) does not define a named pattern for
 | [Contrast — minimum (WCAG 1.4.3)](https://www.w3.org/TR/WCAG22/#contrast-minimum) | Text rendered inside SVG must meet 4.5:1 against its background. |
 | [Non-text contrast (WCAG 1.4.11)](https://www.w3.org/TR/WCAG22/#non-text-contrast) | The icon fill must meet 3:1 contrast against the adjacent background for UI components. |
 
-**Bottom line:** Every `<swc-icon>` is either explicitly decorative (hidden) or explicitly meaningful (named). Leaving `label` empty when an icon is the sole communication of meaning is an author error that fails WCAG 1.1.1.
+**Bottom line:** Every icon element — `<swc-icon>` or a per-icon workflow element — is either explicitly decorative (hidden) or explicitly meaningful (named). Leaving `label` empty when an icon is the sole communication of meaning is an author error that fails WCAG 1.1.1.
 
 ---
 
@@ -97,20 +103,22 @@ The [APG](https://www.w3.org/WAI/ARIA/apg/) does not define a named pattern for
 
 ---
 
-## Recommendations: `<swc-icon>`
+## Recommendations: `<swc-icon>` and workflow icons
 
 ### ARIA roles, states, and properties
 
 | Topic | What to do |
 |-------|------------|
-| **One semantic role** | `<swc-icon>` represents one thing: a static SVG image or a decorative glyph. **Do not** set `role="button"`, `role="link"`, or any interactive role on the host. For icon buttons, wrap `<swc-icon>` inside `<swc-button>` or a native `<button>`. |
-| **Host element role** | The host carries no explicit ARIA role; it is a transparent custom-element container. The slotted SVG in the light DOM is the semantic anchor for meaningful icons. This implementation differs from the RFC's stated "host owns semantics" intent: `role="img"` and `aria-label` are applied to the SVG rather than the host. Both approaches produce a correct accessibility tree; the SVG-centric approach avoids needing a separate step to hide the SVG when the host carries the role. The ARIA snapshot confirms the correct outcome: `img "Search"`. |
-| **Decorative (no `label`)** | `updateHostAccessibility()` sets `aria-hidden="true"` on the host. `updateSlottedIcon()` sets `aria-hidden="true"` on the SVG and removes `aria-label`. Both are hidden. This is the default and the common case. |
+| **One semantic role** | Both `<swc-icon>` and per-icon workflow elements represent one thing: a static SVG image or a decorative glyph. **Do not** set `role="button"`, `role="link"`, or any interactive role on the host. For icon buttons, wrap inside `<swc-button>` or a native `<button>`. |
+| **Host element role** | The host carries no explicit ARIA role; it is a transparent custom-element container. The SVG is the semantic anchor for meaningful icons. This differs from the RFC's stated "host owns semantics" intent: `role="img"` and `aria-label` are applied to the SVG rather than the host. Both approaches produce a correct accessibility tree; the SVG-centric approach avoids needing a separate step to hide the SVG. The ARIA snapshot confirms the correct outcome: `img "Search"`. |
+| **Decorative (no `label`)** | `updateHostAccessibility()` sets `aria-hidden="true"` on the host. `updateSlottedIcon()` sets `aria-hidden="true"` on the SVG and removes `aria-label`. Both are hidden. This is the default and the most common case. |
 | **Meaningful (with `label`)** | `updateSlottedIcon()` sets `role="img"` and `aria-label` equal to the `label` value on the SVG, then removes `aria-hidden` from the SVG. `updateHostAccessibility()` removes `aria-hidden` from the host. The host becomes a transparent container; the SVG carries the role and name. |
-| **Label is authoritative** | `updateSlottedIcon()` overwrites whatever ARIA attributes the slotted SVG already carries. If an icon function emits its own `aria-label` or `role`, the frame replaces them with the host's `label` value (or hides them when `label` is empty). This resolves the RFC's "A11y suppression mechanism" open question via overwrite-on-slot. |
+| **Label is authoritative** | `updateSlottedIcon()` overwrites whatever ARIA attributes the SVG already carries. If an icon function emits its own `aria-label` or `role`, the frame replaces them with the host's `label` value (or hides them when `label` is empty). This resolves the RFC's "A11y suppression mechanism" open question via overwrite-on-slot. |
+| **Per-icon element SVG source** | Per-icon workflow elements bake their SVG during element definition rather than accepting it via slot. `updateSlottedIcon()` still runs via `firstUpdated`, so the same ARIA attributes are applied to the baked SVG. No separate handling is needed. |
+| **Workflow icon label content** | The element tag name describes shape, not function. `<swc-icon-star>` says nothing about why the icon is present. When the icon is meaningful, `label` must describe the function in context: `label="Add to favorites"`, not `label="Star"`. When the icon is decorative (inside a labeled button), omit `label` entirely. |
 | **`size`** | Visual only. Not mapped to any ARIA state or property. |
 | **CSS custom properties** | `--swc-icon-color`, `--swc-icon-inline-size`, `--swc-icon-block-size` are visual only. No ARIA mapping. |
-| **Docs expectation** | Document that `label` is required when `<swc-icon>` is used as standalone content. Document that `size` and color properties carry no ARIA meaning. Do not list Tab, Space, or Enter as valid icon keys. |
+| **Docs expectation** | Document that `label` is required when any icon element is used as standalone content, and that `label` should describe function in context, not icon shape. Document that `size` and color properties carry no ARIA meaning. Do not list Tab, Space, or Enter as valid icon keys. |
 
 ### Shadow DOM and cross-root ARIA Issues
 
@@ -120,21 +128,21 @@ None. The slotted SVG is in the light DOM. ARIA attributes are set directly on i
 
 **Decorative icon (no `label`)**
 
-Host has `aria-hidden="true"` and is not in the accessibility tree. The SVG also has `aria-hidden="true"`. Assistive technology sees nothing for this element.
+Host has `aria-hidden="true"` and is not in the accessibility tree. The SVG also has `aria-hidden="true"`. Assistive technology sees nothing for this element. Applies to both `<swc-icon>` and per-icon workflow elements.
 
-**Meaningful icon (with `label`)**
+**Meaningful `<swc-icon>` (with `label`)**
 
 Host has no `aria-hidden` and no explicit role; it is a transparent container. The SVG has `role="img"` and `aria-label="<label value>"`. Assistive technology announces the image node with the label.
 
 Confirmed by `icon.a11y.spec.ts`:
 
-```
+```text
 - img "Search"
 ```
 
 **Sizes story (`icon.a11y.spec.ts`):**
 
-```
+```text
 - img "Extra-small"
 - img "Small"
 - img "Medium"
@@ -142,9 +150,25 @@ Confirmed by `icon.a11y.spec.ts`:
 - img "Extra-large"
 ```
 
+**Meaningful workflow icon (with `label`)**
+
+Per-icon workflow elements produce the same tree shape. The baked SVG carries `role="img"` and `aria-label` via `updateSlottedIcon()`.
+
+Expected for `<swc-icon-star label="Add to favorites">`:
+
+```text
+- img "Add to favorites"
+```
+
+Expected for `<swc-icon-folder label="Open project">`:
+
+```text
+- img "Open project"
+```
+
 **Icon inside a labeled control (most common case)**
 
-When `<swc-icon>` is slotted inside a `<swc-button label="Close">`, the button owns the accessible name. The icon should have no `label` (decorative); the button label covers the announcement. Setting a `label` on the icon here produces redundant speech.
+When any icon element is slotted inside a `<swc-button label="Close">`, the button owns the accessible name. The icon should have no `label` (decorative); the button label covers the announcement. Setting a `label` on the icon here produces redundant speech.
 
 ### Keyboard and focus
 
@@ -158,10 +182,11 @@ When `<swc-icon>` is slotted inside a `<swc-button label="Close">`, the button o
 
 | Kind of test | What to check |
 |--------------|---------------|
-| **Unit (Storybook play functions)** | `SlottedSvgAccessibilityTest`: slotted SVG has `role="img"` and `aria-label` matching `label`. `NoLabelAriaHiddenTest`: both host and SVG have `aria-hidden="true"` when `label` is empty. `LabelTogglingTest`: ARIA attributes update correctly when `label` changes at runtime. |
-| **Playwright ARIA snapshots (`icon.a11y.spec.ts`)** | Labeled icons expose as `img "<label text>"`. Sizes story: each icon exposes with its size-appropriate label. |
-| **aXe + Storybook test-runner** | WCAG 2.x rules on icon stories. Decorative-only story instances must include a `label` to avoid name-required violations, or the story must be scoped to a context where the icon is already inside a labeled parent. |
-| **Color contrast** | Icon fill meets 3:1 against background per WCAG 1.4.11. Verify across semantic color variants and static-color stories. |
+| **Unit (Storybook play functions, `swc-icon`)** | `SlottedSvgAccessibilityTest`: slotted SVG has `role="img"` and `aria-label` matching `label`. `NoLabelAriaHiddenTest`: both host and SVG have `aria-hidden="true"` when `label` is empty. `LabelTogglingTest`: ARIA attributes update correctly when `label` changes at runtime. |
+| **Unit (Storybook play functions, workflow icons)** | Per-icon elements follow the same pattern. Verify that the baked SVG receives `role="img"` and `aria-label` when `label` is set, and `aria-hidden="true"` when `label` is empty. |
+| **Playwright ARIA snapshots (`icon.a11y.spec.ts`)** | `<swc-icon>` labeled stories expose as `img "<label text>"`. Sizes story: each size exposes with its label. Workflow icon stories: each labeled element exposes as `img` with the function-describing label (not the shape name). |
+| **aXe + Storybook test-runner** | WCAG 2.x rules on all icon stories. Decorative-only instances must be inside a labeled parent; standalone icons must have `label` set. |
+| **Color contrast** | Icon fill meets 3:1 against background per WCAG 1.4.11. Verify across color variants and static-color stories for both `<swc-icon>` and workflow icon stories. |
 
 ### Manual screen reader testing
 
@@ -173,16 +198,17 @@ See the **Browse mode (document/scan mode)** section of the [2nd-gen Storybook s
 
 ## Summary checklist
 
-- [ ] Decorative icons (no `label`) have `aria-hidden="true"` on both host and SVG.
-- [ ] Meaningful icons (`label` set) expose the slotted SVG as `img "<label value>"` in the accessibility tree.
+- [ ] Decorative icons (no `label`) have `aria-hidden="true"` on both host and SVG — applies to `<swc-icon>` and all per-icon workflow elements.
+- [ ] Meaningful icons (`label` set) expose the SVG as `img "<label value>"` in the accessibility tree.
 - [ ] `label` changes at runtime update ARIA attributes on both host and SVG correctly.
-- [ ] No ARIA role is set on the host; `role="img"` lives on the slotted SVG in the light DOM.
-- [ ] `<swc-icon>` is not in the Tab order; focus moves to the next focusable element.
+- [ ] No ARIA role is set on the host; `role="img"` lives on the SVG (light DOM for `<swc-icon>`, baked SVG for per-icon elements).
+- [ ] Icon elements are not in the Tab order; focus moves to the next focusable element.
 - [ ] `size` and CSS custom properties are documented as visual-only (no ARIA mapping).
-- [ ] ARIA snapshot tests (`icon.a11y.spec.ts`) cover labeled icons in the overview, anatomy, and sizes stories.
+- [ ] Workflow icon `label` values describe function in context (`"Add to favorites"`), not icon shape (`"Star"`); this is documented for authors.
+- [ ] ARIA snapshot tests (`icon.a11y.spec.ts`) cover labeled `<swc-icon>` stories (overview, anatomy, sizes).
+- [ ] ARIA snapshot tests for per-icon workflow elements verify `img "<function-label>"` for each labeled story.
 - [ ] Manual screen reader testing uses browse mode per the Storybook guide.
-- [ ] aXe runs on icon stories; all story instances either include a `label` or are inside a labeled parent.
-- [ ] Per-icon workflow elements (`<swc-icon-star>`, etc.) share `IconBase` and are covered by the same test assertions.
+- [ ] aXe runs on all icon stories; every standalone icon instance has a `label`, or is inside a labeled parent.
 
 ---
 

From 386925b3a0b9646f519e77b695e6dbf1ecc6ff96 Mon Sep 17 00:00:00 2001
From: Nikki Massaro <massaro@adobe.com>
Date: Wed, 8 Jul 2026 12:29:19 -0400
Subject: [PATCH 4/5] docs(icon): updated to note that the icon is typically
 decorative

---
 .../03_components/icon/accessibility-migration-analysis.md    | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
index 066ed7b2c2f..8258f03f289 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
@@ -58,7 +58,9 @@ Per-icon workflow elements (`<swc-icon-star>`, `<swc-icon-folder>`, etc.) extend
 - `label` absent → decorative, both host and SVG are hidden.
 - `label` present → meaningful, SVG exposes as `img` with the label as its accessible name.
 
-One authoring difference matters for accessibility: **the element tag name describes shape, not function.** `<swc-icon-star>` tells the browser what shape to render; it says nothing about why the icon is there. The `label` must describe the function in context — `label="Add to favorites"`, not `label="Star"`. Decorative use (inside a labeled button) requires no `label` at all.
+One authoring difference matters for accessibility: **the element tag name describes shape, not function.** `<swc-icon-star>` tells the browser what shape to render; it says nothing about why the icon is there.
+
+In practice, workflow icons are almost always decorative. The parent element — a `<swc-button>`, `<swc-badge>`, or menu item — carries the `label` that assistive technology announces, and the icon itself needs no `label` at all. Only set `label` on a workflow icon when it genuinely stands alone as the sole communication of meaning, with no labeled parent. In that case `label` must describe the function in context — `label="Add to favorites"`, not `label="Star"`.
 
 ### What it is not
 

From b5c0f6458053d2cc32890d94847ca707d194e826 Mon Sep 17 00:00:00 2001
From: Nikki Massaro <massaro@adobe.com>
Date: Wed, 8 Jul 2026 12:37:57 -0400
Subject: [PATCH 5/5] docs(icon): updated to reflect that icons are decorative
 by default

---
 .../icon/accessibility-migration-analysis.md  | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
index 8258f03f289..a17d8be3971 100644
--- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
+++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/icon/accessibility-migration-analysis.md
@@ -49,7 +49,7 @@ This document covers the accessibility requirements and recommendations for **`<
 `<swc-icon>` accepts an SVG in its default slot and controls whether that SVG is exposed to assistive technology or hidden from it:
 
 - **Decorative** (no `label`): the common case. The icon is inside an already-labeled control such as a button or menu item. Both host and SVG receive `aria-hidden="true"` so the icon does not generate a duplicate announcement.
-- **Meaningful** (with `label`): the icon stands alone as content. The slotted SVG is exposed as an image with the `label` value as its accessible name.
+- **Meaningful** (with `label`): an exotic, discouraged use case. Only appropriate when the icon genuinely stands alone with no ancestor providing a role and accessible name. The slotted SVG is exposed as an image with the `label` value as its accessible name.
 
 ### Per-icon workflow elements
 
@@ -60,7 +60,7 @@ Per-icon workflow elements (`<swc-icon-star>`, `<swc-icon-folder>`, etc.) extend
 
 One authoring difference matters for accessibility: **the element tag name describes shape, not function.** `<swc-icon-star>` tells the browser what shape to render; it says nothing about why the icon is there.
 
-In practice, workflow icons are almost always decorative. The parent element — a `<swc-button>`, `<swc-badge>`, or menu item — carries the `label` that assistive technology announces, and the icon itself needs no `label` at all. Only set `label` on a workflow icon when it genuinely stands alone as the sole communication of meaning, with no labeled parent. In that case `label` must describe the function in context — `label="Add to favorites"`, not `label="Star"`.
+In practice, workflow icons are almost always decorative. The parent element — a `<swc-button>`, `<swc-badge>`, or menu item — carries the `label` that assistive technology announces, and the icon itself needs no `label` at all. Standalone use of a workflow icon with `label` set is exotic and discouraged; confirm there is no viable ancestor element that can carry the role and accessible name before reaching for it. When a valid standalone use case exists, `label` must describe the function in context — `label="Add to favorites"`, not `label="Star"`.
 
 ### What it is not
 
@@ -80,7 +80,7 @@ In practice, workflow icons are almost always decorative. The parent element —
 The [APG](https://www.w3.org/WAI/ARIA/apg/) does not define a named pattern for a generic SVG icon wrapper. Relevant guidance comes from the APG's treatment of images and decorative content:
 
 - A **decorative** icon inside an already-labeled control must be hidden from assistive technology to prevent duplicate announcement.
-- A **standalone meaningful** icon needs `role="img"` and an accessible name (`aria-label`), because SVG elements do not have a reliable implicit ARIA role across all browsers and assistive technologies.
+- A **standalone meaningful** icon needs `role="img"` and an accessible name (`aria-label`), because SVG elements do not have a reliable implicit ARIA role across all browsers and assistive technologies. This pattern is technically correct but represents an exotic, discouraged use case; the strongly preferred pattern is an ancestor element that carries the role and accessible name.
 - A **custom element** has no implicit ARIA role; `role="img"` must be applied explicitly to the element that carries the semantics.
 
 ### Guidelines that apply
@@ -92,7 +92,7 @@ The [APG](https://www.w3.org/WAI/ARIA/apg/) does not define a named pattern for
 | [Contrast — minimum (WCAG 1.4.3)](https://www.w3.org/TR/WCAG22/#contrast-minimum) | Text rendered inside SVG must meet 4.5:1 against its background. |
 | [Non-text contrast (WCAG 1.4.11)](https://www.w3.org/TR/WCAG22/#non-text-contrast) | The icon fill must meet 3:1 contrast against the adjacent background for UI components. |
 
-**Bottom line:** Every icon element — `<swc-icon>` or a per-icon workflow element — is either explicitly decorative (hidden) or explicitly meaningful (named). Leaving `label` empty when an icon is the sole communication of meaning is an author error that fails WCAG 1.1.1.
+**Bottom line:** Icons should almost always be decorative, relying on an ancestor element such as `<swc-button>` or `<swc-badge>` to carry the role and accessible name. Using an icon as the sole communication of meaning — setting `label` and exposing `role="img"` with no labeled ancestor — is an exotic use case that should be discouraged unless a valid use case can be confirmed. When such a use case exists, the icon must have `label` set; leaving it empty while the icon is the only conveyance of meaning fails WCAG 1.1.1.
 
 ---
 
@@ -111,16 +111,16 @@ The [APG](https://www.w3.org/WAI/ARIA/apg/) does not define a named pattern for
 
 | Topic | What to do |
 |-------|------------|
-| **One semantic role** | Both `<swc-icon>` and per-icon workflow elements represent one thing: a static SVG image or a decorative glyph. **Do not** set `role="button"`, `role="link"`, or any interactive role on the host. For icon buttons, wrap inside `<swc-button>` or a native `<button>`. |
+| **One semantic role** | Icons are decorative by default. The parent element — `<swc-button>`, `<swc-badge>`, a menu item, or similar — carries the accessible meaning, and the icon itself should have no `label` (and therefore `aria-hidden="true"`). Only in the rare case where an icon stands completely alone, with no labeled parent providing context, does it need `label` set and `role="img"` applied to the SVG. **Do not** set `role="button"`, `role="link"`, or any interactive role on the icon host. |
 | **Host element role** | The host carries no explicit ARIA role; it is a transparent custom-element container. The SVG is the semantic anchor for meaningful icons. This differs from the RFC's stated "host owns semantics" intent: `role="img"` and `aria-label` are applied to the SVG rather than the host. Both approaches produce a correct accessibility tree; the SVG-centric approach avoids needing a separate step to hide the SVG. The ARIA snapshot confirms the correct outcome: `img "Search"`. |
 | **Decorative (no `label`)** | `updateHostAccessibility()` sets `aria-hidden="true"` on the host. `updateSlottedIcon()` sets `aria-hidden="true"` on the SVG and removes `aria-label`. Both are hidden. This is the default and the most common case. |
-| **Meaningful (with `label`)** | `updateSlottedIcon()` sets `role="img"` and `aria-label` equal to the `label` value on the SVG, then removes `aria-hidden` from the SVG. `updateHostAccessibility()` removes `aria-hidden` from the host. The host becomes a transparent container; the SVG carries the role and name. |
+| **Meaningful (with `label`)** | An exotic, discouraged use case. Before using it, confirm there is no viable ancestor element that can carry the role and accessible name. When a valid standalone use case exists: `updateSlottedIcon()` sets `role="img"` and `aria-label` equal to the `label` value on the SVG, then removes `aria-hidden` from the SVG. `updateHostAccessibility()` removes `aria-hidden` from the host. The host becomes a transparent container; the SVG carries the role and name. |
 | **Label is authoritative** | `updateSlottedIcon()` overwrites whatever ARIA attributes the SVG already carries. If an icon function emits its own `aria-label` or `role`, the frame replaces them with the host's `label` value (or hides them when `label` is empty). This resolves the RFC's "A11y suppression mechanism" open question via overwrite-on-slot. |
 | **Per-icon element SVG source** | Per-icon workflow elements bake their SVG during element definition rather than accepting it via slot. `updateSlottedIcon()` still runs via `firstUpdated`, so the same ARIA attributes are applied to the baked SVG. No separate handling is needed. |
 | **Workflow icon label content** | The element tag name describes shape, not function. `<swc-icon-star>` says nothing about why the icon is present. When the icon is meaningful, `label` must describe the function in context: `label="Add to favorites"`, not `label="Star"`. When the icon is decorative (inside a labeled button), omit `label` entirely. |
 | **`size`** | Visual only. Not mapped to any ARIA state or property. |
 | **CSS custom properties** | `--swc-icon-color`, `--swc-icon-inline-size`, `--swc-icon-block-size` are visual only. No ARIA mapping. |
-| **Docs expectation** | Document that `label` is required when any icon element is used as standalone content, and that `label` should describe function in context, not icon shape. Document that `size` and color properties carry no ARIA meaning. Do not list Tab, Space, or Enter as valid icon keys. |
+| **Docs expectation** | Document that icons should almost always be decorative and that the ancestor element carries the accessible name. Document that standalone use with `label` is exotic and discouraged; authors should confirm no ancestor can provide the role and name before using it. When standalone use is unavoidable, `label` must describe function in context, not icon shape. Document that `size` and color properties carry no ARIA meaning. Do not list Tab, Space, or Enter as valid icon keys. |
 
 ### Shadow DOM and cross-root ARIA Issues
 
@@ -132,9 +132,9 @@ None. The slotted SVG is in the light DOM. ARIA attributes are set directly on i
 
 Host has `aria-hidden="true"` and is not in the accessibility tree. The SVG also has `aria-hidden="true"`. Assistive technology sees nothing for this element. Applies to both `<swc-icon>` and per-icon workflow elements.
 
-**Meaningful `<swc-icon>` (with `label`)**
+**Meaningful `<swc-icon>` (with `label`) — exotic, discouraged use case**
 
-Host has no `aria-hidden` and no explicit role; it is a transparent container. The SVG has `role="img"` and `aria-label="<label value>"`. Assistive technology announces the image node with the label.
+Only appropriate when the icon has no ancestor providing a role and accessible name, and a valid standalone use case has been confirmed. Host has no `aria-hidden` and no explicit role; it is a transparent container. The SVG has `role="img"` and `aria-label="<label value>"`. Assistive technology announces the image node with the label.
 
 Confirmed by `icon.a11y.spec.ts`:
 
@@ -152,9 +152,9 @@ Confirmed by `icon.a11y.spec.ts`:
 - img "Extra-large"
 ```
 
-**Meaningful workflow icon (with `label`)**
+**Meaningful workflow icon (with `label`) — exotic, discouraged use case**
 
-Per-icon workflow elements produce the same tree shape. The baked SVG carries `role="img"` and `aria-label` via `updateSlottedIcon()`.
+Same guidance as above: only appropriate when no ancestor can carry the role and accessible name, and a valid use case has been confirmed. Per-icon workflow elements produce the same tree shape. The baked SVG carries `role="img"` and `aria-label` via `updateSlottedIcon()`.
 
 Expected for `<swc-icon-star label="Add to favorites">`:
 
@@ -201,14 +201,14 @@ See the **Browse mode (document/scan mode)** section of the [2nd-gen Storybook s
 ## Summary checklist
 
 - [ ] Decorative icons (no `label`) have `aria-hidden="true"` on both host and SVG — applies to `<swc-icon>` and all per-icon workflow elements.
-- [ ] Meaningful icons (`label` set) expose the SVG as `img "<label value>"` in the accessibility tree.
+- [ ] Standalone meaningful icons (`label` set) are treated as exotic use cases in docs; the strongly preferred pattern — ancestor carries the accessible name, icon is decorative — is documented and demonstrated first.
 - [ ] `label` changes at runtime update ARIA attributes on both host and SVG correctly.
 - [ ] No ARIA role is set on the host; `role="img"` lives on the SVG (light DOM for `<swc-icon>`, baked SVG for per-icon elements).
 - [ ] Icon elements are not in the Tab order; focus moves to the next focusable element.
 - [ ] `size` and CSS custom properties are documented as visual-only (no ARIA mapping).
 - [ ] Workflow icon `label` values describe function in context (`"Add to favorites"`), not icon shape (`"Star"`); this is documented for authors.
 - [ ] ARIA snapshot tests (`icon.a11y.spec.ts`) cover labeled `<swc-icon>` stories (overview, anatomy, sizes).
-- [ ] ARIA snapshot tests for per-icon workflow elements verify `img "<function-label>"` for each labeled story.
+- [ ] ARIA snapshot tests for per-icon workflow elements verify `img "<function-label>"` for any labeled standalone story; the decorative-inside-labeled-parent pattern is the primary story.
 - [ ] Manual screen reader testing uses browse mode per the Storybook guide.
 - [ ] aXe runs on all icon stories; every standalone icon instance has a `label`, or is inside a labeled parent.