Skip to content

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 ​

ItemValue
HostLinux, detached tmux; no desktop or pointer interaction
Node26.12.1
npm12.2.1
OpenCode2.3.0, isolated HOME/XDG config/data/state
Providerlocal deterministic fake provider; no model request or API key
Fixtureacme-notes workspace; agents Ada (leader), Nova, Rook; synthetic release-note prose
Capture geometry140×40 for the replay and every still
MotionENSEMBLE_REDUCED_MOTION=1 for stable frames
VitePress1.6.4 with local search
Python / Pillow3.13.5 / 13.0.0 for the manual renderer
Browser auditPlaywright 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.

AssetNatural sizePurpose
docs/public/media/workspace-shell.png1400×800Three panes with an active Work card
docs/public/media/work-active.png1400×800ACTIVE Work pane, one WORKING card
docs/public/media/work-history.png1400×800HISTORY pane with rolled-up groups and an expanded REPLIED card
docs/public/media/approvals.png1400×800Full approvals inbox with one pending Memory approval
docs/public/media/settings.png1400×800Ada settings, General tab
docs/public/media/native-session.png1400×800Ada's native session with the synthetic reply
docs/public/media/hero-terminal.cast110×34, 6 framesasciinema 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 / checkResult
npm run verify2144 tests pass, 0 fail, 0 skip; typecheck pass
npm run docs:checkok (contract v7; OpenCode 2.2.6/2.2.7/2.3.0; Node >=22.23.4)
npm run docs:media7 assets regenerated from the synthetic fixture; manifest written
npm run docs:media:checkok (manifest, hashes, screenshots, cast, alt text, captions, Mermaid, headings)
npm run docs:site:build183 pages, 51 redirects, local search and sitemap built
axe-core, 11 routes × dark/light0 WCAG 2 A/AA or 2.1 A/AA violations after the fixes
Keyboard pass17 unique focus stops over 18 Tab presses; first stop Skip to content; 18/18 focus indicators
Heading orderHome: one H1, 12 headings, no skips; Work-pane guide: one H1, 5 headings, no skips; media check covers all user pages
Responsive overflowNo horizontal overflow at 390, 768, 800, 860, 900, 979, 980, 1024, or 1280 px
Reduced motionPoster and play button visible, no player instance, until activation; activation starts the player
Normal motionThe hero player starts when scrolled into view
Mermaid renderAll 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.

Released under the MIT License.