accessibility-migration-analysis
/accessibility-migration-analysis
Tworzy dokumenty analizy dostępności przy migracji komponentów do drugiej generacji, na etapie analizy dostępności każdego komponentu.
- Autor
- adobe ↗
- Repozytorium
- spectrum-web-components ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 11
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Tworzy dokumenty analizy dostępności przy migracji komponentów do drugiej generacji, na etapie analizy dostępności każdego komponentu.
Wyzwalacze z opisu
Oryginalny opis (EN)
Create accessibility migration analysis docs for gen2 component migration. Use when on the "analyze accessibility" step for one or more components.
Jak działa
- Mindset
- When to use this skill
- How to invoke
- Quick reference
- File location and discovery
- Full instructions
- ARIA and WCAG context
- Related 1st-gen accessibility (Jira)
- Recommendations: ARIA roles, states, and properties
- Accessibility tree expectations
Podgląd SKILL.md
---
name: accessibility-migration-analysis
description: Create accessibility migration analysis docs for gen2 component migration. Use when on the "analyze accessibility" step for one or more components.
---
# 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-*` …”).
- **Scope:** Include rows your team tracks for this component’s **1st-gen** (`sp-*`) accessibility work; **add rows** when you file or discover issues, and **trim or update** when Jira state or scope changes. Do **not** maintain a separate contributor-doc index file for the same list.
- **Exclude (always apply when curating the table):**
- **Labels:** Do **not** list issues that carry Jira labels **`gen2`** or **`gen-2`** (match your project’s spelling and casing). This section tracks **1st-gen** (`sp-*`) accessibility work, not gen2 program-only tickets.
- **Audit:** Do **not** list **audit** issues whose **summary begins with Audit and improve** (usually **Epics** for cross-cutting accessibility audits—e.g. primitive components, card and meter). Track those in Jira or program views, not in per-component tables.
- **Migration consultation:** Do **not** list **stories** whose summary follows **Migration (YYYY-MM-DD): Accessibility consultation for gen2 migration** (program-level gen2 consultation; track in migration/program views, not per-component tables).
- **Reference:** See **`badge/accessibility-migration-analysis.md`** (and sibling component docs) for a full example table. **Avatar** currently documents the Jira block in **`avatar/rendering-and-styling-migration-analysis.md`** alongside other accessibility migration content—prefer splitting to **`avatar/accessibility-migration-analysis.md`** when that file is added.
### Dual or conditional ARIA roles
**Before writing `## Recommendations`**, check whether the component (especially in **1st-gen** source) could expose **more than one host `role`** across modes, properties, or author overrides.
**Prompt the user** when you find any of these:
- A property or attribute that **changes host `role`** (for example `selects`, `variant`, or author-supplied `role`)
- **Different APG patterns** mapped to the same tag (for example toolbar **and** radio group)
- Docs or tests that expect **different roles** for the same element in different configurations
**Default guidance to surface in the prompt:**
- **`swc-*` should map to one host semantic role only.** If two roles are both valid for the same visual pattern, that is a signal the design is really **two components** (or one inner component plus an **outer wrapper** for a landmark role such as `toolbar`).
- **Do not** recommend keeping a single component that **switches host roles** unless the user explicitly chooses that after the prompt. Even then, document it as an **exception** with migration cost and author confusion called out.
**After the user decides**, record the outcome in the doc:
- **Fixed single role** — state the prescribed role and that other former roles move to **different components** or **parent markup** (link to those components in **`### When to use something else`** when helpful).
- **Split** — name the **two (or more) distinct gen2 components** and which role each owns; note 1st-gen API surfaces that map to each.
- **Wrapper pattern** — when only a **landmark** role differs (for example `toolbar` around a `group`), document **outer wrapper + inner component**, not role swapping on the inner host.
Do **not** guess which role wins when multiple are plausible—use the **ask-questions-if-underspecified** skill if needed.
## Recommendations: ARIA roles, states, and properties
Use a **table** (`Topic | What to do`).
**Single semantic role policy** (always address):
- **One host role per component:** Every **`swc-*`** maps to **one** semantic host role (or **no** host role when semantics live on a child). A component that serves **more than one role** should **most likely be two distinct components**—confirm with the user when 1st-gen or design artifacts suggest otherwise (see [Dual or conditional ARIA roles](#dual-or-conditional-aria-roles)).
- **Prescribed host role** (e.g. `separator`, `progressbar`, `group`): State that the role is **prescribed** and **fixed**, **must not** be author-overridable in implementation or docs. If another role is needed, authors must use **different markup or a different component**—not a role override on this element.
- **No default host role** (e.g. badge, status light): State that the component should still represent **one** clear semantic thing; **do not** set a conflicting host `role` (e.g. `button`, `progressbar`) to fake another widget—use the appropriate **button / link / tag / other** component instead.
- **Never** recommend **`aria-live="assertive"`** for loading or routine progress.
- Treat **`aria-live="polite"`** as **rare**: polite regions still **queue** speech, and **several** components or regions updating together becomes **noisy** (bursts, backlog). Prefer **native role semantics** (e.g. **`progressbar`**) and **one** primary message for related loaders when possible.
Then add rows for **name**, **states**, **properties**, **visual-only props**, **docs expectations**, etc., **verified against the real implementation**.
### Shadow DOM and cross-root ARIA Issues
- **Heading text must be exactly:** `### Shadow DOM and cross-root ARIA Issues` (word **Issues** capitalized).
- **If** the component has **no** cross-root ARIA concerns (no reliance on **ID references** that must resolve across shadow boundaries, e.g. `aria-labelledby` / `aria-describedby` pointing at shadow-only IDs) **and** it is **not** a **form-associated** control (or otherwise dependent on cross-root labeling in ways that need a written plan), the **entire body** of the subsection should be a single word: **`None`** (no extra sentences).
- **Otherwise** describe the concrete issues and expectations (e.g. `ElementInternals`, `aria-*` delegation, proposed ID strategies).
## Accessibility tree expectations
- Use short subsections or bold lead-ins for variants (e.g. with text, icon-only, determinate vs indeterminate).
- Describe what assistive technologies should **see**—aligned with implementation.
## Live regions and announcements (progress, loading, status)
When the component or its docs touch **live regions** or **frequent** status updates:
- Call out **over-announcing** as a risk: docs should **warn** authors not to flood screen reader users.
- **Never** recommend **`aria-live="assertive"`** for loading or routine progress (interrupts and overwhelms).
- Treat **`aria-live="polite"`** as **rare**: polite regions still **queue** speech, and **several** components or regions updating together becomes **noisy** (bursts, backlog). Prefer **native role semantics** (e.g. **`progressbar`**) and **one** primary message for related loaders when possible.
For **progress**, **loading**, **busy**, or **spinner** UX (including motion, variants, and when which treatment applies), **consult** Adobe’s Figma file **Loading animation discovery**: [Loading animation discovery](https://www.figma.com/design/42VzvpW262EAUbYsadO4e8/Loading-animation-discovery). Align written guidance with that source where the doc covers those states; **add the same link under `## References`** in the contributor doc whenever you cite or rely on it.
See **`CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md`** for a full example.
### Keyboard and focus
Use a **single** `### Keyboard and focus` subsection under `## Recommendations`. Do **not** add a separate `### “Not focusable” (skill boilerplate)` heading.
- **If the component is not focusable** in its default, supported use (no Tab stop, not a keyboard widget): under `### Keyboard and focus`, include **only** this sentence (no extra bullets or tables):
`**Not focusable.** Keyboard navigation should skip this component and move to the next focusable element.`
- **If the component is focusable or has a keyboard pattern:** put Tab order, keys, roving tabindex, focus trap, and related guidance in the same `### Keyboard and focus` subsection. Do **not** paste the divider-style “Not focusable. …” one-liner, and do **not** add a paragraph arguing that line “does not apply”—that text is only for **non-focusable** decorative hosts.
- **If that one-sentence “Not focusable” block does not fit** (for example a shell or positioning host with no default keyboard contract, but not static decoration like a divider): still use one `### Keyboard and focus`; add a short paragraph that describes what applies for _this_ host (see `CONTRIBUTOR-DOCS/03_project-planning/03_components/popover/accessibility-migration-analysis.md`). Never split that explanation out under a nested `### “Not focusable”` heading.
## Testing
### Automated tests
- Table: **Kind of test** | **What to check** (unit, aXe/Storybook, Playwright ARIA snapshots, contrast, etc.—match what the repo actually uses for that component).
- **Form-associated components:** if the component participates in a `<form>` (text field, checkbox, checkbox group, radio group, picker, combobox, and similar), the Automated tests table **must** include a form-participation row and the doc **must** state that stories demonstrate the component inside a native `<form>` (native `<form>` for now; a dedicated form component later). Cover the full form lifecycle required for every form-associated component by [forms strategy RFC §3.5](../../../CONTRIBUTOR-DOCS/03_project-planning/05_strategies/forms-strategy-rfc.md#35-testing-form-participation): value on submit (`FormData`), validation of required/constrained state at the level the constraint lives, reset (`formResetCallback`), and getting the value. Add a matching **Summary checklist** item.
### Manual screen reader testing (non-focusable components)
**When to include:** Add `### Manual screen reader testing` after `### Automated tests` whenever the component is **not keyboard focusable** in its default, supported use—the same situation where `### Keyboard and focus` is only the prescribed **Not focusable** sentence.
**What to write:** Explain that manual testers using a **screen reader** need **browse mode** (document or scan mode) to encounter the control in **content order**; **forms** / **application**-style **focus navigation** alone will **not Tab** to a **non-focusable widget**, so **browse mode** is required to verify **name**, **role**, and **relevant state** in the **reading order**.
**Reference (required in the contributor doc when this subsection exists):** Link to the gen2 Storybook accessibility guide in the repo. From `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component>/accessibility-migration-analysis.md`, the relative path is:
`../../../../gen2/packages/swc/.storybook/guides/accessibility-guides/screen_reader_testing.mdx`
In the **body**, point to the **Browse mode (document/scan mode)** section. Add the same link (or a short line such as “gen2 Storybook: Screen reader testing” pointing to that file) under **`## References`**. Add a **summary checklist** item that **manual SR testing** uses **browse mode** per that guide.
**See:** `CONTRIBUTOR-DOCS/03_project-planning/03_components/meter/accessibility-migration-analysis.md` for a full example.
## Summary checklist
- Markdown task list (`- [ ]`) of concrete, verifiable items (stories, docs, tree, focus, tooling, and for non-focusable components manual screen reader / browse mode per the Storybook guide when `### Manual screen reader testing` is present).
- When the component had **conditional or multiple plausible host roles** in 1st-gen, include a checklist item that **gen2 uses one fixed host role** (or **split components / wrapper pattern** per user decision)—not role switching on one tag.
## References
- Include WAI-ARIA, WCAG 2.2, APG “Read me first” (or equivalent), and the component rendering-and-styling migration link at minimum. Add APG pattern links when used in the doc.
- When the doc includes `### Manual screen reader testing` for a non-focusable component, add the gen2 Storybook screen reader testing guide: `gen2/packages/swc/.storybook/guides/accessibility-guides/screen_reader_testing.mdx` (in contributor docs, link with `../../../../gen2/packages/swc/.storybook/guides/accessibility-guides/screen_reader_testing.mdx` from `03_components/<component>/accessibility-migration-analysis.md`; adjust if the file moves).
- When the doc discusses progress, loading, busy, or spinner behavior and you point authors at the Loading animation discovery Figma file in the body, list it again here: [Loading animation discovery](https://www.figma.com/design/42VzvpW262EAUbYsadO4e8/Loading-animation-discovery).
## Writing style
- Follow text-formatting workspace rules: sentence case for headings; proper nouns (ARIA, WCAG, APG) as usual.
- Prefer plain, scannable wording; link to the rendering doc instead of duplicating it.
- Verify behavior and ARIA in gen2 source before stating what the component exposes.
- For optional `###` subsections copied from peer docs that do not apply to the component, keep the heading and add a short “Does not apply” (or “Intentionally omitted”) body—do not leave readers to infer omission; match the “subsections that do not apply (keep the heading)” guidance in Full instructions.
- **Bold:** You may use `**…**` sparingly when it helps scanning (constraints, out-of-scope callouts, critical negations)—not for whole paragraphs or decoration. When estimating load, count only body prose: exclude markdown heading title lines (`#`…`####`), text inside link labels (`[…](…)`), fenced code, inline code, paths, generated breadcrumbs/TOC, and obvious boilerplate. Non-header, non-link prose should not sit more than about 30% inside bold markup; trim if above that.
- **Bold (runs):** When adjacent words share the same emphasis, use one bold span (`**migration wave**`), not separate pairs per word (`**migration** **wave**`). Do not merge across words that should stay unstyled, or around links or code where splitting is clearer.
## Pull request
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 | `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
Apply these settings when creating the PR:
- **Title:** `docs({{component-name}}): a11y migration analysis` — for example `docs(dropzone): a11y migration analysis`.
- **Draft:** Create as a draft PR.
- **Label:** Add the `a11y` label.
- **Project:** Add to the "Spectrum Web PR Status" project with status **In development**.
When the user asks to mark the PR as ready for review, apply all of the following:
- Convert draft to ready for review (`gh pr ready`).
- Add the `Status: Ready for review` label.
- Add the `High priority PR review` label.
### Template
```markdown
## Description
In spectrum-web-components/CONTRIBUTOR-DOCS/03_project-planning/03_components/{{component-name}}/accessibility-migration-analysis.md:
- Documented recommendations for ARIA roles, states, and properties for the gen2 {{component-readable-name}}
- Shadow DOM and cross-root ARIA considerations documented, including any limitations or required workarounds (e.g., ElementInternals, cross-root ARIA delegation)
- Accessibility tree expectations documented, including expected node roles, names, states, and hierarchy
- Keyboard interaction model fully specified, covering focus management, key bindings, roving tabindex or active-descendant patterns, and focus trapping where applicable
- Testing requirements defined, including unit tests, integration tests, and manual screen reader testing matrix (JAWS, NVDA, VoiceOver)
- Known 1st-gen accessibility issues cataloged with disposition (fix in gen2, defer, or won't fix) and linked to any open GitHub issues or bugs
- Applicable WAI-ARIA design pattern identified with relevant ARIA roles documented
- 1st-gen component analysis completed, covering current ARIA implementation, keyboard handling, existing test coverage, and known issues with dispositions
## Motivation and context
The gen2 migration is an opportunity to address known accessibility gaps, align with the latest WAI-ARIA Authoring Practices, and ensure the component meets WCAG 2.2 AA compliance.
## Related issue(s)
- resolves {{component-a11y-migration-JIRA-ticket}}
## Screenshots (if appropriate)
---
## Author's checklist
- [ ] I have read the **[CONTRIBUTING](<(https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTING.md)>)** and **[PULL_REQUESTS](<(https://github.com/adobe/spectrum-web-components/blob/main/PULL_REQUESTS.md)>)** documents.
- [ ] I have reviewed at the Accessibility Practices for this feature, see: [Aria Practices](https://www.w3.org/TR/wai-aria-practices/)
- [ ] I have added automated tests to cover my changes.
- [ ] I have included a well-written changeset if my change needs to be published.
- [ ] I have included updated documentation if my change required it.
---
## Reviewer's checklist
- [ ] Includes a Github Issue with appropriate flag or Jira ticket number without a link
- [ ] Includes thoughtfully written changeset if changes suggested include `patch`, `minor`, or `major` features
- [ ] Automated tests cover all use cases and follow best practices for writing
- [ ] Validated on all supported browsers
- [ ] All VRTs are approved before the author can update Golden Hash
### Manual review test cases
Review the [{{component-readable-name}} accessibility migration analysis](https://github.com/adobe/spectrum-web-components/blob/{{branch-name}}/CONTRIBUTOR-DOCS/03_project-planning/03_components/{{component-name}}/accessibility-migration-analysis.md)
- [ ] ARIA roles, states, and properties covered
- [ ] Shadow DOM and cross-root ARIA considerations covered
- [ ] Accessibility tree documented
- [ ] Keyboard interaction fully specified
- [ ] Testing requirements defined
- [ ] Known 1st-gen issues cataloged with dispositions
- [ ] Review the changes that include the adaptive dual-border guidance
```
## Related rules and skills
- `contributor-doc-update` rule — when to run `update-nav.js` after heading or structure changes.
- `ask-questions-if-underspecified` skill — when dual or conditional host roles need a product decision before Recommendations are written.
- `component-migration-analysis` skill — for `rendering-and-styling-migration-analysis.md`, not this file.
- `stories-documentation` / `stories-format` rules and skills — Storybook docs, separate from this contributor planning doc.
Wersje
W bazie nie ma innych skilli o nazwie accessibility-migration-analysis.
Migawka bazy z 13.11.2026 · wersja paczki 5d2bafc811dd (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 90component-migration-analysis
Tworzy dokumenty analizy renderowania i stylów przy migracji komponentów gen2. - 100component-accessibility-specification
Tworzy dokumenty specyfikacji dostępności komponentów interfejsu, dla komponentów migrowanych i nowych, wraz z analizą dostępności. - 90accessibility-review
Tworzy, wdraża lub przegląda prace przeglądu dostępności z kontrolą formatu, dostępności, wydajności i weryfikacji wizualnej. - 100prism-audit
Audytuje frontend pod kątem rozmiaru bundla, zależności, dostępności, wydajności i jakości komponentów, przy przeglądzie frontendu lub kontroli wydajności i dostępności. - 100accessibility
Zawiera wzorce dostępności stron i zgodność z WCAG 2.1 i 2.2: budowanie dostępnych komponentów, audyt interfejsu i naprawę problemów z czytnikiem ekranu. - 100accessibility-generator
Generuje infrastrukturę dostępności dla VoiceOver, Dynamic Type i innych funkcji, dodaje etykiety i podpowiedzi oraz audytuje zgodność aplikacji.