# Codex Insider — Developer Handover

Everything needed to build the site and newsletter. **Not affiliated with OpenAI** — the footer line is required on every page and email.

## Start here
1. Open `pages/brand-kit.html` — the full visual brand kit (self-contained, works offline).
2. Open `pages/homepage.html`, `pages/article.html`, `pages/newsletter.html` — the reference builds. Each has a working light/dark toggle in the nav.
3. Link `styles.css` in your app. Everything below is driven by its tokens.
4. `screenshots/` is the visual spec — desktop and mobile, light and dark, top to bottom.

## Contents
```
styles.css                   entry point — imports the three token files
tokens/colors.css            palette + light/dark semantic tokens
tokens/typography.css        font stacks, sizes, weights, tracking (Google Fonts import)
tokens/spacing.css           4px spacing scale + radii
assets/                      logo + icon SVGs
assets/png/                  transparent PNG exports, 512 → 16
pages/                       three reference builds, self-contained HTML
screenshots/desktop/         homepage + article, light & dark, scrolled top→bottom
screenshots/mobile/          same at 390px
screenshots/email/           newsletter template
screenshots/brand/           brand kit pages
```

Screenshots are numbered in scroll order: `01-home-light.png` is the top of the homepage, `06-` the footer.

## Implementation

### Theme
Light is the default. Follow the OS preference, let the user override, persist the choice.

```html
<link rel="stylesheet" href="styles.css">
<script>
  const saved = localStorage.getItem('theme');
  const dark = saved ? saved === 'dark' : matchMedia('(prefers-color-scheme: dark)').matches;
  if (dark) document.documentElement.dataset.theme = 'dark';
</script>
```

`data-theme="dark"` on any element flips every semantic token inside it. **Style components with semantic tokens only** (`--bg`, `--surface`, `--surface-2`, `--text-1/2/3`, `--border`, `--accent`, `--accent-strong`, `--accent-soft`, `--on-accent`, `--link`, `--success`, `--warning`, `--danger`) — never raw ramp values like `--indigo-600`, or dark mode won't work.

Note: `--gradient-mist` and the `--ink-*` scale are theme-aware too (mist inverts to a deep indigo wash in dark). `--gradient-ink` is intentionally dark in both modes — terminal blocks never invert.

### Type
- **Geist** 400/500/600/700 — everything readable. Headings 600. Tracking: −0.03em display, −0.015em headings, normal body.
- **Geist Mono** 400/500/600 — kickers (uppercase, +0.06em), metadata, code. Never body copy.
- Both free on Google Fonts, imported by `tokens/typography.css`. **Self-host for production email** and add `Arial, sans-serif` fallbacks inline — email clients won't load webfonts reliably.

### Layout
- Content max-width **1120px**; article measure **760px**; email **600px**.
- Sections separated by 1px `--border` hairlines with 64px vertical padding — not by cards.
- Breakpoints: **900px** (multi-column grids collapse to one, nav links → menu) and **620px** (3/4-up grids to one column, display type down to 32px, padding to 20px). See `screenshots/mobile/`.
- The reference pages implement this with `data-r` markers + two media queries in `<head>`; use your own class names, but keep the same breakpoints and behavior.

### Visual rules
- **One filled button per view** (Subscribe, `--text-1` bg / `--bg` text, pill). Everything else is ghost or plain text.
- Radii: 8px (thumbnails, code blocks), 10px (inputs, terminal), 999px (buttons, badges). Nothing larger in product UI.
- **No shadows** in the site UI. Elevation comes from hairlines and whitespace.
- Kickers are plain mono uppercase text, not filled pills, on editorial surfaces.
- Motion 150–200ms ease-out. The only decorative animation is the blinking terminal cursor (`ciBlink`, 1.1s step-end).
- Hover: links → `--accent`. Press: 0.98 scale.

### Content model
The homepage sorts by freshness, and each tier has its own treatment — keep this if you change the layout:
- **The Wire** (fresh) — reverse-chronological log, mono, on ink. Tagged `SHIP` (green) / `NEWS` (indigo) / `RUMOR` (amber). Live indicator.
- **Catch up / Watch** (recent) — dated editorial lists and video cards.
- **The Handbook** (evergreen) — numbered chapters, **no publish dates**. Show a verification stamp instead (`✓ verified 5.4` in `--success`, `re-verifying` in `--warning`). Re-stamp on each model release.
- **One-liners** (tips) — single command + one sentence. Make the command click-to-copy.
- **Resources** — hairline index, external links marked `↗`.

### Logo
- Primary is the gradient mark; use mono black/white where gradient can't print or contrast fails.
- Min 16px. Clear space = ½ mark width. Don't recolor, rotate, or nest the squircle in another container.
- Favicon: `assets/png/logo-gradient-32.png` + `-16.png`. App/touch: `assets/app-icon-*`.

### Copy
Sharp, not snarky — reads like a great changelog. Sentence case everywhere, including buttons and nav. "You" voice. No emoji; terminal glyphs (`➜ ✓ #`) only inside code blocks.

## Known gaps
- Video thumbnails are gradient placeholders — swap in real stills.
- Mobile nav collapses the links; the menu drawer isn't designed yet.
- Handbook chapter page, archive/tag index, and search are not designed yet.
