Merge pull request #24 from dcondrey/feat/gate-more-quirks

feat: gate ten more documented quirks, and correct the dark-mode claim

Author: dcondrey

README.md

@@ -49,8 +49,8 @@ in translation on the oldest clients.
   project's conventions. See [Lint any email](#lint-any-email).
 - **Three ways to use it.** Copy the single-file master, assemble the documented partials, or run the
   build. All three produce identical markup.
-- **Dark mode, three ways.** `prefers-color-scheme`, Outlook.com `[data-ogsc]`/`[data-ogsb]`, and
-  Gmail-safe explicit `bgcolor` on every cell.
+- **Dark mode, three ways.** `prefers-color-scheme`, Outlook.com `[data-ogsc]`/`[data-ogsb]`, and a
+  Gmail-safe explicit `background-color` on every container the dark CSS repaints.
 - **Five branded templates, and a scaffolder.** Distinct designs (see below), each rebuilt in the
   house conventions with self-authored generated art and passing both gates clean. Start a new one
   with `node scripts/new-template.mjs <name> "Brand"` — a complete, conformant template out of the box.

docs/quirks.md

@@ -13,11 +13,11 @@ offender; several quirks affect more than one client. Every fix is annotated inl
 | 5 | No `max-width` → layout won't center/constrain | Outlook Windows | 600px MSO ghost table wrapping a fluid `.email-container` |
 | 6 | No CSS background images | Outlook Windows (classic); *partial* in Outlook.com & Yahoo | VML `v:fill type="frame"` for Outlook; solid `bgcolor` fallback always behind |
 | 7 | Message clipped at ~102 KB (footer/unsub hidden) | Gmail | `--production` minify; build warns past the threshold |
-| 8 | Runs its own dark-mode inversion, ignores `prefers-color-scheme` | Gmail | Explicit `bgcolor` on **every** cell so nothing is left "unset" |
+| 8 | Runs its own dark-mode inversion, ignores `prefers-color-scheme` | Gmail | Explicit `background-color` on every element the dark CSS repaints, so nothing is left "unset" |
 | 9 | Inverts pure `#000000` / `#ffffff` unconditionally | Apple Mail (dark) | Off-black `#2b2b30` / off-white text; `supported-color-schemes` meta |
 | 10 | `prefers-color-scheme` support is inconsistent | Cross-client | Progressive enhancement + `color-scheme` meta; never depended on |
 | 11 | Partial colour inversion, custom attributes | Outlook.com (dark) | `[data-ogsc]` (text) / `[data-ogsb]` (background) targeted overrides |
-| 12 | Undefined `<td>` background repainted dark | Gmail (dark) | Same as #8 — no cell without an explicit colour |
+| 12 | Undefined `<td>` background repainted dark | Gmail (dark) | Same as #8 — every `darkmode-bg`/`darkmode-card` container declares its light colour inline, gated by the `dark-bg-explicit` rule |
 | 13 | Auto-links dates, phones, addresses in blue | iOS Mail | `format-detection` meta + `a[x-apple-data-detectors]` reset |
 | 14 | Auto-inflates "too small" text | iOS, Windows | `-webkit-text-size-adjust` / `-ms-text-size-adjust:100%` |
 | 15 | Auto-scales/reformats the whole layout | Apple Mail | `x-apple-disable-message-reformatting` meta |

framework/build/lint.test.mjs

@@ -63,6 +63,21 @@ assert(/color-scheme.*meta/.test(bad.out), 'bad.html: dark-mode-declaration rule
 assert(/PixelsPerInch/.test(bad.out), 'bad.html: Outlook-DPI rule fires');
 assert(/prefers-color-scheme: dark\) block/.test(bad.out), 'bad.html: dark-mode-CSS rule fires');
 
+// --- quirk coverage: rules added for documented quirks must actually fire.
+assert(/mso-table-lspace/.test(bad.out), 'bad.html: Outlook table-gutter rule fires');
+assert(/ExternalClass/.test(bad.out), 'bad.html: Outlook.com .ExternalClass rule fires');
+assert(/text-size-adjust/.test(bad.out), 'bad.html: text-inflation rule fires');
+assert(/format-detection meta/.test(bad.out), 'bad.html: iOS auto-link rule fires');
+assert(/x-apple-disable-message-reformatting/.test(bad.out), 'bad.html: Apple reformatting rule fires');
+assert(/data-ogsc/.test(bad.out), 'bad.html: Outlook.com dark-mode rule fires');
+assert(/Times New Roman/.test(bad.out), 'bad.html: MSO font-fallback rule fires');
+
+// The dark-mode background rule must be exercised, not vacuously passed: a
+// darkmode-* class with no light-state colour is the failure it exists to catch.
+const paintedOk = runHouse(GOOD);
+assert(/dark-mode painted elements declare an explicit background-color/.test(paintedOk.out),
+  'good.html: dark-mode background rule runs against a real painted element');
+
 // --- profile split: the universal rules must be safe to point at anyone's HTML.
 // bad.html omits every house convention, so if those rules leaked into the
 // default profile the CLI would fail on all third-party output.

framework/build/rules.mjs

@@ -141,16 +141,22 @@ function findStyleBlocks(html, tags) {
   return blocks;
 }
 
+/** Elements the dark-mode CSS repaints, so their light state must be explicit. */
+const PAINTED_CLASS = /class=["'][^"']*darkmode-(?:bg|card)\b/i;
+const EXPLICIT_BG = /background-color\s*:|bgcolor\s*=/i;
+
 function buildContext(html) {
   const structural = stripDocComments(html);
   const tags = scanTags(html);
-  const imgs = openTags(scanTags(structural), 'img').map((t) => t.raw);
+  const structuralTags = scanTags(structural);
+  const imgs = openTags(structuralTags, 'img').map((t) => t.raw);
   const styleBlocks = findStyleBlocks(html, tags);
   return {
     html,
     structural,
     imgs,
     styleBlocks,
+    painted: structuralTags.map((t) => t.raw).filter((t) => PAINTED_CLASS.test(t)),
     bytes: Buffer.byteLength(html, 'utf8'),
     preheader: findPreheader(html, tags),
   };
@@ -268,6 +274,27 @@ export const RULES = [
         ? [SEVERITY.PASS, `viewport + charset meta present.`]
         : [SEVERITY.WARN, `Missing viewport or charset meta.`],
   },
+  {
+    // Quirk 16: an <img> is inline by default, so the line-box descender leaves
+    // a ~3px gap under it in most clients. display:none is the dark-mode swap.
+    id: 'img-display',
+    scope: 'universal',
+    run: ({ imgs }) => {
+      const inline = imgs.filter((t) => !/display:\s*(?:block|none)/i.test(t));
+      return inline.length
+        ? [SEVERITY.WARN, `${inline.length} <img> without display:block — most clients leave a ~3px gap under an inline image. First: ${inline[0].slice(0, 80)}…`]
+        : [SEVERITY.PASS, `All ${imgs.length} <img> tags are display:block (or deliberately hidden).`];
+    },
+  },
+  {
+    // Quirk 6: classic Outlook drops CSS background images entirely.
+    id: 'css-background-image',
+    scope: 'universal',
+    run: ({ html, structural }) =>
+      !/background-image\s*:/i.test(structural) || /v:fill/i.test(html)
+        ? [SEVERITY.PASS, `No CSS background-image without a VML fallback.`]
+        : [SEVERITY.WARN, `CSS background-image with no <v:fill> fallback — classic Outlook drops it and paints nothing behind the content.`],
+  },
   {
     id: 'placeholder-href',
     scope: 'universal',
@@ -302,6 +329,82 @@ export const RULES = [
         ? [SEVERITY.PASS, `Dark-mode CSS present (prefers-color-scheme block).`]
         : [SEVERITY.FAIL, `No @media (prefers-color-scheme: dark) block — the template opts into dark mode but never styles it.`],
   },
+  {
+    // Quirks 8 + 12: Gmail repaints a background it considers unset. The
+    // framework declares the light colour on the element the dark CSS overrides,
+    // not on every <td> — so that pairing is the invariant worth enforcing.
+    id: 'dark-bg-explicit',
+    scope: 'house',
+    run: ({ painted }) => {
+      const unset = painted.filter((t) => !EXPLICIT_BG.test(t));
+      return unset.length
+        ? [SEVERITY.FAIL, `${unset.length} element(s) carry a darkmode-bg/darkmode-card class with no explicit background-color — the dark override has nothing to override, so Gmail repaints them. First: ${unset[0].slice(0, 80)}…`]
+        : [SEVERITY.PASS, `All ${painted.length} dark-mode painted elements declare an explicit background-color.`];
+    },
+  },
+  {
+    // Quirk 17: Word injects space around tables unless both are zeroed.
+    id: 'mso-table-spacing',
+    scope: 'house',
+    run: ({ html }) =>
+      /mso-table-lspace/i.test(html) && /mso-table-rspace/i.test(html)
+        ? [SEVERITY.PASS, `mso-table-lspace/rspace zeroed (Outlook adds table gutters otherwise).`]
+        : [SEVERITY.FAIL, `No mso-table-lspace/rspace reset — Outlook injects extra space around every table.`],
+  },
+  {
+    // Quirk 18: Outlook.com wraps the body in .ExternalClass and restyles it.
+    id: 'external-class',
+    scope: 'house',
+    run: ({ html }) =>
+      /\.ExternalClass/i.test(html)
+        ? [SEVERITY.PASS, `.ExternalClass reset present (Outlook.com line-height/width).`]
+        : [SEVERITY.FAIL, `No .ExternalClass reset — Outlook.com alters line-height and width of the whole message.`],
+  },
+  {
+    // Quirk 14: iOS and Windows inflate text they judge too small.
+    id: 'text-size-adjust',
+    scope: 'house',
+    run: ({ html }) =>
+      /-webkit-text-size-adjust/i.test(html) && /-ms-text-size-adjust/i.test(html)
+        ? [SEVERITY.PASS, `text-size-adjust pinned for WebKit and Windows.`]
+        : [SEVERITY.FAIL, `Missing -webkit-/-ms-text-size-adjust — iOS and Windows auto-inflate "too small" text.`],
+  },
+  {
+    // Quirk 13: iOS auto-links dates, phones and addresses in system blue.
+    id: 'auto-link-detection',
+    scope: 'house',
+    run: ({ html }) =>
+      /name=["']format-detection["']/i.test(html) && /x-apple-data-detectors/i.test(html)
+        ? [SEVERITY.PASS, `format-detection meta + x-apple-data-detectors reset present.`]
+        : [SEVERITY.FAIL, `Missing format-detection meta or the x-apple-data-detectors reset — iOS recolours dates, phones and addresses.`],
+  },
+  {
+    // Quirk 15: Apple Mail rescales the whole layout without this.
+    id: 'apple-reformatting',
+    scope: 'house',
+    run: ({ html }) =>
+      /x-apple-disable-message-reformatting/i.test(html)
+        ? [SEVERITY.PASS, `x-apple-disable-message-reformatting present (Apple Mail leaves the layout alone).`]
+        : [SEVERITY.FAIL, `No x-apple-disable-message-reformatting meta — Apple Mail auto-scales and reformats the layout.`],
+  },
+  {
+    // Quirk 11: Outlook.com signals dark mode with its own attributes.
+    id: 'outlook-com-dark',
+    scope: 'house',
+    run: ({ html }) =>
+      /\[data-ogsc\]/i.test(html) && /\[data-ogsb\]/i.test(html)
+        ? [SEVERITY.PASS, `[data-ogsc]/[data-ogsb] overrides present (Outlook.com dark mode).`]
+        : [SEVERITY.FAIL, `No [data-ogsc]/[data-ogsb] rules — Outlook.com inverts text and background on its own terms.`],
+  },
+  {
+    // Quirk 3: Word falls back to Times New Roman, not the next stack entry.
+    id: 'mso-font-fallback',
+    scope: 'house',
+    run: ({ html }) =>
+      /\[if mso\]/i.test(html) && /mso-font-alt|font-family\s*:\s*Arial/i.test(html)
+        ? [SEVERITY.PASS, `MSO font fallback declared (Outlook would use Times New Roman otherwise).`]
+        : [SEVERITY.FAIL, `No [if mso] font fallback — classic Outlook renders web fonts as Times New Roman.`],
+  },
   {
     id: 'preheader',
     scope: 'house',

framework/build/test/good.html

@@ -1,7 +1,9 @@
 <!--
   lint fixture: GOOD — a minimal but valid email that must pass every lint rule
-  (0 fail). If a change to lint.mjs makes this file fail, either the change is
-  wrong or this fixture needs a matching, deliberate update. See lint.test.mjs.
+  (0 fail, 0 warn) under --profile house. It carries every house convention, so
+  it doubles as the smallest complete example of them. If a change to the rules
+  makes this file fail, either the change is wrong or this fixture needs a
+  matching, deliberate update. See lint.test.mjs.
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
@@ -10,25 +12,36 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <meta name="color-scheme" content="light dark">
   <meta name="supported-color-schemes" content="light dark">
+  <meta name="format-detection" content="telephone=no,date=no,address=no,email=no">
+  <meta name="x-apple-disable-message-reformatting">
   <title>Good fixture</title>
   <!--[if mso]>
   <noscript><xml><o:OfficeDocumentSettings><o:AllowPNG/><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml></noscript>
+  <style type="text/css">
+    body, table, td, a { font-family: Arial, Helvetica, sans-serif !important; }
+  </style>
   <![endif]-->
   <style type="text/css">
+    body { margin:0; padding:0; -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
+    table, td { mso-table-lspace:0pt; mso-table-rspace:0pt; border-collapse:collapse; }
+    .ExternalClass { width:100%; }
+    .ExternalClass, .ExternalClass p, .ExternalClass td { line-height:100%; }
     .email-container { max-width:600px; }
     a { text-decoration:none; }
+    a[x-apple-data-detectors] { color:inherit !important; text-decoration:none !important; }
     @media (prefers-color-scheme: dark) {
       .darkmode-bg { background-color:#111114 !important; }
       .darkmode-text { color:#e6e6e6 !important; }
     }
     [data-ogsc] .darkmode-text { color:#e6e6e6 !important; }
+    [data-ogsb] .darkmode-bg { background-color:#111114 !important; }
   </style>
 </head>
 <body>
   <div style="display:none; font-size:1px; line-height:1px; max-height:0; max-width:0; opacity:0; overflow:hidden; mso-hide:all;">
     Hidden preheader controls the inbox preview line. &zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;
   </div>
-  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
+  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" class="darkmode-bg" style="background-color:#f4f4f7;">
     <tr>
       <td align="center">
         <img src="hero.jpg" width="600" height="200" alt="A valid hero image" style="display:block;">
@@ -40,7 +53,7 @@
         <!--[if !mso]><!-->
         <a href="#" style="background:#445942; color:#ffffff; display:inline-block; padding:12px 30px;">Shop now</a>
         <!--<![endif]-->
-        <p><a href="#unsub">Unsubscribe</a> from this mailing list.</p>
+        <p class="darkmode-text"><a href="#unsub">Unsubscribe</a> from this mailing list.</p>
       </td>
     </tr>
   </table>

framework/dist/email.html

@@ -211,8 +211,9 @@
 
               - width="600" attribute + class="fluid" = full width on desktop,
                 shrinks to screen on mobile, never upscales in Outlook.
-              - The <td> has an explicit bgcolor so Gmail's dark-mode engine does
-                not paint its own background behind a transparent PNG.
+              - The wrapping table declares an explicit background-color (and the
+                darkmode-card class that overrides it) so Gmail's dark-mode engine
+                does not paint its own background behind a transparent PNG.
 
               OPTIONAL: to bake text OVER a background image (the 2014 signature
               trick — still the only way to get a background image behind text in
@@ -329,8 +330,9 @@
               - Background is #2b2b30, NOT pure #000000. Apple Mail inverts pure
                 black/white outright in dark mode; an off-black is left alone.
                 (Same reason the light text is #d8d8d8, not #ffffff.)
-              - Every cell has an explicit bgcolor so Gmail's dark engine cannot
-                paint an unset cell.
+              - The wrapping table declares an explicit background-color, paired with
+                the darkmode-bg class that overrides it, so Gmail's dark engine has
+                nothing unset to repaint. The lint rule dark-bg-explicit enforces it.
               - The unsubscribe link is REQUIRED for CAN-SPAM / CASL / GDPR and
                 for one-click unsubscribe (RFC 8058) that Gmail & Yahoo now
                 enforce for bulk senders. Keep it real, not a sample value.

framework/partials/30-hero.html

@@ -9,8 +9,9 @@
 
               - width="600" attribute + class="fluid" = full width on desktop,
                 shrinks to screen on mobile, never upscales in Outlook.
-              - The <td> has an explicit bgcolor so Gmail's dark-mode engine does
-                not paint its own background behind a transparent PNG.
+              - The wrapping table declares an explicit background-color (and the
+                darkmode-card class that overrides it) so Gmail's dark-mode engine
+                does not paint its own background behind a transparent PNG.
 
               OPTIONAL: to bake text OVER a background image (the 2014 signature
               trick — still the only way to get a background image behind text in

framework/partials/60-footer.html

@@ -5,8 +5,9 @@
               - Background is #2b2b30, NOT pure #000000. Apple Mail inverts pure
                 black/white outright in dark mode; an off-black is left alone.
                 (Same reason the light text is #d8d8d8, not #ffffff.)
-              - Every cell has an explicit bgcolor so Gmail's dark engine cannot
-                paint an unset cell.
+              - The wrapping table declares an explicit background-color, paired with
+                the darkmode-bg class that overrides it, so Gmail's dark engine has
+                nothing unset to repaint. The lint rule dark-bg-explicit enforces it.
               - The unsubscribe link is REQUIRED for CAN-SPAM / CASL / GDPR and
                 for one-click unsubscribe (RFC 8058) that Gmail & Yahoo now
                 enforce for bulk senders. Keep it real, not a sample value.