Write useful image alt text: context, links, decoration and complex diagrams

Describe the information an informative image adds

For a fictional repair guide, “Bicycle” is too broad if the photograph’s purpose is to identify a damaged brake cable. A relevant alternative might be “Frayed brake cable beside the lever clamp.” It conveys the detail needed for that step without inventorying every visible object.

WAI’s informative-image guidance ties the alternative to the essential information. Describe a relevant position or relationship when it matters, such as which cable enters which connector. Avoid guesses about an unidentified person’s identity, feelings or circumstances.

Read the alternative with the preceding and following sentences. Does the instruction still make sense? If the article says “Turn the part shown here,” an unexplained image cannot supply that instruction for everyone. Name the part in the text and give the image an appropriate complementary description.

A caption can supply attribution, context or visible explanation. It does not automatically replace all missing image information. Equally, repeating a complete nearby explanation word for word can add unnecessary repetition. Review the information already present and what the image contributes.

Use an empty alternative deliberately for decoration

WAI’s decorative-image guidance recommends a null alternative, alt=””, for an HTML image that contributes no necessary information or functionality. Omitting the alt attribute is different: some screen readers may announce the filename instead.

A small decorative spark beside an already clear section heading may need no spoken description. Calling it “blue decorative spark icon” on every section would interrupt the reading. But a similar symbol used alone to identify a warning has a different role; its meaning must be available.

Do not classify an image as decorative merely because describing it takes effort. A photograph showing an assembly detail or a graph supplying the article’s evidence remains informative. If nearby text already provides the complete equivalent, confirm that this is true before choosing an empty alternative.

For purely decorative background artwork, use the site’s supported presentation controls. Do not move essential instructions into a CSS background just because that avoids an empty-alt warning. The editorial responsibility is to preserve the information, not satisfy one automated check.

Make linked images explain the destination or action

WAI’s functional-image guide explains that an image acting as a control should convey its function. An image-only link to a workshop homepage could be named “Example Workshop home”; “Orange logo” describes appearance while leaving the destination unclear.

For an image-only link that downloads a document, “Download the maintenance checklist (PDF)” is more useful than “Checklist cover.” Ensure the destination really is that document. A button that prints the page should communicate that action rather than only the shape of its printer icon.

If an image and visible text belong to the same link and the text already expresses the complete purpose, an empty image alternative can avoid duplication. Text merely positioned beside a separate image link is a different structure. Check the actual link and its accessible name, not the screenshot alone.

Review a card containing several links too. The image, title and extra action can create repeated or ambiguous stops. Ask the maintainer to preserve understandable link names and interaction rather than guessing that every logo should always use the same alt text.

Keep important text as real text where possible

WAI’s images-of-text guidance recommends avoiding images of text where ordinary text can achieve the presentation, with relevant exceptions such as logos. Real page text is easier for readers to enlarge, adapt and select.

For a promotional graphic, put the actual offer and essential conditions in ordinary page text. A short alt value cannot compensate for an important deadline or restriction that exists only as tiny lettering in an image. If the image itself supplies necessary words, the text alternative must preserve that essential wording.

A screenshot showing a software setting needs a different decision. Give the action in written steps and describe the relevant state or control rather than transcribing every menu. Remove credentials and personal data before preparing a public screenshot; alternative text must not reintroduce information deliberately removed from the image.

The website typography guide covers testing ordinary text under enlargement and spacing changes. Those checks remain useful even after a graphic has a good alternative.

Give charts and diagrams a detailed equivalent

WAI’s complex-image guidance describes a short identification together with a longer text representation of the essential information. A chart’s title alone does not explain the relationships that the article asks readers to understand.

For a fictional chart comparing three backup schedules, the short alternative might identify the comparison and point to a clearly named explanation below. That explanation should provide the relevant schedules, values, relationships and conclusion. An accessible data table may help when readers need the underlying numbers.

Do not squeeze a long table into one enormous alt attribute. Put structured information in ordinary headings, paragraphs and tables that readers can navigate. If a diagram’s sequence or connections matter, describe them in order; naming the boxes without the relationships loses the point.

Verify that a promised “full description below” actually exists and can be located. Update that equivalent when the chart changes. The appropriate detail depends on the image’s purpose; neither a generic “graph” label nor an unrelated dataset is sufficient.

Check the particular use in WordPress

The current WordPress Image block documentation describes alternative-text controls and marking an image as decorative. An alt edit in block settings applies to that specific page or post; the Media Library value supplies a default for insertion elsewhere. Check the interface available in your installed version and theme.

For an existing article, select the actual Image block, review its role and saved alternative, then save through the normal editor workflow. Do not assume that changing the library entry has repaired every older placement, gallery, featured-image template or third-party block using that file.

Reopen the page and inspect the served image element. Confirm the expected alt value or intentional empty attribute, the intended link and any nearby caption or detailed description. A title attribute, attachment description and filename are separate fields, not automatic replacements for the alt value.

Use the WordPress media and sizing workflow for image selection, generated sizes and visual quality. A correctly sized file can still have an unhelpful alternative, and good wording does not fix a broken image URL.

Review wording without turning it into keyword storage

Google’s image guidance recommends useful contextual alt text and warns against keyword stuffing. Repeating the target phrase, brand and location on every image does not explain each image’s role. Write for the reader first and keep the description accurate.

Mozilla’s img reference explains the alt attribute’s text replacement role. Keep ordinary alternatives concise, but move genuinely complex information into an appropriate longer equivalent rather than deleting essential meaning to fit an arbitrary character target.

Automatic descriptions can be a draft to review, not proof of context. A system may identify a bicycle but miss the damaged cable, invent text or misread a chart. Verify any generated wording against the image and its page purpose before saving it.