Claude Opus 5
@@ -0,0 +1,79 @@
|
||||
# Theme contract
|
||||
|
||||
What the engine promises a theme, and the only thing this repository is bound to (ADR-0023). A theme's
|
||||
markup, layout and styling are not the engine's business; a theme's *inputs* are.
|
||||
|
||||
**STATUS: not built.** This is the shape the contract takes when the first template renders. Everything
|
||||
here is engine obligation, not theme instruction — a theme may ignore any of it.
|
||||
|
||||
## The stability rule
|
||||
|
||||
Fields and names are **added, never renamed or removed**. Absence is always legal: a template reading a
|
||||
field that does not exist gets the zero value and must not crash, and the engine must not make a missing
|
||||
field fatal at request time (ADR-0002, invariant 1). This is the View-layer freeze from
|
||||
`architecture.md`, arriving as soon as a theme exists rather than at Arc 2.
|
||||
|
||||
Breaking the contract is not a feature — it is a new contract version, and it needs an ADR.
|
||||
|
||||
## What the engine provides
|
||||
|
||||
| Provides | Detail |
|
||||
|---|---|
|
||||
| the page object | known fields plus an `Extra` bag carrying unknown frontmatter (ADR-0002) |
|
||||
| the resolved cascade | settings for this bundle after site → section → bundle resolution (ADR-0017) |
|
||||
| queries the page needs | its sequence neighbours, its taxonomy terms, its section's members |
|
||||
| named template lookup | per-type sets; a theme redefines a named block and inherits the rest (ADR-0019) |
|
||||
| URLs | every path the engine emits, so a theme never constructs one by hand |
|
||||
| per-page assets | the `styles` / `scripts` frontmatter lists, resolved relative to the bundle |
|
||||
| chrome strings | looked up by key and language, never hardcoded English in a template |
|
||||
| validity windows | a template that renders time-dependent output declares one (ADR-0013) |
|
||||
|
||||
## Extras view
|
||||
|
||||
For a request under a bundle's extras directory (ADR-0025) the engine additionally provides:
|
||||
|
||||
| Field | Contents |
|
||||
|---|---|
|
||||
| `.Extras.Entries` | the tree: `Name`, `Path`, `URL`, `RawURL`, `Kind`, `Size`, `IsDir`, `ModTime` |
|
||||
| `.Extras.Selected` | nil on the bare listing; otherwise the chosen entry |
|
||||
| `.Extras.Selected.HTML` | rendered output for `markdown` and `text` kinds; empty otherwise |
|
||||
| `.Extras.Selected.RawURL` | always present — for `<img src>`, `<object data>`, or a download link |
|
||||
|
||||
`.Bundle` is the parent, so a theme has its title, language and breadcrumb. Selecting an entry is an
|
||||
ordinary link and a full re-render, so a sidebar-plus-pane layout needs no JavaScript; swapping the pane
|
||||
client-side is a later enhancement over working markup, never a requirement.
|
||||
|
||||
## What the engine does not provide
|
||||
|
||||
Layout, class names, CSS, client-side behaviour, and any choice about how something *looks* — including
|
||||
how media is embedded, how a listing is arranged, and whether something appears in a sidebar. Those are
|
||||
theme decisions, and a request touching them is split: a contract extension here, a change there.
|
||||
|
||||
The engine also does not provide a component library, a CSS build step, or a JavaScript runtime.
|
||||
`conventions.md` holds the output floor the engine itself meets — semantic HTML, zero-JS, every image
|
||||
carrying width, height and alt — and a theme is expected to stay inside it, but the engine does not
|
||||
enforce a theme's markup.
|
||||
|
||||
## The reference theme
|
||||
|
||||
The binary embeds a reference theme — templates plus one small stylesheet — so a bare site root renders
|
||||
(ADR-0026). It exists to make this document executable: it implements every field and block named here and
|
||||
nothing else, and a golden-file test through it catches contract regressions before a real theme does.
|
||||
|
||||
It is not a design. Legibility only, no branding, no visual opinions, no JavaScript — `verify.sh` fails on
|
||||
a `<script` tag in it. If it starts accumulating taste, it has stopped being a reference.
|
||||
|
||||
It demonstrates the contract; it is not the contract. Changing it does not change what a theme may rely on
|
||||
— which is why `verify.sh` also fails when it changes without this document changing, since in practice the
|
||||
two drift together.
|
||||
|
||||
## Splitting a request
|
||||
|
||||
When a feature spans engine and theme, this repo delivers:
|
||||
|
||||
1. the contract extension — new fields, new named blocks, new queries, new URLs;
|
||||
2. a note stating what a theme must do to use it, precise enough to act on without this conversation;
|
||||
3. embedded defaults updated far enough to prove the extension works.
|
||||
|
||||
It does not deliver the theme. Claiming otherwise is the same error as claiming to have migrated content
|
||||
in a site root this repo cannot see.
|
||||
Reference in New Issue
Block a user