/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. 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 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://e