docs(breadcrumbs): update docs for accessibility and clarity (#5711)

rise-erpelding · nikkimk · web-flow · commit a718f57143db · 2025-08-28T17:02:14.000-04:00
* docs(breadcrumbs): update docs for accessibility and clarity

* docs(breadcrumbs): pr fixes

* Update packages/breadcrumbs/breadcrumb-item.md

Include disabled as a state

Co-authored-by: Nikki Massaro &lt;5090492+nikkimk@users.noreply.github.com&gt;

---------

Co-authored-by: Nikki Massaro &lt;5090492+nikkimk@users.noreply.github.com&gt;
diff --git a/packages/breadcrumbs/README.md b/packages/breadcrumbs/README.md
@@ -1,52 +1,55 @@
-## Description
+## Overview
+
+An `<sp-breadcrumbs>` shows hierarchy and navigational context for a user's location within an app. The `<sp-breadcrumbs>` component defines its list of items using child `<sp-breadcrumb-item>` elements placed in its default slot.
+
+[View the design documentation for this component.](https://spectrum.adobe.com/page/breadcrumbs/)
 
 ### Usage
 
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/breadcrumbs?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/breadcrumbs)
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/breadcrumbs?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/breadcrumbs)
 
-```
+```zsh
 yarn add @spectrum-web-components/breadcrumbs
 ```
 
 Import the side effectful registration of `<sp-breadcrumbs>` and `<sp-breadcrumb-item>` via:
 
-```
+```js
 import '@spectrum-web-components/breadcrumbs/sp-breadcrumbs.js';
 import '@spectrum-web-components/breadcrumbs/sp-breadcrumb-item.js';
 ```
 
 When looking to leverage the `Breadcrumbs` or `BreadcrumbItem` base class as a type and/or for extension purposes, do so via:
 
-```
-import { Breadcrumbs, BreadcrumbItem } from '@spectrum-web-components/breadcrumbs';
+```js
+import {
+    Breadcrumbs,
+    BreadcrumbItem,
+} from '@spectrum-web-components/breadcrumbs';
 ```
 
-## Example
+### Anatomy
 
-```html
-<sp-breadcrumbs>
-    <sp-breadcrumb-item value="1">Home</sp-breadcrumb-item>
-    <sp-breadcrumb-item value="2">Trend</sp-breadcrumb-item>
-    <sp-breadcrumb-item value="3">March 2019 Assets</sp-breadcrumb-item>
-</sp-breadcrumbs>
-```
+Breadcrumbs consist of several key parts:
 
-## Disabled
-
-`sp-breadcrumb-item` can have a `disabled` state which disables the events from the disabled item.
+- A breadcrumbs list, usually consisting of multiple [breadcrumb items](/components/breadcrumb-item), with a separator between each item.
+- A breadcrumbs title at the end of the list displaying the current location within the hierarchy.
+- A truncation menu may also appear, which displays all options within a breadcrumb. Within the menu, items are listed with the hierarchy ordered from the top (root) to the bottom, and will include the currently selected item. Breadcrumbs truncate when there isn't enough space to show all items, or when the list contains five or more levels. Truncation helps manage space and keep the most relevant breadcrumbs visible in deeply nested hierarchies.
 
 ```html
 <sp-breadcrumbs>
-    <sp-breadcrumb-item disabled value="1">Home</sp-breadcrumb-item>
-    <sp-breadcrumb-item value="2">Trend</sp-breadcrumb-item>
-    <sp-breadcrumb-item value="3">March 2019 Assets</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="home">Home</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="assets">March 2019 Assets</sp-breadcrumb-item>
 </sp-breadcrumbs>
 ```
 
-## Compact
+### Options
+
+#### Compact
 
-When needing to optimize for functional space of `sp-breadcrumbs`, the compact option is useful for reducing the height of the breadcrumbs while still maintaining the proper user context.
+When needing to optimize for functional space of `<sp-breadcrumbs>`, the `compact` property can be used to reduce the height of the breadcrumbs while still maintaining the proper user context.
 
 ```html
 <sp-breadcrumbs compact>
@@ -56,34 +59,52 @@ When needing to optimize for functional space of `sp-breadcrumbs`, the compact o
 </sp-breadcrumbs>
 ```
 
-## Links
+#### Overflowing
 
-By default, `sp-breadcrumbs` emits a `change` event when clicking on one of its children.
-However, there may be cases in which these should redirect to another page. This can be achieved by using the `href` attribute instead of `value`.
-Please note that the `change` event will no longer be triggered in this case.
+When space becomes limited or the maximum visible items are reached, the component automatically moves the first breadcrumbs into an action menu, adjusting dynamically as the window is resized.
+
+By default, the maximum number of visible breadcrumbs is 4, as recommended by [Spectrum Design](https://spectrum.adobe.com/page/breadcrumbs/#Don%E2%80%99t-show-too-many-breadcrumbs-at-once). You can override this by using the `max-visible-items` attribute. The `<sp-breadcrumbs>` component will always display the action menu and the breadcrumbs title, so the minimum number of visible items is 1.
+
+<sp-tabs selected="default" label="Overflow options">
+<sp-tab value="default">Default</sp-tab>
+<sp-tab-panel value="default">
 
 ```html
 <sp-breadcrumbs>
-    <sp-breadcrumb-item href="https://opensource.adobe.com/home">
-        Home
-    </sp-breadcrumb-item>
-    <sp-breadcrumb-item href="https://opensource.adobe.com/trend">
-        Trend
-    </sp-breadcrumb-item>
-    <sp-breadcrumb-item href="https://opensource.adobe.com/assets">
-        March 2019 Assets
-    </sp-breadcrumb-item>
+    <sp-breadcrumb-item value="your_stuff">Your stuff</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="team">Team</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="in_progress">In progress</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
 </sp-breadcrumbs>
 ```
 
-## Overflowing
+</sp-tab-panel>
+<sp-tab value="one-max-item">One maximum visible item</sp-tab>
+<sp-tab-panel value="one-max-item">
 
-When the space is limited or the maximum number of visible items is reached, the component will render the first breadcrumbs inside an action menu. If needed, the last breadcrumb item will be truncated and will render a tooltip with the full text.
+```html
+<sp-breadcrumbs max-visible-items="1">
+    <sp-breadcrumb-item value="your_stuff">Your stuff</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="team">Team</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="in_progress">In progress</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
+</sp-breadcrumbs>
+```
 
-As recommended by [Spectrum Design](https://spectrum.adobe.com/page/breadcrumbs/#Don%E2%80%99t-show-too-many-breadcrumbs-at-once), by default the maximum visible breadcrumbs is 4. If you want to override this, you can use the `max-visible-items` attribute.
+</sp-tab-panel>
+<sp-tab value="three-max-items">Three maximum visible items</sp-tab>
+<sp-tab-panel value="three-max-items">
 
 ```html
-<sp-breadcrumbs>
+<sp-breadcrumbs max-visible-items="3">
     <sp-breadcrumb-item value="your_stuff">Your stuff</sp-breadcrumb-item>
     <sp-breadcrumb-item value="team">Team</sp-breadcrumb-item>
     <sp-breadcrumb-item value="in_progress">In progress</sp-breadcrumb-item>
@@ -95,9 +116,37 @@ As recommended by [Spectrum Design](https://spectrum.adobe.com/page/breadcrumbs/
 </sp-breadcrumbs>
 ```
 
-### Show root
+</sp-tab-panel>
+<sp-tab value="resizable">Resizable</sp-tab>
+<sp-tab-panel value="resizable">
+
+These breadcrumbs are in a resizable container. Reduce the size of the container to see how the maximum number of visible items changes.
+
+```html
+<div style="border: 2px solid; padding: 20px; resize: both; overflow: auto;">
+    <sp-breadcrumbs max-visible-items="8">
+        <sp-breadcrumb-item value="your_stuff">Your stuff</sp-breadcrumb-item>
+        <sp-breadcrumb-item value="team">Team</sp-breadcrumb-item>
+        <sp-breadcrumb-item value="in_progress">In progress</sp-breadcrumb-item>
+        <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
+        <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
+        <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
+        <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
+        <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
+    </sp-breadcrumbs>
+</div>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+#### Show root
 
-Use the "root" slot to always render the first breadcrumb item, even if the breadcrumbs are overflowing.
+Use the `root` slot on the first breadcrumb item to always render the first breadcrumb item, even if the breadcrumbs are overflowing. The root will always show in addition to the number of items specified with `max-visible-items`.
+
+<sp-tabs selected="overflowing" auto label="Root slot variations">
+<sp-tab value="overflowing">Overflowing</sp-tab>
+<sp-tab-panel value="overflowing">
 
 ```html
 <sp-breadcrumbs>
@@ -112,9 +161,48 @@ Use the "root" slot to always render the first breadcrumb item, even if the brea
 </sp-breadcrumbs>
 ```
 
-## Custom Action Menu
+</sp-tab-panel>
+<sp-tab value="not-overflowing">Not overflowing</sp-tab>
+<sp-tab-panel value="not-overflowing">
+
+```html
+<sp-breadcrumbs>
+    <sp-breadcrumb-item slot="root" value="your_stuff">
+        Your stuff
+    </sp-breadcrumb-item>
+    <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
+</sp-breadcrumbs>
+```
+
+</sp-tab-panel>
+</sp-tabs>
 
-The component offers the possibility to replace the action menu's icon with a custom one using the `icon` slot. Moreover, for accesibility purposes you can provide an internationalized string for the menu label using the `menu-label` attribute.
+#### Links
+
+By default, `sp-breadcrumbs` emits a `change` event when clicking on one of its children.
+However, there may be cases in which clicking should redirect to another page. This can be achieved by using the `href` attribute instead of `value`.
+Please note that the `change` event will no longer be triggered in this case.
+
+```html
+<sp-breadcrumbs>
+    <sp-breadcrumb-item href="https://opensource.adobe.com/">
+        Home
+    </sp-breadcrumb-item>
+    <sp-breadcrumb-item href="https://opensource.adobe.com/trend">
+        Trend
+    </sp-breadcrumb-item>
+    <sp-breadcrumb-item href="https://opensource.adobe.com/assets">
+        March 2019 Assets
+    </sp-breadcrumb-item>
+</sp-breadcrumbs>
+```
+
+#### Custom Action Menu
+
+The component offers the possibility to replace the action menu's icon with a custom one using the `icon` slot. Moreover, for accessibility purposes you can provide an internationalized string for the menu label using the `menu-label` attribute.
 
 ```html
 <sp-breadcrumbs menu-label="Settings">
@@ -127,3 +215,22 @@ The component offers the possibility to replace the action menu's icon with a cu
     <sp-breadcrumb-item value="1">Preset #1</sp-breadcrumb-item>
 </sp-breadcrumbs>
 ```
+
+### Accessibility
+
+The `<sp-breadcrumbs>` component provides the following accessibility features:
+
+- Automatically sets `role="navigation"` to ensure proper semantic meaning for assistive technologies
+- Uses semantic markup by rendering a `<ul>` with each [`<sp-breadcrumb-item>`](/components/breadcrumb-item) assigned `role="listitem"`
+- The last breadcrumb item automatically receives `aria-current="page"` to indicate the current location
+- Sets `aria-label` based on the `label` property, defaulting to `"Breadcrumbs"` if none is provided
+- Each breadcrumb item is keyboard accessible with `tabindex="0"`
+- Provides an accessible [action menu](/components/action-menu) with keyboard navigation and screen reader support
+
+#### Best practices
+
+- **Limit breadcrumb depth**: Keep breadcrumbs to 4-5 levels maximum to avoid overwhelming users
+- **Use descriptive labels**: Each breadcrumb item should clearly identify the section or page
+- **Maintain consistent hierarchy**: Always start from the root and progress logically to the current page
+- **Handle overflow gracefully**: Use the `max-visible-items` property to control truncation behavior
+- **Provide meaningful menu labels**: Use the `menu-label` attribute to describe the overflow menu purpose
diff --git a/packages/breadcrumbs/breadcrumb-item.md b/packages/breadcrumbs/breadcrumb-item.md
@@ -1,58 +1,114 @@
 ## Overview
 
-For use within an `<sp-breadcrumbs>` element, an `<sp-breadcrumb-item>` represents a single item in a list.
+For use within an [`<sp-breadcrumbs>`](/components/breadcrumbs) element, an `<sp-breadcrumb-item>` represents a single item in a breadcrumbs list. The default slot contains the main content of the breadcrumb item.
 
 ### Usage
 
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/breadcrumbs?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/breadcrumbs)
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/breadcrumbs?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/breadcrumbs)
 
-```
+```zsh
 yarn add @spectrum-web-components/breadcrumbs
 ```
 
 Import the side effectful registration of `<sp-breadcrumb-item>` as follows:
 
-```
+```js
 import '@spectrum-web-components/breadcrumbs/sp-breadcrumb-item.js';
 ```
 
 When looking to leverage the `BreadcrumbItem` base class as a type and/or for extension purposes, do so via:
 
-```
+```js
 import { BreadcrumbItem } from '@spectrum-web-components/breadcrumbs';
 ```
 
-## Example
+### Anatomy
+
+The breadcrumb item consists of the following:
+
+- A clickable anchor (`<a>`) that contains the breadcrumb text and handles navigation
+- Text content as the main label displayed in the default slot, which becomes the clickable link text
+- A separator consisting of a chevron [UI icon component](/components/icons-ui/) (`<sp-icon-chevron100>`) that visually separates breadcrumb items
+- An optional [action menu](/components/action-menu) for displaying overflowed breadcrumb items
+
+### Options
+
+#### Value or href attributes
+
+When using the `href` attribute instead of the `value` attribute, the breadcrumb item behaves as a regular anchor link.
+
+<sp-tabs selected="link" label="Value or href attributes">
+<sp-tab value="using-value">Value</sp-tab>
+<sp-tab-panel value="using-value">
 
 ```html
 <sp-breadcrumbs>
-    <sp-breadcrumb-item value="1">Home</sp-breadcrumb-item>
-    <sp-breadcrumb-item value="2">Trend</sp-breadcrumb-item>
-    <sp-breadcrumb-item value="3">March 2019 Assets</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="home">Home</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="assets">March 2019 Assets</sp-breadcrumb-item>
 </sp-breadcrumbs>
 ```
 
-## Links
-
-When using the `href` attribute instead of the `value` attribute, the breadcrumb item behaves as a regular anchor link.
+</sp-tab-panel>
+<sp-tab value="using-link">Link</sp-tab>
+<sp-tab-panel value="using-link">
 
 ```html
 <sp-breadcrumbs>
-    <sp-breadcrumb-item href="/1">Home</sp-breadcrumb-item>
-    <sp-breadcrumb-item href="/2">Trend</sp-breadcrumb-item>
-    <sp-breadcrumb-item href="/3">March 2019 Assets</sp-breadcrumb-item>
+    <sp-breadcrumb-item href="/home">Home</sp-breadcrumb-item>
+    <sp-breadcrumb-item href="/trend">Trend</sp-breadcrumb-item>
+    <sp-breadcrumb-item href="/assets">March 2019 Assets</sp-breadcrumb-item>
 </sp-breadcrumbs>
 ```
 
-## Disabled
+</sp-tab-panel>
+</sp-tabs>
+
+#### With menu content
 
-Disabled breadcrumb items no longer receive focus and keyboard events.
+When breadcrumbs overflow, `<sp-breadcrumbs>` will create an `<sp-breadcrumb-item>` with an [`<sp-action-menu>`](/components/action-menu) that contains the full list of breadcrumb items in reading order.
+
+```html
+<sp-breadcrumbs max-visible-items="2">
+    <sp-breadcrumb-item slot="root" value="your_stuff">
+        Your stuff
+    </sp-breadcrumb-item>
+    <sp-breadcrumb-item value="team">Files</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
+</sp-breadcrumbs>
+```
+
+### States
+
+#### Disabled
+
+An `sp-breadcrumb-item` can have a `disabled` state which disables the events from that item.
 
 ```html
 <sp-breadcrumbs>
-    <sp-breadcrumb-item disabled value="1">Home</sp-breadcrumb-item>
-    <sp-breadcrumb-item disabled value="2">Trend</sp-breadcrumb-item>
-    <sp-breadcrumb-item value="3">March 2019 Assets</sp-breadcrumb-item>
+    <sp-breadcrumb-item disabled value="home">Home</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
+    <sp-breadcrumb-item value="assets">March 2019 Assets</sp-breadcrumb-item>
 </sp-breadcrumbs>
 ```
+
+### Accessibility
+
+The `<sp-breadcrumb-item>` component provides the following accessibility features:
+
+- Automatically applies `role="listitem"` to ensure proper semantic meaning for assistive technologies
+- The last breadcrumb item automatically receives `aria-current="page"` to indicate the current location
+- Applies `aria-disabled="true"` when the `disabled` property is set
+- Each breadcrumb item is keyboard accessible with `tabindex="0"`
+- Supports `Enter` key activation for navigation
+
+#### Best practices
+
+- **Provide meaningful text content**: Ensure each breadcrumb item has descriptive and meaningful labels
+- **Use proper hierarchy**: Place breadcrumb items in the correct order from root to current page
+- **Handle navigation events**: Listen for the `breadcrumb-select` event when using `value` instead of `href`
+- **Keep labels concise**: Use short, descriptive labels that clearly identify each level
