This page is in progress -
Why This is Important
An image description describes the essential information in an image. It is primarily for Blind and visually impaired people to access visuals.
Blind and visually impaired people use screen readers to interact with websites and apps. A screen reader is a type of assistive tech that converts things on screen to audio and/or braille. It's important that things are understandable and interactive to screen readers.
Keyboard accessibility is essential for people who do not use a computer mouse (which might be because they have unpredictable or very specific movement due to a motor disability). Many Blind and visually impaired people also use keyboard interactions in order to use their screen reader.
Error support is accessible to people with a diversity of disabilities. A cognitive disability might affect how a person perceives and understands things. A physical disability might lead to unpredictable movement. Other factors such as environment, stress, and multi-tasking may also lead to errors.
In order to be accessible, gestures and interactions must account for people with physical and motor disabilities, who might have unpredictable or very specific movement.
Image descriptions are essential for Blind and visually impaired people to access images. They are also beneficial to people who are colorblind, people with cognitive or intellectual disabilities, people who want more context about an image, etc.
This references WCAG criterion 1.1.1 Non-Text Content (Level A).
Level AAA compliance is considered more difficult to meet because it requires more resources to fulfill. It also might encompass conflicting access needs (meaning what is accessible to some might be inaccessible to others). Use your best judgment of your target audience and your team's capabilities to determine if this is a pragmatic goal to reach.
How to Implement This
Where to add the image description
Many people have suggested to me that the best place for the image description is actually in the caption that is also visible to sighted people. Why? Because:
- It's available to screen magnifier users
- It's available to sighted people who may need or benefit from the description
- It's available to people who want to share the image, so they can copy/paste the description
Typically, it is recommended to add the description in the alt attribute of the image, such as in below:
<img src="kittens.jpg" alt="3 small brown kittens taking a nap in a basket">
My current understanding of a more accessible experience is to add the complete description in the visible caption and add an abbreviated note in the alt attribute.
For example, here's what I'd recommend for the following image:
Image description: A website titled, "Amazing blog," which is labeled h1. The navigation, labeled main-nav, shows 4 tabs. Below are two h2 titles that say, "Wonderful title." The first heading has text below that says, "And a wonderful subtitle too."
Alt text: Website with headers and main-nav labeled
WCAG notes that decorative images do not require alt text because they do not add information to the page. In this case, the alt attribute should be written as:
<img src="pattern.png" alt="">
What makes an image decorative might depend on your audience. Some people prefer a lot of visual detail. Others do not want image descriptions unless the image itself conveys meaning. The direction you go will depend on your capacity and your target audience.
How to write an image description
Here's an image description writing guide that I created. I am constantly evolving it based on feedback, so feel free to leave comments. Here is a Brazilian Portuguese translation of my article: Como descrever uma imagem
Other guides for writing image descriptions:
- Image Description Guidelines - DIAGRAM Center
- Guidelines for Creating Image Descriptions
- Cooper Hewitt Guidelines for Image Description | Cooper Hewitt, Smithsonian Design Museum
Community support for image descriptions
Depending on your spoons or disability, writing image descriptions may not be feasible. There are community groups available to provide more collective access, where you can request other people to write it for you.
Please note: These groups are community-driven efforts to make the practice of writing itself more accessible and available to disabled, neurodivergent, and chronically ill people. For those who have the ability, energy, and/or financial resources to write descriptions, it's recommended that they are in a supportive role.
Interesting further reading
How to Test This
Keep in mind that these automated tools only test for the existence of alt text, and not their quality or how descriptive they are. In an interesting Carnegie Mellon study of image description on twitter it describes on page 6 a rating of the quality of descriptions, from "irrelevant" to "great: almost everything described."
Corrections to decorative alt text by Cam Beaudoin, The A11y Coder
Contribute and Give Feedback
If you would like to provide feedback or contribute content on this resource, please fill out the form below.