Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Pisanie

component-accessibility-specification

/component-accessibility-specification

Tworzy dokumenty specyfikacji dostępności komponentów interfejsu, dla komponentów migrowanych i nowych, wraz z analizą dostępności.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
11
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Tworzy dokumenty specyfikacji dostępności komponentów interfejsu, dla komponentów migrowanych i nowych, wraz z analizą dostępności.

Wyzwalacze z opisu

analyze accessibility
Oryginalny opis (EN)

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.

Jak działa

  1. Mindset
  2. Scope: accessibility specification, not migration plan
  3. When to use this skill
  4. How to invoke
  5. Quick reference
  6. File location and discovery
  7. Full instructions
  8. ARIA and WCAG context
  9. Related 1st-gen accessibility (Jira)
  10. Recommendations: ARIA roles, states, and properties
Sekcje z nagłówków SKILL.md, w oryginale · 352 linii, 4 696 słów
Podgląd SKILL.md
---
name: component-accessibility-specification
description: 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.
---

# 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.
- **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](#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](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/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](../../../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>/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](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 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

```markdown
## 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.

Wersje

W bazie nie ma innych skilli o nazwie component-accessibility-specification.

Migawka bazy z 13.11.2026 · wersja paczki 75bd756f6b1a (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

  • 100accessibility-migration-analysis
    Tworzy dokumenty analizy dostępności przy migracji komponentów do drugiej generacji, na etapie analizy dostępności każdego komponentu.
  • 84audit-accessibility
    Sprawdza komponenty i strony interfejsu pod kątem dostępności, w tym zgodności z WCAG i obsługi czytników ekranu.
  • 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.
  • 90component-migration-analysis
    Tworzy dokumenty analizy renderowania i stylów przy migracji komponentów gen2.
  • 100frontend-design
    Projektuje architekturę interfejsu: hierarchię komponentów, strategię zarządzania stanem, tokeny designu i wymagania dostępności, na etapie planowania frontendu.
  • 10004-components
    Pisze komponenty i zasoby projektu z zera lub z kodu oraz przenosi zmiany komponentów do nowych wersji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.