aiwg
Version:
Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.
424 lines (323 loc) • 9.48 kB
Markdown
# Email Template Specification
**Card ID**: `EML-{PROJECT}-{NNNN}`
**Version**: 1.0
**Status**: Draft | In Development | QA | Production
**Template Name**: {TEMPLATE_NAME}
**Owner**: {OWNER_NAME}
## Template Overview
### Purpose
{What this template is designed for}
### Use Cases
- {Use case 1}
- {Use case 2}
- {Use case 3}
### Template Type
- [ ] Promotional
- [ ] Transactional
- [ ] Newsletter
- [ ] Nurture/Drip
- [ ] Automated/Triggered
- [ ] System notification
## Design Specifications
### Layout Structure
```
┌─────────────────────────────────┐
│ HEADER │
│ [Logo] [Nav Links] │
├─────────────────────────────────┤
│ HERO │
│ [Image/Video Placeholder] │
│ [Headline] │
│ [Subheadline] │
│ [Primary CTA] │
├─────────────────────────────────┤
│ BODY SECTION 1 │
│ [Content Block] │
├─────────────────────────────────┤
│ BODY SECTION 2 │
│ [2-3 Column Layout] │
├─────────────────────────────────┤
│ FOOTER │
│ [Social Icons] │
│ [Unsubscribe] [Preferences] │
│ [Address] [Legal] │
└─────────────────────────────────┘
```
### Dimensions
| Element | Desktop | Mobile |
|---------|---------|--------|
| Max width | 600px | 100% |
| Min width | 320px | 320px |
| Padding | 20px | 15px |
| Column gutter | 20px | 10px |
## Module Library
### Header Module
| Element | Specification |
|---------|---------------|
| Logo | Max 200px wide, linked to homepage |
| Logo alt text | "{Brand Name}" |
| Navigation | Optional, max 4 links |
| Background | {Color/#HEX} |
| Height | Auto, min 60px |
### Hero Module
| Element | Specification |
|---------|---------------|
| Image size | 600x300px (2:1 ratio) |
| Retina image | 1200x600px |
| Alt text | Required, descriptive |
| Headline | H1, max 60 characters |
| Subheadline | 100-150 characters |
| CTA button | Min 44x44px touch target |
### Content Block Modules
**Single column**:
| Element | Specification |
|---------|---------------|
| Width | 100% (max 560px with padding) |
| Image | 560px wide, auto height |
| Text | Left-aligned, 16px body |
**Two column**:
| Element | Specification |
|---------|---------------|
| Column width | 280px each (20px gutter) |
| Mobile behavior | Stack vertically |
| Image | 280px wide |
**Three column**:
| Element | Specification |
|---------|---------------|
| Column width | 180px each (20px gutters) |
| Mobile behavior | Stack or 2+1 |
| Image | 180px wide |
### Footer Module
| Element | Specification |
|---------|---------------|
| Social icons | 32x32px, max 6 icons |
| Unsubscribe | Required, prominent |
| Physical address | Required (CAN-SPAM) |
| Copyright | Current year |
| View in browser | Optional |
## Typography
### Font Stack
```css
font-family: {Primary}, {Fallback}, Arial, Helvetica, sans-serif;
```
### Type Hierarchy
| Element | Size | Weight | Line Height | Color |
|---------|------|--------|-------------|-------|
| H1 | 28px / 24px mobile | Bold | 1.2 | {#HEX} |
| H2 | 22px / 20px mobile | Bold | 1.3 | {#HEX} |
| H3 | 18px / 16px mobile | Bold | 1.4 | {#HEX} |
| Body | 16px / 16px mobile | Normal | 1.5 | {#HEX} |
| Small | 14px / 14px mobile | Normal | 1.4 | {#HEX} |
| Link | Inherit | Normal | Inherit | {#HEX} |
| Caption | 12px / 12px mobile | Normal | 1.4 | {#HEX} |
## Color Palette
### Primary Colors
| Name | Hex | Usage |
|------|-----|-------|
| Primary | #{HEX} | CTA buttons, links |
| Secondary | #{HEX} | Accents, icons |
| Background | #{HEX} | Email background |
| Content bg | #{HEX} | Content area |
### Text Colors
| Name | Hex | Usage |
|------|-----|-------|
| Heading | #{HEX} | All headings |
| Body | #{HEX} | Body text |
| Muted | #{HEX} | Secondary text |
| Link | #{HEX} | Hyperlinks |
| Link hover | #{HEX} | Hover state |
### Dark Mode
| Element | Light Mode | Dark Mode |
|---------|------------|-----------|
| Background | #{HEX} | #{HEX} |
| Text | #{HEX} | #{HEX} |
| CTA button | #{HEX} | #{HEX} |
## Button Styles
### Primary Button
```html
<a href="{URL}" style="
display: inline-block;
padding: 14px 28px;
background-color: {#HEX};
color: #ffffff;
text-decoration: none;
border-radius: {X}px;
font-weight: bold;
font-size: 16px;
">
{Button Text}
</a>
```
### Secondary Button
```html
<a href="{URL}" style="
display: inline-block;
padding: 12px 24px;
background-color: transparent;
color: {#HEX};
text-decoration: none;
border: 2px solid {#HEX};
border-radius: {X}px;
font-weight: bold;
font-size: 14px;
">
{Button Text}
</a>
```
### Button States
| State | Background | Text | Border |
|-------|------------|------|--------|
| Default | {#HEX} | {#HEX} | {#HEX} |
| Hover | {#HEX} | {#HEX} | {#HEX} |
| Active | {#HEX} | {#HEX} | {#HEX} |
---
## Image Specifications
### Image Requirements
| Type | Dimensions | Format | Max Size |
|------|------------|--------|----------|
| Hero | 600x300 / 1200x600 @2x | JPG/PNG | 200KB |
| Feature | 560xAuto | JPG/PNG | 150KB |
| Product | 280x280 | PNG | 100KB |
| Icon | 64x64 | PNG/SVG | 10KB |
| Logo | 200x60 | PNG | 30KB |
### Alt Text Guidelines
- Descriptive, not decorative ("Blue sneakers on white background")
- Action-oriented for CTAs ("Shop the sale")
- Empty alt for decorative images (alt="")
- Max 125 characters
## Editable Regions
### Content Blocks
| Region ID | Type | Required | Constraints |
|-----------|------|----------|-------------|
| hero_image | Image | Yes | 600x300px |
| hero_headline | Text | Yes | Max 60 chars |
| hero_cta | Link | Yes | URL + text |
| body_content | HTML | Yes | Rich text |
| product_1 | Module | No | Product block |
| product_2 | Module | No | Product block |
| product_3 | Module | No | Product block |
### Dynamic Content Blocks
| Block ID | Variable | Rules |
|----------|----------|-------|
| {block_id} | {variable} | {Show if condition} |
## Personalization
### Merge Tags
| Tag | Default | Example |
|-----|---------|---------|
| {{first_name}} | Friend | Hi {{first_name}}, |
| {{company}} | your company | At {{company}}, |
| {{product_name}} | our product | Check out {{product_name}} |
### Conditional Content
```
{% if segment == "VIP" %}
{VIP exclusive content}
{% else %}
{Standard content}
{% endif %}
```
## Accessibility Requirements
### WCAG 2.1 Compliance
- [ ] Color contrast minimum 4.5:1 (body text)
- [ ] Color contrast minimum 3:1 (large text, buttons)
- [ ] All images have alt text
- [ ] Links have descriptive text
- [ ] Logical reading order
- [ ] No color-only indicators
### Screen Reader Support
- [ ] Role="presentation" on layout tables
- [ ] Proper semantic structure
- [ ] Skip navigation where appropriate
- [ ] Language attribute set
## Testing Requirements
### Email Clients
**Desktop**:
- [ ] Apple Mail (macOS)
- [ ] Outlook 2016/2019/365 (Windows)
- [ ] Outlook for Mac
- [ ] Thunderbird
**Webmail**:
- [ ] Gmail
- [ ] Yahoo Mail
- [ ] Outlook.com
- [ ] AOL Mail
**Mobile**:
- [ ] iOS Mail (iPhone, iPad)
- [ ] Gmail app (iOS, Android)
- [ ] Outlook app (iOS, Android)
- [ ] Samsung Mail
### Rendering Checks
- [ ] Images load correctly
- [ ] Fonts render properly
- [ ] Links work and track
- [ ] Buttons are tappable (min 44px)
- [ ] Text is readable at mobile size
- [ ] Dark mode renders correctly
- [ ] Plain text version works
## Code Requirements
### HTML Standards
- DOCTYPE: HTML 4.01 Transitional or XHTML 1.0
- Tables for layout (email compatibility)
- Inline CSS required
- VML for Outlook shapes/buttons
### Coding Best Practices
- [ ] Max width set on tables
- [ ] Border-collapse: collapse
- [ ] Cellpadding/cellspacing for spacing
- [ ] MSO conditionals for Outlook
- [ ] Background images with fallback color
- [ ] Web-safe fonts with fallbacks
### Sample Structure
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{Email Subject}</title>
<!--[if mso]>
<style>
/* Outlook-specific styles */
</style>
<![endif]-->
</head>
<body style="margin:0; padding:0;">
<table role="presentation" width="100%">
<!-- Email content -->
</table>
</body>
</html>
```
## Version Control
### Template Versions
| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 1.0 | {DATE} | Initial template | {Name} |
| 1.1 | {DATE} | {Changes} | {Name} |
### File Locations
| File | Location |
|------|----------|
| HTML source | {Path/URL} |
| Design file | {Figma/Sketch URL} |
| Image assets | {Asset folder URL} |
## Approvals
| Role | Name | Status | Date |
|------|------|--------|------|
| Designer | | | |
| Developer | | | |
| Email Manager | | | |
| Brand | | | |
*Template version: 1.0 | MMK Framework*