SEO - missing image alt text #17672
Conversation
mnelsonBT
requested review from
minimalsm,
pettinarip and
wackerow
as code owners
✅ Deploy Preview for ethereumorg ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
github-actions
Bot
added
content 🖋️
myelinated-wackerow
left a comment
myelinated-wackerow
left a comment
There was a problem hiding this comment.
PR #17672 Review: SEO - Missing Image Alt Text
Summary
Many of the alt text additions in this PR are counter to WCAG best practices. Roughly half should be reverted to alt="".
Category 1: Logos with adjacent text names -- SHOULD STAY alt=""
The W3C alt decision tree explicitly states: if an image "shows content that is redundant to real text nearby," use alt="".
This applies to all the product/client logos in this PR:
- Bug bounty page: Besu, Erigon, Geth, Lighthouse, Lodestar, Nimbus, Nethermind, Prysm, Reth, Teku, Grandine, Solidity, Vyper
- Deposit contract page: ConsenSys, Ethereum Foundation, Blockscout
Each of these logos sits right next to the product title text. Adding alt="Besu logo" means a screen reader would say something like "Besu logo, Besu" -- that's redundant and actually worse for accessibility.
Category 2: Decorative/illustrative hero images -- SHOULD STAY alt=""
Per the WAI decorative images tutorial, images that are "illustrative of adjacent text but not contributing information" are classified as decorative ("eye-candy").
This applies to:
- Learn page: All illustrative card images (eth token, impact, future, DeFi, stablecoins, rhino, doge computer, etc.) -- each accompanies a card with descriptive text/links
- Homepage: Section hero images ("Ethereum learn hub hero image", "Ethereum quizzes hub hero image", etc.) -- these describe the section, not the image, and the section text already conveys that
- Translation program:
enterprise-eth.pngandparticipate.png-- generic illustrations - Blockie avatar: Supplementary to the displayed address
Category 3: Technical diagrams and screenshots -- SHOULD have alt text (correct additions)
These are the correct additions in the PR:
cons_client_net_layer.png/exe_client_net_layer.png-- network architecture diagramsnode-architecture-text-background.png-- node architecture diagram- Grafana dashboard screenshots (grafana1-8.png)
- Etherscan/Dune Analytics screenshots
- Charts (daily blocks, gas limits, gas usage)
- GraphQL query demo GIF
- Verkle tree diagram
- Alchemy API key walkthrough GIF
These convey information that isn't available in surrounding text, so they genuinely need descriptive alt text.
Key Rules Applied
| Rule | Source | Application |
|---|---|---|
Redundant to adjacent text -> alt="" |
W3C Alt Decision Tree | Product logos next to product names |
Eye-candy illustrating adjacent text -> alt="" |
W3C Decorative Images | Hero/card illustrations |
| Diagrams, charts, screenshots -> descriptive alt | WCAG 1.1.1 | Technical diagrams, data charts, UI screenshots |
Recommendation
Revert logo and decorative illustration alt text back to alt="". Keep the diagram/screenshot/chart alt texts as-is.
Sources
- W3C WAI: Decorative Images
- W3C WAI: Alt Decision Tree
- W3C WAI: Tips and Tricks for Images
- Deque: Writing Alt Text for Accessibility
Reviewed by Claude (claude-opus-4-6)
wackerow
left a comment
wackerow
left a comment
There was a problem hiding this comment.
cc: @mnelsonBT Dropped some comments.. Lemme know if you need a hand!
| title: "Besu", | ||
| link: "https://besu.hyperledger.org/en/stable/", | ||
| image: besu, | ||
| alt: "Besu logo", |
There was a problem hiding this comment.
clients, specs and languages arrays are the ones that render here in this screenshot, and already have associated text for the brand. In these cases I'd suggest keeping them off (at alt="" which is the default fallback).
| <ClientRow> | ||
| <Client> | ||
| <Image src={besu} alt="" {...iconImageProps()} /> | ||
| <Image src={besu} alt="Besu logo" {...iconImageProps()} /> |
There was a problem hiding this comment.
👍 These look good, as they're associated with the eleven (11) client logos that do not have any associated text already, nested under "Clients featured in the bounties"
There was a problem hiding this comment.
BUT: We also need to keep non-English in mind. We have an entry in the common namespace "item-logo": "{item} logo", that allows us to use the item-logo key and provide an item name (the brand name) so it interpolates into each language accordingly.
Currently, this means we need to load the common namespace first
// below: const t = await getTranslations({ namespace: "page-bug-bounty" })
const tCommon = await getTranslations({ namespace: "common" })And then refactor the alt attributes to:
// Using Erigon as an example:
alt={tCommon("item-logo", { item: "Erigon" })}This namespace may undergo some changes soon (see #17662) but in the meantime, if we want to do this correctly, that would be the approach.
There was a problem hiding this comment.
Would revert these additions ✂️
There was a problem hiding this comment.
Same ✂️
The component this data is passed to have alt="" hard coded already, so not needed
| <Image | ||
| src={banner} | ||
| alt="" | ||
| alt={`${location} Ethereum community hub banner`} |
There was a problem hiding this comment.
Would revert this one back... decorative logo, with a title already available
| alt={`${location} Ethereum community hub banner`} | |
| alt="" |
- Undo prop changes for Bento images - rm english alt text for hub logo decoration
- Remove alts for decorative logos that have associated text - Update lone logos without associated text to use i18n alt label
wackerow
left a comment
wackerow
left a comment
There was a problem hiding this comment.
@mnelsonBT Lgtm... Applied those patches. Take another look and if you're good with this can pull in for next weeks deploy
LGTM @wackerow - thank you for doing so! |
3 participants
Resolves missing alt text on images across ethereum.org
Description