Skip to content

docs(tray): improve a11y of tray docs examples #5888

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

Merged
merged 1 commit into from
Nov 19, 2025
+25 −38
Merged

docs(tray): improve a11y of tray docs examples #5888

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
63 changes: 25 additions & 38 deletions 1st-gen/packages/tray/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,7 @@ import { Tray } from '@spectrum-web-components/tray';

### Anatomy

A tray has a single default `slot`.

<sp-tabs selected="dialog" auto label="Using tray's slot">
<sp-tab value="dialog">Dialog</sp-tab>
<sp-tab-panel value="dialog">
A tray has a single default `slot`. Expected content typically includes dialogs and their content, plain text, forms and/or form elements, and some native HTML elements. Always ensure that your tray's content is accessible according to WCAG standards.
Copy link
Contributor

@caseyisonit caseyisonit Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clean language, love it


```html
<overlay-trigger type="modal">
Expand All @@ -43,30 +39,6 @@ A tray has a single default `slot`.
</overlay-trigger>
```

</sp-tab-panel>
<sp-tab value="menu">Menu</sp-tab>
<sp-tab-panel value="menu">

```html
<overlay-trigger type="modal">
<sp-button slot="trigger" variant="secondary">Toggle menu</sp-button>
<sp-tray slot="click-content">
<sp-menu style="width: 100%">
<sp-menu-item selected>Deselect</sp-menu-item>
<sp-menu-item>Select Inverse</sp-menu-item>
<sp-menu-item focused>Feather...</sp-menu-item>
<sp-menu-item>Select and Mask...</sp-menu-item>
<sp-menu-divider></sp-menu-divider>
<sp-menu-item>Save Selection</sp-menu-item>
<sp-menu-item disabled>Make Work Path</sp-menu-item>
</sp-menu>
Comment on lines -54 to -62
Copy link
Collaborator Author

@marissahuysentruyt marissahuysentruyt Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In context, this menu doesn't really make- it's only a partial implementation and would normally be rendered within a popover instead.

After discussing with the team, we decided to leave out the tray examples with menus in favor of other content.

</sp-tray>
</overlay-trigger>
```

</sp-tab-panel>
</sp-tabs>

### Accessibility

`<sp-tray>` presents a page blocking experience and should be opened with the `Overlay` API using the `modal` interaction to ensure that the content appropriately manages the presence of other content in the tab order of the page and the availability of that content for a screen reader.
Expand All @@ -87,20 +59,35 @@ This dismiss helper pattern is also implemented in the [`<sp-picker>`](https://o
<sp-tab value="auto">Content has no buttons</sp-tab>
<sp-tab-panel value="auto">

This example shows the default behavior where the tray automatically detects that the menu content lacks dismiss buttons and renders visually hidden helpers. Screen readers will announce them as "Dismiss, button" and these helpers are keyboard accessible.
This example shows the default behavior where the tray automatically detects that the content lacks dismiss buttons and renders visually hidden helpers. Screen readers will announce them as "Dismiss, button" and these helpers are keyboard accessible.

```html
<overlay-trigger type="modal">
<sp-button slot="trigger" variant="secondary">
Toggle menu content
Toggle tray content
</sp-button>
<sp-tray slot="click-content">
<sp-menu style="width: 100%">
<sp-menu-item>Deselect</sp-menu-item>
<sp-menu-item>Select Inverse</sp-menu-item>
<sp-menu-item>Feather...</sp-menu-item>
<sp-menu-item>Select and Mask...</sp-menu-item>
</sp-menu>
<div style="display: flex; flex-direction: column; margin: 16px;">
<p style="margin-block-start: 0;">
Custom content that doesn't have dismiss functionality, so the
tray detects it needs the visually-hidden dismiss buttons.
Copy link
Contributor

@caseyisonit caseyisonit Nov 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yessss kween to incorporating contextual documentation in the example!! we should flag this as a good practice to continue!

</p>
<label>
What's your favorite Super Mario character?
<select
name="favorite-characters"
style="margin-block-start: 8px;"
>
<option value="">
Choose your favorite Super Mario character.
</option>
<option value="mario">Mario</option>
<option value="luigi">Luigi</option>
<option value="toad">Toad</option>
<option value="bowser">Bowser</option>
</select>
</label>
</div>
</sp-tray>
</overlay-trigger>
```
Expand Down Expand Up @@ -137,7 +124,7 @@ Set `has-keyboard-dismiss` (or `has-keyboard-dismiss="true"`) to prevent the tra
Toggle without helpers
</sp-button>
<sp-tray slot="click-content" has-keyboard-dismiss>
<p>
<p style="margin: 16px;">
Copy link
Collaborator Author

@marissahuysentruyt marissahuysentruyt Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added this solely to make it look a little nicer inside the tray.

Custom content that should have custom dismiss functionality, even
though the tray didn't detect buttons in this slot.
</p>
Expand Down
Loading