How to Write Useful Alt Text for Website Images
A beginner, hands-on guide to write useful alt text for website images with browser inspection, exact code-level changes and verification.
By the end: You will implement and verify write useful alt text for website images on a real local/staging page.
You will implement and verify write useful alt text for website images on a real local/staging page.
Key terms before you start
These definitions make the steps easier to follow and help distinguish controls, files and concepts that can look similar at first.
What you need before starting
- A page you are allowed to edit
- Access to the HTML/CSS/JS or CMS/template that renders it
- A modern browser with Developer Tools
Step-by-step tutorial
Every step is shown below. Work through them in order and use each checkpoint to confirm the result before moving on.
Work on a local or staging copy
Open the project containing the website source. If this is a production site, use a staging copy or backup before structural changes.
A browser page is rendered from source files/CMS output; DevTools edits do not save back to the server.
Move it into the actual source and reload.
Open the page in a modern browser
Load the page, then press F12 or Ctrl+Shift+I (Windows/Linux) to open Developer Tools.
DevTools lets you inspect the DOM, applied CSS, computed sizes, requests and console errors.
Move it into the actual source and reload.
Identify why the image exists
Ask what information or function disappears if the image cannot be seen.
Alt text describes purpose in context, not every visible pixel.
Use the Styles/Computed panels to trace the final value instead of adding stronger selectors blindly.
Decide informative versus decorative
If it conveys useful information, write alt; if purely decorative, use alt="".
Do not omit alt attribute on decorative images because some screen readers may announce the filename.
Write the useful information
For a damage photo, describe the relevant damage; for a person, identify them only if identity matters and is appropriate.
Avoid “image of” unless that fact is itself meaningful.
Move it into the actual source and reload.
Do not duplicate adjacent text
If a caption already conveys exactly the information, consider whether repeating it adds noise.
Context determines the best alternative.
Handle linked images as actions
If the image is the only content of a link, the accessible name should describe the destination/action.
“Company logo” may be insufficient if the link purpose is “Wemaxa home”.
Move it into the actual source and reload.
Test missing image / accessibility tree
Inspect the accessibility name or temporarily block image loading.
The surrounding content should still make sense.
Test the public/staging URL logged out
Open the final URL in a private/incognito window.
CMS/admin sessions can hide caching, permission or styling differences.
Check caching, loaded asset URL, theme/template and logged-out view.
Document the changed file/rule
Record the file/template/component and purpose of the change in the project notes or version-control commit.
Future maintainers should not have to reverse-engineer why a rule exists.
Check caching, loaded asset URL, theme/template and logged-out view.
Reload the real page and reproduce the result after all temporary DevTools edits are gone.
Concrete examples
Copyable example
<img src="roof-damage.jpg" alt="Missing shingles around the chimney">
<img src="orange-swoosh.svg" alt="">Troubleshooting
Move it into the actual source and reload.
Check caching, loaded asset URL, theme/template and logged-out view.
Use the Styles/Computed panels to trace the final value instead of adding stronger selectors blindly.
The change has a traceable reason/location.
How the topic comes up in practice
Short excerpts from public discussions that directly relate to the task. Use the source link for the complete context.
“Proper semantics, alt text, labels, structured content, clear hierarchy... that's basically making your site readable in general.”
accessible, semantic websites ↗
“JPEG XL and WebP were significantly better than PNG at lossless compression of graphics images.”
modern web image formats ↗
Continue with these tutorials
Documentation and references
Use these primary and supporting sources to verify current controls, browser behavior and product-specific details.