Skip to content

Rebuild the viewer as canvases (Phase 31 slice I) - #253

Merged
vicmaster merged 5 commits into
masterfrom
phase-31-slice-i
Nov 18, 2026
Merged

vicmaster merged 5 commits into
masterfrom
phase-31-slice-i

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Phase 31 slice I, the last slice. The phase began when framesmith judged its own viewer and gave every page a perfect usability score while the viewer had a 17px Back link and 21 click targets built from plain spans. This PR rebuilds the viewer as canvases on the finished phase, through the real tools, and keeps the rebuild as a test. The run surfaced three framesmith defects, fixed here.

The rebuild

test-viewer-rebuild.ts drives the MCP server over stdio, as test-ridgeline.ts does for Phase 30:

  1. project_create, then one design system for the whole app at project scope: generate_design_system with seed #B45309 (amber, the viewer's accent), the technical personality and the 14px desktop-app body.
  2. Three base canvases, each canvas_create({ type: "desktop-app" }), then apply_structure, then batch_design:
    • Gallery from browser-app.
    • Canvas detail from editor-inspector-app.
    • Archive from split-workbench-app.
  3. Three screen-state variants made with canvas_add_variant:
    • comment-open: a popover under the Comment button, placed from the button's snapshot_layout box.
    • confirm-delete: the delete dialog.
    • the archive's empty state.

No autofix, no token overrides and no rule changes. Every canvas resolves its tokens from the project, and every colour on every canvas is a $token.

Canvas Fast Detailed Stress Designed truncations
Gallery 99, READY 99, READY CLEAN 15
Canvas detail 100, READY 100, READY CLEAN 28
Archive 100, READY 100, READY CLEAN 20
Comment open 100, READY 100, READY CLEAN 28
Confirm delete 100, READY 100, READY CLEAN 28
Archive empty 99, READY 99, READY CLEAN 8

What every one of the six shows, in both modes:

  • Findings. Zero errors, warnings and cliché tells. The remaining infos are APCA advisories (two or three in the dark theme) and a typography note.
  • Dark theme. No dark-theme warning or error. The project carries a dark layer, and a negative control proves the dark check is live.
  • Click targets. Zero desktop-app-handbuilt-target findings.
  • Surface report. surface.rulesOn holds all 14 desktop-app-* rules, and rulesOff holds type-scale-ratio. rulesOn lists the rules that are enabled. desktop-app-row-rhythm is enabled but not exercised, because none of the six canvases has a table.
  • Stress. The directive reads each canvas's own current CLEAN stress run.
  • Perturbations. Every stress perturbation touched at least one node, with one exception: big-numbers has nothing to widen on the empty archive, which shows no figures.

The test also proves its own checks are live: ten twins that must fail, nine of them on throwaway clones of the detail page and one a check of the test's own duplicate-card predicate. They cover:

  • a dark-only contrast failure;
  • the baseline's hand-built Back control;
  • two packed 20px buttons;
  • a label that clips under long text;
  • a popover off the window;
  • a focus ring the colour of its panel;
  • a canvas never stressed;
  • an edit after a stress run;
  • two primaries in one dialog;
  • a duplicated issue card.

The six baseline defects, by name

# Baseline defect In the rebuild
1 Muted labels at 2.14:1 (and near misses under 4.5:1) $text-secondary measures 5.58 / 6.00 / 5.58:1 on the three surfaces in light and 4.64 / 5.38 / 4.64:1 in dark
2 "← Back" target 17px tall A link (icon arrow-left, label "Back"), 24px tall, with no desktop-app-target finding
3 Inspector tabs were spans One tabs node: Quality, Design system, Feedback, one active
4 Issue cards were clickable divs Plain content holding a link ("Show 4 nodes")
5 Four identical issue cards in a row One card per distinct finding, 18 findings in 7 cards, the repeat naming its 4 nodes
6 Delete beside Archive at the same weight Delete is a destructive button behind a divider; Archive is secondary

Muted labels
Back
Inspector tabs
Issue cards
Grouped issue
Delete apart from Archive

The full screens, in the dark theme, are in docs/viewer-rebuild/:

Gallery
Canvas detail
Comment open
Confirm delete
Archive
Archive empty

Where the rebuild differs from the live viewer:

  • Archive list. The archive lists canvases as tree rows grouped by project, because list-row has no selected state and the detail panel shows one selected canvas.
  • Card score. Each card's score sits on its preview as a badge, as the live viewer overlays it. A title row would have taken the card past the 8-level depth advisory.
  • Sidebar. The sidebar shows five projects, because the amber seed yields five distinct series colours for the identity dots.

Three fixes the rebuild needed

Detailed evaluate now measures layout in the design system's fonts (approved before building).

  • Detailed canvas_evaluate laid the canvas out in the system fallback font. screenshot, canvas_stress and snapshot_layout render in the design system's own faces. So a detailed CLEAN was judged on different glyph widths than the screen shows.
  • The handler now prepares the same fonts in detailed mode and passes them to both detailed renders.
  • A face that cannot load comes back as a Font warnings item, as it does for screenshot.
  • Fast mode renders nothing and stays offline.
  • test-evaluate-fonts.ts pins this. It sets a monospace body, which flips two detailed verdicts, and runs a sans-serif twin where neither fires.

A drawer and a scrolling popover or menu read as scrolling under stress.

  • Panes with overflow: "auto" were already read as scrolling, but overlays build their own markup and missed the marker. So the comment popover (a fixed height with a scrolling body) and every drawer were reported as clipped under long text.
  • They now carry the marker.
  • A popover with overflow: "hidden" still clips.

Fonts used only inside a component are loaded.

  • An instance has no children of its own, so a family used only inside a component was never fetched. It rendered in the fallback face in screenshots, stress and detailed evaluate.
  • The font backstop now also reads the component definitions.

A smaller correction came with these:

  • Stress now names the width when a scrolling node overflows sideways.
  • A scrolling root that overflows sideways as well as down is now a warning. It used to be passed off as the root simply "growing taller".

Docs

  • The canvas_evaluate docstring, README and GUIDELINES say detailed mode lays out in the design system's fonts.
  • The canvas_stress docstring, README and GUIDELINES name the drawer and the scrolling popover or menu.
  • The batch_design docstring and GUIDELINES recommend overflow: "auto" on a fixed-height popover or menu.
  • VISION ticks slice I, closes Phase 31, and adds two follow-ups the rebuild found:
    • a misspelt non-colour token resolves to nothing with no finding;
    • nav-item counts are not a stress slot.
  • The spec gains slice I's contracts, an as-built block, and every verifier finding with what it changed.

Testing

  • npm run test:full: 138/138 on the final revision.
  • Each new fixture was proved failing on the code before its fix and passing after.
  • test-ridgeline.ts and the desktop pattern gates still pass with detailed evaluate in the real fonts.

@vicmaster
vicmaster merged commit f5aa9c6 into master Nov 18, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-31-slice-i branch November 18, 2026 19:04
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