diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs
index b22ed46..4424090 100644
--- a/docs-site/astro.config.mjs
+++ b/docs-site/astro.config.mjs
@@ -45,7 +45,15 @@ export default defineConfig({
       // The mark IS the word "cuckoo" — a rebus. replacesTitle stops Starlight
       // rendering the title text beside it (which would read "…escapement The
       // Cuckoo Escapement"). The SVG's aria-label carries the full name.
-      logo: { src: "./src/assets/logo.svg", replacesTitle: true },
+      //
+      // Two variants, because Starlight renders the logo as an <img> and CSS
+      // cannot reach inside it. The single cream-on-black logo was invisible in
+      // the light theme — cream wordmark on a cream page.
+      logo: {
+        light: "./src/assets/logo-light.svg",
+        dark: "./src/assets/logo.svg",
+        replacesTitle: true,
+      },
       favicon: "/favicon.svg",
       customCss: ["./src/styles/brass.css"],
 
diff --git a/docs-site/src/assets/logo-light.svg b/docs-site/src/assets/logo-light.svg
new file mode 100644
index 0000000..1586853
--- /dev/null
+++ b/docs-site/src/assets/logo-light.svg
@@ -0,0 +1,43 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 78" role="img" aria-label="The Cuckoo Escapement">
+  <style>
+    .mono  { font-family: "JetBrains Mono","SF Mono",Menlo,monospace; font-weight: 700; }
+    .cream { fill: #2b2721; }
+    .gear  { fill: none; stroke: #a97c1f; stroke-width: 1.9; stroke-linejoin: round; }
+    .rim   { fill: none; stroke: #a97c1f; stroke-width: 1.3; opacity: .8; }
+    .tick  { stroke: #a97c1f; stroke-width: 1.4; opacity: .5; stroke-linecap: round; }
+    .head  { fill: #2b2721; }
+    .eye   { fill: #faf7f1; }
+  </style>
+
+  <!-- one ring, two readings: gear teeth outside (escapement), hour ticks inside (dial) -->
+  <path d="M 30.61 13.60 L 34.99 6.14 L 41.01 6.14 L 45.39 13.60 L 46.36 13.91 L 54.29 10.46 L 59.16 14.00 L 58.33 22.60 L 58.93 23.43 L 67.37 25.29 L 69.23 31.02 L 63.49 37.49 L 63.49 38.51 L 69.23 44.98 L 67.37 50.71 L 58.93 52.57 L 58.33 53.40 L 59.16 62.00 L 54.29 65.54 L 46.36 62.09 L 45.39 62.40 L 41.01 69.86 L 34.99 69.86 L 30.61 62.40 L 29.64 62.09 L 21.71 65.54 L 16.84 62.00 L 17.67 53.40 L 17.07 52.57 L 8.63 50.71 L 6.77 44.98 L 12.51 38.51 L 12.51 37.49 L 6.77 31.02 L 8.63 25.29 L 17.07 23.43 L 17.67 22.60 L 16.84 14.00 L 21.71 10.46 L 29.64 13.91 Z" class="gear"/>
+  <circle cx="38.0" cy="38.0" r="23.5" class="rim"/>
+  <g class="tick">
+    <line x1="38.00" y1="15.50" x2="38.00" y2="18.50"/>
+    <line x1="49.25" y1="18.51" x2="47.75" y2="21.11"/>
+    <line x1="57.49" y1="26.75" x2="54.89" y2="28.25"/>
+    <line x1="60.50" y1="38.00" x2="57.50" y2="38.00"/>
+    <line x1="57.49" y1="49.25" x2="54.89" y2="47.75"/>
+    <line x1="49.25" y1="57.49" x2="47.75" y2="54.89"/>
+    <line x1="38.00" y1="60.50" x2="38.00" y2="57.50"/>
+    <line x1="26.75" y1="57.49" x2="28.25" y2="54.89"/>
+    <line x1="18.51" y1="49.25" x2="21.11" y2="47.75"/>
+    <line x1="15.50" y1="38.00" x2="18.50" y2="38.00"/>
+    <line x1="18.51" y1="26.75" x2="21.11" y2="28.25"/>
+    <line x1="26.75" y1="18.51" x2="28.25" y2="21.11"/>
+  </g>
+
+  <!-- the cuckoo, head only, beak open mid-call -->
+  <g class="head">
+    <!-- crest: three feathers, swept back. this is what says "bird" -->
+    <path d="M 30 26 L 27 16 L 35 23 Z"/>
+    <path d="M 36 23 L 36 13 L 42 22 Z"/>
+    <path d="M 42 23 L 46 15 L 47 25 Z"/>
+    <circle cx="37" cy="39" r="13.5"/>                 <!-- big round head -->
+    <path d="M 47 33.5 L 62 34.5 L 48.5 40 Z"/>        <!-- upper beak: SHORT + chunky -->
+    <path d="M 47.5 42 L 60 46.5 L 46 44 Z"/>          <!-- lower beak, gape open -->
+  </g>
+  <circle cx="40.5" cy="35.5" r="2.2" class="eye"/>
+
+  <text x="92" y="52" class="mono cream" font-size="33">escapement</text>
+</svg>