Repository navigation
Add chapter navigation, scan-first tables, state colours and code colours to explainers - #26
Merged
Merged
Conversation
…lors - ExplainerShell chapterNav: a sticky chapter rail on wide screens and a compact top bar with a disclosure list on narrow screens. It tracks the current chapter, uses fragment links, closes on Escape, and scrolls smoothly only without a reduced-motion preference. Section takes id, navLabel and anchors. The review tool docks under the rail. - ExplainerShell appearance="auto" follows prefers-color-scheme with the ISO dark tokens. Code keeps a dark plate in dark mode. - DataTable, StatusPill, Badge and Legend: sticky header, zebra rows, right-aligned tabular numbers, monospace IDs, state pills, flag badges and labelled cards below 640px. - One --ve-status-* state ramp, AA in light and dark. DiagramCanvas nodes take tone and a dashed, hatched stroke; DiagramCanvas takes a legend. - CodeBlock and DiffBlock color tokens from --ve-syntax-* through Shiki's CSS-variables theme; diff rows use --ve-code-add/--ve-code-remove with a +/- gutter. Diffs list removed lines first. - The MDX preflight decodes \u and \x escapes, so escaped code highlights correctly, and finds CodeBlock/DiffBlock tags with a quote-aware scan. - The review panel label uses --ve-accent-text, which passes AA. - An e2e browser test exports examples/visual-explainer-mdx/review-scan.mdx and checks the rail, keyboard, reduced motion, table, key, code colors, escaping and AA contrast in light and dark. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ve:export ran the MDX preflight (integrity checks, Shiki highlighting and diff rows) only on the entry file. An explainer that keeps one chapter per MDX file lost its code colours in each imported chapter. The exporter now applies the preflight to each .mdx module that the entry imports from its own directory tree, outside node_modules. The review-scan example keeps its code section in review-scan-code.mdx, so the browser e2e test fails if an imported chapter is not highlighted. The test also shares one browser across its cases, to stay inside the check budget. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ge CSS - The cover title token is clamp(1.875rem, 1.25rem + 2vw, 2.5rem): 30px on a phone and 40px on a desktop, with a 28ch measure and 1.1 leading. All presets use the token. The ISO, Algebrica and Mono Color header rules no longer set their own title and summary sizes. - Add DefinitionList and Definition (term and detail in two columns, an optional state tone, stacked below 640px) and Subsection (a titled block under a rule, with an optional marker, level 4 and a rail anchor). - A Section body has a default reading rhythm: block spacing, h3 and h4 headings, and list markers. - The review-scan e2e test checks the title size, the new blocks, and AA contrast of the definitions in light and dark. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A StatusPill or Badge in running text wraps inside its line and never gets wider than its container. In a table it stays on one line. - Inline code in a Section body clones its padding and border at a line break, so the last fragment does not extend past the column. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dder - Disclosure: a native details block with a 44px summary row and an optional meta (a count or a pill). A fragment link to the block, or to an element inside it, opens it and each enclosing block. Closed detail takes no layout, so it never widens the page. A nested block's summary is plain weight, so the outer action reads first. - ChipLinks: in-page links as 44px chips, each with an optional state pill and its word. - DiagramModes: one architecture diagram in a Simple (ELI5) and a Detailed mode on one grid. Each box is sized for the longer of its two labels and keeps its place across modes. A labelled Simple / Detailed switch sets every two-mode diagram on the page, the page remembers the choice, and the switch fades only when motion is allowed. - Touch targets: plain text links in a Section body and the mobile diagram connection links are 44px targets. - Type: the ISO section heading is one step larger (up to 2rem) with a 24ch measure, DefinitionList takes size="lead" for the first ideas on a page, and paragraphs inside a Disclosure keep the copy measure. - Tables: a long identifier, such as a path, wraps inside its cell. - The review-scan browser test checks the new blocks: 44px targets, a link that opens a closed block, stable node positions across modes and a remembered mode. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…iagrams for explainers - Disclosure: opening a block with an id writes its fragment to the address; open blocks persist for the session; a deep link opens the block and its parents and keeps the headline in view while the page settles; `share` adds a copy-link control; `lazy` renders the body at the first open, with `contains` for the link targets inside it. Subsection takes `share` too. - Term: a glossary word with a tooltip on hover, focus or tap, and `expansion` for the first use of an abbreviation. - Steps and Step: numbered run steps with rich content, two columns from 1024px. - StatusPill and ChipLinks items take a `meaning` (a tooltip and screen-reader text). Legend takes `layout="list"`. DataTable takes `density="compact"` (short cards below 640px). - Diagrams: `direction="wrap"` sets a long flow in rows across the column; diagrams shrink to fit their column (to 75% at most); only the variant that the screen shows is rendered; merged edges with one label carry it once. - Shell: a skip link, a fragment landing after the first render, focus rings on disclosure summaries, and no mono outside code and data. - Export: an MDX export keeps only the web-font families of its presets, as variable ranges (15 faces instead of 93 for iso). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ixes Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… its export checks
- visual-explainer-mdx/trust-map.tsx and trust-map-rules.ts: MergeVerdict, PromiseChips,
PromiseList, ClaimDetail, VerifyTheVerifiers ("Can these checks catch a bug?"),
UnclaimedChanges, WhatChanged, VerdictLegend, Glossary, Glossed, CodeRef, PromiseLink,
ArchitectureDiagram, Walkthrough and Invariants. They take the trust map, refs.resolved.json
(with the values that understando derives once) and explain.json, validate them, and throw on
bad data.
- ve:export pre-renders a page that uses them (React on the server, then hydrateRoot), so text,
tables, the merge verdict, promises and claims show without JavaScript; a no-JS deep link shows
its collapsed claim. --prerender turns it on for any source.
- Export checks on the pre-render: no claim, verifier or control ID and no code in the narrative
prose, glossary coverage of Term and abbreviations, link targets and unique ids, a result line
first in the verify level, an action on each weak check and each risky unclaimed file. With
--guard-repo and --guard-head, the no-hand-copy guard fails on two pasted lines of the repo.
- The export highlights refs.resolved.json and stamps the page with the trust-map head and hash.
- scripts/ve-mdx/trust-map.mjs writes the PR-body section from the same data.
- cards/trust-map.md: the data contract, the stable anchors, the components and the checks.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The components now read every strength, count, summary and action from the derived block of refs.resolved.json (understando scripts/derive.py, schema 2) and no longer compute them: claimChecks, checkResult, verifierReport and the mutationLabel truncation are gone. - Trust maps of schema 1 and 2 render; refs of schema 1 fail with "run understando explain again". Schema 2 checks: each claim lists checks that exist, and each verifier is a check of a claim. Strengths come from derived.claims, so a map without a verdict run still renders. - Claim cards: the derived check summary, the weakest check with its action, the joined statements, all checks in one collapsed block, and anchors for legacy ids so an old deep link opens the merged claim. - Promise cards use the derived count and tally; risks can name legacy ids. - The verify level opens with derived.verify.result and .other; every "what we broke" text is a derived sentence. - Unclaimed changes lead with the derived summary lines. - The PR section table is Claim | Strength | Checks | Weakest check. - The fixture is the fresh wallet run; an old-shape map proves schema 1 still exports. The browser test covers the claim card, the verify line, the legacy deep link and the old shape. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d strong Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Bar chips on the claims, the met count on each promise, the bar summary in the merge verdict, three kinds of control (planted bugs, degraded eval variants, broken-UI runs), the recorded browser video, a Surface and a Bar column in the PR section, and the new glossary words. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…Lead and Aside, openers and tone marks Tokens in themes.css (--ve-space-1..9, --ve-measure, --ve-text-*, two weights) set every gap and size of an explainer page. Levels get one rule above and 64px of air; subsections no rule; a definition list keeps its sentence in body ink and marks the tone on the label. A Disclosure is a boxed opener. StatusPill draws a shape per tone (check, half disc, warning, cross). Explainer code sits on a light plate in the ISO light theme. Lead and Aside open a level and hold a short note. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… numbered stations The merge verdict is a tinted panel with the state word first; each evidence-bar line and the verify result show countable squares with a key. The promises level opens with How to read a promise, worked on the weakest promise from derived data, and each promise is one card with its strength, bars and best check; extra fixes and extra core files wait behind openers. A numbered chain diagram renders as stations whose numbers match the Steps list, with each loop back as a return band. The card documents Lead, numbered and the question headings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
theclaymethod
marked this pull request as ready for review
October 11, 2026 19:36
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.
Explainers get chapter navigation, tables that are fast to read, state colours shared by diagrams and tables, and syntax and diff colours in code.
Changes
Chapter rail:
ExplainerShell chapterNav. On wide screens it is a sticky side rail; below 1200px it is a top bar. It marks the current chapter as you scroll and closes on Escape. It scrolls smoothly only when reduced motion is off.Sectiongetsid,navLabelandanchors.Tables: new
DataTable,StatusPill,BadgeandLegendcomponents. They have a sticky header, zebra rows, right-aligned numbers and monospace IDs. Below 640px each row becomes a card.State colours: shared
--ve-status-*tokens, AA in light and dark. Diagram nodes take atone. A dashed, hatched outline marks the weaker tier. A diagram can have a key.Code: the existing Shiki highlighter now uses a colour theme from the tokens. Diffs colour added and removed lines and keep the +/- gutter. In dark mode, code blocks no longer turn white.
Escaping: the pre-export step decodes
<correctly. A test checks that a<script>string in code renders as text.Chapter files:
ve:exportruns its pre-export step on each.mdxfile that the main file imports.Cover title and page blocks: the title token is now 30px on a phone and 40px on a desktop, for all presets. New
DefinitionList,DefinitionandSubsectioncomponents and a defaultSectiontext rhythm replace page CSS.Shareable disclosures: opening a
Disclosurethat has anidwrites its fragment to the address. A deep link opens the block and its parents, and keeps the headline in view. The page keeps the open blocks for the session.shareadds a copy-link control to aDisclosureor aSubsection.lazyrenders the body at the first open.Glossary terms: new
Termcomponent. Hover, focus or tap shows the definition.expansionspells out an abbreviation at its first use.Run steps: new
StepsandStepcomponents. From 1024px the steps sit in two columns.State meanings:
StatusPillandChipLinksitems take ameaning, which gives a tooltip and screen-reader text.Legend layout="list"puts one swatch, word and sentence on each line.Compact table:
DataTable density="compact"makes each row a short card below 640px.Wrap layout:
direction="wrap"puts a long flow in rows across the column.Fitted diagrams: each diagram shrinks to fit its column, to 75% at most. The page renders only the variant for the current screen. Edges that merge, and that have the same label, show the label one time.
Keyboard: the shell has a skip link. Disclosure summaries have a focus ring. A fragment lands after the first render.
Fonts: an MDX export loads only the web fonts of its presets, as variable weight ranges. The iso preset declares 15 faces, not 93. Mono shows only code and data.
Verification
npm run checkve:check,ve:evalexplainer-scan.browser.test.mjsKnown weakness: dense diagrams can have crowded edge labels. The layout engine causes this.
🤖 Generated with Claude Code