# 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 fonts, 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.

## 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`) | the passage-lookup / navigation links |
| 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) — 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) — sand `#ede4d3` / umber `#4a3f2f`, accent
  ochre `#b8894a`.
- **benedictines** (dark) — black habit `#17130f` / parchment `#e8dcc0`,
  accent gold `#c9a227`.
- **franciscans** (dark, warm) — undyed brown `#3a2f26` / `#e0d5c3`, accent
  tau/terracotta `#a8703a`, link/refrain olive.
- **memento_mori** (dark, greyscale) — ash `#1a1a1a` / bone `#d8d4cc`;
  `#7a4a42` (dried blood) is reserved for the `.error` role only.
- **camedules** (light) — `#f2f1ee` / slate `#3a3f44`, accent slate-blue
  `#5f7a86`, refrain sage `#7a9a88`.

Liturgical seasons:

- **advent** (dark violet) — `#241b33` / `#e6e0ef`, accent violet
  `#8a6db0`, refrain rose `#b0708a`.
- **nativity** (light, white/gold) — `#faf6ec` / `#3a3226`, accent gold
  `#c9a227`, refrain evergreen `#4a7a5a`.
- **lent** (dark, ashen violet) — `#2a2530` / `#cfc8d2`, accent muted
  violet `#7a6a86`, refrain dried rose `#8a6a72`.
- **easter** (light, radiant white/gold) — `#fdfbf4` / `#33302a`, accent
  bright gold `#d4af37`.
- **pentecost** (dark, ember/red) — `#241210` / `#f0e0d8`, accent flame
  `#d9705a`, link orange `#e0975a`.
- **ordinary** (light green) — `#eef2e6` / `#33382e`, accent green
  `#5a7a3f`.

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.