Agent skill

email-accessibility

HTML email accessibility reference. Email client rendering constraints, table-based layout patterns, accessible inline styles, MJML/Foundation/Maizzle framework patterns, dark mode adaptation, and image blocking fallbacks.

View SKILL.md on GitHub Repository
Stars 217
Forks 22

Install this agent skill to your Project

npx add-skill https://github.com/Community-Access/accessibility-agents/tree/main/.github/skills/email-accessibility

SKILL.md

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)

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

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

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

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

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

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

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

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

Community-Access/accessibility-agents

i18n-accessibility

Internationalization and RTL accessibility specialist. Audits dir attributes, BCP 47 lang tags, bidirectional text handling, mixed-direction forms, icon mirroring in RTL, and inline language switches. Ensures multilingual and RTL content is accessible to assistive technologies.

217 22
Explore
Community-Access/accessibility-agents

testing-coach

Accessibility testing coach for web applications. Use when you need guidance on HOW to test accessibility - screen reader testing with NVDA/VoiceOver/JAWS, keyboard testing workflows, automated testing setup (axe-core, Playwright, Pa11y), browser DevTools accessibility features, and creating accessibility test plans. Does not write product code - teaches and guides testing practices.

217 22
Explore
Community-Access/accessibility-agents

pdf-scan-config

Internal helper agent. Invoked by orchestrator agents via Task tool. PDF accessibility scan configuration manager. Use to create, edit, validate, or explain .a11y-pdf-config.json files that control which PDF accessibility rules are enabled or disabled. Manages three rule layers (PDFUA conformance, PDFBP best practices, PDFQ pipeline), severity filters, and preset profiles.

217 22
Explore
Community-Access/accessibility-agents

aria-specialist

ARIA implementation specialist for web applications. Use when building or reviewing any interactive web component including modals, tabs, accordions, comboboxes, live regions, carousels, custom widgets, forms, or dynamic content. Also use when reviewing ARIA usage for correctness. Applies to any web framework or vanilla HTML/CSS/JS.

217 22
Explore
Community-Access/accessibility-agents

Desktop A11y Testing Coach

Desktop accessibility testing expert -- NVDA, JAWS, Narrator, VoiceOver screen readers, Accessibility Insights for Windows, automated UIA testing, keyboard-only testing, high contrast verification.

217 22
Explore
Community-Access/accessibility-agents

lighthouse-bridge

Internal helper agent. Invoked by orchestrator agents via Task tool. Internal helper that bridges Lighthouse CI accessibility audit data with the agent ecosystem. Parses Lighthouse reports, normalizes accessibility findings, tracks score regressions, and deduplicates against local scans.

217 22
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results