Skip to content

Commit e624795

Browse files
rise-erpeldingrise-erpelding
authored
docs(illustratedmessage): audit and update a11y documentation (#5692)
1 parent 99ab45e commit e624795

File tree

1 file changed

+131
-10
lines changed

1 file changed

+131
-10
lines changed

‎packages/illustrated-message/README.md‎

Lines changed: 131 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,148 @@
1-
## Description
1+
## Overview
22

3-
An `<sp-illustrated-message>` displays an illustration icon and a message, usually in an empty state or on an error page. It is also used inside a DropZone.
3+
An `<sp-illustrated-message>` displays an outline illustration and a message, usually in an empty state or on an error page. It is also used inside a [DropZone](/components/dropzone).
44

55
### Usage
66

77
[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/illustrated-message?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/illustrated-message)
88
[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/illustrated-message?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/illustrated-message)
99
[![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-qrvmdaws)
1010

11-
```
11+
```zsh
1212
yarn add @spectrum-web-components/illustrated-message
1313
```
1414

1515
Import the side effectful registration of `<sp-illustrated-message>` via:
1616

17-
```
17+
```js
1818
import '@spectrum-web-components/illustrated-message/sp-illustrated-message.js';
1919
```
2020

2121
When looking to leverage the `IllustratedMessage` base class as a type and/or for extension purposes, do so via:
2222

23-
```
23+
```js
2424
import { IllustratedMessage } from '@spectrum-web-components/illustrated-message';
2525
```
2626

27-
## Example
27+
### Anatomy
28+
29+
An illustrated message consists of the following parts:
30+
31+
- An **outline illustration** that supports the messaging. The illustrated message accepts an `<svg>` into its default slot. This SVG is displayed as an illustration above the heading and description.
32+
- A required **heading** that appears in bold below the illustration, using a few words to convey what a user needs to do or know about.
33+
- An optional **body area** that elaborates on the heading and offers more information about how to complete the interaction, including buttons or links to show the user what to do next.
34+
35+
### Examples
36+
37+
<sp-tabs selected="call-to-action-with-link" auto label="Illustrated message examples">
38+
<sp-tab value="call-to-action-with-link">Call to action with link</sp-tab>
39+
<sp-tab-panel value="call-to-action-with-link">
40+
41+
```html
42+
<sp-illustrated-message heading="Drag and Drop Your File">
43+
<svg
44+
xmlns="http://www.w3.org/2000/svg"
45+
viewBox="0 0 200 100"
46+
width="200"
47+
height="100"
48+
>
49+
<defs>
50+
<style>
51+
.cls-1,
52+
.cls-2 {
53+
fill: none;
54+
stroke-linecap: round;
55+
stroke-linejoin: round;
56+
}
57+
.cls-1 {
58+
stroke-width: 3px;
59+
}
60+
.cls-2 {
61+
stroke-width: 2px;
62+
}
63+
</style>
64+
</defs>
65+
<path
66+
class="cls-1"
67+
d="M110.53,85.66,100.26,95.89a1.09,1.09,0,0,1-1.52,0L88.47,85.66"
68+
></path>
69+
<line class="cls-1" x1="99.5" y1="95.5" x2="99.5" y2="58.5"></line>
70+
<path class="cls-1" d="M105.5,73.5h19a2,2,0,0,0,2-2v-43"></path>
71+
<path
72+
class="cls-1"
73+
d="M126.5,22.5h-19a2,2,0,0,1-2-2V1.5h-31a2,2,0,0,0-2,2v68a2,2,0,0,0,2,2h19"
74+
></path>
75+
<line class="cls-1" x1="105.5" y1="1.5" x2="126.5" y2="22.5"></line>
76+
<path
77+
class="cls-2"
78+
d="M47.93,50.49a5,5,0,1,0-4.83-5A4.93,4.93,0,0,0,47.93,50.49Z"
79+
></path>
80+
<path
81+
class="cls-2"
82+
d="M36.6,65.93,42.05,60A2.06,2.06,0,0,1,45,60l12.68,13.2"
83+
></path>
84+
<path
85+
class="cls-2"
86+
d="M3.14,73.23,22.42,53.76a1.65,1.65,0,0,1,2.38,0l19.05,19.7"
87+
></path>
88+
<path
89+
class="cls-1"
90+
d="M139.5,36.5H196A1.49,1.49,0,0,1,197.5,38V72A1.49,1.49,0,0,1,196,73.5H141A1.49,1.49,0,0,1,139.5,72V32A1.49,1.49,0,0,1,141,30.5H154a2.43,2.43,0,0,1,1.67.66l6,5.66"
91+
></path>
92+
<rect
93+
class="cls-1"
94+
x="1.5"
95+
y="34.5"
96+
width="58"
97+
height="39"
98+
rx="2"
99+
ry="2"
100+
></rect>
101+
</svg>
102+
<p slot="description">
103+
<sp-link href="#">Select a file</sp-link>
104+
from your computer.
105+
</p>
106+
</sp-illustrated-message>
107+
```
108+
109+
</sp-tab-panel>
110+
<sp-tab value="call-to-action-with-buttons">Call to action with buttons</sp-tab>
111+
<sp-tab-panel value="call-to-action-with-buttons">
112+
113+
```html
114+
<sp-illustrated-message heading="Error 404: Page not found">
115+
<div slot="description">
116+
<p>
117+
This page isn't available. Try checking the URL or visit a different
118+
page.
119+
</p>
120+
<sp-button-group style="--mod-buttongroup-justify-content: center;">
121+
<sp-button treatment="outline" variant="primary">Back</sp-button>
122+
<sp-button treatment="fill" variant="primary">Refresh</sp-button>
123+
</sp-button-group>
124+
</div>
125+
<svg
126+
xmlns="http://www.w3.org/2000/svg"
127+
viewBox="0 0 150 103"
128+
width="150"
129+
height="103"
130+
>
131+
<path
132+
d="M133.7,8.5h-118c-1.9,0-3.5,1.6-3.5,3.5v27c0,0.8,0.7,1.5,1.5,1.5s1.5-0.7,1.5-1.5V23.5h119V92c0,0.3-0.2,0.5-0.5,0.5h-118c-0.3,0-0.5-0.2-0.5-0.5V69c0-0.8-0.7-1.5-1.5-1.5s-1.5,0.7-1.5,1.5v23c0,1.9,1.6,3.5,3.5,3.5h118c1.9,0,3.5-1.6,3.5-3.5V12C137.2,10.1,135.6,8.5,133.7,8.5z M15.2,21.5V12c0-0.3,0.2-0.5,0.5-0.5h118c0.3,0,0.5,0.2,0.5,0.5v9.5H15.2z M32.6,16.5c0,0.6-0.4,1-1,1h-10c-0.6,0-1-0.4-1-1s0.4-1,1-1h10C32.2,15.5,32.6,15.9,32.6,16.5z M13.6,56.1l-8.6,8.5C4.8,65,4.4,65.1,4,65.1c-0.4,0-0.8-0.1-1.1-0.4c-0.6-0.6-0.6-1.5,0-2.1l8.6-8.5l-8.6-8.5c-0.6-0.6-0.6-1.5,0-2.1c0.6-0.6,1.5-0.6,2.1,0l8.6,8.5l8.6-8.5c0.6-0.6,1.5-0.6,2.1,0c0.6,0.6,0.6,1.5,0,2.1L15.8,54l8.6,8.5c0.6,0.6,0.6,1.5,0,2.1c-0.3,0.3-0.7,0.4-1.1,0.4c-0.4,0-0.8-0.1-1.1-0.4L13.6,56.1z"
133+
></path>
134+
</svg>
135+
</sp-illustrated-message>
136+
```
137+
138+
</sp-tab-panel>
139+
<sp-tab value="informative">Informative</sp-tab>
140+
<sp-tab-panel value="informative">
28141

29142
```html
30143
<sp-illustrated-message
31-
heading="Drag and Drop Your File"
32-
description="Additional descriptive text"
144+
heading="Error 404: Page not found"
145+
description="This page isn't available. Try checking the URL or visit a different page."
33146
>
34147
<svg
35148
xmlns="http://www.w3.org/2000/svg"
@@ -45,6 +158,14 @@ import { IllustratedMessage } from '@spectrum-web-components/illustrated-message
45158
</sp-illustrated-message>
46159
```
47160

48-
## Content
161+
</sp-tab-panel>
162+
</sp-tabs>
163+
164+
### Accessibility
165+
166+
The `<sp-illustrated-message>` component provides a semantic structure for displaying illustrated content with proper heading hierarchy. However, there are several considerations to keep in mind for accessibility:
49167

50-
The illustrated message accepts an `<svg>` into its default slot. This SVG is displayed as an illustration above the heading and description.
168+
- **Always include a clear, standalone heading.** All illustrated messages must include a heading or title. This heading communicates the result of why the UI is appearing in the way that it is. If included, the description elaborates on the heading and offers more information.
169+
- **Ensure that text and image work together.** The illustration within an illustrated message adds value to the language that it’s paired with, and vice versa. An illustration’s meaning should be readily clear, contextual, and relevant to the overall message described in the text.
170+
- **Provide actionable solutions.** Offer an actionable solution when possible by using [links](/components/link) or [buttons](/components/button).
171+
- **Make error codes meaningful and contextual.** If an illustrated message is for an error state, use the heading to summarize the error. Only include an error code or other technical information if it’s useful and relevant for the user. Put the error code either at the beginning of the heading using a colon, or at the end of the message using parentheses; don’t hide it in the middle of the heading or bury it in the description.

0 commit comments

Comments
 (0)