| name | author-template |
| description | Framework-agnostic guide to authoring a new HTML email template from a brief. Use when the user describes an email they want ("welcome email", "newsletter", "transactional receipt") and wants help designing the structure regardless of chosen framework. |
Authoring an Email Template from a Brief
This skill is framework-neutral. Once the structure is agreed, hand off to the matching framework skill (foundation-emails, maizzle, or mjml) for syntax.
1. Clarify the brief
Ask (if not already known):
- Type: transactional (receipt, verification, password reset), marketing (newsletter, promo), lifecycle (welcome, onboarding, re-engagement)?
- Primary action: what should the recipient do? One primary CTA is ideal.
- Sender identity: brand, from-name, from-address.
- Content blocks: what sections — hero, body, feature grid, testimonial, CTA, footer?
- Length: short (one screen) or long-form?
- Existing brand assets: logo URL, palette, typography, tone?
2. Structure first, syntax later
Sketch the block structure in plain language before writing any markup:
[Preheader: "Your order #1234 has shipped"]
[Header: logo, centered]
[Hero: "Your order is on its way"]
[Body: order details table]
[CTA: Track package → button]
[Secondary: "Need help? Reply to this email"]
[Footer: company address, unsubscribe, social links]
Having the block list up front makes the framework syntax trivial.
3. Email anatomy reference
Preheader (hidden, 80–90 chars)
First thing to write. Without it, clients show "View in browser" — wasted.
Header
Logo, usually centered, max ~160px wide. Some marketing emails skip the logo for a text-only header.
Hero
The attention-grab. Options:
- Image + headline overlay (use framework's hero/VML-compatible pattern)
- Text-only large heading
- Image above headline
Body
Short paragraphs, generous line-height (1.5+), 16px minimum font size. Break up with subheads.
CTA
One primary CTA. Use a real button (framework-generated, not a styled link). Action verb: "Get started", "Track order", "Confirm email".
Secondary content
Optional. Related links, "other things you might like", social proof.
Footer
- Unsubscribe link (required for marketing)
- Physical address (CAN-SPAM requirement in US)
- Social icons (optional)
- "Why am I getting this?" (increases trust)
4. Copy principles
- Subject line: 30–50 chars. Front-load the value.
- Preheader: complement the subject, don't repeat it.
- Headline: 1 line if possible. Lead with benefit.
- Body: scannable. Short paragraphs. Bold key terms sparingly.
- CTA: specific verb + object. "Download the report" beats "Click here".
- Tone: matches sender. Transactional = clear/neutral. Marketing = branded/warm.
5. Design principles
- 600px max width. Don't fight it.
- One CTA primary, others secondary or absent.
- Single-column on mobile — default behavior of all frameworks.
- Plenty of whitespace — emails feel cramped easily.
- Images with text fallbacks — if images don't load, layout should still make sense.
- Consistent vertical rhythm — use framework spacers, not ad-hoc margins.
6. Common template patterns
Transactional receipt
Preheader → Logo → "Thanks for your order" → Order summary table → Shipping info → CTA (track) → Footer.
Welcome email
Preheader → Logo → "Welcome, {firstName}" → 1-paragraph intro → 3 steps/features list → CTA (get started) → Footer.
Newsletter
Preheader → Logo → Hero headline → 3–5 story blocks (image + headline + blurb + "read more") → Footer.
Password reset
Preheader → Logo → "Reset your password" heading → 1-paragraph instruction → CTA (reset button) → "Didn't request this? Ignore." → Footer.
Promotional
Preheader → Logo → Hero (offer + image) → 1-paragraph value prop → CTA → Fine print → Footer.
7. Hand off
Once the structure and copy are agreed:
- Foundation user →
foundation-emails skill
- Maizzle user →
maizzle skill
- MJML user →
mjml skill
- Undecided →
choose-framework skill first
Always cross-reference email-client-gotchas before shipping.
