Email Design System

Every email leaving the monorepo (marketing site, workspace, partners portal, memo) renders through one package, @matters/email (packages/email). It implements the design spec in EMAIL_DESIGN.md at the repo root: a centered 600px column on near black, opening directly on a bright blue panel styled as a folded, creased sheet of paper with near black type "printed" on it, brief cyan-labelled text blocks below, and a full compliance footer.

Templates in each app are thin content-model builders. They decide what an email says; the package decides how it looks, produces the HTML, produces an equivalent text/plain part from the same model, and appends the footer. Nothing in an app writes email HTML by hand.

Why one system#

Before this, the repo carried three unrelated email stacks: raw template literals with two diverging copies of a layout helper in the root app, @react-email/components templates on a light theme in partners, and text-only Resend sends in memo. Four templates shipped with no text part, none carried the postal address CAN-SPAM requires, and the subscription opt-in was an unstyled <div>. Consolidating on one renderer fixes all of that structurally: a template cannot ship without a footer or a text part, because the renderer emits both.

Package layout#

Consumers: root app (package.json), apps/workspace, apps/partners, apps/memo, all via "@matters/email": "workspace:*". The Next apps list it in transpilePackages; memo's Vite build transpiles linked workspace packages automatically. The package depends only on zod and @matters/lib (for ValidationError).

Consumers: root app (package.json), apps/workspace, apps/partners, apps/memo, all via "@matters/email": "workspace:*". The Next apps list it in transpilePackages; memo's Vite build transpiles linked workspace packages automatically. The package depends only on zod and @matters/lib (for ValidationError).

Design variants#

A variant owns the HTML presentation of a document and nothing else. Content, compliance and the text/plain part are variant-independent, so every registered design carries the same copy, the same links and the same footer — only the look differs. That invariant is enforced by tests parameterised over the registry, so a new variant is covered the moment it lands.

The registered designs#

The dark and light folded-paper twins#

folded-paper and folded-paper-light are one renderer in one file, not two designs — a FoldedSurround object parameterises everything outside, and one thing inside, the folded-paper poster. The paper's own blue, its crease grid and grain are identical in both; only the surround, and the poster's printed ink, change:

The accent had to move. Cyan reaches only 1.77:1 against white, which is unreadable as text; brand blue reaches 8.76:1. Both were measured.

The poster ink is the one place the flyer itself is not byte-identical between the two surrounds — everything else inside the paper (markup shape, rotation, the crease grid, the grain, the credits layout) is shared, and a test normalises the ink out and asserts the rest matches exactly. The dark surround keeps EMAIL_DESIGN.md's near-black "printed on paper" ink, unchanged, per spec. The light surround prints in brand anti-flash-white instead: near-black-on-blue measures only 2.12:1, and shipping that same low contrast inside an otherwise light-themed email reads as a bug rather than a deliberate choice. Anti-flash-white on the same blue reaches 7.5 to 9.1:1 depending on the fold shade, comfortably past both the 4.5:1 body-text and 3:1 large-text WCAG thresholds. The poster button's background follows the same rule (near-black on dark, anti-flash-white on light); its label stays brand blue on both, since blue reads clearly against either fill.

Both surrounds emit the full dark-mode colour lock set. The light one needs it more, in fact: a client "helpfully" darkening a light email is the common failure, not the reverse.

Brand recolouring#

The v3 and v4 specs shipped with palettes of their own; both were recoloured to the brand kit. BRAND_COLORS in tokens.ts holds the canonical seven, verified against tailwind.config.ts, the theme package's shared.css and its bridge.css, which all agree. The theme package also defines a --color-non-brand-* set; it is labelled non-brand deliberately, so no email may use it.

editorial-receipt deliberately keeps the v2 spec's warm paper and deep navy, because the recolour brief covered v3 and v4 only. Its palette is one object at the top of its file, so moving it onto BRAND_COLORS is a one-place edit if that changes.

Email clients cannot be trusted with rgba, so every opacity step in the specs is pre-composited against the surface it sits on and shipped as opaque hex. The composites were computed, not eyeballed, and the three brand accents were checked by relative luminance to confirm they need black type rather than white.

How a variant maps arbitrary content#

A variant must render any document, or switching designs would break emails. So each design's anatomy is mapped onto the shared model rather than requiring fields only one design supplies:

Three spec elements are deliberately not reproduced, in every case to avoid fabricating content:

• v2's monetary totals. Nothing in the model carries money, and a faked subtotal is worse than none.
• v3's skeleton placeholder bars and designed mini-UIs (a prompt input, a token grid, a code panel). The hero panel carries the document's own credits instead, and feature blocks are cards with a tinted header. Grey filler bars and invented product screenshots are decoration, and inventing them for arbitrary email content would misrepresent it.
• v4's orbiting topology graph and mix-blend-luminosity imagery. Email has no reliable animation, and this system ships no images at all.

Also medium-forced: v4's headline scales to 48px rather than 64-96px because the column is 600px wide, its fixed nav becomes a header row, and product thumbnails in v2 become numbered tiles. v4's spec asks for General Sans, which Google Fonts does not host, so it uses DM Sans — the brand body face and the closest available substitute.

Choosing a design#

Precedence, highest first:

1. Per render — renderEmail(doc, { variant }). Every root template takes an optional trailing options argument forwarded straight to renderEmail, so one send can use a chosen design without touching the template: buildReminderEmail(params, { variant }).
2. Workspace setting, per mail type — an override stored against that mail type in Settings → Email Design. This is what every real send now resolves.
3. Workspace setting, global default — the default chosen in the same panel.
4. Per document — variant on the EmailDocument, for a template inherently tied to one design. Leave it unset so the email follows the settings above.
5. Environment — EMAIL_DESIGN_VARIANT=<id>. Still honoured, and still the only mechanism for the partners and memo apps, which do not read the Mongo settings (see below). An unrecognised value is ignored in favour of folded-paper: a typo must never stop mail from sending.
6. Programmatic — setDefaultEmailVariant(id) once at startup.
7. Otherwise DEFAULT_EMAIL_VARIANT (folded-paper).

Layers 2 and 3 are resolved by resolveVariantForMailType / renderOptionsForMailType in lib/services/email-design.service.ts, and layers 4 to 7 by renderEmail itself.

Changing the design from the workspace#

Settings → Email Design (/settings?view=email-design) sets one global default and, independently, an override per mail type. No deploy and no environment variable.

Permissions. org:marketing:view to read, org:marketing:edit to save — the same pair the Overture settings panel uses, because email design is a marketing surface spanning every mail type rather than a webinar-only one. A user without the read permission gets an explanatory panel rather than a broken one.

Storage. Mongo mattersai.email_design_settings, singleton _id: "global", holding defaultVariant, overrides, updated_at and updated_by. Cleared and unregistered overrides are dropped on write, so the document is always a faithful picture of what is actually overridden.

Propagation. The workspace and the marketing site are separate deployments with separate caches. A save busts the email-design tag locally and then pings the site's /api/revalidate with the same tag, exactly as revalidateOvertures does. That tag had to be added to ALLOWED_WEBHOOK_TAGS in app/api/revalidate/route.ts, which is a strict allowlist. If the webhook secret is unset the ping is skipped and the read's 300 second revalidate window is the guaranteed upper bound, so a change takes effect within five minutes at worst.

A design lookup must never stop an email being sent. That rule shapes the service: the read returns defaults on any database failure, an override naming a variant that is no longer registered is logged and ignored rather than passed to renderEmail (which rejects unknown ids), and the resolver never throws into a send path. Tests cover each of those paths.

Mail types#

lib/email/mail-types.ts is the single registry of what counts as "a kind of email", replacing two hand-copied lists — the six webinar keys were duplicated between the preview route and EmailsView.tsx, and the datasheet, subscription and sales-export mails were in neither.

Ids are stored in Mongo, so treat them as a stable wire format. Adding a mail type means adding an entry here and passing its id at the send site; the settings panel and the resolver pick it up with no further change.

Two caveats the panel states in place:

• custom in raw-HTML mode ignores the setting. The admin authored a whole document, so their markup wins. Simple mode honours it.
• Partners and memo are not covered. They send through Resend from their own deployments and do not read this Mongo settings document, so they follow EMAIL_DESIGN_VARIANT or the package default. Wiring them in would mean either giving them Mongo access or having every partner email make a cross-app HTTP call, and neither is worth it for operational mail. This is a deliberate boundary, not an oversight.

An explicitly named unknown id throws ValidationError, at every layer (render option, document field, setter) — a caller passes ids it controls, and silently rendering the wrong design is worse than a loud failure. Only the environment default degrades quietly, for the reason above.

Partners and memo templates follow the resolved default and take no per-send variant argument, because neither app has a surface that would choose one. Adding it is one forwarded argument per builder if that changes.

Previewing a design#

Two preview surfaces, for two different jobs.

Settings → Email Design → Preview (/settings?view=email-design) is the sample-content picker: choose any mail type and any registered design independently, and it renders a real sample of that mail type through the actual template in that design. This is what to reach for to answer "what would a datasheet email look like in Technical Blueprint" without touching the saved settings. Backed by POST /api/workspace/email-design/preview (org:marketing:view, read-only), which calls buildSampleMail(mailType, { variant }) from lib/email/mail-samples.ts — one sample per mail type, each rendered through the same builder a real send uses, with placeholder data instead of a live record. Omitting variant in the request previews whatever a real send of that mail type would currently use (its override, or the global default), which is what the panel does before you touch either picker.

Workspace → Webinars → Emails has a narrower Design picker beside the webinar template list, for previewing the six webinar templates with real webinar data selected from the page. It is populated from GET /api/workspace/webinars/email/preview, which returns the registry plus the active default, so a new variant appears in the UI with no front-end change. "App default" names the design currently in force.

To eyeball one locally instead, render it to a file and screenshot it:

import { EMAIL_VARIANT_IDS, renderEmail } from "@matters/email";
for (const id of EMAIL_VARIANT_IDS) {
  writeFileSync(`v-${id}.html`, renderEmail(doc, { variant: id }).html);
}

Serve the directory over HTTP (a file: URL is blocked by the Playwright MCP browser) and screenshot at 680px and 380px.

Adding a variant#

Two steps, mirroring @matters/theme:

1. Write packages/email/src/variants/<id>.ts exporting (doc: EmailDocument) => string. Read the whole document model and honour every field — most importantly the footer, since compliance is not optional in any design.
2. Append one entry to EMAIL_VARIANTS in variants/index.ts with an id, a label, a one-line description (both shown in the picker) and the renderer.

No template, transport, route or UI changes. The shared renderEmailText gives the new design its text part for free, and the parameterised tests start asserting the compliance invariants against it immediately.

Note that the further a design departs structurally from folded paper, the more the model may need new optional fields. That is additive: a field one variant ignores costs the others nothing.

The content model#

interface EmailDocument {
  preheader: string; // hidden preview text, 1 to 160 chars
  title?: string; // <title>; defaults to the headline
  viewInBrowserUrl?: string; // renders the 11px "View in browser" line when set
  flyer: EmailFlyer;
  blocks?: EmailBlock[]; // up to 6, rendered 2-up
  footer: EmailFooter;
  year?: number; // copyright year; defaults to now, pass for deterministic tests
  variant?: EmailVariantId; // pin this email to one design; unset follows the app default
}

interface EmailFlyer {
  overline?: string; // italic serif, rotated -2deg: "(you're on the list)"
  kicker: string; // tracked caps: "Registration confirmed"
  presenter?: string; // small tracked caps; default "Presented by Matters.AI"
  headline: string[]; // 1 to 4 stacked lines; wrap ONE phrase in *asterisks* for the serif italic accent
  credits?: EmailCredit[]; // up to 6 { label, value }, laid out 2-up as fold cells
  note?: string; // tracked caps, rotated +1deg, under the credits
  cta?: EmailCta; // near black button with a blue label
  secondaryCta?: EmailCta; // underlined near black text link under the button
}

interface EmailBlock {
  eyebrow: string; // cyan tracked caps
  body?: string | string[]; // paragraphs, escaped; newlines become <br/>
  html?: string; // TRUSTED pre-escaped rich content only (admin authored emails)
  links?: EmailCta[]; // inline cyan text links
}

interface EmailFooter {
  reason: string; // "You're receiving this because ..."
  unsubscribeUrl?: string; // required for any list or marketing send
  preferencesUrl?: string; // rendered only when a preference centre exists
  fineprint?: string; // e.g. "Reference ID: PL-2026-0142"
}

Rules enforced by the schema:

• Every href must be an absolute http(s) URL. Relative paths and mailto: fail validation.
• Empty or whitespace-only optional strings are treated as absent, so builders can forward record fields (description: datasheet.excerpt) without guarding them.
• The preheader is capped at 160 characters. Write a dedicated one; do not reuse a long body.
• Validation failures throw ValidationError whose message lists every path and reason, e.g. Email document failed validation (flyer.cta.href: Email links must be absolute http(s) URLs).

Rendering anatomy#

Canvas. <body> is #050505; the 600px column is #0a0a0a. There is no brand header row: the flyer is the opening. A hidden preheader <div> (with zero-width filler so clients do not pull body copy into the preview) precedes everything.

Folded paper flyer. Built entirely from table cells so it survives every client:

• Each fold is a real <td> with its own solid blue shade (paper #211be9, paperLight #2a25ec, paperDark #1c16d4) so adjacent rectangles catch light differently.
• Creases are two 1px rows (dark valley #120d9e over light ridge #5b57f1) between fold rows and two 1px columns between the left and right cells. No borders, no box shadows, so Outlook renders them.
• Paper grain is an inline SVG feTurbulence tile applied as background-image on each cell over its background-color. Gmail and Outlook drop data URIs and fall back to the flat shade, which is the documented degradation path.
• Row 1: overline (left cell, light) and kicker + presenter (right cell, dark, right aligned). Row 2: the headline (full width). Rows 3+: credits, two per row, alternating shades. Last row: note, button and secondary link. The last row is omitted when it has nothing to print, so a flyer with only credits ends cleanly on the grid.
• Microcopy rotation uses transform: rotate() on display:inline-block spans. Outlook and Gmail ignore it and render flat. Do not add VML to fight this.

Type. Space Grotesk 700 uppercase, 60px, letter-spacing: -0.03em, line-height: 0.95 for the headline (40px under 600px viewports); the *accent* phrase switches to DM Serif Display italic 400 with case preserved. Labels are Space Grotesk tracked caps. Body is DM Sans. Fonts load from Google Fonts via a <link> wrapped in <!--[if !mso]> with fallbacks Helvetica Neue, Arial and Georgia. Ink on paper is #131316 everywhere.

Button. A padded <td bgcolor="#131316"> containing the <a> (bulletproof, never an image), label in Space Grotesk tracked caps coloured #211be9. mso-padding-alt keeps Outlook padding.

Detail blocks. Two per row on desktop (class="mai-stack" collapses them to one column under 600px). Eyebrow is cyan #5ad3e6 tracked caps; body is 13px DM Sans in white/60 (#9d9d9d, pre-composited on the column colour so Outlook, which drops rgba, matches Apple Mail). Links are cyan underlined tracked caps. Cyan is the only accent on dark surfaces; blue appears only as the paper.

Footer (never trimmed). Three rows separated by a 1px #1e1e1e hairline:

1. Social row: LinkedIn, X, YouTube, Instagram, Website as text links (no icon images, so it survives image blocking). URLs live in EMAIL_BRAND.socials.
2. Why + controls: the reason sentence, optional fineprint, then Unsubscribe, Manage preferences (only when a URL is supplied) and Privacy Policy, underlined in white/60.
3. Legal: © {year} Matters.AI, a product of Aegislock AI Pvt Ltd. All rights reserved. and the postal address on its own line. The address is mandatory for CAN-SPAM; the renderer always emits it.

Dark mode. <meta name="color-scheme" content="light dark"> plus supported-color-schemes, and every colour is re-asserted with !important under @media (prefers-color-scheme: dark), [data-ogsc] and [data-ogsb] (Outlook.com), so no client inverts the blue paper or the near black type.

The text part#

renderEmailText walks the same model: kicker, presenter, overline, headline (asterisks stripped), Label: value for every credit, note, Label: url for every CTA, each block's eyebrow, paragraphs and links, then the footer reason, unsubscribe and preferences URLs, privacy policy, every social link, the legal line and the address. html blocks pass through htmlToText. The output never contains <. Because both parts come from one model, the text part cannot drift from the HTML part, which matters for spam scoring and for text-only readers who need the unsubscribe URL.

Client degradation matrix#

Everything the recipient must act on (host, date, join link, code, button, unsubscribe) is live HTML text. Nothing is rasterised into an image.

Copy rules#

• Write Matters.AI (capital AI, dot). "Matters Memo" is allowed only in owner-facing memo mail; visitor-facing memo mail (OTP codes) says Matters.AI and sends from Matters.AI <memo@matters.ai>.
• No hyphens as prose punctuation, no em dashes, in subjects or bodies. Use a colon or a comma. ("Your recording is ready: Title", not "ready — Title".)
• Kickers are tracked caps at 11px on a half-width cell; keep them under 60 characters (buildCustomEmail truncates admin subjects to that length).
• Headlines are one to four short lines with exactly one *accent* phrase, e.g. ["You're", "*in.*"], ["Seven", "days", "*left.*"].
• The footer reason states honestly why the recipient got the mail. Transactional mail with no list (OTP, datasheet delivery, opt-in confirmation, partner notifications) omits unsubscribeUrl; every list or marketing send must supply it.

Template inventory#

Root marketing app and workspace (transport: lib/email/index.ts, SES with Resend fallback)#

Workspace admin previews live at POST /api/workspace/webinars/email/preview with templates registration, reminder, auto_invite, bulk_invite, recording_ready, unsubscribe, and in the Emails tab of the webinars module.

Partners portal (transport: apps/partners/lib/email.ts, Resend)#

All builders are pure functions in apps/partners/lib/email-templates.ts; lib/email.ts resolves portal URLs and sends through deliverPartnerEmail, which normalises Resend's non-throwing error shape into one log line and { ok, error }.

The former apps/partners/emails/*.tsx React Email templates and the @react-email/components dependency were removed.

Memo (transport: apps/memo/src/lib/email/resend.ts, Resend)#

Adding a new email#

1. Write a pure builder next to its siblings (lib/email/… in root, lib/email-templates.ts in partners, the module that owns the copy in memo). It takes typed params and returns { subject, html, text } from renderEmail(...).
2. Fill the model: a preheader under 160 chars, a kicker, a one to four line headline with one *accent*, credits for the vital facts, a cta with an absolute URL, one or two blocks, and an honest footer reason. Add unsubscribeUrl if this is a list send.
3. Pass both parts to the transport (sendEmail({ to, subject, html, text })). Never send HTML alone.
4. Add a test asserting the links appear in both parts and the text part contains no <. Root tests live in tests/lib/, partners in __tests__/lib/, memo beside the module.
5. Render it locally for a look: a tsx script that imports the builder and writes the HTML, then playwright screenshot --viewport-size=640,1000 --full-page file://… (Playwright is a partners dev dependency).
6. Add the template to this inventory and, for webinar templates, to the workspace preview route and EmailsView.tsx.

Testing#

• tests/lib/email-design-system.test.ts: footer always present, unsubscribe and preferences controls, socials as text links, accent markup, escaping, URL validation, empty optional handling, no markup in text. Plus a describe.each over the variant registry asserting the compliance invariants and an identical text part for every registered design, and the variant precedence rules (caller, document, env, programmatic default, unknown-id handling).
• tests/lib/webinar-invite-email.test.ts, tests/lib/recording-ready-email.test.ts: webinar template contracts (both CTAs, omission of the Zoom link when unset, text mirrors links).
• apps/partners/__tests__/lib/email-templates.test.ts: every partner template carries the footer and a real text part; status labels; reminder tiers; ARR formatting.
• apps/memo/src/lib/alerts/hot-lead.test.ts: subject and text contracts plus the HTML part.

Known gaps#

• There is no preference centre in any app, so Manage preferences is only rendered when a builder supplies preferencesUrl. Building one is tracked in PENDING_TASKS.md.
• Five designs are registered. All were rendered and visually checked in Chromium at 680px and 380px, but only in Chromium. See the cross-client note above.
• The workspace Email Design panel — settings and preview — is type-checked, lint-clean, and the workspace production build includes both /api/workspace/email-design and /api/workspace/email-design/preview in its route manifest, but neither has been click-tested in a browser against a live Mongo, since that needs Clerk auth.
• Partners and memo do not read the workspace setting, as described above.
• editorial-receipt is the one design still off the brand kit, by instruction rather than oversight.
• A Litmus or Email on Acid pass across Outlook and Gmail is still to be done before the next bulk webinar send.

Key files#

• EMAIL_DESIGN.md (repo root): the design spec this system implements.
• packages/email/src/*: the renderer; variants/ holds the registry and one file per design.
• lib/email/webinar-emails.ts, components/template-emails/*: root templates.
• apps/partners/lib/email-templates.ts, apps/partners/lib/email.ts: partner templates and transport.
• apps/memo/src/lib/email/resend.ts, apps/memo/src/lib/alerts/hot-lead.ts: memo templates.
• apps/workspace/app/api/workspace/webinars/email/preview/route.ts: webinar admin preview.
• apps/workspace/app/api/workspace/email-design/route.ts (settings) and .../email-design/preview/route.ts (sample preview): the workspace design-settings API.
• apps/workspace/app/(workspace)/settings/components/EmailDesignSettings.tsx: the settings + preview panel.
• lib/email/mail-types.ts, lib/email/mail-samples.ts, lib/schemas/email-design.ts, lib/services/email-design.service.ts: the mail-type registry, preview samples, schema and settings service.

Related#

• Webinars & Recording Hub: the outbound webinar email system, streams, suppression and one-click unsubscribe.
• Partners Notification Engine: routing, channels and delivery records.