# `<name>.examples.html` section order convention

Every primitive's own `packages/web-components/components/<name>/<name>.examples.html`
follows one binding `<h2 variant="section">` order. gh#4159: a merged-registers sweep
(gh#3843) found the order inconsistent across five files, `alert` had "Typography
registers" near the top, `code`/`command` had it after the generated API tail, and
`accordion`/`divider` had it before Edge Cases, with no reference doc anywhere stating
which shape was correct. `site-docs-authoring`'s own `intent.md` explicitly declines
`packages/web-components/components/*/*.examples.html` and hands it here; this file is
that hand-off's landing spot.

## Required order

1. **Variant/usage sections**, one `<h2 variant="section">` per prop value, state, or
   usage recipe the component demonstrates (`inline`, `block with language`, `grouped`,
   …). Author-ordered; no fixed sequence among these.
2. **`Combinations`**, sections composed together in context.
3. **`Typography registers`**, the three-register (`scale="ui-sm"` / regular /
   `scale="content-md"`) showcase, when the component carries one. Hand-authored, so it
   sits with the other hand-authored sections above, immediately after `Combinations`
   and before `Edge Cases`, never after the generated API tail.
4. **`Edge Cases`**, boundary conditions and unusual content.
5. **Generated API sections**, in order: `Properties`, `Events`, `Methods` (when
   applicable), `CSS Tokens`, `Slots`, `A2UI`, `Related`.

Rationale for `Typography registers` landing before `Edge Cases` rather than after the
API tail: it is hand-authored prose+markup like `Combinations`/`Edge Cases`, not a
generated table like `Properties`/`Events`/`CSS Tokens`; grouping it with the other
hand-authored sections keeps the generated-vs-authored boundary at one place in the file
instead of two.

## Why this also matters for `.examples.md`

`scripts/build/generate-examples-md.mjs` derives each `<name>.examples.md` from the
`.examples.html` source. Its main loop picks only the first `MAX_FRAGMENTS` (3)
`data-section` blocks in document order, so a section sitting far down the file (several
variant sections deep, as most shipped components run) would normally never be selected.
`Typography registers` is the one named exception: `processComponent()` guarantees its
inclusion regardless of ordinal position, so this convention is about authoring
coherence and readability, not about whether the section survives derivation at all.

## Enforcement

`generate-examples-md.mjs`'s own `checkSectionOrder()`, run as part of `npm run
check:examples-md-fresh` (`--verify` mode) and the plain generate run alike, parses
every `packages/web-components/components/*/*.examples.html`'s ordered `<h2
variant="section">` list and reds, naming the file and both indices, when `Typography
registers` sits after `Edge Cases`. Pre-existing violations outside a given PR's own
lane are grandfathered via `scripts/build/examples-registers-order-baseline.json` (a
ratchet: printed as an advisory finding, never silently dropped, and never allowed to
grow) so the gate never regresses unrelated work; shrink that list to zero as each
file's own section order gets fixed.