email-html-mjml — Responsive Email Developer Generate valid, cross-client MJML 4.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 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. Plan layout — Decide and announce the structure before writing code (single-column, 2-col grid, hero + content, etc.) Load component references — Read the relevant file(s) from the Component Index below before writing any MJML Generate MJML — Write complete, valid MJML starting from with a full Compile — Follow compilation.md . Run npx mjml with --config.minify=true Deliver both files — Always output .mjml source AND compiled .html 9 Engineering Rules Structural Integrity — All visual content MUST be in inside . Sections cannot be nested. Responsive Defaults — Assume 600px width. Use to prevent mobile stacking for side-by-side elements (social bars, logo rows). Outlook Compatibility — Use for web fonts (prevents Times New Roman fallback). Always provide a fallback stack (Arial, sans-serif). For background images, always set both background-size and a fallback background-color . Gmail Optimization — Use inline="inline" on for custom CSS. Prefer component attributes ( color , font-size ) over CSS classes for critical styles. 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. Accessibility — Every MUST have alt . Always set (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). Styling Efficiency — Use with , component defaults, and to eliminate repetitive inline styles. Hero Sections — Use for full-bleed hero banners; it falls back to a regular section in unsupported clients. Avoid and — client support is too poor to be useful. Templating Support — Wrap dynamic tags (Handlebars/Liquid) in to protect them from the MJML parser. Critical Gotchas Outlook: Background images: VML only generated for and — 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: 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: Always compile with --config.minify=true — removes whitespace between inline-block columns Whitespace between tags causes stacking even inside 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

< mj-style inline = " inline "

.dark-logo { display: none !important; } </ mj-style

< 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 is set (screen reader email label + aria-label ) lang attribute on root tag alt on every and Heading role set via mj-html-attributes (NOT as a direct attribute on mj-text ):

< 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

< 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 blocks Component Index Before writing any MJML, read the component file(s) for the components you'll use. Group Components Load when File Head mj-attributes, mj-font, mj-style, mj-preview, mj-breakpoint, mj-html-attributes Setting up head, global styles components/head.md Layout mj-body, mj-section, mj-column, mj-group, mj-wrapper Building structure / grid components/layout.md Content mj-text, mj-image, mj-button, mj-divider, mj-spacer, mj-table Adding content blocks components/content.md Interactive mj-accordion, mj-carousel, mj-social, mj-navbar Interactive or social elements components/interactive.md Advanced mj-hero, mj-raw, mj-include Hero banners, template tags, partials components/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 assets/examples/basic-layout.mjml — MJML docs basic layout example. Covers 6-section structure: company header, image hero + button, intro text, 2-column image+text, 3-column icons, social row. Intentionally bare-bones (no mj-head , no dark mode, placeholder copy) — reflects the MJML docs style. Use as a structural reference for layout patterns only, not as a production template. Output Always deliver: .mjml — complete MJML source (editable, version-controllable) .html — compiled output (production-ready, send via ESP) Name files after the email type: welcome.mjml , promo-sale.mjml , order-confirmation.mjml