hermes

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.

context

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.

task

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:

  1. 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="".
  2. Contains text? If the same text is already next to the image, use alt="". If the text is only a visual effect, use alt="". Otherwise the alt is that text.
  3. Adds meaning to the content? Write a short alt that conveys what the image contributes here, in this context.
  4. 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.
  5. 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.
constraints
  • 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.
output format

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".

examples
example

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

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install write-alt-text --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill write-alt-text -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

more in accessibility

All of Accessibility
PersonaAccessibility

Accessibility 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-specialist
PromptAccessibility

Audit 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-accessibility
PromptAccessibility

Audit 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-accessibility
PromptAccessibility

Build 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-widget
PromptAccessibility

Build 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-accessibility
PromptAccessibility

Fix 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