♿ MJML Accessibility Checker
A VSCode extension that checks your MJML email templates for accessibility issues in real time, based on WCAG guidelines and best practices for email accessibility.
Developed by Crafting.email® - the email specialists.
Web version available
Want to try before you install? The
MJML Accessibility Checker
is also available as a web tool, no setup needed.
ℹ️ The web version has limited checks compared to this extension. For the full experience, the VSCode plugin is the way to go.
Features
- Color contrast errors: detects insufficient contrast between text and background colors (WCAG AA: 4.5:1)
- Missing alt text: flags
<mj-image> tags without an alt attribute
- Ambiguous link text: warns about links like "click here", "read more", "learn more" (EN check only)
- Non-descriptive button labels: warns about
<mj-button> with generic text (EN check only)
- Missing
<mj-title>: reminder for assistive technology support
- Missing
<mj-preview>: reminder for screen reader context
Issues appear as inline squiggles directly in your .mjml files, just like regular linting.
Usage
- Open any
.mjml file
- Issues appear automatically as you type or on save
- Hover over squiggles to read the accessibility message
- Run "MJML Accessibility Checker: Check Now" from the Command Palette (
Cmd+Shift+P / Ctrl+Shift+P)
- Run "MJML Accessibility Checker: Show Full Report" for a side panel with all issues grouped by severity and a live accessibility score
Settings
| Setting |
Default |
Description |
mjmlAccessibility.checkOnSave |
true |
Run checks automatically when the file is saved |
mjmlAccessibility.checkOnType |
false |
Run checks while typing (may slow down editor on large files) |
mjmlAccessibility.contrastThreshold |
4.5 |
Minimum WCAG contrast ratio (4.5 for AA normal text, 3.0 for AA large text) |
Full Report Panel
Open the Full Report via "MJML Accessibility Checker: Show Full Report" to see:
- Live accessibility score (0–100) with a visual ring indicator
- Issues grouped by Errors, Warnings, and Info
- Exact line numbers for each issue
- Timestamp of the last check
- The report updates automatically as you edit your file
ℹ️ Ambiguous label checks (buttons and links) are evaluated in English only (EN).
Installation (from source)
git clone https://github.com/ricfreire/vscode-mjml-accessibility-checker
cd vscode-mjml-accessibility-checker
npm install
npm run compile
npx vsce package
code --install-extension mjml-accessibility-checker-1.0.0.vsix
ℹ️ If the code command is not available, install the extension via VSCode:
Extensions → ... → Install from VSIX
License
MIT License - see LICENSE for details.
Disclaimer & Limitations
This tool is a development aid designed to highlight common accessibility issues in MJML email templates. It does not guarantee full WCAG compliance or legal conformance.
Results are generated automatically and may include false positives, false negatives, or inaccuracies. Not all accessibility issues can be detected, and some limitations may not be explicitly listed.
A passing score does not ensure full accessibility. Manual testing, including screen reader validation and professional audits, is strongly recommended.
Ricardo Freire or Crafting.email® accepts no liability for any issues, damages, or legal claims resulting from the use of this tool.
Links
