How to Write AI-Generated Alt Text and Audit It for Accessibility

Record the image's job before writing

Make a short inventory with the page URL, image or component ID, surrounding heading and text, caption, link or button action, current alternative, and the information a person would lose if the image disappeared. Inspect the rendered page, not just a media-library thumbnail. The same asset may be decorative in one placement and essential in another. The W3C alt decision tree starts with the image's purpose in context.

An empty alternative is a deliberate decision, not a missing field. W3C explains that omitting the attribute can cause a screen reader to announce an image filename. Its decorative-image examples also show why a repeated label inside the same link needs no second announcement. Do not hide an image that supplies an instruction, a status, or a destination the surrounding text does not supply.

Settle the cases that change with the component

A magnifying-glass image inside a button with no other name can provide the button's name. In the first example, the image alternative is the action. In the second, the button already has a name, so the image is silent. Both are possible patterns; use the one that matches the actual component and confirm its accessible name in the browser. See the W3C functional-image examples.

<button type="submit"><img src="search.png" alt="Search"></button>
<button type="submit" aria-label="Search"><img src="search.png" alt=""></button>

For a logo that is the sole content of a home link, the link still needs a destination name, such as alt="Grow AI Skills home". If the logo and the visible words “Grow AI Skills home” sit inside the same link, use alt="" on the logo to avoid reading the name twice. If the logo and words are separate links, inspect each link on its own. Adjacent words elsewhere on the page do not automatically name an image-only link.

For a screenshot, describe the part needed for the reader's next step, such as the selected setting or an error message. Do not narrate every button in a busy interface. If a screenshot contains necessary text, compare the AI draft with the image where names, amounts, dates, or warnings matter. W3C recommends real text where possible; when an image of text must remain, its alternative needs the same words. A product photo is only redundant when the surrounding text already supplies every visual detail needed for the buying decision. If color, shape, condition, or a defect matters, describe that detail without inventing a material or feature you cannot verify.

Handle images that do not fit one alt field

Five star icons may together mean “Rating: 3.5 out of 5.” Giving each star its own announcement makes the result harder to understand; W3C's grouped-image example puts the combined value on one image and empty alternatives on the rest. A gallery is different: each photograph may add a distinct view, so give each one an alternative that distinguishes it from the others. For an image map, name the overall image and each clickable region's destination; a single alt on the outer image cannot name every hotspot. See the W3C image-map example.

An icon drawn as inline SVG, CSS, or a font may have no img element to edit. Inspect the complete control's accessible name instead of hunting for an alt field; W3C's image tips also discuss naming SVG images. A purely decorative CSS background needs no announcement; essential words or actions must be available in the HTML. For an unlabeled icon-only button, a visible label or a correct accessible name on the button is the repair. Test the resulting name in the browser, including focus and mobile states.

Before sending screenshots or customer images to an external AI service, check whether they contain names, account details, private messages, or confidential product data. Redact or use a local process when those details are not needed to decide the alternative. Record the page context separately so the model does not have to guess a control's purpose from pixels.

Give AI the image and the page context

Send one record per placement. Include the exact nearby text, what a link or button does, whether any caption or data equivalent exists, and the intended reader task. A filename or pixels alone cannot establish whether a divider is decorative or whether a chart has an equivalent table. If you do not know the destination, the meaning of a status, or whether detailed data exists on the page, ask the page owner before accepting wording.

For each attached image, use only the image and page context I supply.
Return JSON matching alt-audit-draft-schema.json: one record per placement
with id, page_url, category, proposed_alt, long_description_needed,
draft_status, missing_context, and reason. Categories are decorative,
redundant, functional, informative, image_of_text, complex, or unresolved.

If purpose, control behavior, essential wording, or a claimed chart
equivalent is unknown, set draft_status to "blocked", proposed_alt and
long_description_needed to null, and list the exact questions in
missing_context. Use category "unresolved" if even the image's job is unknown.
An assertion that a table exists without its contents and published location
is missing context. Do not guess a value, person, date, feature, or destination.
Otherwise set draft_status to "draft", missing_context to [], and propose
an alt string. Use "" only when the image is decorative or its meaning is
already provided by the same component. Name a control's action, not its
icon shape. Transcribe essential image text exactly. No record is approved
until a human checks it on the final page.

I will supply each image, its page URL and placement ID, nearby text,
caption, link or button action, existing equivalent, and reader task.

Use the draft schema for new work. Its blocked state requires a null proposal and at least one missing-context question, so a guessed alternative cannot look like a finished answer. A valid JSON record still needs a human verdict; a schema cannot tell whether “Search” is the right action on this page. The older five-field schema belongs to the retained six-image exercise and has no approval state. Do not feed that exercise output straight into a CMS.

Work a Search icon from draft to HTML

In the original practice case, a magnifying-glass icon is the Search button's only visible label. The supplied context establishes the action, and the retained model output proposed “Search.” The record below shows how to carry that proposal into the new draft format; it is an editorial adaptation of the original output, not another model run.

{"records":[{"id":"02-search-button.png","page_url":"https://example.test/search",
"category":"functional","proposed_alt":"Search",
"long_description_needed":false,"draft_status":"draft",
"missing_context":[],"reason":"The supplied context says this icon submits Search."}]}

The reviewer compares the proposal with the actual button action. “Magnifying glass” would describe the shape but not the action. If the button really submits a search, the first HTML pattern above uses alt="Search". In the published page, focus the button and confirm that the browser reports its role as button and its accessible name as “Search.” Record that result before calling the placement complete. The example URL is reserved sample data; it is not a claim that this check ran on a public page.

Move that same icon beside visible “Search” text inside the button and the correct image alternative changes to alt="". The visible text names the button. On a narrow screen, check again: if responsive CSS removes the visible label, the control still needs an accessible name in that state. This is why copying one alt value across every use of an asset is unreliable.

The four-card status image needs a different check. Its proposed alt says three cards pass and one needs review. Compare those counts with the image and surrounding text. If the four statuses are already written in the same component, an empty image alternative may avoid repetition; if the graphic is the only source, “status graphic” would omit the result. Leave the review open until you see the actual placement.

Make a chart's detailed information available in text

A brief alt can identify a chart and its main point, but it cannot carry every series, unit, value, exception, and comparison. The W3C complex-image examples pair a short description with detailed information in nearby text, a table, or a clearly linked description. A table of values may still need a sentence about the relationship the page asks readers to notice.

The original six-image exercise is a useful failure case. Its prompt states that a complete table sits below the trend chart, so the retained output says no additional long description is needed. Neither the chart file nor the exercise includes that table. A real page with the same gap stays blocked until someone checks or supplies the equivalent. A passing prompt-and-checker result does not fill in missing page content.

For a complete worked example, open this separate synthetic chart. It was drawn from the three rows below; no model inferred its numbers. The vertical axis counts items, and the two lines show completed items and items needing review.

The completed count rises from 20 to 30 and then falls to 25; the review-needed count falls from 5 to 2 across the three months. On a page using this chart, put that sentence and the table next to the image. The short alternative can be: “Completed items rise then dip; review-needed items fall each month, January to March. Values in the table below.” The table supplies the exact values and series names that the short alt omits.

<img src="/downloads/alt-audit-sample-chart.png"
     alt="Completed items rise then dip; review-needed items fall each month, January to March. Values in the table below.">
<p>Completed items rise from 20 to 30, then fall to 25. Items needing review fall from 5 to 2.</p>
<!-- Put the three-row data table immediately after this paragraph. -->

Before approving a real chart, compare its plotted points, labels, units, dates, legend, annotations, and exceptions with the source data and published equivalent. Check that the table remains reachable in reading order. If the picture shows a threshold or warning absent from the table, add that fact to the nearby explanation. Mark the equivalent verified only after opening the finished page, not because a CMS field or AI prompt says it exists.

Review each draft against a visible source

Give a reviewer the image and the whole component together. The review-ledger template has separate columns for the AI proposal, evidence checked, final alt, owner, review status, and published-page check. Use blocked until missing facts are resolved, and approved only after a person checks the wording. Track the published-page result separately as pending, pass, or reopen. Leave final_alt blank on blocked rows; export only reviewer-approved values to the CMS. The following checks catch problems a character limit cannot:

Here is how the record changes across the worked cases. “Pending” means a reader still has to check the actual published page; the synthetic examples do not claim to have passed that step.

For each row, store the URL and placement ID rather than only the filename. A CMS may reuse one file in a decorative card and an image-only link; the final alternative belongs to the placement. When a reviewer changes the AI draft, record why. After the page is published, add the URL, browser and assistive-technology combination used, observed accessible name or missing detail, and a pass or reopen decision. A corrected media-library field is not the same as a checked page.

A 180-character maximum is used by the downloadable six-fixture checker as an editorial boundary for that exercise. It is not a WCAG pass rule. If the image needs more than a short phrase or sentence, keep the short alt focused and put the detailed equivalent in page text. For a decorative img, confirm the final HTML contains alt="" rather than no alt attribute.

Inspect the published page, including changed states

1. Open the public URL, not the CMS editor. Inspect the actual img, SVG, or image button and its parent control. Check whether the intended alternative survived rendering and whether a decorative img has alt="" rather than a missing attribute.
2. In the browser's developer tools, select the complete link or button and read its role and computed accessible name in the Accessibility pane. For the Search example, the expected result is a button named “Search”; “Magnifying glass,” a filename, and an unnamed button require repair. Record what the browser actually reports.
3. Tab to each interactive image and activate it. Read the component in page order with the screen reader and browser combination your audience supports. Listen for duplicate labels, a missing action, or a chart announced without a clear route to its detailed information.
4. For a chart, follow the text equivalent in reading order. Compare its series, values, units, periods, and important annotations with the image and source data. If the equivalent is linked, check the link text and destination.
5. Repeat at mobile widths and in states that swap or reveal images: carousels, lazy-loaded versions, and CMS variants can render a different element. Review translated alternatives with the local page text. Record failures by URL and placement, fix them, and repeat the same check.

Automated tools can flag missing attributes and some unnamed controls. They cannot decide whether “Search” matches the action or whether a chart explanation preserves the page's meaning. Close a review row only after the reviewer records the final wording and the published-page observation.

Use the six fixtures for calibration, not certification

The original six-image set covers a divider, Search button, status cards, project notice, trend chart, and redundant logo. One retained model run passed all six fixture expectations for category, alt mode, long-description state, and required wording; deliberate wrong-category and invalid-ID mutations failed. That result checks the exercise's contract. It does not verify the chart's claimed table or a published page. No screen-reader, CMS, mobile, or translated-page test was part of that run.

To reproduce the fixture check, download the original context prompt, schema, retained output, independent expectations, and checker. The six PNG inputs are in the resource list below. Save these files together, then run python3 ai-alt-text-audit-check.py alt-text-observed.json --expectations alt-text-fixture-expectations.json --expected-count 6. The broader replay runner can repeat the disclosed negative mutations with python3 advanced-ai-replay.py alt.

For your own site, write expectations for each placement. Start with controls, charts, essential text, and safety information. Keep missing context and unpublished equivalents blocked in the review ledger until someone checks them.