How code blocks should be framed and sized against 18px prose

[mmcky]

From DrDrij's review of the v2.5.0 preview (item 7, "some code blocks lack the blue left border and do not stand out"). Two independent choices sit behind that one sentence, and the border is the smaller of them: every code block in this theme sets its <pre> at 13px against 18px prose, where the Sphinx build sets it at 16.2px against the same 18px. A grey card drawn around 13px text will not answer "does not stand out", so the frame and the size are one decision taken together. Neither is a choice this repo has ever made — grep -rn --exclude-dir=node_modules 'myst-code\|border-l-\|jp-code-font-size' over the v2.5.0 tree returns nothing, so both are inherited untouched from upstream.

What is on the page today

Monospace sizing in the two builds. The Sphinx figures are pre{font-size:.9rem} from quantecon-book-theme.css against its @media(min-width:992px){html{font-size:18px}} desktop root, with .highlight pre{line-height:125%} from pygments.css.

Element	This theme	Sphinx build	Ratio to its own 18px prose
body prose	18px	18px	1.00 / 1.00
inline literal (code in a paragraph)	16px	16.2px	0.89 / 0.90
code block source (<pre>)	13px / 17px	16.2px / 20.25px	0.72 / 0.90
static cell output text	14px / 20px	16.2px	0.78 / 0.90

Code is 20% smaller than the Sphinx build's, with 16% tighter leading, and it sits at 0.72x the prose it is embedded in where Sphinx sits at 0.90x. It also leaves this theme with three monospace sizes in two font stacks — 16px inline and 13px in blocks on menlo, consolas, …, 14px in static outputs on Tailwind's font-mono ui-monospace stack (@myst-theme/jupyter dist/safe.js:58 puts font-mono text-sm on a div, not a pre) — where the Sphinx build renders one size in one stack.

The frame

myst-to-react@1.3.0 dist/code.js:64 renders every code node as <CodeBlock … shadow={true} border={node.executable} background={!node.executable}>, and dist/code.js:55-57 turns those three booleans into mutually exclusive class sets on the wrapper div.myst-code: shadow gives my-5 text-sm shadow hover:shadow-md …, background gives bg-stone-200/10, and border gives border border-l-4 border-gray-200 border-l-blue-400 dark:border-l-blue-400 dark:border-gray-800. node.executable is set only for code-cell directives and ipynb code cells, so a {code-block} directive or a plain fence takes the background branch: a 10%-opacity fill and nothing else.

Property	Theme, executable	Theme, non-executable	Sphinx, executable (div.cell_input)	Sphinx, non-executable (div.highlight)
background	transparent	rgba(231,229,228,0.1)	#f7f7f7	#f7f7f7
border	1px rgb(229,231,235)	none	1px	1px #e1e1e1
left rule	4px rgb(96,165,250)	none	3px #0072bc	none — the same 1px #e1e1e1
shadow	Tailwind shadow, shadow-md on hover	same	none	none

The executable / non-executable split is right, and the Sphinx build makes the same one. body div.cell div.cell_input{border-left-color:#0072bc} is the only code-related border-left rule in quantecon-book-theme.css, and all it does is recolour the left edge of div.cell > div.cell_input{border: var(--mystnb-source-border-width) … solid; border-left-width: medium} from mystnb.css — so a non-executable block in the Sphinx build gets no blue accent either. What Sphinx does give it is a card, html body:not(.use-pygments-style) .highlight{background:#f7f7f7;border:1px solid #e1e1e1}, and that is precisely what this theme omits. Dark twins are in the same sheet, so a card here has values to carry across: --qe-dark-code-bg:#1e1e32, --qe-dark-border:#3a3a5c, and --qe-dark-link:#6cb6ff for the accent.

#f7f7f7 on white is a very quiet card, which makes it a defensible default but not, on its own, an answer to "they do not stand out". Going a step darker is a legitimate improvement on both builds if that is what the design calls for — read the contrast section below before choosing a value, because the card is the ground every code token is measured against.

The size, and why it is not text-sm

text-sm (14px) sits on the .myst-code wrapper div and only ever reaches the <pre> by inheritance, so it never wins. thebe-core@0.5.0 ships the vendored JupyterLab rule at node_modules/thebe-core/dist/lib/thebe-core.css:263-271:

tt,
code,
kbd,
samp,
pre {
  font-family: var(--jp-code-font-family);
  font-size: var(--jp-code-font-size);
  line-height: var(--jp-code-line-height);
}

--jp-code-font-size: 13px and --jp-code-line-height: 1.3077 are set at thebe-core.css:105-106, giving exactly the 13px / 17.0px above. The rule is (0,0,1) — the same specificity as Tailwind preflight's code,kbd,pre,samp{…font-size:1em} — and app/root.tsx:158-159 loads thebeCoreCss immediately after the Tailwind bundle, so it wins the tie on source order and lands directly on the <pre>, which outranks anything the wrapper could pass down by inheritance. Inline code escapes it only because styles/quantecon.css:217 scopes .article :not(pre) > code at (0,1,2).

The precedent for a value is already in the file, one selector away. styles/quantecon.css:230 sets inline literals to font-size: 1rem, with the comment that "the Sphinx build sizes inline code at .9rem off its own root (16.2px), fixed regardless of the surrounding text … Against this theme's 16px root, 1rem is the same 16px". The :not(pre) > scoping that deliberately kept the literal colour off code blocks also kept that size decision off them. Note that .article is 18px in v2.5.0 (styles/quantecon.css:314, font-size: 1.125rem) and the root is deliberately left at 16px for WCAG 1.4.4, per the UNITS note at styles/quantecon.css:55-74 — so 1rem on a <pre> means 16px pinned, not 16px scaled with content.

There is a second axis here that is easy to miss, and it can be settled independently of the value: which selector carries it. A narrow .article .myst-code pre rule at (0,2,1) is obvious and contained, but it leaves the static output text at 14px and does nothing for whatever Thebe swaps in when live compute is enabled, so code could visibly change size when a reader clicks the toggle. Setting :root { --jp-code-font-size: … } instead moves source blocks and Jupyter-rendered output together and stays consistent across the Thebe toggle, at the cost of reaching into Jupyter's own output styling; its blast radius is knowable — --jp-code-font-size is used in exactly four places in thebe-core.css, the element rule at :269, the Jupyter-output rule at :2764, and two calc()s at :173 and :2752. Neither vector reaches the static .myst-jp-safe-output-text div, which carries Tailwind text-sm and needs its own rule either way.

This moves the ground #172 is measured against

Two consequences, and the second is the one that constrains the choice.

First, #172's premise sentence — "Code blocks render at text-sm, so the 3:1 large-text allowance does not apply" — is wrong on the number, for the reason above: blocks render at 13px, not 14px. Its conclusion survives untouched, since none of 13px, 14px, 16px or 16.2px is WCAG large text (18pt / 24px, or 14pt / 18.66px bold) and the allowance never applies at any candidate size. Only the stated figure needs correcting there.

Second, #172 measures every figure against white, which is correct today — executable blocks compute a fully transparent background and non-executable ones compute rgba(231,229,228,0.1), which flattens to #fdfcfc. Putting a #f7f7f7 card under both kinds drops every one of those figures by exactly 6.7%.

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

The count of failures is unchanged and no colour crosses the line, so #172's finding stands. What does not survive is #172's remedy: its five candidate replacements were computed to clear 4.5:1 on white and clear it by 0.01–0.18, so on #f7f7f7 they land at 4.21:1, 4.31:1, 4.31:1, 4.32:1 and 4.37:1 and none of them reaches AA any more. #172's table therefore has to be restated against whatever ground is chosen here, not re-checked against it, and a card darker than #f7f7f7 makes that restatement larger rather than optional. Inline literals are unaffected either way: --qe-literal-color sits on prose background, and .article :not(pre) > code keeps it off blocks.

A question only DrDrij can answer

Which build screenshot B came from. The "Exercise 2" admonition shot is ambiguous, and the answer decides whether a separate defect exists. If it is the mystmd render, there is one nobody has recorded: myst-to-react/dist/exercise.js:40 puts 'myst-exercise my-5 shadow dark:bg-stone-800 overflow-hidden', 'dark:border-l-4 border-slate-400' on the exercise Callout — a left-border colour with no light-mode width, against Tailwind preflight's border-width: 0. A light-mode exercise therefore has no left rule at all, only the header's border-y and the drop shadow, where the Sphinx build gives it div.exercise{border-color: var(--note-border-color); background-color: var(--note-title-color)} from exercise.css, i.e. a #007bff rule over an rgba(68,138,255,.1) ground. That is a separate item from this one and would be filed on its own once the build is confirmed; if screenshot B is the Sphinx render, nothing is filed.

An alternative nobody has proposed

The lecture corpus has 965 {code-cell} directives and only 26 {code-block}, 25 of them carrying :class: no-execute — counted over lectures/*.md in QuantEcon/lecture-python-programming at 5e574c1. Screenshot A is one of them, lectures/python_by_example.md:126-132. Converting those 26 to {code-cell} with a skip-execution tag would give the blue border DrDrij asked for with no CSS divergence from the Sphinx build at all, and it is cheaper than any of the divergence options below. It is an authoring change in QuantEcon/lecture-python-programming rather than a theme change, so it would be raised there. It does not remove the size question, and it does not remove the case for framing non-executable blocks: a plain fence written in any other lecture still lands in the unframed branch.

Options

On the frame.

1. The Sphinx card on both kinds, blue accent on executable cells only. #f7f7f7 with a 1px #e1e1e1 rule for non-executable; the same card plus the 3px #0072bc left rule for executable; the --qe-dark-* values for dark mode. Faithful to the deployed sites, and the accent keeps marking "this cell was actually run". Costs a restatement of Five light-mode code token colours fall short of WCAG AA contrast #172's table against #f7f7f7.
2. The same structure with a deliberately stronger card than #f7f7f7. Answers "they do not stand out" more directly than parity does, and is an improvement on both builds rather than a defect in one. Costs the same restatement plus new candidate colours for Five light-mode code token colours fall short of WCAG AA contrast #172, and a difference from the deployed sites that has to be recorded on Book-theme parity cutover — tracking #147.
3. Give non-executable blocks the blue accent too, as the review literally asks. Diverges from Sphinx and erases the executable / non-executable distinction that Sphinx preserves and that the lectures lean on — a reader can currently tell a run cell from a shown snippet at a glance. Recorded as a known difference on Book-theme parity cutover — tracking #147.
4. Accept as is. Costs nothing and no reader has complained in the Sphinx era, but a 10%-opacity fill with no border is not a frame in either build's terms, and the reviewer picked it out of a screenshot.

On the size — the value.

1. 1rem (16px), with line-height: 1.25 to reproduce Sphinx's 20.25/16.2 ratio. Matches the inline-literal decision already at styles/quantecon.css:230 and puts the whole code column on one size; 0.2px under the Sphinx build.
2. 1.0125rem (16.2px), Sphinx exact. Items 6 and 8 of the same review independently converged on 1.0125rem as the root-relative constant for Sphinx's 18px root, so it is consistent with them — at the cost of the internal consistency option 1 buys, for 0.2px.
3. Leave 13px. Keeps three monospace sizes in two stacks, and leaves the larger half of the complaint unanswered. If it is chosen, Five light-mode code token colours fall short of WCAG AA contrast #172's stated size should still be corrected to 13px.

On the size — the vector.

1. .article .myst-code pre at (0,2,1). Narrow and obvious; leaves static output at 14px, and code may visibly resize when a reader enables live compute.
2. :root { --jp-code-font-size: … }. Moves source blocks and Jupyter-rendered output together and holds across the Thebe toggle; reaches into Jupyter's output styling and the two calc()s above.

What settles this

The size has a clear recommendation — option 1 on both axes — and mainly needs confirming, since 13px against 18px prose is hard to defend in either build's terms and the file already made the same call for inline literals. The frame is genuinely a designer's call between options 1 and 2, where the measured Sphinx values are the default and DrDrij's case for a stronger card is the only thing that would move it; whichever is chosen, the ground colour has to be settled before #172's palette can be restated against it. Screenshot B's provenance is a one-line answer that decides whether a separate exercise-border item exists.

[DrDrij]

On the frame: Option 4, accept as is.
On the size: Option 1, Go with recommendation.

[quantecon-services]

Recording, for whoever implements #184, what follows from the 2026-09-10 decision and what is still open on it. Re-checked against v3.0.0 (2ca0288): nothing since v2.5.0 has changed a declaration on code-block size or frame, so the measurements above stand.

Stands as decided. Frame: option 4. Size: option 1, 1rem with line-height: 1.25.

The selector is an engineering choice, and it goes the other way from the recommendation above. The narrow .article .myst-code pre leaves static outputs at 14px and Thebe's re-rendered outputs at 13px, so a cell's source and its output would sit at different sizes, and code would resize when a reader enables live compute. #184 already records :root { --jp-code-font-size; --jp-code-line-height } plus one rule for .myst-jp-safe-output-text as the better vector, and that is what #184 will carry. Same rendered source block; one monospace size everywhere.

One rider on the frame, proposed to ride in #184 unless either of you objects. The executable cell's left rule is upstream's border-l-blue-400, #60a5fa. The Sphinx build draws that rule in #0072bc (body div.cell div.cell_input { border-left-color: $primary }), and so do this theme's header rule, footer rule, links (#167) and outline marker (#196). Recolouring it is one declaration on .article .myst-code.border-l-blue-400; it touches neither the ground #172 is measured against nor the frame structure option 4 kept, and moves only notebook.png, which the size change moves anyway. Dark mode needs its own rule at the same specificity, per the cascade trap in #184: keep #60a5fa, or take the book theme's #6cb6ff.

Two things only @DrDrij can settle:

1. A one-line reason for option 4 on the frame, for the record. Under the stance on Book-theme parity cutover — tracking #147 it is a divergence from the live sites — Sphinx draws a #f7f7f7 card with a hairline around a non-executable block, this theme draws a white one with a shadow — and a divergence without a recorded reason gets re-filed by the next reviewer. "The size was the complaint, and the blue rule means the cell ran" would be enough.
2. Which build screenshot B came from. Your What ratio inline maths should sit at against the prose #179 answer suggests the mystmd render; if so, a light-mode {exercise} has no left rule at all (Whether admonition, exercise and proof bodies step down from the 18px content size #178 records the mechanism) and that gets filed as its own item.

---

Generated by Claude Code