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 text, buttons, and other screen elements to audio and/or braille. If you are new to screen readers, I recommend watching a video to learn how it works.
Image descriptions are also beneficial to people who are colorblind, intellectually or cognitively disabled, and/or generally want more context about a photo.
This references WCAG criterion 1.1.1 Non-Text Content (Level A).
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 black rectangles. Below are two h2 titles that say, "Wonderful title" and one has text below it that says, "And a wonderful subtitle too."
Alt text: Website with headers h1, h2, and h3 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="">
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 not for people who have the ability and energy to write descriptions themselves, or for those who have the financial means to pay someone to write the descriptions. They are community-driven efforts to make the practice of writing itself more accessible and available to disabled, neurodivergent, and chronically ill people.
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.