accessibility-migration-analysis

# Component migration: analyze accessibility Create comprehensive accessibility documentation for the **analyze accessibility** step of gen2 component migration. One markdown file per component, following a fixed structure (ARIA context, recommendations, testing, checklist, references). Use this when **creating or updating** `accessibility-migration-analysis.md` under `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component>/`. ## Mindset You are an accessibility auditor, not a documenter. Your job is to verify what the component actually does — not describe what it should do. Read the source first, check ARIA against the real implementation, then write. Never document behavior you haven't confirmed. When source or design suggests **more than one host ARIA role** for the same component, treat that as a **design smell**: pause, **prompt the user**, and default to **one role per component** (or split into distinct components) before writing Recommendations. ## When to use this skill - You are on the "analyze accessibility" step of the gen2 component migration workstream - The user asks to create an accessibility migration analysis for one or more components - The user asks to analyze accessibility for a component (e.g. "analyze accessibility for button", "create accessibility analysis for dialog") ## How to invoke - Say "create accessibility analysis for [component]", "analyze accessibility for [component]", or "accessibility migration for [component]" - Or refer to the step "analyze accessibility" in the gen2 component migration workstream — the agent should use this skill and read the full instructions below ## Quick reference ### Output - **One markdown file per component** at: `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/accessibility-migration-analysis.md` - **Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read** - **Nav:** After adding the file or changing `##` / `###` headings, run `node update-nav.js` from `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs`. Register the doc in `03_components/README.md` when introducing a new component folder. - **Non-focusable** components: include `### Manual screen reader testing` under `## Testing` (see [Testing](#testing) in **Full instructions**), with **browse mode** and a link to `gen2/packages/swc/.storybook/guides/accessibility-guides/screen_reader_testing.mdx`. ### Reference examples (consistency) Use these existing docs when matching structure, headings, tables, and phrasing: - `CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/accessibility-migration-analysis.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/accessibility-migration-analysis.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/meter/accessibility-migration-analysis.md` (non-focusable component with `### Manual screen reader testing`—**browse mode** and Storybook guide) - `CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/accessibility-migration-analysis.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/popover/accessibility-migration-analysis.md` (subheadings for **template** subsections that **do not apply**, with **Does not apply** / **Intentionally omitted** explanations) ## File location and discovery - **Path:** `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component-name>/accessibility-migration-analysis.md` - **Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read**. - **Nav:** After adding a file or changing `##` / `###` headings, run `node update-nav.js` from `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs` (see **contributor-doc-update** rule). Register the doc in `03_components/README.md` when introducing a new component folder. - **Non-focusable** components: add `### Manual screen reader testing` (browse mode + `gen2/packages/swc/.storybook/guides/accessibility-guides/screen_reader_testing.mdx`)—see **Full instructions** under `## Testing`. ### Important - Verify behavior and ARIA in **gen2 source** before stating what the component exposes — do not document ARIA the code does not set - **React Spectrum references:** Treat **RSP** as shorthand for **React Spectrum**. When the user supplies a React Spectrum component URL such as `https://react-spectrum.adobe.com/ComponentName`, include that URL as the link in the migration document. Before using the reference, read the full API from its LLM-friendly counterpart at `https://react-spectrum.adobe.com/ComponentName.md`; use the `.md` page for research, but do not replace the user-facing component link with the `.md` URL. Apply this rule to every supplied React Spectrum component URL. - Ask clarifying questions for uncertain mappings instead of guessing - **Dual or conditional host roles:** When 1st-gen source, RSP/Figma, or migration notes show the **same component** taking **more than one host `role`** (for example `toolbar` vs `radiogroup`, or a property that swaps roles), **stop and prompt the user** before writing Recommendations. A component that legitimately serves **two or more ARIA roles** should **most likely be two distinct components**—not one element whose role changes. Do not document multiple host roles as acceptable without an explicit product decision; see [Dual or conditional ARIA roles](#dual-or-conditional-aria-roles) in **Full instructions**. - When the doc covers **progress**, **loading**, **busy**, or **spinner** UX, align guidance with Adobe’s Figma file **Loading animation discovery** ([Loading animation discovery](https://www.figma.com/design/42VzvpW262EAUbYsadO4e8/Loading-animation-discovery)); if you cite or rely on it in the doc body, **also** list that link under **`## References`** ## Full instructions ### Required section order Use this **H2** order. **Do not** skip any of these top-level **H2** blocks for the component; each must appear in the file when that analysis exists. 1. `## Overview` 2. `## ARIA and WCAG context` 3. `## Related 1st-gen accessibility (Jira)` 4. `## Recommendations: \`<swc-component-name>\`` 5. `## Testing` with `### Automated tests` and, when the component is **not focusable** in its default supported use, `### Manual screen reader testing` (see [Testing](#testing) below) 6. `## Summary checklist` 7. `## References` Under **`## Recommendations`**, use these **`###` subsections** in order: 1. `### ARIA roles, states, and properties` 2. `### Shadow DOM and cross-root ARIA Issues` 3. `### Accessibility tree expectations` 4. **Optional (when product guidance needs it):** e.g. `### Assistive technology, live regions`—place **after** accessibility tree expectations and **before** keyboard and focus. For **motion** (WCAG 2.2.2, reduced motion, Spectrum tokens), add rows to **Guidelines that apply** and the **Recommendations** table instead of a separate `### Motion` section—see **`progress-circle/accessibility-migration-analysis.md`**. For **loading / progress** design intent (variants, motion), align with Figma **Loading animation discovery** ([Loading animation discovery](https://www.figma.com/design/42VzvpW262EAUbYsadO4e8/Loading-animation-discovery)) and **list it under `## References`** whenever the contributor doc cites it. 5. `### Keyboard and focus` Separate major sections with a horizontal rule (`---`) where existing docs use it (after Overview, after ARIA and WCAG context, after Related 1st-gen accessibility (Jira) before Recommendations, after Recommendations block before Testing). ### `###` subsections that do not apply (keep the heading) The **H2** list above is mandatory. **Within Recommendations** and **Testing**, the skill and **peer** docs (for example `CONTRIBUTOR-DOCS/03_project-planning/03_components/button/accessibility-migration-analysis.md` and `popover/accessibility-migration-analysis.md`) use additional **`###` subsections**—form association, live regions, motion, extra keyboard boilerplate, Playwright or manual test expectations, and similar. - **If a template subsection does not apply** to the component, **do not delete the topic**: keep the same **`###` heading** the peer doc or this skill would use, and set the **body** to a short **Does not apply** (or **Intentionally omitted**) explanation: **what** the subsection would normally cover, and **why** it does not apply (wrong interaction model, out of scope, concern already covered only under **Guidelines that apply** or elsewhere). - This keeps the **In this doc** table of contents and **side-by-side** reading across components **aligned**, so reviewers are not left wondering whether a topic was forgotten or out of scope. - **Exception — “none” is still an answer:** A subsection that exists to record **whether** cross-root or other issues **exist** may use a **minimal body** (for example **`### Shadow DOM and cross-root ARIA Issues`** with only the word **`None`**) when the **topic** applies but the **outcome** is _no_ issue. That is **not** the same as a subsection the component **type** never needs. Use **None** for “we checked; nothing to report,” and **Does not apply** for “this subsection’s category is irrelevant to this host.” ### Overview - Start with a short paragraph: what the doc covers, **`swc-*` name**, and **WCAG 2.2 Level AA** as the target. - Use **`###` subheadings** for structured bits—**do not** use bold-only labels like `**Also read:**` as section titles. **Typical subheadings** (include what fits the component): | Subheading | Use when | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `### Also read` | Always—point at the component’s `rendering-and-styling-migration-analysis.md` (and optional related a11y docs). | | `### What it is` or `### What a <noun> is` | Always—one clear definition. | | `### When to use something else` | When authors often confuse this with another component—link to other migration or a11y docs with relative paths. When 1st-gen used **conditional host roles**, note which **gen2 component** (or outer wrapper pattern) replaces each role—after the user confirms the split or fixed role policy. | | `### What it is not` | When a common mistaken identity exists (e.g. progress ring vs in-field spinner). | | `### Related` | Optional—related components (e.g. progress bar vs progress circle). | Body text under each `###` is normal paragraphs and/or bullets. ## ARIA and WCAG context - `### Pattern in the APG` — bullets: how APG (or lack of a named pattern) relates to this widget; link to APG patterns when relevant. - `### Guidelines that apply` — a **table** with columns **`Idea`** and **`Plain meaning`** (WCAG / WAI-ARIA links in the first column as needed). - Use the heading **`### Guidelines that apply`** (not “Guidelines that still apply”) for consistency across components. - Optional closing paragraph: `**Bottom line:** …` before `---`. ## Related 1st-gen accessibility (Jira) - **Placement:** Third **H2**, immediately **after** `## ARIA and WCAG context` and **before** `## Recommendations`, separated with `---` like other major sections. - **Content:** Put the **markdown table** immediately under the **H2** (no intro paragraph). **Adobe Jira** is authoritative for **open** vs **closed** status and for **resolution**—refresh table cells when you triage; this table is only a snapshot. Use link targets such as `https://jira.corp.adobe.com/browse/SWC-####`. - **After the table:** Do **not** add follow-up paragraphs that list excluded issues or explain cross-component scope (for example paragraphs starting with **Omitted from this table (by doc rules)** or **Scope note**). Apply **Exclude** by **omitting rows**; put any needed nuance in an optional **Notes** column or in the **Summary** cell. - **Columns (recommended): Jira** | **Type** (Story, Bug, Epic, …) | **Status (snapshot)** | **Resolution (snapshot)** (e.g. Unresolved, Done, Fixed—omit or use “—” when not applicable) | **Summary**. Optional **Notes** when helpful (PR references, file paths, `@todo` locations, “applies to related `sp-*` …”).