How to Make Screenshots Accessible: Alt Text, Annotations & Best Practices

The accessibility problem with screenshots

Screenshots are images. Screen readers can't read images. If your documentation, bug reports, or tutorials rely on screenshots without alt text, a significant portion of your audience gets nothing — just "image" or silence where your content should be.

This isn't a niche concern. The WebAIM Million report consistently finds that missing alt text is the most common accessibility error on the web. And developer documentation is one of the worst offenders because it's screenshot-heavy and often written quickly.

The good news: making screenshots accessible isn't hard. It takes about 15 seconds per image once you know the pattern.

How to write alt text for screenshots

Alt text for screenshots follows different rules than alt text for photos or icons. A photo of a sunset might get "orange sunset over the ocean." A screenshot needs to describe what the user would learn by looking at it.

The formula: describe the purpose of the screenshot, not every pixel in it. Ask yourself: "If someone can't see this image, what do they need to know?"

When to use alt text vs. a text alternative

Alt text works for screenshots that illustrate a concept or show a UI state. But some screenshots contain critical information that needs to be fully available in text — not summarized in an alt attribute.

If your screenshot contains readable text that is the content (an error message, a code snippet, a terminal command, configuration values), provide that text in the document itself, not just in the image. The screenshot becomes supplementary — it confirms the text, but the text stands alone.

For example, if you're documenting a Terminal command:

<!-- Accessible approach -->
<p>Run this command to resize the image:</p>
<pre><code>sips --resampleWidth 1440 screenshot.png</code></pre>
<img src="terminal-output.png"
     alt="Terminal showing successful resize of screenshot.png to 1440px wide">

<!-- Inaccessible approach -->
<img src="terminal-output.png" alt="Terminal command">

The first approach gives screen reader users the actual command. The second approach tells them there's a terminal command but not what it says.

Annotated screenshots and accessibility

Annotations — arrows, circles, numbered callouts — are invisible to screen readers. If your screenshot has a red arrow pointing to a specific button, the alt text needs to describe what the arrow points to, not just that an arrow exists.

For numbered callout screenshots (common in step-by-step tutorials), describe the sequence in the alt text or in surrounding text:

<img src="steps-annotated.png"
     alt="Three-step workflow: (1) click File menu, (2) select Export,
          (3) choose PNG format from the dropdown">

Even better: describe the steps in the body text and use the screenshot as a visual confirmation. This way the content is accessible regardless of whether the image loads.

Screenshots in Markdown documentation

Most developer docs are written in Markdown, where images look like this:

![Alt text goes here](screenshot.png)

The problem: developers frequently leave the alt text empty or write placeholder text like "screenshot" or "image." Every screenshot in your docs should have meaningful alt text. Here's a Markdown-specific checklist:

• Never use empty alt text — ![](screenshot.png) makes the image invisible to screen readers
• Never use the filename — ![screenshot-2026-04-05.png](screenshot.png) is meaningless
• Keep it under 125 characters — screen readers handle long alt text poorly; if you need more, use surrounding text
• Don't start with "Screenshot of" — screen readers already announce "image," so this is redundant
• Include the key information — what app, what state, what's important about what's shown

Screenshots in GitHub issues and PRs

GitHub renders Markdown images in issues and pull requests. When you paste a screenshot into a GitHub issue, it generates markup like this:

![image](https://user-images.githubusercontent.com/...)

That "image" alt text is useless. Take the extra 10 seconds to replace it with something meaningful. Especially in bug reports — the screenshot is often the most important part of the issue, and it should be accessible to everyone on the team.

A good pattern for bug report screenshots:

![Login form showing "Invalid credentials" error after entering correct password](screenshot.png)

This tells a screen reader user exactly what the bug is, even without seeing the image.

Using AI to generate alt text for screenshots

AI vision models (Claude, GPT-4o, Gemini) are remarkably good at describing screenshots. If you have a backlog of undescribed screenshots in your documentation, you can use AI to draft alt text quickly.

The workflow: paste the screenshot into Claude or ChatGPT and ask for alt text. The AI will describe what's in the image. Review and edit the result — AI-generated alt text tends to be too long and too literal. You want the purpose, not a pixel-by-pixel description.

For batch processing, you can script this with the Claude API or use a tool that supports image inputs. Feed each screenshot through the API with a prompt requesting concise alt text, and you'll get a first draft for every image in minutes.

Accessibility checklist for screenshot-heavy documentation

Tools that help with screenshot accessibility

axe DevTools and WAVE: browser extensions that flag missing or empty alt text on any page, including documentation sites. Run them on your docs to find every image that needs alt text.

markdownlint: a Markdown linter that can be configured to flag images with empty alt text. Add it to your CI pipeline to catch missing alt text before it merges.

# .markdownlint.json
{
  "MD045": true
}

Rule MD045 flags images without alt text. This catches ![](image.png) patterns in pull requests automatically.

macOS VoiceOver: test your documentation with the built-in screen reader. Press Cmd+F5 to toggle VoiceOver, then navigate through your doc and listen to how screenshots are announced. You'll immediately hear which images need better alt text.

Why this matters for developer teams

Accessible documentation isn't just about compliance. When your screenshots have good alt text, your docs are searchable (alt text is indexed by search engines and in-page search), they work in low-bandwidth environments (alt text displays when images fail to load), and they're usable by every member of your team regardless of ability.

The pattern is simple: every time you add a screenshot, spend 15 seconds writing alt text that describes what the reader would learn by looking at it. Over time, this becomes automatic — and your documentation becomes significantly better for everyone.