Skip to content

fix: story layout, light-palette contrast, 3D labels without console errors - #222

Merged
mnaimfaizy merged 1 commit into
mainfrom
fix/visual-polish
Oct 13, 2026
Merged

mnaimfaizy merged 1 commit into
mainfrom
fix/visual-polish

Conversation

@mnaimfaizy

Copy link
Copy Markdown
Owner

What changes

Stories keep their picture readable. The code panel now sits above the picture until the page is 1536px wide, and beside it from there. A 12-unit label, measured in the browser on the Stack ↔ Heap story:

Page width Before After
1024 about 5.5px 8.8px
1280 about 7.9px 12.7px
1536 side by side 10.1px, side by side

The agreed break was 1280px, but side by side at 1280 and 1440 still gave labels under 10px, so the break is at 1536. The Git branch-pointers story follows the same rule. The classes and the page-width model live in src/shared/components/viz/storyLayout.ts.

Light-palette contrast. Every failing light colour is darkened within its own hue. Text now reaches 4.5:1 on every background it is drawn on and strokes reach 3:1. The test enforces those floors for every pair the views draw, replacing the old "kept on purpose" exception. Three text roles are added (text.unreachable, text.microtask, text.task) so text no longer borrows a stroke colour. The dark palette's values are unchanged.

Role Old → new Worst ratio
object.stroke #10b981 → #059669 2.24 → 3.32
array.stroke #0ea5e9 → #0284c7 2.42 → 3.57
focus / root #f59e0b → #b45309 1.74 → 4.08
unreachable.stroke #f43f5e → #be123c 3.06 → 5.24
text.muted #94a3b8 → #586880 2.14 → 4.72
text.root #d97706 → #92400e 2.59 → 5.75
text.onFocus #b45309 → #92400e 4.08 → 5.75

3D labels. The first caption of the Event Loop story's 3D view used to render empty, which was worked around by remounting it; that remount produced React "synchronously unmount a root" errors in development. The real cause is that drei moves every Html during the mounting commit. A stable label host (useLabelHost) removes both the workaround and the errors. A test with a real canvas and drei reproduces the empty caption and the errors without the fix.

Small fixes. The Stack ↔ Heap story's beat count is derived from its beat model. The Marble Diagrams take(3) picture completes with the third value.

Checks

npx tsc -b, npm run lint, npm run test:run (1,207 tests in 90 files) and npm run build pass; three.js is not in the entry graph.

Checked in the browser: label sizes at 1024, 1280 and 1536; the light colours on the Stack ↔ Heap story; both stories in 3D with all captions present and no console errors.

Known

  • At 1024px the two JavaScript stories reach about 8.8px, not 10px: the section is 606px wide and they need about 670px. Only narrower page padding would close that.
  • The focus colour is visibly different: a dark amber where it was a bright one.
  • Not enforced by the test: region and label borders, lit 3D solids and translucent halos.
  • The Git 3D scenes still use un-hosted labels.

🤖 Generated with Claude Code

Stories: the code panel stays above the picture until 2xl, where a 62% column still draws 12-unit labels at 10px (storyLayout.ts, with the page-width model and tests). Beat counts come from the beat model.

Palette: every light colour the story views draw as text reaches 4.5:1 and every mark 3:1 on each background it is drawn on; the pinned exceptions are gone. New text roles (unreachable, microtask, task) replace strokes used as text. Dark renders as before.

3D: drei Html labels are attached to the Canvas's outer element from their first render (useLabelHost), so they are never moved during the mounting commit. That removes the 'synchronously unmount a root' errors and the empty first caption, so the keyed remount is gone. Covered by a jsdom test over the real Canvas and Html.

RxJS: the built-in take(3) marble diagram completes with its third value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mnaimfaizy
mnaimfaizy merged commit c46b064 into main Oct 13, 2026
9 checks passed
@mnaimfaizy
mnaimfaizy deleted the fix/visual-polish branch October 13, 2026 06:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant