/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