Repository navigation
Docs site: dark mode that follows the system setting, and a few accessibility fixes #519
Description
The docs site is always light: there is no prefers-color-scheme rule and no theme toggle in site.css or arcadedb.css, so a reader whose system is set to dark gets a white page (code blocks are already dark). This issue proposes a dark mode that follows the system setting with a small manual toggle, plus a few accessibility fixes that sit next to it. A pull request for step 1 is linked below; step 2 is an open question.
What I measured. These numbers are from my own measurement on a local build of the site with the table and "On this page" fixes from #511 applied (laptop width 1280px, and 390px for the phone figures). Contrast is the WCAG ratio of the rendered text colour against its background.
| Check | Result |
|---|---|
| Dark mode, theme toggle | none (prefers-color-scheme appears nowhere in site.css or arcadedb.css) |
| Contrast, laptop width | body text 7.5:1, table text 7.5:1, links in text 5.2:1, inline code 5.0:1, nav links 5.1:1, "On this page" links 6.6:1, headings 16.9:1 (all pass WCAG AA, 4.5:1) |
| Contrast, diagram labels (computed from the CSS colours) | green, amber and lime labels on white are 2.0 to 2.5:1, below the 3:1 that large text needs; light values are left as they are in this proposal |
| Text size | already relative: the root is set in em and the UI text in rem, so it follows the reader's default size; px appears only as SVG user units inside the diagrams, which scale with the figure. No change needed |
| Line length | median 72 characters per line at 1280px, 37 at 390px |
| Tap targets (WCAG 2.2 AA, 2.5.8, 24px minimum) | on the time-series page at 390px with the menu open, 28 of 60 links and buttons are under 24px (left navigation items about 20px tall, folding toggles 16x16); links inside running text are exempt and not counted |
| Keyboard focus | no custom :focus-visible ring; the default UI sets outline: none on 9 rules |
| Reduced motion | no prefers-reduced-motion rule; the diagram dots are SMIL animations (animateMotion) that CSS cannot stop |
Step 1 (the linked pull request).
- Dark mode on the existing CSS variables. Light values stay exactly as they are. Dark values are chosen so every text and background pair keeps at least 4.5:1 (3:1 for large text and for borders of controls); the computed ratios for every pair, in both themes, are listed in the pull request.
- The system setting decides by default. A small toggle in the header cycles system, light, and dark, overrides it, and remembers the choice (
localStorage, wrapped intry/catch, so it still works for the page when storage is blocked). The saved theme is applied before the first paint, so there is no white flash. - Hard-coded colours in the default UI's
site.css(navbar, left navigation, "On this page", tables, admonitions, quotes, footer, search) and inarcadedb.css(landing cards, the SVG diagrams, badges) now read the same tokens. - Tap targets of at least 24px on small and touch screens, and the phone header row fits so the menu button is not pushed off the screen.
- A visible
:focus-visiblering on everything focusable. prefers-reduced-motion: no transitions or hover lift, and the SMIL diagram animation is paused.
No .adoc content changes. Three pages carry inline SVG with their own fill colours; they keep their own light panels in dark mode and are the one place I would like a maintainer to look.
Step 2 (open question, no work started). If you want one look across the main website, these docs, and Studio, a small ArcadeData/design-system repository could hold the tokens for light and dark, the type scale, spacing, fonts, logo usage, and shared components, and each site would vendor a copy. I would be glad to set that up and keep it in sync. The brand itself stays your decision: the blue, the fonts, and the logo are yours, and the tokens in step 1 only name what the docs already use.
If you would rather have a different default (for example light unless the reader opts in), a different toggle placement, or the changes split into smaller pull requests, tell me and I will adjust.
Activity
docs(ui): dark mode that follows the system setting with a toggle, an…