alt-text-design
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.
How do I install this agent skill?
npx skills add https://github.com/owl-listener/inclusive-design-skills --skill alt-text-designIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive guidelines for designing accessible alternative text for images and visual content. It contains no code, external dependencies, or security risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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?
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/owl-listener/inclusive-design-skills/alt-text-design">View alt-text-design on skillZs</a>