# Email Design > HTML email template design with cross-client compatibility and responsive patterns. Trigger: user asks to "design an email", "build an email template", "create a newsletter", "HTML email", "email layout", "transactional email", "welcome email", "promotional email", or any email template work. - Skill: `arnavpuri/email-design` (Agent Skill) - Install (CLI): `npx skillmds@latest add arnavpuri/email-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/arnavpuri/email-design/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: arnavpuri (https://skillmd.com/u/arnavpuri) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/arnavpuri/email-design --- # Email Design ## Pre-Flight: Check Design Context Before generating email template code: 1. Use `get_design_context` to check for existing brand colors, logos, fonts, or email design systems. 2. If a Figma URL is provided, pull screenshots and metadata to match the design. 3. Determine: What type of email? (welcome, newsletter, promotional, transactional) What ESP? --- ## 1. Fundamental Constraints Email HTML is not web HTML. These constraints are non-negotiable: | Rule | Why | |------|-----| | **Table-based layout** | Outlook and older clients don't support flexbox/grid | | **Inline CSS** | Many clients strip `

``` --- ## 3. MSO Conditional Comments (Outlook) Outlook uses Word as its rendering engine. Use MSO conditionals for Outlook-specific fixes. ```html ``` Common MSO fixes: force `border-collapse: collapse` and explicit widths in `[if mso]` style blocks. For Outlook rounded buttons, use VML `` with `arcsize`, `fillcolor`, and `` for text, wrapped in `[if mso]` / `[if !mso]` conditionals with a standard `` fallback. --- ## 4. Responsive Email (Fluid Hybrid Method) The fluid hybrid approach works without media queries in clients that don't support them. ### Two-Column Layout ```html

Column 1

Content for the first column.

Column 2

Content for the second column.

``` --- ## 5. Email Typography ### Web-Safe Font Stacks ```css /* Sans-serif (most common) */ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; /* Serif */ font-family: Georgia, 'Times New Roman', Times, serif; /* Monospace (for code) */ font-family: 'Courier New', Courier, monospace; ``` ### Web Font Loading (Limited Support) ```html ``` ### Typography Scale for Email | Element | Size | Weight | Line Height | |---------|------|--------|-------------| | H1 (hero) | 28–32px | 700 | 1.2 | | H2 (section) | 22–24px | 700 | 1.25 | | H3 (subsection) | 18–20px | 600 | 1.3 | | Body | 15–16px | 400 | 1.5 | | Small / Caption | 13px | 400 | 1.4 | ### Rules - Minimum body font size: 14px (some clients enforce this). - Use `px` not `rem` or `em` in emails. - Set `line-height` as a multiplier, not in px. - Always specify `color` inline on text elements. --- ## 6. Bulletproof Buttons Buttons that work in every email client, including Outlook. ### Method: Padding-Based (Best) ```html

Get Started Free

``` ### Button Rules - Minimum size: 44px tall, 150px+ wide. - Use `display: inline-block` with padding (not fixed width). - Add `target="_blank"` on all links. - Set both `background-color` on the `` AND the `` for Outlook. - `border-radius` on `` works in most clients but not Outlook. - For Outlook rounded buttons, use VML (see section 3). --- ## 7. Email Section Templates ### Header ```html

``` ### Hero Section ```html

Welcome to Our Platform

You're all set to start building amazing things.

``` ### Content Block ```html

What's inside

Here's what you can do to get started with your account.

``` ### Feature Row (Icon + Text) ```html

Quick Setup

Get up and running in less than 5 minutes.

``` ### Footer ```html

Company Name, 123 Street, City, State 12345
Unsubscribe | Manage preferences

``` --- ## 8. Dark Mode Email Considerations ### Meta Tags (Required) ```html ``` ### CSS Targeting ```css /* Apple Mail, iOS Mail */ @media (prefers-color-scheme: dark) { .email-bg { background-color: #1a1a2e !important; } .dark-bg { background-color: #16213e !important; } .dark-text { color: #e0e0e0 !important; } } /* Outlook.com */ [data-ogsc] .dark-bg { background-color: #16213e !important; } [data-ogsc] .dark-text { color: #e0e0e0 !important; } ``` ### Image Handling - Use transparent PNGs where possible (adapt to any background). - Add a white outline/glow to dark logos so they're visible on dark backgrounds. - Test with images blocked — alt text should convey the message. --- ## 9. Image Optimization ### Rules | Guideline | Value | |-----------|-------| | Max file size per image | 200KB | | Total email size | Under 100KB HTML + 800KB images | | Format | PNG for graphics, JPEG for photos | | Retina | Serve 2x, set `width` attribute to 1x | | Alt text | Always. Styled alt text as fallback. | ### Retina Images ```html Product showcase

``` ### Styled Alt Text ```html Spring Sale: 40% off everything

``` --- ## 10. Template Types ### Welcome Email - Hero with brand color background - Personalized greeting ("Hi {first_name}") - 3 quick-start steps with icons - Primary CTA: "Get started" or "Complete your profile" - Optional: onboarding video thumbnail ### Newsletter - Simple header with logo + date - Featured article with large image - 2-column article grid below - Short excerpts (2–3 lines) with "Read more" links - Footer with social links and unsubscribe ### Promotional - Bold hero with offer ("40% OFF") - Product grid (2 columns) - Each product: image, name, price, CTA - Urgency: "Ends Sunday" or countdown - Trust signals: free shipping, returns ### Transactional - Minimal design, clear information - Order confirmation: items, quantities, prices, total - Shipping update: tracking number, delivery date - Password reset: single CTA button, security note - No promotional content (improves deliverability) --- ## Email Design Checklist - [ ] Table-based layout (no flexbox/grid) - [ ] All critical styles are inline - [ ] Max width 600px - [ ] All images have alt text and width/height attributes - [ ] Bulletproof buttons (padding-based or VML) - [ ] MSO conditionals for Outlook - [ ] Responsive at 320px–600px (fluid hybrid) - [ ] Web-safe fonts with fallback stack - [ ] Preview text is set (hidden preheader) - [ ] Dark mode meta tags and CSS included - [ ] Images under 200KB each, total email under 100KB HTML - [ ] Unsubscribe link in footer - [ ] Tested in Litmus or Email on Acid across major clients - [ ] Links have `target="_blank"` - [ ] `role="presentation"` on all layout tables