You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Goal: every finding from DrDrij's design review of the v2.5.0 lecture build is resolved, or consciously declined with the reason recorded.
Where we stand (verified 2026-09-12)
Next: the combined CSS PR, branched from main at v3.0.0 (2ca0288), carrying #184 (code size), #185 (callout size) and #176 (link decoration) — and #201 (footer contrast) if the maintainer takes option 1 on it first. Every design gate this plan waited on opened on 2026-09-10; what still waits on a choice does not block the PR.
Filed 2026-09-09 from DrDrij's review of the v2.5.0 build of the Python Programming lectures. Eight observations went in; each was root-caused against v2.5.0 — origin/main at 6d773b63c when he looked — then adversarially re-checked and re-measured against his own deploy.
Seven produced work here. One did not: the inline-literal spacing he flagged is already at parity, reproducing the Sphinx build within about 1% on every metric including the padding he reports as missing, so it survives only as a design question about whether to adopt a treatment Sphinx built and never switched on (#180). One was misdiagnosed in a useful way: inline maths is within 2.2% of the Sphinx ratio (#179), but the exercise block in that screenshot has a real and previously unreported defect beside it (#178 records the mechanism).
The eighth was not in this plan. The Back button throwing an "Application Error" on statically-built pages was a cutover gate, filed as #186 on #147; it shipped in v2.6.1 (#192), ahead of everything here, as intended.
Re-verified against v3.0.0. Four releases have shipped since the reviewed commit: v2.6.0 (#171, #174), v2.6.1 (#186), v2.7.0 (#182, #92, #173, #198) and v3.0.0 today (#203–#209, #217, #218). None touched the surfaces this review measured — code-block size, callout size, inline maths, link decoration and the byline colour render as they did at v2.5.0, so the measurements in the sub-issues stand. Their styles/quantecon.css line numbers do not: #171 and #200 have edited the file since, so the deferred-underline note is now at :404-406 and the CONTENT LINKS block at :382; the byline line is ProjectFrontmatter.tsx:102. Two things did move:
The three gates opened on 2026-09-10. DrDrij answered #176 (keep the resting underline), #177 (frame: accept as is; size: the recommendation, 16px) and #178 (option 1, 16px). That unblocks #184, #185 and #176's implementation. Still waiting on a choice:
What ratio inline maths should sit at against the prose #179 — DrDrij answered the two clarifying questions (desktop width; judging the mystmd render on its own), which makes option 3 the live one, but no ratio is chosen; 1.10em is the proposal on the issue. It rides in the combined PR only if a value is settled first.
Moved.#182 went to #147 on 2026-09-10 and shipped in v2.7.0 (#196), with h4 entries added in v3.0.0 (#208). #183 and #181 went to #147 on 2026-09-11; both wait on DrDrij there. #128 joined on 2026-09-10 as design iteration on the shipped header placement; #114's build (PR #195) is open against that placement with merge conflicts. Ten work items remain here; sub-issue progress reads 0 of 10.
Nothing in this plan has started.
Plan
Gates: the three design choices this plan waited on — the resting underline, the code-block frame and size, the callout body size — were taken on 2026-09-10. What still waits on a choice (#179's value, #180, the #201 call, #237) is smaller and does not block the CSS PR. #179 and #180 remain the two findings that resolve to a choice with no implementation behind them unless the choice goes a particular way.
Sequencing rationale: the decisions came first because they were cheap, they unparked most of the plan, and they were the part that needed DrDrij. The table-of-contents enumerator (#181), placed early for its lead time, moved to #147 with the rest of the landing-page work, so the long-lead item is no longer here.
PR #171 and PR #174 merged in v2.6.0, so the CSS items branch from main. Four of them move overlapping snapshot sets and between them touch every snapshot name, so they should share one PR, with a single local --update-snapshots=all and one /update-snapshots comment for the linux set. Shipped separately they collide on each other's binaries four times, which is the failure that cost a full baseline refresh across #165, #166 and #167 in early September. The snapshot set now has seven names — rtl.png was added by #174 — and no snapshot is taken in dark mode, so #237 moves no baseline and is unguarded until one is added.
The byline split is superseded.#174 merged with text-sky-500 copied onto its translator links, as predicted, so both occurrences (ProjectFrontmatter.tsx:102 and :137) are #183's, on #147. Only the link-decoration rules remain here.
Three tracker records asserted parity that did not exist, and each was checked against the code rather than the thread. They are the reason two of these findings were never scheduled: a reader auditing the plan would have concluded both surfaces were done.
"the translators half only; authors are already at parity"
The page-header byline is hard-coded to Tailwind's text-sky-500 #0ea5e9, where the Sphinx build renders #0072bc. It also fails WCAG AA at 2.77:1 on white.
Record corrected on #147. Defect open as #183 on #147, waiting on DrDrij; both occurrences (ProjectFrontmatter.tsx:102, :137) remain in code at v3.0.0.
PLAN.md:57 (now :77-78)
"On this page" TOC and back-to-top listed under Already at parity, ✅ / ✅
The outline discarded the activeId its own hook computed, so nothing ever highlighted, and the nav was absolute inset-0, so it left the viewport entirely — measured at −1378px after 1500px of scroll.
Fixed in v2.7.0 (#196), extended in v3.0.0 (#208); the row now records it; the file is closed.
one row records the outline as absolute positioned and grades it "✅ Parity" against "scroll spy"
The same defect. The row states the cause and grades it as parity in the same line.
Defect fixed as above. #33 is a closed February review; its table stands as a historical record.
One finding was a decision the team already took and deferred rather than a defect that slipped through. styles/quantecon.css:404-406 records it: "they underline on hover only, where these underline always, and they colour :visited links #004979, which these leave alone." DrDrij independently found what PR #167 chose not to do, and on 2026-09-10 took the call the other way: the resting underline stays (#176).
Premises
The review was assessed under a stance taken on 2026-09-09 and recorded on #147: strict parity with the deployed Sphinx lectures is the default metric, and design suggestions from DrDrij are considered on their merits where he makes a case. The Sphinx build establishes what should exist and how it should behave; it does not establish the pixel values. An item is therefore not closed merely because the Sphinx build shares the characteristic — where something reads wrong in both builds, that is an improvement request, and two of the decisions in this plan exist for exactly that reason.
Out of scope / what does not change
The cutover itself, and every parity item tracked on #147, are outside this plan — it covers the findings of one review, not the parity programme they touch.
Bringing #147's own body into QEP-6 conformance is not part of this work. It carries a work-item roster and a hand-written progress table, both of which QEP-6 §7 replaces with the sub-issue list; its stamp heading carries a clock time and timezone after the date where the canonical form is the date alone; and a ## Next session — resume here section sits above the stamp, where §7 allows a single Next: line only inside it. That is the conform tooling's job under QEP-6's adoption clause 3, and rewriting a live tracker's body is its own change.
No milestone is set on the work here. Ten items is below the size where grouping earns its keep, list position carries the order, and putting these on book-theme parity would change what that milestone counts.
Goal: every finding from DrDrij's design review of the v2.5.0 lecture build is resolved, or consciously declined with the reason recorded.
Where we stand (verified 2026-09-12)
Next: the combined CSS PR, branched from
mainat v3.0.0 (2ca0288), carrying #184 (code size), #185 (callout size) and #176 (link decoration) — and #201 (footer contrast) if the maintainer takes option 1 on it first. Every design gate this plan waited on opened on 2026-09-10; what still waits on a choice does not block the PR.Filed 2026-09-09 from DrDrij's review of the v2.5.0 build of the Python Programming lectures. Eight observations went in; each was root-caused against
v2.5.0—origin/mainat6d773b63cwhen he looked — then adversarially re-checked and re-measured against his own deploy.Seven produced work here. One did not: the inline-literal spacing he flagged is already at parity, reproducing the Sphinx build within about 1% on every metric including the padding he reports as missing, so it survives only as a design question about whether to adopt a treatment Sphinx built and never switched on (#180). One was misdiagnosed in a useful way: inline maths is within 2.2% of the Sphinx ratio (#179), but the exercise block in that screenshot has a real and previously unreported defect beside it (#178 records the mechanism).
The eighth was not in this plan. The Back button throwing an "Application Error" on statically-built pages was a cutover gate, filed as #186 on #147; it shipped in v2.6.1 (#192), ahead of everything here, as intended.
Re-verified against v3.0.0. Four releases have shipped since the reviewed commit: v2.6.0 (#171, #174), v2.6.1 (#186), v2.7.0 (#182, #92, #173, #198) and v3.0.0 today (#203–#209, #217, #218). None touched the surfaces this review measured — code-block size, callout size, inline maths, link decoration and the byline colour render as they did at v2.5.0, so the measurements in the sub-issues stand. Their
styles/quantecon.cssline numbers do not: #171 and #200 have edited the file since, so the deferred-underline note is now at :404-406 and the CONTENT LINKS block at :382; the byline line isProjectFrontmatter.tsx:102. Two things did move:.article .qe-site-footer arule Light-mode site footer falls short of WCAG AA once the 70% opacity is composited #201 measured at 3.01:1 composited, and the Decide how the CC BY-SA licence footer survives the cutover: a theme default or a per-repo footer.md #203 decision removes lecture-python-programming's ownfooter.md. Light-mode site footer falls short of WCAG AA once the 70% opacity is composited #201's hedge that the figure "only bites where there is link text" is gone: every default-footer page carries link text. The footer rules themselves are unchanged in v3.0.0.The three gates opened on 2026-09-10. DrDrij answered #176 (keep the resting underline), #177 (frame: accept as is; size: the recommendation, 16px) and #178 (option 1, 16px). That unblocks #184, #185 and #176's implementation. Still waiting on a choice:
Moved. #182 went to #147 on 2026-09-10 and shipped in v2.7.0 (#196), with h4 entries added in v3.0.0 (#208). #183 and #181 went to #147 on 2026-09-11; both wait on DrDrij there. #128 joined on 2026-09-10 as design iteration on the shipped header placement; #114's build (PR #195) is open against that placement with merge conflicts. Ten work items remain here; sub-issue progress reads 0 of 10.
Nothing in this plan has started.
Plan
Gates: the three design choices this plan waited on — the resting underline, the code-block frame and size, the callout body size — were taken on 2026-09-10. What still waits on a choice (#179's value, #180, the #201 call, #237) is smaller and does not block the CSS PR. #179 and #180 remain the two findings that resolve to a choice with no implementation behind them unless the choice goes a particular way.
Sequencing rationale: the decisions came first because they were cheap, they unparked most of the plan, and they were the part that needed DrDrij. The table-of-contents enumerator (#181), placed early for its lead time, moved to #147 with the rest of the landing-page work, so the long-lead item is no longer here.
PR #171 and PR #174 merged in v2.6.0, so the CSS items branch from
main. Four of them move overlapping snapshot sets and between them touch every snapshot name, so they should share one PR, with a single local--update-snapshots=alland one/update-snapshotscomment for the linux set. Shipped separately they collide on each other's binaries four times, which is the failure that cost a full baseline refresh across #165, #166 and #167 in early September. The snapshot set now has seven names —rtl.pngwas added by #174 — and no snapshot is taken in dark mode, so #237 moves no baseline and is unguarded until one is added.What each decision means for the PR:
<pre>to1remwithline-height: 1.25, from 13px / 17px; no frame change; the executable / non-executable split stays as upstream renders it. Which selector carries the size is an engineering choice, recorded on Non-executable code blocks get no frame, and every code block renders 13px against 18px prose #184.1rem, root-relative, on.myst-admonition,.myst-exerciseand.myst-proof; the title weight and the.myst-dropdown/ topic tail are Whether admonition, exercise and proof bodies step down from the 18px content size #178's recorded open questions, not blockers..link, .hover-link, which removes the thumbnail-driven dotted / solid split in the same stroke; colours unchanged;:visitedleft unstyled unless a colour is chosen. The dark-mode link colour is Which dark palette this theme ships: the pre-0.18.0 greys it has, the book theme's navy-charcoal, or its own #237's.The byline split is superseded. #174 merged with
text-sky-500copied onto its translator links, as predicted, so both occurrences (ProjectFrontmatter.tsx:102and:137) are #183's, on #147. Only the link-decoration rules remain here.Related work
.hljs-addition, per its 2026-09-11 comments; still undecided.PLAN.md— closed by docs: close out PLAN.md, moving its lasting guidance to CONTRIBUTING #230 in v3.0.0; its outline row (nowPLAN.md:77) records The "On this page" outline scrolls off the page and never marks the current section #182 as shipped.Findings
Three tracker records asserted parity that did not exist, and each was checked against the code rather than the thread. They are the reason two of these findings were never scheduled: a reader auditing the plan would have concluded both surfaces were done.
text-sky-500#0ea5e9, where the Sphinx build renders #0072bc. It also fails WCAG AA at 2.77:1 on white.ProjectFrontmatter.tsx:102,:137) remain in code at v3.0.0.PLAN.md:57(now:77-78)activeIdits own hook computed, so nothing ever highlighted, and the nav wasabsolute inset-0, so it left the viewport entirely — measured at −1378px after 1500px of scroll.absolutepositioned and grades it "✅ Parity" against "scroll spy"One finding was a decision the team already took and deferred rather than a defect that slipped through.
styles/quantecon.css:404-406records it: "they underline on hover only, where these underline always, and they colour:visitedlinks #004979, which these leave alone." DrDrij independently found what PR #167 chose not to do, and on 2026-09-10 took the call the other way: the resting underline stays (#176).Premises
The review was assessed under a stance taken on 2026-09-09 and recorded on #147: strict parity with the deployed Sphinx lectures is the default metric, and design suggestions from DrDrij are considered on their merits where he makes a case. The Sphinx build establishes what should exist and how it should behave; it does not establish the pixel values. An item is therefore not closed merely because the Sphinx build shares the characteristic — where something reads wrong in both builds, that is an improvement request, and two of the decisions in this plan exist for exactly that reason.
Out of scope / what does not change
The cutover itself, and every parity item tracked on #147, are outside this plan — it covers the findings of one review, not the parity programme they touch.
Bringing #147's own body into QEP-6 conformance is not part of this work. It carries a work-item roster and a hand-written progress table, both of which QEP-6 §7 replaces with the sub-issue list; its stamp heading carries a clock time and timezone after the date where the canonical form is the date alone; and a
## Next session — resume heresection sits above the stamp, where §7 allows a singleNext:line only inside it. That is the conform tooling's job under QEP-6's adoption clause 3, and rewriting a live tracker's body is its own change.No milestone is set on the work here. Ten items is below the size where grouping earns its keep, list position carries the order, and putting these on
book-theme paritywould change what that milestone counts.