From bf356cd9a3ebef0ae884197746cb7646705f8f91 Mon Sep 17 00:00:00 2001
From: inference-bot <bot@inference.coop>
Date: Tue, 3 Nov 2026 20:36:45 +0000
Subject: [PATCH] docs site: legible header in dark mode, typography in its own
 stylesheet

Dark mode: the slate scheme set the header to #3f6b3e, a dark green on a dark page, so
the bar disappeared into the background. It is now green-mid with near-black text.

Typography moves to publishing/typography.css, loaded after brand.css, and declares
Figtree on the elements themselves -- Material defines --md-text-font-family on <body>,
so a :root value loses to it by DOM proximity. Heading colours are scoped to the light
scheme, since ink is unreadable on the dark one.
---
 mkdocs.yml                |  1 +
 publishing/brand.css      | 16 +++++++++++---
 publishing/typography.css | 46 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+), 3 deletions(-)
 create mode 100644 publishing/typography.css

diff --git a/mkdocs.yml b/mkdocs.yml
index 6acc00e..4324f05 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -107,6 +107,7 @@ markdown_extensions:
 extra_css:
   # Co-op brand: palette from the website + self-hosted Figtree (SIL OFL 1.1).
   - publishing/brand.css
+  - publishing/typography.css
 
 # Keep build/tooling files out of the rendered site.
 exclude_docs: |
diff --git a/publishing/brand.css b/publishing/brand.css
index 8374128..9ad6311 100644
--- a/publishing/brand.css
+++ b/publishing/brand.css
@@ -48,7 +48,14 @@
 
 /* Dark scheme keeps the same accents; light stays the default. */
 [data-md-color-scheme="slate"] {
-  --md-primary-fg-color: #3f6b3e;
+  /* The header was #3f6b3e -- a dark green against a dark page, so the bar
+     disappeared into the background. Green-mid with near-black text keeps the
+     bar legible in dark mode while staying on brand. */
+  --md-primary-fg-color: #6ba86b;
+  --md-primary-fg-color--light: #7ab87a;
+  --md-primary-fg-color--dark: #5b8c5a;
+  --md-primary-bg-color: #16201a;
+  --md-primary-bg-color--light: rgba(22, 32, 26, 0.7);
   --md-accent-fg-color: #d98a75;
   --md-typeset-a-color: var(--green-light);
   --md-code-bg-color: #2e3328;
@@ -174,6 +181,11 @@ body,
   font-size: 2.6rem;
   font-weight: 700;
   letter-spacing: -0.02em;
+}
+/* ink is a light-scheme colour; in dark mode let Material's own fg colour apply */
+[data-md-color-scheme="default"] .md-typeset h1,
+[data-md-color-scheme="default"] .md-typeset h2,
+[data-md-color-scheme="default"] .md-typeset h3 {
   color: var(--ink);
 }
 
@@ -181,13 +193,11 @@ body,
   font-size: 1.7rem;
   font-weight: 600;
   letter-spacing: -0.01em;
-  color: var(--ink);
 }
 
 .md-typeset h3 {
   font-size: 1.25rem;
   font-weight: 600;
-  color: var(--ink);
 }
 
 .md-header__title {
diff --git a/publishing/typography.css b/publishing/typography.css
new file mode 100644
index 0000000..bff3652
--- /dev/null
+++ b/publishing/typography.css
@@ -0,0 +1,46 @@
+/* Typography for the co-op documentation site.
+ *
+ * Loaded after publishing/brand.css on purpose: the font has to be declared on the
+ * elements themselves. Material renders body and headings with
+ * var(--md-text-font-family), which it defines on <body>, so a :root-level value
+ * loses to it by DOM proximity no matter how the cascade is ordered.
+ *
+ * Figtree is self-hosted -- see the @font-face rules in brand.css. No CDN, no
+ * third-party font service.
+ */
+
+body,
+.md-typeset,
+.md-nav,
+.md-header,
+.md-tabs,
+.md-footer {
+  font-family: "Figtree", system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+}
+
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3,
+.md-typeset h4,
+.md-typeset h5,
+.md-typeset h6,
+.md-header__title,
+.md-nav__title {
+  font-family: "Figtree", system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  letter-spacing: -0.01em;
+}
+
+.md-typeset h1 { font-size: 2.6rem; font-weight: 700; letter-spacing: -0.02em; }
+.md-typeset h2 { font-size: 1.7rem; font-weight: 600; }
+.md-typeset h3 { font-size: 1.25rem; font-weight: 600; }
+.md-header__title { font-weight: 600; }
+
+/* Colour is scheme-specific, so it stays out of the rules above. */
+[data-md-color-scheme="default"] .md-typeset h1,
+[data-md-color-scheme="default"] .md-typeset h2,
+[data-md-color-scheme="default"] .md-typeset h3,
+[data-md-color-scheme="default"] .md-typeset h4 {
+  color: #2d3327;
+}