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 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 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); 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.
## Overview
## ARIA and WCAG context
## Related 1st-gen accessibility (Jira)
## Recommendations: \``
## Testing with ### Automated tests and, when the component is not focusable in its default supported use, ### Manual screen reader testing (see Testing below)
## Summary checklist
## References
Under ## Recommendations, use these ### subsections in order:
### ARIA roles, states, and properties
### Shadow DOM and cross-root ARIA Issues
### Accessibility tree expectations
- 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) and list it under ## References whenever the contributor doc cites it.
### 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.
- 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/component-accessibility-specification.md or avatar/component-accessibility-specification.md (and sibling component docs) for a full example table.
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).
- 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, ARIA properties, accessibility effects of visual variants, docs expectations, etc. Describe existing public properties only when needed to explain verified accessibility behavior; do not design new component properties or slots here. Verify claims about current behavior against the real implementation; label requirements for unimplemented behavior as proposed and cite their design or standards evidence.
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 required accessibility outcomes (e.g. names and descriptions must resolve across supported compositions). Reference existing supported mechanisms such as
ElementInternals or aria-* delegation when relevant; leave new implementation-strategy selection to the migration plan.
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 when available or explicitly identified as proposed requirements when not yet implemented.
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. 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/component-accessibility-specification.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/component-accessibility-specification.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).
- Describe accessibility acceptance requirements, not code-change tasks or event/API test matrices. For unimplemented components, make clear that these are future test requirements rather than completed coverage.
- 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: 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>/component-accessibility-specification.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/component-accessibility-specification.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).
- Check accessible behavior and verification, not API finalization, dependency readiness, parent implementation changes, migration sequencing, or design sign-off.
- 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, and APG “Read me first” (or equivalent) at minimum. Include the component rendering-and-styling migration link when that document exists; for new components, cite available plans, designs, or related specifications instead. 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>/component-accessibility-specification.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.
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 available gen2 source before stating what the component currently exposes. For unimplemented behavior, document proposed requirements and unresolved accessibility questions without claiming source verification.
- 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-JIRA-ticket}} |
Jira ID for this component's accessibility specification 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}}): component accessibility specification, for example docs(dropzone): component accessibility specification.
- 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
## Description
In spectrum-web-components/CONTRIBUTOR-DOCS/03_project-planning/03_components/{{component-name}}/component-accessibility-specification.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)
- When a predecessor exists, 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; otherwise, the retained 1st-gen section states that it does not apply
- Applicable WAI-ARIA design pattern identified with relevant ARIA roles documented
- Available implementation or design evidence reviewed, with proposed requirements distinguished from verified behavior; 1st-gen source reviewed only when a predecessor exists
## Motivation and context
This specification defines accessibility requirements for a migrated or new gen2 component, aligns with the latest WAI-ARIA Authoring Practices, and targets WCAG 2.2 AA. For migrations, it also addresses known accessibility gaps in the predecessor.
## Related issue(s)
- resolves {{component-a11y-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}} component accessibility specification](https://github.com/adobe/spectrum-web-components/blob/{{branch-name}}/CONTRIBUTOR-DOCS/03_project-planning/03_components/{{component-name}}/component-accessibility-specification.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 when a predecessor exists; otherwise, the retained section states that it does not apply
- [ ] 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.
1---2name: component-accessibility-specification3description: Create component accessibility specification docs for migrated and new gen2 components. Use when specifying or analyzing accessibility for one or more components, including the "analyze accessibility" migration step.4metadata:5 source: https://skillmd.com/skills/adobe/component-accessibility-specification6---78# Component accessibility specification910Create comprehensive accessibility documentation for migrated and new gen2 components, including the **analyze accessibility** step of component migration. A 1st-gen predecessor is not required.11One markdown file per component, following a fixed structure (ARIA context, recommendations, testing, checklist,12references). Use this when **creating or updating** `component-accessibility-specification.md` under `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component>/`.1314## Mindset1516You 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.1718When 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.1920## Scope: accessibility specification, not migration plan2122Match 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.2324- 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.25- 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**.26- 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.27- 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.28- 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.29- Keep **Summary checklist** limited to verifiable accessibility outcomes, not migration readiness, scheduling, or implementation sign-off.3031## When to use this skill3233- You are on the "analyze accessibility" step of the gen2 component migration workstream34- You are specifying accessibility for a new gen2 component, such as card view, with no 1st-gen predecessor35- The user asks to create a component accessibility specification for one or more components36- The user asks to analyze accessibility for a component (e.g. "analyze accessibility for button", "create accessibility analysis for dialog")3738## How to invoke3940- Say "create component accessibility specification for [component]", "create accessibility analysis for [component]", or "analyze accessibility for [component]"41- Or refer to the step "analyze accessibility" in the gen2 component migration workstream — the agent should use this skill and read the full instructions below4243## Quick reference4445### Output4647- **One markdown file per component** at:48 `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/component-accessibility-specification.md`49- **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.50- **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.51- **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`.5253### Reference examples (consistency)5455Use these existing docs when matching structure, headings, tables, and phrasing:5657- `CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/component-accessibility-specification.md`58- `CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/component-accessibility-specification.md`59- `CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/component-accessibility-specification.md`60- `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)61- `CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/component-accessibility-specification.md`62- `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)6364## File location and discovery6566- **Path:** `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component-name>/component-accessibility-specification.md`67- **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.68- **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.69- **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`.7071### Important7273- 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.74- **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.75- Ask clarifying questions for uncertain mappings instead of guessing76- **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**.77- 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`**7879## Full instructions8081### Required section order8283Use 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.84851. `## Overview`862. `## ARIA and WCAG context`873. `## Related 1st-gen accessibility (Jira)`884. `## Recommendations: \`<swc-component-name>\``895. `## Testing` with `### Automated tests` and, when the component is **not focusable** in its default supported use, `### Manual screen reader testing` (see [Testing](#testing) below)906. `## Summary checklist`917. `## References`9293Under **`## Recommendations`**, use these **`###` subsections** in order:94951. `### ARIA roles, states, and properties`962. `### Shadow DOM and cross-root ARIA Issues`973. `### Accessibility tree expectations`984. **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.995. `### Keyboard and focus`100101Separate 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).102103### `###` subsections that do not apply (keep the heading)104105The **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.106107- **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).108- 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.109- **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.”110111### Overview112113- Start with a short paragraph: what the doc covers, **`swc-*` name**, and **WCAG 2.2 Level AA** as the target.114- Use **`###` subheadings** for structured bits—**do not** use bold-only labels like `**Also read:**` as section titles.115- 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.116117**Typical subheadings** (include what fits the component):118119| Subheading | Use when |120| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |121| `### 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. |122| `### What it is` or `### What a <noun> is` | Always—one clear definition. |123| `### 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. |124| `### What it is not` | When a common mistaken identity exists (e.g. progress ring vs in-field spinner). |125| `### Related` | Optional—related components (e.g. progress bar vs progress circle). |126127Body text under each `###` is normal paragraphs and/or bullets.128129## ARIA and WCAG context130131- `### Pattern in the APG` — bullets: how APG (or lack of a named pattern) relates to this widget; link to APG patterns when relevant.132- `### Guidelines that apply` — a **table** with columns **`Idea`** and **`Plain meaning`** (WCAG / WAI-ARIA links in the first column as needed).133- Use the heading **`### Guidelines that apply`** (not “Guidelines that still apply”) for consistency across components.134- Optional closing paragraph: `**Bottom line:** …` before `---`.135136## Related 1st-gen accessibility (Jira)137138- **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.139- **Placement:** Third **H2**, immediately **after** `## ARIA and WCAG context` and **before** `## Recommendations`, separated with `---` like other major sections.140- **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-####`.141- **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.142- **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-*` …”).143- **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.144- **Exclude (always apply when curating the table):**145 - **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.146 - **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.147 - **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).148- **Reference:** See **`badge/component-accessibility-specification.md`** or **`avatar/component-accessibility-specification.md`** (and sibling component docs) for a full example table.149150### Dual or conditional ARIA roles151152**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.153154**Prompt the user** when you find any of these:155156- A property or attribute that **changes host `role`** (for example `selects`, `variant`, or author-supplied `role`)157- **Different APG patterns** mapped to the same tag (for example toolbar **and** radio group)158- Docs or tests that expect **different roles** for the same element in different configurations159160**Default guidance to surface in the prompt:**161162- **`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`).163- **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.164165**After the user decides**, record the outcome in the doc:166167- **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).168- **Split** — name the **two (or more) distinct gen2 components** and which role each owns; note 1st-gen API surfaces that map to each.169- **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.170171Do **not** guess which role wins when multiple are plausible—use the **ask-questions-if-underspecified** skill if needed.172173## Recommendations: ARIA roles, states, and properties174175Use a **table** (`Topic | What to do`).176177**Single semantic role policy** (always address):178179- **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)).180- **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.181- **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.182- **Never** recommend **`aria-live="assertive"`** for loading or routine progress.183- 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.184185Then add rows for **name**, **states**, **ARIA properties**, **accessibility effects of visual variants**, **docs expectations**, etc. Describe existing public properties only when needed to explain verified accessibility behavior; do not design new component properties or slots here. Verify claims about current behavior against the real implementation; label requirements for unimplemented behavior as proposed and cite their design or standards evidence.186187### Shadow DOM and cross-root ARIA Issues188189- **Heading text must be exactly:** `### Shadow DOM and cross-root ARIA Issues` (word **Issues** capitalized).190- **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).191- **Otherwise** describe the concrete issues and required accessibility outcomes (e.g. names and descriptions must resolve across supported compositions). Reference existing supported mechanisms such as `ElementInternals` or `aria-*` delegation when relevant; leave new implementation-strategy selection to the migration plan.192193## Accessibility tree expectations194195- Use short subsections or bold lead-ins for variants (e.g. with text, icon-only, determinate vs indeterminate).196- Describe what assistive technologies should **see**, aligned with implementation when available or explicitly identified as proposed requirements when not yet implemented.197198## Live regions and announcements (progress, loading, status)199200When the component or its docs touch **live regions** or **frequent** status updates:201202- Call out **over-announcing** as a risk: docs should **warn** authors not to flood screen reader users.203- **Never** recommend **`aria-live="assertive"`** for loading or routine progress (interrupts and overwhelms).204- 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.205206For **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.207208See **`CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/component-accessibility-specification.md`** for a full example.209210### Keyboard and focus211212Use a **single** `### Keyboard and focus` subsection under `## Recommendations`. Do **not** add a separate `### “Not focusable” (skill boilerplate)` heading.213214- **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):215216 `**Not focusable.** Keyboard navigation should skip this component and move to the next focusable element.`217218- **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.219220- **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/component-accessibility-specification.md`). Never split that explanation out under a nested `### “Not focusable”` heading.221222## Testing223224### Automated tests225226- Table: **Kind of test** | **What to check** (unit, aXe/Storybook, Playwright ARIA snapshots, contrast, etc.—match what the repo actually uses for that component).227- Describe accessibility acceptance requirements, not code-change tasks or event/API test matrices. For unimplemented components, make clear that these are future test requirements rather than completed coverage.228- **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.229230### Manual screen reader testing (non-focusable components)231232**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.233234**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**.235236**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>/component-accessibility-specification.md`, the relative path is:237238`../../../../gen2/packages/swc/.storybook/guides/accessibility-guides/screen_reader_testing.mdx`239240In 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.241242**See:** `CONTRIBUTOR-DOCS/03_project-planning/03_components/meter/component-accessibility-specification.md` for a full example.243244## Summary checklist245246- 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).247- Check accessible behavior and verification, not API finalization, dependency readiness, parent implementation changes, migration sequencing, or design sign-off.248- 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.249250## References251252- Include WAI-ARIA, WCAG 2.2, and APG “Read me first” (or equivalent) at minimum. Include the component rendering-and-styling migration link when that document exists; for new components, cite available plans, designs, or related specifications instead. Add APG pattern links when used in the doc.253- 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>/component-accessibility-specification.md`; adjust if the file moves).254- 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).255256## Writing style257258- Follow text-formatting workspace rules: sentence case for headings; proper nouns (ARIA, WCAG, APG) as usual.259- Prefer plain, scannable wording; link to the rendering doc instead of duplicating it.260- Verify behavior and ARIA in available gen2 source before stating what the component currently exposes. For unimplemented behavior, document proposed requirements and unresolved accessibility questions without claiming source verification.261- 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.262- **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.263- **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.264265## Pull request266267When 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.268269### Variable substitution rules270271| Placeholder | Value | Example |272| -------------------------------- | --------------------------------------------------------------------- | ----------------------- |273| `{{component-name}}` | Package name, kebab-case | `icon`, `picker-button` |274| `{{branch-name}}` | GitHub branch, format `<username>/swc-<jira-number>-<component>-a11y` | `nikkimk/icon-a11y` |275| `{{component-a11y-JIRA-ticket}}` | Jira ID for this component's accessibility specification ticket | `SWC-2146` |276| `{{component-readable-name}}` | Human-readable name, first letter capitalized | `Icon`, `Color handle` |277278### PR settings279280Apply these settings when creating the PR:281282- **Title:** `docs({{component-name}}): component accessibility specification`, for example `docs(dropzone): component accessibility specification`.283- **Draft:** Create as a draft PR.284- **Label:** Add the `a11y` label.285- **Project:** Add to the "Spectrum Web PR Status" project with status **In development**.286287When the user asks to mark the PR as ready for review, apply all of the following:288289- Convert draft to ready for review (`gh pr ready`).290- Add the `Status: Ready for review` label.291- Add the `High priority PR review` label.292293### Template294295```markdown296## Description297298In spectrum-web-components/CONTRIBUTOR-DOCS/03_project-planning/03_components/{{component-name}}/component-accessibility-specification.md:299300- Documented recommendations for ARIA roles, states, and properties for the gen2 {{component-readable-name}}301- Shadow DOM and cross-root ARIA considerations documented, including any limitations or required workarounds (e.g., ElementInternals, cross-root ARIA delegation)302- Accessibility tree expectations documented, including expected node roles, names, states, and hierarchy303- Keyboard interaction model fully specified, covering focus management, key bindings, roving tabindex or active-descendant patterns, and focus trapping where applicable304- Testing requirements defined, including unit tests, integration tests, and manual screen reader testing matrix (JAWS, NVDA, VoiceOver)305- When a predecessor exists, 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; otherwise, the retained 1st-gen section states that it does not apply306- Applicable WAI-ARIA design pattern identified with relevant ARIA roles documented307- Available implementation or design evidence reviewed, with proposed requirements distinguished from verified behavior; 1st-gen source reviewed only when a predecessor exists308309## Motivation and context310311This specification defines accessibility requirements for a migrated or new gen2 component, aligns with the latest WAI-ARIA Authoring Practices, and targets WCAG 2.2 AA. For migrations, it also addresses known accessibility gaps in the predecessor.312313## Related issue(s)314315- resolves {{component-a11y-JIRA-ticket}}316317## Screenshots (if appropriate)318319---320321## Author's checklist322323- [ ] 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.324- [ ] I have reviewed at the Accessibility Practices for this feature, see: [Aria Practices](https://www.w3.org/TR/wai-aria-practices/)325- [ ] I have added automated tests to cover my changes.326- [ ] I have included a well-written changeset if my change needs to be published.327- [ ] I have included updated documentation if my change required it.328329---330331## Reviewer's checklist332333- [ ] Includes a Github Issue with appropriate flag or Jira ticket number without a link334- [ ] Includes thoughtfully written changeset if changes suggested include `patch`, `minor`, or `major` features335- [ ] Automated tests cover all use cases and follow best practices for writing336- [ ] Validated on all supported browsers337- [ ] All VRTs are approved before the author can update Golden Hash338339### Manual review test cases340341Review the [{{component-readable-name}} component accessibility specification](https://github.com/adobe/spectrum-web-components/blob/{{branch-name}}/CONTRIBUTOR-DOCS/03_project-planning/03_components/{{component-name}}/component-accessibility-specification.md)342343- [ ] ARIA roles, states, and properties covered344- [ ] Shadow DOM and cross-root ARIA considerations covered345- [ ] Accessibility tree documented346- [ ] Keyboard interaction fully specified347- [ ] Testing requirements defined348- [ ] Known 1st-gen issues cataloged with dispositions when a predecessor exists; otherwise, the retained section states that it does not apply349- [ ] Review the changes that include the adaptive dual-border guidance350```351352## Related rules and skills353354- `contributor-doc-update` rule — when to run `update-nav.js` after heading or structure changes.355- `ask-questions-if-underspecified` skill — when dual or conditional host roles need a product decision before Recommendations are written.356- `component-migration-analysis` skill — for `rendering-and-styling-migration-analysis.md`, not this file.357- `stories-documentation` / `stories-format` rules and skills — Storybook docs, separate from this contributor planning doc.