diff --git a/docs/AGENTS.md b/docs/AGENTS.md index c73084b38..281b72fc8 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -41,7 +41,7 @@ One component per job. If two components on a page render the same list, delete | Static image | `Frame` with a caption that says what it is | A bare `img` with no context | | Genuinely out-of-band aside | One `Note`, `Tip`, or `Warning` per page | Stacked callouts, or a callout for ordinary prose | -**Do not use accordions for journeys, choices, instructions, or troubleshooting.** They hide the thing the reader needs, cost a click, and weaken `Cmd+F`, printing, and deep linking. A dense optional reference or example gallery may keep accordions when showing every item at once would make the page unusable; the Prompt Guide's verified-example gallery is the existing exception. Long symptom or task lists become visible `##` sections instead — they get anchors the support team can link directly, and they appear in the page contents. +**Do not use accordions for journeys, choices, instructions, or troubleshooting.** They hide the thing the reader needs, cost a click, and weaken `Cmd+F`, printing, and deep linking. A dense optional reference or example gallery may keep accordions when showing every item at once would make the page unusable. Two patterns in the Prompt Guide are the standing exceptions: its verified-example gallery, and the per-page `## Variants` blocks. Those hold long alternative prompts rather than parallel instructions, so the `Tabs` row above does not apply — a reader picks one to read in full, not one of several ways to do the same step. Long symptom or task lists become visible `##` sections instead — they get anchors the support team can link directly, and they appear in the page contents. **No diagram that restates adjacent prose.** A four-node flow beside a four-step list is the same content twice. Keep whichever is more useful and delete the other.