docs: a11y docs html aria by nikkimk · Pull Request #6142 · adobe/spectrum-web-components

nikkimk · 2026-04-03T20:35:55Z

Description

In contributor docs directory (CONTRIBUTOR-DOCS/04_accessibility_guides/01_semantic_html_aria.md):

HTML and ARIA page is created in the accessibility section of docs:
Page includes a section on semantic HTML and its importance
Page explains ARIA as a secondary method when HTML semantics are insufficient
Page includes a dedicated section on cross-root ARIA challenges
Feel free to use examples from our codebase to illustrate this (i.e. typography, button as link, button v role as button, etc)
All referenced sources are properly linked
Content follows text formatting conventions (sentence case, proper use of backticks, etc.)
Page is accessible and follows WCAG guidelines
Technical accuracy is reviewed by team members

Motivation and context

Create a comprehensive documentation page in the accessibility section that covers HTML semantics, ARIA best practices, and the challenges of cross-root ARIA in web components. This page should educate developers on proper semantic HTML usage, when to use ARIA, and current limitations with shadow DOM implementations.

Related issue(s)

fixes [Issue Number]

Screenshots (if appropriate)

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed at the Accessibility Practices for this feature, see: 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

Go to https://swcpreviews.z13.web.core.windows.net/pr-6142/docs/second-gen-storybook/?path=/docs/guides-accessibility-guides-semantic-html-and-aria--readme:

Verify all links are working and point to correct resources
Confirm code examples (if included) are syntactically correct
Check that content follows workspace text formatting conventions (sentence case for headings, proper use of backticks)
Test page on documentation site to ensure proper rendering
Have content reviewed by accessibility expert or team member familiar with ARIA
Verify page is navigable with keyboard only
Test page with screen reader to ensure accessibility

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

Accessibility testing checklist

Required: Complete each applicable item and document your testing steps (replace the placeholders with your component-specific instructions).

Keyboard (required — document steps below) — What to test for: Focus order is logical; Tab reaches the component and all interactive descendants; Enter/Space activate where appropriate; arrow keys work for tabs, menus, sliders, etc.; no focus traps; Escape dismisses when applicable; focus indicator is visible.
1. Go here
2. Do this action
3. Expect this result
Screen reader (required — document steps below) — What to test for: Role and name are announced correctly; state changes (e.g. expanded, selected) are announced; labels and relationships are clear; no unnecessary or duplicate announcements.
1. Go here
2. Do this action
3. Expect this result

changeset-bot · 2026-04-03T20:36:03Z

⚠️ No Changeset found

Latest commit: 0fc3b0f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2026-04-03T20:46:27Z

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-6142

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

nikkimk · 2026-04-03T21:00:15Z

...02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md

@@ -30,7 +30,7 @@
 - [Phase 3: API migration](#phase-3-api-migration)
    - [What to do](#what-to-do)
    - [Property migration scenarios](#property-migration-scenarios)
-    - [API patterns (statics, warnings, and 1st-gen exports)](#api-patterns-statics-warnings-and-1st-gen-exports)
+    - [API patterns (statics and warnings)](#api-patterns-statics-and-warnings)


TOC automatic update

nikkimk · 2026-04-03T21:00:36Z

CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md

-    - [Factor rendering out of 1st-gen component](02_step-by-step/02_factor-rendering-out-of-1st-gen-component.md)
-    - [Move base class to 2nd-gen core](02_step-by-step/03_move-base-class-to-2nd-gen-core.md)
+    - [Understand the 1st-gen component structure](02_step-by-step/02_factor-rendering-out-of-1st-gen-component.md)
+    - [Create base class in 2nd-gen core](02_step-by-step/03_move-base-class-to-2nd-gen-core.md)


TOC automatic update

nikkimk · 2026-04-03T21:00:47Z

CONTRIBUTOR-DOCS/03_project-planning/01_objectives-and-strategy.md

 - [Strategy](#strategy)
    - [Disruptive vs. non-disruptive change](#disruptive-vs-non-disruptive-change)
-    - [Side-by-side development of 1st-gen and 2nd-gen](#side-by-side-development-of-1st-gen-and-2nd-gen)
+    - [Independent development of 1st-gen and 2nd-gen](#independent-development-of-1st-gen-and-2nd-gen)


TOC automatic update

nikkimk · 2026-04-03T21:03:36Z

CONTRIBUTOR-DOCS/02_style-guide/02_typescript/08_component-types.md

-    - [S1-only suffixing rule](#s1-only-suffixing-rule)
+    - [Naming rule](#naming-rule)
 - [File structure](#file-structure)
    - [Section order](#section-order)
    - [Section separators](#section-separators)
 - [Constant patterns](#constant-patterns)
    - [Sizes](#sizes)
    - [Variants with S1/S2 split](#variants-with-s1s2-split)
-    - [Variants without S1/S2 split](#variants-without-s1s2-split)
+    - [Simple variant arrays](#simple-variant-arrays)


TOC automatic update

nikkimk · 2026-04-03T21:05:19Z

2nd-gen/packages/swc/.storybook/guides/accessibility-guides/semantic_html_aria.mdx

+- [Cross-root ARIA delegation (explainer)](https://leobalter.github.io/cross-root-aria-delegation/) and [repository](https://github.com/leobalter/cross-root-aria-delegation).
+- [Reference target for cross-root ARIA (WICG explainer)](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/reference-target-explainer.md); [Can I use… `shadowrootreferencetarget`](https://caniuse.com/mdn-html_elements_template_shadowrootreferencetarget) for current support.
+- [How shadow DOM and accessibility are in conflict](https://blogs.igalia.com/alice/how-shadow-dom-and-accessibility-are-in-conflict/) — Alice Boxhall.
+- [Shadow DOM and accessibility: the trouble with ARIA](https://nolanlawson.com/2022/11/28/shadow-dom-and-accessibility-the-trouble-with-aria/) — Nolan Lawson.


**STOP:

All other changes past this point were automatic navigation updates to the CONTRIBUTOR GUIDES**

nikkimk added 2 commits April 3, 2026 15:54

chore: updated TOC for contributor docs

b4373d3

docs: added semenatic HTML and ARIA a11y docs

acf221e

nikkimk self-assigned this Apr 3, 2026

docs: moved to guide to storybook

9e4be05

nikkimk marked this pull request as ready for review April 3, 2026 20:58

nikkimk requested a review from a team as a code owner April 3, 2026 20:58

nikkimk and others added 3 commits April 3, 2026 16:58

Merge branch 'main' into nikkimk/a11y-docs-html-aria

a231978

docs: undo a11y docs in crontibutor guidelines

2a04eb7

docs: undo a11y docs in crontibutor guidelines

0fc3b0f

nikkimk commented Apr 3, 2026

View reviewed changes

caseyisonit added Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels Apr 3, 2026

cdransf approved these changes Apr 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: a11y docs html aria#6142

docs: a11y docs html aria#6142
nikkimk wants to merge 6 commits intomainfrom
nikkimk/a11y-docs-html-aria

nikkimk commented Apr 3, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Apr 3, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 3, 2026 •

edited

Loading

Uh oh!

nikkimk Apr 3, 2026

Uh oh!

nikkimk Apr 3, 2026

Uh oh!

nikkimk Apr 3, 2026

Uh oh!

nikkimk Apr 3, 2026

Uh oh!

nikkimk Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

nikkimk commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

Accessibility testing checklist

Uh oh!

changeset-bot bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

Uh oh!

nikkimk Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

nikkimk Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

nikkimk Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

nikkimk Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

nikkimk Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nikkimk commented Apr 3, 2026 •

edited

Loading

changeset-bot bot commented Apr 3, 2026 •

edited

Loading

github-actions bot commented Apr 3, 2026 •

edited

Loading