@company-semantics/contracts 35.0.0 → 36.0.0

package/src/notifications/renderers/email/chat.ts

@@ -8,17 +8,18 @@
  * the "⋮" dots.
  *
  * INVARIANTS:
- * - Pure, and byte-identical to what the deleted `src/email/render/blocks` emits. The
- *   box art is real output: the output-parity golden asserts every column of it.
+ * - Pure. The box art is real output, and every column of it is locked by
+ *   `../../__tests__/render-snapshot.test.ts` — a stray space is a visibly
+ *   broken email, not a whitespace nit.
  * - Both surfaces truncate at the same point — `clampMessage` is the one
  *   truncation authority, and HTML and plain text both run content through it.
  */
 
 import type { CallToAction, ChatTurn, ChatUnitItem } from "../../content";
 
-import { FONT_SIZE, MONO } from "./constants";
 import { ctaButton } from "./cta";
 import { escapeHtml } from "./escape-html";
+import { styleClass } from "./styles";
 
 /** Greedy word-wrap into lines of at most `width` chars (hard-breaks long words). */
 function wrapText(text: string, width: number): string[] {
@@ -52,6 +53,17 @@ const MESSAGE_WIDTH = 36;
  * user box aligns with the assistant box. */
 const CHAT_INDENT = "       ";
 
+/**
+ * The gap under a chat row: 24px clears the bubbles, 16px hugs whatever the row
+ * is introducing (a CTA, the dots).
+ *
+ * A recipe name rather than a margin string, because a margin cannot be inline on
+ * the AMP surface (ADR-CONTRACTS-089) — and naming the two the layout actually has
+ * is what makes a third one a deliberate addition to `./styles.ts` rather than a
+ * new string appearing at a call site.
+ */
+type ChatRow = "chat-row-16" | "chat-row-24";
+
 /** Word-wrap `text`, then clamp to `maxLines`, ellipsizing the last line on overflow. */
 function wrapClamped(text: string, width: number, maxLines: number): string[] {
   const lines = wrapText(text, width);
@@ -76,8 +88,7 @@ function clampMessage(text: string): string {
 /** The `<hr>` bracketing a chat unit — 24px toward the bubbles, 12px on the
  * outer side. */
 function chatRuleHtml(position: "top" | "bottom"): string {
-  const margin = position === "top" ? "12px 0 24px 0" : "24px 0 12px 0";
-  return `<hr style="border: none; border-top: 1px solid #bbb; margin: ${margin};">`;
+  return `<hr ${styleClass(`chat-rule-${position}`, "faint")}>`;
 }
 
 /**
@@ -89,34 +100,35 @@ function chatRuleHtml(position: "top" | "bottom"): string {
  */
 function renderBubble(
   turn: ChatTurn,
-  margin: string,
+  row: ChatRow,
 ): { html: string; text: string[] } {
   const clamped = clampMessage(turn.text);
   const isUser = turn.role === "user";
 
-  const radius = isUser ? "8px 8px 0 8px" : "8px 8px 8px 0";
-  const bubbleAlign = isUser ? " text-align: right;" : "";
-  const cellAlign = isUser ? "right" : "left";
-  const csHidden = isUser ? "visibility: hidden; " : "";
-  const kaomojiHidden = isUser ? "" : "visibility: hidden; ";
+  // Each side draws its own avatar and hides the other's, which is what reserves
+  // both columns and keeps the two bubbles aligned.
+  const bubble = isUser ? "bubble-user" : "bubble-assistant";
+  const channel = isUser ? "chat-channel-right" : "chat-channel-left";
+  const avatar = isUser ? "chat-avatar-left-hidden" : "chat-avatar-left";
+  const kaomoji = isUser ? "chat-avatar-right" : "chat-avatar-right-hidden";
 
   const attributionRow =
     isUser && turn.from
       ? `
   <tr>
     <td></td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch;">${escapeHtml(turn.from)}</td>
+    <td ${styleClass("chat-attribution", "meta")}>${escapeHtml(turn.from)}</td>
     <td></td>
   </tr>`
       : "";
 
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: ${margin};">
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass(row)}>
   <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; ${csHidden}white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: ${cellAlign};"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
-      <tr><td style="border-radius: ${radius}; padding: 10px 14px;${bubbleAlign} ${MONO} font-size: ${FONT_SIZE}; color: #ffffff; background: #666;">${escapeHtml(clamped)}</td></tr>
+    <td ${styleClass(avatar)}>[c_S]</td>
+    <td ${styleClass(channel)}><table cellpadding="0" cellspacing="0" border="0" ${styleClass("chat-bubble-wrap")}>
+      <tr><td ${styleClass(bubble, "bubble")}>${escapeHtml(clamped)}</td></tr>
     </table></td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; ${kaomojiHidden}white-space: nowrap;">(•̀_ರ╮)</td>
+    <td ${styleClass(kaomoji)}>(•̀_ರ╮)</td>
   </tr>${attributionRow}
 </table>`;
 
@@ -148,7 +160,7 @@ const CHAT_RIGHT_EDGE = CHAT_INDENT.length + MESSAGE_WIDTH + 4;
 /** Centered "⋮" HTML, sized to sit above and centered over a CTA box (they share
  * the same inline-block, so the dots span exactly the button's width). */
 function dotsOverCtaHtml(): string {
-  return `<div style="${MONO} font-size: 20px; font-weight: bold; color: #666; text-align: center; margin: 0 0 16px 0;">⋮</div>`;
+  return `<div ${styleClass("dots-over-cta", "dots")}>⋮</div>`;
 }
 
 /**
@@ -163,15 +175,15 @@ function renderChatCta(
   align: "left" | "right",
   withDots: boolean,
 ): { html: string; text: string[] } {
-  const { html: btnHtml, text: btnText } = ctaButton(cta, "0");
+  const { html: btnHtml, text: btnText } = ctaButton(cta, "none");
   // Dots + button share one inline-block so the dots center over the button's
   // exact width regardless of label length.
-  const stack = `<div style="display: inline-block; text-align: left;">${withDots ? dotsOverCtaHtml() : ""}${btnHtml}</div>`;
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 24px 0;">
+  const stack = `<div ${styleClass("cta-stack")}>${withDots ? dotsOverCtaHtml() : ""}${btnHtml}</div>`;
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass("chat-row-24")}>
   <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: ${align};">${stack}</td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
+    <td ${styleClass("chat-avatar-left-hidden")}>[c_S]</td>
+    <td ${styleClass(`chat-channel-${align}`)}>${stack}</td>
+    <td ${styleClass("chat-avatar-right-hidden")}>(•̀_ರ╮)</td>
   </tr>
 </table>`;
 
@@ -203,11 +215,11 @@ function renderChatCta(
  * case folds the dots into the CTA via `renderChatCta`, centered over the box).
  */
 function renderChatDots(): { html: string; text: string[] } {
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 16px 0;">
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass("chat-row-16")}>
   <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: center; ${MONO} font-size: 20px; font-weight: bold; color: #666;">⋮</td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
+    <td ${styleClass("chat-avatar-left-hidden")}>[c_S]</td>
+    <td ${styleClass("dots-cell", "dots")}>⋮</td>
+    <td ${styleClass("chat-avatar-right-hidden")}>(•̀_ರ╮)</td>
   </tr>
 </table>`;
   // Center the "⋮" over the message box (avatar gutter + box width + borders).
@@ -250,11 +262,11 @@ export function renderChatUnit(items: ChatUnitItem[]): {
     // A bubble directly above a CTA or continuation dots gets a tighter 16px
     // gap; else 24px.
     const next = items[i + 1]?.type;
-    const margin =
+    const row: ChatRow =
       next === "callToAction" || next === "continuation"
-        ? "0 0 16px 0"
-        : "0 0 24px 0";
-    parts.push(renderBubble(item, margin));
+        ? "chat-row-16"
+        : "chat-row-24";
+    parts.push(renderBubble(item, row));
   });
 
   const width = parts

package/src/notifications/renderers/email/colors.ts

@@ -0,0 +1,342 @@
+/**
+ * The email channel's colour — every colour it emits, in every scheme it
+ * supports (ADR-CONTRACTS-088).
+ *
+ * This is the one place a colour changes. Everything else in this directory asks
+ * for a ROLE and gets whatever answer the scheme has; no module below emits a
+ * literal, and `__tests__/colors.test.ts` fails if one creeps back in.
+ *
+ * **Why this is email's and not the notification layer's.** Email is the only
+ * channel that hand-authors colour, because it is the only one with no
+ * client-side semantic vocabulary to lean on. `../slack` says `:warning:` and
+ * `context` and lets Slack's client theme it — Block Kit exposes no author-set
+ * colour at all, so Slack's dark mode costs us nothing. `../sms` has no colour to
+ * have. A shared `notifications/colors.ts` would look DRY and would put a
+ * channel's presentation back inside the channel-agnostic layer, which is the
+ * coupling `../../renderer.ts` exists to prevent. A channel that needs colour
+ * gets its own file, next to its own renderer.
+ *
+ * **Roles are meaning, not coincidence** — and this file has already been paid for
+ * saying so. `border`, `bubble`, `meta` and `dots` all answered `#666`, and a
+ * palette keyed by colour would have made them one entry. Then `border` alone
+ * moved to the link's blue, which under that shortcut would have dragged every
+ * chat bubble with it.
+ *
+ * The test is whether two things are two DECISIONS, not whether they currently
+ * agree — and it cuts both ways. `faint` and `rule` were split on that reasoning
+ * and it was wrong: the `/* EOM *\/` marker and the rules are one decision, "the
+ * marks that recede", wearing two names. They were merged. A role that can never
+ * be answered separately is not a role, it is a synonym, and synonyms cost the
+ * same as roles while buying nothing.
+ *
+ * **What tracks the app, and what does not.** `./constants.ts` explains that a
+ * copied token cannot follow the app, because contracts sits above it in the
+ * dependency flow — "that divergence is the cost of the arrow pointing one way".
+ * That cost is worth paying for the colours a recipient reads as OURS, and not
+ * for the rest:
+ *
+ * - `link`, `border` and `destructive` are copied, and named below with the token
+ *   they came from. A link is the brand's blue in a light email for the same
+ *   reason it is in the app, and a CTA's edge is that blue because the box IS the
+ *   link.
+ * - Every other role is this channel's own. Its look — monospace, rules, box art —
+ *   is not the app's, and inventing an app token to copy for `bubble` or `dots`
+ *   would be debt bought for nothing.
+ *
+ * INVARIANTS:
+ * - Pure data and pure functions of it. No clock, no environment, no I/O.
+ * - Nothing here is exported from the domain barrel. A colour is not vocabulary,
+ *   for the same reason `./constants.ts`'s margins are not.
+ */
+
+/**
+ * A scheme the channel can render. Two today; the shape is a set rather than a
+ * boolean because `highContrast` or `print` would join it rather than replace it.
+ */
+export type ColorScheme = "light" | "dark";
+
+/**
+ * Every colour decision this channel makes, named by what it means.
+ *
+ * `faint` is the marks that recede — the `/* EOM *\/` marker AND every rule. One
+ * decision, so one role, even though it lands on `color` in one place and
+ * `border-top-color` in the other. Which CSS property carries a colour is not
+ * what makes it a different colour.
+ */
+export type Role =
+  | "background"
+  | "text"
+  | "faint"
+  | "meta"
+  | "cta"
+  | "ctaHover"
+  | "bubble"
+  | "onBubble"
+  | "dots"
+  | "link"
+  | "destructive";
+
+/** One scheme's answer for every role. `Record` — a scheme owes an answer to all of them. */
+export type EmailPalette = Record<Role, string>;
+
+/** Every role, for tests to iterate. Source order is the table in ADR-CONTRACTS-088. */
+export const ROLES: readonly Role[] = [
+  "background",
+  "text",
+  "faint",
+  "meta",
+  "cta",
+  "ctaHover",
+  "bubble",
+  "onBubble",
+  "dots",
+  "link",
+  "destructive",
+];
+
+/**
+ * The roles carried by a class hook, and therefore needing a rule in
+ * `DARK_STYLE`. The absentees are not exceptions to tune — they are structural,
+ * each riding another role's rule because it can never move alone:
+ *
+ * - `background` and `text` land on `body`, which needs no class.
+ * - `onBubble` rides `.cs-bubble` — a bubble's fill and its text change together
+ *   or not at all.
+ */
+export const CLASS_ROLES: readonly Role[] = [
+  "faint",
+  "meta",
+  "cta",
+  "ctaHover",
+  "bubble",
+  "dots",
+  "link",
+  "destructive",
+];
+
+/**
+ * Roles whose rule is a `:hover` state rather than a resting colour.
+ *
+ * Two things follow, and both are departures from every other role:
+ *
+ * - **It cannot be inline.** `:hover` has no inline form, so BOTH schemes state it
+ *   in the stylesheet — light in `BASE_STYLE`, dark overriding in `DARK_STYLE`.
+ *   Every other role is inline-light with a dark override.
+ * - **It is opportunistic.** `:hover` support in mail clients is poor and
+ *   inconsistent: good in Apple Mail, partial in new Outlook for Mac and Yahoo,
+ *   absent in Gmail and classic Outlook. Where it does not work the button simply
+ *   rests, which is the state it has today — so this can only add, never subtract.
+ */
+export const HOVER_ROLES: readonly Role[] = ["ctaHover"];
+
+/**
+ * The app's `--primary`, per scheme — resolved with `pnpm color`, never eyeballed.
+ *
+ * TWO roles spend this: `link` and `cta`. A call to action is a link wearing a
+ * box, so its edge and its label are the link's colour and say which of these it
+ * is. They stay separate roles rather than collapsing into one, because "the CTA
+ * tracks the link" is a decision this states rather than a fact about colour —
+ * pull them apart by giving `cta` its own value, not by unpicking a shared
+ * constant.
+ */
+const PRIMARY: Record<ColorScheme, string> = {
+  // `:root --primary` (`oklch(0.5249 0.264881 263.0129)` → `#0050ff`). Left at the
+  // value the old layer shipped: deltaEOK to the token is 0.0167, inside the 0.02
+  // JND, so they are the same blue to a reader and "fixing" it would rewrite 25
+  // snapshots to change nothing anyone can see.
+  light: "#0047FF",
+  // `.dark --primary` (`oklch(0.91 0.165 195)`), gamut-mapped to sRGB. The token
+  // sits just outside sRGB and maps to aqua — `oklch(#00ffff)` is
+  // `L=0.9054 C=0.1546 H=194.77` against the token's `0.91 / 0.165 / 195` — so
+  // this is the token, not a clamping artifact.
+  dark: "#00ffff",
+};
+
+const PALETTES: Record<ColorScheme, EmailPalette> = {
+  light: {
+    background: "#ffffff",
+    text: "#1a1a1a",
+    faint: "#bbb",
+    meta: "#666",
+    cta: PRIMARY.light,
+    // The app's `:root --secondary-item-hover` — `--primary` at 20%,
+    // `oklch(0.9064 0.1527 194.8 / 20%)` — flattened over this scheme's
+    // `background`, because an email cannot lean on alpha:
+    //   pnpm color 'oklch(0.9064 0.1527 194.8 / 20%)' --over '#ffffff'
+    // A function of `background`; recompute if that moves.
+    ctaHover: "#d1ffff",
+    bubble: "#666",
+    onBubble: "#ffffff",
+    dots: "#666",
+    link: PRIMARY.light,
+    // The app's `:root --destructive` (`oklch(0.577 0.245 27.325)`) in sRGB.
+    destructive: "#e7000b",
+  },
+  dark: {
+    background: "#1a1a1a",
+    text: "#e8e8e8",
+    faint: "#666",
+    meta: "#8a8a8a",
+    cta: PRIMARY.dark,
+    // Same token and same arithmetic as `bubble` below, and the identical answer
+    // — both are `.dark --secondary-item-hover` over this `background`. Two roles
+    // because they are two decisions: a hovered button and a chat bubble have no
+    // reason to move together, and the day one of them changes, keying this
+    // palette by colour would have moved both.
+    ctaHover: "#154848",
+    // The app's `.dark --secondary-item-hover` (the tree-nav hover), which is
+    // `--primary` at 20% — `oklch(0.91 0.165 195 / 20%)` — FLATTENED over this
+    // scheme's `background`, because an email cannot lean on alpha:
+    //   pnpm color 'oklch(0.91 0.165 195 / 20%)' --over '#1a1a1a'
+    // It is a function of `background`, so recompute it if that moves. Hue
+    // survives the flattening (195.10), which is what makes it read as the same
+    // hover rather than a grey.
+    bubble: "#154848",
+    onBubble: "#ffffff",
+    dots: "#8a8a8a",
+    link: PRIMARY.dark,
+    destructive: "#ff6b6b",
+  },
+};
+
+/**
+ * One scheme's palette.
+ *
+ * Callers ask for a scheme rather than importing a `LIGHT` / `DARK` object, so a
+ * third scheme is an entry in `PALETTES` rather than an edit to every call site.
+ */
+export function palette(scheme: ColorScheme): EmailPalette {
+  return PALETTES[scheme];
+}
+
+/** The CSS properties a role's colour lands on. */
+export type ColorProp =
+  | "color"
+  | "background"
+  | "background-color"
+  | "border-color"
+  | "border-top-color";
+
+/**
+ * `onBubble` → `cs-on-bubble`. Derived, never hand-typed.
+ *
+ * The `cs-` prefix is load-bearing, and `./styles.ts` explains why: a role class
+ * survives into the shipped HTML because `DARK_STYLE` needs it there, while a
+ * `csr-` recipe class is consumed by the inliner and never ships. The prefixes
+ * are what make "a hook" and "a bundle of declarations" mechanically separable.
+ */
+export function classNameFor(role: Role): string {
+  return `cs-${role.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+}
+
+/**
+ * A class attribute for one or more roles, e.g. `class="cs-cta cs-cta-hover"`.
+ *
+ * Each class is DERIVED from its role, which is what makes a class that names one
+ * role while carrying another's colour unrepresentable rather than merely
+ * tested.
+ *
+ * Several roles land on one element when they are separately decidable but
+ * inseparably placed — a CTA's edge and its hover fill are both the box, and the
+ * hover one is present only when the box is actually clickable.
+ */
+export function roleClass(...roles: Role[]): string {
+  return `class="${roles.map(classNameFor).join(" ")}"`;
+}
+
+/**
+ * A role's LIGHT declaration, unterminated: `color: #666`.
+ *
+ * Light is the baseline every client gets, including the ones that strip
+ * `<style>`. Dark arrives via `darkStyle` instead — see it for why the two are
+ * not two sources of truth.
+ *
+ * Unterminated because a declaration is an ingredient: `./styles.ts` composes it
+ * into an ordered recipe and owns the separators, and that recipe is what BOTH
+ * surfaces are built from — inline for HTML, a rule for AMP. See `./constants.ts`'s
+ * `MONO_DECL`, which is unterminated for the same reason.
+ */
+export function roleDecl(role: Role, prop: ColorProp = "color"): string {
+  return `${prop}: ${PALETTES.light[role]}`;
+}
+
+const light = PALETTES.light;
+const dark = PALETTES.dark;
+
+/**
+ * The scheme-independent rules — everything that has no inline form.
+ *
+ * Only `:hover` lives here, and only because it cannot be inline. This block is
+ * the LIGHT hover; the dark block follows it in the shell and overrides it, so
+ * source order is what resolves them (same specificity).
+ *
+ * Whether any of it happens is the client's call, and this is the ONE role whose
+ * reach the AMP surface changes. Apple Mail honours `:hover`, new Outlook for Mac
+ * and Yahoo partially, Gmail and classic Outlook not at all — but Gmail is an AMP
+ * client, and there this rule simply works. On the html surface there is no
+ * fallback to write: without it the button rests, which is how it looks today.
+ * Purely additive, like the dark path. See `./styles.ts` for the surface split.
+ *
+ * `.cs-cta-hover` is present ONLY on a CTA that actually has an `href` — see
+ * `./cta.ts`. An OTP code wears `.cs-cta` for its edge and never this, because a
+ * hover state on something unclickable promises a click that will not happen.
+ */
+export function hoverStyle(important: boolean): string {
+  const bang = important ? " !important" : "";
+  return `.cs-cta-hover:hover { background-color: ${light.ctaHover}${bang}; }`;
+}
+
+/** The html surface's hover block. See `hoverStyle` for why it is `important`. */
+export const BASE_STYLE = hoverStyle(true);
+
+/**
+ * The dark override.
+ *
+ * A template rather than a generated string — it reads top to bottom as the CSS
+ * it is — but it interpolates `palette("dark")` rather than literals, so a
+ * colour still changes in exactly one place. What a template CAN do is forget a
+ * role; `__tests__/colors.test.ts` is what catches that.
+ *
+ * `!important` on every declaration is load-bearing, not defensive: the light
+ * colour is inline, inline beats a stylesheet on specificity, and without
+ * `!important` every rule here silently loses and dark quietly does nothing.
+ *
+ * **This block is the html surface's alone, and gives up nothing by being so.**
+ * AMP4EMAIL disallows the `prefers-color-scheme` media feature outright — verified
+ * against the AMP validator, with and without `data-css-strict` — so the AMP
+ * surface cannot carry these rules in any form, and does not try
+ * (ADR-CONTRACTS-089). It costs nothing, because the two audiences are disjoint:
+ * this block is read by Apple Mail, iOS Mail and Outlook for Mac (see
+ * `./shells.ts`), and AMP is read by Gmail, Yahoo and Mail.ru — clients that
+ * force-invert and never honoured it. Unlike `hoverStyle`, there was no version of
+ * this worth parameterizing.
+ *
+ * `.cs-faint` states both `color` and `border-top-color` because one role lands
+ * on two properties — the `/* EOM *\/` span takes the first and ignores the
+ * second, each `<hr>` does the reverse. Two classes would be tidier to read and
+ * would mean the class no longer derives from the role, which is the property
+ * that makes a class carrying the wrong colour unrepresentable. A declaration an
+ * element ignores costs nothing; a class that can lie costs a debugging session.
+ *
+ * This block is additive and fail-safe. A client that strips `<style>` or ignores
+ * `prefers-color-scheme` keeps the inline light colours — which is exactly
+ * today's behaviour, not a degraded one.
+ *
+ * Custom properties would collapse all of this into one `:root` redefinition and
+ * are NOT used: caniemail puts them at ~45% support, and Outlook for Mac 16.80 —
+ * a current client, and one of the three that honours `prefers-color-scheme` at
+ * all — does not support them. In a client without them `color: var(--text, #1a1a1a)`
+ * is an invalid declaration and drops whole, so text loses its colour rather than
+ * falling back. They would break dark mode in a client we are building it for.
+ */
+export const DARK_STYLE = `@media (prefers-color-scheme: dark) {
+body { background-color: ${dark.background} !important; color: ${dark.text} !important; }
+.cs-faint { color: ${dark.faint} !important; border-top-color: ${dark.faint} !important; }
+.cs-meta { color: ${dark.meta} !important; }
+.cs-cta { border-color: ${dark.cta} !important; }
+.cs-cta-hover:hover { background-color: ${dark.ctaHover} !important; }
+.cs-bubble { background: ${dark.bubble} !important; color: ${dark.onBubble} !important; }
+.cs-dots { color: ${dark.dots} !important; }
+.cs-link { color: ${dark.link} !important; }
+.cs-destructive { color: ${dark.destructive} !important; }
+}`;

package/src/notifications/renderers/email/constants.ts

@@ -1,8 +1,12 @@
 /**
- * Email channel constants — the styling vocabulary and the one link in it
+ * Email channel constants — typography, layout, and the one link in them
  * (ADR-CONTRACTS-086). `EMAIL_FROM` (SES envelope) is infra and stays in the
  * backend.
  *
+ * Colour is NOT here: it moved to `./colors.ts` when the channel gained a second
+ * scheme (ADR-CONTRACTS-088). What is left is what has only ever had one answer —
+ * a font stack does not change in the dark.
+ *
  * These are the email channel's own answer and are deliberately NOT exported
  * from the domain barrel: a margin is not vocabulary. The brand NAME is not here
  * either — it is `../../context`'s `COMPANY_NAME`, because it is the same answer
@@ -24,8 +28,16 @@ export const COMPANY_URL = "https://companysemantics.ai";
 // Styling
 // =============================================================================
 
-/** The `font-family` declaration every element carries. */
-export const MONO = `font-family: ${MONO_FONT_STACK};`;
+/**
+ * The `font-family` declaration every element carries, WITHOUT its semicolon.
+ *
+ * Declarations are stored unterminated because `./styles.ts` composes them into
+ * an ordered list and puts the separators back — one `; ` between, one `;` at the
+ * end — for both surfaces. A declaration that carried its own terminator would
+ * make the joiner's output depend on which declaration it happened to be, which
+ * is exactly the drift the registry exists to prevent.
+ */
+export const MONO_DECL = `font-family: ${MONO_FONT_STACK}`;
 
 /**
  * The single font size for every email element (HTML). Plain text is monospace
@@ -45,3 +57,15 @@ export const SPACING: Record<Spacing, string> = {
   tight: "0 0 4px 0",
   none: "0",
 };
+
+/**
+ * A CTA button's inner padding.
+ *
+ * It lands in three places that MUST agree, or Outlook double-pads and the box
+ * collapses: `./styles.ts`'s `cta-anchor` (linked — the padding is what makes the
+ * whole box clickable), its `cta-cell-code` (unlinked), and `./cta.ts`'s
+ * `MSO_CTA_STYLE` (Outlook, which cannot do the first). It sits here rather than
+ * in `./cta.ts` because `./styles.ts` needs it and `./cta.ts` imports FROM
+ * `./styles.ts` — a constant shared by both belongs below both.
+ */
+export const CTA_PAD = "16px 24px";

package/src/notifications/renderers/email/cta.ts

@@ -7,19 +7,48 @@
  * (`./chat`), which place it at different margins.
  *
  * INVARIANTS:
- * - Pure, and byte-identical to what the deleted `src/email/render/blocks` emits.
+ * - Pure. The markup is CLASS-ONLY (ADR-CONTRACTS-089) — what ships is whatever
+ *   the surface's shell makes of it. `../../__tests__/render-snapshot.test.ts`
+ *   locks the html surface's bytes.
  * - `href` absent means the label IS the payload (an OTP code): the button must
  *   not become a link, and plain text must not print a URL under it.
  */
 
 import type { CallToAction } from "../../content";
 
-import { FONT_SIZE, MONO } from "./constants";
+import { CTA_PAD, type Spacing } from "./constants";
 import { escapeHtml } from "./escape-html";
+import { styleClass } from "./styles";
 
 /** Padding columns on each side of the `>> LABEL <<` line in the ASCII box. */
 const CTA_BOX_PAD = 3;
 
+/**
+ * Outlook's answer to a full-box click target.
+ *
+ * A linked button makes its whole box clickable by moving the padding onto the
+ * `<a>` and setting `display: block`. Outlook's Word engine supports `display:
+ * none` and no other value, so the anchor stays inline there, and Word drops
+ * vertical padding on an inline element — the button would render cramped against
+ * its border. This MSO-only block puts the padding back on the cell and zeroes it
+ * on the anchor, so Outlook renders exactly today's padded, text-clickable box
+ * while every honouring client gets the full-box target.
+ *
+ * Lives here rather than in `./styles.ts`: that registry holds the declarations an
+ * ELEMENT makes, and `htmlShell` spends them inline. This is a `<head>` rule aimed
+ * at one engine, and `./shells.ts` composes it behind an `<!--[if mso]>` gate the
+ * same way it composes the colour blocks. It rides on `.cs-cta`, a ROLE class, so
+ * it survives `inlineStyles` untouched — and its `!important` still beats the
+ * inline padding, exactly as before.
+ *
+ * The AMP surface never composes it: Outlook's Word engine is not an AMP client,
+ * `display: block` works natively in Gmail/Yahoo/Mail.ru, and AMP forbids both
+ * conditional comments and `!important`. Nothing has to strip it — it lives in the
+ * `<head>`, not in an `EmailLine`.
+ */
+export const MSO_CTA_STYLE = `.cs-cta td { padding: ${CTA_PAD} !important; }
+.cs-cta a { padding: 0 !important; }`;
+
 /** `>> LABEL <<` ASCII box (`*` corners): 3 lines, sized to the label. */
 function asciiCtaBox(label: string): string {
   const pad = " ".repeat(CTA_BOX_PAD);
@@ -35,24 +64,45 @@ function asciiCtaBox(label: string): string {
  */
 export function ctaButton(
   cta: CallToAction,
-  margin: string,
+  margin: Spacing,
 ): { html: string; text: string } {
   const { label, href } = cta;
 
-  const tableStyle = `display: inline-block; border: 1px solid #666; border-radius: 2px; margin: ${margin}; max-width: 220px;`;
-  const tdStyle = `padding: 16px 24px; text-align: center; ${MONO} font-size: ${FONT_SIZE};`;
+  // The hover hook goes on ONLY when there is somewhere to go. An OTP code is a
+  // box with no link in it, and lighting it up under the pointer would promise a
+  // click that does not exist. On the html surface `:hover` is opportunistic — see
+  // `./colors.ts`'s `hoverStyle` — so it adds a state in Apple Mail and changes
+  // nothing in Gmail; on the AMP surface it simply works, which is what that
+  // surface is FOR (ADR-CONTRACTS-089).
+  const boxClass = href
+    ? styleClass(`cta-box-${margin}`, "cta", "ctaHover")
+    : styleClass(`cta-box-${margin}`, "cta");
+  // A linked button carries its padding on the anchor (below), so the WHOLE box is
+  // the click target; the cell then holds none. An unlinked code is not clickable,
+  // so its padding stays on the cell and the label is a bare `<span>` — today's
+  // box exactly. Outlook ignores the anchor's `display: block` and is corrected by
+  // `MSO_CTA_STYLE`, which puts this same padding back on the cell there.
+  const cellClass = href
+    ? styleClass("cta-cell-linked")
+    : styleClass("cta-cell-code");
 
   // Underline only the label text (not the chevrons/spaces), and only when linked.
   const labelHtml = href
-    ? `<span style="text-decoration: underline;">${escapeHtml(label)}</span>`
+    ? `<span ${styleClass("cta-label")}>${escapeHtml(label)}</span>`
     : escapeHtml(label);
   const chevrons = `&gt;&gt; ${labelHtml} &lt;&lt;`;
+  // Both wear the `link` colour — a call to action looks like one whether or not
+  // it goes anywhere, and the box's edge is already that colour. What separates
+  // them is the UNDERLINE above and the `<a>` itself: an unlinked label is a
+  // `<span>`, so an OTP code is still not clickable and still prints no URL. The
+  // linked anchor fills the box (`display: block` + the padding) so a click
+  // anywhere in it counts.
   const inner = href
-    ? `<a href="${href}" style="color: #0047FF; text-decoration: none;">${chevrons}</a>`
-    : chevrons;
+    ? `<a href="${escapeHtml(href)}" ${styleClass("cta-anchor", "link")}>${chevrons}</a>`
+    : `<span ${styleClass("cta-code", "link")}>${chevrons}</span>`;
 
-  const html = `<table cellpadding="0" cellspacing="0" border="0" style="${tableStyle}">
-  <tr><td style="${tdStyle}">
+  const html = `<table cellpadding="0" cellspacing="0" border="0" ${boxClass}>
+  <tr><td ${cellClass}>
     ${inner}
   </td></tr>
 </table>`;