Five light-mode code token colours fall short of WCAG AA contrast

[mmcky]

Found while building Phase 3 (#89, landed in #171). The code-token palette the theme now ships is quantecon-book-theme's own (_code.scss), reproduced for parity. Measured against the white ground the theme's code blocks sit on (bg-stone-200/10 over white), five of its light-mode colours fall short of the WCAG 2.1 AA minimum of 4.5:1 for normal text. Code blocks render at text-sm, so the 3:1 large-text allowance does not apply. Every dark-mode value passes.

Token	Sphinx class	Colour	Contrast on white	AA
f-string substitution	.si	#70a0d0	2.75:1	✗
comment	.c .c1	#60a0b0	2.94:1	✗
number	.m .mi .mf	#40a070	3.24:1	✗
variable (non-Python)	.nv	#bb60d5	3.65:1	✗
class name	.nc	#0e84b5	4.21:1	✗
string	.s	#4070a0	5.19:1	✓
keyword, builtin	.k .nb	#007020	6.29:1	✓
decorator	.nd	#555555	7.46:1	✓
function name	.nf	#06287e	13.02:1	✓

Comments and numbers are the ones that matter in practice: every lecture code cell has both. The text colour scheme that landed alongside is fine (em 7.49:1, strong 5.73:1, inline literals 4.54:1).

This is a two-theme decision, not a fix for this repo alone. The values are the Sphinx builds' as deployed today, and #171 reproduced them deliberately so the migrated sites look like the current ones. Changing them here only would reintroduce a difference the parity work exists to remove; changing them means the same change in quantecon-book-theme's _code.scss, or accepting that the two stacks diverge on this point until the cutover.

If the decision is to fix, the nearest darker shade of each hue that reaches AA, keeping the palette's character:

Token	Today	Candidate	Contrast
comment	#60a0b0	#447c89	4.68:1
number	#40a070	#34835c	4.62:1
f-string substitution	#70a0d0	#3c7ab7	4.51:1
class name	#0e84b5	#0d7dac	4.62:1
variable	#bb60d5	#af44ce	4.62:1

Those are minimum-change candidates, not a design proposal; a designer may prefer a bigger move on the comment colour in particular, since 4.68:1 is barely over the line.

Options

1. Fix in both themes, same values, before the cutover. One PR here (styles/quantecon.css, CODE HIGHLIGHTING block, light values only) and one in quantecon-book-theme; refresh the visual baselines in both.
2. Fix here only and let the Sphinx sites keep the old values until they are retired. Simpler, but the parity tracker (Book-theme parity cutover — tracking #147) would need to record the known difference.
3. Accept as is. The colours have shipped on every lecture site for years without a reported complaint; record the decision and close.

Where it fits: not a cutover gate (#147 is about matching the current sites, which this does), so deliberately off the parity milestone. The decision should be taken before Phase 6 (#92) writes the parity docs, so the docs describe the settled palette.

[mmcky]

@DrDrij a decision is needed here before Phase 6 (#92) writes the parity docs, since the docs should describe the settled palette. On the current #147 sequence that is after #186 and #173 land.

The three options in the body stand. Under the parity stance recorded on #147 (2026-09-09), the Sphinx values are the default and a divergence needs a reason and the matching change in quantecon-book-theme. So option 1 (fix in both themes, same values) is the route if you want the contrast fixed, and option 3 (record and close) is what happens by default if #92 starts without an answer. The candidate values in the body are minimum-change; a bigger move on the comment colour is yours to propose.

[quantecon-services]

Came to this from a comment-accuracy review of #200. Two things for the decision here.

The count is six, not five. The table above omits .hljs-addition, the diff-line green:

Token	hljs class	Colour	Contrast on white	AA
diff addition	.hljs-addition	#00a000	3.48:1	✗

Its pair .hljs-deletion #a00000 passes at 8.42:1, so the two sides of a diff are AA-asymmetric. I recomputed every light value in the CODE HIGHLIGHTING block to confirm the rest of the table — #70a0d0 2.75, #60a0b0 2.94, #40a070 3.24, #bb60d5 3.65, #0e84b5 4.21 all match, and every passing value matches too.

Whether diff colours belong in scope is a fair question — they show up in far fewer cells than comments and numbers — but the issue title and the in-code comment both state a bare count, so it is worth settling explicitly rather than leaving the reader to wonder which one was excluded. A minimum-change candidate in the same hue, for consistency with the table above:

Token	Today	Candidate	Contrast
diff addition	#00a000	#008a00	4.52:1

The two-theme framing is worth keeping in the code, not only here. #200 rewrote the CODE HIGHLIGHTING comment and, in dropping the Sphinx references, also dropped the clause recording that these values are inherited and that revisiting them is a decision for both themes rather than a fix for one. That is a live constraint, not project history — without it the next reader sees six AA failures and a free hand. I have restored it on claude/busy-dijkstra-oy40fc along with the corrected count, and the comment now points here.

No change proposed to the palette itself in that branch — option 1/2/3 is still this thread's call.

---

Generated by Claude Code

[quantecon-services]

Correcting my own comment above, having since read #187.

I measured on pure white. The real ground is bg-stone-200/10 over white — #fdfcfc — as this issue's opening comment already says, and #187 further notes the code-block work will move that ground by about 6.7%, which is why its five candidate colours stop reaching AA. My candidate walks into exactly that trap:

	on #ffffff	on #fdfcfc (actual)
#008a00 (what I proposed)	4.53:1	4.42:1 — fails
#008400	4.87:1	4.77:1

So #008400 or darker for the diff-addition green, not #008a00. Apologies for the noise.

The finding itself is unaffected — all six are still under AA on the real ground, just about 2% lower than I quoted: subst 2.69, comments 2.87, numbers 3.16, diff additions 3.40, variables 3.57, class names 4.11. And #187's correction that code blocks render at 13px, not text-sm, does not change the threshold — 13px normal weight is still normal text, so 4.5:1 applies, not the 3:1 large-text allowance. If anything it strengthens the case.

Given #187's point that the ground is about to move anyway, the practical conclusion is that any candidate list here should be stated against the ground it will actually sit on, and restated in whichever PR moves it.

---

Generated by Claude Code