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 MJM

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 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 ): 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. 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: 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. File Use as a reference for assets/examples/basic layout.mjml Structure 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.mjml Transactional. 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.mjml Promotional. 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.mjml Editorial + 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

email-html-mjml