Design and usage review: twelve passes

2026-10-22, starting from b7892ea. Scope: workshop entry, paper studio controls, and the native dialog journey. Goal: make component adoption clearer while keeping visual hierarchy, reading order and keyboard behavior aligned. This is focused review evidence, not a claim of complete library or WCAG conformance.

Review sequence

Pass Review Result
1 Current source and ownership Pulled main; changes stay in the workshop, dialog component, stories and guides.
2 Entry hierarchy and identity Workshop hierarchy remains clear; replaced a missing arrow glyph with the shared icon and named the home link.
3 Typography and content density Dialog body now uses explicit 14px/1.6 typography, with spacing between separate paragraphs.
4 Spacing and target size Close target is 36px; long header content can shrink without pushing the close action out.
5 Themes and desktop allocation Compact dialog fits all five themes; workshop/studio/controls have no page overflow at both target desktop sizes.
6 Form labels and selected states Studio selects have associated labels; choosing a pace leaves exactly one pressed button.
7 Visual and keyboard order Stacked actions now follow DOM order; native Tab proceeds from safe alternative to confirmation.
8 Decision safety Required-decision story resists Escape and exposes explicit outcomes; invalid no-exit combinations show author guidance.
9 Long content and constrained space Long bodies scroll; focused footer actions remain reachable at 683 × 384 CSS pixels; RTL compact content fits.
10 Motion and forced colors Reduced-motion surface/backdrop transitions are zero; forced-color dialog border remains solid.
11 Usage and semantic guidance Added compact/long/required stories, short-description control, nonempty-title guard and host-validation guidance.
12 Final verification Lint, boundary checks, 20 tests, CSS/site builds and generated documentation-link checks pass.

Apply these rules when composing a screen

Evidence and limits

Current-run Chromium screenshots and DOM/keyboard checks covered the workshop, paper studio, compact actions and long-content modal. Desktop sizes: 1440 × 900 and 1366 × 768. A 900 × 600 check confirmed the workshop's unsupported notice and hidden workshop. The 683 × 384 dialog check is constrained-viewport evidence, not a full browser-zoom or assistive-technology test. Five dialog themes were checked for overflow and action order; that does not establish every color pair's contrast. Firefox, Safari, screen readers and exhaustive contrast testing remain unverified. No new compatibility shim, layout runtime or dependency was added.

Automated coverage: pnpm test-boundaries has 12 fixtures; pnpm test-dialog has 4 lifecycle tests and 4 story-contract tests. Story tests validate labels, safe focus, explicit outcomes and invalid combinations; actual CSS order and geometry were checked in Chromium. Run pnpm build-site then pnpm check-docs for guide links, and pnpm check-generated after committing generated CSS changes.