fluxopt · FBumann · Sep 25, 2026 · Sep 25, 2026 · Sep 25, 2026 · Sep 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ it releases that version ([RELEASING.md](https://github.com/fluxopt/specsolve/bl
 
 ## Upcoming version
 
+- docs: the site follows the reader's light or dark setting in its own violet colour, with code, diagrams and footnotes readable in both ([#1767](https://github.com/fluxopt/specsolve/pull/1767))
 - feat!: specsolve requires mathspec 0.2.0 and uses its words spec and model, so an archive holds its spec as spec.yaml ([#1768](https://github.com/fluxopt/specsolve/pull/1768))
 - docs: every link to the language's documentation points at mathspec.readthedocs.io ([#1764](https://github.com/fluxopt/specsolve/pull/1764))
 - fix: the PyPI page links the docs, issues and changelog, and a stale saved answer says the layout moves before 1.0 ([#1763](https://github.com/fluxopt/specsolve/pull/1763))

diff --git a/docs/about/architecture.md b/docs/about/architecture.md
@@ -99,14 +99,14 @@ flowchart TB
 
     BUILD --> MODEL["<b>a linopy.Model</b> — the oracle stops here<br/>solved by the tests, and compared with the Result"]
 
-    classDef laneL fill:#fdf6ec,stroke:#b7791f,stroke-width:2px,color:#111
-    classDef laneR fill:#f0f7f0,stroke:#3a7d44,stroke-width:2px,color:#111
-    classDef laneE fill:#eef1fb,stroke:#4a5fc1,stroke-width:2px,color:#111
-    classDef laneT fill:#f7f0f7,stroke:#8b3a7d,stroke-width:2px,color:#111
-    classDef waist fill:#e9edfa,stroke:#4a5fc1,stroke-width:3px,color:#111
-    classDef flat fill:#fffdf5,stroke:#8a8578,stroke-width:2px,stroke-dasharray:4 3,color:#111
-    classDef data fill:#fdf4e8,stroke:#b7791f,stroke-width:1.5px,color:#111
-    classDef out fill:#eef6ee,stroke:#3a7d44,stroke-width:2px,color:#111
+    classDef laneL stroke:#b7791f,stroke-width:2px
+    classDef laneR stroke:#3a7d44,stroke-width:2px
+    classDef laneE stroke:#4a5fc1,stroke-width:2px
+    classDef laneT stroke:#8b3a7d,stroke-width:2px
+    classDef waist stroke:#4a5fc1,stroke-width:3px
+    classDef flat stroke:#8a8578,stroke-width:2px,stroke-dasharray:4 3
+    classDef data stroke:#b7791f,stroke-width:1.5px
+    classDef out stroke:#3a7d44,stroke-width:2px
     class MS laneL
     class REL laneR
     class LIN laneE
@@ -161,9 +161,9 @@ flowchart LR
     AST --> RUN["<b>run it</b><br/>solver · LP/MPS file"]
     DATA[("your data<br/>parquet · polars · any Arrow table")] --> RUN
     RUN --> ANS(["<b>your answers</b><br/>tables you can join"])
-    classDef built fill:#eef6ee,stroke:#3a7d44,stroke-width:1.5px,color:#111
-    classDef waist fill:#e9edfa,stroke:#4a5fc1,stroke-width:3px,color:#111
-    classDef data fill:#fdf4e8,stroke:#b7791f,stroke-width:1.5px,color:#111
+    classDef built stroke:#3a7d44,stroke-width:1.5px
+    classDef waist stroke:#4a5fc1,stroke-width:3px
+    classDef data stroke:#b7791f,stroke-width:1.5px
     class Y,SHOW,CHECK,RUN,ANS built
     class AST waist
     class DATA data

diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -3,6 +3,7 @@
  * Light = darkened-Monokai variant (dark hues on light bg for readability);
  * Dark = classic Monokai. YAML is what most of this site's code blocks are,
  * so the string and key colours are the ones worth checking after an edit.
+ * Every colour holds 4.5:1 on its code background.
  */
 
 :root,
@@ -11,132 +12,72 @@
   --md-code-bg-color: #fafafa;
 
   --md-code-hl-keyword-color:     #d11f72;   /* darkened pink */
-  --md-code-hl-string-color:      #998800;   /* mustard yellow */
+  --md-code-hl-string-color:      #7f7100;   /* mustard yellow */
   --md-code-hl-number-color:      #6f42c1;   /* purple */
-  --md-code-hl-function-color:    #4d8d04;   /* green */
+  --md-code-hl-function-color:    #457e04;   /* green */
   --md-code-hl-comment-color:     #75715e;   /* olive-gray */
   --md-code-hl-name-color:        #272822;   /* default text */
   --md-code-hl-operator-color:    #d11f72;   /* pink */
   --md-code-hl-punctuation-color: #272822;
   --md-code-hl-constant-color:    #6f42c1;   /* purple — None, True, False */
-  --md-code-hl-special-color:     #4d8d04;   /* green — decorators */
-  --md-code-hl-variable-color:    #d35400;   /* burnt orange */
+  --md-code-hl-special-color:     #457e04;   /* green — decorators */
+  --md-code-hl-variable-color:    #c14d00;   /* burnt orange */
   --md-code-hl-generic-color:     #272822;
 }
 
 [data-md-color-scheme="slate"] {
   --md-code-fg-color: #f8f8f2;
-  /* Derived from slate body bg hsla(var(--md-hue), 15%, 14%, 1):
-     same hue, less saturated (6%), brighter (18%). Subtle slate hint, mostly gray. */
+  /* Slate's hue, desaturated to a grey that stands off the page. */
   --md-code-bg-color: hsla(var(--md-hue), 6%, 18%, 1);
 
-  --md-code-hl-keyword-color:     #f92672;   /* hot pink */
+  --md-code-hl-keyword-color:     #fb5d95;   /* hot pink */
   --md-code-hl-string-color:      #e6db74;   /* yellow */
   --md-code-hl-number-color:      #ae81ff;   /* purple */
   --md-code-hl-function-color:    #a6e22e;   /* green */
-  --md-code-hl-comment-color:     #75715e;   /* olive-gray */
+  --md-code-hl-comment-color:     #9b9682;   /* olive-gray */
   --md-code-hl-name-color:        #f8f8f2;   /* default text */
-  --md-code-hl-operator-color:    #f92672;   /* pink */
+  --md-code-hl-operator-color:    #fb5d95;   /* pink */
   --md-code-hl-punctuation-color: #f8f8f2;
   --md-code-hl-constant-color:    #ae81ff;   /* purple — None, True, False */
   --md-code-hl-special-color:     #a6e22e;   /* green — decorators */
   --md-code-hl-variable-color:    #fd971f;   /* orange */
   --md-code-hl-generic-color:     #f8f8f2;
 }
 
-/* --- Custom palette: soft dark slate primary + sky accent --- */
+/* --- Palette: one violet hue, as primary and accent ---
+ * In the modern variant the primary colour paints links, the primary button and
+ * the progress bar; the accent paints hover, focus and the active navigation
+ * entry. The primary is the shade that rests, the accent the one that answers
+ * the pointer. Links hold 4.5:1 on either background, and the dark scheme puts
+ * dark text on its light button.
+ */
 
-:root,
 [data-md-color-primary="custom"] {
-  --md-primary-fg-color: #334155;          /* slate-700 — soft dark header */
-  --md-primary-fg-color--light: #475569;   /* slate-600 */
-  --md-primary-fg-color--dark: #1e293b;    /* slate-800 — hover/active */
+  --md-primary-fg-color: #6d28d9; /* violet-700 */
+  --md-primary-fg-color--light: #7c3aed; /* violet-600 */
+  --md-primary-fg-color--dark: #5b21b6; /* violet-800 */
   --md-primary-bg-color: #ffffff;
   --md-primary-bg-color--light: #ffffffb3;
 }
 
-/* Light-mode accent: deeper sky for contrast on white */
 [data-md-color-accent="custom"] {
-  --md-accent-fg-color: #0284c7;           /* sky-600 */
-  --md-accent-fg-color--transparent: rgba(2, 132, 199, 0.1);
+  --md-accent-fg-color: #7c3aed; /* violet-600 */
+  --md-accent-fg-color--transparent: #7c3aed1a;
   --md-accent-bg-color: #ffffff;
   --md-accent-bg-color--light: #ffffffb3;
 }
 
-/* Dark-mode accent: brighter sky for contrast on slate background */
-[data-md-color-scheme="slate"][data-md-color-accent="custom"] {
-  --md-accent-fg-color: #38bdf8;           /* sky-400 — brighter for dark bg */
-  --md-accent-fg-color--transparent: rgba(56, 189, 248, 0.15);
-}
-
-/* Light-mode resting link: brighter than the accent for prominence.
-   Hover keeps the accent (sky-600) for darken-on-hover affordance. */
-.md-typeset a {
-  color: #0284c7;                          /* sky-600 */
-}
-
-.md-typeset a:hover {
-  color: #0ea5e9;                          /* sky-500 — brighten on hover */
-}
-
-[data-md-color-scheme="slate"] .md-typeset a {
-  color: #38bdf8;                          /* sky-400 */
+[data-md-color-scheme="slate"][data-md-color-primary="custom"] {
+  --md-primary-fg-color: #a78bfa; /* violet-400 */
+  --md-primary-fg-color--light: #c4b5fd; /* violet-300 */
+  --md-primary-fg-color--dark: #8b5cf6; /* violet-500 */
+  --md-primary-bg-color: #0f172a; /* slate-900 */
+  --md-primary-bg-color--light: #0f172ab3;
 }
 
-[data-md-color-scheme="slate"] .md-typeset a:hover {
-  color: #7dd3fc;                          /* sky-300 */
-}
-
-/* The active entry in the right-hand table of contents, and a `code` span
-   inside it, are bound to --md-typeset-a-color, which defaults to
-   --md-primary-fg-color (slate-700). In slate that is slate-700 on a near-black
-   chip — unreadable. Re-bind to the sky link colours. The left sidebar needs
-   nothing: the theme colours its active item with the accent already. */
-:root,
-[data-md-color-scheme="default"] {
-  --md-typeset-a-color: #0284c7;           /* sky-600 — matches link color */
-}
-
-[data-md-color-scheme="slate"] {
-  --md-typeset-a-color: #38bdf8;           /* sky-400 — matches link color */
-}
-
-/* --- Mermaid in dark mode ---
- *
- * The diagrams colour some nodes through `classDef`, e.g.
- * `classDef stream fill:#f0f7f0,stroke:#3a7d44,color:#111`. In slate that came
- * apart and the labels disappeared — near-white text on a near-white fill.
- *
- * The two halves of that declaration do not survive the same way, and neither
- * can be fixed by overriding a rule:
- *
- *   fill  — mermaid emits `#<generated-id> .stream > * { fill: … !important }`.
- *           An ID *and* `!important`: nothing we can write outranks it, so the
- *           pale fills are fixed in both schemes.
- *   color — never applies at all. It reaches the text only by inheritance,
- *           while Material styles `.nodeLabel` directly, and a directly-applied
- *           value beats an inherited one at any specificity. The label colour
- *           is always Material's, which is light in slate. Hence the clash.
- *
- * So the fills win and the labels follow the scheme — the one combination that
- * cannot work. Rather than fight it, render the whole diagram the way its
- * colours were chosen for: light, on its own card, in both schemes.
- *
- * This is variable shadowing, not a specificity contest. Material defines each
- * of these as `var(--md-mermaid-…)` and mermaid's generated CSS *reads* them
- * inside the SVG; redefining them on the container is what those `var()` calls
- * resolve against. The values below are what the default scheme computes.
- */
-[data-md-color-scheme="slate"] .md-typeset .mermaid {
-  --md-mermaid-label-fg-color: #272822;          /* = default's --md-code-fg-color */
-  --md-mermaid-edge-color: #272822;
-  --md-mermaid-node-bg-color: rgba(2, 132, 199, 0.1);
-  --md-mermaid-node-fg-color: #0284c7;           /* sky-600, our light accent */
-  --md-mermaid-label-bg-color: #ffffff;
-
-  background: #ffffff;
-  border-radius: 4px;
-  padding: 0.8rem 0.4rem;
+[data-md-color-scheme="slate"][data-md-color-accent="custom"] {
+  --md-accent-fg-color: #c4b5fd; /* violet-300 */
+  --md-accent-fg-color--transparent: #c4b5fd26;
 }
 
 /* --- Landing page --- */
@@ -261,40 +202,22 @@
 }
 
 @keyframes target-flash {
-  0%, 100% {
+  0%,
+  100% {
     background-color: transparent;
     box-shadow: -0.4rem 0 0 0 transparent;
   }
-  25%, 65% {
-    background-color: rgba(2, 132, 199, 0.35);    /* sky-600 — matches accent */
-    box-shadow: -0.4rem 0 0 0 rgba(2, 132, 199, 0.75);
+  25%,
+  65% {
+    background-color: color-mix(in srgb, var(--md-accent-fg-color) 30%, transparent);
+    box-shadow: -0.4rem 0 0 0 color-mix(in srgb, var(--md-accent-fg-color) 70%, transparent);
   }
   45% {
     background-color: transparent;
     box-shadow: -0.4rem 0 0 0 transparent;
   }
 }
 
-[data-md-color-scheme="slate"] .md-content :target {
-  animation: target-flash-dark 1.5s ease-in-out;
-}
-
-@keyframes target-flash-dark {
-  0%, 100% {
-    background-color: transparent;
-    box-shadow: -0.4rem 0 0 0 transparent;
-  }
-  25%, 65% {
-    background-color: rgba(56, 189, 248, 0.22);   /* sky-400 — matches dark accent */
-    box-shadow: -0.4rem 0 0 0 rgba(56, 189, 248, 0.65);
-  }
-  45% {
-    background-color: transparent;
-    box-shadow: -0.4rem 0 0 0 transparent;
-  }
-}
-
-
 /* --- Benchmark figures ---------------------------------------------------
    The charts are `<img>`-referenced SVG (docs/charts/), so they scale with
    the column like any image. That is right on a wide screen and wrong on a

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -121,18 +121,26 @@ nav:
 
 theme:
   palette:
-    - scheme: slate
+    - media: "(prefers-color-scheme)"
       primary: custom
       accent: custom
       toggle:
-        icon: lucide/moon
+        icon: lucide/sun-moon
         name: Switch to light mode
-    - scheme: default
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
       primary: custom
       accent: custom
       toggle:
         icon: lucide/sun
         name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: lucide/moon
+        name: Switch to system preference
 
   icon:
     repo: fontawesome/brands/github
@@ -149,18 +157,22 @@ theme:
     - navigation.indexes
     - navigation.top
     - navigation.footer
+    - navigation.path
     - toc.follow
     - search.highlight
     - search.share
     - content.code.annotate
     - content.code.copy
     - content.code.select
     - content.tabs.link
+    - content.tooltips
+    - content.footnote.tooltips
 
 markdown_extensions:
   - admonition
   - attr_list
   - def_list
+  - footnotes
   - md_in_html
   - tables
   - toc: