first commit

docs/communication/emails/email-templates/src/theme/theme.md

@@ -0,0 +1,89 @@
+# theme
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Provides the theme tokens consumed by every email component — colours,
+typography, spacing, branding, border-radius, and max-width. Themes are
+immutable plain objects: `createTheme` returns a fresh object every call
+and never mutates the shipped `defaultTheme`, so the module is safe to
+import in cross-tenant contexts where two consumers compose distinct
+themes side-by-side.
+
+The default palette is `#2563eb` primary (Tailwind blue-600), a slate
+secondary, and a 600 px max-width — sane email-client defaults that
+render correctly in Gmail, Apple Mail, Outlook 2016+, and the major web
+clients without further customisation.
+
+## Features
+
+- `defaultTheme`: frozen default `EmailTheme` instance.
+- `createTheme(options?)`: deep-merges `options` into `defaultTheme`,
+  returning a new object.
+- `mergeThemes(base, override)`: shallow-merges each section into `base`.
+- Every section is independently overridable — partial colour overrides
+  leave other colours intact.
+
+## Usage: Basic
+
+```ts
+import { createTheme } from "@suaveplan/email-templates/theme";
+
+const theme = createTheme({
+  colors: { primary: "#ff6600" },
+  branding: { companyName: "Acme Corp" },
+});
+```
+
+## Usage: Advanced
+
+Compose a per-locale theme by layering region-specific tokens onto a base:
+
+```ts
+import { createTheme, mergeThemes } from "@suaveplan/email-templates/theme";
+
+const base = createTheme({
+  branding: { companyName: "Acme" },
+  typography: {
+    fontFamily: "'Inter', sans-serif",
+  },
+});
+
+const jaTheme = mergeThemes(base, {
+  typography: { fontFamily: "'Noto Sans JP', sans-serif" },
+});
+```
+
+`mergeThemes` differs from `createTheme` in that it merges into the
+explicitly-supplied `base` (which may itself differ from `defaultTheme`)
+— useful when a multi-tenant pipeline pre-builds a per-tenant base and
+then layers a per-locale override on top.
+
+## API Reference
+
+| Symbol         | Kind     | Description                                                |
+| -------------- | -------- | ---------------------------------------------------------- |
+| `defaultTheme` | const    | The shipped default `EmailTheme`.                          |
+| `createTheme`  | function | `(options?) => EmailTheme` — overrides applied to default. |
+| `mergeThemes`  | function | `(base, override) => EmailTheme`.                          |
+
+Types: `EmailTheme`, `EmailThemeColors`, `EmailThemeTypography`,
+`EmailThemeSpacing`, `EmailThemeBranding`, `EmailThemeOptions`.
+
+## Implementation Notes
+
+Token defaults are declared as module-local `const … as const`
+expressions so they cannot be re-bound; the exported `defaultTheme` is a
+spread of those tokens. The exported value is intentionally **not**
+`Object.freeze`'d — TypeScript's `readonly` already prevents accidental
+re-assignment at the type level, and freezing would interact badly with
+serialise / hydrate flows in downstream tests.
+
+Spread-merging means deep nested fields cannot be partially overridden
+within the same `createTheme` call (e.g. you cannot override one branding
+field without losing the others) — each section is treated as a single
+unit. That matches upstream behaviour exactly; consumers who need a
+deeper merge can compose two `createTheme` calls with `mergeThemes`.