Using images with accessibility

Images enhance understanding of complex workflows and UI elements. Ensure they include alt text for accessibility, and follow guidelines for effective use in documentation.

Images can help sighted readers understand complex workflows, refer to an icon, or view a portion of the UI, but they must include surrounding text to be meaningful for users with visual disabilities. If your image isn't visually valuable, replace the image with text instead. When you create an image, check that the image reinforces the understanding of the surrounding text and includes alt text.

Users with visual disabilities need alt text to perceive images with a screen reader. Users who are neurodivergent might use screen readers to assist their understanding of various types of images. Users who don't speak English as their first language can use tools to translate alt text for images that use English labels. All users rely on text that accurately and thoroughly describes every image in Splunk documentation.

For more guidance on using images, see Including images in Splunk docs.

Guidelines for using images

Follow these guidelines when using images in your documentation:


Category	Guidelines	Resources
Image content and surrounding text	Don't include new information in an image. Introduce new information in the surrounding text of the image. Lead into an image with a description of the content and the purpose of the image.	See Best practices for writing surrounding text.
Color and color contrast	When using color, include other indicators to convey the message of the image. Use a combination of colors, shapes, patterns, explanatory text, and labels. Ensure your image meets the contrast ratio for users with visual disabilities. See https://webaim.org/resources/contrastchecker/ on the WebAIM website.	See Diagrams.
Screenshots	When including screenshots in your content, be sure to capture the UI while using the light theme with your screen zoomed to 100%. Don't use the dark theme.	See Screenshots.
Alt text	All informative images in Splunk docs must have alt text. This includes screenshots, diagrams, GIF, and inline images. Keep alt text concise. For inline images, GIFs, and complex diagrams, include adequate surrounding text so you don't place too much information in the alt text. Ensure that the entire section still makes sense if you replace an image with its alt text. Decorative images, such page dividers or brand graphics that don't add information to a page, don't require alt text.	See Best practices for writing alt text.

Best practices for writing surrounding text

When you're writing surrounding text, keep the following points in mind:

For an inline image, write the name or description of the icon in the sentence. Put the icon in parentheses immediately after that text.
For a complex diagram, use lines of surrounding text to explain the diagram. You can include a simple sentence in the alt text that refers to the precise location of this descriptive text.
Lead into the image with a complete sentence. Punctuate the end of the sentence with a colon.
It's okay to use "before", "after", and "following" in the surrounding text when you refer to an image. Don't rely on directional language, such as "left", "right", "above", or "below", when you refer to a location in a UI or document. These instructions are unhelpful screen reader users.

Best practices for writing alt text

When you're writing alt text for an image, keep the following points in mind:

Use short phrases or complete sentences with punctuation.
Avoid starting alt text with general phrases like "Image of". If you want to specify the type of image, you can describe the image using phrases like "Screenshot of" or "Diagram of".
Focus on describing the meaning of the image rather than what you see in the image.
- Lead with the most important information.
- Introduce only relevant information based on the context of the topic.
- Don't call out implications or add new information to the alt text.
- Keep the alt text concise overall. If you need to add detailed information to convey the meaning of the image, add this information to the surrounding text.
For complex images, introduce the image with the surrounding text first. Then, add the most important information about the image in the first sentence of alt text. Add another sentence of alt text that describes where the surrounding text is on that page.

For examples of alt text, see Alt text examples.