# Email Brand Rules

> **Locked 13 May 2026.** Every rule below has a reason and a date. Don't drift. If a rule needs to change, update this file in the same commit that changes the templates.

These rules extend `MARBL/Brand.md` for the email surface specifically. Where the two conflict, this file wins for email; the parent doc wins everywhere else.

---

## Colour palette (text)

Beige (`#F3E2C8`) is a background and decorative colour only. **Never use it as text.** Settled in `Brand.md` on 14 April 2026; finally propagated to emails on 13 May 2026.

| Usage | Value |
|-------|-------|
| Headings | `#ffffff` |
| Body text | `rgba(255, 255, 255, 0.7)` |
| Muted / labels / footer | `rgba(255, 255, 255, 0.4)` |
| Accent (CTAs, links, edition labels, "New Nura Lead" tag) | `#F35226` (ember) |
| CTA button text on ember | `#131112` (dark on ember) |
| Secondary button text | `rgba(255, 255, 255, 0.85)` |
| Body background | `#0d0c0c` |
| Card background | `#161415` (border `#2a2a2a`) |
| Accent panel background | `#1a1918` (3px ember left border) |

Grey hex literals like `#8a8078` are deprecated for email - use the white rgba scale instead so all surfaces stay consistent.

---

## No icons

**Rule:** Do not use emoji, unicode symbols, ASCII glyphs, or CTA arrows inside email content. Removed 13 May 2026 across all templates.

**Banned examples:**
- 💬 🎙️ 🔗 🚀 (emoji)
- `✉` `🌐` `💡` (unicode entities)
- `→` `→` (arrows after CTA labels)
- The Marbl logo is fine because it ships as a hosted PNG (`marbl-codes-email.png`), not a glyph

**Why:** Inconsistent rendering across email clients (especially Outlook), accessibility (screen readers announce them), brand restraint (the logo + ember accent already do the work).

---

## Buttons

### Primary CTA (every "main action" button)

```css
background-color: #F35226;        /* ember */
border-radius: 12px;               /* --radius-lg */
padding: 14px 32px;
color: #131112;                    /* dark-on-ember */
font-size: 15px;
font-weight: 700;
text-decoration: none;
```

Mark-up pattern (table-wrapped for Outlook):

```html
<table cellpadding="0" cellspacing="0" style="margin: 0 0 28px 0;">
  <tr>
    <td style="background-color: #F35226; border-radius: 12px;">
      <a href="..." style="display: inline-block; padding: 14px 32px; color: #131112; font-size: 15px; font-weight: 700; text-decoration: none;">
        Action label
      </a>
    </td>
  </tr>
</table>
```

### Secondary (outline)

```css
border: 1px solid rgba(255, 255, 255, 0.15);
border-radius: 12px;
padding: 13px 31px;                /* 1px less than primary to account for border */
color: rgba(255, 255, 255, 0.85);
font-size: 15px;
font-weight: 700;
```

Same table-wrap pattern as primary.

### Rules

- Border-radius is `12px` (never `8px`, never `9999px` pill - pills are for badges only)
- No glow / coloured `box-shadow`. Ever.
- Padding `14px 32px` for primary. Mirror for secondary minus border width.
- CTA arrows (`&rarr;`) are banned per the "no icons" rule.

---

## Category pills (daily digest)

Pills sit above each article title in the featured-insights list. Per-category text colour and matching border at 30% alpha, no background fill.

```css
border: 1px solid <category at 0.3 alpha>;
border-radius: 9999px;             /* --radius-full */
padding: 0 10px 4px 10px;          /* asymmetric for optical centring of uppercase */
line-height: 1;
font-size: 11px;
font-weight: 600;
color: <category text colour>;
text-transform: uppercase;
letter-spacing: 1px;
```

Mirrors the canonical `.featured-category-badge` from `marbl-luma/src/website/css/luma.css`.

### Category colour table

| Category | Text colour | Border colour |
|----------|-------------|---------------|
| `ai` | `#22d3ee` (cyan) | `rgba(34, 211, 238, 0.3)` |
| `quantum` | `#a78bfa` (purple) | `rgba(167, 139, 250, 0.3)` |
| `web` | `#34d399` (green) | `rgba(52, 211, 153, 0.3)` |
| `robotics` | `#fb923c` (orange) | `rgba(251, 146, 60, 0.3)` |
| `voices` | `#ec4899` (pink) | `rgba(236, 72, 153, 0.3)` |
| `builders` | `#8b5cf6` (violet) | `rgba(139, 92, 246, 0.3)` |
| `inside_marbl` | `#F35226` (ember) | `rgba(243, 82, 38, 0.3)` |

### Pill mark-up pattern

```html
<table cellpadding="0" cellspacing="0" style="margin: 0 0 8px 0;">
  <tr>
    <td style="border: 1px solid rgba(34, 211, 238, 0.3); border-radius: 9999px; padding: 0 10px 4px 10px; line-height: 1;"><span style="font-size: 11px; font-weight: 600; color: #22d3ee; text-transform: uppercase; letter-spacing: 1px; line-height: 1;">AI and Machine Learning</span></td>
  </tr>
</table>
```

**Optical-centring note.** Uppercase letterspaced text has no descenders, so symmetric padding looks top-heavy. The asymmetric `0 10px 4px 10px` lifts the text up to its optical centre. Browser-iframe and Gmail-web render this cleanly. Outlook desktop should be tested before locking a new pill style.

**Whitespace.** Keep the `<span>` and label on a single source line with no internal whitespace - some clients render indentation whitespace as visible inline boxes.

---

## Accent panels

The `<div>` with the 3px ember left-border (used for "What to expect", "What you asked about", "Contact Details"):

```css
background-color: #1a1918;
border-left: 3px solid #F35226;
border-radius: 0 12px 12px 0;
padding: 16px 20px;
margin: 0 0 24px 0;
```

Always `0 12px 12px 0` - the left side is square because of the 3px ember border.

---

## Footer

Every email footer includes, in this order:

1. **Action row** - unsubscribe (if applicable) + Marbl Codes link + "Built by Richard Bland"
2. **Legal block** - MEM Digital Limited / Wellingborough / Company No. 13753194 / Privacy + Terms

Mark-up pattern (text-align centre is the daily-digest variant; left-align is the welcome / verification variant):

```html
<tr>
  <td style="padding: 24px 0 0 0;">
    <p style="color: rgba(255, 255, 255, 0.4); font-size: 12px; line-height: 1.5; margin: 0 0 8px 0;">
      <a href="${unsubscribeUrl}" style="color: rgba(255, 255, 255, 0.4); text-decoration: none;">Unsubscribe</a> &middot; <a href="https://marbl.codes" style="color: #F35226; text-decoration: none;">Marbl Codes</a> &middot; Built by Richard Bland
    </p>
    <p style="color: rgba(255, 255, 255, 0.4); font-size: 10px; line-height: 1.6; margin: 0;">
      <strong style="color: #ffffff;">MEM Digital Limited</strong> trading as <strong style="color: #ffffff;">Marbl Codes</strong><br>
      Wellingborough, Northamptonshire, United Kingdom<br>
      Registered in England &amp; Wales. Company No. 13753194<br>
      <a href="https://marbl.codes/legal/privacy" style="color: rgba(255, 255, 255, 0.4); text-decoration: none;">Privacy</a> &middot; <a href="https://marbl.codes/legal/terms" style="color: rgba(255, 255, 255, 0.4); text-decoration: none;">Terms</a>
    </p>
  </td>
</tr>
```

---

## Other rules (mechanical)

- **Dark mode only** - no light variant, no media-query toggle. Email clients that force dark inversion will already get our dark.
- **Escape every user input** - call `escapeHtml()` on anything that comes from a config field or runtime data
- **Use `'cen' + 'ter'`** for any CSS `align` keyword in the template - prevents britfix from rewriting `center` to `centre` in serving HTML
- **UTM parameters** on every outbound link that drives traffic to a Marbl property (Atlas links already do this; mirror the pattern when adding new ones)
- **Logo** - hosted PNG at `https://marbl.codes/assets/images/marbl-codes-email.png`, 40px high, never replace with SVG (Outlook doesn't render SVG reliably)
- **Width** - card max-width 560px (the de-facto email-safe width)
- **Font stack** - `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif` - system fonts only, no web fonts (Outlook breaks them)