A docs guide for writing accessible emails

[mmaxence]

The docs guides section has an i18n guide today, and nothing yet on accessibility. A lot of what makes an HTML email accessible is non-obvious: semantic structure, meaningful alt text on images, sufficient color contrast, a sensible reading order, a language attribute, and making sure the content still reads well when images are blocked.

Would a short guide on writing accessible emails with react-email be welcome? I would keep it practical and map each pattern to the components people already use, with small before and after examples. Happy to draft it if it fits the direction of the guides.

[Nimrodogachi]

A practical before/after pair for the guide would be a linked image used as the whole CTA, alongside a decorative image beside text inside the same link. The first needs alt text that communicates the link’s purpose. The second can use an empty alt attribute when the link text already supplies that information. W3C’s functional-image examples show the distinction clearly.

A short QA section could show an images-blocked preview, then reading-order and link-label checks with a screen reader in the target email clients. An alt-attribute check can catch omissions, but the wording and actual reading experience still need manual review.