Figures and other images

Use images only when they provide useful visual explanations of information that is otherwise difficult to express with words, or for screenshots of UIs that are important to the discussion.

Create and save images

  • To create a diagram, use any drawing tool.
  • To take a screenshot, use any screen capture tool.
  • Don't use images of text, code samples, or terminal output. Use actual text.
  • For diagrams (architectural drawings, flow diagrams, and so on, as distinct from screenshots), use SVG files if possible because SVGs stay sharp when you zoom in on the image. If you don't have an SVG file, then save your image as a PNG file unless you have a good reason to use a different format.
  • For animations and videos, don't use animated GIF. Instead, use a more resource-efficient format (such as MP4).
  • Be consistent for a given document or doc set in what operating system you use for screenshots—for example, take all screenshots on macOS or on Linux. Similarly, be consistent in how your screenshots look. If you take screenshots that include drop shadows of the main window, make sure that similar screenshots are consistent.
  • Crop screenshots to show the relevant information. For example, don't include the full window if you just want to show a single button or menu item. Cropping helps the reader focus on the information that you want to convey in the screenshot, and it can help future-proof the screenshot if other parts of the UI change.
  • Don't include personally identifying information (PII) in screenshots.

    If a source screenshot includes PII, hide it with a solid-color overlay with 100% opacity. Don't rely on blurs, mosaic effects, or similar image-processing effects to obscure PII; such effects can be reversed to reveal the original information.

    If you're exporting an image to a format that can include information on separate layers (for example, PDF or TIFF), flatten the image on export.

  • Don't use image maps. Instead, provide a list of text references following the image. Reasons to avoid image maps include the following:
    • Image maps are problematic for accessibility.
    • Browser implementation for image maps varies, and image maps might not function correctly on mobile devices due to scaling.
    • The technical complexity of creating and maintaining a coordinates overlay is often prohibitive.
    • Use descriptive filenames for your image files. For more information, see Filenames and file types.

Text associated with images

There are differences between alt text, figure captions, and figure descriptions. Independently of these elements, an introductory sentence should precede most images. The sentence can end with a colon or a period; usually a colon if it immediately precedes the image, usually a period if there's more material (such as a note paragraph) between the introduction and the image. Always introduce an image with a complete sentence. You don't need to introduce screenshots that immediately follow procedural text that describes a UI.

Alt text
A concise description of the image that can replace the image in situations where the image isn't visible, such as people using screen readers, people using text-only browsers, or people who have a low-bandwidth internet connection. Alt text should consider the context of the image, not just its content. For more information, see alt attribute.
Figure caption
A description of the image that provides more information about the image.
Figure description
A textual representation of the figure. In other words, the information that is conveyed in the image is captured in the text. A figure description provides detailed information about what an image is trying to convey.

Figure captions are optional. When using the <figcaption> element, both the <figcaption> and <img> elements must be wrapped in the <figure> element to ensure that the figure caption is properly associated with the image.

The following example assumes that the figure description is on the same page as the figure.


<figure id="emu-foot">
  <img src="/assets/images/emu-foot.svg"
    alt="An emu foot has three toes."
  <figcaption><b>Figure 1.</b> Diagram of an emu's
leg with each bone labeled.</figcaption>
<div id="descr-1">
<p>In figure 1, the following bones are labeled: femur, fibula, tibiotarsus, tarsometatarsus, and


![An emu foot has three toes.](/assets/images/emu-foot.svg){: width="120"}

**Figure 1.** Diagram of an emu's leg with each bone labeled.

In figure 1, the following bones are labeled: femur, fibula, tibiotarsus,
tarsometatarsus, and phalanges.

Alt text

As shown in the preceding example, use an alt attribute to provide a text alternative for the image in context. Alt text is used by assistive technologies, such as screen readers, and might appear if the image cannot load. However, if the image is decorative (not informative) or it's provided only as a visual aid for information that is already expressed in text, then provide empty alternative text (alt="") so it will be ignored by assistive technologies.

When using the <img> element, the alt attribute is required, even if its assigned value is an empty string (alt=""). If you exclude the alt attribute completely, then screen readers might instead read the filename aloud. The presence of alt attributes helps support navigability in screen readers, markup validation, and search engine optimization.

As per the HTML specification, "the most general rule to consider when writing alternative text is the following: the intent is that replacing every image with the text of its alt attribute not change the meaning of the page." So if the alternative text is redundant with surrounding text or it's not useful to visually impaired readers, use the empty tag.

Consider the following when writing alt text:

  • Don't include phrases like Image of or Photo of.
  • Include punctuation. When screen readers encounter punctuation, they pause before continuing.
  • Use consistent alt text for repeated instances of an image, such as controls, status indicators, or icons that appear multiple times in your document.
  • When possible, avoid using all-caps in alt text. Some screen readers read capital letters as each letter individually.
  • Introduce diagrams in the text, not in the alt text.
  • Don't use figure captions to replace alt text.
  • Use full sentences.
  • Write short, descriptive alt text in 155 characters or less.
  • If the image presents more useful information than you can fit in the 155 character limit, include a brief summary of the image in the altattribute and also include the longdesc attribute to link to a more extensive description of the image. The longdesc attribute value should be a link, not text.
  • Alt text should consider the context of the image, not just its content.

Figure captions

Figure captions are concise and comprehensive summaries of a figure or image.

  • Use the form "<b>Figure NUMBER.</b> DESCRIPTION".
  • Use punctuation in figure captions.
  • When you refer to a figure, don't use spatial descriptions such as "the image below." Instead, mention it by number. For example: "... as shown in figure 1." Don't capitalize the word figure in a reference to a figure, except at the start of a sentence.
  • Don't include the figure caption in a sentence referencing the figure.

Figure descriptions

A figure description is text that provides a more detailed explanation of information represented by a figure. Any new information should be conveyed through text, and not introduced in a figure or image.

The figure description should not be confused with the longdesc attribute, which can be used to provide a more lengthy description of the content and context of an image than can be conveyed in the alt attribute's recommended 155 character limit.

  • Create text that conveys the same information as the figure.
  • Use when a figure caption doesn't convey the purpose or complete information of the figure.
  • Use punctuation in figure descriptions.

Text in figures

In most cases, avoid embedding explanatory text in screenshot graphics; text that's incorporated into a graphic hurts accessibility and searchability, and increases localization costs if figures are localized. If you must embed text in an image, then be sure to also provide the same information in a form that people with visual disabilities can use, such as a figure description.

When you must include text in figures and images, use the following guidelines:

  • Keep text brief. Avoid complete sentences and punctuation when possible.
  • Don't embed figure descriptions or captions in the figure or image. Instead, put figure descriptions and captions in text following the figure.
  • Don't create new abbreviations to condense text.
  • Use sentence case. Follow guidelines for capitalization for titles and headings.
  • Use numbered callouts in figures to help you write a figure description, but don't use callouts for detailed annotations.
  • Use full trademarked product names.

Accessibility resources

For more information about the accessibiity of diagrams and screenshots, see the following resources:

High-resolution images

Modern browsers can use high-resolution images if they are available; this makes the images look better on high-resolution displays.

To provide a high-resolution image, use the <img> element's srcset attribute in addition to the standard src attribute. The srcset attribute lets you specify different image assets for different screen resolutions. It accepts a comma-delimited set of image URLs, with the target screen resolution specified by a size qualifier: 1x meaning the "standard" resolution, 2x meaning "double" the resolution, and so on.

If a web browser supports the srcset attribute, it selects an image from the specified images that's an appropriate resolution for the current display. If the browser doesn't support the srcset attribute, it uses the image in the src attribute. Consequently, you must always still include the src attribute.

For example, to provide both a standard resolution image and a double-resolution image, add a srcset attribute and specify both 1x and 2x image assets:

<img src="/assets/images/skateboard.png"
  srcset="/assets/images/skateboard.png 1x,
  /assets/images/skateboard_2x.png 2x"
  width="375" alt="" />
  • The width attribute matches the CSS pixel size used for the page dimensions. (The height is automatically calculated based on the width and the image's proportions; don't state it explicitly.)
  • Set the src attribute to point to the standard-resolution (1x) image, not the 2x version. (Almost everyone who has a high-resolution screen also has a modern browser that can recognize the srcset attribute. The src attribute is mainly used by older browsers on low-resolution devices, which should download the smaller, low-resolution image.) Even if your original image is the higher-resolution image, set the src attribute to use the standard-resolution version; don't force a reader using a low-resolution screen to download a graphic that's higher-resolution than they can view.
  • The filename for the double-resolution image (in this case, skateboard_2x.png) can be anything—it's the " 2x" value following the filename that informs the browser which resolution the file is. But it's a good idea to use a filename of the form BASENAME_2x.EXTENSION to make clear to human readers that it's a double-resolution version of BASENAME.EXTENSION.
  • The double-resolution image must be exactly twice the width and height of the standard image, give or take a pixel. (For example, it's okay for the double-resolution image to be 875x500 and the standard size to be 438x250.)
  • Don't scale up an existing 1x image to make the 2x version. If all you have is the 1x version, then use it alone. But if you're starting with a high-resolution image (at 2x resolution or better), then you can scale it down to appropriate dimensions for 1x and 2x.
  • Currently, only an additional 2x image is necessary, but someday screen PPI may increase further. So the srcset attribute supports further alternative sizes, each specified by the appropriate multiplier, such as 3x or 4x.
  • A browser that supports the srcset attribute uses only the images provided in that attribute—it ignores the src attribute. So specify all available image resolutions in the srcset attribute.

For more information, see the HTML specification for the <img> element.

Layout of images on a page

  • Don't try to place an image manually; for example, don't use a style attribute or other workarounds to control the image's left/right justification or the margins around the image. Instead, use your site's standard CSS image styles.
  • Don't make your image too small. It's fine for an image to take up the full width of a page.
  • Consider how the image will look when printed out.
  • In general, don't use an image that's wider than the column it appears in. On, for example, the main-body column is 856px wide, so use images that are no wider than that. In that context, the high-resolution 2x version of the image should be no wider than 1712px.

    • Screenshots at full resolution often take up too much space on the page, so you may have to resize them.
    • If the graphics were created by someone else (for example, a designer on the team you're supporting), it may be fairly trivial for them to provide you with images at the appropriate size. If the images they provide are wider than 856px, ask the designer if they can provide the relevant graphics as 856px/1712px pairs.
  • Don't link to the figure from within the same page unless it's a very long page and you're linking to it from quite far away on the page.
  • Don't center the image on the page.
  • Don't put the <img> inside a <p>.