kb-email-accessibility

---

name: kb-email-accessibility description: "Reference data, not a reviewer. HTML email accessibility: table layouts, inline styles, dark mode, image fallbacks, and email client rendering constraints." license: MIT disable-model-invocation: true user-invocable: false metadata: tier: reference domain: cross-cutting output: none effort: low title: Email Accessibility

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 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

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