img-001 must GuidesAPI docs Always provide alt text for images and non-text elements. Use descriptive alt text that conveys the element’s purpose; use empty alt text for purely decorative images.
Images
This page covers requirements for all images in documentation: alt text, text alternatives, how to introduce and caption figures, and how to refer to them. Screenshot-specific and diagram-specific guidance lives on their own pages.
Provide alt text
Section titled “Provide alt text”Examples
- ✓
 - ✗
for a diagram that carries meaning - ✓
for a purely decorative divider - ✗
Rationale
Alt text is how a screen-reader user gets an image’s meaning; decorative images take empty alt so they are skipped.
Keep alt text concise
Section titled “Keep alt text concise”img-002 should GuidesAPI docs Alt text should be concise (155 characters or fewer). When an image requires more explanation than fits in alt text, provide a longer description in the surrounding body text.
Examples
- ✓ Alt text: “The billing dashboard with the Export button highlighted.” The individual dashboard panels are described in the paragraph that follows the image.
- ✗ Alt text: “The billing dashboard showing the navigation sidebar with six sections, the usage graph for the last 30 days, the current invoice total, the payment method on file, and the Export button in the upper-right toolbar.”
Rationale
Alt text is read aloud in full, so it stays short, with any longer explanation in the surrounding text.
Describe the content, not the medium
Section titled “Describe the content, not the medium”img-008 should GuidesAPI docs Alt text should not begin with phrases like ‘Image of’ or ‘Photo of’, should include punctuation, and should use full sentences or noun phrases.
Examples
- ✓ Alt text: “The deployment pipeline’s three stages: build, test, and release.”
- ✗ Alt text: “Image of deployment pipeline”
Rationale
“Image of” wastes the first words a screen reader announces, so describing the content directly is more useful.
Use text, not images of text
Section titled “Use text, not images of text”img-003 must GuidesAPI docs Do not use images of text, code samples, or terminal output; use actual text instead.
Examples
- ✓ The install command in a fenced code block:
npm install example-sdk - ✗ A PNG screenshot of a terminal window showing the install command
Rationale
Text baked into an image cannot be selected, searched, translated, or read by assistive tech.
Avoid explanatory text in images
Section titled “Avoid explanatory text in images”img-007 should GuidesAPI docs Avoid embedding explanatory text in images. When text must appear in a figure, keep it brief, use sentence case, and ensure the same information is available in accessible text form, such as a figure description.
Examples
- ✓ A diagram with brief sentence-case labels on each stage, with the stages explained in the paragraph and figure description that follow
- ✗ A diagram whose stages are explained only in text boxes drawn inside the image
Rationale
Text embedded in a figure is not translated or read by assistive tech, so the same information belongs in accessible text.
Avoid image maps
Section titled “Avoid image maps”img-004 should GuidesAPI docs Avoid image maps; when they must be used, provide text link alternatives and ensure keyboard (Tab key) navigability.
Examples
- ✓ A clickable region map followed by the same regions as a list of text links, reachable with the Tab key
- ✗ A clickable region map as the only way to choose a region
Rationale
Image maps are hard to use by keyboard and screen reader, so text alternatives keep them reachable.
Introduce images in text
Section titled “Introduce images in text”img-005 should GuidesAPI docs Introduce images with a complete sentence (ending in a colon if the image immediately follows, or a period if other content intervenes).
Examples
- ✓ The following diagram shows the authentication flow:
- ✗ An image inserted directly after a heading, with no introductory sentence
Rationale
An introducing sentence gives the image context and a screen-reader pause before it.
Punctuate and number figure captions
Section titled “Punctuate and number figure captions”img-006 must GuidesAPI docs Figure captions, when used, should be complete sentences, or sentence fragments with end punctuation. If figure numbers are used, follow the form ‘Figure NUMBER. DESCRIPTION.’ Do not capitalize ‘figure’ in cross-references except at the start of a sentence.
Examples
- ✓ Figure 3. The request lifecycle from client to database.
- ✗ figure 3 - request lifecycle
- ✓ The retry path appears in figure 3.
- ✗ The retry path appears in Figure 3.
Don’t use spatial references
Section titled “Don’t use spatial references”img-009 must GuidesAPI docs Do not use spatial references such as ‘the image above’ when referring to figures; use figure numbers or restate the figure.
Examples
- ✓ Figure 2 shows the resulting network topology.
- ✗ The image above shows the resulting network topology.
Rationale
“The image above” breaks when layout reflows or content is read linearly; a figure number is stable.