From 302329d5b20e1a1bae50d241877ae14c5d15a8c8 Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Wed, 10 Jun 2026 14:32:48 +0000 Subject: [PATCH] docs(website): record the cast-placement policy in STYLE.md "A cast wherever the app does something": broad on Getting-started / Using-the-playground / Guides + the landing; selective on Reference (motion beats the still, static output kept regardless); skip pure-lookup/conceptual. Casts are selective (a representative slice, not every command); autoplay only the landing; all re-record via `pnpm casts`. --- website/STYLE.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) 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.