docs(topnav): top nav docs accessibility audit #5724

marissahuysentruyt · 2025-09-10T16:59:23Z

Description

This PR adds to the sp-top-nav and sp-top-nav-item component documentation, with more complete API documentation, accessibility guidance, and practical usage examples.

Follows documentation standard format
Documents properties, slots, events, anatomy, states, behaviors
Expanded accessibility information to detail any ARIA attributes, keyboard interactions, and best practices
Added more examples to demo top nav/top nav item options

Motivation and context

The existing sidenav documentation was incomplete and lacked API coverage, and did not follow SWC's recommended format. This work should also now make the documentation accessible for future audits.

Related issue(s)

Addresses SWC-422

Screenshots (if appropriate)

N/A - Documentation changes only

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed 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

Complete API documentation verification
1. Go to the updated top nav documentation
  - top nav (parent) component
  - top nav item
2. Verify all properties, slots, methods, events, etc. are documented
3. Please check for accuracy, correct grammar/punctuation, spelling, etc.
Accessibility documentation validation
1. Review the accessibility section in the documentation
  - top nav (parent) component
  - top nav item
2. Verify accessibility concerns and decisions are clearly documented
Example accessibility validation
1. Review all code examples in the documentation
  - top nav (parent) component
  - top nav item
2. Test examples with screen readers and keyboard navigation
3. Expect all examples to meet accessibility standards

Device review

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

changeset-bot · 2025-09-10T16:59:27Z

⚠️ No Changeset found

Latest commit: d3e8acf

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 · 2025-09-10T17:01:24Z

📚 Branch Preview

🔍 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-5724

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.

github-actions · 2025-09-10T17:04:13Z

Tachometer results

Currently, no packages are changed by this PR...

marissahuysentruyt · 2025-09-10T19:06:54Z

packages/top-nav/README.md

+</sp-tab-panel>
+</sp-tabs>
+
+#### Other properties


Any thoughts on a different heading for this? I tried to keep some of the original examples, but it ended up being sort of hodge-podge of examples to lump together (hence "other properties").

Hmmm, you could move this <sp-tabs> up above sizes, leave it without a heading, then put Sizes down below with the #### Sizes heading. But it's also fine as it is.

ah yes! I think I like this better- thanks!

packages/top-nav/README.md

packages/top-nav/top-nav-item.md

rise-erpelding

This looks great! I called out a few things, mostly questions that may or may not need addressing, plus some syntax-y type things, I wouldn't consider any of that really blocking so I'm going to approve. Happy to take another look at this after you make changes though, if you want!

rise-erpelding · 2025-09-11T19:42:22Z

packages/top-nav/README.md

-### Example
+### Anatomy
+
+The `sp-top-nav`` component consists of the following parts:


Suggested change

The `sp-top-nav`` component consists of the following parts:

The `sp-top-nav` component consists of the following parts:

rise-erpelding · 2025-09-11T19:55:14Z

packages/top-nav/top-nav-item.md

+    <sp-top-nav-item href="#pam">Pam</sp-top-nav-item>
+    <sp-top-nav-item href="#phyllis">Phyllis</sp-top-nav-item>
+    <sp-top-nav-item href="#angela" disabled>Angela</sp-top-nav-item>
+    <sp-top-nav-item href="#meredith">Meredith</sp-top-nav-item>


rise-erpelding · 2025-09-11T19:58:05Z

packages/top-nav/top-nav-item.md

+The `sp-top-nav-item` consists of the following parts:
+
+- **Default slot**: text content for the navigation item
+- **Label**: Sets a visually-hidden `aria-label` on the item


I wanted to ask about this one. At first, I was wondering if we should set label on some of the examples here, but then I saw the best practices note saying to use label sparingly. But it also says you can use it if "screen reader text is significantly different from visible text," so maybe it's useful instead to show an example where that's used? Maybe an icon-only item?

rise-erpelding · 2025-09-11T20:03:02Z

packages/top-nav/top-nav-item.md

+
+### Anatomy
+
+The `sp-top-nav-item` consists of the following parts:


Do we want brackets? I think there are other instances of this happening, but I won't point out all of them since I know left a lot of comments already on the sidenav PR.

Suggested change

The `sp-top-nav-item` consists of the following parts:

The `<sp-top-nav-item>` consists of the following parts:

rise-erpelding · 2025-09-11T20:07:12Z

packages/top-nav/top-nav-item.md

+```html
+<sp-top-nav
+    selected="https://opensource.adobe.com/spectrum-web-components/components/top-nav-item/#dwight"
+>
+    <sp-top-nav-item href="#michael">Michael</sp-top-nav-item>
+    <sp-top-nav-item href="#dwight" selected>Dwight</sp-top-nav-item>
+    <sp-top-nav-item href="#kevin">Kevin</sp-top-nav-item>
+    <sp-top-nav-item href="#jim">Jim</sp-top-nav-item>
+</sp-top-nav>
+```


When I load the page, I don't see Dwight selected. Is that expected, because the selected url in <sp-top-nav> doesn't match the preview url?

I took it to be expected. When I change this url to the localhost version, Dwight is selected. I'm hoping 🤞 that once this merges and deploys that it would work.

as is (with the production URL): no styles difference

with the localhost: selected styles look to be applied

rise-erpelding · 2025-09-11T20:21:46Z

packages/top-nav/README.md

+        Home
+    </sp-top-nav-item>
+    <sp-top-nav-item href="#services">Services</sp-top-nav-item>
+    <sp-top-nav-item href="#about">About</sp-top-nav-item>


Does it matter if this item doesn't have selected?

rise-erpelding · 2025-09-11T20:27:10Z

packages/top-nav/README.md

+</sp-tab-panel>
+</sp-tabs>
+
+#### Other properties


Hmmm, you could move this <sp-tabs> up above sizes, leave it without a heading, then put Sizes down below with the #### Sizes heading. But it's also fine as it is.

nikkimk

I have a few changes and some questions.

nikkimk · 2025-09-12T14:44:04Z

packages/top-nav/README.md

-### Example
+### Anatomy
+
+The `sp-top-nav`` component consists of the following parts:


Suggested change

The `sp-top-nav`` component consists of the following parts:

The `<sp-top-nav>` component consists of the following parts:

nikkimk · 2025-09-12T17:28:46Z

packages/top-nav/README.md

+</sp-tab-panel>
+</sp-tabs>
+
+#### Other properties


I noticed a selectionIndicatorStyle property in the API(https://swcpreviews.z13.web.core.windows.net/pr-5724/docs/components/top-nav/api/#attributes-and-properties). We should probably include information about it.

I have some questions about that property! I can definitely include more info on it, but I'm unsure how to use it properly.

Because this property is tied to the window.location.href, when I try to manually set it, it automatically gets reset to noSelectionStyles since the URL of the docs page doesn't actually match the selected URL I defined in the demo. I think I have fixed up the examples to properly show the selection indicator once this is merged, (for example, when you run this locally, use the localhost:8080 URL in place of opensource.adobe.com/spectrum-web-components), but I can't quite figure out how to "use" selectionIndicatorStyle.

nikkimk · 2025-09-12T17:31:09Z

packages/top-nav/README.md

+        Home
+    </sp-top-nav-item>
+    <sp-top-nav-item href="#services">Services</sp-top-nav-item>
+    <sp-top-nav-item href="#about">About</sp-top-nav-item>


The selection indicator is not showing here. Does it require a selectionIndicatorStyle value?

The selection indicator is only triggered after a selection is made. I believe it's JS only. To be frank, I'm having a tough time figuring out how to even document this, as it seems like it just keeps getting overridden.

nikkimk · 2025-09-12T17:31:57Z

packages/top-nav/top-nav-item.md

+<sp-top-nav>
+    <sp-top-nav-item href="#pam">Pam</sp-top-nav-item>
+    <sp-top-nav-item href="#phyllis">Phyllis</sp-top-nav-item>
+    <sp-top-nav-item href="#angela" disabled>Angela</sp-top-nav-item>
+    <sp-top-nav-item href="#meredith">Meredith</sp-top-nav-item>


nikkimk · 2025-09-12T17:32:30Z

packages/top-nav/top-nav-item.md

+    selected="https://opensource.adobe.com/spectrum-web-components/components/top-nav-item/#dwight"
+>
+    <sp-top-nav-item href="#michael">Michael</sp-top-nav-item>
+    <sp-top-nav-item href="#dwight" selected>Dwight</sp-top-nav-item>


The selection indicator is not showing here. Does the <sp-top-nav> require a selectionIndicatorStyle value?

marissahuysentruyt self-assigned this Sep 10, 2025

marissahuysentruyt added a11y Issues related to accessibility Documentation Component: Top Nav labels Sep 10, 2025

marissahuysentruyt commented Sep 10, 2025

View reviewed changes

packages/top-nav/README.md Outdated Show resolved Hide resolved

marissahuysentruyt commented Sep 10, 2025

View reviewed changes

packages/top-nav/README.md Outdated Show resolved Hide resolved

marissahuysentruyt commented Sep 10, 2025

View reviewed changes

packages/top-nav/top-nav-item.md Outdated Show resolved Hide resolved

marissahuysentruyt added 2 commits September 10, 2025 16:02

docs(topnav): update top-nav docs

2bc9807

docs(topnav): add top-nav-item documentation

49db7c8

marissahuysentruyt force-pushed the marissahuysentruyt/swc-422-top-nav-docs-audit branch from e36bd60 to 49db7c8 Compare September 10, 2025 20:03

marissahuysentruyt added the ready-for-review label Sep 10, 2025

marissahuysentruyt marked this pull request as ready for review September 10, 2025 20:04

marissahuysentruyt requested a review from a team as a code owner September 10, 2025 20:04

marissahuysentruyt changed the title ~~docs(topnav): top nav documentation a11y audit~~ docs(topnav): top nav docs accessibility audit Sep 10, 2025

rise-erpelding approved these changes Sep 11, 2025

View reviewed changes

nikkimk requested changes Sep 12, 2025

View reviewed changes

marissahuysentruyt added 2 commits September 12, 2025 17:08

docs(topnav): use brackets when referring to components

af4635e

docs(topnav): fix selection indicator for selected items

d3e8acf

marissahuysentruyt requested a review from nikkimk September 17, 2025 15:00

	The `sp-top-nav`` component consists of the following parts:
	The `sp-top-nav` component consists of the following parts:


		### Anatomy

		The `sp-top-nav-item` consists of the following parts:

	The `sp-top-nav-item` consists of the following parts:
	The `<sp-top-nav-item>` consists of the following parts:

	The `sp-top-nav`` component consists of the following parts:
	The `<sp-top-nav>` component consists of the following parts:

docs(topnav): top nav docs accessibility audit #5724

Are you sure you want to change the base?

docs(topnav): top nav docs accessibility audit #5724

Uh oh!

Conversation

marissahuysentruyt commented Sep 10, 2025 • 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

Uh oh!

changeset-bot bot commented Sep 10, 2025 • 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 Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Sep 10, 2025

Tachometer results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nikkimk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marissahuysentruyt commented Sep 10, 2025 •

edited

Loading

changeset-bot bot commented Sep 10, 2025 •

edited

Loading

github-actions bot commented Sep 10, 2025 •

edited

Loading