email-html-accessibility
Skill0 starsChanged 29 days agoMITView on GitHub
Use when designing or building an HTML email or newsletter, when a template must survive Gmail and Outlook, or when images are blocked by default and the message stops making sense.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- accessible-authenticationSkill
- accessible-formsSkill
- accessible-nameSkill
- accordion-disclosureSkill
- audit-componentSkill
- carouselSkill
- charts-and-datavizSkill
- combobox-autocompleteSkill
- data-tableSkill
- fix-color-contrastSkill
- forced-colors-and-dark-modeSkill
- headings-and-landmarksSkill
- keyboard-focusSkill
- live-regionsSkill
- media-captionsSkill
- menu-buttonSkill
- modal-dialogSkill
- motion-and-animationSkill
- page-title-and-languageSkill
- pagination-and-searchSkill
- pointer-and-gesturesSkill
- predictable-contextSkill
- progress-and-loadingSkill
- screen-reader-test-planSkill
- semantic-htmlSkill
- skip-linksSkill
- svg-and-iconsSkill
- tabsSkill
- tooltip-popoverSkill
- triage-automated-resultsSkill
- wcag22-new-criteriaSkill
- zoom-reflow-text-spacingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
Use real semantics where they survive: Prefer headings, paragraphs and lists to styled <div>s.
- Very specific: line 83
Keep one column and let the DOM order be the reading order: Avoid order or floats that reverse columns, and avoid absolutely positioned …
- Very specific: line 120
A layout table without
role="presentation": Every screen reader announces "table, 2 columns, 12 rows" around content that is not a table …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Email HTML accessibility
Criteria: SC 1.3.1 Info and Relationships, SC 1.4.3 Contrast (Minimum), SC 1.1.1 Non-text Content, SC 2.4.4 Link Purpose (In Context)
An HTML email is the least forgiving rendering environment there is: no reliable JavaScript, CSS that gets stripped, layout forced through tables, and images blocked until the recipient opts in. Design for images-off and CSS-light first, because that is the state many people actually read. The failure that survives every preview is a layout table announced as a data table around the whole message.
When to use
- Building an HTML email, newsletter, or transactional message.
- "It looks fine in the preview but breaks in Outlook."
- "Images are blocked by default — what does the reader get?"
- Reviewing an email template for real clients rather than a browser.
Procedure
- Design for images-off. Many clients block images until the user allows them, and the alt text is all that shows. Write alt text that reads as content, and style it (colour, font size) so it is legible if it appears.
Use real semantics where they survive. Prefer headings, paragraphs and lists to styled
<div>s. Wrap layout tables inrole="presentation"so they are not announced as data tables. Keep genuine data tables as tables, with<th scope>and a<caption>(SC 1.3.1).<!-- Fails SC 1.3.1 — a layout table announced as "table, 1 column, 12 rows" around the whole email — and SC 1.1.1 — a text image with no alt, inside a link with no name --> <table width="600"> <tr><td> <img src="logo.png"> <a href="https://example.com/sale"><img src="sale-banner.png"></a> </td></tr> </table> <p style="color:#999999;background-color:#ffffff"> <a href="https://example.com/sale">Click here</a> for the sale. </p><!-- Passes SC 1.3.1 — the layout table is presentational — and SC 1.1.1 — every image has alt, and a decorative rule would use alt="" --> <table role="presentation" width="600" cellpadding="0" cellspacing="0"> <tr><td> <img src="logo.png" width="120" height="32" alt="Example Co."> <h1 style="color:#1f2933;font-size:24px">Autumn sale</h1> </td></tr> </table> <p style="color:#595959;background-color:#ffffff"> <a href="https://example.com/sale" style="color:#1a4fd6">Shop the autumn sale</a> </p>- Set text and background together, and check the ratio (SC 1.4.3). Body
text needs 4.5:1; large text — at least 24px, or at least 18.66px bold —
needs 3:1.
#999999on#ffffffis about 2.85:1 and fails;#595959on#ffffffis about 7:1 and passes. Always writecolorandbackground-colorin the same rule, because clients that strip one leave you with invisible text. - Expect dark mode. Some clients recolour or invert your palette. Set
color-schemeso the client knows the message can adapt, and test in a client's dark theme rather than assuming your light-mode ratios hold. - Write link text that means something on its own (SC 2.4.4). "Click here" and "Read more" tell a screen reader user nothing, and a user tabbing through links hears only the link text. Name the destination.
- Build buttons from a real link, not an image. A background colour with a
solid fallback border survives CSS stripping; an image of a button disappears
when images are blocked and is an image of text. Make sure the link is a
single
<a>and that any image inside it has alt. - Keep one column and let the DOM order be the reading order. Avoid
orderor floats that reverse columns, and avoid absolutely positioned blocks that move around the reading order when a screen reader walks the source. - Test in real clients, not just a browser. Save the rendered HTML or the
.emland open it, then run the checks in Verify.
Verify
| Do this | Passing looks like | Criterion |
| Load with images blocked | the message is still understandable from alt text | 1.1.1 |
| Turn CSS off and read the source order | it reads top-to-bottom in a sensible order | 1.3.1 |
| Read with a screen reader | headings and lists are announced; the layout table is not | 1.3.1 |
| List the links on their own | each says where it goes | 2.4.4 |
| Measure text and links against the real background, light and dark | at least 4.5:1 body, at least 3:1 large | 1.4.3 |
// Assert the two things that break most often in email: alt text and link names.
for (const img of document.querySelectorAll('img')) {
if (img.getAttribute('alt') === null) console.error('image missing alt:', img.src);
}
for (const a of document.querySelectorAll('a')) {
const name = (a.textContent + (a.querySelector('img')?.alt ?? '')).trim();
if (!name) console.error('link has no accessible name:', a.href);
if (/^(click here|read more|more|shop)$/i.test(name)) console.warn('non-descriptive link:', name);
}
// A layout table must not be exposed as a data table.
for (const t of document.querySelectorAll('table')) {
if (!t.querySelector('th') && t.getAttribute('role') !== 'presentation') {
console.warn('table with no headers and no role="presentation"', t);
}
}Failure modes
- A layout table without
role="presentation". Every screen reader announces "table, 2 columns, 12 rows" around content that is not a table (SC 1.3.1). - Missing or junk alt text —
alt="image",alt="banner.png", or noaltat all. The browser or client may fall back to reading the filename (SC 1.1.1). - Text baked into images. With images blocked the message loses its headings and calls to action, and live text has been replaced by an image of text.
- Grey-on-white body text such as
#999999. It looks tasteful in the design tool and fails 4.5:1 (SC 1.4.3), often badly after a client's dark-mode inversion. - "Click here" links. They pass every visual review and fail SC 2.4.4 for anyone reading links out of context.
- White text over a background image, or a background colour that gets stripped. The text becomes invisible in the clients that strip backgrounds.
- Floats or absolute positioning that change reading order. The visual columns look right; the source is read in a different sequence.
- Overcorrection —
role="presentation"on a real data table, or deleting all images. It removes the headers from a genuine table, or strips legitimate imagery rather than writing alt text for it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

