# Pipeline Personalities — what each rendering layer does to your HTML

The newsletter passes through multiple rendering layers between source file and subscriber inbox. Each layer has its own quirks. This file documents every known one so the stylist agent and the auditor can pre-flight check for them.

**This file is universal — do NOT customize it.** These are email client facts, not brand preferences. Add your own failures to MISTAKES-LOG.md as you discover them.

---

## The pipeline (top to bottom)

```
issues/NNN.md  (source markdown + frontmatter + raw HTML for TIP_BODY)
   |  build.py applies template + replaces placeholders
   v
issues/NNN-rendered.html  (rendered HTML)
   |  paste into Beehiiv/Substack/etc.
   v
Platform post  (platform strips/transforms before send)
   |  platform sends to subscriber
   v
Email rendering  (varies per client)
   |
   v
The actual subscriber experience
```

---

## Layer 1: Beehiiv

### What Beehiiv strips
- `<style>` tags — completely removed. No CSS classes, no `@media` queries, no `prefers-color-scheme`.
- `<link>` tags — removed.
- External font references.

### What Beehiiv preserves
- **Inline styles on elements** — these survive intact.
- HTML attributes: `width`, `align`, `border`, `cellpadding`.
- Standard HTML entities (`&middot;`, `&mdash;`, `&rarr;`, `&hellip;`).

### What Beehiiv mangles
- **Non-ASCII characters in raw paste** — UTF-8 bytes get re-decoded, producing mojibake (e.g., `↓` becomes garbage). Always use HTML entities.
- `<body>` background colour — Beehiiv overrides with its own canvas.
- Wide `<table>` layouts may show visible borders. Suppress with `border="0" cellpadding="0" cellspacing="0" style="border:0;border-collapse:collapse"`.

### Beehiiv API note
The `POST /v2/publications/{pub}/posts` endpoint requires Enterprise plan. For free/growth tiers: manual paste is the send method.

---

## Layer 2: Gmail web (~30% of all email opens)

- **Images blocked by default** until user clicks "Display images below". Alt text matters.
- **Maximum HTML before clipping: 102KB.** Beyond this, Gmail shows `[Message clipped]`.
- **`prefers-color-scheme` NOT respected** — Gmail has its own dark mode algorithm.
- **Threading**: Gmail groups emails with the same subject. Each preview send must use a unique subject line.
- **Auto-dark-mode** on some accounts inverts colours unpredictably. Design light-first with explicit text colours.
- **Promotions tab risk**: too many images, too many links, marketing language. Personal voice helps avoid it.

---

## Layer 3: Apple Mail (~20% of email opens, especially on mobile)

- **`prefers-color-scheme` IS respected.** Dark mode media query works.
- **Dynamic dark mode**: if you don't specify dark mode styles, Apple Mail inverts backgrounds and text in unpredictable ways. Specify explicit dark mode overrides for any critical dark/light contrast.
- **Fallback fonts**: Apple Mail falls back to system fonts if web fonts aren't downloaded.

---

## Layer 4: Outlook (Windows, ~10% of email opens, high among enterprise)

- **No Flexbox support.** Any `display:flex` or `display:grid` layouts will break.
- **No `border-radius`** support on table cells.
- **Table-based layouts are the only reliable layouts.** Period.
- **Conditional comments**: Outlook uses IE rendering for HTML/CSS. CSS features from after ~2010 may not work.
- **VML required for rounded buttons**: use VML fallbacks if rounded buttons are critical.

---

## Layer 5: Mobile email clients (50%+ of all opens are on mobile)

- **320px minimum viewport**: the iPhone SE / older Android. Many clients don't scale down below this.
- **Tap target size**: links and buttons must be at least 44x44px to be tappable reliably.
- **Font size enforcement**: iOS will upscale fonts smaller than 13px. Set `text-size-adjust: 100%` in meta viewport.
- **Max width**: set `max-width: 600px` on your outer wrapper. Mobile clients constrain to viewport width.

---

## Implications for HTML structure (universal rules)

1. **Inline styles only.** No `<style>` blocks — Beehiiv strips them.
2. **Table-based layout only.** No Flexbox/Grid — Outlook breaks.
3. **HTML entities for every non-ASCII character.** No literal `↓ · → — …`.
4. **Every block declares its own background.** Don't rely on `<body>` background.
5. **All layout tables have `border="0" cellpadding="0" cellspacing="0" style="border-collapse:collapse;border:0"`.** Suppresses visible borders.
6. **Total HTML under 102KB.** Gmail clips above this.
7. **Images always have `alt` text.** Most clients block images by default.
8. **Tap targets 44x44px minimum.** Anything smaller is effectively invisible on mobile.
