Community-Access 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:
| Feature | Gmail | Outlook (Win) | Apple Mail | Yahoo | Outlook.com |
|---|---|---|---|---|---|
Semantic HTML (<nav>, <main>) |
Stripped | Stripped | Supported | Stripped | Stripped |
role attributes |
Stripped | Stripped | Supported | Stripped | Stripped |
aria-* attributes |
Stripped | Stripped | Supported | Stripped | Stripped |
<style> blocks |
Supported | Supported | 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 |
Rendered | Rendered | Rendered | Rendered | Rendered |
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
| 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 |