alt-text-design

Q: How do I install alt-text-design?

Run npx skills add https://github.com/owl-listener/inclusive-design-skills --skill alt-text-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/alt-text-design/ (personal) or .claude/skills/alt-text-design/ (project).

by owl-listenerMedia & Creative

Write meaningful alternative text for images, charts, diagrams, and visual content. Use when creating or reviewing alt text, image descriptions, chart summaries, or any visual content that needs a text equivalent. Triggers on: alt text, image description, alternative text, screen reader, decorative image, chart description, infographic, data visualisation, complex image, meaningful alt.

Installs: 75
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/owl-listener/inclusive-design-skills --skill alt-text-design

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads alt-text-design automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Alt Text Design

Write alt text that conveys the same information and purpose as the visual content — not just what the image looks like, but what it communicates.

Core Principle

Alt text answers the question: if this image disappeared, what information would be lost? That's what needs to be in the alt text.

Decision Tree

1. Is the image purely decorative?

Background textures, dividers, visual flourishes
Images that repeat information already in adjacent text
Action: use empty alt (alt="") so screen readers skip it

2. Is the image functional?

A linked logo, an icon button, an image link
Action: alt text describes the function, not the image
Logo linking to homepage: alt="Company name — home"
Search icon button: alt="Search"
NOT alt="magnifying glass icon"

3. Is the image informative?

Photos, illustrations, screenshots that add information
Action: describe the information the image conveys
Photo of a damaged product: alt="Crack running along the bottom edge of the screen"
NOT alt="Photo of a phone" or alt="product-image-032.jpg"

4. Is the image complex?

Charts, graphs, diagrams, infographics, maps
Action: short alt text summarising the key message PLUS a longer description nearby (in the page text or a linked detail)
Bar chart: alt="Bar chart showing sales growth — details below" followed by a text summary of the data
NOT alt="bar chart" and not the entire data set in the alt attribute

Writing Good Alt Text

Be Specific

Bad: "A group of people"
Good: "Three team members reviewing a prototype on a whiteboard"

Convey Purpose, Not Just Appearance

Bad: "Red circle with a number"
Good: "3 unread notifications"

Match the Context

The same image needs different alt text in different contexts:

On a recipe page: "Finished risotto in a white bowl, garnished with parmesan and basil"
On a kitchenware product page: "Round white ceramic serving bowl, 22cm diameter"

Keep It Concise

Aim for one sentence, two at most
Don't start with "Image of..." or "Picture of..." — screen readers already announce it as an image
For complex images: keep alt text short and provide detail elsewhere

Specific Content Types

Charts and Graphs

Alt text: state the type and the key takeaway
Provide a text summary or data table nearby
"Line chart showing website traffic doubling between January and June 2026. Full data in the table below."

Screenshots

Describe what the screenshot shows that matters to the reader
"Settings panel with the notifications toggle switched off"
NOT "Screenshot of the settings page"

Icons with Labels

If the icon has a visible text label, the icon is decorative (alt="")
If the icon is the only indicator, the alt text must convey the meaning

Images of Text

Avoid images of text wherever possible — use real text
If unavoidable: the alt text must contain the full text in the image

Assessment Questions

Does every non-decorative image have meaningful alt text?
Does the alt text convey purpose, not just appearance?
Are decorative images marked with empty alt?
Do complex images have both short alt text and a longer description?
Would someone using a screen reader get the same information as someone seeing the image?

FAQ

What does the alt-text-design skill do?

How do I install alt-text-design?

Run npx skills add https://github.com/owl-listener/inclusive-design-skills --skill alt-text-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/alt-text-design/ (personal) or .claude/skills/alt-text-design/ (project).

Which AI agents can use alt-text-design?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is alt-text-design safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains alt-text-design?

It is published by owl-listener in owl-listener/inclusive-design-skills. It has 75 recorded installs.