# Context: the design system (as it actually is)

Read this before touching CSS. Everything here was extracted from the current
files, not assumed.

## There is no single palette. There are three.

The same semantic names carry different values depending on which stylesheet
loaded them:

| Token | `styles.css`, `rules/styles.css` | `chapters.css`, `skills-review/styles.css` | `hands-on/*/styles.css` |
| --- | --- | --- | --- |
| `--paper` | `#f5f4f1` | `#f6f3ed` | `#f4f3ef` |
| `--ink` | `#172f42` | `#122534` | `#173044` |
| `--muted` | `#697b89` | `#65717a` | `#687d8c` |
| `--line` | `#d8dee2` | `#d0d5d2` | `#d5dde1` |
| `--blue` | `#527f9f` | `#215675` | `#5683a1` |
| `--gold` | `#efc76b` | `#ebbf58` | `#efc86d` |
| `--accent` | `#7c78a8` | — | — |
| `--deep` | `#102536` | — | — |
| `--red` | — | `#a7483f` (chapters only) | — |
| `--violet` | — | `#6b668f` (review desk only) | — |

Most deltas are a few units per channel — drift, not intent. `--blue` is the
exception: `#527f9f` vs `#215675` is a visible difference and may be deliberate.

**Decision required before any component work** (task 02). Options:

- **Canonicalize** to one palette. Recommended. The sub-perceptual deltas
  collapse; only `--blue` needs a human's eye on a before/after screenshot.
- **Keep three named surfaces** (`--surface-guide`, `--surface-chapter`,
  `--surface-lab`) if the drift turns out to be intentional per section.

Do not "just pick one" silently in the middle of another task. This is its own
reviewed change with visual diffs attached.

## The typography you see is not the typography that was written

`styles.css` line 1:

```css
@font-face{font-family:Manrope;src:url('https://fonts.googleapis.com/css2?family=DM+Mono&family=Manrope:wght@400;600;700;800&display=swap')}
```

`src:` points at a **CSS stylesheet**, not a font file. No browser can load a
font from that, so:

- every `font-family:Manrope,Arial,sans-serif` renders as **Arial**
- every `font:… 'DM Mono',monospace` renders as the **generic monospace** face
- there are no `@font-face` blocks anywhere else and zero font files in the repo
- `scripts/audit-ui.mjs` only rejects external `<link>`/`<script>` tags, so this
  slipped through the "dependency-free" audit

**This is a trap for the refactor.** Self-hosting Manrope and DM Mono in Astro
is the obvious "fix" — and it would change how every page looks, violating
"maintain the same styles". Treat it as an explicit product decision:

- **Keep current rendering**: delete the dead `@font-face`, replace the font
  stacks with what actually renders today (`Arial, sans-serif` /
  `ui-monospace, monospace`). Zero visual change. Honest CSS.
- **Adopt the intended fonts**: self-host the woff2 files in `public/fonts/`,
  add real `@font-face` with `font-display:swap`. Better-looking, but it is a
  redesign and needs sign-off plus fresh screenshots.

Default to the first unless a human says otherwise.

## Type scale

`Georgia, serif` is used deliberately for emphasis (`h1 em`, `.hero em`) and is
real — it is a system font, so it does render. Keep it.

Sizes are all `clamp()`, roughly:

| Role | Value |
| --- | --- |
| Display / `h1` | `clamp(56px,9vw,126px)` |
| Section `h2` | `clamp(36px,5vw,65px)` |
| Sub-head | `clamp(24px,3vw,38px)` |
| Pull-quote | `clamp(22px,3vw,36px)` |
| Body | `15px/1.6` … `18px` |
| Eyebrow / label | `10–11px` monospace, `letter-spacing:.08–.1em`, uppercase |

There are 14+ distinct clamp triples doing near-identical jobs. Collapse to a
named scale (`--step-0` … `--step-6`) during tokenization; the visual result
should be unchanged within a pixel or two at common viewports.

## Breakpoints

Sixteen distinct max-widths are in use: 420, 520, 530, 560, 600, 620, 720, 800,
850, 880, 900, 1000, 1050, 1100 — plus `min-width:1600px` and `min-width:2200px`.

Collapse to a named set (suggested: 560 / 800 / 1100 / 1600 / 2200) and prove
equivalence with screenshots at the *old* breakpoint values, since that is
where regressions will hide.

`@media(prefers-reduced-motion:reduce)` is already respected in several
stylesheets. Keep it — see [`../rules/animation.md`](../rules/animation.md).

## House style worth preserving

The visual identity is editorial-print: flat colour blocks, hairline `1px`
rules, uppercase monospace eyebrows with wide tracking, very tight negative
letter-spacing on display type (`-.06em` … `-.08em`), grid layouts with `gap:1px`
over a background colour to fake borders, and near-zero border-radius.

That last trick (`gap:1px` + parent background) is used everywhere. It is
intentional. Do not replace it with `border`.