Arrangements name topologies; variants are modifiers; semantics are rune-locked

Decision

Six rules governing how the arrangement vocabulary may grow. They govern a vocabulary that does not exist yet; that is deliberate, and rule 5 says why.

1. Topologies get names

An arrangement names a topology — the shape of the relationship between a container and its children. stack, row, grid, split, ladder, tree, rail, track are topologies. timeline, steps, playlist are not; they are runes that use one.

2. Variants are modifiers, not names

Direction, marker, connector, wrap and density are modifiers on a topology. Promoting a combination to a name produces a combinatorial explosion: naming timeline immediately owes timeline-horizontal, timeline-grouped, numbered-horizontal, numbered-grouped.

3. Semantic modifiers are rune-locked; cosmetic ones are theme-free

marker: ordinal | positional | none is rune-owned and immutable — it states whether the index is data. The marker's chrome (circle, square, bare numeral, colour, weight), the connector's rendering, spacing, and responsive direction collapse are entirely the theme's.

This is ADR-028's principle one level down: a theme may not redefine what a section is, and it may not redefine whether an index is information.

4. Arrangements nest

A container's topology and its items' internal layout are independent. A playlist is a ladder of rows; a steps list is a ladder of stacks. This is the capability whose absence currently forces bespoke CSS: after BUG-024 removes track's duplicated counter, the remaining display: flex / flex: 1 / ellipsis in skeleton/styles/runes/track.css is the track's inner arrangement, which no mechanism can declare.

5. Two bars, by what the addition is for

An earlier draft had one rule — three existing implementations before promotion — which is right for one kind of addition and circular for the other. Existing implementations only exist for shapes the current vocabulary permitted, so counting them approves consolidations of what people already hand-rolled and can never approve anything new. rail reads as having one consumer not because rails are rare, but because nothing could declare one: every would-be rail became bespoke CSS and does not register as an implementation of anything.

5a — a consolidating topology needs three existing implementations. It replaces bespoke CSS that already exists, so the claim being made is this pattern recurs, and the repetitions are the evidence. Two is a coincidence; three is a pattern. A generic primitive that is 80% right is worse than the bespoke CSS it replaced, because the remaining 20% is fought silently in every consumer and the cost is invisible until the fourth one. Ships stable.

5b — an enabling topology needs a contract, a case, and a tier. It offers what nothing does today, so there is nothing to count. Instead it needs:

• a contract statable without naming any rune — if the definition needs an example to be intelligible, it is not a topology yet;
• at least one concrete design that wants it, with a sketch of the markup and CSS it would produce;
• no overlap with an existing topology (see rule 1 — a variant is not a topology);

and it ships provisional: recorded in the theme contract as unstable, excluded from the stability guarantee, and changeable without a migration.

Promotion from provisional to stable requires a second independent consumer that adopted it without needing its shape changed. That is what the old three-implementation bar was a crude proxy for. The thing a second consumer teaches is not "people want this" — it is "the contract survived contact with a use case its author did not have in mind."

6. Vocabulary is cheap; mechanism is expensive

Rules 5a and 5b govern mechanism. They do not govern names.

sections has a closed seven-value role vocabulary (header | preamble | title | description | body | footer | media), which is right because a role changes what the engine does. Presentational groups (rule 2 of ADR-029) have no vocabulary at all: every theme invents its own wrapper names. A conventional, open set of group names — byline, meta, actions, aside — is worth publishing at a much lower bar than a topology, because a wrong name costs nothing (add another) while a wrong mechanism costs migrations.

A group name carries no geometry. Its shape comes from the arrangement it declares, exactly as any other container's does — so a byline is a group named byline that arranges as a row, and skeleton styles the arrangement, never the name. This is what keeps the vocabulary free: nothing is stamped on a node for being called something, so a rune part that happens to share a conventional name inherits nothing and needs no reserved-name rule to protect it. Opt-in is by declaring an arrangement, not by choosing a label.

The capability is already there, under the pre-rename spelling. A layout entry's attrs are spread onto the wrapper the engine creates (placeNames, engine.ts), and skeleton/styles/dimensions/metadata.css already styles [data-zone-layout="bar"] generically — display: flex, flex-wrap: wrap, align-items: center, plus data-wrap and data-align modifiers. So this works today, in any theme, with no new code:

byline: {
  tag: 'div',
  attrs: { 'data-zone-layout': 'bar' },
  children: ['track-artist', 'track-duration'],
}

Pinned by case B2 in packages/transform/test/child-rune-layout.test.ts. What the rename buys is type safety rather than capability: stamping the attribute through attrs is a stringly-typed back door that nothing validates, where a first-class arrange key on LayoutEntry would be checked against the vocabulary.

Rule 6 also closes a concrete gap. A plugin shipping CSS for its own runes cannot target a group a theme invented. Without a conventional vocabulary, plugin CSS and theme structure cannot meet.