Technology & EngineeringEmail Template279 lines

Email Accessibility

Accessible email design patterns for inclusive, standards-compliant email templates

Quick Summary29 lines

You are an expert in accessible email design for building inclusive email templates that work with assistive technology.

## Key Points

- Over 1 billion people worldwide live with some form of disability.
- Many corporate and government environments block images by default, making alt text essential.
- Screen readers like NVDA, JAWS, and VoiceOver are used to read emails daily.
- Accessibility regulations (ADA, EAA, AODA, Section 508) increasingly apply to digital communications.
- Declare `lang` on the `<html>` element. This is the single most impactful accessibility attribute for screen readers.
- Use `role="presentation"` on every layout table. Without it, screen readers announce "table with X rows and Y columns" for every structural wrapper.
- Write meaningful alt text that conveys the purpose of the image, not just its appearance. For a product photo: "Blue running shoes" is better than "image1.jpg" or "photo".
- Use actual text over images of text. Text in images cannot be resized, searched, or read by screen readers when images are blocked.
- Ensure a logical heading hierarchy (h1 then h2 then h3). Do not skip levels.
- Make links distinguishable by more than just color. Underline links or add an icon indicator.
- Use descriptive link text. "View your order" is better than "Click here".
- Maintain minimum 44x44px touch targets for buttons and links on mobile.

## Quick Example

```html
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
```

```html
<p lang="en">Thank you for your purchase.</p>
<p lang="fr">Merci pour votre achat.</p>
```

skilldb get email-template-skills/Email AccessibilityFull skill: 279 lines

Paste into your CLAUDE.md or agent config

Email Accessibility — Email Templates

You are an expert in accessible email design for building inclusive email templates that work with assistive technology.

Core Philosophy

Overview

Email accessibility ensures that all recipients, including those using screen readers, magnifiers, keyboard navigation, or who have cognitive or visual impairments, can read and interact with email content. Since email clients vary widely in their support for ARIA and semantic HTML, accessibility in email requires specific techniques that differ from web accessibility.

Core Concepts

Why Email Accessibility Matters

Over 1 billion people worldwide live with some form of disability.
Many corporate and government environments block images by default, making alt text essential.
Screen readers like NVDA, JAWS, and VoiceOver are used to read emails daily.
Accessibility regulations (ADA, EAA, AODA, Section 508) increasingly apply to digital communications.

Semantic Structure

Email HTML supports a limited subset of semantic elements. Use what is available:

<!-- Use headings for visual and structural hierarchy -->
<h1 style="font-size: 24px; font-weight: bold; margin: 0 0 16px;">Order Confirmation</h1>
<h2 style="font-size: 18px; font-weight: bold; margin: 0 0 12px;">Shipping Details</h2>

<!-- Use paragraph tags for body text -->
<p style="font-size: 16px; line-height: 24px; margin: 0 0 16px;">
  Your order has been shipped and is on the way.
</p>

<!-- Use lists for enumerations -->
<ul style="padding-left: 20px; margin: 0 0 16px;">
  <li style="font-size: 16px; line-height: 24px;">Item One</li>
  <li style="font-size: 16px; line-height: 24px;">Item Two</li>
</ul>

Language Declaration

Always declare the content language so screen readers use the correct pronunciation:

<html lang="en" xmlns="http://www.w3.org/1999/xhtml">

For multi-language emails, use lang attributes on specific elements:

<p lang="en">Thank you for your purchase.</p>
<p lang="fr">Merci pour votre achat.</p>

Role Attributes on Layout Tables

Layout tables must be hidden from screen readers:

<!-- Layout table — hidden from assistive tech -->
<table role="presentation" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td>Layout content</td>
  </tr>
</table>

<!-- Data table — announced as a table -->
<table role="table" cellpadding="8" cellspacing="0" border="1" style="border-collapse: collapse;">
  <caption style="font-weight: bold; text-align: left; padding-bottom: 8px;">
    Order Summary
  </caption>
  <thead>
    <tr>
      <th scope="col" style="text-align: left;">Item</th>
      <th scope="col" style="text-align: right;">Price</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left;">Widget</td>
      <td style="text-align: right;">$29.99</td>
    </tr>
  </tbody>
</table>

Implementation Patterns

Image Accessibility

<!-- Informative image: descriptive alt text -->
<img
  src="https://example.com/product.jpg"
  alt="Blue running shoes, side view"
  width="300"
  height="200"
  style="display: block; border: 0;"
/>

<!-- Decorative image: empty alt to skip in screen readers -->
<img
  src="https://example.com/divider.png"
  alt=""
  role="presentation"
  width="600"
  height="1"
  style="display: block; border: 0;"
/>

<!-- Logo with company name as alt -->
<img
  src="https://example.com/logo.png"
  alt="Acme Corp"
  width="150"
  height="40"
  style="display: block; border: 0;"
/>

<!-- When images are blocked, style the alt text -->
<img
  src="https://example.com/hero.jpg"
  alt="Summer Sale — 30% off all items"
  width="600"
  height="300"
  style="display: block; border: 0; font-size: 18px; font-weight: bold; color: #333333; background-color: #f0f0f0;"
/>

Accessible Links and Buttons

<!-- Descriptive link text — avoid "click here" -->
<a href="https://example.com/order/12345"
   style="color: #5469d4; text-decoration: underline;">
  View your order status
</a>

<!-- Button with sufficient contrast and size -->
<table role="presentation" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td style="border-radius: 4px; background-color: #5469d4;">
      <a href="https://example.com/activate"
         style="display: inline-block; padding: 14px 32px; color: #ffffff; font-size: 16px; font-weight: bold; text-decoration: none; border-radius: 4px;">
        Activate Your Account
      </a>
    </td>
  </tr>
</table>

Color Contrast

Ensure text meets WCAG 2.1 AA contrast ratios (4.5:1 for normal text, 3:1 for large text):

<!-- Good: #333333 on #ffffff = 12.63:1 ratio -->
<td style="color: #333333; background-color: #ffffff; font-size: 16px;">
  This text has excellent contrast.
</td>

<!-- Bad: #999999 on #ffffff = 2.85:1 ratio — fails AA -->
<!-- <td style="color: #999999; background-color: #ffffff;"> -->

<!-- Footer text: use at least #767676 on white for 4.54:1 -->
<td style="color: #767676; background-color: #ffffff; font-size: 14px;">
  Smaller text needs higher contrast.
</td>

Reading Order

The visual order must match the DOM order because screen readers follow the source:

<!-- Correct: heading before content in source -->
<table role="presentation" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td>
      <h2 style="margin: 0 0 8px;">Section Title</h2>
      <p style="margin: 0;">Section content follows the heading.</p>
    </td>
  </tr>
</table>

Hidden Preheader Text

Preheader text appears in inbox previews. Hide it visually but keep it accessible:

<div style="display: none; max-height: 0; overflow: hidden; mso-hide: all;">
  Your order has shipped! Track it now.
</div>
<!-- Padding to push invisible characters out of preview -->
<div style="display: none; max-height: 0; overflow: hidden; mso-hide: all;">
  &zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;
</div>

Accessible Data Tables

When displaying tabular data (invoices, order summaries, schedules):

<table role="table" cellpadding="8" cellspacing="0" border="0"
       style="border-collapse: collapse; width: 100%; max-width: 560px;">
  <caption style="font-size: 18px; font-weight: bold; text-align: left; padding-bottom: 12px;">
    Invoice #12345
  </caption>
  <thead>
    <tr style="background-color: #f4f4f4;">
      <th scope="col" style="text-align: left; font-size: 14px; padding: 8px; border-bottom: 2px solid #cccccc;">
        Description
      </th>
      <th scope="col" style="text-align: center; font-size: 14px; padding: 8px; border-bottom: 2px solid #cccccc;">
        Qty
      </th>
      <th scope="col" style="text-align: right; font-size: 14px; padding: 8px; border-bottom: 2px solid #cccccc;">
        Amount
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left; padding: 8px; border-bottom: 1px solid #eeeeee;">Pro Plan (annual)</td>
      <td style="text-align: center; padding: 8px; border-bottom: 1px solid #eeeeee;">1</td>
      <td style="text-align: right; padding: 8px; border-bottom: 1px solid #eeeeee;">$199.00</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <th scope="row" colspan="2" style="text-align: right; padding: 8px; font-weight: bold;">Total</th>
      <td style="text-align: right; padding: 8px; font-weight: bold;">$199.00</td>
    </tr>
  </tfoot>
</table>

Best Practices

Declare lang on the <html> element. This is the single most impactful accessibility attribute for screen readers.
Use role="presentation" on every layout table. Without it, screen readers announce "table with X rows and Y columns" for every structural wrapper.
Write meaningful alt text that conveys the purpose of the image, not just its appearance. For a product photo: "Blue running shoes" is better than "image1.jpg" or "photo".
Use actual text over images of text. Text in images cannot be resized, searched, or read by screen readers when images are blocked.
Ensure a logical heading hierarchy (h1 then h2 then h3). Do not skip levels.
Make links distinguishable by more than just color. Underline links or add an icon indicator.
Use descriptive link text. "View your order" is better than "Click here".
Maintain minimum 44x44px touch targets for buttons and links on mobile.
Provide a plain-text version of every email for clients or users that prefer it.
Keep line length under 80 characters for readability. Use max-width on text containers.

Common Pitfalls

Image-only emails: If the entire email is one large image, it becomes completely inaccessible when images are blocked and to screen reader users. Always use real HTML text for critical content.
Missing role="presentation": Forgetting this on layout tables is the most common email accessibility issue. Screen readers will announce nested table structures, creating a confusing experience.
Low-contrast text: Light gray text on white backgrounds is a frequent design choice that fails WCAG contrast requirements. Use a contrast checker tool.
"Click here" link text: Screen reader users often navigate by links. A list of "Click here" links is meaningless out of context. Use descriptive text.
Relying on color alone to convey meaning: "Fields marked in red are required" fails for colorblind users. Add text labels or icons.
Using display: none on content meant to be read: Content with display: none is hidden from screen readers too. If content should be visually hidden but readable, use clip/position techniques, but note email client support is limited.
Missing table headers: Data tables without <th> and scope attributes prevent screen readers from associating cells with their headers.

Anti-Patterns

Over-engineering for hypothetical scale. Building for millions of users when you have hundreds adds complexity without value. Solve today's problems first.

Ignoring the existing ecosystem. Reinventing functionality that mature libraries already provide well wastes time and introduces unnecessary risk.

Premature abstraction. Creating elaborate frameworks and utilities before you have enough concrete cases to know what the abstraction should look like produces the wrong abstraction.

Neglecting error handling at boundaries. Internal code can trust its inputs, but system boundaries (user input, APIs, file I/O) require defensive validation.

Skipping documentation for obvious code. What is obvious to you today will not be obvious to your colleague next month or to you next year.

Install this skill directly: skilldb add email-template-skills

Get CLI access →