Which dark palette this theme ships: the pre-0.18.0 greys it has, the book theme's navy-charcoal, or its own

[quantecon-services]

Raised as a design question on #187 on 2026-09-11 (study row F029, spun out of #210's close) and filed here as a Decision so that #187's sub-issue list is the plan. Nothing below is new work: it is the question as posted, with the two palettes written down side by side and what a move would touch, so the choice can be built from this issue without reopening it.

What ships today (v3.0.0)

The dark theme is the palette quantecon-book-theme had before its 0.18.0 release.

Surface	Value	Where
content panel	#222	qepage-dark, tailwind.config.js:42; applied by Page.tsx:27
toolbar	#444	qetoolbar-dark, tailwind.config.js:44
chrome text / muted	#fff / #a6a6a6	qetext-dark, qetext-dark-muted, tailwind.config.js:47-48
content links	#fff, weight 600	--qe-link-color under .dark, styles/quantecon.css:108
inline literal / emphasis / strong	#d78787 / #5fafaf / #d7af5f	the .dark token block, styles/quantecon.css:102-110; seoul256's dark set, chosen against #222
"On this page" active entry	#6cb6ff	styles/quantecon.css:607-611, chosen against #222
footer links	#93c5fd	styles/quantecon.css:485, chosen for 5.0:1 at the footer's 70% opacity on #222
code-block ground	#1e1e1e	upstream .dark .hljs { background: #1e1e1e !important }
page behind the panel	#1c1917	upstream, measured in #176

docs/dark-mode.md describes this and, since #229, says the palette is an open design question and points here.

What the book theme ships

0.18.0 (2026-02-24, "Complete dark theme overhaul", quantecon-book-theme#365) replaced the greys with a navy-charcoal set, declared as overridable custom properties. Read from src/quantecon_book_theme/assets/styles/_dark-theme.scss:21-40 at 649cc376, which is 0.22.0, the release the lecture repositories pin (13 of them, per the #187 comment):

Token	Value	Role
--qe-dark-bg	#1a1a2e	page background
--qe-dark-surface	#252540	cards, sidebars
--qe-dark-surface-alt	#2d2d4a	toolbar, inputs
--qe-dark-border	#3a3a5c	borders
--qe-dark-text / --qe-dark-text-muted	#d4d4e4 / #9898b0	body text / muted
--qe-dark-heading / --qe-dark-heading-top	#e8e8f0 / #f0f0f8	h2–h5 / h1
--qe-dark-link / -hover / -visited	#6cb6ff / #91cdff / #a08fff	links
--qe-dark-code-bg	#1e1e32	code blocks
--qe-dark-inline-code	#e0b0ff	inline literals
--qe-dark-accent / -dark	#0072bc / #005a96	the light accent, carried over

So most Sphinx lecture sites a reader opens in dark mode today are navy-charcoal, and this theme is grey. Both are QuantEcon palettes; the question is which one, or neither.

Contrast, so the choice is not made on compliance grounds

Both palettes clear WCAG AA on every text surface. The difference is tone, not legibility.

Surface	This theme, on #222	Book theme, on #1a1a2e
body text	#fff 15.9:1	#d4d4e4 11.7:1
muted text	#a6a6a6 6.5:1	#9898b0 6.1:1
links	#fff 15.9:1	#6cb6ff 7.9:1
inline literal	#d78787 5.8:1	#e0b0ff 9.6:1
emphasis / strong (seoul256 dark)	6.2:1 / 7.7:1	6.7:1 / 8.3:1 if kept
accent as a non-text rule	—	#0072bc 3.4:1 (1.4.11 asks 3:1)

One figure carries over to #176. A dark link that is not white has to be findable without colour alone: #6cb6ff against #d4d4e4 body text is 1.47:1, and this theme's #fff against its #d6d3d1 prose is 1.49:1. Neither palette reaches the 3:1 that would let colour mark a link, so the resting underline DrDrij kept on #176 is what carries the cue in dark mode whichever palette ships. The dark-mode link colour #176 left open is therefore this decision's to take: white under option 1, #6cb6ff under option 2.

What a move would touch

• Tokens. The four colours in tailwind.config.js and the .dark block in styles/quantecon.css. The seoul256 dark set survives (every value is above 6:1 on #1a1a2e); the outline's #6cb6ff is already the book theme's link colour; the footer's #93c5fd was derived against #222 and is re-derived.
• Upstream greys. The code ground is upstream's #1e1e1e !important and would need #1e1e32 over it; exercises carry dark:bg-stone-800, shadows dark:shadow-neutral-900, the page behind the panel is #1c1917. A full move means auditing the dark: utilities the components inherit, or a navy panel sits on a stone page.
• Docs. docs/dark-mode.md describes whatever ships; docs: correct the user docs against what the theme actually does #229 already corrected the provenance line.
• Baselines: none, which is the problem. No visual snapshot is taken in dark mode — tests/visual/*.spec.ts set no colour scheme — so a palette change moves zero PNGs and is also unguarded. Whichever option is taken should add one dark-mode snapshot so the palette cannot drift again.

Options

1. Keep the greys. Costs nothing. Under the stance recorded on Book-theme parity cutover — tracking #147, this is the divergence and needs a reason written down: the sites readers use are navy, and docs/dark-mode.md would say so as a deliberate difference rather than an open question.
2. Take the book theme's navy-charcoal. Parity with the live sites in dark mode, from a token table that already exists and is documented upstream. Costs the token swap, the dark: utility audit and the code-ground override above, plus the dark snapshot.
3. A palette of the theme's own. DrDrij's call on colour; the same build cost as option 2 plus the design work, and a visible difference from the Sphinx sites for the whole migration window.

Under the stance, option 2 is the default and options 1 and 3 need a case. The measurements do not choose: both palettes pass.

What settles it

DrDrij's choice among the three, with, under 2 or 3, the token values to build from — including the dark link colour, which closes the half of #176 that was left open.