agentleFS
framix-teamframix-team/skill-email-html-mjml/email-html-mjml/SKILL.md

email-html-mjml

Skill67 starsChanged 3 months agoMITView on GitHub

Responsive HTML email template generation using MJML 5.x framework. Use when the user asks to create, generate, design, or build an email template — including welcome emails, promotional blasts, transactional templates, newsletters, or any responsive email. Also use when the user asks to compile MJML to HTML, work with or edit existing MJML templates or `.mjml` files, or troubleshoot email rendering issues across clients.

  • Installs packages

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. podo/design-agent-skills★ 32same name
    2. jasonfesta/design-agents★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If a compiled template is missing content you expected from an include, check for this first

    line 51
  2. Very specific:

    Always pair background-repeat="no-repeat" with explicit background-size

    line 56
  3. Distinctive:

    Use component attributes for critical layout — CSS classes may be stripped

    line 60
  4. Very specific:

    If any column in a section sets vertical-align, ALL columns in that section must explicitly set it

    line 69
  5. Very specific:

    No text baked into images — always use live <mj-text> blocks

    line 122
  6. Distinctive:

    Before writing any MJML, read the component file(s) for the components you'll use.

    line 128
  7. Very specific:

    Read compilation.md for the full workflow.

    line 144
  8. Very specific:

    Always use npx or ./node_modules/.bin/mjml

    line 152
  9. Very specific:

    If mjml not in package.json, suggest npm install -D mjml

    line 153
  10. Very specific:

    All four compile clean under --config.validationLevel=strict --config.minify=true on MJML 5.4.0.

    line 159
  11. Distinctive:

    All copy, image URLs, and brands in these files are placeholders — replace them.

    line 168

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

email-html-mjml — Responsive Email Developer

Generate valid, cross-client MJML 5.x templates and compile them to production-ready HTML. The primary goal is compatibility: Outlook (2013–365), Gmail (web/app), Apple Mail, and major mobile clients. Every output must be compilable with --config.validationLevel=strict and survive Gmail's 102KB clip limit.


Workflow

  1. Gather requirements — Infer email type, brand colors, and content from the user's message and conversation context. Ask only for what is genuinely missing and blocking progress (e.g., no colors provided and the layout has branded sections). Never front-load a questionnaire.
  2. Plan layout — Decide and announce the structure before writing code (single-column, 2-col grid, hero + content, etc.)
  3. Load component references — Read the relevant file(s) from the Component Index below before writing any MJML
  4. Generate MJML — Write complete, valid MJML starting from <mjml> with a full <mj-head>
  5. Compile — Follow compilation.md. Run npx mjml with --config.minify=true
  6. Deliver both files — Always output .mjml source AND compiled .html

9 Engineering Rules

  1. Structural Integrity — All visual content MUST be in <mj-column> inside <mj-section>. Sections cannot be nested.
  2. Responsive Defaults — Assume 600px width. Use <mj-group> to prevent mobile stacking for side-by-side elements (social bars, logo rows). Use <mj-section gutter="..."> for equal spacing between columns instead of padding tricks.
  3. Outlook Compatibility — Use <mj-font> for web fonts (prevents Times New Roman fallback). Always provide a fallback stack (Arial, sans-serif). For <mj-section> background images, always set both background-size and a fallback background-color.
  4. Gmail Optimization — Use inline="inline" on <mj-style> for custom CSS. Prefer component attributes (color, font-size) over CSS classes for critical styles.
  5. Dark Mode — Include dark mode support when explicitly requested or when the email has a light background that would cause harsh forced-inversion. See the Dark Mode Pattern below.
  6. Accessibility — Every <mj-image> MUST have alt. Always set <mj-title> (populates aria-label). Maintain WCAG 2.1 AA 4.5:1 contrast. For heading roles, use mj-html-attributes — direct role/aria-level attributes on mj-text are illegal under strict validation (see Accessibility Checklist below).
  7. Styling Efficiency — Use <mj-attributes> with <mj-all>, component defaults, and <mj-class> to eliminate repetitive inline styles.
  8. Hero Sections — Use <mj-hero> for full-bleed hero banners; it falls back to a regular section in unsupported clients. Avoid <mj-accordion> and <mj-carousel> — client support is too poor to be useful.
  9. Templating Support — Plain interpolations ({{firstName}}) need no wrapping — they pass through text, attributes, mj-title and mj-preview untouched. Only block tags containing < or > ({% if x < 5 %}, {{#if a<b}}) need <!-- htmlmin:ignore --> protection, or minify silently corrupts them. An <mj-raw> between content components inside a column emits its content between </tr> and <tr> — invalid markup; put mj-raw between sections, and keep templating tags out of <mj-style> (see compilation.md).

Critical Gotchas

MJML 5 mj-include is disabled by default:

  • <mj-include> tags are silently ignored unless includes are explicitly enabled — a deliberate security change from MJML 4
  • CLI: add --config.allowIncludes true. Node API: pass ignoreIncludes: false
  • Scope allowed directories with --config.includePath (CLI) or includePath (Node) — only MJML, HTML, and CSS includes are supported
  • A partial outside the template's own directory is denied unless its directory is allowlisted
  • --config.validationLevel=strict does not catch this — a dropped include still exits 0 and still writes the .html. A clean compile is NOT proof the include landed; grep the output for known partial content before delivering
  • If a compiled template is missing content you expected from an include, check for this first

Outlook:

  • Background images: VML only generated for <mj-section> and <mj-hero> — nowhere else
  • Background positioning: keyword values only (top, center, bottom) — pixel values ignored
  • Always pair background-repeat="no-repeat" with explicit background-size
  • Font fallback: <mj-font> hides @font-face from Outlook via MSO conditional comments

Gmail:

  • Use component attributes for critical layout — CSS classes may be stripped
  • 102KB clip: always compile with --config.minify=true

iOS / Android stacking:

  • MJML 5's minify no longer strips whitespace between tags — htmlnano collapses runs to a single space where html-minifier removed them (verified: v4 emits <![endif]--><div class="mj-column-per-50", v5 emits <![endif]--> <div ...). The anti-stacking defence that still works is the font-size:0px MJML puts on the parent <td>, which is emitted in both versions
  • To restore v4 whitespace stripping: --config.minifyOptions '{"collapseWhitespace":"all"}' (JSON string form required)
  • Whitespace between tags causes stacking even inside <mj-group>

Vertical-align bug:

  • If any column in a section sets vertical-align, ALL columns in that section must explicitly set it

JavaScript:

  • JS is completely blocked in all email clients (Gmail, Outlook, Apple Mail, iOS Mail). No onclick, no clipboard API, no interactivity of any kind. Interactive-looking elements (copy buttons, toggles) are purely decorative.

Dark Mode Pattern

<mj-head>
  <mj-raw>
    <meta name="color-scheme" content="light dark">
    <meta name="supported-color-schemes" content="light dark">
  </mj-raw>

  <!-- Light logo visible by default; dark logo hidden -->
  <mj-style inline="inline">
    .dark-logo { display: none !important; }
  </mj-style>

  <!-- Dark mode overrides -->
  <mj-style>
    @media (prefers-color-scheme: dark) {
      .light-logo { display: none !important; }
      .dark-logo  { display: block !important; }
    }
  </mj-style>
</mj-head>

Safe neutrals: #121212 (not #000000) and #F1F1F1 (not #FFFFFF) — prevents jarring forced inversions.


Accessibility Checklist

  • <mj-title> is set (screen reader email label + aria-label)
  • lang attribute on root <mjml> tag
  • alt on every <mj-image> and <mj-social-element>
  • Heading role set via mj-html-attributes (NOT as a direct attribute on mj-text):
    <!-- In mj-head -->
    <mj-html-attributes>
      <mj-selector path=".email-heading div">
        <mj-html-attribute name="role">heading</mj-html-attribute>
        <mj-html-attribute name="aria-level">1</mj-html-attribute>
      </mj-selector>
    </mj-html-attributes>
    <!-- On the component -->
    <mj-text css-class="email-heading" ...>Heading text</mj-text>
  • 4.5:1 contrast ratio on all text/background pairs
  • No text baked into images — always use live <mj-text> blocks

Component Index

Before writing any MJML, read the component file(s) for the components you'll use.

GroupComponentsLoad whenFile
Headmj-attributes, mj-font, mj-style, mj-preview, mj-breakpoint, mj-html-attributesSetting up head, global stylescomponents/head.md
Layoutmj-body, mj-section, mj-column, mj-group, mj-wrapperBuilding structure / gridcomponents/layout.md
Contentmj-text, mj-image, mj-button, mj-divider, mj-spacer, mj-tableAdding content blockscomponents/content.md
Interactivemj-accordion, mj-carousel, mj-social, mj-navbarInteractive or social elementscomponents/interactive.md
Advancedmj-hero, mj-raw, mj-includeHero banners, template tags, partialscomponents/advanced.md

General reference (hierarchy, ending tags, validation, width math, Gmail clip): mjml-reference.md


Compilation

Read compilation.md for the full workflow. Key command:

npx mjml template.mjml -o dist/template.html --config.minify=true --config.validationLevel=strict

Hard rules:

  • Never npm install -g mjml
  • Always use npx or ./node_modules/.bin/mjml
  • If mjml not in package.json, suggest npm install -D mjml

Examples

All four compile clean under --config.validationLevel=strict --config.minify=true on MJML 5.4.0.

FileUse as a reference for
assets/examples/basic-layout.mjmlStructure only. MJML docs example: 6-section layout (header, image hero + button, intro, 2-col image+text, 3-col icons, social row). Intentionally bare-bones — no mj-head, no dark mode, placeholder copy. Not a production template.
assets/examples/order-confirmation.mjmlTransactional. Full mj-head (mj-attributes + mj-class + mj-font + mj-html-attributes), receipt mj-table with scope="col" headers, Handlebars in mj-raw with htmlmin:ignore, conditional block, and mj-include of partials/footer.mjml. Requires --config.allowIncludes true.
assets/examples/promo-sale.mjmlPromotional. mj-hero and mj-section background images (VML generated), mj-navbar, mj-group non-stacking row, mj-social, mj-breakpoint, plus the MJML 5 gutter / border / inner-padding attributes.
assets/examples/newsletter.mjmlEditorial + dark mode. The full dark-mode pattern from above, mj-wrapper, mj-html-attributes for aria-level 1 and 2, and vertical-align set on every column in each section.

All copy, image URLs, and brands in these files are placeholders — replace them; do not ship them as-is.


Output

Always deliver:

  1. <name>.mjml — complete MJML source (editable, version-controllable)
  2. <name>.html — compiled output (production-ready, send via ESP)

Name files after the email type: welcome.mjml, promo-sale.mjml, order-confirmation.mjml

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.