# 02 — Design system

## Concept: the illuminated evidence file

Medieval scribes copied Scripture by hand in iron-gall ink, painted with mineral pigments, gilded key letters, and wrote cross-references in the margins. This site borrows that world, not as costume, but as structure:

- **Pigments become the status colors.** Verdigris (green), orpiment (yellow) and vermilion (red) were real manuscript pigments.
- **Marginalia become the layout.** Related questions and Scripture references sit in a right-hand margin beside the answer, the way scribes noted cross-references.
- **Gold leaf is rare.** Gold is used only for the brand mark and the connection arcs. Nowhere else.
- **The cross-reference arc is the signature.** The famous visualization of the Bible's cross-references draws arcs between chapters. This site draws arcs between its own questions.

Spend the boldness in one place: the arc diagram on the home page. Everything else stays quiet, readable and disciplined.

## Color tokens

Define these as CSS custom properties on `:root`. Light theme is the default; dark theme overrides them.

| Token | Light | Dark | Use |
| --- | --- | --- | --- |
| `--limewash` | `#E9ECEB` | `#121828` | Page background (cool plaster grey, not cream) |
| `--folio` | `#F7F8F7` | `#1A2236` | Raised surfaces: the answer block, menus |
| `--iron-gall` | `#1F2430` | `#E6E8EC` | Body text |
| `--iron-gall-soft` | `#4A5160` | `#A9B0BE` | Secondary text, captions |
| `--rule` | `#C9CECF` | `#2C3550` | Hairlines and borders |
| `--lapis` | `#23408E` | `#8EA6E8` | Links, focus rings, brand blue |
| `--gold-leaf` | `#B88A2C` | `#D9AE55` | Brand mark and connection arcs only |
| `--verdigris` | `#2F7D63` | `#5BB394` | Green status |
| `--orpiment` | `#B07E10` | `#E0B341` | Yellow status |
| `--vermilion` | `#B23A2E` | `#E2685B` | Red status |

Check every text/background pair for WCAG AA. Status colors on `--limewash` are used for seals and short labels; long text stays `--iron-gall`.

## The status seal

Status is never shown by color alone. Each status has a shape:

- **Green — filled circle.** Settled.
- **Yellow — half-filled circle** (left half filled). Strong but debated.
- **Red — open ring.** Open question.

The seal is an inline SVG component (`<StatusSeal status="green" />`), always paired with the status word ("Settled", "Debated", "Open") and the color name available to screen readers. The filled-ness itself tells the story: the more filled, the more settled.

## Typography

Two families, clearly distinct roles:

- **Literata** (Google Fonts, variable, has optical sizes) for headings and all reading text. It was designed for long-form reading on screens.
- **IBM Plex Sans** for interface elements: navigation, buttons, status words, filters, metadata.

Type scale (based on a 1.25 ratio, 18px body):

| Role | Font | Size / line-height | Weight | Notes |
| --- | --- | --- | --- | --- |
| Display (home hero) | Literata, opsz 72 | clamp(2.5rem, 6vw, 4.5rem) / 1.05 | 600 | Letter-spacing −0.02em |
| H1 (question title) | Literata, opsz 48 | clamp(2rem, 4vw, 2.75rem) / 1.15 | 600 | |
| H2 (article section) | Literata | 1.5rem / 1.3 | 600 | |
| H3 | Literata | 1.2rem / 1.4 | 600 | |
| Body | Literata | 1.125rem / 1.7 | 400 | Max 68 characters per line |
| UI | Plex Sans | 0.9375rem / 1.4 | 500 | Sentence case |
| Small / meta | Plex Sans | 0.8125rem / 1.4 | 400 | |

Rules:

- Sentence case everywhere. No all-caps labels, no tracked-out eyebrows above headings.
- Don't emphasize single words in headlines with color or italics.
- Scripture references render in Literata, not monospace.
- Use real punctuation: curly quotes, en dashes for ranges, true ellipses.

## Layout

### Question page (the most important page)

Desktop: a reading column with a margin column to its right.

```
┌──────────────────────────────────────────────────────────────┐
│  Tested          Questions  Connections  About      [search] │
├──────────────────────────────────────────────────────────────┤
│  The Canon › 3.4                                             │
│                                                              │
│  Why isn't Enoch in the Bible?            │  Related         │
│  ● Settled   Textual Criticism, History   │  3.5 Jude quotes │
│                                           │      Enoch       │
│  ┌─────────────────────────────────────┐  │  3.11 Ethiopian  │
│  │ Short answer                        │  │      Bible       │
│  │ It was written c. 300–100 BC by     │  │  3B.10 1 Enoch   │
│  │ several authors, not by Enoch...    │  │                  │
│  └─────────────────────────────────────┘  │  Scripture       │
│                                           │  Jude 14–15      │
│  What Scripture says                      │                  │
│  ...                                      │                  │
│  What the evidence says                   │                  │
│  ...                                      │                  │
└──────────────────────────────────────────────────────────────┘
```

- Reading column: max 68ch, left-aligned, never justified.
- Margin column: ~16rem, sticky on scroll on desktop. On mobile it moves below the article as "Keep exploring".
- The short-answer block sits on `--folio` with a 3px left border in the status color. It's the only boxed element on the page.
- Breadcrumb shows the group and question number, so readers learn where they are.

### Home page

```
┌──────────────────────────────────────────────────────────────┐
│  Tested                                             [search] │
│                                                              │
│      ╭───────╮   ╭─────────────╮      ╭──╮                   │
│   ╭──┼──╮  ╭─┼───┼──╮      ╭───┼──────┼──┼──╮                │
│  ─┴──┴──┴──┴─┴───┴──┴──────┴───┴──────┴──┴──┴─  (arc diagram) │
│   God  Creation  Canon  Text  OT  Christ ...                 │
│                                                              │
│  Every hard question about the Bible,                        │
│  weighed in the open.                                        │
│  [ Search 150 questions...                              ]    │
│                                                              │
│  ● Settled 64   ◐ Debated 78   ○ Open 7                      │
│                                                              │
│  Groups (list with counts, not cards)                        │
└──────────────────────────────────────────────────────────────┘
```

- The arc diagram fills the top of the page. Each question is a small tick on a baseline, grouped by section with section names underneath. Each Related link is a gold arc above the baseline.
- Hovering or focusing a question highlights its arcs and shows its title; clicking opens it.
- The headline and search sit under the diagram, left-aligned. Search is the main action.
- The status counts (computed from data, never hard-coded) double as filters into the question list.
- Groups render as a simple list with question counts and seal tallies, not identical cards.

### Questions list

A dense, scannable list grouped by section. Each row: number, question, seal and status word, domains. Filters for status and domain at the top; filter state lives in the URL query string so filtered views can be shared.

### Connections page

A full-screen force-directed graph (D3) of all questions. Nodes are seals in their status color, edges are hairlines in `--gold-leaf` at low opacity. Selecting a node shows its card and highlights neighbors. It must have a keyboard-accessible alternative: a plain list of each question and its links.

## Motion

- One orchestrated moment: on first home-page load, the arcs draw in left to right over about 1.2 seconds. Nothing else animates on load.
- Interaction motion only: highlight arcs on hover/focus, expand/collapse transitions under 200ms.
- With `prefers-reduced-motion: reduce`, arcs appear instantly and nothing moves.

## Components

- `StatusSeal` — the seal plus status word.
- `QuestionRow` — one row in lists.
- `Marginalia` — the right-hand Related and Scripture column.
- `ShortAnswer` — the bordered short-answer block.
- `ArcDiagram` — the home-page signature (SVG, built at build time, with small hydrated hover script).
- `ConnectionsGraph` — the D3 graph (client-side island).
- `SearchBox` — Pagefind UI, restyled to match tokens.

Border radius: 4px on inputs and buttons, 6px on the short-answer block, 0 elsewhere. No drop shadows except a single soft one on open menus.

## Brand assets (in `brand/`)

- `favicon.svg` — open book with a gold arc rising from one page to the other, crowned by a small cross. Generate `favicon.ico` (32px), `apple-touch-icon.png` (180px) and `icon-512.png` from it with `sharp` in a build script.
- `logo-full.svg` — mark plus "Tested" wordmark in Literata.
- `og-image.svg` — 1200×630 social card. Render to PNG at build time. Per-question OG images are a stretch goal.

When the mark is inlined in the header, swap its fixed fills for `var(--lapis)` (book) and `var(--gold-leaf)` (arcs) so it follows the theme. The favicon keeps its lapis tile in both themes.