1 files changed, 119 insertions, 0 deletions
diff --git a/docs/THEMES.md b/docs/THEMES.md
new file mode 100644
index 0000000..b9bfeca
--- /dev/null
+++ b/docs/THEMES.md
@@ -0,0 +1,119 @@
+# 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.