docs: the site follows the reader's light or dark setting in its own violet colour, with code, diagrams and footnotes readable in both by FBumann · Pull Request #1767 · fluxopt/specsolve

FBumann · 2026-09-25T13:09:48Z

Prompt: Lets first do everything thats worth and stable from this message: […] Then do Follow the system setting & accent colors. keep the modern theme

Two later asks set scope: "Do all of it", which refers to the session's CSS audit, and "Not sure about the new colors", answered with Monokai kept at fixed contrast.

Note

The following content was generated by AI.

The site now opens in the reader's system light or dark mode, and it has its own violet colour. Code keeps Monokai, and every colour now reaches 4.5:1 contrast. The architecture diagrams read in both modes, pages show breadcrumbs, and footnotes render.

Method, gate output, alternatives

Commits

Features. navigation.path, content.tooltips, content.footnote.tooltips, and the footnotes extension. Without the extension, docs/examples/index.md rendered [^stigler_diet] and [^transport_dantzig] as literal text.
Palette. The toggle is system → light → dark. Primary and accent are one violet hue. The hand-written link colours, the TOC re-bind and the dark-only target flash are removed, because they all read the palette now.
Diagrams. The two diagrams in about/architecture.md keep each lane's coloured stroke, but drop the pale fill and the color:#111. The theme now colours nodes and labels in each scheme, so the 38-line block that drew the diagrams on a white card in dark mode is removed.
Monokai at 4.5:1. The Monokai block stays. Six colours move along their own hue until they reach 4.5:1 on the code background, and the lowest is now 4.65:1.
main merged after feat!: specsolve requires mathspec 0.2.0 and uses its words spec and model, so an archive holds its spec as spec.yaml #1768. The CHANGELOG.md conflict is resolved by keeping both lines.

Colours

Role	Light (on `#fff`)	Dark (on `#0b0c0f`)
primary: links, primary button	violet-700 `#6d28d9`, 7.10:1	violet-400 `#a78bfa`, 7.19:1
accent: hover, focus, active nav	violet-600 `#7c3aed`	violet-300 `#c4b5fd`
text on the primary button	white	slate-900 `#0f172a`, 6.56:1

Code token	Before	After
light string	`#998800`, 3.42:1	`#7f7100`
light function and decorator	`#4d8d04`, 3.92:1	`#457e04`
light variable	`#d35400`, 3.99:1	`#c14d00`
dark comment	`#75715e`, 2.81:1	`#9b9682`
dark keyword and operator	`#f92672`, 3.64:1	`#fb5d95`

In the modern variant the primary colour paints only links, the primary button and the progress bar. The former slate-700 "soft dark header" primary never reached the header. Violet is a taste call: the first table is the whole change.

Verified

On the merge commit, with mathspec 0.2.0 from uv.lock:

tests/test_architecture.py, test_models_gallery.py::test_the_gallery_math_is_current, test_docs_math.py, test_docs_site.py and test_pypsa_ladder_page.py: 161 passed. These include the two tests that failed CI before feat!: specsolve requires mathspec 0.2.0 and uses its words spec and model, so an archive holds its spec as spec.yaml #1768.
python -m zensical build --strict: no issues.
ruff check .: clean.

Before the merge:

Headless Chromium on the built site:
- The OS set to light or dark picks default or slate.
- The toggle cycles system → light → dark → system, and the choice survives a reload.
- The link, button and code colours match the tables.
- The breadcrumbs show on the ladder rungs.
- The footnote tooltip on examples/ shows the Laderman note.
- The target flash animates in both schemes.
- Both diagrams were rendered with Mermaid 11.17.2 in both schemes.

Not run

pixi run check: pixi cannot fetch its conda-to-PyPI mapping through this session's proxy, so the gates above ran through uv. The full suite and pyrefly were not run. No Python changed.

Deliberately not done

Instant previews: Zensical marks them experimental.
Glossary hover definitions: they need a generator from glossary.md.
Lightbox: GLightbox is a new dependency.
The classic variant.
Logo and favicon: docs: the documentation site has its own logo and favicon energy-models/mathspec#726.

Departure

This PR holds separable changes as separate commits. The session is bound to one branch per repository, so they could not be stacked as their own PRs.

🤖 Generated with Claude Code

https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

…der and preview on hover Turn on the `navigation.path` breadcrumbs, `content.tooltips` and `content.footnote.tooltips`, and the `footnotes` extension: the two footnotes on the examples index rendered as literal `[^stigler_diet]` text. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

… violet colour The palette toggle has three states: system, light, dark. A new visitor gets the scheme the operating system asks for, not dark. Primary and accent are one violet hue, so the site no longer looks like mathspec's. The primary (violet-700 on white, violet-400 on slate) rests on links and the primary button; the accent (one shade brighter) answers hover and focus. The hand-written link colours and the second, dark-only target flash go: both read the palette now. The Mermaid card follows the accent. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

codspeed · 2026-09-25T13:11:11Z

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

_{Comparing claude/funny-maxwell-3w18ii (ec9f992) with main (8c783ca)²}

82 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
No successful run was found on main (d38ce56) during the generation of this report, so 8c783ca was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

FBumann · 2026-09-25T13:18:42Z

Prompt: Then resolve cnflicts in #1767

Note

The following content was generated by AI.

This PR has no merge conflict. Its base is still main at 306921e. It is blocked because ci failed: two tests in suite fail, and they fail because mathspec 0.2.0 is out, not because of this diff. #1768 fixes both.

Failing tests, cause, plan

suite (run 36139278292), 2 failed, 4068 passed:

test_architecture.py::test_the_model_argument_is_what_the_language_takes_minus_the_lowered_form: KeyError: 'model'. mathspec 0.2.0 renamed to_spec's first parameter from model to spec.
test_models_gallery.py::test_the_gallery_math_is_current: stale math on 40 pages. mathspec 0.2.0 changed the typeset legend.

main was green at 12:28 with mathspec 0.1.0. mathspec 0.2.0 reached PyPI after that, and this run resolved mathspec>=0.1.0 to it. The next run on main fails the same way.

#1768 bumps to mathspec>=0.2.0, updates the test and regenerates the 40 pages. It is not ported here: it is 77 files, and it is still changing.

Plan: merge #1768, then merge main into this branch. Both PRs add a line at the top of ## Upcoming version, so CHANGELOG.md will conflict at that point, and the merge resolves it by keeping both lines.

🤖 Generated with Claude Code

Generated by Claude Code

read-the-docs-community · 2026-09-25T13:18:56Z

Documentation build overview

📚 specsolve | 🛠️ Build #34759446 | 📁 Comparing ec9f992 against latest (306921e)

🔍 Preview build

71 files changed · ± 71 modified

± Modified

…ht and dark mode Drop the Monokai code colours: in light mode strings, functions and variables fell below 4.5:1, and in dark mode comments were 2.8:1. The `modern` variant's own highlight colours replace them. The two architecture diagrams keep each lane's coloured stroke and drop the pale fill and `color:#111` that broke them in dark mode. The theme now colours nodes and labels per scheme, so the CSS that drew both diagrams on a white card in dark mode goes too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

The Monokai block comes back, with the six colours that fell short shifted along their own hue until they reach 4.5:1 on the code background: in light mode strings #998800 -> #7f7100, functions and decorators #4d8d04 -> #457e04, variables #d35400 -> #c14d00; in dark mode comments #75715e -> #9b9682, keywords and operators #f92672 -> #fb5d95. The lowest is now 4.65:1. The comment on the dark code background no longer names a page lightness the modern variant does not use. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

# Conflicts: # CHANGELOG.md

> **Prompt:** Prepare the release PR > [!NOTE] > The following content was generated by AI. This releases **0.1.0**, the first final release on PyPI after 0.1.0rc1. Merging it tags `v0.1.0`, opens the GitHub release, and publishes to PyPI once the `pypi` environment is approved. The notes name the three breaks since rc1. <details><summary>The version, what the notes claim, and how they were checked</summary> **Why 0.1.0 and not 0.2.0.** PyPI holds only `0.1.0rc1`, which is a pre-release that a user must pin to get. AGENTS.md says a release that breaks a file or an import raises the minor version. A release candidate is where such breaks are expected before the final version, so this final release stays 0.1.0 and lists each break since rc1. If you want 0.2.0 instead, only the heading changes. **The section** - `## Upcoming version` becomes `## 0.1.0 (2026-09-25)`, and a new empty `## Upcoming version` sits above it. - A short opening says the package is on PyPI, and a paragraph defines spec and model, which specsolve now uses as mathspec 0.2.0 does. - The three breaks since rc1, from #1768: - the archive member `model.yaml` is now `spec.yaml`; - specsolve requires mathspec 0.2.0, where `model=` is now `spec=` and `mathspec.model` is now `mathspec.spec`; - messages now say "spec" for the file. - The four PR lines since rc1 (#1767, #1768, #1764 and #1763) stay as they were. The #1767 line came in by merging `main`, which resolved the conflict on the heading. **Checked** - `python -m tools.changelog check`, after the merge: "releases 0.1.0 on merge". - `python -m tools.changelog notes 0.1.0` prints the section as the release notes. - `pytest tests/test_changelog.py`: 39 passed. - The recovery step in the notes was run against this tree. An archive with `model.yaml` is refused with a `LayoutError`. After its member is renamed to `spec.yaml`, `load_archive` reads it and returns the same objective. **Not checked:** the release workflow itself, which runs only on merge. </details> 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Xh8mtkAfVLEGYCTtwy3oqd Co-authored-by: Claude <noreply@anthropic.com>

claude added 3 commits September 25, 2026 13:07

docs: add the changelog line

ec15829

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

claude added 2 commits September 25, 2026 13:26

docs: the changelog line names what the PR now covers

f23bab8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125VUbY4punr8zWRu2EcbiH

FBumann changed the title ~~docs: the site follows the reader's light or dark setting in its own violet colour, and footnotes render~~ docs: the site follows the reader's light or dark setting in its own violet colour, with code, diagrams and footnotes readable in both Sep 25, 2026

FBumann enabled auto-merge (squash) September 25, 2026 13:28

FBumann disabled auto-merge September 25, 2026 13:28

claude added 2 commits September 25, 2026 13:39

Merge origin/main after #1768

ec9f992

# Conflicts: # CHANGELOG.md

FBumann merged commit 21e9eab into main Sep 25, 2026
14 of 15 checks passed

FBumann deleted the claude/funny-maxwell-3w18ii branch September 25, 2026 14:16

FBumann mentioned this pull request Sep 25, 2026

chore: release 0.1.0 #1772

Merged

Navigation Menu

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

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
FBumann merged 7 commits into
mainfrom
claude/funny-maxwell-3w18ii

FBumann commented Sep 25, 2026 •

edited

Loading

Uh oh!

codspeed Bot commented Sep 25, 2026 •

edited

Loading

Uh oh!

FBumann commented Sep 25, 2026

Uh oh!

read-the-docs-community Bot commented Sep 25, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

FBumann commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Commits

Colours

Verified

Not run

Deliberately not done

Departure

Uh oh!

codspeed Bot commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

FBumann commented Sep 25, 2026

Uh oh!

read-the-docs-community Bot commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

FBumann commented Sep 25, 2026 •

edited

Loading

codspeed Bot commented Sep 25, 2026 •

edited

Loading

read-the-docs-community Bot commented Sep 25, 2026 •

edited

Loading