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`.
This commit is contained in:
claude@clouddev1
2026-06-10 14:32:48 +00:00
parent 65a48fa5ae
commit 302329d5b2
+23
View File
@@ -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.