docs(tags): update a11y docs #5676

cdransf · 2025-08-06T17:25:32Z

Description

Improving the accessibility documentation of components.

Related issue(s)

SWC-416

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

Device review

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

changeset-bot · 2025-08-06T17:25:35Z

⚠️ No Changeset found

Latest commit: 9ce7536

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-08-06T17:27:19Z

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

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-08-06T17:30:07Z

Tachometer results

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

packages/tags/README.md

Rajdeepc · 2025-08-08T14:21:56Z

packages/tags/README.md

+`<sp-tags>` is a `role="list"` container that manages a collection of `Tag` elements. It has an `aria-label` attribute that defaults to "Tags".
+
+`<sp-tags>` uses the roving tabindex pattern for efficient keyboard navigation. `Tab` enters the collection, arrow keys navigate between tags, and only deletable tags are focusable. The container provides `role="list"` semantics with each tag as a `role="listitem"` for proper screen reader support.


This is great but can we extend this a bit and make it more granular for the users? I was thinking can we add Mouse and keyboard interaction sections under Accessibility and add the usage patterns for the same.

**Mouse** Read-only tags: Do not get mouse functionality besides a mouse cursor on hover and do not have interactive functionality. **Keyboard** Read-only tags: Can not be operated by a keyboard and have no interactive functionality.

rise-erpelding

I know Rajdeep has a few comments here, and I added a couple more that I don't consider to be blockers -- looks good to me!

rise-erpelding · 2025-08-08T18:55:16Z

packages/tags/README.md

+- **Tags**: The container component (`<sp-tags>`) that manages a collection of `Tag` elements.
+- **Tag**: The individual tag element (`<sp-tag>`) that represents a single tag. [Read more about the `Tag` component.](/components/tag/)
+
+### Examples


I don't think there's anything wrong with the examples as they are right now, but they could be consolidated similar to how other components have been done by using tabs.

Or, honestly, we don't need to show 3 different examples for tags to show no visual, avatar, icon, etc., since that can be covered by the singular tag component, so one single example might be fine.

Not a blocker as far as I'm concerned, just some food for thought!

rise-erpelding · 2025-08-08T19:53:21Z

packages/tags/README.md

+- **Tags**: The container component (`<sp-tags>`) that manages a collection of `Tag` elements.
+- **Tag**: The individual tag element (`<sp-tag>`) that represents a single tag. [Read more about the `Tag` component.](/components/tag/)
+
+### Examples

 ```html-live


Is there a preference between html and html-live? I see more html in the components we've already done but am not sure if there's a specific preference.

marissahuysentruyt

Nice work! For clarity, I think maybe we should add either some headings for the different variant options, but other than that, I only have suggestions!

marissahuysentruyt · 2025-08-08T20:26:11Z

packages/tags/README.md

+
+### Accessibility
+
+`<sp-tags>` is a `role="list"` container that manages a collection of `Tag` elements. It has an `aria-label` attribute that defaults to "Tags".


Just to sort of follow Rajdeeps suggestions, what do you think about changing "Tag elements" to "` elements?

marissahuysentruyt · 2025-08-08T20:26:47Z

packages/tags/README.md

+- **Tags**: The container component (`<sp-tags>`) that manages a collection of `Tag` elements.
+- **Tag**: The individual tag element (`<sp-tag>`) that represents a single tag. [Read more about the `Tag` component.](/components/tag/)
+
+### Examples


Do you think we should add any additional headings to like, name the tag variants? Or at least have a heading for "With an image" or "With an icon" something? We could do a set of tabs, too.

Just a thought!

Also- should this be "Examples" or "Options?" Looks like the documentation structure has "Options" instead.

marissahuysentruyt · 2025-08-08T20:31:17Z

packages/tags/README.md

+
+`<sp-tags>` is a `role="list"` container that manages a collection of `Tag` elements. It has an `aria-label` attribute that defaults to "Tags".
+
+`<sp-tags>` uses the roving tabindex pattern for efficient keyboard navigation. `Tab` enters the collection, arrow keys navigate between tags, and only deletable tags are focusable. The container provides `role="list"` semantics with each tag as a `role="listitem"` for proper screen reader support.


oh oh oh! I was just looking into roving tabindex. Want to link to the documentation?

/tools/roving-tab-index

Co-authored-by: Rajdeep Chandra <[email protected]>

cdransf self-assigned this Aug 6, 2025

cdransf marked this pull request as ready for review August 6, 2025 17:31

cdransf requested a review from a team as a code owner August 6, 2025 17:31

docs(tags): update a11y docs

ac54c75

cdransf force-pushed the cdransf/tags-docs-audit branch from b075661 to ac54c75 Compare August 6, 2025 17:33

cdransf requested review from nikkimk, caseyisonit, rise-erpelding and marissahuysentruyt August 6, 2025 21:19

cdransf added the ready-for-review label Aug 7, 2025

Rajdeepc reviewed Aug 8, 2025

View reviewed changes

rise-erpelding approved these changes Aug 8, 2025

View reviewed changes

marissahuysentruyt reviewed Aug 8, 2025

View reviewed changes

cdransf and others added 2 commits August 10, 2025 20:29

Update packages/tags/README.md

6b7eda3

Co-authored-by: Rajdeep Chandra <[email protected]>

Update packages/tags/README.md

9ce7536

Co-authored-by: Rajdeep Chandra <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(tags): update a11y docs #5676

docs(tags): update a11y docs #5676

cdransf commented Aug 6, 2025

Uh oh!

changeset-bot bot commented Aug 6, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Aug 6, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Aug 6, 2025

Uh oh!

Uh oh!

Uh oh!

Rajdeepc Aug 8, 2025

Uh oh!

rise-erpelding left a comment

Uh oh!

rise-erpelding Aug 8, 2025

Uh oh!

rise-erpelding Aug 8, 2025

Uh oh!

marissahuysentruyt left a comment

Uh oh!

marissahuysentruyt Aug 8, 2025

Uh oh!

marissahuysentruyt Aug 8, 2025

Uh oh!

marissahuysentruyt Aug 8, 2025

Uh oh!

marissahuysentruyt Aug 8, 2025

Uh oh!

Uh oh!

		`<sp-tags>` is a `role="list"` container that manages a collection of `Tag` elements. It has an `aria-label` attribute that defaults to "Tags".

		`<sp-tags>` uses the roving tabindex pattern for efficient keyboard navigation. `Tab` enters the collection, arrow keys navigate between tags, and only deletable tags are focusable. The container provides `role="list"` semantics with each tag as a `role="listitem"` for proper screen reader support.


		### Accessibility

		`<sp-tags>` is a `role="list"` container that manages a collection of `Tag` elements. It has an `aria-label` attribute that defaults to "Tags".

docs(tags): update a11y docs #5676

Are you sure you want to change the base?

docs(tags): update a11y docs #5676

Conversation

cdransf commented Aug 6, 2025

Description

Related issue(s)

Author's checklist

Reviewer's checklist

Device review

Uh oh!

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

Tachometer results

Uh oh!

Uh oh!

Uh oh!

Rajdeepc Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

rise-erpelding Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

rise-erpelding Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt left a comment

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

changeset-bot bot commented Aug 6, 2025 •

edited

Loading

github-actions bot commented Aug 6, 2025 •

edited

Loading