Documentation visuals and accessibility
Status: PASS for the generated media, rendered diagrams, heading order, keyboard reachability, contrast in the checked pages/themes, and reduced-motion behavior. The install line in the replay is illustrative. Date: 2026-11-17 Ticket: #309 Parent spec: #301 Branch: ticket/309-docs-visuals
This record covers the visual layer for the VitePress documentation site: the terminal replay, six screenshots, Mermaid rendering, alt text and captions, and a measured browser accessibility pass. All captures use the isolated synthetic Acme Notes fixture. No real screen, display, browser tab, conversation, credential, or user path was read.
Follow-up merge-gate correction (2026-11-17)
The first handoff at 7b46d7c reported npm run verify as 2143 pass. That result did not reproduce on the independent merge gate at the same commit: 2142/2143 passed, and docs:check fails when generated reference drifts returned exit 2 instead of 1. The fixture copied docs/ but not the root README.md; the new media check read that file unguarded and threw before docs:check could report the reference drift.
The fix copies README.md and LICENSE into the docs-check fixture, makes the media checker report a missing required page as a normal validation failure, and adds a regression test for the missing-README diagnostic. The gates below are fresh results from the fixed tree. The original green browser/axe pass was not affected by this Node-only test failure and was not rerun.
Environment
| Item | Value |
|---|---|
| Host | Linux, detached tmux; no desktop or pointer interaction |
| Node | 26.12.1 |
| npm | 12.2.1 |
| OpenCode | 2.3.0, isolated HOME/XDG config/data/state |
| Provider | local deterministic fake provider; no model request or API key |
| Fixture | acme-notes workspace; agents Ada (leader), Nova, Rook; synthetic release-note prose |
| Capture geometry | 140×40 for the replay and every still |
| Motion | ENSEMBLE_REDUCED_MOTION=1 for stable frames |
| VitePress | 1.6.4 with local search |
| Python / Pillow | 3.13.5 / 13.0.0 for the manual renderer |
| Browser audit | Playwright 1.56.1, Chromium headless shell 141.0.7390.37, axe-core 4.10.3 |
Generated media
npm run docs:media starts only the fake provider and a temporary OpenCode host through the existing live harness, creates the synthetic workspace through the real RPC surface, captures the actual TUI with tmux capture-pane -e, renders the images, and writes the asciinema v2 cast. The temporary project path is redacted to ~/dev/acme-notes with same-width padding so later columns do not shift. The renderer rejects /home/, /tmp/opencode/, the current user name, and fixture markers before writing.
| Asset | Natural size | Purpose |
|---|---|---|
docs/public/media/workspace-shell.png | 1400×800 | Three panes with an active Work card |
docs/public/media/work-active.png | 1400×800 | ACTIVE Work pane, one WORKING card |
docs/public/media/work-history.png | 1400×800 | HISTORY pane with rolled-up groups and an expanded REPLIED card |
docs/public/media/approvals.png | 1400×800 | Full approvals inbox with one pending Memory approval |
docs/public/media/settings.png | 1400×800 | Ada settings, General tab |
docs/public/media/native-session.png | 1400×800 | Ada's native session with the synthetic reply |
docs/public/media/hero-terminal.cast | 110×34, 6 frames | asciinema v2 replay |
docs/public/media/MANIFEST.json records the SHA-256 and dimensions of every The acceptance review regenerated every capture at 140×40 so the full three-pane shell has room around it; the earlier 110×34 and cropped pane captures were replaced.
asset. npm run docs:media:check verifies the hashes, all DocsFigure paths, non-empty alt text, captions, the terminal-hero poster description and text summary, Mermaid accTitle/accDescr, and user-page heading order.
The fixture and visible UI states are deterministic, but elapsed-time labels, stream-phase glyphs, and the native Build durations are rendered by the host and can differ between regenerations. The manifest records the committed bytes so the docs check detects a stale file rather than claiming byte-identical replay.
The replay assets are a scripted replay: the install command is typed at a real isolated shell prompt but is deliberately not executed; the workspace, message, Work card, and native session frames are captured from the local fake host. The page caption and disclosure say so. The cast is assembled from those captured frames rather than recorded by the asciinema CLI; it is a valid asciinema v2 file and is played by the locally bundled asciinema-player.
Mermaid
Five diagrams render as SVG with accTitle/accDescr exposed as the SVG title/desc and role="graphics-document document":
concepts/architecture: Ensemble architecture.concepts/workspace-shell: three-pane shell.concepts/work-lifecycle: ACTIVE and terminal lifecycle.concepts/dispatch-budgets: budget layers and continuation paths.concepts/conversations-and-routing: group, mention, file, and direct paths.
The theme labels are pinned to VitePress text/background tokens, and node label line-height is pinned to 1.2 so the Mermaid geometry does not clip text. The architecture edge direction was changed to server -> config to separate its label from the storage edge.
Measured checks
| Command / check | Result |
|---|---|
npm run verify | 2144 tests pass, 0 fail, 0 skip; typecheck pass |
npm run docs:check | ok (contract v7; OpenCode 2.2.6/2.2.7/2.3.0; Node >=22.23.4) |
npm run docs:media | 7 assets regenerated from the synthetic fixture; manifest written |
npm run docs:media:check | ok (manifest, hashes, screenshots, cast, alt text, captions, Mermaid, headings) |
npm run docs:site:build | 183 pages, 51 redirects, local search and sitemap built |
| axe-core, 11 routes × dark/light | 0 WCAG 2 A/AA or 2.1 A/AA violations after the fixes |
| Keyboard pass | 17 unique focus stops over 18 Tab presses; first stop Skip to content; 18/18 focus indicators |
| Heading order | Home: one H1, 12 headings, no skips; Work-pane guide: one H1, 5 headings, no skips; media check covers all user pages |
| Responsive overflow | No horizontal overflow at 390, 768, 800, 860, 900, 979, 980, 1024, or 1280 px |
| Reduced motion | Poster and play button visible, no player instance, until activation; activation starts the player |
| Normal motion | The hero player starts when scrolled into view |
| Mermaid render | All five pages produced SVG with title, desc, and graphics-document role |
The 768–979 px navigation overflow was fixed by dropping the wide desktop menu row in that range; the sidebar and primary actions remain. The code-language label and Mermaid edge-label contrast fixes are in docs/.vitepress/theme/custom.css.
Limitations and not run
- No screen-reader pass (NVDA, VoiceOver, Orca), no real mobile device, and no Safari or Firefox run. The browser audit used headless Chromium against the local VitePress preview only, not the user's browser.
- No macOS/Herdr run and no real installed-package run. The docs page and assets are Linux outputs.
- The replay is not a clean public-registry install and is not a live
asciinema rec. Install output is not claimed. - The screenshots show the synthetic fake provider/model labels and fixture content. They are not customer data or a hosted service.
- VitePress reports a client-chunk size warning from the Mermaid bundle. It is a local, lazily loaded asset; no external analytics or runtime service was added.
- Long playback performance, audio, and a screen-reader-only terminal-player path were not measured. The page supplies a text summary of the replay as the accessible equivalent.