Skip to content

0051: The folded-paper visual identity and scripted product recordings

  • Status: accepted (the maintainer chose the direction on 2026-11-01 and approved the preview on 2026-11-15, restyle-site-folded-paper task 5.3)
  • Date: 2026-11-01
  • Change: restyle-site-folded-paper

Context

The marketing site (ADR 0040, ADR 0050) was built with placeholder styling: system fonts, a white page with a teal accent, an empty mark slot and a text favicon. The finished logo, a hexagon of folded bands in blue, teal, gold and copper around a keyhole, sat unused in web/brand/logo/. Nothing on the site showed the product working, and the home page led with storage rather than with what is new: AI coding agents can use secrets without seeing them, with a human approving each scope.

The site has hard constraints that any look must keep: no JavaScript on marketing pages, no request to another origin, a strict Content-Security-Policy, WCAG 2.2 AA in both colour schemes, a 100 KiB page budget, a 60 KiB font budget, and every product claim registered and gated.

On 2026-11-01 the maintainer compared four hero directions and three motif strengths in mockups (kept in openspec/changes/restyle-site-folded-paper/mockups/) and chose "folded paper", strong throughout, with a dark version, the fonts below, the logo, a new headline and real product clips.

Decision

  • Folded paper. Every section of a marketing page sits on the paper base or one of the logo's colour tints with a large hexagon fold shape; cards carry a paper-stack shadow; the logo's five-colour strip divides sections; steps and icons sit in hexagons; buttons are pills; ink is #12313a. Everything decorative is CSS and stays out of the accessibility tree.
  • One source of colour. All colours are tokens in web/brand/tokens.ts, generated into /theme.css for both schemes; stylesheets use only the custom properties, and a check refuses colour literals elsewhere. The contrast check covers every text token on every background it can overlap, including the fold shapes, which are opaque for that reason. The mockup's gold focus ring fails 3:1 on light paper, so the light scheme uses #1f4a5c.
  • Dark paper follows the system. Marketing pages switch on prefers-color-scheme with no toggle (a toggle needs script); the docs keep Starlight's toggle on the same palettes.
  • Self-hosted fonts from the package manager. Lexend 600, Atkinson Hyperlegible 400 and 700 and JetBrains Mono 400 come from Fontsource packages and are subset at build time to printable ASCII, which loses nothing because the site is ASCII-only by rule. They fit the existing 60 KiB font budget. No font service is used.
  • The logo is the master; everything else is derived at build time. The header mark, hero logo, favicon set, touch icon and social image are generated from the committed transparent PNG. The SVG export is about 1 MB, so the favicon is raster. The wordmark stays text.
  • Clips are recordings of the real product, made by a script. A pipeline in Docker (make web-media) builds the CLI, daemon, native host and extension from the tree, creates a demo vault with fake data, runs a scene script that reuses the extension's end-to-end harness, and encodes short muted loops. Terminal scenes are recorded from real pseudo-terminals and rendered deterministically with xterm.js; the browser scene is captured from a headed Chromium under Xvfb driven by real X input. Output is never edited; idle gaps may be shortened and typing is scripted, and the clip's description says so.
  • A clip is held to the claims registry. A committed manifest lists each clip's files and hashes, its duration and dimensions, the absence of audio, the claims it demonstrates and the hashes of the scene and fixture that made it. The website checks fail when a file, scene or fixture drifts from the manifest or when a demonstrated claim disappears or becomes a roadmap claim. The scenes assert their own story and also run in make e2e, so a product change that breaks a clip's story fails the existing suite.
  • Clips play only where they help. They autoplay muted with native controls (so they can be paused without script) only when the visitor has not asked for reduced motion and the viewport is at least 40 rem wide; otherwise a still and a text description are shown and no video is requested. Clip files have their own budget; the 100 KiB page budget keeps counting everything else, and Lighthouse's mobile performance score stays the gate.
  • media-src 'self' joins the Content-Security-Policy.

Decided while building (groups 1 to 4)

  • The browser clip uses the end-to-end extension build. Chromium reports navigator.webdriver as soon as a remote debugging port is open, so the store build's content script does not run under the recorder, and the release native host refuses a browser started with a debugging port or a loaded extension. The clip is recorded with the e2e extension build and a daemon and native host built with the vaultfold_e2e tag, and its manifest entry says so (extensionBuild: "e2e"). Everything the viewer sees is real vaultfold UI.
  • The terminal clips stack two panes (one above the other) because two 60-column terminals do not fit 1280 px across; step text names the panes by title.
  • What the approval clip claims. The agent's first run exits with approval pending and is not shown a code; the code is shown to the human by vaultfold agent approve, whose listing names the vault, the scope and the program asking (not a session). The copy, the registry claim (dev.agent-approval) and the spec were changed to say exactly that; the product was not changed.
  • No hero logo on the home page (the maintainer's decision at copy sign-off): the logo is in the header only. The section label chip is one colour on every band (--accent), so it stays visible on each tint.
  • The wide-screen navigation uses details::details-content behind an @supports test, so the header menu needs no script; browsers without it keep the Menu button at every width.
  • Docs. Starlight's variables come from the same tokens as the marketing pages in all four places the docs use them, the gray scale being the ink, the soft ink, three mixes of ink and paper, the code background and the raised paper; --sl-font and --sl-font-mono are the self-hosted faces. Starlight's "black" is the card token, because Starlight paints raised surfaces (the search box, cards) with it and also uses it as the label on a link or accent fill. The docs' extra contrast pairs are declared beside the marketing pairs and held to the same minimums. The docs header carries the logo through a SiteTitle override that renders the same optimised WebP as the marketing header, not Starlight's logo option, which would ship the 512 px master PNG (about 200 KiB) on every docs page and took the docs index to 94 on Lighthouse performance (target 95); with the override it scores 98. The colour strip under the docs header is drawn on the page header element only (Expressive Code frames have a .header of their own).

Consequences

  • The site's look is a token file, a stylesheet and a handful of components; changing a colour is one edit, re-checked for contrast.
  • Re-recording a clip is one command, but someone has to run it: a product change that alters what a clip shows without breaking its story will not fail any check, and the clip shows the older output until it is re-recorded. The web README says when and how to re-record.
  • Clips are binary files in the repository (about 1 to 3 MB per recording round). If that grows into a problem, the files can move to release assets without changing the page markup.
  • The recordings need a Linux container with Xvfb and ffmpeg; they cannot show macOS or Windows UI, so platform prompts (the macOS helper, the Windows dialog) are not filmed. The approval clip uses the terminal path that works everywhere.
  • On a phone the clips are stills. If phone visitors should see motion, the width condition can be dropped in one constant, at the cost of about a megabyte per home page view.
  • The cross-device "approve from your phone" flow is not filmed; it is a roadmap claim until the phone apps exist.