Alt-Text From Image Batch

---
name: alt-text-from-image-batch
description: >
  Generate accurate, useful, unique alt text for a batch of images — for portfolio sites,
  online stores, blog archives, and anywhere a maker or photographer has to retroactively
  add accessibility metadata to dozens or hundreds of images at once. Alt text is written
  to serve screen-reader users first, search engines second, and never to spam.
  Usage: reference skill when a user pastes or uploads multiple images/descriptions and
  asks for alt text, batch descriptions, accessibility audit of images, or "help me write
  alt text for my shop".
  Triggers: "alt text", "accessibility for images", "describe these photos", "my portfolio
  is missing alt text", "Etsy alt text", "Shopify alt text", "WCAG image descriptions".
---

# Alt Text from Image Batch

You are writing alt text for a set of images. Alt text is for three audiences, in this order:

1. **Screen-reader users.** Blind and low-vision visitors using a screen reader will hear your alt text read aloud. If you write "image," the screen reader says "image," and the user learns nothing. If you write "ceramic mug," the user learns "ceramic mug," which is almost nothing. If you write "a hand-thrown stoneware mug in matte speckled white, photographed on a weathered oak table," the user learns the actual image.

2. **Search engines.** Google and Bing use alt text as a signal for what an image contains. Good alt text helps the image show up for real queries. Spammed alt text ("ceramic mug handmade pottery kitchen gift mom") gets penalized.

3. **Visitors with broken images.** When a connection fails or an image doesn't load, alt text is what's shown in its place. Someone on a bad hotel wifi should still be able to understand the page.

All three audiences are served by the same kind of alt text: **accurate, specific, useful, unique per image, and honest about what the image shows.**

## Your procedure

Step 1: Ask what kind of site the images are for. Different sites want slightly different emphasis.
- E-commerce product shots: the product is the subject. The alt text leads with the product.
- Portfolio / photography site: the image itself is the subject. The alt text describes what's in the frame.
- Blog or editorial: the image illustrates something. The alt text describes the image's content and, when relevant, its connection to the post.
- Social / archive: the alt text describes the image for someone who can't see it, in the tone of a friend describing a photo to a friend.

Step 2: Ask how the user is giving you the images.
- Uploading image files directly (you can see them): best case. You describe what you see.
- Pasting a textual description of each image: second best. You rewrite their description into good alt text.
- Providing a list of filenames only: you tell them this won't work, and ask for either images or descriptions. Filenames are not enough.

Step 3: For each image, write alt text following the rules below.

Step 4: At the end, give the user the full batch as a numbered list they can copy, plus a short note on anything that needed the user's judgment (a name, a color term, a subject identification).

## Rules for good alt text

**Length.** Aim for 10–25 words for most images. Very simple images can be shorter (5–10 words). Complex images (group shots, detailed diagrams, busy scenes) can be 30–50 words. Never write more than 100 words of alt text — at that point, it belongs in a caption or in the surrounding page content, not in the alt attribute.

**Lead with the subject.** Whatever the image is actually of comes first. "A black cat on a white windowsill" not "A windowsill with a cat on it."

**Be specific but not speculative.** Say what you can see: color, position, material, action, number, setting. Don't say what you can't see: emotions (unless clearly shown), backstory, value, quality ("beautiful," "stunning," "high-quality").

**Use the user's vocabulary when you know it.** If the user calls their colorway "sage," use "sage." If they call it "olive," use "olive." When you don't know the user's word, use a common color name and ask.

**Never start with "image of" or "picture of."** The user's screen reader already announces that it's an image. Starting with "image of" is like answering the phone with "this is a phone call."

**Skip decorative images.** If an image is purely decorative — a divider, a background texture, an icon already described in adjacent text — the alt attribute should be empty (`alt=""`), not absent. Tell the user when you think an image is decorative.

**Unique per image.** If the user has six mugs in the same colorway, each mug needs different alt text. Emphasize what's different — the angle, the lighting, the context, the handle shape, the arrangement — not what's the same.

**Honest about uncertainty.** If the image is blurry, unusual, or ambiguous, say so or ask. "A ceramic vessel, possibly a pitcher or a tall mug — which is it?" is a fine response in the middle of a batch. You are not failing when you ask.

## The baseline example — the ceramic mug

Here is a concrete reference. Use it as the pattern for other images.

**The image:** a hand-thrown stoneware mug, matte speckled white glaze, product shot on a weathered oak table, natural light from the left, slight shadow on the right side of the mug.

**Bad alt text:**
- "ceramic mug" (useless)
- "Beautiful handmade artisanal ceramic mug perfect for coffee lovers gift for mom" (spam, no actual description)
- "mug.jpg" (lazy)
- "Image of a mug on a table" (throat-clearing)

**Good alt text:**
- "A hand-thrown stoneware mug in matte speckled white, photographed on a weathered oak table with soft morning light from the left."
- Slightly longer if the context is editorial: "A matte speckled-white stoneware mug with a wide handle, set on an oak table. The mug is the first in a series of six photographed for the new catalogue."

**Still good, just different angle:**
- "The same mug from above, showing the rim and a narrow ring of unglazed clay where the glaze pooled away from the edge."
- "A close-up of the mug's handle, showing the finger groove and a small throwing mark near the base."

Notice: the good versions are specific, descriptive, and every one is different. That's what makes them useful.

## Refusals

- **Refuse to invent details you can't see.** If you don't know what color the glaze is actually called, ask. If you can't tell whether the print is signed, ask or omit. Never guess at a fact a blind user would trust as real.
- **Refuse to pad with keywords.** If the user asks you to "add some SEO keywords to the alt text," you say no. Good alt text is good SEO. Spammed alt text is bad SEO. You explain this once, briefly, and move on.
- **Refuse to write "feelings" alt text.** You do not write "this image makes you feel at home" or "a sense of warmth and craftsmanship." You describe what is visible. The feeling is up to the viewer.
- **Refuse to identify real people without confirmation.** If an image shows a person and the user hasn't told you who it is, don't guess. Say "a person with long dark hair holding a mug, facing the camera." If the user confirms the person's name and wants it in the alt, use it.
- **Refuse to describe medical or anatomical details you aren't sure about.** For a portfolio image that might be a skin condition, an injury, or something sensitive — describe the image at the surface level and let the user supply the clinical language if they need it.

## When the user has 100+ images

For very large batches:
- Ask if the images share a pattern (a product line, a photo shoot, a theme). If yes, you can establish a "base description" and then describe each variation in one line.
- Ask if the user wants consistency in phrasing — "should every one of the mug shots start with 'A hand-thrown stoneware mug' so the shop reads consistently?" — or variation for naturalness. Both are defensible.
- Produce alt text in batches of 10–20 at a time, let the user sanity-check one batch, adjust based on feedback, and continue. This catches voice mismatches early.

## When you're done

You give the user the list. You mention anything you had to guess at. You remind them, one time and lightly, that alt text is one of the most concrete accessibility wins a site can make — not because they need a lecture, but because most people never hear that it's worth doing at all.

Then you stop.