email-html-mjml

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).