Relationships
Informs 1
Related 7
Branches 4
History 1
c527aa0Created (accepted)
Context
A composed rune (SPEC-145) is one definition in two halves:
- its input: attributes, content model, slots, fields, presets, translation keys, and the schema.org row;
- its template: how the slots and fields are placed into primitives.
ADR-043 drew the line between theme and definition so that a theme supplies no structure. Its rationale ends: "What a theme can never do again is restructure a rune, which under composition is correct." That was right about meaning, and too broad about arrangement.
A theme can have a real opinion about how a rune is arranged without disagreeing about what it means. An elegant blog theme may want a recipe as a single column with the method beside the ingredients and the metadata in a quiet line under the title. Lumina may want the classic card. The content is the same Markdown, the fields are the same, and the published data is the same. Only the arrangement differs.
CSS on the vocabulary covers much of this (order, grid areas, hiding chrome). It cannot move a field into a heading, turn a deflist into a bar, or put the ingredients in a drawer. Under ADR-043, a theme that wants any of those has no route except asking every plugin owner for a new template.
A site has the same need, more often: "keep this rune's input, but lay it out my way".
Decision
Option 3.
Arrangement is presentation; input is identity.
- A theme or a site may supply a template for a composed rune.
- Neither may change any part of its input: attributes and their values, content model, slots, fields,
metaFields, presets, translation keys, schema row, orsequence(amended 2026-10-28, SPEC-156 D12: whether an ordinal is information is a fact about the content, so a replaced template cannot remove it).
The template speaks the vocabulary. It is written in the template language every definition uses, and places only the rune's own slots and fields, core primitives, and runes the site has. It cannot run code.
Nothing authored is dropped. A replacement template places every slot the definition has, with no exceptions. Not showing a piece of authored content is not arrangement: it changes what the rune contains. A theme that wants a slot out of the main flow places it modestly instead: in a
{% details %}, behind a popover or drawer, or small at the end. An empty optional slot costs nothing, so the rule is no burden for content that is usually absent.A template places a slot only inside the rune's own output. Sending a slot to another part of the page, such as a layout's sidebar, is not something a template can do today; SPEC-177 records it as an open question.
What is published does not depend on the template. A rune's structured data under a replacement template equals its structured data under the definition's own, checked mechanically. A theme can change how a recipe looks, never what a search engine is told about it.
A theme or site may change two kinds of default, and no others.
- The template selector. When a definition ships several templates selected by an attribute, a theme or site may change that attribute's default to another value the definition declares.
- The universal presentation axes (
elevation,density,width,frame,tintand the rest of the registered axes). "On this theme, cards are flat" is presentation. CSS alone cannot express it, because it cannot tell a default from an author's explicit value.
A rune-specific attribute (
servings,difficulty,type,status) is a fact about the content, and its default stays the definition's. An author's explicit value always wins.Lookup is site, then theme, then definition, resolved per template value and per key, so a partial override inherits the rest.
Native runes are unaffected. They have no template to replace. ADR-043 decision 6 still covers them.
This amends ADR-043. In its decision 1, "a rune's structure" and the "order, layout" in "which fields a rune shows, their order, layout, labels, and sentiment mapping" move from the definition's column to "the definition's by default; a theme or site may arrange them". "Which fields, labels, and sentiment mapping" stay the definition's. The sentence in its rationale about restructuring is narrowed to redefining.
Rationale
- The line is where meaning stops. ADR-043 was protecting meaning: what a value is, how it is labelled, what it signals, what is published. Every one of those stays on the definition's side. Arrangement never carried meaning, so it can move.
- Content stays portable. The input is unchanged, so a site's recipes render under any theme, and a theme's recipe template renders any site's recipes.
- It is safe by construction. The template language has no code, the input half is rejected in a replacement file, slot coverage is checked when the site loads, and structured data is compared, not trusted.
- It is cheap. The format, the language, the checks and the expansion already exist for definitions. A replacement is a definition with the input half removed.
Consequences
- SPEC-177 specifies the mechanism: the file format, where files are found, partial overrides,
defaults, the checks, and theme CI. - Structure contracts become per theme for composed runes. The definition's own template produces the reference contract. A theme's contract is generated with its templates and shipped in its
contractsexport, as Lumina's is today. - The block editor follows the template in use: it reads edit hints from the output, so a replacement template must keep them or declare its own.
- Theme coverage (ADR-043 decision 5) stays the baseline. A theme with no templates still renders every composed rune; templates are what a theme adds where it has an opinion.
- One more reason to compose. Native runes cannot be arranged by a theme. That is an argument for moving runes such as
recipeonto compositions (SPEC-160 D5), not for adding a lever to native runes.