# lectio-web themes

`lectio-web` renders one fixed page structure (`internal/web/static/base.css`
owns every layout, spacing and typography rule) and lets a **theme**
restyle it with colour only. A theme is a single CSS file that sets values
for a small set of role variables and role classes; nothing else.

## Colour only, no gimmicks

A theme file may set **colours** (and colours alone) on the roles listed
below. It must never:

- set a background image, gradient, shadow, animation or transition,
- change font sizes, spacing, borders' width/style, or layout,
- add rounded corners or any other chrome base.css doesn't already have.

If a rule in your theme isn't a `color`, `background`/`background-color`,
or `border-color` declaration, it doesn't belong in a theme file — with the
single exception below.

### The one non-colour override: `--theme-font`

A theme may set the custom property `--theme-font` to change the **reading
typeface** (and only the typeface — base.css still owns every size and
spacing). base.css reads it as `--font-reading: var(--theme-font, <serif>)`,
so leaving it unset keeps the default serif. base.css also declares a named
font-family palette in `:root` — `--font-serif`, `--font-serif-old`,
`--font-serif-classic`, `--font-serif-iowan`, `--font-sans`,
`--font-sans-humanist` (plus the pre-existing `--font-mono`) — all system-font
stacks, no webfonts. Every built-in theme sets `--theme-font` to one of
these, so each has its own distinct reading face (see the table below);
`memento_mori` sets it to `--font-mono`. Set this one variable if you want a
different reading face — never a bare `font-family` on an element.

**Monospace for any theme.** Independently of the theme, `lectio-web` can force
the reading face to monospace: set `web_mono = true` in your config, or flip the
**mono** checkbox in the top bar. It overrides whatever `--theme-font` the current
theme uses (the UI chrome stays as is), and persists as you change date, theme or
version. `memento_mori` simply ships with it on.

## The role variables and classes

Every built-in theme, and every user theme, **must** define all of these —
a role left undefined renders unstyled (browser default, usually black on
white regardless of the rest of the theme).

| Role | Selector / variable | Meaning |
|---|---|---|
| Page background | `--bg` (used by `body { background: var(--bg) }`) | overall page background |
| Page text | `--fg` (used by `body { color: var(--fg) }`) | default body text colour |
| Section heading | `.heading` | a reading's heading, e.g. "Ewangelia (J 20, 1. 11-18)" — the accent colour |
| Citation / subtitle | `.citation` | a section's subtitle line — muted |
| Verse number | `.vnum` | the "chapter:verse" prefix on a bible-version verse line — muted/secondary |
| Refrain | `.refrain` | a responsorial psalm's repeated response line — secondary |
| Links | `a` (and `a:hover`, `a:focus`) | any hyperlink rendered in the page |
| Borders | `.controls`, `.version-label`, `.reading-section + .reading-section`, and `.controls input/select/button` | the hairline rules base.css draws between controls, version columns and sections — `border-color` only; base.css owns the width/style |

The built-in themes also declare internal custom properties
(`--muted`, `--accent`, `--link`, `--refrain`, `--border`, …) purely to
keep the file organised — only the roles in the table above are load-bearing;
your own theme is free to skip the indirection and write literal colours
straight onto the selectors.

## Writing your own theme

1. Copy a built-in theme file (e.g.
   `internal/web/static/themes/ordinary.css`) as a starting point.
2. Save it as `${XDG_CONFIG_HOME:-~/.config}/lectio/themes/<yourname>.css`.
3. Fill in every role above with your own colours.
4. Restart `lectio-web` (or reload) — `<yourname>` now appears in the theme
   list, and a user theme file always overrides a built-in of the same
   name.

Minimal template:

```css
:root {
  --bg: #ffffff;
  --fg: #111111;
  --muted: #666666;
  --accent: #0055aa;
  --link: #0055aa;
  --refrain: #886600;
  --border: #dddddd;
}

.heading  { color: var(--accent); }
.citation { color: var(--muted); }
.vnum     { color: var(--muted); }
.refrain  { color: var(--refrain); }

a { color: var(--link); }
a:hover, a:focus { color: var(--accent); }

.controls,
.version-label,
.reading-section + .reading-section,
.controls input,
.controls select,
.controls button {
  border-color: var(--border);
}
```

## Built-in themes

Religious orders:

- **transfiguration** (dark, serif `--font-serif`) — bg `#262e28`, fg
  `#e6dec6`, accent `#d3b380` (gold), muted `#99a18c`, link/refrain `#97ad6e`
  (olive), border `#4a5347`. Verse numbers use the gold accent rather than
  muted, matching the source transfiguration theme.
- **desert_fathers** (light, Iowan serif `--font-serif-iowan`) — sand
  `#ede4d3` / umber `#4a3f2f`, accent ochre `#bd7a24`.
- **benedictines** (dark, old-style serif `--font-serif-old`) — black habit
  `#17130f` / parchment `#e8dcc0`, accent gold `#c9a227`.
- **franciscans** (dark, warm, humanist sans `--font-sans-humanist`) —
  undyed brown `#31271f` / `#e0d5c3`, accent tau/terracotta `#b56626`,
  link/refrain olive.
- **memento_mori** (dark, bare monospace `--font-mono`, no role colours) —
  ash `#121212` / bone-grey `#c9c9c9`; every reading role (muted, accent,
  link, refrain) resolves to the same plain foreground — headings and
  verse numbers are distinguished only by base.css's bold/size, not colour.
  `#7a4a42` (dried blood) is reserved for the `.error` role, the theme's
  only non-bare colour.
- **dominicans** (black & white, classic serif `--font-serif-classic`) —
  white habit `#f6f5f3` / black cappa `#1c1c1c`; greyscale only, no accent
  colour.

Liturgical seasons and feasts:

- **advent** (dark violet, classic serif `--font-serif-classic`) —
  `#241b33` / `#e6e0ef`, accent violet `#9a63d6`, refrain rose `#b0708a`.
- **nativity** (light, white/gold, old-style serif `--font-serif-old`) —
  `#faf6ec` / `#3a3226`, accent gold `#c9a227`, refrain evergreen `#4a7a5a`.
- **lent** (dark, ashen violet, serif `--font-serif`) — `#2a2530` /
  `#cfc8d2`, accent muted violet `#7a6a86`, refrain dried rose `#8a6a72`.
- **easter** (light, radiant white/gold, Iowan serif `--font-serif-iowan`) —
  `#fdfbf4` / `#33302a`, accent bright gold `#d4af37`.
- **pentecost** (red/white/gold, humanist sans `--font-sans-humanist`) —
  scarlet `#4d1418` / cream `#f5ecdb`, accent gold `#e2b74a`, refrain soft
  gold `#e0c074`.
- **ordinary** (light green, sans `--font-sans`) — `#eef2e6` / `#33382e`,
  accent green `#4f8a2a`.
- **epiphany** (dark, indigo/gold, serif `--font-serif`) — indigo night
  `#131a2e` / starlight `#e6e8f2`, accent star gold `#d9bf6a`, refrain gold
  `#c9a94e`.
- **marian** (light, blue/white/gold, old-style serif `--font-serif-old`) —
  white-blue `#f3f6fb` / navy `#23303f`, accent Marian blue `#255fbf`,
  refrain gold `#b08d3a`.

The exact hex values live in `internal/web/static/themes/*.css` — this list
is a quick reference, the CSS files are the source of truth.