Email Accessibility Skill
Reference data for HTML email accessibility under email client rendering constraints. Used by email-accessibility agent.
Email Client Rendering Constraints
Email HTML operates under severe constraints compared to web browsers. Support below is from caniemail.com (Gmail webmail, Outlook for Windows, Apple Mail for macOS, Yahoo webmail, Outlook.com; tests dated 2019-2026). Clients change, so retest before relying on a row.
| Feature | Gmail | Outlook (Win) | Apple Mail | Yahoo | Outlook.com |
|---|---|---|---|---|---|
Semantic HTML (<nav>, <main>) |
Partial | Not supported | Supported | Not supported | Partial |
role attribute |
Supported | Supported | Supported | Partial | Supported |
aria-label, aria-hidden |
Supported | Supported | Supported | Not supported | Supported |
<style> blocks |
Partial | Partial | Supported | Supported | Supported |
| External CSS | Stripped | Stripped | Stripped | Stripped | Stripped |
| JavaScript | Stripped | Stripped | Stripped | Stripped | Stripped |
| CSS Grid | Supported | Not supported | Supported | Supported | Supported |
| CSS Flexbox | Supported | Not supported | Supported | Supported | Supported |
<button> element |
Supported | Not supported | Supported | Partial (submit only) | Partial (reset only) |
tabindex |
Stripped | Stripped | Supported | Stripped | Stripped |
Key Constraint: Outlook Desktop uses the Word rendering engine, not a browser engine
Accessible Email Patterns
Table-Based Layout (Required for Outlook)
<table role="presentation" cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td align="center" style="padding: 20px;">
<!-- Content here -->
</td>
</tr>
</table>
Rules:
- ALL layout tables MUST have
role="presentation"to prevent screen readers from announcing table semantics - Data tables (actual tabular data) should NOT have
role="presentation"- they need proper<th>,scope, and<caption> - Use
cellspacing="0" cellpadding="0" border="0"on layout tables
Images
<img src="hero.jpg" alt="Product launch announcement: 50% off all subscriptions through March" width="600" height="300" style="display: block; max-width: 100%;">
Rules:
- Every
<img>must havealtattribute - Decorative images:
alt=""(empty, not omitted) - Set explicit
widthandheight- prevents layout shifts when images are blocked - Many email clients block images by default - alt text is the only fallback
- Style images with
display: blockto prevent gaps in Outlook - Use
style="font-size: 14px; font-family: Arial, sans-serif; color: #333333;"on the<img>tag - some clients display alt text using these styles
Links
<a href="https://example.com/subscribe" style="color: #005a9c; text-decoration: underline;">
Subscribe to our accessibility newsletter
</a>
Rules:
- Link text must be descriptive (no "click here" or "read more")
- Always use
text-decoration: underline- color alone can't distinguish links (WCAG 1.4.1) - Include
styleattributes directly on<a>tags - some clients strip<style>blocks - For CTA buttons, use the bulletproof button pattern (see below)
Bulletproof Buttons (Work in All Clients)
<table role="presentation" cellspacing="0" cellpadding="0" border="0">
<tr>
<td style="border-radius: 4px; background: #005a9c;">
<a href="https://example.com/action" style="background: #005a9c; border: 15px solid #005a9c; font-family: Arial, sans-serif; font-size: 16px; line-height: 1.1; text-align: center; text-decoration: none; display: block; border-radius: 4px; font-weight: bold;">
<span style="color: #ffffff;">Get Started</span>
</a>
</td>
</tr>
</table>
Headings
- Use heading elements (
<h1>through<h6>) for visual and semantic structure - Maintain heading hierarchy (don't skip levels)
- Note: heading elements work in most email clients even where other semantic HTML is stripped
Language
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
- Always set
langattribute on<html>element - Include
xmlnsfor XHTML compatibility (some email clients require it)
Dark Mode Adaptation
<!-- Meta tag for dark mode support -->
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
<style>
@media (prefers-color-scheme: dark) {
.email-body { background-color: #1a1a1a !important; }
.text-content { color: #e0e0e0 !important; }
}
</style>
Rules:
- Test contrast ratios in both light and dark modes
- Some clients invert colors automatically - use
data-ogsb="ignore"for Outlook.com to prevent unwanted inversions - Transparent PNGs work well in both modes; JPGs with white backgrounds look broken in dark mode
Reading Order
- Email reading order follows the HTML source order (no CSS Grid reordering possible in email)
- Single-column layouts are most accessible - multi-column requires careful
dir="ltr"and table cell ordering - For RTL languages, use
dir="rtl"on the<html>element and reverse table cell order
Framework Patterns
MJML
<mj-image src="photo.jpg" alt="Description of the image" />
<mj-button href="https://example.com" background-color="#005a9c" color="#ffffff">
Accessible Button Text
</mj-button>
Foundation for Emails
<img src="photo.jpg" alt="Description" class="float-center">
<button class="button large" href="https://example.com">
<a href="https://example.com">Accessible Button Text</a>
</button>
Email Accessibility Checklist
Each check, with its WCAG SC and priority.
| Check | WCAG SC | Priority |
|---|---|---|
All layout tables have role="presentation" |
1.3.1 | Critical |
All images have meaningful or empty alt |
1.1.1 | Critical |
| Link text is descriptive | 2.4.4 | Serious |
| Color contrast meets 4.5:1 | 1.4.3 | Serious |
Language is set on <html> |
3.1.1 | Serious |
| Heading hierarchy is logical | 1.3.1 | Moderate |
| Links are underlined (not color-only) | 1.4.1 | Moderate |
| Dark mode contrast is verified | 1.4.3 | Moderate |
| Preheader text is meaningful | Best practice | Minor |
| Alt text styled for image-blocked view | Best practice | Minor |