From 82cfa67951d00a228de52ac4d0bf763a09e05c96 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 06:31:04 +0000
Subject: [PATCH] site(covers): cover spec gate and build-time dark cover
 variants

Decisions 3 (gate) and 4 of the #340 visual-style ruling.

- scripts/cover-spec.mjs runs in `pnpm build`. Every cover*.svg of a post
  dated on or after SPEC_FROM (2026-11-17) is held to: at most 2 font
  sizes, title at least 56px, nothing under 28px, at most 8 text runs,
  at most 6 fill colours. Existing covers are grandfathered by the post's
  date. SPEC_FROM is the day after the last queued slot (11-16), because
  the publish queue re-dates its six pre-spec posts to their publish days.
  A queued post that slips past it takes a dated, named LATE_QUEUE entry;
  the list is empty, and a stale entry fails. --report prints one row per
  cover and never fails (88 of 88 break the spec today).
- scripts/cover-dark.mjs writes cover*.dark.svg (gitignored) beside each
  light SVG cover, before `astro build` and in `pnpm dev`. Site tokens map
  to their dark values. Every other colour goes through a luminance
  inversion that keeps WCAG contrast; the script checks this for all 1,670
  texts. The two covers with a dark ground are skipped.
- ArticleCard, the BlogPost hero, and the home and cluster cards render
  both covers lazily and hide one by :root[data-theme]. Only one is
  downloaded per theme. The dark variant takes no --cover-filter.
- svg-text-fit skips *.dark.svg, exports its parse helpers, and carries
  computed fills in checkSvg.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
---
 .gitignore                         |   2 +
 package.json                       |   4 +-
 scripts/cover-dark.mjs             | 193 +++++++++++++++++++++++++++
 scripts/cover-spec.mjs             | 204 +++++++++++++++++++++++++++++
 scripts/dev.mjs                    |   8 ++
 scripts/lib/cover-colors.mjs       | 179 +++++++++++++++++++++++++
 scripts/lib/cover-inventory.mjs    | 121 +++++++++++++++++
 scripts/svg-text-fit.mjs           |  21 +--
 src/components/ArticleCard.astro   |  54 ++++++--
 src/components/ClusterPage.astro   |  56 ++++++--
 src/components/MarketingHome.astro |  54 ++++++--
 src/layouts/BlogPost.astro         |  60 +++++++--
 src/lib/cover-variant.ts           |  30 +++++
 13 files changed, 939 insertions(+), 47 deletions(-)
 create mode 100644 scripts/cover-dark.mjs
 create mode 100644 scripts/cover-spec.mjs
 create mode 100644 scripts/lib/cover-colors.mjs
 create mode 100644 scripts/lib/cover-inventory.mjs
 create mode 100644 src/lib/cover-variant.ts

diff --git a/.gitignore b/.gitignore
index 52edfd4d..a00c05aa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,5 @@ pnpm-debug.log*
 .env.production
 # macOS
 .DS_Store
+# dark cover variants, written by scripts/cover-dark.mjs on every build and dev start
+content/blog/**/*.dark.svg
diff --git a/package.json b/package.json
index 404a33c6..cc2cc472 100644
--- a/package.json
+++ b/package.json
@@ -15,8 +15,10 @@
     "positioning:check": "node scripts/check-positioning.mjs",
     "seo:smoke": "node scripts/seo-smoke.mjs",
     "svg:lint": "node scripts/svg-text-fit.mjs",
+    "cover:spec": "node scripts/cover-spec.mjs",
+    "cover:dark": "node scripts/cover-dark.mjs",
     "og:images": "node scripts/og-images.mjs",
-    "build": "node scripts/check-positioning.mjs && node scripts/gen-zh-hant.mjs && node scripts/content-lint.mjs --published && node scripts/svg-text-fit.mjs && astro build && node scripts/og-images.mjs && node scripts/content-lint.mjs --dist",
+    "build": "node scripts/check-positioning.mjs && node scripts/gen-zh-hant.mjs && node scripts/content-lint.mjs --published && node scripts/svg-text-fit.mjs && node scripts/cover-spec.mjs && node scripts/cover-dark.mjs && astro build && node scripts/og-images.mjs && node scripts/content-lint.mjs --dist",
     "preview": "astro preview",
     "check": "astro check"
   },
diff --git a/scripts/cover-dark.mjs b/scripts/cover-dark.mjs
new file mode 100644
index 00000000..85ef5fd7
--- /dev/null
+++ b/scripts/cover-dark.mjs
@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// Dark cover variants: beside every light `cover*.svg` under content/blog,
+// write `cover*.dark.svg`, the same drawing with each colour swapped for its
+// dark counterpart (scripts/lib/cover-colors.mjs: the site's token pairs,
+// then OKLCH lightness mirroring for every other colour).
+//
+//   node scripts/cover-dark.mjs [--verbose]     (pnpm cover:dark; runs in `pnpm build` and `pnpm dev`)
+//
+// The variants are build output, not source: .gitignore keeps them out of the
+// repo and this script rewrites them from the light covers on every build, so
+// a cover edit cannot leave a stale dark copy behind. The templates
+// (src/lib/cover-variant.ts) render both images, lazy, and show one by the
+// page's `data-theme`; the hidden one is never fetched.
+//
+// What is rewritten: `fill`, `stroke`, `stop-color` and `color`, as
+// attributes, in `style` attributes and in `<style>` blocks. A drop shadow's
+// `flood-color` is left alone (a shadow stays dark in both themes). The root
+// gets the dark counterpart of black as its `fill` when it sets none, because
+// a text that names no fill inherits black, which would vanish on the dark
+// ground. A colour this script cannot read fails it, naming the file.
+//
+// Skipped: a cover whose ground (the first shape covering the canvas) is
+// already dark, OKLab L under 0.5. It needs no dark variant, and mirroring
+// would turn it into a light one. Its thumbnails keep the --cover-filter.
+//
+// Checked: every text's contrast against the shape under it. The dark variant
+// may not drop a text below the smaller of its light contrast and 3:1 (2%
+// slack for 8-bit rounding); a drop fails the build with the text and both
+// ratios (--verbose prints them all). The palette keeps contrast by
+// construction, so a failure means a new colour spelling or a token pair in
+// scripts/lib/cover-colors.mjs that does not.
+import { readdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { argv, cwd, exit } from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { contrast, darkColor, parseColor, toOklab } from './lib/cover-colors.mjs';
+import { coverInventory } from './lib/cover-inventory.mjs';
+import { checkSvg, parseXml } from './svg-text-fit.mjs';
+import { isCover } from './cover-spec.mjs';
+
+const ROOT = cwd();
+const BLOG = path.join(ROOT, 'content', 'blog');
+const VERBOSE = argv.includes('--verbose');
+const rel = (f) => path.relative(ROOT, f).split(path.sep).join('/');
+// A dark variant may not take a text under this contrast unless the light
+// cover already had it lower (then it may not go lower than that), less
+// SLACK: rounding each colour to 8-bit sRGB moves a ratio by up to 1.2%
+// (measured over the 1,670 texts of the 86 light covers).
+const MIN_CONTRAST = 3;
+const SLACK = 0.02;
+
+export const darkPath = (file) => file.replace(/\.svg$/, '.dark.svg');
+
+const COLOR_TOKEN = /#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|\b(?:white|black)\b/g;
+const KNOWN_WORDS = /^(?:none|currentcolor|transparent|inherit)$/i;
+
+function mapValue(value, where) {
+  const out = value.replace(COLOR_TOKEN, (token) => darkColor(token));
+  const rest = out.replace(/url\([^)]*\)/g, '').replace(COLOR_TOKEN, '').trim();
+  if (rest && !KNOWN_WORDS.test(rest)) throw new Error(`${where}: colour value "${value}" is not one this script reads`);
+  return out;
+}
+
+/** The dark variant of one cover's source. */
+export function darkSvg(src, where = 'svg') {
+  const PROP = '(?<![\\w-])(fill|stroke|stop-color|color)';
+  const css = (text) =>
+    text.replace(new RegExp(`${PROP}(\\s*:\\s*)([^;}"'<]+)`, 'g'), (_m, prop, sep, value) => `${prop}${sep}${mapValue(value, where)}`);
+  // Only inside markup, never in a text node: a <style> block's CSS, a style=""
+  // attribute's CSS, and presentation attributes (preceded by whitespace, in a tag).
+  let out = src.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/g, (_m, open, body, close) => `${open}${css(body)}${close}`);
+  out = out.replace(/<[a-zA-Z][^<>]*>/g, (tag) =>
+    tag
+      .replace(/(\sstyle\s*=\s*)("([^"]*)"|'([^']*)')/g, (_m, sep, quoted, dq, sq) => `${sep}${quoted[0]}${css(dq ?? sq)}${quoted[0]}`)
+      .replace(new RegExp(`(?<=\\s)${PROP.slice('(?<![\\w-])'.length)}(\\s*=\\s*)("([^"]*)"|'([^']*)')`, 'g'), (_m, prop, sep, quoted, dq, sq) => {
+        const q = quoted[0];
+        return `${prop}${sep}${q}${mapValue(dq ?? sq, where)}${q}`;
+      }));
+  const root = /<svg\b[^>]*>/.exec(out);
+  if (!root) throw new Error(`${where}: no <svg> root`);
+  if (!/\sfill\s*=/.test(root[0])) {
+    out = out.slice(0, root.index) + root[0].replace(/^<svg\b/, `<svg fill="${darkColor('black')}"`) + out.slice(root.index + root[0].length);
+  }
+  return out;
+}
+
+// Paint server id -> its stop colours, for reading a gradient host's colour.
+function gradients(src) {
+  const map = new Map();
+  const walk = (node) => {
+    for (const c of node.children ?? []) {
+      if (!c.name) continue;
+      if (/Gradient$/.test(c.name) && c.attrs.id) {
+        const stops = c.children.filter((s) => s.name === 'stop')
+          .map((s) => /(?:^|;)\s*stop-color\s*:\s*([^;]+)/.exec(s.attrs.style ?? '')?.[1] ?? s.attrs['stop-color'] ?? 'black');
+        map.set(c.attrs.id, stops);
+      }
+      walk(c);
+    }
+  };
+  walk(parseXml(src));
+  return map;
+}
+
+const colorsOf = (fill, grads) => {
+  if (!fill) return [];
+  const ref = /^url\(\s*['"]?#([^'")\s]+)/.exec(fill);
+  const list = ref ? grads.get(ref[1]) ?? [] : [fill];
+  return list.map((v) => parseColor(v)).filter(Boolean);
+};
+
+/**
+ * Each text's contrast against the shape under it (svg-text-fit's host), the
+ * worst over a gradient host's stops. A text on the bare canvas is measured
+ * against `canvasColor`, the ground the page draws behind the image.
+ */
+export function textContrasts(src, canvasColor) {
+  const grads = gradients(src);
+  const { texts } = checkSvg(src);
+  return texts.map((t) => {
+    const fg = colorsOf(t.fill, grads)[0];
+    const bgs = t.host.tag === 'canvas' ? [parseColor(canvasColor)] : colorsOf(t.host.fill, grads);
+    const ratio = fg && bgs.length ? Math.min(...bgs.map((bg) => contrast(fg, bg))) : null;
+    return { line: t.line, content: t.content, ratio };
+  });
+}
+
+async function lightCovers(dir) {
+  const out = [], stale = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const sub = await lightCovers(p);
+      out.push(...sub.out); stale.push(...sub.stale);
+    } else if (isCover(entry.name)) out.push(p);
+    else if (/^cover.*\.dark\.svg$/.test(entry.name)) stale.push(p);
+  }
+  return { out, stale };
+}
+
+async function main() {
+  const { out: covers, stale } = await lightCovers(BLOG);
+  const kept = new Set();
+  const failures = [];
+  let written = 0, unchanged = 0, skipped = 0, texts = 0;
+  for (const file of covers) {
+    const src = await readFile(file, 'utf8');
+    const { ground } = coverInventory(src);
+    if (ground && toOklab(parseColor(ground)).L < 0.5) {
+      skipped++;
+      if (VERBOSE) console.log(`${rel(file)}  ground ${ground} is already dark: no variant`);
+      continue;
+    }
+    const dark = darkSvg(src, rel(file));
+    const target = darkPath(file);
+    kept.add(target);
+    // Light text on the canvas is measured on the light page's --surface-sunk
+    // (the card's ground), dark on the dark one.
+    const before = textContrasts(src, '#e9efe9');
+    const after = textContrasts(dark, '#202b25');
+    for (let i = 0; i < before.length; i++) {
+      const [b, a] = [before[i], after[i]];
+      if (b.ratio === null || a.ratio === null) continue;
+      texts++;
+      const floor = Math.min(b.ratio, MIN_CONTRAST);
+      if (VERBOSE) console.log(`${rel(file)}:${b.line}  "${b.content.slice(0, 40)}"  ${b.ratio.toFixed(2)}:1 -> ${a.ratio.toFixed(2)}:1`);
+      if (a.ratio < floor * (1 - SLACK)) {
+        failures.push(`${rel(target)}:${a.line}  "${a.content}" contrast ${a.ratio.toFixed(2)}:1 against the shape under it, down from ${b.ratio.toFixed(2)}:1 in ${rel(file)}; the dark variant may not go under ${floor.toFixed(2)}:1`);
+      }
+    }
+    const banner = `<!-- Generated by scripts/cover-dark.mjs from ${path.basename(file)}; do not edit. -->\n`;
+    const content = banner + dark;
+    let current = null;
+    try { current = await readFile(target, 'utf8'); } catch { /* not yet written */ }
+    if (current === content) { unchanged++; continue; }
+    await writeFile(target, content);
+    written++;
+  }
+  let removed = 0;
+  for (const file of stale) {
+    if (kept.has(file)) continue;
+    await unlink(file);
+    removed++;
+  }
+  if (failures.length) {
+    for (const f of failures) console.error(f);
+    console.error(`cover-dark: FAIL — ${failures.length} text${failures.length === 1 ? '' : 's'} lose contrast in the dark variant`);
+    exit(1);
+  }
+  console.log(`cover-dark: OK — ${kept.size} dark variants (${written} written, ${unchanged} unchanged, ${removed} stale removed); ${skipped} cover${skipped === 1 ? '' : 's'} already dark, skipped; ${texts} texts keep their contrast`);
+}
+
+if (import.meta.url === pathToFileURL(argv[1] ?? '').href) await main();
diff --git a/scripts/cover-spec.mjs b/scripts/cover-spec.mjs
new file mode 100644
index 00000000..96c9d9d9
--- /dev/null
+++ b/scripts/cover-spec.mjs
@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// Cover spec gate: a blog cover is read at card size (about 344px wide, a
+// 1200-wide canvas drawn at under a third of its size), so it carries a title
+// and little else. Every `cover*.svg` of a post dated on or after SPEC_FROM
+// must keep to the spec the maintainer ruled on #340 (2026-11-02):
+//
+//   sizes   at most 2 font sizes
+//   title   the largest text (the title) is at least 56px
+//   min     no text under 28px
+//   runs    at most 8 <text> runs
+//   fills   at most 6 distinct fill colours (a gradient counts its stops)
+//
+//   node scripts/cover-spec.mjs                 (pnpm cover:spec; runs in `pnpm build`)
+//   node scripts/cover-spec.mjs --report        every cover, dated or not, one row each; never fails
+//   node scripts/cover-spec.mjs --report --verbose   …and every finding under its row
+//   node scripts/cover-spec.mjs FILE.svg ...    these files, whatever their post's date
+//
+// Sizes are in canvas px, as the SVG sets them; every cover is drawn on a
+// canvas 1200 to 1600 wide. A finding names the file, the rule, and the
+// element (by line) that breaks it.
+//
+// Existing covers are grandfathered by their post's `date`, not by a list:
+// a post first published before SPEC_FROM keeps its cover until the redo
+// card replaces it, and `--report` prints what those covers would fail.
+// The date is the post's frontmatter `date` (every locale of a post shares
+// it); a post directory with no dated .mdx is not checked.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { argv, cwd, exit } from 'node:process';
+import { pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+import { splitFrontmatter } from './lib/frontmatter.mjs';
+import { Unsupported, coverInventory } from './lib/cover-inventory.mjs';
+
+// A cover of a post dated on or after SPEC_FROM is held to the spec.
+//
+// Why 2026-11-17 and not the day this gate merged: the publish queue re-dates
+// each queued post to its publish day, and the six posts queued when the gate
+// landed (#260 11-04, #283 11-06, #263 11-09, #284 11-11, #280 11-13, #281
+// 11-16) carry covers drawn before the spec. The last queued slot is 11-16,
+// so the gate starts the day after; no new posts are being written until the
+// queue ends (maintainer: 「暂时只发不写新的」).
+//
+// If a queued post slips past 11-16, either add a dated, named one-line entry
+// for its slug to LATE_QUEUE below, or move SPEC_FROM. Do not redraw a cover
+// to get it past the gate on its publish day.
+export const SPEC_FROM = '2026-11-17';
+
+// Queued posts allowed past SPEC_FROM with a pre-spec cover, one line each:
+// { slug, date: the publish date it was re-dated to, reason }. An entry holds
+// only while the post carries exactly that date, and an entry that matches no
+// post at that date fails the gate, so the list cannot outlive the queue.
+export const LATE_QUEUE = [];
+
+export const SPEC = { maxSizes: 2, minTitle: 56, minSize: 28, maxRuns: 8, maxFills: 6 };
+
+const ROOT = cwd();
+const BLOG = path.join(ROOT, 'content', 'blog');
+const rel = (f) => path.relative(ROOT, f).split(path.sep).join('/');
+const px = (n) => `${Math.round(n * 10) / 10}px`;
+const quote = (s) => `"${s.length > 48 ? `${s.slice(0, 47)}…` : s}"`;
+export const isCover = (name) => /^cover.*\.svg$/.test(name) && !name.endsWith('.dark.svg');
+
+/** What one cover measures against each rule, for the --report row. */
+export function specSummary(src) {
+  const { texts, fills } = coverInventory(src);
+  const sizes = [...new Set(texts.flatMap((t) => t.sizes))].sort((a, b) => b - a);
+  return {
+    runs: texts.length,
+    sizes,
+    title: sizes[0] ?? 0,
+    under: texts.filter((t) => t.sizes.some((s) => s < SPEC.minSize)).length,
+    fills: fills.length,
+  };
+}
+
+/** Every finding the spec raises against one cover's source. */
+export function specFindings(src) {
+  const { texts, fills } = coverInventory(src);
+  const findings = [];
+  for (const t of texts) {
+    const small = t.sizes.filter((s) => s < SPEC.minSize);
+    if (small.length) {
+      findings.push({ rule: 'min', line: t.line, message: `<text> ${quote(t.content)} is set at ${small.map(px).join(', ')}; no text may be under ${SPEC.minSize}px` });
+    }
+  }
+  // Sizes in order of first use; the third and later are the offenders.
+  const firstAt = new Map();
+  for (const t of texts) for (const s of t.sizes) if (!firstAt.has(s)) firstAt.set(s, t);
+  if (firstAt.size > SPEC.maxSizes) {
+    const all = [...firstAt.keys()];
+    for (const s of all.slice(SPEC.maxSizes)) {
+      const t = firstAt.get(s);
+      findings.push({ rule: 'sizes', line: t.line, message: `<text> ${quote(t.content)} adds a font size, ${px(s)}; the cover uses ${all.length} (${all.map(px).join(', ')}) and at most ${SPEC.maxSizes} are allowed` });
+    }
+  }
+  const largest = texts.reduce((best, t) => (Math.max(...t.sizes) > (best ? Math.max(...best.sizes) : -1) ? t : best), null);
+  if (!largest) findings.push({ rule: 'title', line: 1, message: `the cover has no text, so no title of at least ${SPEC.minTitle}px` });
+  else if (Math.max(...largest.sizes) < SPEC.minTitle) {
+    findings.push({ rule: 'title', line: largest.line, message: `the largest text, <text> ${quote(largest.content)} at ${px(Math.max(...largest.sizes))}, is the title and must be at least ${SPEC.minTitle}px` });
+  }
+  if (texts.length > SPEC.maxRuns) {
+    const t = texts[SPEC.maxRuns];
+    findings.push({ rule: 'runs', line: t.line, message: `${texts.length} <text> runs, at most ${SPEC.maxRuns}; run ${SPEC.maxRuns + 1} is ${quote(t.content)}` });
+  }
+  if (fills.length > SPEC.maxFills) {
+    for (const f of fills.slice(SPEC.maxFills)) {
+      findings.push({ rule: 'fills', line: f.line, message: `<${f.tag}> adds fill colour ${f.color}; the cover paints ${fills.length} (${fills.map((x) => x.color).join(' ')}) and at most ${SPEC.maxFills} are allowed` });
+    }
+  }
+  return findings.sort((a, b) => a.line - b.line);
+}
+
+/** The post's first-publication date (YYYY-MM-DD) from any dated .mdx in its directory. */
+async function postDate(dir, entries) {
+  const dates = [];
+  for (const name of entries.filter((n) => n.endsWith('.mdx'))) {
+    const split = splitFrontmatter(await readFile(path.join(dir, name), 'utf8'));
+    if (!split.ok) continue;
+    const data = yaml.load(split.raw);
+    const d = data && typeof data === 'object' ? data.date : undefined;
+    if (d instanceof Date) dates.push(d.toISOString().slice(0, 10));
+    else if (typeof d === 'string' && /^\d{4}-\d{2}-\d{2}/.test(d)) dates.push(d.slice(0, 10));
+  }
+  return dates.sort()[0];
+}
+
+async function covers() {
+  const out = [];
+  const walk = async (dir) => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const names = entries.filter((e) => e.isFile()).map((e) => e.name);
+    const found = names.filter(isCover);
+    if (found.length) {
+      const date = await postDate(dir, names);
+      for (const name of found) out.push({ file: path.join(dir, name), date });
+    }
+    for (const e of entries) if (e.isDirectory()) await walk(path.join(dir, e.name));
+  };
+  await walk(BLOG);
+  return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+
+async function main() {
+  const args = argv.slice(2);
+  const report = args.includes('--report');
+  const verbose = args.includes('--verbose');
+  const named = args.filter((a) => !a.startsWith('--')).map((a) => path.resolve(a));
+  const all = named.length ? named.map((file) => ({ file, date: null })) : await covers();
+  const slugOf = (file) => path.basename(path.dirname(file));
+  const late = (c) => LATE_QUEUE.some((e) => e.slug === slugOf(c.file) && e.date === c.date);
+  const checked = named.length || report ? all : all.filter((c) => c.date && c.date >= SPEC_FROM && !late(c));
+  const excused = named.length || report ? 0 : all.filter((c) => c.date && c.date >= SPEC_FROM && late(c)).length;
+  const grandfathered = all.length - checked.length - excused;
+  const staleLate = named.length || report ? [] : LATE_QUEUE.filter((e) => !all.some((c) => slugOf(c.file) === e.slug && c.date === e.date));
+
+  const lines = [], errors = [];
+  const byRule = {};
+  let failing = 0;
+  if (report) {
+    lines.push(`spec: runs <= ${SPEC.maxRuns} · sizes <= ${SPEC.maxSizes} · title >= ${SPEC.minTitle}px · runs under ${SPEC.minSize}px = 0 · fills <= ${SPEC.maxFills}`);
+    lines.push(['cover', 'date', 'runs', 'sizes (px)', 'title', 'under', 'fills', 'broken'].join('\t'));
+  }
+  for (const { file, date } of checked) {
+    let findings, src;
+    try {
+      src = await readFile(file, 'utf8');
+      findings = specFindings(src);
+    } catch (err) {
+      if (!(err instanceof Unsupported)) throw err;
+      errors.push(`${rel(file)}: ${err.message} (the gate cannot read this cover)`);
+      continue;
+    }
+    if (findings.length) failing++;
+    const broken = [...new Set(findings.map((f) => f.rule))];
+    for (const r of broken) byRule[r] = (byRule[r] ?? 0) + 1;
+    if (report) {
+      const m = specSummary(src);
+      lines.push([rel(file), date ?? '-', m.runs, m.sizes.map((s) => Math.round(s * 10) / 10).join('/'), m.title, m.under, m.fills, broken.join(',') || 'ok'].join('\t'));
+      if (verbose) for (const f of findings) lines.push(`  :${f.line}  [${f.rule}] ${f.message}`);
+      continue;
+    }
+    for (const f of findings) lines.push(`${rel(file)}:${f.line}  [${f.rule}] ${f.message}`);
+  }
+  const rules = Object.entries(byRule).map(([r, n]) => `${r} ${n}`).join(', ');
+  const rulesNote = rules ? ` (covers breaking each rule: ${rules})` : '';
+  if (report) {
+    for (const l of lines) console.log(l);
+    for (const e of errors) console.log(e);
+    console.log(`cover-spec --report: ${failing} of ${checked.length} covers break the spec${rulesNote}; ${errors.length} unreadable. Report only: nothing fails.`);
+    return;
+  }
+  for (const l of lines) console.error(l);
+  for (const e of errors) console.error(e);
+  for (const e of staleLate) console.error(`LATE_QUEUE entry for ${e.slug} (${e.date}) matches no post with a cover dated ${e.date}; remove it`);
+  const scope = named.length ? `${checked.length} named cover${checked.length === 1 ? '' : 's'}` : `${checked.length} cover${checked.length === 1 ? '' : 's'} of posts dated on or after ${SPEC_FROM}, ${grandfathered} grandfathered by date${excused ? `, ${excused} excused by LATE_QUEUE` : ''}`;
+  if (failing || errors.length || staleLate.length) {
+    console.error(`cover-spec: FAIL — ${failing} cover${failing === 1 ? ' breaks' : 's break'} the spec${rulesNote}, ${errors.length} unreadable, ${staleLate.length} stale LATE_QUEUE entr${staleLate.length === 1 ? 'y' : 'ies'} (${scope}). Spec: at most ${SPEC.maxSizes} font sizes, title at least ${SPEC.minTitle}px, nothing under ${SPEC.minSize}px, at most ${SPEC.maxRuns} <text> runs, at most ${SPEC.maxFills} fill colours.`);
+    exit(1);
+  }
+  console.log(`cover-spec: OK — ${scope}`);
+}
+
+if (import.meta.url === pathToFileURL(argv[1] ?? '').href) await main();
diff --git a/scripts/dev.mjs b/scripts/dev.mjs
index 46b99843..7a626ee3 100644
--- a/scripts/dev.mjs
+++ b/scripts/dev.mjs
@@ -54,6 +54,14 @@ try {
   /* non-fatal — keep the dev server starting even if generation hiccups */
 }
 
+// 2.6) Write the dark cover variants (scripts/cover-dark.mjs), which the
+// templates pick up through src/lib/cover-variant.ts.
+try {
+  execSync('node scripts/cover-dark.mjs', { stdio: 'inherit', cwd: root });
+} catch {
+  /* non-fatal — without them the covers render light-only, dimmed by --cover-filter */
+}
+
 // 3) Start one clean dev server (port/host come from astro.config.mjs).
 const child = spawn(`${root}node_modules/.bin/astro`, ['dev', '--port', String(PORT)], {
   stdio: 'inherit',
diff --git a/scripts/lib/cover-colors.mjs b/scripts/lib/cover-colors.mjs
new file mode 100644
index 00000000..ecc5a23a
--- /dev/null
+++ b/scripts/lib/cover-colors.mjs
@@ -0,0 +1,179 @@
+// Colours in blog cover SVGs: reading a CSS/SVG colour literal, and the
+// light-to-dark palette that scripts/cover-dark.mjs paints each cover's dark
+// variant with.
+//
+// Two readers. scripts/cover-spec.mjs counts the distinct fill colours a
+// cover paints (the spec allows six), so it needs every spelling of one
+// colour (`white`, `#fff`, `#FFFFFF`, `rgb(255,255,255)`) to be one colour.
+// scripts/cover-dark.mjs rewrites each colour to its dark counterpart.
+//
+// ─── The dark palette ───────────────────────────────────────────────────────
+//
+// Two layers, applied in order:
+//
+//   1. TOKEN_MAP: the site's own light tokens and their dark values, copied
+//      from the two `:root` blocks in src/layouts/Base.astro, plus white. A
+//      cover drawn in the site palette lands on exactly the colours the dark
+//      page uses. Keep it in step with Base.astro when a token changes.
+//   2. Everything else (the 88 covers hold about 370 distinct literals, far
+//      too many to pair by hand) goes through `flipLightness`, which inverts
+//      the colour's luminance in the one way that keeps WCAG contrast: a
+//      dark label 7:1 on a pale card becomes a pale label 7:1 on a dark card.
+//      Hue and chroma are kept (chroma is reduced only as far as the sRGB
+//      gamut forces). White lands on the dark page's --surface, and a
+//      ground of #f8faf7 next to it.
+//
+// Not rewritten: drop-shadow `flood-color` and `lighting-color`. A shadow is
+// darkness under a card in both themes; flipping it would paint a glow.
+
+/** Light token -> dark token, from src/layouts/Base.astro (`:root` and `:root[data-theme='dark']`). */
+export const TOKEN_MAP = new Map([
+  ['#f3f7f2', '#101713'], // --bg
+  ['#fffffb', '#17201b'], // --surface
+  ['#ffffff', '#17201b'], // white panels sit at the dark --surface
+  ['#e9efe9', '#202b25'], // --surface-sunk
+  ['#151a17', '#f4f7f2'], // --ink
+  ['#515b55', '#aab6ad'], // --ink-soft
+  ['#626c66', '#8a968d'], // --muted
+  ['#dfe7df', '#2a3931'], // --line
+  ['#3d58f0', '#91a3ff'], // --accent / --ring
+  ['#eef2ff', '#202849'], // --accent-soft
+  ['#68625d', '#a8a29e'], // --status-archived
+]);
+
+const NAMED = {
+  white: '#ffffff',
+  black: '#000000',
+};
+
+/**
+ * Parse one colour literal to `{ r, g, b, a }` (0-255, alpha 0-1), or `null`
+ * for a value that is not a literal colour (`none`, `url(#g)`, `currentColor`,
+ * `transparent`, `inherit`). Throws on a colour spelling it cannot read, so a
+ * new spelling fails the build instead of passing through unmapped.
+ */
+export function parseColor(value) {
+  const v = value.trim().toLowerCase();
+  if (v === 'none' || v === 'transparent' || v === 'currentcolor' || v === 'inherit' || v.startsWith('url(')) return null;
+  if (NAMED[v]) return parseColor(NAMED[v]);
+  let m = /^#([0-9a-f]{3,4})$/.exec(v);
+  if (m) {
+    const [r, g, b, a = 'f'] = m[1].split('');
+    return { r: parseInt(r + r, 16), g: parseInt(g + g, 16), b: parseInt(b + b, 16), a: parseInt(a + a, 16) / 255 };
+  }
+  m = /^#([0-9a-f]{6})([0-9a-f]{2})?$/.exec(v);
+  if (m) {
+    const n = parseInt(m[1], 16);
+    return { r: n >> 16, g: (n >> 8) & 255, b: n & 255, a: m[2] ? parseInt(m[2], 16) / 255 : 1 };
+  }
+  m = /^rgba?\(\s*([\d.]+)\s*[, ]\s*([\d.]+)\s*[, ]\s*([\d.]+)\s*(?:[,/]\s*([\d.]+%?)\s*)?\)$/.exec(v);
+  if (m) {
+    const alpha = m[4] === undefined ? 1 : m[4].endsWith('%') ? parseFloat(m[4]) / 100 : parseFloat(m[4]);
+    return { r: Math.round(+m[1]), g: Math.round(+m[2]), b: Math.round(+m[3]), a: alpha };
+  }
+  throw new Error(`colour "${value}" is not a spelling this script reads (hex, rgb(), rgba(), white, black)`);
+}
+
+const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, '0');
+/** `#rrggbb`, with the alpha kept as `#rrggbbaa` only when it is not 1. */
+export const toHex = ({ r, g, b, a = 1 }) => `#${hex2(r)}${hex2(g)}${hex2(b)}${a < 1 ? hex2(a * 255) : ''}`;
+
+/** One canonical spelling per colour, for counting distinct colours. */
+export const canonicalColor = (value) => {
+  const c = parseColor(value);
+  return c ? toHex(c) : null;
+};
+
+// ─── OKLab (Björn Ottosson, 2020) ───────────────────────────────────────────
+
+const toLinear = (c) => {
+  const x = c / 255;
+  return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+};
+const fromLinear = (x) => 255 * (x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055);
+
+export function toOklab({ r, g, b }) {
+  const [lr, lg, lb] = [toLinear(r), toLinear(g), toLinear(b)];
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  return {
+    L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  };
+}
+
+function oklabToLinear({ L, a, b }) {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+const inGamut = (rgb) => rgb.every((x) => x >= -1e-6 && x <= 1 + 1e-6);
+
+/** WCAG relative luminance, 0-1. */
+export const luminance = ({ r, g, b }) => 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+/** WCAG contrast ratio of two colours. */
+export const contrast = (p, q) => {
+  const [hi, lo] = [luminance(p), luminance(q)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+};
+
+// The dark page's --surface (#17201b) is where white lands; DARK_K is the
+// constant that puts it there (see `flipLightness`).
+const DARK_K = 1.05 * (0.0126 + 0.05);
+
+function clipToGamut(L, a, b) {
+  let rgb = oklabToLinear({ L, a, b });
+  if (inGamut(rgb)) return rgb;
+  let lo = 0, hi = 1;
+  for (let i = 0; i < 24; i++) {
+    const mid = (lo + hi) / 2;
+    if (inGamut(oklabToLinear({ L, a: a * mid, b: b * mid }))) lo = mid; else hi = mid;
+  }
+  return oklabToLinear({ L, a: a * lo, b: b * lo });
+}
+const linearLuminance = ([r, g, b]) => 0.2126 * r + 0.7152 * g + 0.0722 * b;
+
+/**
+ * The dark counterpart of one colour, inverted so that contrast is kept.
+ *
+ * WCAG contrast is the ratio of (Y + 0.05) for two luminances Y. The map
+ * Y' = DARK_K / (Y + 0.05) - 0.05 turns that ratio upside down and leaves it
+ * the same size: two colours 4.6:1 apart in the light cover are 4.6:1 apart
+ * in the dark one, the dark one on top. DARK_K sends white (Y 1) to the dark
+ * --surface (Y 0.0126). Colours darker than Y 0.0126 would need a Y' above 1,
+ * so they all land on white: only near-black against near-black loses
+ * separation, and no cover sets text that way.
+ *
+ * The new colour keeps the old one's OKLCH hue and chroma (chroma reduced by
+ * bisection only as far as the sRGB gamut requires), and its OKLab lightness
+ * is found by bisection to give the target luminance. Alpha is kept.
+ */
+export function flipLightness(color) {
+  const { a, b } = toOklab(color);
+  const target = Math.min(1, Math.max(0, DARK_K / (luminance(color) + 0.05) - 0.05));
+  let lo = 0, hi = 1;
+  for (let i = 0; i < 30; i++) {
+    const mid = (lo + hi) / 2;
+    if (linearLuminance(clipToGamut(mid, a, b)) < target) lo = mid; else hi = mid;
+  }
+  const [r, g, bl] = clipToGamut((lo + hi) / 2, a, b).map((x) => fromLinear(Math.min(1, Math.max(0, x))));
+  return { r, g, b: bl, a: color.a ?? 1 };
+}
+
+/** The dark counterpart of a colour literal, as `#rrggbb[aa]`; `null` for a non-colour. */
+export function darkColor(value) {
+  const c = parseColor(value);
+  if (!c) return null;
+  const opaque = toHex({ ...c, a: 1 });
+  const pinned = TOKEN_MAP.get(opaque);
+  if (pinned) return toHex({ ...parseColor(pinned), a: c.a });
+  return toHex(flipLightness(c));
+}
diff --git a/scripts/lib/cover-inventory.mjs b/scripts/lib/cover-inventory.mjs
new file mode 100644
index 00000000..45818e7b
--- /dev/null
+++ b/scripts/lib/cover-inventory.mjs
@@ -0,0 +1,121 @@
+// What a blog cover SVG draws, as the cover spec counts it: its text runs
+// (each `<text>` with the font sizes and fill colours its characters are set
+// in), the fill colours of everything it paints, and its ground (the fill of
+// the first shape that covers the canvas).
+//
+// Read through the same parser and CSS cascade as scripts/svg-text-fit.mjs, so
+// a size set by a class in a `<style>` block counts exactly as a browser
+// applies it. Readers: scripts/cover-spec.mjs (the spec gate) and
+// scripts/cover-dark.mjs (which skips a cover whose ground is already dark).
+
+import { canonicalColor } from './cover-colors.mjs';
+import { NOT_RENDERED, Unsupported, computeStyle, numbers, parseCss, parseXml } from '../svg-text-fit.mjs';
+
+export { Unsupported };
+
+const SHAPES = new Set(['rect', 'circle', 'ellipse', 'polygon', 'polyline', 'path']);
+
+const textOf = (node) => (node.text !== undefined ? node.text : (node.children ?? []).map(textOf).join(''));
+
+/**
+ * @param {string} src SVG source.
+ * @returns {{
+ *   texts: { line: number, content: string, sizes: number[], fills: string[] }[],
+ *   fills: { color: string, line: number, tag: string }[],
+ *   ground: string | null,
+ *   canvas: { width: number, height: number },
+ * }}
+ *   `fills` lists each distinct fill colour once, with the first element that
+ *   paints it (a gradient fill counts as each of its stop colours).
+ */
+export function coverInventory(src) {
+  const svg = parseXml(src);
+  const vb = numbers(svg.attrs.viewBox ?? '');
+  const canvas = vb.length === 4
+    ? { width: vb[2], height: vb[3] }
+    : { width: parseFloat(svg.attrs.width) || 300, height: parseFloat(svg.attrs.height) || 150 };
+  const css = [];
+  const byId = new Map();
+  const index = (node) => {
+    for (const c of node.children ?? []) {
+      if (!c.name) continue;
+      if (c.name === 'style') css.push(c.children.map((t) => t.text ?? '').join(''));
+      if (c.attrs.id) byId.set(c.attrs.id, c);
+      index(c);
+    }
+  };
+  index(svg);
+  const rules = parseCss(css.join('\n'));
+
+  // A gradient's stop colours, following href to the gradient it inherits from.
+  const stopColors = (id, seen = new Set()) => {
+    const g = byId.get(id);
+    if (!g || seen.has(id)) throw new Unsupported(`fill references a missing paint server #${id}`);
+    if (!/Gradient$/.test(g.name)) throw new Unsupported(`fill references a <${g.name}> (#${id}), which is not modelled`);
+    seen.add(id);
+    const stops = g.children.filter((c) => c.name === 'stop');
+    if (!stops.length) {
+      const href = (g.attrs.href ?? g.attrs['xlink:href'] ?? '').replace(/^#/, '');
+      return href ? stopColors(href, seen) : [];
+    }
+    return stops.map((s) => {
+      const inline = /(?:^|;)\s*stop-color\s*:\s*([^;]+)/.exec(s.attrs.style ?? '')?.[1];
+      return canonicalColor(inline ?? s.attrs['stop-color'] ?? 'black');
+    }).filter(Boolean);
+  };
+  const paintColors = (fill) => {
+    const ref = /^url\(\s*['"]?#([^'")\s]+)['"]?\s*\)/.exec(fill);
+    if (ref) return stopColors(ref[1]);
+    const c = canonicalColor(fill);
+    return c ? [c] : [];
+  };
+
+  const texts = [];
+  const fills = new Map();
+  let ground = null;
+  const addFill = (fill, el) => {
+    for (const color of paintColors(fill)) if (!fills.has(color)) fills.set(color, { color, line: el.line, tag: el.name });
+  };
+  const paints = (style) => style.fill !== 'none' && Number(style['fill-opacity']) > 0 && Number(style.opacity) > 0;
+
+  const walkText = (text, node, style, run) => {
+    for (const child of node.children) {
+      if (child.text !== undefined) {
+        if (child.text.trim()) { run.sizes.add(style.fontSize); run.fills.add(style.fill); addFill(style.fill, text); }
+        continue;
+      }
+      if (child.name !== 'tspan' && child.name !== 'a') continue;
+      const s = computeStyle(child, rules, style);
+      if (s.display === 'none' || s.visibility === 'hidden') continue;
+      walkText(text, child, s, run);
+    }
+  };
+  const walk = (el, parentStyle) => {
+    if (NOT_RENDERED.has(el.name)) return;
+    const style = computeStyle(el, rules, parentStyle);
+    if (style.display === 'none' || Number(style.opacity) === 0) return;
+    if (el.name === 'text') {
+      if (style.visibility === 'hidden') return;
+      const run = { sizes: new Set(), fills: new Set() };
+      walkText(el, el, style, run);
+      const content = textOf(el).replace(/\s+/g, ' ').trim();
+      if (content) texts.push({ line: el.line, content, sizes: [...run.sizes], fills: [...run.fills] });
+      return;
+    }
+    if (SHAPES.has(el.name)) {
+      if (style.visibility === 'hidden' || !paints(style)) return;
+      addFill(style.fill, el);
+      if (ground === null && el.name === 'rect' && !el.attrs.transform) {
+        const w = el.attrs.width ?? '', h = el.attrs.height ?? '';
+        const full = (v, ref) => v.trim() === '100%' || parseFloat(v) >= ref;
+        if (full(w, canvas.width) && full(h, canvas.height) && !(parseFloat(el.attrs.x) > 0) && !(parseFloat(el.attrs.y) > 0)) {
+          ground = paintColors(style.fill)[0] ?? null;
+        }
+      }
+      return;
+    }
+    for (const child of el.children) if (child.name) walk(child, style);
+  };
+  walk(svg, null);
+  return { texts, fills: [...fills.values()], ground, canvas };
+}
diff --git a/scripts/svg-text-fit.mjs b/scripts/svg-text-fit.mjs
index bcea213a..95704a8d 100644
--- a/scripts/svg-text-fit.mjs
+++ b/scripts/svg-text-fit.mjs
@@ -132,9 +132,9 @@ const decodeEntities = (s) =>
     return String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1)));
   });
 
-class Unsupported extends Error {}
+export class Unsupported extends Error {}
 
-function parseXml(src) {
+export function parseXml(src) {
   const lineStarts = [0];
   for (let i = 0; i < src.length; i++) if (src[i] === '\n') lineStarts.push(i + 1);
   const lineAt = (offset) => {
@@ -218,7 +218,7 @@ function parseSelector(sel) {
   return { parts, spec };
 }
 
-function parseCss(css) {
+export function parseCss(css) {
   const rules = [];
   const clean = css.replace(/\/\*[\s\S]*?\*\//g, '');
   if (/@/.test(clean)) throw new Unsupported('CSS at-rules are not modelled');
@@ -257,7 +257,7 @@ function invert(m) {
   if (!det) return null;
   return [m[3] / det, -m[1] / det, -m[2] / det, m[0] / det, (m[2] * m[5] - m[3] * m[4]) / det, (m[1] * m[4] - m[0] * m[5]) / det];
 }
-const numbers = (s) => (s.match(/[-+]?(?:\d*\.\d+|\d+\.?)(?:e[-+]?\d+)?/gi) ?? []).map(Number);
+export const numbers = (s) => (s.match(/[-+]?(?:\d*\.\d+|\d+\.?)(?:e[-+]?\d+)?/gi) ?? []).map(Number);
 
 function parseTransform(text) {
   let m = IDENTITY;
@@ -415,11 +415,11 @@ function shapeGeometry(el, canvas) {
 
 // --- the walk --------------------------------------------------------------
 
-const NOT_RENDERED = new Set(['defs', 'marker', 'clipPath', 'mask', 'pattern', 'symbol', 'linearGradient', 'radialGradient', 'filter', 'title', 'desc', 'metadata', 'style', 'script']);
+export const NOT_RENDERED = new Set(['defs', 'marker', 'clipPath', 'mask', 'pattern', 'symbol', 'linearGradient', 'radialGradient', 'filter', 'title', 'desc', 'metadata', 'style', 'script']);
 const SHAPES = new Set(['rect', 'circle', 'ellipse', 'polygon', 'path']);
 const UNSUPPORTED_ELEMENTS = new Set(['use', 'svg', 'image', 'foreignObject', 'textPath', 'switch']);
 
-function computeStyle(el, rules, parentStyle) {
+export function computeStyle(el, rules, parentStyle) {
   const specified = {};
   for (const prop of PROPS) if (el.attrs[prop] !== undefined) specified[prop] = el.attrs[prop].trim();
   const matching = rules.filter((r) => selectorMatches(el, r.parts)).sort((p, q) => p.spec - q.spec || p.order - q.order);
@@ -688,7 +688,7 @@ export function checkSvg(src) {
     if (el.name === 'text') {
       if (style.visibility === 'hidden') return;
       const laid = layoutText(el, rules, style);
-      if (laid) texts.push({ line: el.line, content: laid.content, box: toRoot(ctm, laid.box), order: order++ });
+      if (laid) texts.push({ line: el.line, content: laid.content, box: toRoot(ctm, laid.box), fill: style.fill, order: order++ });
       return;
     }
     if (SHAPES.has(el.name)) {
@@ -696,7 +696,7 @@ export function checkSvg(src) {
       const geo = shapeGeometry(el, canvas);
       const inverse = invert(ctm);
       if (geo && inverse) {
-        painted.push({ tag: el.name, line: el.line, box: toRoot(ctm, geo.box), contains: geo.contains, inverse, evenOdd: style['fill-rule'] === 'evenodd', order: order++ });
+        painted.push({ tag: el.name, line: el.line, box: toRoot(ctm, geo.box), contains: geo.contains, inverse, evenOdd: style['fill-rule'] === 'evenodd', fill: style.fill, order: order++ });
       }
       return;
     }
@@ -748,12 +748,15 @@ export function checkSvg(src) {
 
 // --- CLI -------------------------------------------------------------------
 
+// `*.dark.svg` files are build output (scripts/cover-dark.mjs): the light
+// cover's geometry with its colours swapped, so measuring them again would
+// only count every box twice.
 async function svgFiles(dir) {
   const out = [];
   for (const entry of await readdir(dir, { withFileTypes: true })) {
     const p = path.join(dir, entry.name);
     if (entry.isDirectory()) out.push(...(await svgFiles(p)));
-    else if (entry.name.endsWith('.svg')) out.push(p);
+    else if (entry.name.endsWith('.svg') && !entry.name.endsWith('.dark.svg')) out.push(p);
   }
   return out.sort();
 }
diff --git a/src/components/ArticleCard.astro b/src/components/ArticleCard.astro
index efcd408e..5cdd922b 100644
--- a/src/components/ArticleCard.astro
+++ b/src/components/ArticleCard.astro
@@ -4,6 +4,7 @@ import type { Locale } from '../lib/i18n';
 import { formatDate, postPath, STATUS_COLOR, ui } from '../lib/i18n';
 import type { LocalePost } from '../lib/posts';
 import { termLabel } from '../lib/terms';
+import { darkCover } from '../lib/cover-variant';
 import { phraseHtml } from '../../scripts/lib/cjk-phrases.mjs';
 
 interface Props {
@@ -32,6 +33,10 @@ const thumbSizes =
     ? '(min-width: 1024px) 640px, calc(100vw - 2rem)'
     : '(max-width: 640px) calc(100vw - 2rem), (max-width: 900px) calc(55vw - 2rem), 400px';
 const thumbLoading = variant === 'feature' ? 'eager' : 'lazy';
+// An SVG cover with a dark variant (src/lib/cover-variant.ts) is drawn twice,
+// one image per theme. Both are lazy, the feature card's too: a display:none
+// image is only skipped when it is lazy, so an eager pair would fetch both.
+const coverDark = darkCover(post.entry.filePath, d.cover);
 ---
 
 <li class:list={['article-item', variant]}>
@@ -39,14 +44,37 @@ const thumbLoading = variant === 'feature' ? 'eager' : 'lazy';
     <div class="thumb">
       {d.cover ? (
         d.cover.format === 'svg' ? (
-          <img
-            src={d.cover.src}
-            alt={d.title}
-            width={d.cover.width}
-            height={d.cover.height}
-            loading={thumbLoading}
-            decoding="async"
-          />
+          coverDark ? (
+            <>
+              <img
+                class="cover-light"
+                src={d.cover.src}
+                alt={d.title}
+                width={d.cover.width}
+                height={d.cover.height}
+                loading="lazy"
+                decoding="async"
+              />
+              <img
+                class="cover-dark"
+                src={coverDark.src}
+                alt={d.title}
+                width={coverDark.width}
+                height={coverDark.height}
+                loading="lazy"
+                decoding="async"
+              />
+            </>
+          ) : (
+            <img
+              src={d.cover.src}
+              alt={d.title}
+              width={d.cover.width}
+              height={d.cover.height}
+              loading={thumbLoading}
+              decoding="async"
+            />
+          )
         ) : (
           <Image
             src={d.cover}
@@ -139,6 +167,16 @@ const thumbLoading = variant === 'feature' ? 'eager' : 'lazy';
   .card:hover .thumb :global(img) {
     transform: scale(1.035);
   }
+  /* One cover per theme (src/lib/cover-variant.ts). The dark variant is drawn
+     dark, so it takes no --cover-filter dimming; raster covers and SVGs with
+     no variant keep it. */
+  :global(:root:not([data-theme='dark'])) .cover-dark,
+  :global(:root[data-theme='dark']) .cover-light {
+    display: none;
+  }
+  .thumb .cover-dark {
+    filter: none;
+  }
   .thumb-fallback {
     display: flex;
     flex-direction: column;
diff --git a/src/components/ClusterPage.astro b/src/components/ClusterPage.astro
index 00901396..c4ac476d 100644
--- a/src/components/ClusterPage.astro
+++ b/src/components/ClusterPage.astro
@@ -5,6 +5,7 @@ import type { Cluster } from '../lib/clusters';
 import { clusterCopy, clusterLabels } from '../lib/cluster-i18n';
 import { blogPath, formatDate, postPath, type Locale } from '../lib/i18n';
 import { builtHubLocale } from '../lib/posts';
+import { darkCover } from '../lib/cover-variant';
 import { termBySlug, termHref, termLabel } from '../lib/terms';
 import { phraseHtml } from '../../scripts/lib/cjk-phrases.mjs';
 
@@ -14,7 +15,10 @@ interface Props {
   posts: { slug: string; entry: CollectionEntry<'blog'> }[];
 }
 
-const { cluster, locale, posts } = Astro.props;
+const { cluster, locale } = Astro.props;
+// `coverDark`: an SVG cover's dark variant (src/lib/cover-variant.ts); the
+// card then draws both images, lazy, one shown per theme.
+const posts = Astro.props.posts.map((post) => ({ ...post, coverDark: darkCover(post.entry.filePath, post.entry.data.cover) }));
 // zh and ja headings carry a <wbr> between phrases (scripts/lib/cjk-phrases.mjs).
 const ph = (text: string): string => phraseHtml(text, locale);
 const copy = clusterCopy(cluster, locale);
@@ -101,18 +105,41 @@ const CARD_SIZES = '(max-width: 640px) calc(100vw - 2rem), 400px';
       <a href={blogPath(locale)}>{labels.allArticles} <span>→</span></a>
     </div>
     <div class="article-grid">
-      {posts.map(({ slug, entry }) => (
+      {posts.map(({ slug, entry, coverDark }) => (
         <a class="article-card" href={postPath(locale, slug)}>
           {entry.data.cover &&
             (entry.data.cover.format === 'svg' ? (
-              <img
-                src={entry.data.cover.src}
-                alt={entry.data.title}
-                width="360"
-                height="380"
-                loading="lazy"
-                decoding="async"
-              />
+              coverDark ? (
+                <>
+                  <img
+                    class="cover-light"
+                    src={entry.data.cover.src}
+                    alt={entry.data.title}
+                    width="360"
+                    height="380"
+                    loading="lazy"
+                    decoding="async"
+                  />
+                  <img
+                    class="cover-dark"
+                    src={coverDark.src}
+                    alt={entry.data.title}
+                    width="360"
+                    height="380"
+                    loading="lazy"
+                    decoding="async"
+                  />
+                </>
+              ) : (
+                <img
+                  src={entry.data.cover.src}
+                  alt={entry.data.title}
+                  width="360"
+                  height="380"
+                  loading="lazy"
+                  decoding="async"
+                />
+              )
             ) : (
               <Image
                 src={entry.data.cover}
@@ -349,6 +376,15 @@ const CARD_SIZES = '(max-width: 640px) calc(100vw - 2rem), 400px';
     object-fit: cover;
     filter: var(--cover-filter);
   }
+  /* One cover per theme (src/lib/cover-variant.ts); the dark variant is drawn
+     dark and takes no --cover-filter dimming. */
+  :global(:root:not([data-theme='dark'])) .article-card .cover-dark,
+  :global(:root[data-theme='dark']) .article-card .cover-light {
+    display: none;
+  }
+  .article-card img.cover-dark {
+    filter: none;
+  }
   .article-card div {
     padding: 1rem;
   }
diff --git a/src/components/MarketingHome.astro b/src/components/MarketingHome.astro
index fbc8ec43..08cc6ed3 100644
--- a/src/components/MarketingHome.astro
+++ b/src/components/MarketingHome.astro
@@ -4,6 +4,7 @@ import demoPoster from '../assets/objectos-home-demo-poster.png';
 import demoVideo from '../assets/objectos-home-demo.mp4';
 import demoScript from '../assets/objectos-home-demo.js?url&no-inline';
 import { getPostsInLocale } from '../lib/posts';
+import { darkCover } from '../lib/cover-variant';
 import { blogPath, formatDate, postPath, ui, type Locale } from '../lib/i18n';
 import { s2t } from '../lib/zhconvert';
 import { homeCopy } from '../lib/home';
@@ -65,9 +66,12 @@ const aiCardHrefs = [
   marketingPagePath(locale, 'ai'),
   marketingPagePath(locale, 'mcp'),
 ];
+// `coverDark`: an SVG cover's dark variant (src/lib/cover-variant.ts); the
+// card then draws both images, lazy, one shown per theme.
 const posts = (await getPostsInLocale(locale))
   .filter((post) => post.entry.data.status !== 'archived')
-  .slice(0, 3);
+  .slice(0, 3)
+  .map((post) => ({ ...post, coverDark: darkCover(post.entry.filePath, post.entry.data.cover) }));
 
 const topicLink = (slug: string) => {
   const term = termBySlug(slug);
@@ -450,14 +454,37 @@ const demoCopy = DEMO_COPY[locale];
           <a class="article" href={postPath(locale, post.slug)}>
             {post.entry.data.cover &&
               (post.entry.data.cover.format === 'svg' ? (
-                <img
-                  src={post.entry.data.cover.src}
-                  alt={post.entry.data.title}
-                  width={post.entry.data.cover.width}
-                  height={post.entry.data.cover.height}
-                  loading="lazy"
-                  decoding="async"
-                />
+                post.coverDark ? (
+                  <>
+                    <img
+                      class="cover-light"
+                      src={post.entry.data.cover.src}
+                      alt={post.entry.data.title}
+                      width={post.entry.data.cover.width}
+                      height={post.entry.data.cover.height}
+                      loading="lazy"
+                      decoding="async"
+                    />
+                    <img
+                      class="cover-dark"
+                      src={post.coverDark.src}
+                      alt={post.entry.data.title}
+                      width={post.coverDark.width}
+                      height={post.coverDark.height}
+                      loading="lazy"
+                      decoding="async"
+                    />
+                  </>
+                ) : (
+                  <img
+                    src={post.entry.data.cover.src}
+                    alt={post.entry.data.title}
+                    width={post.entry.data.cover.width}
+                    height={post.entry.data.cover.height}
+                    loading="lazy"
+                    decoding="async"
+                  />
+                )
               ) : (
                 <Image
                   src={post.entry.data.cover}
@@ -1340,6 +1367,15 @@ const demoCopy = DEMO_COPY[locale];
     box-shadow: 0 18px 42px -34px rgba(var(--shadow), 0.52);
     filter: var(--cover-filter);
   }
+  /* One cover per theme (src/lib/cover-variant.ts); the dark variant is drawn
+     dark and takes no --cover-filter dimming. */
+  :global(:root:not([data-theme='dark'])) .article .cover-dark,
+  :global(:root[data-theme='dark']) .article .cover-light {
+    display: none;
+  }
+  .article img.cover-dark {
+    filter: none;
+  }
   .article time {
     color: var(--muted);
     font: 600 0.68rem/1 var(--font-mono);
diff --git a/src/layouts/BlogPost.astro b/src/layouts/BlogPost.astro
index d2130a0a..c95b4603 100644
--- a/src/layouts/BlogPost.astro
+++ b/src/layouts/BlogPost.astro
@@ -7,6 +7,7 @@ import { phraseHtml } from '../../scripts/lib/cjk-phrases.mjs';
 import { formatDate, ui, blogPath, postPath, STATUS_COLOR, type Locale } from '../lib/i18n';
 import { termBySlug, termHref, termLabel } from '../lib/terms';
 import { getPostsInLocale, isPublicPost } from '../lib/posts';
+import { darkCover } from '../lib/cover-variant';
 import { clusterCopy, clusterLabels } from '../lib/cluster-i18n';
 import { CLUSTERS, clusterPath } from '../lib/clusters';
 import { ORGANIZATION_ID } from '../lib/organization';
@@ -54,6 +55,11 @@ const coverFile: string | undefined = entry?.filePath ? postCoverFile(entry.file
 if (data.cover && !coverFile) {
   throw new Error(`BlogPost: ${locale}/${slug} has a cover, but its file could not be resolved`);
 }
+// An SVG cover with a dark variant (src/lib/cover-variant.ts) is drawn twice,
+// one image per theme. Both are lazy: a display:none image is only skipped
+// when it is lazy, so the eager, high-priority pair would fetch both. The
+// visible one sits in the first viewport and is requested at first layout.
+const coverDark = darkCover(entry?.filePath, data.cover);
 const shareImage = coverFile
   ? { url: absoluteUrl(ogImagePath(coverFile)), width: OG_IMAGE.width, height: OG_IMAGE.height, alt: data.title }
   : undefined;
@@ -287,16 +293,41 @@ const bodyHtml = annotateBody(await Astro.slots.render('default'));
       {
         data.cover &&
           (data.cover.format === 'svg' ? (
-            <img
-              class="cover"
-              src={data.cover.src}
-              alt={data.title}
-              width={data.cover.width}
-              height={data.cover.height}
-              loading="eager"
-              decoding="async"
-              fetchpriority="high"
-            />
+            coverDark ? (
+              <>
+                <img
+                  class="cover cover-light"
+                  src={data.cover.src}
+                  alt={data.title}
+                  width={data.cover.width}
+                  height={data.cover.height}
+                  loading="lazy"
+                  decoding="async"
+                  fetchpriority="high"
+                />
+                <img
+                  class="cover cover-dark"
+                  src={coverDark.src}
+                  alt={data.title}
+                  width={coverDark.width}
+                  height={coverDark.height}
+                  loading="lazy"
+                  decoding="async"
+                  fetchpriority="high"
+                />
+              </>
+            ) : (
+              <img
+                class="cover"
+                src={data.cover.src}
+                alt={data.title}
+                width={data.cover.width}
+                height={data.cover.height}
+                loading="eager"
+                decoding="async"
+                fetchpriority="high"
+              />
+            )
           ) : (
             <Image
               class="cover"
@@ -477,6 +508,15 @@ const bodyHtml = annotateBody(await Astro.slots.render('default'));
       box-shadow: 0 28px 70px -48px rgba(var(--shadow), 0.68);
       filter: var(--cover-filter);
     }
+    /* One cover per theme (src/lib/cover-variant.ts); the dark variant is
+       drawn dark and takes no --cover-filter dimming. */
+    :global(:root:not([data-theme='dark'])) .cover-dark,
+    :global(:root[data-theme='dark']) .cover-light {
+      display: none;
+    }
+    .cover.cover-dark {
+      filter: none;
+    }
     .tags {
       list-style: none;
       display: flex;
diff --git a/src/lib/cover-variant.ts b/src/lib/cover-variant.ts
new file mode 100644
index 00000000..13f87c20
--- /dev/null
+++ b/src/lib/cover-variant.ts
@@ -0,0 +1,30 @@
+// The dark variant of a post's SVG cover, for the templates that draw covers
+// (ArticleCard, the BlogPost hero, the home and cluster article cards).
+//
+// scripts/cover-dark.mjs writes `cover*.dark.svg` beside every light SVG
+// cover before `astro build` (and `pnpm dev`); this module imports them all,
+// so each one is emitted as a hashed asset like the light cover. A cover with
+// no variant (a raster cover, one whose ground is already dark, or a dev
+// server started with `astro dev` alone) gets `undefined`, and the template
+// draws the one image as before.
+//
+// How the templates use it: both images are rendered with loading="lazy"
+// and the pair carries the classes `cover-light` / `cover-dark`; each
+// template's CSS hides the one that does not match `:root[data-theme]`. A
+// lazy image that is display:none never reaches the viewport, so the browser
+// never fetches it: one cover is downloaded per theme. The theme attribute is
+// set before first paint from the saved choice or prefers-color-scheme
+// (src/layouts/Base.astro), so it covers both.
+import path from 'node:path';
+import { postCoverFile } from '../../scripts/lib/og-image.mjs';
+
+const DARK = import.meta.glob<ImageMetadata>('/content/blog/**/*.dark.svg', { eager: true, import: 'default' });
+
+/** The dark variant of the cover named by the post at `filePath`, if one was generated. */
+export function darkCover(filePath: string | undefined, cover: ImageMetadata | undefined): ImageMetadata | undefined {
+  if (!filePath || cover?.format !== 'svg') return undefined;
+  const light = postCoverFile(filePath);
+  if (!light) return undefined;
+  const key = `/${path.relative(process.cwd(), light).split(path.sep).join('/')}`.replace(/\.svg$/, '.dark.svg');
+  return DARK[key];
+}