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; or Georgia, 'Times New Roman', serif;. Web fonts via @import work in Apple Mail, iOS Mail, and some Android clients only
- Images: always set explicit
width, height:auto, display:block, border:0, and meaningful alt text
- Backgrounds: use inline
background-color; background images require VML fallback for Outlook — see references/client-compatibility.md
- Spacing: use
padding on <td> cells, never margin on 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
lang attribute on <html>
- Add
role="presentation" to all layout tables
- Provide descriptive
alt text 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 dark meta 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
1---2name: email-template-design3description: Design and build professional HTML email templates with inline CSS for broad email client compatibility. Use this skill when the user asks to create, design, or build email templates, newsletters, transactional emails (order confirmations, receipts, shipping notifications, password resets), marketing emails, welcome series, onboarding emails, abandoned cart emails, drip campaigns, or any HTML email layout. Covers responsive design, dark mode support, and compatibility with Gmail, Outlook (desktop + web), Apple Mail, Yahoo, and mobile clients.4---5
6# Email Template Design
7
8Design production-ready HTML email templates using table-based layouts and inline CSS for maximum email client compatibility.
9
10## Workflow
11
121. **Clarify purpose** - Determine the email type (marketing, transactional, lifecycle) and brand context
132. **Select base template** - Start from an asset template in `assets/` or build from scratch using the patterns below
143. **Build structure** - Use table-based layout with the boilerplate from `assets/base.html`
154. **Style inline** - Apply all CSS as inline styles; use `<style>` block only as progressive enhancement
165. **Test compatibility** - Review against the client quirks in `references/client-compatibility.md`
176. **Optimize** - Compress images, add alt text, verify dark mode, ensure accessibility
18
19## Email Type Selection
20
21| Type | Key characteristics | Template asset |
22|------|-------------------|----------------|
23| Marketing / Newsletter | Hero image, CTA buttons, multi-section content | `assets/marketing.html` |
24| Transactional | Data-driven, minimal design, clear information hierarchy | `assets/transactional.html` |
25| Lifecycle / Drip | Personal tone, single CTA, storytelling flow | `assets/lifecycle.html` |
26
27## Core Architecture
28
29Every email template follows this skeleton:
30
31```html
32<!DOCTYPE html>
33<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">
34<head>
35 <meta charset="utf-8">
36 <meta name="viewport" content="width=device-width, initial-scale=1">
37 <meta http-equiv="X-UA-Compatible" content="IE=edge">
38 <meta name="x-apple-disable-message-reformatting">
39 <meta name="format-detection" content="telephone=no,address=no,email=no,date=no,url=no">
40 <title>{{email_title}}</title>
41 <!--[if mso]>
42 <noscript><xml>
43 <o:OfficeDocumentSettings>
44 <o:AllowPNG/>
45 <o:PixelPerInch>96</o:PixelPerInch>
46 </o:OfficeDocumentSettings>
47 </xml></noscript>
48 <![endif]-->
49 <style>
50 /* Reset — progressive enhancement only */
51 table, td { mso-table-lspace:0pt; mso-table-rspace:0pt; }
52 img { -ms-interpolation-mode:bicubic; border:0; height:auto; line-height:100%; outline:none; text-decoration:none; }
53 body { margin:0; padding:0; width:100%!important; -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
54
55 /* Dark mode */
56 @media (prefers-color-scheme: dark) {
57 .dark-bg { background-color: #1a1a2e !important; }
58 .dark-text { color: #e0e0e0 !important; }
59 }
60
61 /* Responsive */
62 @media only screen and (max-width: 600px) {
63 .stack-column { display: block !important; width: 100% !important; max-width: 100% !important; }
64 .mobile-padding { padding-left: 16px !important; padding-right: 16px !important; }
65 .mobile-full-width { width: 100% !important; }
66 .mobile-hide { display: none !important; }
67 .mobile-center { text-align: center !important; }
68 }
69 </style>
70</head>
71<body style="margin:0; padding:0; background-color:#f4f4f4;">
72 <!-- Preview text (hidden preheader) -->
73 <div style="display:none; max-height:0; overflow:hidden;">
74 {{preview_text}}͏‌ ͏‌ ͏‌
75 </div>
76
77 <!-- Outer wrapper -->
78 <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background-color:#f4f4f4;">
79 <tr>
80 <td align="center" style="padding: 20px 0;">
81 <!-- Inner container (600px max) -->
82 <table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" class="mobile-full-width" style="background-color:#ffffff; border-radius:8px; overflow:hidden;">
83 <!-- CONTENT ROWS GO HERE -->
84 </table>
85 </td>
86 </tr>
87 </table>
88</body>
89</html>
90```
91
92## Essential Patterns
93
94### CTA Buttons (Outlook-safe)
95
96```html
97<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:0 auto;">
98 <tr>
99 <td align="center" style="border-radius:6px; background-color:#2563eb;">
100 <!--[if mso]>
101 <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">
102 <v:fill type="tile" color="#2563eb"/>
103 <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>
104 </v:roundrect>
105 <![endif]-->
106 <!--[if !mso]><!-->
107 <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>
108 <!--<![endif]-->
109 </td>
110 </tr>
111</table>
112```
113
114### Two-Column Layout (responsive)
115
116```html
117<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
118 <tr>
119 <td style="padding: 20px;">
120 <!--[if mso]><table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"><tr><td width="280" valign="top"><![endif]-->
121 <div class="stack-column" style="display:inline-block; width:280px; vertical-align:top;">
122 <!-- Left column content -->
123 </div>
124 <!--[if mso]></td><td width="20"></td><td width="280" valign="top"><![endif]-->
125 <div class="stack-column" style="display:inline-block; width:280px; vertical-align:top;">
126 <!-- Right column content -->
127 </div>
128 <!--[if mso]></td></tr></table><![endif]-->
129 </td>
130 </tr>
131</table>
132```
133
134### Hero Image
135
136```html
137<tr>
138 <td style="padding:0; line-height:0;">
139 <img src="{{hero_image_url}}" alt="{{hero_alt}}" width="600" style="display:block; width:100%; max-width:600px; height:auto;" class="mobile-full-width">
140 </td>
141</tr>
142```
143
144## Design Rules
145
1461. **600px max width** for the content container
1472. **All critical styles inline** — `<style>` blocks are for progressive enhancement only (resets, dark mode, responsive)
1483. **Tables for layout** — use `role="presentation"` on every layout table
1494. **System-safe font stacks** — `font-family: Arial, Helvetica, sans-serif;` or `Georgia, 'Times New Roman', serif;`. Web fonts via `@import` work in Apple Mail, iOS Mail, and some Android clients only
1505. **Images**: always set explicit `width`, `height:auto`, `display:block`, `border:0`, and meaningful `alt` text
1516. **Backgrounds**: use inline `background-color`; background images require VML fallback for Outlook — see `references/client-compatibility.md`
1527. **Spacing**: use `padding` on `<td>` cells, never `margin` on tables
1538. **Links**: always use absolute URLs with `https://`
1549. **Preheader text**: hidden preview text improves open rates; pad with `͏‌ ` to prevent email clients from pulling body content
155
156## Accessibility
157
158- Use semantic `lang` attribute on `<html>`
159- Add `role="presentation"` to all layout tables
160- Provide descriptive `alt` text for all images
161- Maintain minimum **4.5:1** contrast ratio for text
162- Use at least **14px** font size for body text
163- Structure content in logical reading order (not reliant on visual layout)
164- Include a plain-text version or web-view link
165
166## Dark Mode
167
168Support three strategies (apply all):
1691. **`@media (prefers-color-scheme: dark)`** in `<style>` — works in Apple Mail, Outlook.com
1702. **`color-scheme: light dark`** meta tag and CSS property — opts into native dark mode handling
1713. **Transparent images** — use PNGs with transparency so logos adapt to dark backgrounds; provide light/dark logo variants when possible
172
173For full dark mode quirks per client, see `references/client-compatibility.md`.
174
175## Pre-Send Checklist
176
177- [ ] All CSS is inline (use a CSS inliner tool if needed)
178- [ ] Preview text is set and padded
179- [ ] All images have `alt`, `width`, `display:block`
180- [ ] CTA buttons use VML fallback for Outlook
181- [ ] Links are absolute `https://` URLs
182- [ ] Responsive breakpoint at 600px tested
183- [ ] Dark mode classes applied to key elements
184- [ ] Unsubscribe link present (required for marketing emails by CAN-SPAM / GDPR)
185- [ ] Plain-text fallback available
186- [ ] Total email size under 102KB (Gmail clipping threshold)
majiayu000