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
- 参考文档agents/openai.yaml516 B
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 havealtattribute - Decorative images:
alt=""(empty, not omitted) - Set explicit
widthandheight— prevents layout shifts when images are blocked - Many email clients block images by default — alt text is the only fallback
- Style images with
display: blockto 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
styleattributes 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
langattribute on<html>element - Include
xmlnsfor 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
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.
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".
wireframe
Generate JSON wireframe with HTML preview
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.
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.
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.