@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.
@@ -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.