Add descriptive alt text to every image — Claude Code

Missing alt text breaks accessibility for screen readers, tanks Google Images ranking, and means AI answer engines cannot cite your visual content.

rocket_launch

Fixing this in Claude Code

Anthropic's official terminal coding agent

Claude Code can grep the whole codebase first, plan the change, then edit every affected file. Paste the prompt below into your Claude Code chat and the fix rolls out across the project in one pass.

Using a different tool? Pick your stack:

Lovable Cursor Bolt v0 Replit Windsurf Claude Code Base44

The prompt for Claude Code

Copy and paste this into your Claude Code chat exactly as-is.

Run Claude Code in the project root and make these exact changes, scanning the whole codebase first:

Add alt text to images

1. Walk through every <img> tag and add a descriptive alt attribute.
2. For decorative images, use alt="" (empty but present).
3. Never write alt="image" or alt="picture" — describe the actual content.

Why this matters

Alt text is the text equivalent of an image. Screen readers read it aloud, Google Images uses it for ranking, and AI tools like ChatGPT and Claude use it to describe your content when they cite the page. Without it, you fail accessibility audits (WCAG 2.1 level A), lose Image SERP traffic, and become harder to cite.

AI-generated code is notoriously bad at alt text — either it ships no alt attribute, or it writes `alt="image"`. Both count as failures. Google specifically calls out unhelpful alt text in its image SEO docs as something it penalizes.

Fixing alt in bulk with an AI prompt is a 15-minute win that lifts accessibility score, unlocks Image SERP traffic, and improves your GEO score at the same time.

How to use this prompt in Claude Code

1. Open your Claude Code project.
2. Copy the prompt above with the copy button.
3. Paste into the Claude Code chat and send.
4. Review the diff, accept the changes, redeploy.
5. Verify the fix using the checklist below.

Common mistakes to avoid

error_outlineWriting `alt="image"` or `alt="photo"` — counts as no alt text for ranking.
error_outlineStuffing keywords: `alt="buy red shoes cheap online"` — penalized.
error_outlineForgetting `alt=""` on decorative images — screen readers read the filename, which is worse than nothing.
error_outlineUsing the image filename as alt automatically — `alt="IMG_2041.jpg"` is useless.
error_outlineWriting alt that duplicates the visible caption verbatim.

How to verify the fix worked

check_circleRun axe-core or Lighthouse Accessibility — "Images have alt text" must pass.
check_circle`document.querySelectorAll("img:not([alt])").length` in console should be 0.
check_circleTurn off images in the browser (Chrome DevTools → Settings → Disable Images) — can you still understand the page?
check_circleGoogle Search Console → Images report — indexed images should have useful context.

Frequently asked questions

Should alt text describe every pixel or convey meaning?expand_more

Convey meaning. If the image is a chart, describe what the chart shows. If it is a product, describe the product. A blind user should get the same information a sighted user gets.

Can alt text include keywords?expand_more

Yes, if the keyword naturally describes the image. "Woman running on a beach at sunset" is better than "running beach sunset keyword".

How long should alt text be?expand_more

Short sentence or phrase. Under ~125 characters. Screen readers read it as one unit and long alt is painful.

Want all 34 prompts tailored to your Claude Code site?

Pantra scans your site in 10 seconds, detects the stack, and generates the exact prompts that apply — only the ones you actually need.

Scan my site

Related Claude Code prompts

Images