diff --git a/website/STYLE.md b/website/STYLE.md index a7d22a3..5699cba 100644 --- a/website/STYLE.md +++ b/website/STYLE.md @@ -137,6 +137,29 @@ a small standalone example, not by complicating this schema. Prefer a code block when a still example suffices. - Pair a hero/landing cast with a text transcript or the equivalent docs snippet (accessibility + SEO). + +### Where to use a cast [DECIDED 2026-06-10] + +**Rule: a cast wherever the app *does something*.** A cast at the top of a page +gives the reader the *shape* of what the page describes — quickly and visually +— with the detailed text below for when they need it. (This helps visual +learners, but is valuable more broadly.) Concretely: + +- **Broadly** on the pages about *doing / interacting*: the landing, **Getting + started** (first project, modes), **Using the playground** (the assistive + editor, output-pane scrolling, undo/redo, projects, copy, export/import), and + **Guides**. +- **Selectively** on **Reference** — only where motion beats the still (e.g. + the relationship diagram being drawn; a query plan appearing). Reference + pages keep their **captured static output** regardless; a cast complements, + never replaces it. +- **Skip** pure-lookup / conceptual pages with nothing to animate (e.g. the + Types table, prose Concepts pages). +- A cast is **selective**: it shows a chosen, representative slice of what the + page documents — it need not exercise every command on the page. +- **Autoplay only the landing hero**; elsewhere casts are click-to-play (a + poster frame) so they don't all clamor at once. All casts re-record in one + `pnpm casts` run, so breadth stays maintainable. - **Driver: `autocast`** (ADR-website-001 §2; chosen by the 2026-06-10 spike). `autocast`'s `!Interactive` feeds keys to the running TUI and captures the redraw — the correct model for a full-screen crossterm app.