Skip to content

Commit

Permalink
feat: DAYL-89 Improve Breadcrumb a11y docn (#5128)
Browse files Browse the repository at this point in the history 
Adds Accessibility tag to relevant properties, removes lower level Accessibility sections, and adds a top level Accessibility section.

Also removes "required" from `text` property (as discussed, since this is essential for all usages, not just for accessibility purposes) and updates readme-specific Property tables to align with the descriptions used in code (so that the GitHub reading experience aligns with the Daylight site).
  • Loading branch information
@geurts
geurts authored Nov 27, 2024
1 parent 01a17c9 commit 02f45bf
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 60 deletions.
112 changes: 54 additions & 58 deletions components/breadcrumbs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,124 +28,120 @@ Breadcrumbs are a way-finding tool that helps users understand where they are w
<!-- docs: end donts -->
<!-- docs: end best practices -->

## Responsive Behavior

Breadcrumbs that overflow their container will appear to fade at the edge.
## Breadcrumbs [d2l-breadcrumbs]

<!-- docs: demo display:block -->
<!-- docs: demo code properties name:d2l-breadcrumbs sandboxTitle:'Breadcrumbs' display:block -->
```html
<script type="module">
import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
</script>
<d2l-breadcrumbs>
<d2l-breadcrumb text="Table of Contents" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Unit 1: Shakespeare" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Lesson 1: Introduction" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="The Comedies, Tragedies, and Histories" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Item 2" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Item 3" href="#"></d2l-breadcrumb>
</d2l-breadcrumbs>
```

This works well for mobile or other touch devices but not as well for mouse or keyboard users, so we have two other options for managing width.
<!-- docs: start hidden content -->
### Properties

### Limited Width
| Property | Type | Description |
|--|--|--|
| `compact` | Boolean | Renders in compact mode, displaying only the last item |
<!-- docs: end hidden content -->

Set a `max-width` to constrain breadcrumbs to a particular width:
## Breadcrumb (child) [d2l-breadcrumb]

<!-- docs: demo code display:block -->
<!-- docs: demo code properties name:d2l-breadcrumb sandboxTitle:'Breadcrumb' display:block -->
```html
<script type="module">
import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
</script>
<d2l-breadcrumbs style="max-width: 250px">
<d2l-breadcrumb text="Trucate Basic Item 1" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Truncate Basic Item 2" href="#"></d2l-breadcrumb>
<d2l-breadcrumbs>
<d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
</d2l-breadcrumbs>
```

### Compact Mode
<!-- docs: start hidden content -->
### Properties

Alternately, add the `compact` attribute to only display the last breadcrumb. The `d2l-breadcrumb-current-page` will be hidden:
| Property | Type | Description |
|--|--|--|
| `text` | String, required | The text of the breadcrumb link |
| `aria-label` | String | ARIA label for the breadcrumb, used if `text` does not provide enough context for screen reader users |
| `href` | String | The Url that breadcrumb is pointing to |
| `target` | String | Target of the breadcrumb item |
<!-- docs: end hidden content -->

<!-- docs: demo code display:block -->
## Current Page [d2l-breadcrumb-current-page]

Only include the current page in the breadcrumb if your page or view does not have a visible heading. You will notice that some older pages or tools in Brightspace still display the current page as the last breadcrumb despite having a visible page heading, but this is now a legacy pattern.

<!-- docs: demo code properties name:d2l-breadcrumb-current-page sandboxTitle:'Current Page Breadcrumb' display:block -->
```html
<script type="module">
import '@brightspace-ui/core/components/breadcrumbs/breadcrumb-current-page.js';
import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
</script>
<d2l-breadcrumbs compact>
<d2l-breadcrumbs>
<d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Item 2" href="#"></d2l-breadcrumb>
<d2l-breadcrumb-current-page text="Current Page"></d2l-breadcrumb-current-page>
</d2l-breadcrumbs>
```

## Breadcrumbs [d2l-breadcrumbs]
## Responsive Behavior

<!-- docs: demo code properties name:d2l-breadcrumbs sandboxTitle:'Breadcrumbs' display:block -->
Breadcrumbs that overflow their container will appear to fade at the edge, as in this example:

<!-- docs: demo display:block -->
```html
<script type="module">
import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
</script>
<d2l-breadcrumbs>
<d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Item 2" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Item 3" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Table of Contents" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Unit 1: Shakespeare" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Lesson 1: Introduction" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Sub-lesson 3: The Breadth of Shakespearean Literature" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="The Comedies, Tragedies, Histories, and Other Long Words" href="#"></d2l-breadcrumb>
</d2l-breadcrumbs>
```

<!-- docs: start hidden content -->
### Properties

| Property | Type | Description |
|--|--|--|
| `compact` | Boolean | Indicates whether the component should render in compact mode |
<!-- docs: end hidden content -->
### Limited Width

## Breadcrumb (child) [d2l-breadcrumb]
Set a `max-width` to constrain breadcrumbs to a particular width:

<!-- docs: demo code properties name:d2l-breadcrumb sandboxTitle:'Breadcrumb' display:block -->
<!-- docs: demo code display:block -->
```html
<script type="module">
import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
</script>
<d2l-breadcrumbs>
<d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
<d2l-breadcrumbs style="max-width: 250px">
<d2l-breadcrumb text="Trucate Basic Item 1" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Truncate Basic Item 2" href="#"></d2l-breadcrumb>
</d2l-breadcrumbs>
```

<!-- docs: start hidden content -->
### Properties

| Property | Type | Description |
|--|--|--|
| `text` | String, required | Text of the breadcrumb item |
| `aria-label` | String | AriaLabel of breadcrumb item |
| `href` | String | Href of the breadcrumb item |
| `target` | String | Target of the breadcrumb item |
<!-- docs: end hidden content -->

### Accessibility Properties

To make your usage of `d2l-breadcrumb` (child) accessible, use the following attribute when applicable:

| Attribute | Description |
|---|---|
| `aria-label` | Acts as a primary label. Use if `text` does not provide enough context. |

## Current Page [d2l-breadcrumb-current-page]
### Compact Mode

Only include the current page in the breadcrumb if your page or view does not have a visible heading. You will notice that some older pages or tools in Brightspace still display the current page as the last breadcrumb despite having a visible page heading, but this is now a legacy pattern.
Alternately, add the `compact` attribute to only display the last breadcrumb. The `d2l-breadcrumb-current-page` will be hidden:

<!-- docs: demo code properties name:d2l-breadcrumb-current-page sandboxTitle:'Current Page Breadcrumb' display:block -->
<!-- docs: demo code display:block -->
```html
<script type="module">
import '@brightspace-ui/core/components/breadcrumbs/breadcrumb-current-page.js';
import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
</script>
<d2l-breadcrumbs>
<d2l-breadcrumbs compact>
<d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
<d2l-breadcrumb text="Item 2" href="#"></d2l-breadcrumb>
<d2l-breadcrumb-current-page text="Current Page"></d2l-breadcrumb-current-page>
</d2l-breadcrumbs>
```

## Accessibility

Breadcrumbs adhere to [W3C's Breadcrumbs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/), so they are contained in a navigation landmark region with proper aria labelling and add `aria-current` to the final breadcrumb if it represents the [Current Page](#d2l-breadcrumb-current-page).

Note that we do not apply a `visited` style to breadcrumbs, since they reflect tool hiearchy and are part of the UI rather than part of the page content.
4 changes: 2 additions & 2 deletions components/breadcrumbs/breadcrumb.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,12 @@ class Breadcrumb extends RtlMixin(FocusMixin(LitElement)) {
*/
target: { type: String, reflect: true },
/**
* REQUIRED: text of the breadcrumb link
* REQUIRED: The text of the breadcrumb link
* @type {string}
*/
text: { type: String, reflect: true },
/**
* ARIA label of the breadcrumb
* ACCESSIBILITY: ARIA label for the breadcrumb, used if `text` does not provide enough context for screen reader users
* @type {string}
*/
ariaLabel: { attribute: 'aria-label', type: String, reflect: true }
Expand Down

0 comments on commit 02f45bf

Please sign in to comment.