You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .ai/skills/accessibility-migration-analysis/SKILL.md
+67-37Lines changed: 67 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,9 @@ alwaysApply: false
7
7
8
8
# Component migration: analyze accessibility
9
9
10
-
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).
10
+
Create comprehensive accessibility documentation for the **analyze accessibility** step of 2nd-gen component migration.
11
+
One markdown file per component, following a fixed structure (ARIA context, recommendations, testing, checklist,
12
+
references). Use this when **creating or updating**`accessibility-migration-analysis.md` under `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component>/`.
11
13
12
14
## Mindset
13
15
@@ -42,10 +44,17 @@ Use these existing docs when matching structure, headings, tables, and phrasing:
-**Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read**.
51
+
-**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.
52
+
45
53
### Important
46
54
47
55
- Verify behavior and ARIA in **2nd-gen source** before stating what the component exposes — do not document ARIA the code does not set
48
56
- Ask clarifying questions for uncertain mappings instead of guessing
57
+
- 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`**
49
58
50
59
## Full instructions
51
60
@@ -55,105 +64,126 @@ Use this **H2** order. **Do not** skip sections that apply; omit only what truly
55
64
56
65
1.`## Overview`
57
66
2.`## ARIA and WCAG context`
58
-
3.`## Recommendations: \`<swc-component-name>\``
59
-
4.`## Testing` with `### Automated tests`
60
-
5.`## Summary checklist`
61
-
6.`## References`
67
+
3.`## Related 1st-gen accessibility (Jira)`
68
+
4.`## Recommendations: \`<swc-component-name>\``
69
+
5.`## Testing` with `### Automated tests`
70
+
6.`## Summary checklist`
71
+
7.`## References`
62
72
63
73
Under **`## Recommendations`**, use these **`###` subsections** in order:
64
74
65
75
1.`### ARIA roles, states, and properties`
66
76
2.`### Shadow DOM and cross-root ARIA Issues`
67
77
3.`### Accessibility tree expectations`
68
-
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`.
78
+
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.
69
79
5.`### Keyboard and focus`
70
80
71
-
Separate major sections with a horizontal rule (`---`) where existing docs use it (after Overview, after ARIA and WCAG context, after Recommendations block before Testing).
81
+
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).
72
82
73
83
### Overview
74
84
75
85
- Start with a short paragraph: what the doc covers, **`swc-*` name**, and **WCAG 2.2 Level AA** as the target.
76
-
- Use **`###` subheadings** for structured bits — **do not** use bold-only labels like `**Also read:**` as section titles.
86
+
- Use **`###` subheadings** for structured bits—**do not** use bold-only labels like `**Also read:**` as section titles.
77
87
78
88
**Typical subheadings** (include what fits the component):
|`### Also read`| Always — point at the component's `rendering-and-styling-migration-analysis.md` (and optional related a11y docs). |
83
-
|`### What it is` or `### What a <noun> is`| Always — one clear definition. |
84
-
|`### When to use something else`| When authors often confuse this with another component — link to other migration or a11y docs with relative paths. |
85
-
|`### What it is not`| When a common mistaken identity exists (e.g. progress ring vs in-field spinner). |
86
-
|`### Related`| Optional — related components (e.g. progress bar vs progress circle). |
|`### Also read`| Always—point at the component’s `rendering-and-styling-migration-analysis.md` (and optional related a11y docs). |
93
+
|`### What it is` or `### What a <noun> is`| Always—one clear definition. |
94
+
|`### When to use something else`| When authors often confuse this with another component—link to other migration or a11y docs with relative paths. |
95
+
|`### What it is not`| When a common mistaken identity exists (e.g. progress ring vs in-field spinner). |
96
+
|`### Related`| Optional—related components (e.g. progress bar vs progress circle). |
87
97
88
-
### ARIA and WCAG context
98
+
Body text under each `###` is normal paragraphs and/or bullets.
99
+
100
+
## ARIA and WCAG context
89
101
90
102
-`### Pattern in the APG` — bullets: how APG (or lack of a named pattern) relates to this widget; link to APG patterns when relevant.
91
103
-`### Guidelines that apply` — a **table** with columns **`Idea`** and **`Plain meaning`** (WCAG / WAI-ARIA links in the first column as needed).
92
-
- Use the heading **`### Guidelines that apply`** (not "Guidelines that still apply") for consistency across components.
104
+
- Use the heading **`### Guidelines that apply`** (not “Guidelines that still apply”) for consistency across components.
93
105
- Optional closing paragraph: `**Bottom line:** …` before `---`.
94
106
95
-
### Recommendations: ARIA roles, states, and properties
107
+
## Related 1st-gen accessibility (Jira)
108
+
109
+
-**Placement:** Third **H2**, immediately **after**`## ARIA and WCAG context` and **before**`## Recommendations`, separated with `---` like other major sections.
110
+
-**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-####`.
111
+
-**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.
112
+
-**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-*` …”).
113
+
-**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.
114
+
-**Exclude (always apply when curating the table):**
115
+
-**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.
116
+
-**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.
117
+
-**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).
118
+
-**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.
119
+
120
+
## Recommendations: ARIA roles, states, and properties
96
121
97
122
Use a **table** (`Topic | What to do`).
98
123
99
124
**Single semantic role policy** (always address):
100
125
101
-
-**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.
102
-
-**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.
126
+
-**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.
127
+
-**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.
128
+
-**Never** recommend **`aria-live="assertive"`** for loading or routine progress.
129
+
- 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.
103
130
104
131
Then add rows for **name**, **states**, **properties**, **visual-only props**, **docs expectations**, etc., **verified against the real implementation**.
105
132
106
133
### Shadow DOM and cross-root ARIA Issues
107
134
108
135
-**Heading text must be exactly:**`### Shadow DOM and cross-root ARIA Issues` (word **Issues** capitalized).
109
-
-**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).
136
+
-**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).
110
137
-**Otherwise** describe the concrete issues and expectations (e.g. `ElementInternals`, `aria-*` delegation, proposed ID strategies).
111
138
112
-
### Live regions and announcements
139
+
## Accessibility tree expectations
140
+
141
+
- Use short subsections or bold lead-ins for variants (e.g. with text, icon-only, determinate vs indeterminate).
142
+
- Describe what assistive technologies should **see**—aligned with implementation.
143
+
144
+
## Live regions and announcements (progress, loading, status)
113
145
114
146
When the component or its docs touch **live regions** or **frequent** status updates:
115
147
116
148
- Call out **over-announcing** as a risk: docs should **warn** authors not to flood screen reader users.
117
-
-**Never** recommend **`aria-live="assertive"`** for loading or routine progress.
149
+
-**Never** recommend **`aria-live="assertive"`** for loading or routine progress (interrupts and overwhelms).
118
150
- 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.
119
151
120
-
See `progress-circle/accessibility-migration-analysis.md` for a full example.
152
+
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.
153
+
154
+
See **`CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md`** for a full example.
121
155
122
156
### Keyboard and focus
123
157
124
-
-**If the component is not focusable** in its default, supported use: the subsection must contain **only** this sentence:
158
+
-**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):
125
159
126
160
`**Not focusable.** Keyboard navigation should skip this component and move to the next focusable element.`
127
161
128
162
-**If the component is focusable or has a keyboard pattern:** replace with accurate, component-specific guidance (Tab order, keys, roving tabindex, focus trap, etc.).
129
163
130
-
### Accessibility tree expectations
131
-
132
-
- Use short subsections or bold lead-ins for variants (e.g. with text, icon-only, determinate vs indeterminate).
133
-
- Describe what assistive technologies should **see** — aligned with implementation.
134
-
135
-
### Testing
164
+
## Testing
136
165
137
166
### Automated tests
138
167
139
-
- Table: **Kind of test** | **What to check** (unit, aXe/Storybook, Playwright ARIA snapshots, contrast, etc. — match what the repo actually uses for that component).
168
+
- Table: **Kind of test** | **What to check** (unit, aXe/Storybook, Playwright ARIA snapshots, contrast, etc.—match what the repo actually uses for that component).
140
169
141
170
### Summary checklist
142
171
143
172
- Markdown task list (`- [ ]`) of concrete, verifiable items (stories, docs, tree, focus, tooling).
144
173
145
174
### References
146
175
147
-
- 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.
176
+
- 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.
177
+
- 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).
148
178
149
179
### Writing style
150
180
151
-
- Follow **text-formatting** rules: sentence case for headings (proper nouns such as **ARIA**, **WCAG**, **APG** stay as usual).
152
-
- Prefer plain, scannable wording; avoid duplicating the rendering doc — **link** to it instead.
181
+
- Follow **text-formatting**workspace rules: sentence case for headings (proper nouns such as **ARIA**, **WCAG**, **APG** stay as usual).
182
+
- Prefer plain, scannable wording; avoid duplicating the rendering doc—**link** to it instead.
153
183
-**Verify** behavior and ARIA in **2nd-gen source** before stating what the component exposes.
154
184
155
185
## Related rules and skills
156
186
157
-
-**contributor-doc-update.md** — when to run `update-nav.js` after heading or structure changes.
187
+
-**contributor-doc-update.mdc** — when to run `update-nav.js` after heading or structure changes.
158
188
-**component-migration-analysis** skill — for `rendering-and-styling-migration-analysis.md`, not this file.
159
-
-**stories-documentation.md** / **stories-format.md** — Storybook docs, separate from this contributor planning doc.
189
+
-**stories-documentation.mdc** / **stories-format.mdc** — Storybook docs, separate from this contributor planning doc.
0 commit comments