Skip to content

docs(a11y): tabs a11y migration #6163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nikkimk merged 6 commits into from
Apr 22, 2026
Merged

docs(a11y): tabs a11y migration #6163

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
26b76ba
chore: updated a11y migration docs rules
nikkimk Apr 9, 2026
06de5ad
docs(tabs): a11y igration docs for tabs
nikkimk Apr 9, 2026
1cb746d
Merge branch 'main' into nikkimk/tabs-a11y-migration
nikkimk Apr 13, 2026
c16bacf
Delete .cursor/rules/accessibility-migration-analysis.mdc
nikkimk Apr 22, 2026
8579d7e
Merge branch 'main' into nikkimk/tabs-a11y-migration
nikkimk Apr 22, 2026
80028d1
Merge branch 'main' into nikkimk/tabs-a11y-migration
nikkimk Apr 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 21 additions & 6 deletions .cursor/rules/accessibility-migration-analysis.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ These docs describe how a **2nd-gen** `swc-*` component should behave for **acce

Use these existing docs as **examples** when matching structure, headings, tables, and phrasing:

- `CONTRIBUTOR-DOCS/03_project-planning/03_components/action-menu/accessibility-migration-analysis.md`
- `CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/accessibility-migration-analysis.md`
- `CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/accessibility-migration-analysis.md`
- `CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md`
Expand All @@ -31,10 +32,11 @@ Use this **H2** order. **Do not** skip sections that apply; omit only what truly

1. `## Overview`
2. `## ARIA and WCAG context`
3. `## Recommendations: \`<swc-component-name>\``
4. `## Testing` with `### Automated tests`
5. `## Summary checklist`
6. `## References`
3. `## Related 1st-gen accessibility (Jira)`
4. `## Recommendations: \`<swc-component-name>\``
5. `## Testing` with `### Automated tests`
6. `## Summary checklist`
7. `## References`

Under **`## Recommendations`**, use these **`###` subsections** in order:

Expand All @@ -44,7 +46,7 @@ Under **`## Recommendations`**, use these **`###` subsections** in order:
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`**.
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

Expand All @@ -70,6 +72,19 @@ Body text under each `###` is normal paragraphs and/or bullets.
- 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)

- **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` or `Topic | What to do`).
Expand Down Expand Up @@ -134,4 +149,4 @@ See **`progress-circle/accessibility-migration-analysis.md`** for a full example

- **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.mdc** / **stories-format.mdc** — Storybook docs, separate from this contributor planning doc.
- **stories-documentation.mdc** / **stories-format.mdc** — Storybook docs, separate from this contributor planning doc.
3 changes: 3 additions & 0 deletions CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,9 @@
- [Swatch Group migration roadmap](swatch-group/rendering-and-styling-migration-analysis.md)
- Switch
- [Switch migration roadmap](switch/rendering-and-styling-migration-analysis.md)
- Tabs
- [Tabs accessibility migration analysis](tabs/accessibility-migration-analysis.md)
- [Tabs migration roadmap](tabs/rendering-and-styling-migration-analysis.md)
- Tag
- [Tag migration roadmap](tag/rendering-and-styling-migration-analysis.md)
- Tags
Expand Down
Loading
Loading