component-accessibility-specification

# Component accessibility specification Create comprehensive accessibility documentation for migrated and new gen2 components, including the **analyze accessibility** step of component migration. A 1st-gen predecessor is not required. One markdown file per component, following a fixed structure (ARIA context, recommendations, testing, checklist, references). Use this when **creating or updating** `component-accessibility-specification.md` under `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component>/`. ## Mindset You are an accessibility auditor, not a documenter. Read available source first and verify claims about implemented behavior against that source. For new or unimplemented components, use approved designs, APG patterns, WCAG criteria, and related component specifications to define requirements. Clearly distinguish verified implementation behavior from proposed requirements and unresolved accessibility questions; never present planned behavior as already implemented. Inspect a 1st-gen predecessor only when one exists. 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. ## Scope: accessibility specification, not migration plan Match the structure, level of detail, and phrasing of existing component accessibility specifications, especially siblings in the same component family. Keep the document focused on semantic roles, names, states, relationships, accessible interaction, focus, form-association boundaries, and accessibility testing. - Leave public API and slot design, event names/payloads/cancellation contracts, state-management architecture, dependency sequencing, implementation tasks, and migration decision tables for the component's migration plan. Do not create that plan as a side effect of writing the accessibility specification. - Research source and design evidence thoroughly, but summarize relevant findings within the required sections and cite sources under **References**. Do not add standalone evidence inventories, implementation-readiness reviews, or sections such as **Decisions to resolve before implementation**. - Keep necessary accessibility questions close to the affected recommendation. Ask the user when a semantic decision blocks the specification; do not turn unrelated API or delivery questions into accessibility blockers. - Specify observable accessibility outcomes without prescribing an unreviewed API or implementation. For example, require one checked item per exclusive set and focus-only arrow navigation without choosing property names, event contracts, or parent allow-list changes. - Retain accessibility requirements even when implementation comes later, including keyboard behavior, cross-root naming constraints, form participation or its absence, and testing. Link to available migration plans for context without duplicating their task lists or changing their agreed scope. - Keep **Summary checklist** limited to verifiable accessibility outcomes, not migration readiness, scheduling, or implementation sign-off. ## When to use this skill - You are on the "analyze accessibility" step of the gen2 component migration workstream - You are specifying accessibility for a new gen2 component, such as card view, with no 1st-gen predecessor - The user asks to create a component accessibility specification 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 component accessibility specification for [component]", "create accessibility analysis for [component]", or "analyze accessibility 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]/component-accessibility-specification.md` - **Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read** when it exists; for new components, link to available component plans, designs, or related specifications instead. Do not require or invent a migration document. - **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/component-accessibility-specification.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/component-accessibility-specification.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/component-accessibility-specification.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/meter/component-accessibility-specification.md` (non-focusable component with `### Manual screen reader testing`—**browse mode** and Storybook guide) - `CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/component-accessibility-specification.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/popover/component-accessibility-specification.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>/component-accessibility-specification.md` - **Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read** when it exists; otherwise link to available component plans, designs, or related specifications. - **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 currently exposes. When source does not exist yet, label the content as proposed requirements and record only relevant unresolved accessibility questions; do not require a predecessor or imply implementation verification. - **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 specification. 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/component-accessibility-specification.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/component-accessibility-specification.md` and `popover/component-accessibility-specification.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. - When the component is not implemented, state that briefly. Do not expand the overview into an API analysis, evidence inventory, or migration-planning decision log. **Typical subheadings** (include what fits the component): | Subheading | Use when | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `### Also read` | Always link to available supporting evidence: the component's rendering-and-styling migration document when it exists, or component plans, designs, and related specifications for new components. | | `### 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) - **New components:** Keep this H2 in its required position to preserve the document structure. If there is no 1st-gen predecessor, use the body `Does not apply. This is a new gen2 component with no 1st-gen predecessor.` Do not require a Jira search or fabricate predecessor issues or a table. The table rules below apply only when a predecessor exists. - **Placement:** Third **H2**, immediately **after** `## ARIA and WCAG context` and **before** `## Recommendations`, separated with `---` like other major sections.