docs: widen the accordion exception to the pattern it actually covers

Rames' first item on #2976. The clause named one page while the tree has 48
accordions across eight files: 20 in the verified-example gallery it means, and
28 under per-page `## Variants` headings — which the component table two lines
above routes to `Tabs`.

That contradiction matters more than usual because this file instructs agents.
The next one asked to bring the docs in line reads 28 compliant blocks as
violations and converts them.

Named by pattern now, with the reason the Tabs row does not reach them: Variants
blocks hold long alternative prompts a reader picks one of to read in full, not
parallel ways to perform the same step. Pre-existing and untouched by this PR —
the fix is the sentence, not the tree.
This commit is contained in:
ukimsanov
2026-08-04 03:06:59 -07:00
parent e94a458fed
commit da35679bf9
+1 -1
View File
@@ -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.