joshuaandClaude Opus 5.5
54ae9c49a1
Built from the kit specs (CLAUDE.md, docs/01-05): question index import, status seals, connections graph, Pagefind search, Scripture margin, and 157 evidence articles (drafts unless published) with sources and verified "Learn more" links. Includes link, owner-notes, a11y and publish scripts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
162 lines
10 KiB
Markdown
162 lines
10 KiB
Markdown
# 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.
|