@email-kit/cli 1.0.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,212 @@
1
+ <!-- Generated from docs/guide/theme.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
2
+
3
+ # Theme and dark mode
4
+
5
+ The theme gives every colour, font, size and radius the components use. Without one, emails use
6
+ email-kit's built-in neutral theme: shadcn/ui's neutral palette, adjusted so it passes the contrast
7
+ checks.
8
+
9
+ Set it in `email-kit.config.ts` under `theme`. If your app uses shadcn/ui, `init` finds its CSS
10
+ file and asks whether to use it, so your emails match your app from the start.
11
+
12
+ ## Options
13
+
14
+ ```ts
15
+ theme: {
16
+ source: "app/globals.css",
17
+ roles: { link: { light: "#1d4ed8", dark: "#93c5fd" } },
18
+ radius: 6,
19
+ layout: { container: 640 },
20
+ typography: {
21
+ stacks: { sans: ["Inter", "Helvetica", "Arial", "sans-serif"] },
22
+ scale: { body: { sizePx: 16, lineHeightPx: 26 } },
23
+ },
24
+ }
25
+ ```
26
+
27
+ | Field | Type | Default | |
28
+ |---|---|---|---|
29
+ | `source` | see [Sources](#sources) | the built-in theme | Where the colours come from |
30
+ | `input` | `{ [modifier]: context }` | each modifier's default | For a DTCG resolver source only: the context of each modifier besides light and dark, such as `{ brand: "acme" }` |
31
+ | `roles` | `{ [role]: colour }` | | Override a [role](#roles) with a CSS colour or a `"{token}"` from the source, for both modes or `{ light, dark }` |
32
+ | `typography.stacks` | `{ sans?, serif?, mono? }` | system stacks | Font families in order, ending in a generic family. The last named family is classic Outlook's fallback |
33
+ | `typography.scale` | `{ [step]: Partial<TypeStyle> }` | see [Type scale](#type-scale) | Override steps of the type scale |
34
+ | `radius` | `number` | the source's `--radius`, else 10 | The base radius in px |
35
+ | `layout.container` | `number` | `600` | The width of the centred container, in px. Keep it within 480–640 (`tokens.container`) |
36
+ | `dark` | `"authored"` or `"none"` | `"authored"` if the source has a dark palette, else `"none"` | Whether the email carries your dark palette |
37
+ | `emit` | `boolean` | `false` | Also write the resolved theme to `<out>/theme.json` |
38
+
39
+ Every colour is converted to 6-digit hex, since email clients don't all read modern colour syntax:
40
+ out-of-gamut colours are mapped into sRGB, and translucent ones are flattened onto the surface they
41
+ sit on.
42
+
43
+ ## Sources
44
+
45
+ **shadcn CSS.** The CSS file `shadcn init` writes:
46
+
47
+ ```ts
48
+ theme: { source: "app/globals.css" }
49
+ ```
50
+
51
+ email-kit reads the variables in `:root` as the light mode and those in `.dark` (or `:root.dark`,
52
+ `html.dark`, `[data-theme="dark"]`) as the dark mode, inside `@layer base` too. `var()`
53
+ references are resolved; `@theme inline` is skipped.
54
+
55
+ **DTCG token files.** One file per mode, in the W3C Design Tokens format:
56
+
57
+ ```ts
58
+ theme: { source: { light: "tokens/light.tokens.json", dark: "tokens/dark.tokens.json" } }
59
+ ```
60
+
61
+ Colour tokens map to the same names as shadcn's variables, with the leading `color` group dropped:
62
+ `color.primary.foreground` is `primary-foreground`. A group's own value goes under `$root`:
63
+
64
+ ```json
65
+ {
66
+ "color": {
67
+ "$type": "color",
68
+ "background": { "$value": "#ffffff" },
69
+ "foreground": { "$value": "#18181b" },
70
+ "primary": {
71
+ "$root": { "$value": "#1e3a8a" },
72
+ "foreground": { "$value": "#ffffff" }
73
+ }
74
+ },
75
+ "radius": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } }
76
+ }
77
+ ```
78
+
79
+ Aliases (`"{color.primary}"`) are resolved, and a colour object's `hex` wins over conversion. A
80
+ dimension token named `radius` sets the base radius.
81
+
82
+ **A DTCG resolver.** A `.resolver.json` file:
83
+
84
+ ```ts
85
+ theme: { source: "tokens/theme.resolver.json", input: { brand: "acme" } }
86
+ ```
87
+
88
+ The modifier whose contexts include `light` and `dark` gives the two modes (if several do, name the
89
+ colour-scheme one `theme` or `mode`). `input` picks the context of every other modifier. The theme
90
+ checks run on every other combination of contexts too.
91
+
92
+ **The variables themselves**, by their shadcn names. `dark` is optional:
93
+
94
+ ```ts
95
+ theme: {
96
+ source: {
97
+ light: {
98
+ background: "#ffffff",
99
+ foreground: "#18181b",
100
+ primary: "#1e3a8a",
101
+ "primary-foreground": "#ffffff",
102
+ secondary: "#f5f5f5",
103
+ "secondary-foreground": "#18181b",
104
+ muted: "#f5f5f5",
105
+ "muted-foreground": "#52525b",
106
+ destructive: "#991b1b",
107
+ border: "#71717a",
108
+ },
109
+ radius: "0.5rem",
110
+ },
111
+ }
112
+ ```
113
+
114
+ A source error fails the compile with [`invalid-theme`](../reference/errors.md#invalid-theme) or
115
+ [`invalid-colour`](../reference/errors.md#invalid-colour).
116
+
117
+ ## Roles
118
+
119
+ Components never use raw colours; they use roles, which email-kit resolves from the source's
120
+ variables for each mode. Each role takes the first of its variables that the source has. A role
121
+ with none of them uses email-kit's default where there is one, and otherwise fails with
122
+ [`unresolved-role`](../reference/errors.md#unresolved-role) until you add the variable or set the role in
123
+ `roles`.
124
+
125
+ | Role | From |
126
+ |---|---|
127
+ | `pageGround` | Light: `muted`, `accent`. Dark: `background` |
128
+ | `canvas`, `card` | `card`, `background` |
129
+ | `muted` | `muted` |
130
+ | `codeSurface` | `muted`, `secondary` |
131
+ | `inverse` | `foreground` |
132
+ | `ink`, `strongBorder` | `card-foreground`, `foreground` |
133
+ | `mutedInk`, `subtleInk` | `muted-foreground`, adjusted to pass contrast unless you override it |
134
+ | `inverseInk` | `background` |
135
+ | `link`, `brand`, `brandInk` | `primary` |
136
+ | `onBrand` | `primary-foreground`, else whichever of `ink` and `inverseInk` reads better on `brand` |
137
+ | `hairline`, `divider` | `border` |
138
+ | `action.primary.fill`, `.border` | `primary` |
139
+ | `action.primary.label` | `primary-foreground` |
140
+ | `action.secondary.fill` | `secondary` |
141
+ | `action.secondary.label` | `secondary-foreground` |
142
+ | `action.secondary.border` | `border` |
143
+ | `action.destructive.fill`, `.border` | `destructive` |
144
+ | `action.destructive.label` | `destructive-foreground`, else computed |
145
+ | `status.<tone>.fill` | `info`, `success`, `warning` or `destructive` (for `error`), else a default |
146
+ | `status.<tone>.onFill` | the matching `-foreground`, else computed |
147
+ | `status.<tone>.ink`, `.surface`, `.border` | email-kit's defaults, or `roles` |
148
+
149
+ `<tone>` is `info`, `success`, `warning` or `error`. `email-kit tokens` prints every role in both
150
+ modes with its contrast ratio:
151
+
152
+ ```sh
153
+ npx email-kit tokens
154
+ ```
155
+
156
+ ## Type scale
157
+
158
+ | Step | Default (size/line height, px) | Used by |
159
+ |---|---|---|
160
+ | `display` | 36/44, bold | |
161
+ | `h1`, `h2`, `h3` | 28/36, 22/30, 18/26, bold | `Heading` |
162
+ | `lead` | 18/28 | `Text size="lead"` |
163
+ | `body` | 16/24 | `Text`, `ListItem`, `KeyValue` |
164
+ | `bodySm` | 14/22 | `Text size="bodySm"`, tables |
165
+ | `caption` | 14/20 | `Text size="caption"`, `KeyValue` labels |
166
+ | `footer` | 14/20 | `Footer` |
167
+ | `button` | 16/24, bold | `Button` |
168
+ | `code` | 14/20, monospaced | |
169
+ | `otp` | 28/36, bold, monospaced, 6px letter-spacing | `OtpCode` |
170
+ | `wordmark` | 20/28, bold | |
171
+
172
+ A step override takes any of `stack` (`"sans"`, `"serif"` or `"mono"`), `sizePx`, `lineHeightPx`,
173
+ `weight` (400 or 700) and `letterSpacingPx`.
174
+
175
+ ## Dark mode
176
+
177
+ With `dark: "authored"`, each email carries your dark palette: `@media (prefers-color-scheme:
178
+ dark)` rules for every colour it uses, the `[data-ogsc]` and `[data-ogsb]` selectors Outlook.com
179
+ reads, and a `color-scheme: light dark` declaration. With `"none"`, or a source without a dark
180
+ mode, the email declares no dark support and clients that darken emails do it their own way.
181
+
182
+ ## See the resolved theme
183
+
184
+ `email-kit tokens` prints every colour role in light and dark, with its contrast ratio against the
185
+ surface it sits on, then the theme's findings:
186
+
187
+ ```sh
188
+ npx email-kit tokens
189
+ ```
190
+
191
+ ```
192
+ Theme: email-kit default (shadcn neutral, adjusted for email) (dark: authored)
193
+
194
+ Role Light Dark Contrast
195
+ pageGround #f5f5f5 #0a0a0a
196
+ canvas #ffffff #171717 1.09 / 1.10 on pageGround
197
+ ink #0a0a0a #fafafa 19.80 / 17.18 on canvas
198
+ mutedInk #707070 #a1a1a1 4.95 / 6.94 on canvas
199
+ link #171717 #e5e5e5 17.93 / 14.23 on canvas
200
+ …
201
+ ```
202
+
203
+ It exits 1 when a `tokens.*` check fails at error level. `email-kit check` runs the same theme
204
+ checks: text and link contrast (WCAG AA), button colours and sizes, Gmail's dark-mode handling of
205
+ light fills, font stacks and the container width. See the `tokens.*` and `dark.*` entries in the
206
+ [checks reference](../reference/checks.md).
207
+
208
+ ## Using theme values in your own components
209
+
210
+ Your own components use roles too, never literal colours: `role("muted")` writes the light value
211
+ inline and tags the element so the dark value applies in dark mode. See
212
+ [Your own components](components.md#your-own-components).