Fence scan and spec trees, rework serve reading typography - #207
Merged
Conversation
damusix
force-pushed
the
worktree-doc-legibility
branch
2 times, most recently
from
August 18, 2026 13:14
62b1d82 to
a7b4b08
Compare
damusix
marked this pull request as ready for review
August 18, 2026 13:40
Chroma emits token classes rather than inline colors, so one rendered
document follows the theme toggle, and every fence renders as a titled
window — unlabeled ones as `text`, since a tree or an outline is still a
block someone set apart.
Mermaid draws from the repo's own ramp instead of stock palettes, which
were near-monochrome in dark mode, and diagrams gain fullscreen with pan
and zoom. Diagram labels take a boundary color: mermaid wraps markdown
labels in <p>, so the page's prose color was painting them onto a fill.
Reading typography follows published doc-system defaults — a per-element
prose measure, relative code sizing, a 300px pressure on table columns,
and links off the brand amber, which measures 3.5:1 on light paper
against the 4.5:1 WCAG floor.
Specs and `atomic signals scan` fence their trees and outlines; that is
what makes them render as blocks rather than reflowed prose.
Includes the Page memoization fix, without which none of the above
survives a click: React 19 diffs props by identity, so a fresh { __html }
wrapper per render re-set the body innerHTML on any re-render and
discarded every SVG and control written into it after mount.
damusix
force-pushed
the
worktree-doc-legibility
branch
from
August 18, 2026 13:50
a7b4b08 to
8625686
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three patches against how
atomic serverenders documentation.signals scanand the spec template now fence their trees and outlines. Half the existing specs already fenced them and half indented them; nothing stated which, so the template, the currency rule,/atomic-planand the reviewer now all say fenced. Flows stay real markdown so steps keep inline code and links.Unlabeled fences no longer go through chroma. It colored nothing on them — the plaintext lexer has one token type — while stamping a Monokai background inline, so a file tree rendered as a dark box on paper. Labeled fences are untouched.
The typography pass follows published defaults from GitHub, Tailwind Typography, VitePress, Infima and MDN. Two changes are judgment calls worth a look: prose now caps at 40em per element, reversing a deliberate comment that declined a measure, and
.md-contentlinks move off the brand amber, which measures 3.5:1 on light paper against the 4.5:1 WCAG 1.4.3 floor. Chrome keeps the brand value.