feat: add dark mode

[Brett-Best]

Important

This draft is explicitly an AI-driven experiment exploring dark mode as an accessibility improvement. The implementation, tooling research, browser checks, APCA comparison, and initial code review were AI-assisted. It is not a claim of WCAG or APCA compliance, and it should receive human accessibility and design review before being considered ready.

Problem

Addresses #974.

The docs currently provide only a light appearance. Dark mode can reduce discomfort for people who are sensitive to bright interfaces or who browse in low-light environments, but adding it here is more involved than enabling a MkDocs setting.

Why this needs a custom approach

MkDocs' native color_mode and user_color_mode_toggle options apply only to its built-in mkdocs theme. This site uses a substantially customized readthedocs theme instead, including a forked base template, RTD-specific .wy-* and .rst-content styling, custom navigation, Algolia DocSearch, plugin-quality pages, and project-specific components.

The earlier discussion in #974 and the unfinished Material-theme migration in #696 illustrate the tradeoff: switching themes to gain a built-in toggle would mean reworking the site's existing templates and thousands of lines of theme-specific CSS. It would be a broad redesign rather than a contained accessibility experiment.

This draft therefore keeps the current theme and adds color-mode support around its existing structure. That requires handling several pieces explicitly:

• apply the saved or system preference before styles paint, avoiding a light-mode flash
• persist an Auto / Light / Dark choice and react to live system changes
• cover RTD navigation, content, forms, tables, admonitions, code and syntax highlighting
• load DocSearch styles early enough for local dark-mode overrides, and style its legacy v2 dropdown
• account for custom plugin scores, setup panels, responsive navigation, and the fastlane wordmark
• keep printed documentation light and hide the interactive selector

What changed

• adds an accessible color-mode selector to the sidebar
• resolves the initial preference in the document head, then manages persistence, system changes, and cross-tab updates with dependency-free JavaScript
• adds a semantic dark palette and targeted styles for the customized RTD theme
• preserves the colored fastlane mark while making the wordmark readable on dark surfaces
• keeps Algolia results on the current preview host so search can be exercised locally
• ignores generated Python cache files and updates the homepage's legacy Twitter badge and link to X

No documentation routes or navigation entries were changed in mkdocs.yml; it only registers the new CSS and JavaScript assets.

Accessibility and browser validation

This was evaluated as an experiment rather than certified as compliant:

• captured five representative pages in both light and dark modes using Playwright at 1280px full-page resolution
• exercised desktop, mobile navigation, persisted selection, live prefers-color-scheme changes, Algolia search, code blocks, tables, admonitions, plugin-quality pages, and print rendering
• observed no browser console errors or warnings in the tested flows
• ran an exploratory APCA-W3 (4g) audit over roughly 250–470 visible text elements per page using bronze-level thresholds

The APCA comparison found contrast parity with the existing light theme: 17 unique failing dark-mode style clusters versus 14 pre-existing light-mode clusters, with a similar minimum contrast around Lc 51. The remaining dark clusters are primarily muted secondary text, GitHub's shipped dark syntax palette, and link colors; their light-theme counterparts also fall below the same bronze thresholds. No dark-mode regression was identified, but these results should not be interpreted as formal compliance.

Repository checks

• bundle exec fastlane test
  • strict MkDocs build
  • filename, redirect, image, and asset-location checks
  • all code samples from 238 files
• node --check docs/js/color-mode.js
• git diff --check upstream/master...HEAD

Maintenance notes

The small inline head script intentionally duplicates the storage key and valid preference values from color-mode.js; this prevents a flash of the wrong theme, but those values must remain synchronized.

The CSS is deliberately comprehensive because it sits on top of a heavily customized legacy theme. A possible follow-up would extract more of the existing light-theme colors into semantic tokens and use dedicated per-mode syntax-highlighting stylesheets, which would reduce the number of targeted overrides over time.

Human review is especially welcome on accessibility priorities, palette choices, and whether this incremental approach is preferable to a future full theme migration.

[iBotPeaches]

Tested it out - works pretty well. I guess since mkdocs is on the way out and probably has no short-term future. Probably no big problem to really build further onto our iteration of it.

Maybe the color switcher can be a bit more elegant is my only 2c. It sits up there with a dropdown vs like an emoji switcher like I commonly see these days.