From 504a3136b7d5f8f628a01a3dec7bdafce8035616 Mon Sep 17 00:00:00 2001
From: dc <dc@4gl.io>
Date: Mon, 28 Sep 2026 23:15:54 +0000
Subject: [PATCH] feat(theme): dark mode by default, with a light/dark toggle

The docs site only offered Material's light scheme. This adds the dark
scheme and makes it the default.

- palette: two entries, slate first, each with a toggle. Material takes the
  first entry as the default, so the site opens dark and a sun icon in the
  header switches to light (and a moon switches back).
- dc-brand.css: the dark scheme's greys are derived from a hue variable, so
  it is pointed at the brand slate (206deg) rather than Material's neutral
  225deg, which gives the whole scheme the same cast as the header.
- dc-brand.css: the brand slate is unreadable on a dark background, so the
  dark scheme uses a light tint of it (#9fb5c6) for body links. Green stays
  the accent, which keeps link hover visible in both schemes.

Contrast, over the dark background rgb(30, 36, 41): body text 8.8:1, body
links 7.4:1, inline code 7.2:1, accent green 5.6:1, header text 10.2:1. The
light scheme is unchanged.
---
 docs/dc-brand.css | 18 ++++++++++++++++++
 mkdocs.yml        |  9 +++++++++
 2 files changed, 27 insertions(+)

diff --git a/docs/dc-brand.css b/docs/dc-brand.css
index 16eaa08..445242f 100644
--- a/docs/dc-brand.css
+++ b/docs/dc-brand.css
@@ -25,3 +25,21 @@
   --md-accent-bg-color: #fff;
   --md-accent-bg-color--light: #ffffffb3;
 }
+
+/*
+ * Dark scheme. Material derives its dark greys from a hue variable, so pointing
+ * that at the brand slate (206deg) gives the whole scheme the same cast as the
+ * header instead of Material's neutral default.
+ */
+[data-md-color-scheme='slate'] {
+  --md-hue: 206deg;
+}
+
+/*
+ * The brand slate is only readable on a light background, so the dark scheme
+ * uses a light tint of it for body links. Green stays the accent, which keeps
+ * link hover visible in both schemes.
+ */
+[data-md-color-scheme='slate'][data-md-color-primary='custom'] {
+  --md-typeset-a-color: #9fb5c6;
+}
diff --git a/mkdocs.yml b/mkdocs.yml
index b745308..9e403ad 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -116,9 +116,18 @@ theme:
   name: material
   logo: 'img/dc-logo.svg'
   palette:
+    - scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
     - scheme: default
       primary: custom
       accent: custom
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
   font:
     text: 'Montserrat'
     code: 'Ubuntu Mono'