diff --git a/.ai/skills/accessibility-migration-analysis/SKILL.md b/.ai/skills/accessibility-migration-analysis/SKILL.md index 00a3f09b86b..fe7d9337651 100644 --- a/.ai/skills/accessibility-migration-analysis/SKILL.md +++ b/.ai/skills/accessibility-migration-analysis/SKILL.md @@ -7,7 +7,9 @@ alwaysApply: false # Component migration: analyze accessibility -Create comprehensive accessibility documentation for the **analyze accessibility** step of 2nd-gen component migration. One markdown file per component, following a fixed structure (ARIA context, recommendations, testing, checklist, references). +Create comprehensive accessibility documentation for the **analyze accessibility** step of 2nd-gen component migration. +One markdown file per component, following a fixed structure (ARIA context, recommendations, testing, checklist, +references). Use this when **creating or updating** `accessibility-migration-analysis.md` under `CONTRIBUTOR-DOCS/03_project-planning/03_components//`. ## Mindset @@ -42,10 +44,17 @@ Use these existing docs when matching structure, headings, tables, and phrasing: - `CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md` - `CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/accessibility-migration-analysis.md` +## File location and discovery + +- **Path:** `CONTRIBUTOR-DOCS/03_project-planning/03_components//accessibility-migration-analysis.md` +- **Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read**. +- **Nav:** After adding a file or changing `##` / `###` headings, run `node update-nav.js` from `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs` (see **contributor-doc-update** rule). Register the doc in `03_components/README.md` when introducing a new component folder. + ### Important - Verify behavior and ARIA in **2nd-gen source** before stating what the component exposes — do not document ARIA the code does not set - Ask clarifying questions for uncertain mappings instead of guessing +- 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 @@ -55,88 +64,108 @@ Use this **H2** order. **Do not** skip sections that apply; omit only what truly 1. `## Overview` 2. `## ARIA and WCAG context` -3. `## Recommendations: \`\`` -4. `## Testing` with `### Automated tests` -5. `## Summary checklist` -6. `## References` +3. `## Related 1st-gen accessibility (Jira)` +4. `## Recommendations: \`\`` +5. `## Testing` with `### Automated tests` +6. `## Summary checklist` +7. `## References` Under **`## Recommendations`**, use these **`###` subsections** in order: 1. `### ARIA roles, states, and properties` 2. `### Shadow DOM and cross-root ARIA Issues` 3. `### Accessibility tree expectations` -4. **Optional (when product guidance needs it):** e.g. `### Assistive technology, live regions` — place **after** accessibility tree expectations and **before** keyboard and focus. For **motion** (WCAG 2.2.2, reduced motion, Spectrum tokens), add rows to **Guidelines that apply** and the **Recommendations** table instead of a separate `### Motion` section — see `progress-circle/accessibility-migration-analysis.md`. +4. **Optional (when product guidance needs it):** e.g. `### Assistive technology, live regions`—place **after** accessibility tree expectations and **before** keyboard and focus. For **motion** (WCAG 2.2.2, reduced motion, Spectrum tokens), add rows to **Guidelines that apply** and the **Recommendations** table instead of a separate `### Motion` section—see **`progress-circle/accessibility-migration-analysis.md`**. For **loading / progress** design intent (variants, motion), align with Figma **Loading animation discovery** ([Loading animation discovery](https://www.figma.com/design/42VzvpW262EAUbYsadO4e8/Loading-animation-discovery)) and **list it under `## References`** whenever the contributor doc cites it. 5. `### Keyboard and focus` -Separate major sections with a horizontal rule (`---`) where existing docs use it (after Overview, after ARIA and WCAG context, after Recommendations block before Testing). +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). ### 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. +- Use **`###` subheadings** for structured bits—**do not** use bold-only labels like `**Also read:**` as section titles. **Typical subheadings** (include what fits the component): -| Subheading | Use when | -| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | -| `### Also read` | Always — point at the component's `rendering-and-styling-migration-analysis.md` (and optional related a11y docs). | -| `### What it is` or `### What a 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. | -| `### 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). | +| Subheading | Use when | +| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | +| `### Also read` | Always—point at the component’s `rendering-and-styling-migration-analysis.md` (and optional related a11y docs). | +| `### What it is` or `### What a 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. | +| `### 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). | -### ARIA and WCAG context +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. +- Use the heading **`### Guidelines that apply`** (not “Guidelines that still apply”) for consistency across components. - Optional closing paragraph: `**Bottom line:** …` before `---`. -### Recommendations: ARIA roles, states, and properties +## Related 1st-gen accessibility (Jira) + +- **Placement:** Third **H2**, immediately **after** `## ARIA and WCAG context` and **before** `## Recommendations`, separated with `---` like other major sections. +- **Content:** Put the **markdown table** immediately under the **H2** (no intro paragraph). **Adobe Jira** is authoritative for **open** vs **closed** status and for **resolution**—refresh table cells when you triage; this table is only a snapshot. Use link targets such as `https://jira.corp.adobe.com/browse/SWC-####`. +- **After the table:** Do **not** add follow-up paragraphs that list excluded issues or explain cross-component scope (for example paragraphs starting with **Omitted from this table (by doc rules)** or **Scope note**). Apply **Exclude** by **omitting rows**; put any needed nuance in an optional **Notes** column or in the **Summary** cell. +- **Columns (recommended):** **Jira** | **Type** (Story, Bug, Epic, …) | **Status (snapshot)** | **Resolution (snapshot)** (e.g. Unresolved, Done, Fixed—omit or use “—” when not applicable) | **Summary**. Optional **Notes** when helpful (PR references, file paths, `@todo` locations, “applies to related `sp-*` …”). +- **Scope:** Include rows your team tracks for this component’s **1st-gen** (`sp-*`) accessibility work; **add rows** when you file or discover issues, and **trim or update** when Jira state or scope changes. Do **not** maintain a separate contributor-doc index file for the same list. +- **Exclude (always apply when curating the table):** + - **Labels:** Do **not** list issues that carry Jira labels **`gen2`** or **`gen-2`** (match your project’s spelling and casing). This section tracks **1st-gen** (`sp-*`) accessibility work, not 2nd-gen 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 2nd-gen migration** (program-level 2nd-gen consultation; track in migration/program views, not per-component tables). +- **Reference:** See **`badge/accessibility-migration-analysis.md`** (and sibling component docs) for a full example table. **Avatar** currently documents the Jira block in **`avatar/rendering-and-styling-migration-analysis.md`** alongside other accessibility migration content—prefer splitting to **`avatar/accessibility-migration-analysis.md`** when that file is added. + +## Recommendations: ARIA roles, states, and properties Use a **table** (`Topic | What to do`). **Single semantic role policy** (always address): -- **Prescribed host role** (e.g. `separator`, `progressbar`): State that the role is **prescribed** and **fixed**, **must not** be author-overridable in implementation or docs, and that **`swc-*` maps to one semantic role only**. 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. +- **Prescribed host role** (e.g. `separator`, `progressbar`): State that the role is **prescribed** and **fixed**, **must not** be author-overridable in implementation or docs, and that **`swc-*` maps to one semantic role only**. If another role is needed, authors must use **different markup or a different component**—not a role override on this element. +- **No default host role** (e.g. badge, status light): State that the component should still represent **one** clear semantic thing; **do not** set a conflicting host `role` (e.g. `button`, `progressbar`) to fake another widget—use the appropriate **button / link / tag / other** component instead. +- **Never** recommend **`aria-live="assertive"`** for loading or routine progress. +- Treat **`aria-live="polite"`** as **rare**: polite regions still **queue** speech, and **several** components or regions updating together becomes **noisy** (bursts, backlog). Prefer **native role semantics** (e.g. **`progressbar`**) and **one** primary message for related loaders when possible. Then add rows for **name**, **states**, **properties**, **visual-only props**, **docs expectations**, etc., **verified against the real implementation**. ### Shadow DOM and cross-root ARIA Issues - **Heading text must be exactly:** `### Shadow DOM and cross-root ARIA Issues` (word **Issues** capitalized). -- **If** the component has **no** cross-root ARIA concerns (no reliance on **ID references** that must resolve across shadow boundaries, e.g. `aria-labelledby` / `aria-describedby` pointing at shadow-only IDs) **and** it is **not** a **form-associated** control, the **entire body** of the subsection should be a single word: **`None`** (no extra sentences). +- **If** the component has **no** cross-root ARIA concerns (no reliance on **ID references** that must resolve across shadow boundaries, e.g. `aria-labelledby` / `aria-describedby` pointing at shadow-only IDs) **and** it is **not** a **form-associated** control (or otherwise dependent on cross-root labeling in ways that need a written plan), the **entire body** of the subsection should be a single word: **`None`** (no extra sentences). - **Otherwise** describe the concrete issues and expectations (e.g. `ElementInternals`, `aria-*` delegation, proposed ID strategies). -### Live regions and announcements +## Accessibility tree expectations + +- Use short subsections or bold lead-ins for variants (e.g. with text, icon-only, determinate vs indeterminate). +- Describe what assistive technologies should **see**—aligned with implementation. + +## Live regions and announcements (progress, loading, status) When the component or its docs touch **live regions** or **frequent** status updates: - Call out **over-announcing** as a risk: docs should **warn** authors not to flood screen reader users. -- **Never** recommend **`aria-live="assertive"`** for loading or routine progress. +- **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. -See `progress-circle/accessibility-migration-analysis.md` for a full example. +For **progress**, **loading**, **busy**, or **spinner** UX (including motion, variants, and when which treatment applies), **consult** Adobe’s Figma file **Loading animation discovery**: [Loading animation discovery](https://www.figma.com/design/42VzvpW262EAUbYsadO4e8/Loading-animation-discovery). Align written guidance with that source where the doc covers those states; **add the same link under `## References`** in the contributor doc whenever you cite or rely on it. + +See **`CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md`** for a full example. ### Keyboard and focus -- **If the component is not focusable** in its default, supported use: the subsection must contain **only** this sentence: +- **If the component is not focusable** in its default, supported use (no Tab stop, not a keyboard widget): the subsection must contain **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:** replace with accurate, component-specific guidance (Tab order, keys, roving tabindex, focus trap, etc.). -### 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. - -### Testing +## 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). +- Table: **Kind of test** | **What to check** (unit, aXe/Storybook, Playwright ARIA snapshots, contrast, etc.—match what the repo actually uses for that component). ### Summary checklist @@ -144,16 +173,17 @@ See `progress-circle/accessibility-migration-analysis.md` for a full example. ### References -- Include **WAI-ARIA**, **WCAG 2.2**, **APG "Read me first"** (or equivalent), and the component **rendering-and-styling migration** link at minimum. Add APG pattern links when used in the doc. +- Include **WAI-ARIA**, **WCAG 2.2**, **APG “Read me first”** (or equivalent), and the component **rendering-and-styling migration** link at minimum. Add APG pattern links when used in the doc. +- When the doc 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** rules: sentence case for headings (proper nouns such as **ARIA**, **WCAG**, **APG** stay as usual). -- Prefer plain, scannable wording; avoid duplicating the rendering doc — **link** to it instead. +- Follow **text-formatting** workspace rules: sentence case for headings (proper nouns such as **ARIA**, **WCAG**, **APG** stay as usual). +- Prefer plain, scannable wording; avoid duplicating the rendering doc—**link** to it instead. - **Verify** behavior and ARIA in **2nd-gen source** before stating what the component exposes. ## Related rules and skills -- **contributor-doc-update.md** — when to run `update-nav.js` after heading or structure changes. +- **contributor-doc-update.mdc** — when to run `update-nav.js` after heading or structure changes. - **component-migration-analysis** skill — for `rendering-and-styling-migration-analysis.md`, not this file. -- **stories-documentation.md** / **stories-format.md** — Storybook docs, separate from this contributor planning doc. +- **stories-documentation.mdc** / **stories-format.mdc** — Storybook docs, separate from this contributor planning doc. diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md index 39d07ca9ae9..32e941a5238 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md +++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md @@ -32,6 +32,7 @@ - [Badge accessibility migration analysis](badge/accessibility-migration-analysis.md) - [Badge migration roadmap](badge/rendering-and-styling-migration-analysis.md) - Button + - [Button accessibility migration analysis](button/accessibility-migration-analysis.md) - [Button migration roadmap](button/rendering-and-styling-migration-analysis.md) - Button Group - [Button Group migration roadmap](button-group/rendering-and-styling-migration-analysis.md) diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/button/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/button/accessibility-migration-analysis.md new file mode 100644 index 00000000000..0e7590856dc --- /dev/null +++ b/CONTRIBUTOR-DOCS/03_project-planning/03_components/button/accessibility-migration-analysis.md @@ -0,0 +1,258 @@ + + +[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Components](../README.md) / Button / Button accessibility migration analysis + + + +# Button accessibility migration analysis + + + +
+In this doc + +- [Overview](#overview) + - [Also read](#also-read) + - [What it is](#what-it-is) + - [When to use something else](#when-to-use-something-else) + - [What it is not](#what-it-is-not) +- [ARIA and WCAG context](#aria-and-wcag-context) + - [Pattern in the APG](#pattern-in-the-apg) + - [Guidelines that apply](#guidelines-that-apply) +- [Related 1st-gen accessibility (Jira)](#related-1st-gen-accessibility-jira) +- [1st-gen implementation notes (avoid in 2nd-gen)](#1st-gen-implementation-notes-avoid-in-2nd-gen) +- [Recommendations: ``](#recommendations-swc-button) + - [ARIA roles, states, and properties](#aria-roles-states-and-properties) + - [Shadow DOM and cross-root ARIA Issues](#shadow-dom-and-cross-root-aria-issues) + - [Form-associated buttons (`submit` / `reset`) — deferred](#form-associated-buttons-submit--reset--deferred) + - [Accessibility tree expectations](#accessibility-tree-expectations) + - [Live regions, loading, and announcements](#live-regions-loading-and-announcements) + - [Keyboard and focus](#keyboard-and-focus) +- [Testing](#testing) + - [Automated tests](#automated-tests) +- [Summary checklist](#summary-checklist) +- [References](#references) + +
+ + + +## Overview + +This doc describes how **`swc-button`** should behave for **accessibility** in 2nd-gen, targeting **WCAG 2.2 Level AA**. **Navigation** uses **`swc-link`**, **native ``**, or Spectrum global styling on anchors—not a button-with-**`href`**. In 1st-gen, **`href`** on **``** was **deprecated** with a migration warning; 2nd-gen **continues** that direction: **do not** ship a **link button** or revive **`href`** on the button component. **Pending / loading** treatment aligns with Spectrum loading guidance ([Figma — Loading animation discovery](https://www.figma.com/design/42VzvpW262EAUbYsadO4e8/Loading-animation-discovery)) and internal **general / accessibility guidance** for loading indicators (delay before show, determinate vs indeterminate, placement, status announcements, and motion). + +**Shared infra:** [spectrum-web-components#6120](https://github.com/adobe/spectrum-web-components/pull/6120) proposes moving mixins and utilities into **`@spectrum-web-components/core`**. **`swc-button`** does **not** need **`like-anchor.ts`** (`LikeAnchor`)—that mixin existed to bolt **anchor** behavior onto controls that already looked like buttons; **`swc-button`** is **only** a **`