@email-kit/cli 1.0.0 → 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.
- package/README.md +124 -17
- package/dist/cli.js +654 -40
- package/dist/docs/guide/checks-and-ci.md +158 -0
- package/dist/docs/guide/components.md +426 -0
- package/dist/docs/guide/formatting.md +77 -0
- package/dist/docs/guide/messages.md +147 -0
- package/dist/docs/guide/sending.md +242 -0
- package/dist/docs/guide/templates.md +269 -0
- package/dist/docs/guide/theme.md +212 -0
- package/dist/docs/reference/checks.md +876 -0
- package/dist/docs/reference/cli.md +214 -0
- package/dist/docs/reference/configuration.md +115 -0
- package/dist/docs/reference/errors.md +264 -0
- package/dist/docs/reference/mustache-core.md +340 -0
- package/dist/skill/email-kit/SKILL.md +326 -0
- package/package.json +6 -6
|
@@ -0,0 +1,876 @@
|
|
|
1
|
+
<!-- Generated from docs/reference/checks.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
|
|
2
|
+
|
|
3
|
+
# Checks
|
|
4
|
+
|
|
5
|
+
<!-- Generated from packages/cli/src/checks: run `pnpm --filter @email-kit/cli test -u` after changing a check. -->
|
|
6
|
+
|
|
7
|
+
`email-kit check` runs these over the compiled emails and the theme. Change a level per project
|
|
8
|
+
with a reason a reviewer will read:
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
checks: { "img.fluid-width": { level: "off", reason: "Hero images are fixed width by design" } }
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Team checks
|
|
15
|
+
|
|
16
|
+
Add your own rules with `defineCheck()` in `customChecks`. They run with the catalogue, take
|
|
17
|
+
levels from `checks`, and show in every reporter. Use a family of your own for the id.
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { defineCheck, defineConfig } from "@email-kit/core"
|
|
21
|
+
|
|
22
|
+
const helpLink = defineCheck({
|
|
23
|
+
id: "acme.help-link",
|
|
24
|
+
level: "warn",
|
|
25
|
+
rule: "Every email links to the help centre.",
|
|
26
|
+
fix: "Add the footer's help link.",
|
|
27
|
+
run({ emails }, report) {
|
|
28
|
+
for (const email of emails) {
|
|
29
|
+
const hrefs = email.elements("a").map((a) => a.attributes.href ?? "")
|
|
30
|
+
if (!hrefs.some((href) => href.startsWith("https://help.acme.com"))) {
|
|
31
|
+
report({ email, message: "No link to the help centre" })
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
},
|
|
35
|
+
})
|
|
36
|
+
|
|
37
|
+
export default defineConfig({ customChecks: [helpLink] })
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Each email has `template`, `locale`, `subject`, `preheader`, `html`, `text` and
|
|
41
|
+
`elements(name?)`. Set `on: "render"` to check the renders of every fixture and generated
|
|
42
|
+
variant instead of the compiled templates (each render then has `fixture`), or `both`.
|
|
43
|
+
|
|
44
|
+
## Theme and tokens
|
|
45
|
+
|
|
46
|
+
### tokens.action-contrast
|
|
47
|
+
**Default:** error
|
|
48
|
+
|
|
49
|
+
**Rule:** Action label/fill ≥ 4.5; fill/canvas ≥ 3, or a border is set.
|
|
50
|
+
|
|
51
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
52
|
+
|
|
53
|
+
### tokens.brand-ink
|
|
54
|
+
**Default:** error
|
|
55
|
+
|
|
56
|
+
**Rule:** `brandInk` on the canvas ≥ 4.5.
|
|
57
|
+
|
|
58
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
59
|
+
|
|
60
|
+
### tokens.button-height
|
|
61
|
+
**Default:** error
|
|
62
|
+
|
|
63
|
+
**Rule:** Button minimum height ≥ 44 px (`sm` only for non-primary actions).
|
|
64
|
+
|
|
65
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
66
|
+
|
|
67
|
+
### tokens.container
|
|
68
|
+
**Default:** warning
|
|
69
|
+
|
|
70
|
+
**Rule:** The container width is within 480–640 px.
|
|
71
|
+
|
|
72
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
73
|
+
|
|
74
|
+
### tokens.contrast
|
|
75
|
+
**Default:** error
|
|
76
|
+
|
|
77
|
+
**Rule:** Text pairs ≥ 4.5 (large text and non-text ≥ 3) in light and authored dark.
|
|
78
|
+
|
|
79
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
80
|
+
|
|
81
|
+
### tokens.dark-ground
|
|
82
|
+
**Default:** warning
|
|
83
|
+
|
|
84
|
+
**Rule:** The authored dark ground isn't `#000000` (aim for `#0a0a0a`–`#1a1a1a`).
|
|
85
|
+
|
|
86
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
87
|
+
|
|
88
|
+
### tokens.font-stack
|
|
89
|
+
**Default:** error
|
|
90
|
+
|
|
91
|
+
**Rule:** Every stack ends in a generic family and has an MSO fallback.
|
|
92
|
+
|
|
93
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
94
|
+
|
|
95
|
+
### tokens.gamut
|
|
96
|
+
**Default:** note
|
|
97
|
+
|
|
98
|
+
**Rule:** Out-of-gamut colours are mapped into sRGB; reports the source and the hex.
|
|
99
|
+
|
|
100
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
101
|
+
|
|
102
|
+
### tokens.gmail-fill
|
|
103
|
+
**Default:** note
|
|
104
|
+
|
|
105
|
+
**Rule:** Action fill YIQ ≤ 205, so Gmail Android leaves it unchanged.
|
|
106
|
+
|
|
107
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
108
|
+
|
|
109
|
+
### tokens.letter-spacing
|
|
110
|
+
**Default:** warning
|
|
111
|
+
|
|
112
|
+
**Rule:** Letter-spacing is in px.
|
|
113
|
+
|
|
114
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
115
|
+
|
|
116
|
+
### tokens.light-ground
|
|
117
|
+
**Default:** note
|
|
118
|
+
|
|
119
|
+
**Rule:** The light ground isn't `#ffffff`.
|
|
120
|
+
|
|
121
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
122
|
+
|
|
123
|
+
### tokens.link-contrast
|
|
124
|
+
**Default:** error
|
|
125
|
+
|
|
126
|
+
**Rule:** The link colour ≥ 4.5 against the canvas and the page ground in each mode.
|
|
127
|
+
|
|
128
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
129
|
+
|
|
130
|
+
### tokens.midtone
|
|
131
|
+
**Default:** warning
|
|
132
|
+
|
|
133
|
+
**Rule:** Grounds behind text and meaningful borders aren't in L* 40–65.
|
|
134
|
+
|
|
135
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
136
|
+
|
|
137
|
+
### tokens.min-size
|
|
138
|
+
**Default:** error
|
|
139
|
+
|
|
140
|
+
**Rule:** Type sizes ≥ 14 px (a warning), never < 13 px (an error).
|
|
141
|
+
|
|
142
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
143
|
+
|
|
144
|
+
### tokens.offwhite-tint
|
|
145
|
+
**Default:** warning
|
|
146
|
+
|
|
147
|
+
**Rule:** No near-white with a 1–3 unit channel offset.
|
|
148
|
+
|
|
149
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
150
|
+
|
|
151
|
+
### tokens.radius
|
|
152
|
+
**Default:** error
|
|
153
|
+
|
|
154
|
+
**Rule:** Radius values parse to single px values.
|
|
155
|
+
|
|
156
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
157
|
+
|
|
158
|
+
### tokens.weights
|
|
159
|
+
**Default:** warning
|
|
160
|
+
|
|
161
|
+
**Rule:** Font weights are 400 or 700.
|
|
162
|
+
|
|
163
|
+
**Fix:** Adjust the colour or the role in the theme; `email-kit tokens` lists every pair.
|
|
164
|
+
|
|
165
|
+
## Sources
|
|
166
|
+
|
|
167
|
+
### source.id-grammar
|
|
168
|
+
**Default:** error
|
|
169
|
+
|
|
170
|
+
**Rule:** Template ids are lowercase words joined by hyphens, unique, and the name of the template's folder. Enforced when compiling: the compile fails with `invalid-id` or `id-mismatch`, which `email-kit check` reports as this check.
|
|
171
|
+
|
|
172
|
+
**Fix:** Rename the template id, like "password-reset", and its folder to match.
|
|
173
|
+
|
|
174
|
+
### source.fixture-valid
|
|
175
|
+
**Default:** error
|
|
176
|
+
|
|
177
|
+
**Rule:** Every fixture validates against the template's schema. Enforced when compiling: the compile fails with `invalid-fixture`, which `email-kit check` reports as this check.
|
|
178
|
+
|
|
179
|
+
**Fix:** Correct the fixture at the path in the message, or the schema.
|
|
180
|
+
|
|
181
|
+
### source.schema-portable
|
|
182
|
+
**Default:** error
|
|
183
|
+
|
|
184
|
+
**Rule:** The schema stays within the portable JSON Schema subset. Enforced when compiling: the compile fails with `schema-not-portable` or `unsupported-schema` or `missing-converter`, which `email-kit check` reports as this check.
|
|
185
|
+
|
|
186
|
+
**Fix:** Use the types and constraints every target language can check; the message names the field.
|
|
187
|
+
|
|
188
|
+
### source.no-literal-colour
|
|
189
|
+
**Default:** error
|
|
190
|
+
|
|
191
|
+
**Rule:** No literal colours in the styles and colour attributes of templates and user components.
|
|
192
|
+
|
|
193
|
+
**Fix:** Use a theme role: `style={{ color: role("mutedInk") }}`. Roles get their dark-mode rules and contrast checks; literals get neither.
|
|
194
|
+
|
|
195
|
+
### source.no-font-family
|
|
196
|
+
**Default:** error
|
|
197
|
+
|
|
198
|
+
**Rule:** No `font-family` in templates or user components.
|
|
199
|
+
|
|
200
|
+
**Fix:** Font stacks come from the theme (`theme.typography.stacks`), with the fallback classic Outlook needs; use Text, Heading or the font() helper.
|
|
201
|
+
|
|
202
|
+
### source.no-font-size
|
|
203
|
+
**Default:** error
|
|
204
|
+
|
|
205
|
+
**Rule:** No literal `font-size` in templates or user components, except 0 or 1px on spacer and divider cells.
|
|
206
|
+
|
|
207
|
+
**Fix:** Sizes come from the type scale: use Text or Heading with a size, or the font() helper.
|
|
208
|
+
|
|
209
|
+
### source.jsx-pragma
|
|
210
|
+
**Default:** warning
|
|
211
|
+
|
|
212
|
+
**Rule:** Templates and user components with JSX start with `/** @jsxImportSource @email-kit/core */`, unless their tsconfig sets `"jsxImportSource": "@email-kit/core"`.
|
|
213
|
+
|
|
214
|
+
**Fix:** Add `/** @jsxImportSource @email-kit/core */` as the file's first line. The compile is right either way; without it, TypeScript and your editor check the file against another framework's JSX types.
|
|
215
|
+
|
|
216
|
+
### source.fixture-exists
|
|
217
|
+
**Default:** error
|
|
218
|
+
|
|
219
|
+
**Rule:** Every template has at least one fixture.
|
|
220
|
+
|
|
221
|
+
**Fix:** Add sample data under `fixtures` in defineEmail(): the checks render it, and so will the preview studio.
|
|
222
|
+
|
|
223
|
+
## Document
|
|
224
|
+
|
|
225
|
+
### html.doctype
|
|
226
|
+
**Default:** error
|
|
227
|
+
|
|
228
|
+
**Rule:** The email starts with `<!doctype html>`.
|
|
229
|
+
|
|
230
|
+
**Fix:** Start the document with `<!DOCTYPE html>`; without it, clients render in quirks mode.
|
|
231
|
+
|
|
232
|
+
### html.lang-dir
|
|
233
|
+
**Default:** error
|
|
234
|
+
|
|
235
|
+
**Rule:** `lang` and `dir` on `<html>` and the wrapper, `xml:lang` on the body, matching the locale.
|
|
236
|
+
|
|
237
|
+
**Fix:** Render through email-kit's document skeleton, which sets them from the locale.
|
|
238
|
+
|
|
239
|
+
### html.title
|
|
240
|
+
**Default:** warning
|
|
241
|
+
|
|
242
|
+
**Rule:** `<title>` is present and equals the subject.
|
|
243
|
+
|
|
244
|
+
**Fix:** Screen readers and some clients show the title; keep it the subject.
|
|
245
|
+
|
|
246
|
+
### html.xmlns
|
|
247
|
+
**Default:** error
|
|
248
|
+
|
|
249
|
+
**Rule:** Office (`o:`) and VML (`v:`) elements need their namespace on `<html>`.
|
|
250
|
+
|
|
251
|
+
**Fix:** Declare xmlns:o="urn:schemas-microsoft-com:office:office" or xmlns:v="urn:schemas-microsoft-com:vml".
|
|
252
|
+
|
|
253
|
+
### html.no-forms-embeds
|
|
254
|
+
**Default:** error
|
|
255
|
+
|
|
256
|
+
**Rule:** No form, input, script, iframe, object, embed, video or svg elements. Also runs on the renders, for values that come from data.
|
|
257
|
+
|
|
258
|
+
**Fix:** Clients strip them or mark the email as suspicious; link to a web page instead.
|
|
259
|
+
|
|
260
|
+
### html.no-body-style
|
|
261
|
+
**Default:** error
|
|
262
|
+
|
|
263
|
+
**Rule:** No `<style>` inside `<body>`.
|
|
264
|
+
|
|
265
|
+
**Fix:** Put styles inline or in the head; clients drop body styles.
|
|
266
|
+
|
|
267
|
+
### html.data-detectors
|
|
268
|
+
**Default:** warning
|
|
269
|
+
|
|
270
|
+
**Rule:** The Apple data-detector reset is present.
|
|
271
|
+
|
|
272
|
+
**Fix:** Keep the `a[x-apple-data-detectors]` rule email-kit writes in the head.
|
|
273
|
+
|
|
274
|
+
### html.mso-font
|
|
275
|
+
**Default:** error
|
|
276
|
+
|
|
277
|
+
**Rule:** The MSO font override is present. Runs when classic Outlook is a target.
|
|
278
|
+
|
|
279
|
+
**Fix:** Keep the `[if mso]` style that sets a font-family; without it Word falls back to Times New Roman.
|
|
280
|
+
|
|
281
|
+
### html.dpi-noscript
|
|
282
|
+
**Default:** error
|
|
283
|
+
|
|
284
|
+
**Rule:** PixelsPerInch XML inside an MSO conditional and `<noscript>`. Runs when classic Outlook is a target.
|
|
285
|
+
|
|
286
|
+
**Fix:** Keep the OfficeDocumentSettings block email-kit writes; it stops Word scaling on high-DPI screens.
|
|
287
|
+
|
|
288
|
+
### html.wrapper-aria
|
|
289
|
+
**Default:** warning
|
|
290
|
+
|
|
291
|
+
**Rule:** The wrapper has role="article" and an aria-label; aria-roledescription only when localised.
|
|
292
|
+
|
|
293
|
+
**Fix:** Keep email-kit's document wrapper: screen readers announce the email by its label.
|
|
294
|
+
|
|
295
|
+
### html.meta
|
|
296
|
+
**Default:** error
|
|
297
|
+
|
|
298
|
+
**Rule:** The head starts with the charset meta and has viewport, x-apple-disable-message-reformatting and format-detection.
|
|
299
|
+
|
|
300
|
+
**Fix:** Keep email-kit's document head: these stop clients rescaling the email and turning numbers into links.
|
|
301
|
+
|
|
302
|
+
### html.body-bare
|
|
303
|
+
**Default:** warning
|
|
304
|
+
|
|
305
|
+
**Rule:** <body> has no presentational attributes or styles beyond margin and padding 0.
|
|
306
|
+
|
|
307
|
+
**Fix:** Gmail, Outlook on the web and Yahoo replace <body>: put backgrounds and spacing on the wrapper.
|
|
308
|
+
|
|
309
|
+
### html.no-external
|
|
310
|
+
**Default:** error
|
|
311
|
+
|
|
312
|
+
**Rule:** No external stylesheets or @import.
|
|
313
|
+
|
|
314
|
+
**Fix:** Most clients block them, and they add a tracking request: email-kit writes styles inline and in the head.
|
|
315
|
+
|
|
316
|
+
### html.no-svg
|
|
317
|
+
**Default:** error
|
|
318
|
+
|
|
319
|
+
**Rule:** No inline <svg> and no SVG references.
|
|
320
|
+
|
|
321
|
+
**Fix:** Use a PNG: SVG shows blank in Outlook on the web and new Outlook, and Gmail rasterises it.
|
|
322
|
+
|
|
323
|
+
### html.no-comments
|
|
324
|
+
**Default:** error
|
|
325
|
+
|
|
326
|
+
**Rule:** No HTML comments longer than 120 characters, except MSO conditionals.
|
|
327
|
+
|
|
328
|
+
**Fix:** Remove the comment: it ships to every reader, counts toward Gmail's clip, and may leak internal notes.
|
|
329
|
+
|
|
330
|
+
### html.no-unresolved
|
|
331
|
+
**Default:** error
|
|
332
|
+
|
|
333
|
+
**Rule:** No leftover markers, and every placeholder names a field of the schema.
|
|
334
|
+
|
|
335
|
+
**Fix:** A placeholder that names no field renders empty: check the template against its schema.
|
|
336
|
+
|
|
337
|
+
### html.hidden-text
|
|
338
|
+
**Default:** warning
|
|
339
|
+
|
|
340
|
+
**Rule:** Hidden styling is used only on the preheader.
|
|
341
|
+
|
|
342
|
+
**Fix:** Hidden text in the body looks like spam to filters and confuses screen readers: remove it or show it.
|
|
343
|
+
|
|
344
|
+
## Layout
|
|
345
|
+
|
|
346
|
+
### layout.ghost-table
|
|
347
|
+
**Default:** error
|
|
348
|
+
|
|
349
|
+
**Rule:** Each `max-width` container sits inside an MSO ghost table of the same px width. Runs when classic Outlook is a target.
|
|
350
|
+
|
|
351
|
+
**Fix:** Classic Outlook ignores max-width and stretches the content across the reading pane: wrap the container in `<!--[if mso]><table width="N">…<![endif]-->`, as email-kit's page shell does.
|
|
352
|
+
|
|
353
|
+
## CSS
|
|
354
|
+
|
|
355
|
+
### css.no-double-brace
|
|
356
|
+
**Default:** error
|
|
357
|
+
|
|
358
|
+
**Rule:** No `}}` in CSS.
|
|
359
|
+
|
|
360
|
+
**Fix:** Separate closing braces with a space or a newline: Outlook on the web and the Outlook apps drop all CSS after `}}`.
|
|
361
|
+
|
|
362
|
+
### css.important-lowercase
|
|
363
|
+
**Default:** error
|
|
364
|
+
|
|
365
|
+
**Rule:** `!important` is lowercase with a space before it, and never inline.
|
|
366
|
+
|
|
367
|
+
**Fix:** Write ` !important`; Gmail drops the whole <style> block for `!IMPORTANT`. Inline styles win without it.
|
|
368
|
+
|
|
369
|
+
### css.no-nesting
|
|
370
|
+
**Default:** error
|
|
371
|
+
|
|
372
|
+
**Rule:** No nested rules, and no at-rule inside an at-rule.
|
|
373
|
+
|
|
374
|
+
**Fix:** Flatten the CSS: Gmail drops the block, Yahoo applies nested properties to the parent.
|
|
375
|
+
|
|
376
|
+
### css.no-modern-colour
|
|
377
|
+
**Default:** error
|
|
378
|
+
|
|
379
|
+
**Rule:** No oklch(), oklab(), lch(), lab(), color-mix(), color(), light-dark() or hsl(), and no space-separated rgb().
|
|
380
|
+
|
|
381
|
+
**Fix:** Use #rrggbb: Gmail drops the whole <style> block for modern colour syntax. Theme colours are converted for you.
|
|
382
|
+
|
|
383
|
+
### css.no-custom-props
|
|
384
|
+
**Default:** error
|
|
385
|
+
|
|
386
|
+
**Rule:** No custom properties (`--x:`) or `var()`.
|
|
387
|
+
|
|
388
|
+
**Fix:** Most clients don't support them; email-kit writes resolved values from the theme.
|
|
389
|
+
|
|
390
|
+
### css.style-size
|
|
391
|
+
**Default:** error
|
|
392
|
+
|
|
393
|
+
**Rule:** All `<style>` blocks together stay under 16,384 bytes (a warning from 12 KB).
|
|
394
|
+
|
|
395
|
+
**Fix:** Gmail ignores styles past about 16 KB. Move rules inline or drop unused ones.
|
|
396
|
+
|
|
397
|
+
### css.colour-hex
|
|
398
|
+
**Default:** error
|
|
399
|
+
|
|
400
|
+
**Rule:** Every colour, in CSS and in attributes, is #rrggbb or transparent.
|
|
401
|
+
|
|
402
|
+
**Fix:** Write six-digit hex: three-digit hex, names and functions break in some clients. Theme roles are hex already.
|
|
403
|
+
|
|
404
|
+
### css.no-alpha
|
|
405
|
+
**Default:** warning
|
|
406
|
+
|
|
407
|
+
**Rule:** No rgba(), hsla(), 8-digit hex or opacity.
|
|
408
|
+
|
|
409
|
+
**Fix:** Clients that ignore alpha show the colour solid or not at all: flatten it against its background (the theme does).
|
|
410
|
+
|
|
411
|
+
### css.banned-layout
|
|
412
|
+
**Default:** error
|
|
413
|
+
|
|
414
|
+
**Rule:** No flex, grid, float, position, calc(), clamp(), min(), max(), :has() or @supports.
|
|
415
|
+
|
|
416
|
+
**Fix:** Classic Outlook and many webmail clients drop these: lay out with tables, as email-kit's components do.
|
|
417
|
+
|
|
418
|
+
### css.media-allowlist
|
|
419
|
+
**Default:** warning
|
|
420
|
+
|
|
421
|
+
**Rule:** Media queries use only width, orientation, resolution and prefers-color-scheme.
|
|
422
|
+
|
|
423
|
+
**Fix:** Other features are unsupported or rewritten by email clients; keep the query to these.
|
|
424
|
+
|
|
425
|
+
### css.inline-parse
|
|
426
|
+
**Default:** error
|
|
427
|
+
|
|
428
|
+
**Rule:** Every inline style parses cleanly.
|
|
429
|
+
|
|
430
|
+
**Fix:** Gmail, Outlook on the web and Office 365 drop a whole style attribute with a stray character: fix the declaration.
|
|
431
|
+
|
|
432
|
+
### css.gradient-fallback
|
|
433
|
+
**Default:** error
|
|
434
|
+
|
|
435
|
+
**Rule:** An element with a background image or gradient also has a solid background colour.
|
|
436
|
+
|
|
437
|
+
**Fix:** Add background-color (or bgcolor): Outlook and images-off show the colour, and text on it stays readable.
|
|
438
|
+
|
|
439
|
+
### css.units
|
|
440
|
+
**Default:** warning
|
|
441
|
+
|
|
442
|
+
**Rule:** No rem, vw or vh in inline styles.
|
|
443
|
+
|
|
444
|
+
**Fix:** Use px: several clients ignore relative units inline.
|
|
445
|
+
|
|
446
|
+
### css.hide-mso
|
|
447
|
+
**Default:** warning
|
|
448
|
+
|
|
449
|
+
**Rule:** display:none outside MSO blocks comes with mso-hide:all.
|
|
450
|
+
|
|
451
|
+
**Fix:** Classic Outlook ignores display:none on some elements: add mso-hide:all.
|
|
452
|
+
|
|
453
|
+
### css.line-height-px
|
|
454
|
+
**Default:** error
|
|
455
|
+
|
|
456
|
+
**Rule:** Text cells set a px line height with mso-line-height-rule:exactly.
|
|
457
|
+
|
|
458
|
+
**Fix:** Use Text, Heading or the font() helper: Word's default line height differs from every other client's.
|
|
459
|
+
|
|
460
|
+
## Images
|
|
461
|
+
|
|
462
|
+
### img.alt
|
|
463
|
+
**Default:** error
|
|
464
|
+
|
|
465
|
+
**Rule:** Every image has `alt`, non-empty when it is linked. Also runs on the renders, for values that come from data.
|
|
466
|
+
|
|
467
|
+
**Fix:** Describe what the image says, name the destination of a linked one, or use alt="" for decoration.
|
|
468
|
+
|
|
469
|
+
### img.dimensions
|
|
470
|
+
**Default:** error
|
|
471
|
+
|
|
472
|
+
**Rule:** Every image has integer `width` and `height` attributes.
|
|
473
|
+
|
|
474
|
+
**Fix:** Word ignores CSS widths on images, and blocked images keep their space only with both attributes.
|
|
475
|
+
|
|
476
|
+
### img.https
|
|
477
|
+
**Default:** error
|
|
478
|
+
|
|
479
|
+
**Rule:** Image URLs are absolute `https:` URLs. Also runs on the renders, for values that come from data.
|
|
480
|
+
|
|
481
|
+
**Fix:** Gmail and Apple fetch images through proxies; relative and http: URLs break or warn.
|
|
482
|
+
|
|
483
|
+
### img.format
|
|
484
|
+
**Default:** error
|
|
485
|
+
|
|
486
|
+
**Rule:** Images are PNG, JPEG or GIF; never SVG or `data:` URIs. Also runs on the renders, for values that come from data.
|
|
487
|
+
|
|
488
|
+
**Fix:** Export a PNG or JPEG: SVG shows blank in Outlook on the web, classic Outlook can't show WebP or AVIF, Gmail drops data: images.
|
|
489
|
+
|
|
490
|
+
### img.fluid-width
|
|
491
|
+
**Default:** warning
|
|
492
|
+
|
|
493
|
+
**Rule:** An image with `max-width:100%` also has `width:100%`.
|
|
494
|
+
|
|
495
|
+
**Fix:** Gmail's Android web client rewrites a lone max-width; give width:100% and max-width in px.
|
|
496
|
+
|
|
497
|
+
## Dark mode
|
|
498
|
+
|
|
499
|
+
### dark.scheme-declared
|
|
500
|
+
**Default:** error
|
|
501
|
+
|
|
502
|
+
**Rule:** Dark CSS is present if, and only if, the color-scheme meta and `:root { color-scheme }` are.
|
|
503
|
+
|
|
504
|
+
**Fix:** Apple Mail applies dark CSS only after both declarations; without dark CSS, declaring them turns unstyled text light.
|
|
505
|
+
|
|
506
|
+
### dark.ogsc-twin
|
|
507
|
+
**Default:** warning
|
|
508
|
+
|
|
509
|
+
**Rule:** Every `prefers-color-scheme` rule has a `[data-ogsc]`/`[data-ogsb]` descendant twin; no `.x[data-og*]`.
|
|
510
|
+
|
|
511
|
+
**Fix:** Outlook.com ignores the media query and matches attribute selectors only in descendant form, `[data-ogsc] .x`.
|
|
512
|
+
|
|
513
|
+
### dark.light-only-css-twin
|
|
514
|
+
**Default:** warning
|
|
515
|
+
|
|
516
|
+
**Rule:** A `light only` meta with a dark palette also has `:root { color-scheme: light dark }`.
|
|
517
|
+
|
|
518
|
+
**Fix:** Apple Mail lets the CSS override the meta, so the authored dark palette still applies there.
|
|
519
|
+
|
|
520
|
+
### dark.no-blend-hack
|
|
521
|
+
**Default:** warning
|
|
522
|
+
|
|
523
|
+
**Rule:** No `u + .body` blend-mode hack.
|
|
524
|
+
|
|
525
|
+
**Fix:** It breaks in current Gmail apps and inverts images; author a dark palette instead.
|
|
526
|
+
|
|
527
|
+
## Accessibility
|
|
528
|
+
|
|
529
|
+
### a11y.layout-table-role
|
|
530
|
+
**Default:** error
|
|
531
|
+
|
|
532
|
+
**Rule:** Layout tables have `role="presentation"` and no `th`, `caption`, `summary` or `scope`.
|
|
533
|
+
|
|
534
|
+
**Fix:** Add role="presentation" to tables used for layout; otherwise screen readers announce rows and columns.
|
|
535
|
+
|
|
536
|
+
### a11y.data-table
|
|
537
|
+
**Default:** error
|
|
538
|
+
|
|
539
|
+
**Rule:** Data tables have `th scope`, a caption or a heading before them, at least 2 × 2 cells, and no presentation role.
|
|
540
|
+
|
|
541
|
+
**Fix:** Use DataTable, which writes all of these.
|
|
542
|
+
|
|
543
|
+
### a11y.one-h1
|
|
544
|
+
**Default:** error
|
|
545
|
+
|
|
546
|
+
**Rule:** Exactly one `h1` (a warning when there is none).
|
|
547
|
+
|
|
548
|
+
**Fix:** Start the email with one Heading (level 1): screen reader users jump to it, and a second one splits the email in two.
|
|
549
|
+
|
|
550
|
+
### a11y.link-text
|
|
551
|
+
**Default:** error
|
|
552
|
+
|
|
553
|
+
**Rule:** No empty links (error) and no generic link text such as "click here" (warning).
|
|
554
|
+
|
|
555
|
+
**Fix:** Say where the link goes ("View your order"): screen reader users list links out of context.
|
|
556
|
+
|
|
557
|
+
### a11y.font-size
|
|
558
|
+
**Default:** error
|
|
559
|
+
|
|
560
|
+
**Rule:** Text is at least 12 px (error), and 14 px or more (warning below).
|
|
561
|
+
|
|
562
|
+
**Fix:** Use a type step from the theme: body is 16 px and the smallest step 14 px.
|
|
563
|
+
|
|
564
|
+
### a11y.viewport
|
|
565
|
+
**Default:** error
|
|
566
|
+
|
|
567
|
+
**Rule:** The viewport meta doesn't block zoom (`user-scalable=no` or `maximum-scale` below 2).
|
|
568
|
+
|
|
569
|
+
**Fix:** Use `width=device-width, initial-scale=1` only: people with low vision zoom to read.
|
|
570
|
+
|
|
571
|
+
## Links
|
|
572
|
+
|
|
573
|
+
### link.dangerous-schemes
|
|
574
|
+
**Default:** error
|
|
575
|
+
|
|
576
|
+
**Rule:** No `javascript:`, `vbscript:`, `data:` or `file:` URLs.
|
|
577
|
+
|
|
578
|
+
**Fix:** Link to an https:// page instead: clients strip these URLs or flag the email as phishing.
|
|
579
|
+
|
|
580
|
+
### link.url-fields
|
|
581
|
+
**Default:** error
|
|
582
|
+
|
|
583
|
+
**Rule:** An `href` or `src` starts with a literal https:// (or mailto:/tel:) URL or a `url` field.
|
|
584
|
+
|
|
585
|
+
**Fix:** Mark the field with `url` in the schema (`z.string().meta(url)`): render() then accepts only https URLs.
|
|
586
|
+
|
|
587
|
+
## Legal
|
|
588
|
+
|
|
589
|
+
### legal.purpose-declared
|
|
590
|
+
**Default:** error
|
|
591
|
+
|
|
592
|
+
**Rule:** Every template declares a purpose: "transactional", "marketing" or "consent-request". Enforced when compiling: the compile fails with `invalid-purpose`, which `email-kit check` reports as this check.
|
|
593
|
+
|
|
594
|
+
**Fix:** Add `purpose` to `defineEmail()`; any promotional content makes it "marketing".
|
|
595
|
+
|
|
596
|
+
### legal.reason
|
|
597
|
+
**Default:** error
|
|
598
|
+
|
|
599
|
+
**Rule:** Every email says why the reader got it ("why you got this"), naming the account or subscription.
|
|
600
|
+
|
|
601
|
+
**Fix:** Add `<Footer reason={t("footer")} …>`, with a line like "You're receiving this because you have an account with Acme."
|
|
602
|
+
|
|
603
|
+
### legal.sender-identity
|
|
604
|
+
**Default:** error
|
|
605
|
+
|
|
606
|
+
**Rule:** Every email names who sends it: the legal name or brand.
|
|
607
|
+
|
|
608
|
+
**Fix:** Add `<Footer sender={sender.legalName} …>`, with `legalName` (or `productName`) set in the config's `sender`.
|
|
609
|
+
|
|
610
|
+
### legal.postal-address
|
|
611
|
+
**Default:** error
|
|
612
|
+
|
|
613
|
+
**Rule:** Marketing and consent-request emails show the sender's postal address.
|
|
614
|
+
|
|
615
|
+
**Fix:** Pass `address={sender.postalAddress}` to `Footer`, with `postalAddress` set in the config's `sender`.
|
|
616
|
+
|
|
617
|
+
## Internationalisation
|
|
618
|
+
|
|
619
|
+
### i18n.missing-keys
|
|
620
|
+
**Default:** error
|
|
621
|
+
|
|
622
|
+
**Rule:** Every locale has every message key a template uses. Enforced when compiling: the compile fails with `missing-message`, which `email-kit check` reports as this check.
|
|
623
|
+
|
|
624
|
+
**Fix:** Add the key to the locale's messages file the message names.
|
|
625
|
+
|
|
626
|
+
### i18n.plural-categories
|
|
627
|
+
**Default:** error
|
|
628
|
+
|
|
629
|
+
**Rule:** Plural messages cover every CLDR category of the locale. Enforced when compiling: the compile fails with `invalid-plural`, which `email-kit check` reports as this check.
|
|
630
|
+
|
|
631
|
+
**Fix:** Add the categories the message lists for that locale.
|
|
632
|
+
|
|
633
|
+
### i18n.fallback
|
|
634
|
+
**Default:** error
|
|
635
|
+
|
|
636
|
+
**Rule:** The locale fallback chain resolves to a compiled locale. Enforced when compiling: the compile fails with `invalid-config`, which `email-kit check` reports as this check.
|
|
637
|
+
|
|
638
|
+
**Fix:** Point locales.fallback at a locale in locales.list.
|
|
639
|
+
|
|
640
|
+
### i18n.expansion
|
|
641
|
+
**Default:** error
|
|
642
|
+
|
|
643
|
+
**Rule:** Every template compiles in the pseudo-locales en-XA (accented, bracketed, longer by length) and ar-XB (right to left), and passes the static checks there.
|
|
644
|
+
|
|
645
|
+
**Fix:** Translations run up to three times longer and right to left: don't build copy from fragments, and don't let the layout depend on a string's length.
|
|
646
|
+
|
|
647
|
+
### i18n.intl-format
|
|
648
|
+
**Default:** error
|
|
649
|
+
|
|
650
|
+
**Rule:** No currency symbols next to an argument, and no dates built from parts, in messages or templates.
|
|
651
|
+
|
|
652
|
+
**Fix:** Format the value in the backend for the recipient's locale (Intl.NumberFormat with a currency, Intl.DateTimeFormat with a time zone) and pass it as a field marked formatted("money") or formatted("date").
|
|
653
|
+
|
|
654
|
+
### i18n.unused-keys
|
|
655
|
+
**Default:** warning
|
|
656
|
+
|
|
657
|
+
**Rule:** Every message key is used by its template.
|
|
658
|
+
|
|
659
|
+
**Fix:** Delete the key from every locale, or use it. Translators spend time on every key.
|
|
660
|
+
|
|
661
|
+
### i18n.rtl-explicit
|
|
662
|
+
**Default:** error
|
|
663
|
+
|
|
664
|
+
**Rule:** In right-to-left emails, every text cell (p, h1–h6, li, td, th, caption) carries dir and an explicit alignment.
|
|
665
|
+
|
|
666
|
+
**Fix:** Use email-kit's components, which do this, or add dir="rtl" and text-align to the element: Orange strips dir from tables and cells, and Outlook mishandles inherited direction.
|
|
667
|
+
|
|
668
|
+
## Text part
|
|
669
|
+
|
|
670
|
+
### text.present
|
|
671
|
+
**Default:** error
|
|
672
|
+
|
|
673
|
+
**Rule:** The text part has at least 80 characters of its own copy.
|
|
674
|
+
|
|
675
|
+
**Fix:** Every email needs a real text part: spam filters score a missing or token one, and some readers only see it.
|
|
676
|
+
|
|
677
|
+
### text.no-markup
|
|
678
|
+
**Default:** error
|
|
679
|
+
|
|
680
|
+
**Rule:** The text part has no HTML tags.
|
|
681
|
+
|
|
682
|
+
**Fix:** Text-part copy comes from the same messages as the HTML: remove markup from the message.
|
|
683
|
+
|
|
684
|
+
### text.no-entities
|
|
685
|
+
**Default:** error
|
|
686
|
+
|
|
687
|
+
**Rule:** The text part has no HTML entities.
|
|
688
|
+
|
|
689
|
+
**Fix:** Write the character itself (é, ’, &): entities show up literally in plain text.
|
|
690
|
+
|
|
691
|
+
### text.wrap-78
|
|
692
|
+
**Default:** warning
|
|
693
|
+
|
|
694
|
+
**Rule:** Text-part lines are at most 78 characters, except lines with a URL.
|
|
695
|
+
|
|
696
|
+
**Fix:** Shorten the copy or split the paragraph: RFC 5322 recommends 78, and some clients wrap long lines badly.
|
|
697
|
+
|
|
698
|
+
### text.urls-full
|
|
699
|
+
**Default:** error
|
|
700
|
+
|
|
701
|
+
**Rule:** Links are absolute URLs, so the text part can show them.
|
|
702
|
+
|
|
703
|
+
**Fix:** Use https:// URLs (or a url field): a relative link can't be followed from plain text, or from a forward.
|
|
704
|
+
|
|
705
|
+
### text.links-match
|
|
706
|
+
**Default:** error
|
|
707
|
+
|
|
708
|
+
**Rule:** Every HTML link appears in the text part, and every URL in the text part is a link in the HTML.
|
|
709
|
+
|
|
710
|
+
**Fix:** Write links with Link or Button, which put them in both parts; don't paste URLs into copy.
|
|
711
|
+
|
|
712
|
+
### text.parity
|
|
713
|
+
**Default:** warning
|
|
714
|
+
|
|
715
|
+
**Rule:** The text part carries the words of the HTML (at least 80% of them).
|
|
716
|
+
|
|
717
|
+
**Fix:** Spam filters compare the parts (MPART_ALT_DIFF): keep the same copy in both.
|
|
718
|
+
|
|
719
|
+
### text.preheader-first
|
|
720
|
+
**Default:** warning
|
|
721
|
+
|
|
722
|
+
**Rule:** The text part starts with the preheader.
|
|
723
|
+
|
|
724
|
+
**Fix:** Keep email-kit's text part: clients preview the first line of text when there's no HTML.
|
|
725
|
+
|
|
726
|
+
### text.no-preheader-padding
|
|
727
|
+
**Default:** error
|
|
728
|
+
|
|
729
|
+
**Rule:** The text part has none of the preheader's filler characters.
|
|
730
|
+
|
|
731
|
+
**Fix:** The filler pads the HTML preview only; in plain text it shows as junk.
|
|
732
|
+
|
|
733
|
+
### text.no-decorative-runs
|
|
734
|
+
**Default:** warning
|
|
735
|
+
|
|
736
|
+
**Rule:** No long runs of =, -, * or _ beyond heading underlines.
|
|
737
|
+
|
|
738
|
+
**Fix:** Screen readers read every character: drop the decoration.
|
|
739
|
+
|
|
740
|
+
## Preheader
|
|
741
|
+
|
|
742
|
+
### preheader.first
|
|
743
|
+
**Default:** error
|
|
744
|
+
|
|
745
|
+
**Rule:** The first text in the wrapper is the hidden preheader.
|
|
746
|
+
|
|
747
|
+
**Fix:** Set the preheader in defineEmail(): clients preview the first text they find.
|
|
748
|
+
|
|
749
|
+
### preheader.not-subject
|
|
750
|
+
**Default:** error
|
|
751
|
+
|
|
752
|
+
**Rule:** The preheader isn't the subject again.
|
|
753
|
+
|
|
754
|
+
**Fix:** Use the preheader to add something: the inbox shows both side by side.
|
|
755
|
+
|
|
756
|
+
### preheader.length
|
|
757
|
+
**Default:** warning
|
|
758
|
+
|
|
759
|
+
**Rule:** The preheader has 1–90 visible characters. Runs on the renders of every fixture and generated variant.
|
|
760
|
+
|
|
761
|
+
**Fix:** Without one, clients preview the first body text; past about 90 characters it's cut.
|
|
762
|
+
|
|
763
|
+
### preheader.padding
|
|
764
|
+
**Default:** warning
|
|
765
|
+
|
|
766
|
+
**Rule:** The hidden preheader is padded with filler, so body text doesn't leak into the preview.
|
|
767
|
+
|
|
768
|
+
**Fix:** Keep email-kit's preheader block: the filler pushes the body text out of the preview.
|
|
769
|
+
|
|
770
|
+
### preheader.no-boilerplate
|
|
771
|
+
**Default:** error
|
|
772
|
+
|
|
773
|
+
**Rule:** The preheader has no "view in browser" or "trouble viewing" text.
|
|
774
|
+
|
|
775
|
+
**Fix:** Say what the email is about: boilerplate wastes the preview and reads as spam.
|
|
776
|
+
|
|
777
|
+
## Subject
|
|
778
|
+
|
|
779
|
+
### subject.length
|
|
780
|
+
**Default:** warning
|
|
781
|
+
|
|
782
|
+
**Rule:** The subject is at most 60 characters. Runs on the renders of every fixture and generated variant.
|
|
783
|
+
|
|
784
|
+
**Fix:** Phones show about 30–40 characters: put the key words first and cut the rest.
|
|
785
|
+
|
|
786
|
+
### subject.no-fake-reply
|
|
787
|
+
**Default:** error
|
|
788
|
+
|
|
789
|
+
**Rule:** The subject doesn't start with Re: or Fwd:.
|
|
790
|
+
|
|
791
|
+
**Fix:** A fake reply prefix is deceptive and a spam signal: describe the email instead.
|
|
792
|
+
|
|
793
|
+
### subject.no-secret
|
|
794
|
+
**Default:** error
|
|
795
|
+
|
|
796
|
+
**Rule:** No secret field (a code or token) in the subject or the preheader.
|
|
797
|
+
|
|
798
|
+
**Fix:** Subjects show on lock screens and in provider logs: put the code in the body only.
|
|
799
|
+
|
|
800
|
+
### subject.generic
|
|
801
|
+
**Default:** warning
|
|
802
|
+
|
|
803
|
+
**Rule:** The subject isn't generic ("Update", "Notification", "Important").
|
|
804
|
+
|
|
805
|
+
**Fix:** Say what happened: generic subjects get ignored and look like spam.
|
|
806
|
+
|
|
807
|
+
## Copy
|
|
808
|
+
|
|
809
|
+
### copy.placeholder-fallbacks
|
|
810
|
+
**Default:** error
|
|
811
|
+
|
|
812
|
+
**Rule:** Empty, long and real data render cleanly: no “Hi ,”, doubled spaces or empty brackets in the subject, preheader or text. Runs on the renders of every fixture and generated variant.
|
|
813
|
+
|
|
814
|
+
**Fix:** Give the value a fallback, restructure the message (“Hi,” rather than “Hi {name},”), or require it in the schema (`z.string().min(1)`).
|
|
815
|
+
|
|
816
|
+
## Size
|
|
817
|
+
|
|
818
|
+
### size.gmail
|
|
819
|
+
**Default:** error
|
|
820
|
+
|
|
821
|
+
**Rule:** The HTML part of the largest render, plus 5 KB for the provider, stays under Gmail's 102 KB clip (a warning from 90 KB). Runs on the renders of every fixture and generated variant.
|
|
822
|
+
|
|
823
|
+
**Fix:** Gmail hides everything past the clip behind “View entire message”, footers and tracking included. Trim the content, or cap long lists.
|
|
824
|
+
|
|
825
|
+
## Output
|
|
826
|
+
|
|
827
|
+
### output.identifiers
|
|
828
|
+
**Default:** error
|
|
829
|
+
|
|
830
|
+
**Rule:** The identifiers derived from template ids are unique and not reserved in target languages. Enforced when compiling: the compile fails with `identifier-collision`, which `email-kit check` reports as this check.
|
|
831
|
+
|
|
832
|
+
**Fix:** Rename one of the templates the message names.
|
|
833
|
+
|
|
834
|
+
### output.drift
|
|
835
|
+
**Default:** error
|
|
836
|
+
|
|
837
|
+
**Rule:** The committed output equals a fresh compile.
|
|
838
|
+
|
|
839
|
+
**Fix:** Run `email-kit compile` and commit the result: the module your app imports is out of date.
|
|
840
|
+
|
|
841
|
+
### output.manifest
|
|
842
|
+
**Default:** error
|
|
843
|
+
|
|
844
|
+
**Rule:** With `contract: true`, the manifest lists exactly the compiled templates and locales, and its hashes match the files.
|
|
845
|
+
|
|
846
|
+
**Fix:** Don't edit compiled files by hand: change the template or messages and run `email-kit compile`.
|
|
847
|
+
|
|
848
|
+
### output.no-orphans
|
|
849
|
+
**Default:** error
|
|
850
|
+
|
|
851
|
+
**Rule:** Every template folder in the output folder has a source template.
|
|
852
|
+
|
|
853
|
+
**Fix:** Delete the folder, or restore its template: the module may still export a template that no longer exists.
|
|
854
|
+
|
|
855
|
+
### output.runtime-dependency
|
|
856
|
+
**Default:** error
|
|
857
|
+
|
|
858
|
+
**Rule:** `@email-kit/runtime` is in the app's dependencies, not its devDependencies: the generated module imports it when the app runs.
|
|
859
|
+
|
|
860
|
+
**Fix:** Install it as a dependency: `npm install @email-kit/runtime` (or your package manager's equivalent). Production installs leave devDependencies out.
|
|
861
|
+
|
|
862
|
+
### output.gitignored
|
|
863
|
+
**Default:** warning
|
|
864
|
+
|
|
865
|
+
**Rule:** The output folder is committed, not gitignored.
|
|
866
|
+
|
|
867
|
+
**Fix:** Commit the output so deploys don't need a compile step, or compile in your build and set this check off with that reason.
|
|
868
|
+
|
|
869
|
+
## AI coding agents
|
|
870
|
+
|
|
871
|
+
### agents.skill-outdated
|
|
872
|
+
**Default:** warning
|
|
873
|
+
|
|
874
|
+
**Rule:** Each copy of the email-kit skill for AI coding agents (`.agents/skills/email-kit/`, `.claude/skills/email-kit/`) matches the one the installed CLI ships.
|
|
875
|
+
|
|
876
|
+
**Fix:** Run `email-kit agents` to update it: agents follow the skill, and an older one describes an older email-kit.
|