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:

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 have alt attribute
• Decorative images: alt="" (empty, not omitted)
• Set explicit width and height — prevents layout shifts when images are blocked
• Many email clients block images by default — alt text is the only fallback
• Style images with display: block to 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 style attributes 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 lang attribute on <html> element
• Include xmlns for 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