Write alt text for images
Writes context-aware alt text for images on a page or in a document, or marks them decorative, following the W3C alt decision tree. Use when publishing images on the web.
Alt text is not a description of the picture. It is the text that replaces the picture for someone who cannot see it, so it depends on why the image is there. The same photo of a laptop needs different alt text on a product page, in a news story about a data breach, and as a decorative header. Common failures: "image of...", file names, repeating the caption, describing a linked logo instead of where the link goes, and long descriptions of decoration that make screen-reader users wade through noise.
Write alt text for these images:
Page context:
For each image, walk the W3C alt decision tree in this order, stop at the first branch that applies, and record it:
- Inside a link or button, or the only content of one? The alt describes the destination or action ("Acme home", "Search"), not the picture, and includes any text the image shows (label in name, WCAG 2.5.3). If the link or button already has visible text that says the same, the image is redundant: use
alt="". - Contains text? If the same text is already next to the image, use
alt="". If the text is only a visual effect, usealt="". Otherwise the alt is that text. - Adds meaning to the content? Write a short alt that conveys what the image contributes here, in this context.
- Complex (chart, diagram, map, infographic)? Write a short alt with the key takeaway, then a long description or data table to place on the page or link to.
- Decorative or redundant with nearby text? Use
alt="". Do not omit the attribute.
Writing rules:
- Stay within about characters. If you need more, the image is complex: use branch 4.
- Do not start with "image of" or "picture of". Name the medium only when it matters ("Oil painting of...", "Screenshot of the settings page...").
- Put the most important information first, end with a full stop, and match the page's language.
- Describe people only by attributes that matter to the content. Do not guess identity, gender, ethnicity, age or disability unless the context establishes it and it matters.
- No keyword stuffing, and no repeating the caption or the surrounding sentence.
- If you cannot see an image and its description is too thin to know what it shows or why it is there, ask instead of inventing details.
- Never invent text, numbers or details that are not visible in the image or stated in its description.
- For charts, give the trend or comparison that matters, not every data point; put the data in the long description.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
Alt text
| # | Image | Branch (functional / text / informative / complex / decorative) | alt | Long description needed? |
Write each alt value exactly as it should appear in quotes, including "" for decorative images.
Markup
An HTML snippet per image with the alt in place, plus figure and figcaption or a linked long description where branch 4 applied.
Questions
What you need to finish any image you could not do, or "None".
Image: company logo reading "Northwind", wrapped in a link to the home page. Context: site header. Branch: functional. alt: "Northwind home"
Image: line chart of monthly sign-ups rising from 1,200 in January to 4,800 in June. Context: quarterly report, paragraph says "growth accelerated". Branch: complex. alt: "Monthly sign-ups quadrupled from 1,200 in January to 4,800 in June." Long description: a table of the six monthly values.
Image: abstract gradient behind the page title. Branch: decorative. alt: ""
2 required values still a placeholder; the assistant will ask for them.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Accessibility
- level
- Beginner
- made for
- Writer / author, Editor, Frontend engineer, Content creator
- risk
- read-only
- version
- v1.0.0 · incubating
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md, ChatGPT, claude.ai
use in
npx @hermes-hq/hodios install write-alt-text --target claude-codenpx skills add hermes-hq/hodios-dist --skill write-alt-text -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
more in accessibility
All of AccessibilityAccessibility specialist
Accessibility specialist who builds and reviews with WCAG, the ARIA Authoring Practices and real assistive-technology behaviour in mind, ranking barriers by who is blocked.
accessibility-specialistAudit a mobile screen for accessibility
Audits an iOS, Android, React Native or Flutter screen for labels, traits, focus order, text scaling, touch targets, contrast and gestures, with platform fixes and a VoiceOver or TalkBack test script.
audit-mobile-accessibilityAudit web accessibility against WCAG 2.2
Audits markup or components against WCAG 2.2 and reports each issue by success criterion with user impact, severity and a concrete code fix. Use before a release or a compliance review.
audit-web-accessibilityBuild an accessible ARIA widget
Implements a combobox, tabs, dialog, menu, disclosure, tree or listbox per the ARIA Authoring Practices pattern, using native elements whenever they suffice. Use for custom interactive widgets.
build-aria-widgetBuild or fix an accessible form
Builds or repairs a web form with programmatic labels, grouping, autocomplete, helpful error messages and announced validation. Use for sign-up, checkout, settings or any data-entry form.
fix-form-accessibilityFix keyboard navigation in a component
Finds and fixes keyboard barriers in a UI component (focus order, traps, invisible focus, mouse-only controls) and adds a keyboard test checklist. Use when a widget fails without a mouse.
fix-keyboard-navigation