AGENT SKILL

kb-email-accessibility

Reference data, not a reviewer. HTML email accessibility: table layouts, inline styles, dark mode, image fallbacks, and email client rendering constraints.

License 许可
MIT
最近更新
2026-11-06
Stars
★ 0
Forks
0

01 前言 Front Matter

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

02 资源文件 1

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

<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

04 同仓库更多 Skills

mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

frontend-slides

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

design-dna

Extract, define, and apply design DNA across three dimensions: design system (tokens), design style (qualitative feel), and visual effects (Canvas, WebGL, 3D, particles, shaders, scroll effects, etc.). Use this skill when: (1) a user wants to see the full 3-dimension design structure/schema, (2) a user provides images, screenshots, or URLs of reference designs and wants them analyzed into a structured JSON profile covering all three dimensions, (3) a user has a Design DNA JSON and content and wants a design generated from it, or (4) any combination of these phases. Triggers on "design DNA", "extract design style", "analyze design", "design tokens from reference", "generate design from JSON", "design system from screenshot", "design profile", "style guide JSON", "visual effects analysis", "design with effects", "3d design analysis".

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

wireframe

Generate JSON wireframe with HTML preview

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

social-publishing

Schedule and publish social media posts across 13 platforms (X, LinkedIn, Instagram, Facebook Pages, TikTok, Discord, Telegram, YouTube, Reddit, WordPress, Pinterest) via the SocialClaw API. Use when the user wants to publish, schedule, or manage social media content programmatically. Requires SOCIALCLAW_API_KEY.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

hermes-tweet

Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.

★ 0
mhyahya854
mhyahya854/AI-Second-Brain_Universal-Rules

refactoring-ui

Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.

★ 0