An agent uses a vision model to write alt text for a web app's icon-only buttons and…

How it works

Alt text replaces an image for people who can't see or process it, and Microsoft's style guide says its goal is an equivalent experience. Good alt text conveys the image's purpose accurately but concisely. It takes interpretation and judgment, not a description of every detail.

Icon-only buttons and links follow their own rules:

1. If a button or link has an image but no text, the image must have alt text.
2. That alt text should say what the control does, not what the image shows.
3. Don't start with "Button" or "Link", because screen readers already announce buttons as buttons and links as links.

The style guide's own example is the question's scenario. For a settings button shown only as two gearwheels, the right alt text is "Open user settings." The wrong one is "Image of two interlocking gears, one larger than the other," because users won't know what the button does. The general guidelines add the matching rule for images: don't start alt text with a general word like "Image," because screen readers already announce images.

So the agent's draft breaks both rules: it starts with "Button:", and it describes the gears instead of the action. A prompt that enforces "describe the action" and "no Button/Link/Image prefix" fixes it.

The other options, and when you'd use them

• Use the image's file name: The guide says not to use the file name as alt text.
• Describe every visible detail: The guide says good alt text isn't about describing every detail. For controls, the action matters more than the picture.
• Repeat the image's caption: If an image has a caption, the alt text and caption shouldn't be redundant. Also avoid just repeating the surrounding text.

Exam tip

For icon-only controls, write the action ("Search this site.", "Open user settings.") and skip the role word. Decorative images get null alt text (alt=""), not a missing attribute.

References

• Alternative text (alt text)