@clay-ds/email

The Lifecycle / Email tier of the Clay Design System — responsive, Outlook-safe HTML emails authored in MJML and composed from the shared Clay foundation tokens.

Why MJML + inlined tokens

Email clients (notably Outlook) do not support CSS custom properties (var(--clay-*)). So this package never ships var() — instead a build step reads the resolved literal token values from @clay-ds/tokens (the dist/tokens.js ES export) and inlines them into MJML at build time.

@clay-ds/tokens (JS literals)
   ↓  src/tokens/build-email-tokens.ts   (generates)
src/generated/base-head.mjml   ← <mj-head>: fonts, mj-class roles, dark-mode
src/generated/email-tokens.ts  ← inline-able constants + px() helper
   ↓  MJML sections + container
src/build/compile.ts  (mjml2html)
   ↓
dist/emails/<name>.html         ← standalone, previewable
dist/emails/<name>.braze.html   ← Braze full-template variant (unsubscribe token)
dist/emails/<name>.static.html  ← hand-authored fallback (no MJML)
dist/catalog.json               ← Storybook + docs source

Structure

• src/container/ — the shared email shell (page bg → 640px card → 560px inner, preheader, responsive + dark/light). Every email reuses it.
• src/sections/ — MJML section partials (logo-header, hero, feature-rows, icon-feature-list, cta-button, footer).
• src/emails/ — full email compositions (container + sections) plus a static-HTML fallback.
• src/tokens/ — the token→email bridge codegen.
• src/build/ — MJML compile + Braze transform + catalog.

Scripts

pnpm --filter @clay-ds/email build          # tokens bridge → tsc → compile MJML
pnpm --filter @clay-ds/email dev            # watch + recompile MJML
pnpm --filter @clay-ds/email tokens:check   # fail if generated token artifacts drift
pnpm --filter @clay-ds/email test           # vitest

Documented in Storybook under Lifecycle/Email/.