Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: DAYL-89 Improve Breadcrumb a11y docn #5128

Merged
merged 3 commits into from
Nov 27, 2024
Merged

feat: DAYL-89 Improve Breadcrumb a11y docn #5128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7fd0b91
Adding Accessibility tag to relevant properties
geurts Nov 1, 2024
70bf275
Minor updates
geurts Nov 26, 2024
d3af0b4
Merge branch 'main' into geurts-breadcrumb-a11y-docn
geurts Nov 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 54 additions & 58 deletions components/breadcrumbs/README.md
View file
Open in desktop
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:
ChrisLabattD2L marked this conversation as resolved.
Show resolved Hide resolved

<!-- 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
Open in desktop
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
Loading