Email Template Design
Design production-ready HTML email templates using table-based layouts and inline CSS for maximum email client compatibility.
Workflow
- Clarify purpose - Determine the email type (marketing, transactional, lifecycle) and brand context
- Select base template - Start from an asset template in
assets/or build from scratch using the patterns below - Build structure - Use table-based layout with the boilerplate from
assets/base.html - Style inline - Apply all CSS as inline styles; use
<style>block only as progressive enhancement - Test compatibility - Review against the client quirks in
references/client-compatibility.md - Optimize - Compress images, add alt text, verify dark mode, ensure accessibility
Email Type Selection
| Type | Key characteristics | Template asset |
|---|---|---|
| Marketing / Newsletter | Hero image, CTA buttons, multi-section content | assets/marketing.html |
| Transactional | Data-driven, minimal design, clear information hierarchy | assets/transactional.html |
| Lifecycle / Drip | Personal tone, single CTA, storytelling flow | assets/lifecycle.html |
Core Architecture
Every email template follows this skeleton:
<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="x-apple-disable-message-reformatting">
<meta name="format-detection" content="telephone=no,address=no,email=no,date=no,url=no">
<title>{{email_title}}</title>
<!--[if mso]>
<noscript><xml>
<o:OfficeDocumentSettings>
<o:AllowPNG/>
<o:PixelPerInch>96</o:PixelPerInch>
</o:OfficeDocumentSettings>
</xml></noscript>
<![endif]-->
<style>
/* Reset — progressive enhancement only */
table, td { mso-table-lspace:0pt; mso-table-rspace:0pt; }
img { -ms-interpolation-mode:bicubic; border:0; height:auto; line-height:100%; outline:none; text-decoration:none; }
body { margin:0; padding:0; width:100%!important; -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
/* Dark mode */
@media (prefers-color-scheme: dark) {
.dark-bg { background-color: #1a1a2e !important; }
.dark-text { color: #e0e0e0 !important; }
}
/* Responsive */
@media only screen and (max-width: 600px) {
.stack-column { display: block !important; width: 100% !important; max-width: 100% !important; }
.mobile-padding { padding-left: 16px !important; padding-right: 16px !important; }
.mobile-full-width { width: 100% !important; }
.mobile-hide { display: none !important; }
.mobile-center { text-align: center !important; }
}
</style>
</head>
<body style="margin:0; padding:0; background-color:#f4f4f4;">
<!-- Preview text (hidden preheader) -->
<div style="display:none; max-height:0; overflow:hidden;">
{{preview_text}}͏‌ ͏‌ ͏‌
</div>
<!-- Outer wrapper -->
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background-color:#f4f4f4;">
<tr>
<td align="center" style="padding: 20px 0;">
<!-- Inner container (600px max) -->
<table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" class="mobile-full-width" style="background-color:#ffffff; border-radius:8px; overflow:hidden;">
<!-- CONTENT ROWS GO HERE -->
</table>
</td>
</tr>
</table>
</body>
</html>Essential Patterns
CTA Buttons (Outlook-safe)
<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:0 auto;">
<tr>
<td align="center" style="border-radius:6px; background-color:#2563eb;">
<!--[if mso]>
<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" href="{{url}}" style="height:44px; width:200px; v-text-anchor:middle;" arcsize="14%" fill="true" stroke="false">
<v:fill type="tile" color="#2563eb"/>
<v:textbox inset="0,0,0,0"><center style="color:#ffffff; font-family:Arial,sans-serif; font-size:16px; font-weight:bold;">Button Text</center></v:textbox>
</v:roundrect>
<![endif]-->
<!--[if !mso]><!-->
<a href="{{url}}" style="display:inline-block; padding:12px 32px; font-family:Arial,Helvetica,sans-serif; font-size:16px; font-weight:bold; color:#ffffff; text-decoration:none; border-radius:6px; background-color:#2563eb;">Button Text</a>
<!--<![endif]-->
</td>
</tr>
</table>Two-Column Layout (responsive)
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr>
<td style="padding: 20px;">
<!--[if mso]><table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"><tr><td width="280" valign="top"><![endif]-->
<div class="stack-column" style="display:inline-block; width:280px; vertical-align:top;">
<!-- Left column content -->
</div>
<!--[if mso]></td><td width="20"></td><td width="280" valign="top"><![endif]-->
<div class="stack-column" style="display:inline-block; width:280px; vertical-align:top;">
<!-- Right column content -->
</div>
<!--[if mso]></td></tr></table><![endif]-->
</td>
</tr>
</table>Hero Image
<tr>
<td style="padding:0; line-height:0;">
<img src="{{hero_image_url}}" alt="{{hero_alt}}" width="600" style="display:block; width:100%; max-width:600px; height:auto;" class="mobile-full-width">
</td>
</tr>Design Rules
- 600px max width for the content container
- All critical styles inline —
<style>blocks are for progressive enhancement only (resets, dark mode, responsive) - Tables for layout — use
role="presentation"on every layout table - System-safe font stacks —
font-family: Arial, Helvetica, sans-serif;orGeorgia, 'Times New Roman', serif;. Web fonts via@importwork in Apple Mail, iOS Mail, and some Android clients only - Images: always set explicit
width,height:auto,display:block,border:0, and meaningfulalttext - Backgrounds: use inline
background-color; background images require VML fallback for Outlook — seereferences/client-compatibility.md - Spacing: use
paddingon<td>cells, nevermarginon tables - Links: always use absolute URLs with
https:// - Preheader text: hidden preview text improves open rates; pad with
͏‌to prevent email clients from pulling body content
Accessibility
- Use semantic
langattribute on<html> - Add
role="presentation"to all layout tables - Provide descriptive
alttext for all images - Maintain minimum 4.5:1 contrast ratio for text
- Use at least 14px font size for body text
- Structure content in logical reading order (not reliant on visual layout)
- Include a plain-text version or web-view link
Dark Mode
Support three strategies (apply all):
@media (prefers-color-scheme: dark)in<style>— works in Apple Mail, Outlook.comcolor-scheme: light darkmeta tag and CSS property — opts into native dark mode handling- Transparent images — use PNGs with transparency so logos adapt to dark backgrounds; provide light/dark logo variants when possible
For full dark mode quirks per client, see references/client-compatibility.md.
Pre-Send Checklist
- All CSS is inline (use a CSS inliner tool if needed)
- Preview text is set and padded
- All images have
alt,width,display:block - CTA buttons use VML fallback for Outlook
- Links are absolute
https://URLs - Responsive breakpoint at 600px tested
- Dark mode classes applied to key elements
- Unsubscribe link present (required for marketing emails by CAN-SPAM / GDPR)
- Plain-text fallback available
- Total email size under 102KB (Gmail clipping threshold)