tested/docs/02-design-system.md

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.