Skip to content

Commit 1304a40

Browse files
author
Amber Febbraro
authored
Merge pull request #4036 from diriquelme/alt_text_guide
added new alt text guide and updated guides page
2 parents 7c51aff + 0f5d64d commit 1304a40

File tree

2 files changed

+338
-0
lines changed

2 files changed

+338
-0
lines changed

‎src/pages/using-spark/guides.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Get answers on topics like layout, messaging, and placement. We’ll be adding n
1010

1111
## Available Guidance
1212

13+
- [Alternative Text](/using-spark/guides/alt-text)
1314
- [Content Style](/using-spark/guides/content-style)
1415
- [Validation Messaging](/using-spark/guides/validation-messaging)
1516
- [Writing Meaningful Web Content With Semantic HTML](/using-spark/guides/writing-meaningful-web-content-with-semantic-html)

‎src/pages/using-spark/guides/alt-text.mdx‎

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,337 @@
1+
---
2+
title: Alternative Text
3+
---
4+
5+
import { SprkDivider, SprkIcon } from '@sparkdesignsystem/spark-react';
6+
7+
<h1 class="sprk-b-PageTitle sprk-b-TypeDisplayOne sprk-u-mbl sprk-u-Measure">
8+
Alternative Text
9+
</h1>
10+
11+
UX Writers, designers and developers can use this **Alternative Text Guide** as an instruction to writing style, usage, text for copy, documentation, reference information, and copy inside Rocket digital experiences.
12+
13+
<SprkDivider element="span" additionalClasses="sprk-u-mvl" />
14+
15+
<h3 class="sprk-b-TypeDisplayThree sprk-u-mbm sprk-u-Measure">Main Takeaways</h3>
16+
17+
- Adding alternative text ensures users with disabilities can understand non-text content.
18+
- Describe the image without altering the meaning of the screen or referencing the word “image.”
19+
- Consider how you would describe that image to someone without them having to visually see the image.
20+
- Decorative images don't need alternative text.
21+
- Use a null attribute (or empty string) for non-semantic or decorative images, for example those that are for ambiance or other non-semantic purposes.
22+
23+
#### Accessibility Benefits
24+
25+
- Screen readers read alt-text in place of images, which allows low or no-vision users to understand the meaning of the image.
26+
- When an image fails to load or if content is blocked, the alt-text will appear in it's place.
27+
- It gives images a text to display so screen readers can read it without altering the meaning of the screen.
28+
29+
<SprkDivider element="span" additionalClasses="sprk-u-mvs" />
30+
31+
### Table Of Contents
32+
33+
<ul>
34+
<li>
35+
<a href="#what-is-alternative-text">What Is Alternative Text</a>
36+
</li>
37+
<li>
38+
<a href="#images-and-graphics">Images and Graphics</a>
39+
</li>
40+
<ul class="sprk-b-List sprk-b-List--indented sprk-u-Measure sprk-u-mvs">
41+
<li>
42+
<a href="#images">Images</a>
43+
</li>
44+
<li>
45+
<a href="#icons">Icons</a>
46+
</li>
47+
<li>
48+
<a href="#svgs">SVG</a>
49+
</li>
50+
</ul>
51+
<li>
52+
<a href="#writing-effective-alt-text-copy">
53+
Writing Effective Alt Text Copy
54+
</a>
55+
</li>
56+
<ul class="sprk-b-List sprk-b-List--indented sprk-u-Measure sprk-u-mvs">
57+
<li>
58+
<a href="#guidelines">Guidelines</a>
59+
</li>
60+
<li>
61+
<a href="#examples">Examples</a>
62+
</li>
63+
</ul>
64+
<li>
65+
<a href="#accessibility">Accessibility</a>
66+
</li>
67+
<ul class="sprk-b-List sprk-b-List--indented sprk-u-Measure sprk-u-mvs">
68+
<li>
69+
<a href="#resources">Resources</a>
70+
</li>
71+
</ul>
72+
</ul>
73+
74+
<SprkDivider element="span" additionalClasses="sprk-u-mvn" />
75+
76+
## What Is Alternative Text
77+
78+
Alternative text or commonly known as **alt-text** is a word or phrase that describes an image’s appearance and function.
79+
80+
> The main purpose of the <a href="https://www.w3.org/TR/WCAG21/#non-text-content">alt tag</a> is to support accessibility, so screen readers and other assistive technology users are able to make full use of the content.
81+
82+
<h3 class="sprk-b-TypeDisplayFour sprk-u-mbm sprk-u-Measure">Syntax</h3>
83+
84+
The text inside the alt tag provides the user with a description of the image.
85+
86+
``` html
87+
<img src="image_of_puppies.png" alt="Four black Goldendoodle puppies">
88+
```
89+
<SprkDivider element="span" additionalClasses="sprk-u-mvm" />
90+
91+
### Images and Graphics
92+
93+
Images and graphics make content visually pleasant and easier to understand.
94+
95+
> To ensure they are accessible, they must have alternative text that describes the information or function represented by them.
96+
97+
<SprkDivider element="span" additionalClasses="sprk-u-mvs" />
98+
99+
### Images
100+
101+
Not all images on the web need the same alt-text. It’s important to consider the context and purpose of the image when writing the text description.
102+
103+
Images can be active, informative or decorative.
104+
105+
- **Active Images** help communicate meaning, actions, status or feedback.
106+
- **Informative Images** help users understand the content on a screen. These include: diagrams, charts, graphs, maps or informative icons.
107+
- **Decorative Images** have no semantic meaning and should have their alt attributes set to the empty (or null) string ("").
108+
109+
> For more information refer to <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt">Developer Mozilla's HTML Image Element - alt.</a>
110+
111+
<SprkDivider element="span" additionalClasses="sprk-u-mvl" />
112+
113+
#### Guidelines
114+
115+
<div class="sprk-b-TableContainer">
116+
<table class="sprk-b-Table--secondary sprk-b-Table--spacing-medium sprk-b-Table--bordered-rows">
117+
<thead>
118+
<tr>
119+
<th>If The Image Is ...</th>
120+
<th>How To Identify It?</th>
121+
<th>The Alt Text Should ...</th>
122+
</tr>
123+
</thead>
124+
<tbody>
125+
<tr>
126+
<td>Active</td>
127+
<td>These images perform an action or have functionality. For example, clickable icons are active images.</td>
128+
<td>Help the user understand what happens when they click the image.</td>
129+
</tr>
130+
<tr>
131+
<td>Informative</td>
132+
<td>These images contain information the user may need. If the image was removed from the screen, the information would be lost.</td>
133+
<td>Explain or describe the information found in the image.</td>
134+
</tr>
135+
<tr>
136+
<td>Decorative</td>
137+
<td>These images are included only for placement or visual effects. An image is decorative if you could remove it from the screen without losing information.</td>
138+
<td>Blank or null ("").</td>
139+
</tr>
140+
</tbody>
141+
</table>
142+
</div>
143+
144+
<SprkDivider element="span" additionalClasses="sprk-u-mvm" />
145+
146+
<h3 class="sprk-b-TypeDisplayThree sprk-u-mbl sprk-u-Measure">Icons</h3>
147+
148+
<p class="sprk-b-TypeBodyTwo sprk-u-mbl sprk-u-Measure">Icons can potentially convey meaning without using words, although researching users' understanding of icons is critical to ensuring that meaning is clear.</p>
149+
150+
<h3 class="sprk-b-TypeDisplayFour sprk-u-mbs sprk-u-Measure">Guidelines</h3>
151+
152+
<div class="sprk-b-TableContainer">
153+
<table class="sprk-b-Table--secondary sprk-b-Table--spacing-medium sprk-b-Table--bordered-rows">
154+
<thead>
155+
<tr>
156+
<th>What Is The Purpose Of The Icon?</th>
157+
<th>How To Identify It?</th>
158+
<th>The Alt Text Should ...</th>
159+
<th>Best Practices</th>
160+
</tr>
161+
</thead>
162+
<tbody>
163+
<tr>
164+
<td>Act as an image</td>
165+
<td>The icon appears as an image or inline image.</td>
166+
<td>Help the user understand what the icon image conveys.</td>
167+
<td>It <strong>must</strong> have an alt attribute.</td>
168+
</tr>
169+
<tr>
170+
<td>For <strong>functionality</strong></td>
171+
<td>For example, a magnifying glass icon prompts users to activate the search function.</td>
172+
<td>Provide contextual text accompanying the icon or add a visually hidden string for screen readers. (No alternative text needed.)</td>
173+
<td>Set the alt attribute to empty or null ("").</td>
174+
</tr>
175+
<tr>
176+
<td>For <strong>decoration</strong></td>
177+
<td>The icon is purely for visual decor.</td>
178+
<td>No alternative text needed.</td>
179+
<td>Set the alt attribute to empty or null ("").</td>
180+
</tr>
181+
</tbody>
182+
</table>
183+
</div>
184+
185+
<SprkDivider element="span" additionalClasses="sprk-u-mvl" />
186+
187+
<h3 class="sprk-b-TypeDisplayFour sprk-u-mbs sprk-u-Measure">Examples</h3>
188+
189+
<div class="sprk-b-TableContainer">
190+
<table class="sprk-b-Table--secondary sprk-b-Table--spacing-medium sprk-b-Table--bordered-rows">
191+
<thead>
192+
<tr>
193+
<th>Icon Image</th>
194+
<th>What Does The Icon Convey?</th>
195+
<th>The Alt Text Should ...</th>
196+
<th>Example</th>
197+
</tr>
198+
</thead>
199+
<tbody>
200+
<tr>
201+
<td><SprkIcon iconName="question" additionalClasses="sprk-c-Icon--xl" /></td>
202+
<td>An image of a question mark icon.</td>
203+
<td>Give users context about what the icon is trying to communicate.</td>
204+
<td>alt="Get more information."</td>
205+
</tr>
206+
<tr>
207+
<td><SprkIcon iconName="search" additionalClasses="sprk-c-Icon--xl" /></td>
208+
<td>An image of a magnifying glass icon.</td>
209+
<td>Give users instructions as a guide when interacting with the search icon.</td>
210+
<td>"Use the magnifying icon to start your search."</td>
211+
</tr>
212+
</tbody>
213+
</table>
214+
</div>
215+
216+
<SprkDivider element="span" additionalClasses="sprk-u-mvl" />
217+
218+
<h3 class="sprk-b-TypeDisplayThree sprk-u-mbl sprk-u-Measure">SVG</h3>
219+
220+
Scalable Vector Graphics or SVG is an XML-based vector graphics format that specifies the contents of an image as a set of drawing commands that create shapes, lines, apply colors, filters, and so forth.
221+
222+
> SVG files are text files containing source code that, when interpreted, draws the desired image.
223+
224+
Here are some **benefits** of using SVG:
225+
- They are easy to style and animate.
226+
- They are great for responsive design because they decrease the screen load time.
227+
228+
For more information, visit <a href="https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#svg"> Developer Mozilla SVG documentation</a>.
229+
230+
<SprkDivider element="span" additionalClasses="sprk-u-mvl" />
231+
232+
<h3 class="sprk-b-TypeDisplayFour sprk-u-mbm sprk-u-Measure">Usage</h3>
233+
234+
SVG files are ideal for:
235+
- Diagrams
236+
- Icons
237+
- Images that can be accurately drawn at any size, like for user interface elements.
238+
239+
<SprkDivider element="span" additionalClasses="sprk-u-mvl" />
240+
241+
<h3 class="sprk-b-TypeDisplayFour sprk-u-mbs sprk-u-Measure">Guidelines</h3>
242+
243+
<div class="sprk-b-TableContainer">
244+
<table class="sprk-b-Table--secondary sprk-b-Table--spacing-medium sprk-b-Table--bordered-rows">
245+
<thead>
246+
<tr>
247+
<th>If The SVG Is ...</th>
248+
<th>What Does The SVG Convey?</th>
249+
<th>The Alt Text Should ...</th>
250+
</tr>
251+
</thead>
252+
<tbody>
253+
<tr>
254+
<td>Acting as an image</td>
255+
<td>It must have alt-text using the alt attribute.</td>
256+
<td>Give users context about what the SVG image is conveying.</td>
257+
</tr>
258+
<tr>
259+
<td>Intended as an image source</td>
260+
<td>Communicate to users what the image is conveying.</td>
261+
<td>If the image is an icon, give users a description. For example, alt="Lightbulb icon."</td>
262+
</tr>
263+
<tr>
264+
<td>Acting as the SVG source</td>
265+
<td>Must have a title.</td>
266+
<td>Help users understand what the image is trying to communicate.</td>
267+
</tr>
268+
<tr>
269+
<td>An inline SVG</td>
270+
<td>Add the alt-text using the (title=" ") element within the SVG image.</td>
271+
<td>Give users a brief description or advisory information of the graphic.</td>
272+
</tr>
273+
</tbody>
274+
</table>
275+
</div>
276+
277+
<SprkDivider element="span" additionalClasses="sprk-u-mvl" />
278+
279+
<h2 class="sprk-b-TypeDisplayTwo sprk-u-mbl sprk-u-Measure">Writing Effective Alt Text Copy</h2>
280+
281+
> As a UX Writer, determine what the alt-text should be depending on the usage, context, and content of the image.
282+
283+
<h3 class="sprk-b-TypeDisplayFour sprk-u-mbm sprk-u-Measure">Guidelines</h3>
284+
285+
- <strong>Determine what information or what the function of the image is.</strong> Copy should describe an image’s purpose or what information it communicates.
286+
- <strong>Choose the appropriate alternative text for the image type. </strong> If the image has no informative value, treat them as decorative images.
287+
- <strong>Describe the image as specifically as possible. </strong> Include the most valuable information at the beginning and provide meaningful descriptions.
288+
- <strong>Keep it as short as possible. </strong> Be concise and avoid keyword stuffing.
289+
- <strong>Use punctuation.</strong>
290+
<ul class="sprk-b-List sprk-b-List--indented"
291+
data-id="unordered-list-2">
292+
<li>Use sentence case.</li>
293+
<li>Add space characters between the image and adjacent text to avoid having words running together when a screen reader reads them.</li>
294+
<li>Include a period at the end of the alt-text – even if it's not a complete sentence. The period will provide a slight pause when read by the screen reader.</li>
295+
<li>If using a null (empty) alternative text (alt="") to hide decorative images, make sure that there is no space character between the quotes.</li>
296+
</ul>
297+
298+
<h3 class="sprk-b-TypeDisplayFour sprk-u-mbm sprk-u-Measure">Examples</h3>
299+
300+
<p class="sprk-b-TypeBodyTwo sprk-u-mbn sprk-u-Measure">Use these examples as a guideline to create the best alt-text copy.
301+
The examples in the table below, describe the image of a rooster.</p>
302+
303+
<div class="sprk-b-TableContainer">
304+
<table class="sprk-b-Table--secondary sprk-b-Table--spacing-medium sprk-b-Table--bordered-rows">
305+
<thead>
306+
<tr>
307+
<th>Average Example</th>
308+
<th>Better Example</th>
309+
<th>Best Example</th>
310+
</tr>
311+
</thead>
312+
<tbody>
313+
<tr>
314+
<td>alt=“Rooster.”</td>
315+
<td>alt=“Rooster crowing.“</td>
316+
<td>alt="Red-crested rooster crowing."</td>
317+
</tr>
318+
</tbody>
319+
</table>
320+
</div>
321+
322+
<SprkDivider element="span" additionalClasses="sprk-u-mvn" />
323+
324+
## Accessibility
325+
326+
Ensure all non-text content (images and graphics) has alternative text so blind users can understand a screen’s content when read by a screen reader.
327+
328+
<p class="sprk-b-TypeBodyTwo sprk-u-mbl sprk-u-Measure"> The content above is not all-inclusive, please review <a href="https://sparkdesignsystem.com/principles/accessibility-guidelines">Spark’s Accessibility Guidelines.</a></p>
329+
330+
> Alternative text enables blind users to interpret images. Refer to <a href="https://www.w3.org/TR/WCAG21/#text-alternatives"> W3’s Text Alternative Guidelines.</a>
331+
332+
<h3 class="sprk-b-TypeDisplayFour sprk-u-mbl sprk-u-Measure">Resources</h3>
333+
334+
- <a href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html">Alternative text for non-text content</a>- WCAG (Web Accessibility Guidelines)
335+
- <a href="https://www.w3.org/TR/WCAG20-TECHS/G82.html">Providing a text alternative that identifies the purpose of the non-text content.</a>
336+
- <a href="https://webaim.org/techniques/alttext/">Techniques for writing alternative text - webaim.org.</a>
337+
- <a href="https://www.w3.org/WAI/tutorials/images/decision-tree/">Decision tree for alternative text - WAI(Web Accessibility Initiative)</a>

0 commit comments

Comments
 (0)