From 70ddf77d338aa4764540d4c07c2e92053cc18703 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Mon, 9 Nov 2026 07:42:18 -0500 Subject: [PATCH] Describe the US layout in CLAUDE.md's template section The section called the 20 and 26 October editions "the two latest", although two 29 October editions have landed, and it called the UK layout "the current template". US editions use a different layout. Say which subsections describe which layout, compare the two element by element, and list what only the US layout has. List what 2026-10-29-uk.html adds to the UK layout. Tell authors to copy the most recent edition for the same audience. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 78 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 85b5817..4e0ec21 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,7 +23,12 @@ newsletters/ ## Newsletter Template Structure -This describes the current template as used by the two latest editions, `editions/2026-10-20-uk.html` (#28) and `editions/2026-10-26-uk.html` (#31). Editions from `2025-11-26-uk-prebudget.html` on use Inter and the teal palette, except `2025-12-08-uk-autumn-budget.html`. Editions before that use Roboto (except `2024-03-28.html`, which uses Helvetica Neue), most with a blue palette (`#2C6496`), so don't copy from them. +UK and US editions use different layouts, so copy the latest edition for your audience (see "Creating New Newsletters"). + +- **UK layout** (dark page, teal gradient hero, white sections): "Head" through "Images" below describe it, from `editions/2026-10-20-uk.html` (#28) and `editions/2026-10-26-uk.html` (#31). "The 29 October UK edition" lists what `editions/2026-10-29-uk.html` adds. +- **US layout** (light grey page, bordered white container, no gradients): "US layout" lists how it differs. `editions/2026-09-08-us-v2.html` first used it, and `editions/2026-10-29-us.html` follows it. The US editions from `2026-01-30-us.html` to `2026-05-19-us.html` have a dark page and gradients, so don't copy from them. + +Editions from `2025-11-26-uk-prebudget.html` on use Inter and the teal palette, except `2025-12-08-uk-autumn-budget.html`. Editions before that use Roboto (except `2024-03-28.html`, which uses Helvetica Neue), most with a blue palette (`#2C6496`), so don't copy from them. ### Head @@ -32,7 +37,7 @@ This describes the current template as used by the two latest editions, `edition ```html ``` - `` sets `font-family:'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;` so clients that ignore the ``, such as Gmail, use a system sans. Classic Outlook for Windows (2007–2016) is the exception: caniemail notes that it ignores the stack for a font declared with `@font-face` and falls back to Times New Roman unless `mso-font-alt` sets the fallback, and neither edition sets it. The `h1` and the card `h2` ask for `font-weight:800`, which the link doesn't load, so they render at 700 where Inter loads; add `800` to `wght@` if you want the heavier weight. + `` sets `font-family:'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;` so clients that ignore the ``, such as Gmail, use a system sans. Classic Outlook for Windows (2007–2016) is the exception: caniemail notes that it ignores the stack for a font declared with `@font-face` and falls back to Times New Roman unless `mso-font-alt` sets the fallback, and the editions described here don't set it. The `h1` and the card `h2` ask for `font-weight:800`, which the link doesn't load, so they render at 700 where Inter loads; add `800` to `wght@` if you want the heavier weight. - **Mobile media query**: apart from the font ``, the only CSS outside inline `style` attributes is one block in ``. It overrides inline values with `!important`, keyed to classes on the container table, its cells and the headings: ```html + ``` + `2026-09-08-us-v2.html` also has `.speaker-cell` for its two-column speaker grid. +- **Callout panel** (optional) below the hero: a table cell with `background-color: #E6FFFA; border-left: 3px solid #319795; padding: 18px 20px;`. +- **"Also in this issue:" jump links** below the panel: 13px `#64748B`, with links styled `color: #319795; text-decoration: none; font-weight: 500;`. Each `href` points at an `` anchor at the top of a later section. +- **Two more merge tags**: `*|ARCHIVE|*` behind "View in browser" in the header and `*|FORWARD|*` behind "Forward to a colleague" in the footer. +- **A table-cell button** in `2026-10-29-us.html`: `` around a link with `color: #FFFFFF; text-decoration: none; font-weight: 700; font-size: 14px; display: inline-block;`. `2026-09-08-us-v2.html` styles the `` itself. +- **Four more colours**, all `@policyengine/ui-kit` tokens: + +| Hex | ui-kit token | Used for | +|---|---|---| +| `#F2F4F7` | `--color-gray-100` | page background and preheader text | +| `#2C7A7B` | `--color-teal-600` | eyebrow labels | +| `#E6FFFA` | `--color-teal-50` | callout panel | +| `#94A3B8` | `--color-gray-400` | footer postal address | + ### Notes for new editions These came from the independent review of #31 (2026-10-27). - **Make the hidden preheader match the campaign's preview text.** The preheader `
` text must be the same words as the Mailchimp campaign's preview text (the uploader's `--preview`, or the preview set in Mailchimp). If you change one, change the other. In #31 they differed: the file says "On Budget day at 4:30pm, we'll present our first estimates and take your questions." while the campaign's preview was "We'll present our first estimates on Budget day and take your questions." -- **Give every `linear-gradient` a solid `background-color` fallback.** caniemail lists no `linear-gradient` support in any Outlook client at the latest version it tested: Windows desktop 2007–2019 (where gradients need VML), Windows Mail, Outlook.com, and the Mac, iOS and Android apps. Without a fallback the element has no background there. The hero and the feature card already do this: `background: linear-gradient(...); background-color:#234E52;`. Put `background-color` after the `background` shorthand, because the shorthand resets it. The hero's 48×3px accent bar has no fallback in either edition, so it doesn't show in Outlook. Don't just add `background-color` to it: caniemail says classic Outlook for Windows ignores `width` and `height` on a `
`, so the colour would likely spread across the hero (untested). To give it one, rebuild it as a 48×3 table cell with `bgcolor` and `font-size:0;line-height:0;`, and test that in Outlook before sending. +- **Give every `linear-gradient` a solid `background-color` fallback.** caniemail lists no `linear-gradient` support in any Outlook client at the latest version it tested: Windows desktop 2007–2019 (where gradients need VML), Windows Mail, Outlook.com, and the Mac, iOS and Android apps. Without a fallback the element has no background there. The hero and the feature card already do this: `background: linear-gradient(...); background-color:#234E52;`. Put `background-color` after the `background` shorthand, because the shorthand resets it. The hero's 48×3px accent bar has no fallback in the UK editions described here, so it doesn't show in Outlook. Don't just add `background-color` to it: caniemail says classic Outlook for Windows ignores `width` and `height` on a `
`, so the colour would likely spread across the hero (untested). To give it one, rebuild it as a 48×3 table cell with `bgcolor` and `font-size:0;line-height:0;`, and test that in Outlook before sending. ### Links @@ -126,9 +192,9 @@ Every link goes to policyengine.org, never to the address of the platform that h ## Creating New Newsletters -**IMPORTANT: Always start from the most recent newsletter as a template.** The template structure evolves over time, so copying from the latest edition ensures you use current styling, layout patterns, and best practices. +**IMPORTANT: Always start from the most recent newsletter as a template.** The template structure evolves over time, so copying from the latest edition ensures you use current styling, layout patterns, and best practices. UK and US editions use different layouts, so take the most recent edition for the same audience. -1. Find the most recent newsletter in `editions/` (sorted by date) +1. Find the most recent newsletter for your audience in `editions/` (sorted by date): `*-uk*.html` or `*-us*.html` 2. Copy it as a new file with date format: `YYYY-MM-DD-{audience}.html` (e.g., `2025-12-02-uk.html`) 3. Update content while maintaining: - Inline styles for email client compatibility @@ -164,7 +230,7 @@ Use a full commit SHA, not a branch name or `main`; see "Images" under "Newslett - **No JavaScript**: Email clients block JavaScript - **External images**: Use full URLs for all images - **Responsive design**: Use media queries in `