email-design

邮件设计

开始之前：加载设计上下文

1. 阅读 .agents/design-context.md（由 design-context 技能编写）。如果文件缺失，请在 tailwind.config.* 或 :root CSS 变量中查找设计令牌。如果都没有，请使用默认值（主色 #2563EB、辅助色 #7C3AED、强调色 #F59E0B、Tailwind 灰色中性色、标题和正文使用 Inter、极简风格），并告知用户使用了默认值——建议运行 design-context。
2. 内联十六进制值——电子邮件客户端不支持 CSS 变量。按钮和链接使用主色，标题、正文和弱化文本使用中性色 900/800/500，外层背景使用中性色 50/100，并在每个适用于 Web 的字体栈中将品牌标题/正文字体放在首位（第 5 节）。下面类似 #4F46E5 的十六进制值是占位符。
3. **Figma：**如果用户提供了 Figma URL，请使用 Figma MCP（get_design_context、get_screenshot）获取设计并按其实现；对于该设计，Figma 会覆盖上下文文件。
4. 询问：邮件类型是什么（欢迎邮件、新闻简报、促销邮件、事务性邮件），以及使用哪个 ESP（可能需要使用其专属合并标签和模板语法）？

---

1. 基本约束

电子邮件 HTML 不等同于网页 HTML。以下约束不可妥协：

规则	原因
基于表格的布局	Windows 版 Outlook（Word 渲染引擎）不支持 flexbox、grid、max-width 或可靠的 float
内联 CSS	有些客户端会移除或部分忽略 <style>（非 Google 账号的 Gmail，以及许多网页邮箱/旧版客户端）；<style> 仅用于媒体查询和深色模式
不使用 JavaScript	所有电子邮件客户端都会将其移除
不使用外部 CSS	有些客户端会屏蔽外部资源
最大宽度 600px	标准电子邮件客户端视口（600–640px）
HTML 小于约 100KB	Gmail 会截断超过 102KB 的邮件——内容、退订链接和打开追踪像素都会隐藏在“查看完整邮件”后面
适用于 Web 的安全字体	自定义字体需要回退字体
所有图片都要有替代文本	图片通常默认会被屏蔽
不使用 CSS 变量	大多数电子邮件客户端不支持
在 <td> 上设置内边距，而不是 <a>/<p>/<div> 上	Outlook 桌面版会忽略许多元素上的内边距/外边距，以及 border-radius、背景图片（不使用 VML 时）和 rgba() 颜色

---

2. 基本邮件结构

<!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.0" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="color-scheme" content="light dark" />
  <meta name="supported-color-schemes" content="light dark" />
  <meta name="format-detection" content="telephone=no, date=no, address=no, email=no" />
  <title>Email Subject Line</title>

  

  <style>
    :root { color-scheme: light dark; supported-color-schemes: light dark; }
    /* Reset styles */
    body, table, td, a { -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%; }
    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; height: 100% !important; }

    /* Responsive styles */
    @media only screen and (max-width: 620px) {
      .email-container { width: 100% !important; max-width: 100% !important; }
      .fluid { max-width: 100% !important; height: auto !important; }
      .stack-column { display: block !important; width: 100% !important; }
      .stack-column-center { text-align: center !important; }
      .center-on-narrow { text-align: center !important; display: block !important;
        margin-left: auto !important; margin-right: auto !important; float: none !important; }
      table.center-on-narrow { display: inline-block !important; }
      .hide-on-mobile { display: none !important; }
      .padding-mobile { padding: 20px !important; }
    }

    /* Dark mode: Apple Mail, iOS Mail, Outlook for Mac/iOS/Android, some others */
    @media (prefers-color-scheme: dark) {
      .email-bg { background-color: #121212 !important; }
      .dark-bg { background-color: #1e1e1e !important; }
      .dark-text { color: #e6e6e6 !important; }
      .dark-text-secondary { color: #b3b3b3 !important; }
      h1, h2, h3 { color: #f2f2f2 !important; }
    }
    /* Outlook.com / Outlook apps: [data-ogsb] = backgrounds, [data-ogsc] = text colors */
    [data-ogsb] .email-bg { background-color: #121212 !important; }
    [data-ogsb] .dark-bg { background-color: #1e1e1e !important; }
    [data-ogsc] .dark-text { color: #e6e6e6 !important; }
    [data-ogsc] .dark-text-secondary { color: #b3b3b3 !important; }
  </style>
</head>

<body style="margin: 0; padding: 0; background-color: #f4f4f7; font-family: -apple-system,
  BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;"
  class="email-bg">
  <div role="article" aria-roledescription="email" aria-label="Email Subject Line" lang="en">

  
  <div style="display: none; font-size: 1px; line-height: 1px; max-height: 0;
    max-width: 0; opacity: 0; overflow: hidden; mso-hide: all;">
    Your preview text goes here. Keep it under 100 characters.
    &#847; &#847; &#847; 
  </div>

  
  <table role="presentation" cellpadding="0" cellspacing="0" border="0"
    width="100%" style="background-color: #f4f4f7;" class="email-bg">
    <tr>
      <td align="center" style="padding: 20px 0;">

        
        <table role="presentation" cellpadding="0" cellspacing="0" border="0"
          width="600" class="email-container dark-bg"
          style="max-width: 600px; width: 100%; background-color: #ffffff; border-radius: 8px;
            overflow: hidden;">

          
          
          
          
          

        </table>

      </td>
    </tr>
  </table>
  </div>
</body>
</html>

---

3. MSO 条件注释（Outlook）

Windows 版经典 Outlook（2007–2021、365 桌面版）使用 Microsoft Word 渲染。“新版 Outlook” for Windows 和 Outlook.com 使用浏览器引擎，但经典 Outlook 仍被广泛使用，因此仍需支持。使用 MSO 条件注释修复 Word 引擎的渲染问题。

常见的 MSO 修复：强制使用 border-collapse: collapse，并在 [if mso] 样式块中指定明确的宽度。对于 Outlook 圆角按钮，使用带有 arcsize、fillcolor 和文本 <center> 的 VML <v:roundrect>，并用 [if mso] / [if !mso] 条件注释包裹，同时提供标准 <a> 作为回退。

---

4. 响应式邮件（流式混合布局）

流式混合布局无需媒体查询，也能在不支持媒体查询的客户端中正常工作。

双栏布局

<div style="display: inline-block; width: 100%; max-width: 290px; vertical-align: top;"
  class="stack-column">
  <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">
    <tr>
      <td style="padding: 20px;">
        <h2 style="margin: 0; font-size: 20px; color: #1a1a2e;">Column 1</h2>
        <p style="margin: 12px 0 0; font-size: 15px; line-height: 1.5; color: #555;">
          Content for the first column.
        </p>
      </td>
    </tr>
  </table>
</div>



<div style="display: inline-block; width: 100%; max-width: 290px; vertical-align: top;"
  class="stack-column">
  <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">
    <tr>
      <td style="padding: 20px;">
        <h2 style="margin: 0; font-size: 20px; color: #1a1a2e;">Column 2</h2>
        <p style="margin: 12px 0 0; font-size: 15px; line-height: 1.5; color: #555;">
          Content for the second column.
        </p>
      </td>
    </tr>
  </table>
</div>

---

5. 邮件排版

适用于 Web 的安全字体栈

将设计上下文中的字体放在首位，然后添加适用于 Web 的安全回退字体栈：

• 无衬线： 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif
• 衬线： Georgia, 'Times New Roman', Times, serif · 等宽： 'Courier New', Courier, monospace

加载 Web 字体（支持有限）

Gmail 和 Outlook 不支持 Web 字体。经典 Outlook 在未安装首选字体时会回退到 Times New Roman——请添加 ``。 在支持的客户端（Apple Mail、iOS Mail、Samsung Mail、Thunderbird）中，可在 <head> 中加载：<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">。

邮件排版字号

元素	字号	字重	行高
H1（主视觉）	28–32px	700	1.2
H2（章节）	22–24px	700	1.25
H3（子章节）	18–20px	600	1.3
正文	15–16px	400	1.5
小字 / 说明文字	13px	400	1.4

规则

• 正文字号最小为 14px（某些客户端会强制使用此字号）。
• 在邮件中使用 px，不要使用 rem 或 em。
• 将 line-height 设置为倍数，而非 px 值。
• 始终为文本元素内联指定 color。

---

6. 万无一失的按钮

适用于所有邮件客户端（包括 Outlook）的按钮。

方法：基于内边距（最佳）

<table role="presentation" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td style="border-radius: 8px; background-color: #4F46E5; mso-padding-alt: 14px 32px;"
      class="button-bg">
      <a href="https://example.com" target="_blank"
        style="display: inline-block; padding: 14px 32px; background-color: #4F46E5; font-size: 16px;
          font-weight: 600; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI',
          Roboto, sans-serif; color: #ffffff; text-decoration: none;
          border-radius: 8px;">
        Get Started Free
      </a>
    </td>
  </tr>
</table>

按钮规则

• 最小尺寸：高 44px、宽 150px 以上。
• 使用带内边距的 display: inline-block（不要使用固定宽度）。
• 同时在 <td> 和 <a> 上设置 background-color；Outlook 会忽略 <a> 的内边距，因此在 <td> 上使用 mso-padding-alt 可还原按钮尺寸（在 Outlook 中只有文本可点击）。
• border-radius 在大多数客户端中有效，但在经典版 Outlook 中无效（按钮会显示为直角）。
• 要在 Outlook 中使用圆角按钮，请使用 VML（参见第 3 节）。

---

7. 邮件版块模板

页眉

<tr>
  <td style="padding: 24px 32px; text-align: center;">
    <img src="https://example.com/logo.png" alt="Company Name"
      width="120" style="display: block; margin: 0 auto;" />
  </td>
</tr>

主视觉版块

<tr>
  <td style="padding: 40px 32px; text-align: center; background-color: #4F46E5;"
    class="padding-mobile">
    <h1 style="margin: 0; font-size: 30px; font-weight: 700; color: #ffffff;
      line-height: 1.2;">
      Welcome to Our Platform
    </h1>
    
    <p style="margin: 16px 0 0; font-size: 16px; color: #E0E7FF;
      line-height: 1.5;">
      You're all set to start building amazing things.
    </p>
    
  </td>
</tr>

内容块

<tr>
  <td style="padding: 32px;" class="padding-mobile">
    <h2 style="margin: 0; font-size: 22px; font-weight: 700; color: #1a1a2e;
      line-height: 1.25;" class="dark-text">
      What's inside
    </h2>
    <p style="margin: 12px 0 0; font-size: 15px; line-height: 1.6; color: #555;"
      class="dark-text-secondary">
      Here's what you can do to get started with your account.
    </p>
  </td>
</tr>

功能行（图标 + 文本）

<tr>
  <td style="padding: 0 32px 24px;" class="padding-mobile">
    <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">
      <tr>
        <td width="48" valign="top" style="padding-right: 16px;">
          <img src="https://example.com/icon-check.png" alt="" width="40" height="40"
            style="display: block;" />
        </td>
        <td valign="top">
          <h3 style="margin: 0; font-size: 16px; font-weight: 600; color: #1a1a2e;">
            Quick Setup
          </h3>
          <p style="margin: 4px 0 0; font-size: 14px; line-height: 1.5; color: #666;">
            Get up and running in less than 5 minutes.
          </p>
        </td>
      </tr>
    </table>
  </td>
</tr>

页脚

<tr>
  <td style="padding: 24px 32px; text-align: center; border-top: 1px solid #e5e7eb;">
    
    <table role="presentation" cellpadding="0" cellspacing="0" border="0"
      style="margin: 0 auto;">
      <tr>
        <td style="padding: 0 8px;">
          <a href="#"><img src="https://example.com/icon-twitter.png" alt="Twitter"
            width="24" height="24" /></a>
        </td>
        <td style="padding: 0 8px;">
          <a href="#"><img src="https://example.com/icon-linkedin.png" alt="LinkedIn"
            width="24" height="24" /></a>
        </td>
      </tr>
    </table>
    
    
    <p style="margin: 16px 0 0; font-size: 13px; line-height: 1.5; color: #6b6b6b;">
      Company Name, 123 Street, City, State 12345<br />
      <a href="#" style="color: #6b6b6b; text-decoration: underline;">Unsubscribe</a>
      &nbsp;|&nbsp;
      <a href="#" style="color: #6b6b6b; text-decoration: underline;">Manage preferences</a>
    </p>
  </td>
</tr>

---

8. 深色模式邮件注意事项

基础结构（第 2 节）已包含所需部分：color-scheme / supported-color-schemes 元标签和 :root 规则、prefers-color-scheme: dark 区块，以及适用于 Outlook.com 和 Outlook 应用的 [data-ogsb] / [data-ogsc] 覆盖规则。

客户端的行为

客户端	行为	可控内容
Apple Mail、iOS Mail、Outlook Mac	遵循 prefers-color-scheme	完全自定义深色调色板
Outlook.com、Outlook iOS/Android	部分自动反色	[data-ogsb] / [data-ogsc] 覆盖规则
Gmail 应用（iOS/Android）	完全或部分强制反色	无——设计时应确保反色后仍清晰易读

• 避免使用纯 #000 / #fff 配色；使用中等深色背景（#121212–#1e1e1e）搭配灰白色文本，反色后的效果更自然。
• 将品牌色作为 <td> 上的 background-color 用于按钮，避免反色后文本变得难以辨认。

图片处理

• 尽可能使用透明 PNG（可适配任意背景）。
• 为深色徽标添加白色轮廓或光晕，使其在深色背景上清晰可见。
• 测试图片被屏蔽时的效果——替代文本应能传达信息。

---

9. 图片优化

规则

指南	值
单张图片最大文件大小	200KB
邮件总大小	HTML 小于 102KB（Gmail 会截断；建议控制在 < 80KB）+ 图片总大小约小于 1MB
格式	图形使用 PNG，照片使用 JPEG
Retina	提供 2x 图片，将 width 属性设为 1x 尺寸
替代文本	始终提供。为替代文本设置样式，作为后备显示方案。

Retina 图片

<img src="https://example.com/hero-1200.jpg" alt="Product showcase"
  width="600" style="display: block; width: 100%; max-width: 600px; height: auto;" />

带样式的替代文本

<img src="https://example.com/hero.jpg"
  alt="Spring Sale: 40% off everything"
  width="600"
  style="display: block; width: 100%; max-width: 600px; height: auto;
    font-family: sans-serif; font-size: 24px; font-weight: bold;
    color: #4F46E5; background-color: #EEF2FF; text-align: center; padding: 40px;" />

---

10. 模板类型

欢迎邮件

• 使用品牌色背景的主视觉
• 个性化问候语（“Hi {first_name}”）
• 3 个带图标的快速入门步骤
• 主要 CTA：“开始使用”或“完善个人资料”
• 可选：入门视频缩略图

新闻简报

• 简洁的页眉，包含徽标 + 日期
• 配有大图的精选文章
• 下方设置 2 列文章网格
• 简短摘要（2–3 行），附带“阅读更多”链接
• 页脚包含社交链接和退订链接

促销邮件

• 突出展示优惠的主视觉（“40% OFF”）
• 商品网格（2 列）
• 每件商品包含：图片、名称、价格、CTA
• 营造紧迫感：“周日截止”或倒计时
• 信任标识：免费配送、退货服务

事务性邮件

• 设计简洁，信息清晰
• 订单确认：商品、数量、价格、总额
• 配送更新：追踪号码、送达日期
• 密码重置：单个 CTA 按钮、安全说明
• 不包含促销内容（有助于提高送达率）

所有类型的送达基础

• 批量发送邮件者（自 2024 年起适用的 Gmail/Yahoo 规则）：设置一键退订标头（List-Unsubscribe + List-Unsubscribe-Post，RFC 8058）、SPF/DKIM/DMARC，以及醒目的退订链接。
• 始终提供纯文本替代内容，并在页脚注明实体邮寄地址。

---

验证：渲染并检查

不要交付未经检查的邮件。生成后：

1. 在浏览器中分别以 390px 和 1440px 截图，例如：npx playwright screenshot --full-page --viewport-size=390,844 file://$PWD/email.html mobile.png。桌面版截图应显示居中的 600px 栏；移动版截图应显示纵向堆叠的栏，且没有水平滚动。
2. 截取深色模式截图（--color-scheme=dark），并在关闭图片的情况下检查（移除 src 属性）——邮件内容和 CTA 仍须清晰可读。
3. 检查文件大小：内联后，wc -c email.html 必须小于约 100KB。
4. 如需覆盖真实客户端（经典版 Outlook、Gmail 应用），请通过 Litmus / Email on Acid 或测试收件箱发送测试邮件——浏览器无法模拟 Word 引擎。如果无法执行此步骤，请告知用户仍需进行此测试。

---

邮件设计检查清单

• 基于表格的布局（不使用 flexbox/grid）
• 所有关键样式均为内联
• 最大宽度为 600px
• 所有图片都带有 alt 文本以及 width/height 属性
• 按钮稳健可靠（基于 padding 或使用 VML）
• 为 Outlook 添加 MSO 条件注释
• 在 320px–600px 屏幕上响应式显示（流式混合布局）
• 使用网页安全字体并提供后备字体栈
• 已设置预览文本（隐藏的预标题）
• 包含深色模式 meta 标签和 CSS
• 每张图片小于 200KB；HTML 小于 102KB，避免 Gmail 截断
• 已通过 Litmus 或 Email on Acid 在主流客户端中测试
• 页脚包含退订链接和实体地址；已在 ESP 中设置 List-Unsubscribe 标头
• 已在 390px 和 1440px 下分别渲染并截取浅色和深色模式截图（参见“验证”）
• 所有布局表格都带有 role="presentation"