docs(tab): update tab docs and a11y #5586

aramos-adobe · 2025-07-07T11:49:24Z

Description

Ensure the full API is documented, including each property, slot, method, event, CSS property, and tokens in the component and along with accessibility concerns and/or decisions, linking to accessibility team documentation where applicable for the tab component.

Related issue(s)

SWC-414

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

changeset-bot · 2025-07-07T11:49:29Z

⚠️ No Changeset found

Latest commit: db5742a

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-07-07T11:51:08Z

📚 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-5586

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-07-07T11:53:59Z

Tachometer results

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

Rajdeepc · 2025-07-07T17:35:20Z

@aramos-adobe before adding the ready for review tag, could you please take a moment to ensure the description is clear and that the developer checklist has been followed? This will really help make the review process smoother for everyone. Appreciate your efforts and congrats on your PR first contribution. Woohoo!!

nikkimk

Some minor changes, but overall all looking good. I like the details you've added to the docs.

packages/tabs/tab.md

marissahuysentruyt

Nice work on this! I think there's some documentation changes that need to be made to clear up the focused state section. To me, they conflicted with the accessibility portion at the bottom, but I left some comments to try to connect my thoughts.

packages/tabs/tab.md

marissahuysentruyt · 2025-07-11T15:57:13Z

packages/tabs/tab.md

+        slot="icon"
+        label="Checking your work"
+        aria-label="Tab w/ checkmark"


I'd have to check with Nikki again, but would we want the label and aria-label to be the same, that way screen reader users get the same experience & information?

When I tested this in Safari, VoiceOver also announces: "Tab w slash checkmark" instead of what this was probably going for "Tab with checkmark."

Or maybe the aria-label replaces label on sp-tab?

Now that I think of it, it makes sense to have only the aria-label exist for icon only situations and it should be on sp-tab

Rajdeepc · 2025-07-15T06:25:28Z

packages/tabs/tab.md

 yarn add @spectrum-web-components/tabs
 ```

 Import the side effectful registration of `<sp-tab>` via:

-```
+```ts


Suggested change

```ts

```js

Rajdeepc · 2025-07-15T06:25:35Z

packages/tabs/tab.md

 import '@spectrum-web-components/tabs/sp-tab.js';
 ```

 When looking to leverage the `Tab` base class as a type and/or for extension purposes, do so via:

+```ts


Suggested change

```ts

```js

Rajdeepc · 2025-07-15T06:26:56Z

packages/tabs/tab.md

+```html
+<sp-tab value="label" label="Label"></sp-tab>
+```


can you also surface the information whether users need to add both the attributes or not to display a label?

Do you mean both the value and label attributes?

I added a line about what the difference was, if that helps.

And then I also updated some of the Accessibility best practices below to be a bit more explicit, it looks like you can use the label attribute or put the text in the slot content.

nit: If you are not wrapping under sp-tabs voiceover or keybaord navigation will not work here.

See my suggestion above

marissahuysentruyt

Nice work on this! My comments were all addressed from the other day.

I did leave one more comment on the aria-label and label conversation we were having. I went back and read Nikki's comment about needing label on the sp-icon element, so I'd would need clarity from her on the correct usage of label AND aria-label, so I tagged her just in case.

I'm going to approve so that if it's already good to go in her eyes, y'all can merge iiiiiiit. 👍

marissahuysentruyt · 2025-07-15T18:10:59Z

packages/tabs/tab.md

-        attribute to define their alignment
-    </sp-tab-panel>
+<sp-tab value="complete" aria-label="Tab with checkmark">
+    <sp-icon-checkmark slot="icon"></sp-icon-checkmark>


I would double check with @nikkimk once more on the aria-label and label attributes! From her first comment, it sounded like we still need the label="Checking your work", so we should determine where the aria-label needs to go, and if it should read the same as the label (to me, this sounds like alt text still instead of providing the same info that a label might provide).

rise-erpelding · 2025-07-15T22:34:45Z

packages/tabs/tab.md

+    <sp-icon-checkmark
+        slot="icon"
+        label="Checking your work"
+    ></sp-icon-checkmark>


@nikkimk would love some feedback on this one after Marissa's feedback! Do we want it like this, or how it was previously, or something else?

This will not be picked up by screen-readers. You would need to wrap it under sp-tabs which manages the focus and tab stops for all children.

@rajdeep is correct. We need to make sure we shoe the tab wrapped in a tabs component.

As part of the documentation standards, "The example code must show the component with enough context to demonstrate how to use it with other elements in an accessible way. See how the examples in packages/help-text/README.md show the component used with field elements."

So even though we are documenting a tab, our examples should still show how to use that tab as part of tabs. This serves many purposes:

It ensures that our documentation pages are accessible.

It shows our consumers how to use the tab with tabs in an accessbile way.

It allows the accessibility team to use our documentation to audit our components as we intend them to work.

Rajdeepc

Few things to consider.

Always wrap tabs in <sp-tabs> for proper focus management. There are quite a few instances where we are only adding sp-tab which will not focus.
Use label attribute when you want visible text + icon
Use aria-label attribute when you want icon-only tabs
Don't add aria-label to the icons - let the tab's label/aria-label handle the accessible name

Rajdeepc · 2025-07-16T08:08:07Z

packages/tabs/tab.md

+```html
+<sp-tab value="label" label="Label"></sp-tab>
+```


nit: If you are not wrapping under sp-tabs voiceover or keybaord navigation will not work here.

Rajdeepc · 2025-07-16T08:10:01Z

packages/tabs/tab.md

+    <sp-icon-checkmark
+        slot="icon"
+        label="Checking your work"
+    ></sp-icon-checkmark>


This will not be picked up by screen-readers. You would need to wrap it under sp-tabs which manages the focus and tab stops for all children.

nikkimk

Thanks for picking this up. I've added some additional suggestions and feedback in the comments.

nikkimk · 2025-07-16T13:10:53Z

packages/tabs/tab.md

+    <sp-icon-checkmark
+        slot="icon"
+        label="Checking your work"
+    ></sp-icon-checkmark>


@rajdeep is correct. We need to make sure we shoe the tab wrapped in a tabs component.

As part of the documentation standards, "The example code must show the component with enough context to demonstrate how to use it with other elements in an accessible way. See how the examples in packages/help-text/README.md show the component used with field elements."

So even though we are documenting a tab, our examples should still show how to use that tab as part of tabs. This serves many purposes:

It ensures that our documentation pages are accessible.

It shows our consumers how to use the tab with tabs in an accessbile way.

It allows the accessibility team to use our documentation to audit our components as we intend them to work.

packages/tabs/tab.md

nikkimk · 2025-07-16T14:38:13Z

packages/tabs/tab.md

+```html
+<sp-tab value="label" label="Label"></sp-tab>
+```


See my suggestion above

packages/tabs/tab.md

nikkimk · 2025-07-16T14:40:52Z

packages/tabs/tab.md

 ```html
-<sp-tabs selected="1" direction="vertical">
+<sp-tabs selected="2">
    <sp-tab label="Tab 1" value="1"></sp-tab>
-    <sp-tab value="2">Tab 2</sp-tab>
-    <sp-tab label="Tab 3" value="3">
-        <sp-icon-checkmark slot="icon"></sp-icon-checkmark>
-    </sp-tab>
-    <sp-tab vertical value="4">
-        Tab 4
-        <sp-icon-checkmark slot="icon"></sp-icon-checkmark>
-    </sp-tab>
-    <sp-tab-panel value="1">
-        Content for Tab 1 which uses an attribute for its content delivery
-    </sp-tab-panel>
-    <sp-tab-panel value="2">
-        Content for Tab 2 which uses its text content directly
-    </sp-tab-panel>
-    <sp-tab-panel value="3">
-        Content for Tab 3 which uses an attribute with a
-        <code>[slot="icon"]</code>
-        child
-    </sp-tab-panel>
-    <sp-tab-panel value="4">
-        Content for Tab 4 which uses both its text content and a
-        <code>[slot="icon"]</code>
-        child displayed using the
-        <code>[vertical]</code>
-        attribute to define their alignment
-    </sp-tab-panel>
+    <sp-tab label="Tab 2" value="2"></sp-tab>
+    <sp-tab label="Tab 3" value="3"></sp-tab>
 </sp-tabs>
 ```


Since we can't show focused without stealing keyboard focus, we could probably remove the example here.

Co-authored-by: Nikki Massaro <[email protected]>

rise-erpelding · 2025-07-17T05:22:54Z

packages/tabs/tab.md


-An `<sp-tab>` element surfaces a `label` attribute to serve as its default text content when none is available in the DOM. An icon may be assigned to the element via the `icon` slot; e.g. `<sp-tab><svg slot="icon" aria-label="Tab w/ Icon">...</svg></sp-tab>`. Associate an `<sp-tab>` element with the `<sp-tab-panel>` that represents its content with the `value` attribute.
+An `<sp-tab>` element surfaces a `label` attribute to serve as its default text content when none is available in the DOM. An icon may be assigned to the element via the `icon` slot; e.g. `<sp-tab><svg slot="icon" label="Tab with icon">...</svg></sp-tab>`. Associate an `<sp-tab>` element with the `<sp-tab-panel>` that represents its content with the `value` attribute.


Correct me if I'm wrong, my understanding of how icon works from checking the code and the documentation is that if the label attribute is set, it sets aria-label on for us? I made a few small updates to the documentation to reflect this (changing instances of aria-label to label), but if that's wrong, please let me know, happy to revert.

The default slot and the label attribute both can set the label internally with a <label> element.

rise-erpelding · 2025-07-17T05:29:31Z

packages/tabs/tab.md

+
+#### Icon only
+
+For tabs that have an icon and no visible label, the icon should have a `label` attribute in order to set the `aria-label` of the icon. Icons should not be used just as decoration. If the tab item does not have a visible label, it must still have a tooltip to disclose the label.


I see this comment about needing a tooltip and the previous comments about wanting to provide "enough context to demonstrate how to use it with other elements in an accessible way" and it feels like tooltip could be part of that. Thoughts? Should I be implementing the tooltip here?

We could provide an example here that uses tooltip and a label attribute but we should also make very clear that a tooltip is no substitute for a label.

Does tabs support a tooltip? I did look into this a couple of times and wasn't able to get a tooltip rendered here.

nikkimk

Luggage gets tagged meticulously (LGTM)

nikkimk · 2025-07-21T16:42:09Z

packages/tabs/tab.md


-An `<sp-tab>` element surfaces a `label` attribute to serve as its default text content when none is available in the DOM. An icon may be assigned to the element via the `icon` slot; e.g. `<sp-tab><svg slot="icon" aria-label="Tab w/ Icon">...</svg></sp-tab>`. Associate an `<sp-tab>` element with the `<sp-tab-panel>` that represents its content with the `value` attribute.
+An `<sp-tab>` element surfaces a `label` attribute to serve as its default text content when none is available in the DOM. An icon may be assigned to the element via the `icon` slot; e.g. `<sp-tab><svg slot="icon" label="Tab with icon">...</svg></sp-tab>`. Associate an `<sp-tab>` element with the `<sp-tab-panel>` that represents its content with the `value` attribute.


The default slot and the label attribute both can set the label internally with a <label> element.

nikkimk · 2025-07-21T16:43:40Z

packages/tabs/tab.md

+
+#### Icon only
+
+For tabs that have an icon and no visible label, the icon should have a `label` attribute in order to set the `aria-label` of the icon. Icons should not be used just as decoration. If the tab item does not have a visible label, it must still have a tooltip to disclose the label.


We could provide an example here that uses tooltip and a label attribute but we should also make very clear that a tooltip is no substitute for a label.

docs(tab): update tab docs and a11y

90e61c1

aramos-adobe requested a review from a team as a code owner July 7, 2025 11:49

aramos-adobe self-assigned this Jul 7, 2025

Rajdeepc added ready-for-review and removed ready-for-review labels Jul 7, 2025

aramos-adobe added Documentation ready-for-review labels Jul 8, 2025

nikkimk requested changes Jul 10, 2025

View reviewed changes

packages/tabs/tab.md Show resolved Hide resolved

packages/tabs/tab.md Outdated Show resolved Hide resolved

packages/tabs/tab.md Outdated Show resolved Hide resolved

packages/tabs/tab.md Outdated Show resolved Hide resolved

packages/tabs/tab.md Outdated Show resolved Hide resolved

marissahuysentruyt requested changes Jul 10, 2025

View reviewed changes

aramos-adobe added 2 commits July 10, 2025 15:48

Merge branch 'main' into aramos-adobe/tab-docs-audit

9fcea0d

docs(tab): adding pr edits

a9d8dfb

aramos-adobe requested review from nikkimk and marissahuysentruyt July 11, 2025 14:26

marissahuysentruyt reviewed Jul 11, 2025

View reviewed changes

docs(tab): correcting icon only doc

d1c887e

aramos-adobe requested a review from marissahuysentruyt July 11, 2025 20:59

Rajdeepc requested changes Jul 15, 2025

View reviewed changes

marissahuysentruyt approved these changes Jul 15, 2025

View reviewed changes

rise-erpelding and others added 2 commits July 15, 2025 12:15

docs(tab): pr review updates

7e7378f

Merge branch 'main' into aramos-adobe/tab-docs-audit

d052d65

rise-erpelding reviewed Jul 15, 2025

View reviewed changes

rise-erpelding requested a review from Rajdeepc July 15, 2025 22:34

Rajdeepc reviewed Jul 16, 2025

View reviewed changes

nikkimk requested changes Jul 16, 2025

View reviewed changes

rise-erpelding and others added 2 commits July 16, 2025 10:28

docs(tab): apply Nikki suggestions from code review

53a487a

Co-authored-by: Nikki Massaro <[email protected]>

docs(tab): clean up

31f6953

Merge branch 'main' into aramos-adobe/tab-docs-audit

bbaa356

rise-erpelding reviewed Jul 17, 2025

View reviewed changes

rise-erpelding requested review from Rajdeepc and nikkimk July 17, 2025 05:29

Rajdeepc approved these changes Jul 17, 2025

View reviewed changes

nikkimk approved these changes Jul 21, 2025

View reviewed changes

nikkimk and others added 2 commits July 21, 2025 17:12

Merge branch 'main' into aramos-adobe/tab-docs-audit

7f060c2

Merge branch 'main' into aramos-adobe/tab-docs-audit

db5742a


		An `<sp-tab>` element surfaces a `label` attribute to serve as its default text content when none is available in the DOM. An icon may be assigned to the element via the `icon` slot; e.g. `<sp-tab><svg slot="icon" aria-label="Tab w/ Icon">...</svg></sp-tab>`. Associate an `<sp-tab>` element with the `<sp-tab-panel>` that represents its content with the `value` attribute.
		An `<sp-tab>` element surfaces a `label` attribute to serve as its default text content when none is available in the DOM. An icon may be assigned to the element via the `icon` slot; e.g. `<sp-tab><svg slot="icon" label="Tab with icon">...</svg></sp-tab>`. Associate an `<sp-tab>` element with the `<sp-tab-panel>` that represents its content with the `value` attribute.


		#### Icon only

		For tabs that have an icon and no visible label, the icon should have a `label` attribute in order to set the `aria-label` of the icon. Icons should not be used just as decoration. If the tab item does not have a visible label, it must still have a tooltip to disclose the label.

docs(tab): update tab docs and a11y #5586

Are you sure you want to change the base?

docs(tab): update tab docs and a11y #5586

Conversation

aramos-adobe commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issue(s)

Author's checklist

Reviewer's checklist

Uh oh!

changeset-bot bot commented Jul 7, 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 Jul 7, 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 Jul 7, 2025

Tachometer results

Uh oh!

Rajdeepc commented Jul 7, 2025

Uh oh!

nikkimk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marissahuysentruyt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt 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!

Rajdeepc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aramos-adobe commented Jul 7, 2025 •

edited

Loading

changeset-bot bot commented Jul 7, 2025 •

edited

Loading

github-actions bot commented Jul 7, 2025 •

edited

Loading

rise-erpelding Jul 17, 2025 •

edited

Loading