Acceptance Criteria
- A new "Compositions" category exists under
site/content/ with its own index/landing page explaining the media-zone model (containers adapt the slot; guests are open). - Each Family A pattern is its own page: authored Markdown + rendered
preview + the mechanism note. - Only patterns that are actually styled/verified (WORK-339, WORK-345) ship as Family A pages; un-verified families (B/C/D/E) are scaffolded or deferred, not documented as working before they are.
- The surface compositions (cover/frame/elevation/substrate/tint/gradient) are documented as patterns and cross-linked with the surface-model gallery (WORK-380) and the
surfaces/card/bg references. - The category is linked from the docs nav and cross-referenced from the rune-authoring composability guide (WORK-338).
Approach
Author as standard site content with the preview rune for live results. Keep one pattern per page so the catalog grows incrementally as later families become first-class. Family A pages depend on the media-zone work landing first.
References
- Catalog source: the composability investigation (this milestone's discussion)
site/content/ structure; preview rune- Mechanisms: WORK-339, WORK-345; contract SPEC-084
Resolution
Completed: 2026-06-10
Branch: claude/work-346-compositions-docs (stacked on claude/work-380-surface-gallery)
What was done
- New Compositions category under
site/content/runes/:runes/compositions.md — landing page explaining the media-zone model (open containers adapt the slot name-agnostically; guests are open), a grid index of the starter patterns, a "Surface compositions" section framing the second axis, and a "Other families" note deferring B–E.- Curated Family-A starter (5 pages), each = authored Markdown + live
{% preview %} + a "How it works" mechanism note: codegroup-in-card (code-sample card), chart-in-card (metric card), map-in-card (location card), diagram-in-card (architecture card), chart-in-bento (dashboard grid — same chart guest, different container).
- Wired into the runes sidebar nav (new "Compositions" group in
runes/_layout.md). - The composability guide's two forward-references (
extend/rune-authoring/composability.md) now resolve to /runes/compositions instead of "forthcoming; WORK-346".
Verification
- Full
vite build green; all 6 pages emit. Structural checks on the output: each pattern's guest nests inside its data-section="media" zone (codegroup renders as data-rune="code-group"), chart-in-bento places both charts in both cell media zones (2/2/2), the landing grid renders 5 linked cards, and there are no error/unknown-tag markers. - The build's lone error (SPEC-041 duplicate spec id) and 29 warnings are all pre-existing and unrelated.
Cross-branch dependency (why stacked)
- Criterion 4 requires cross-linking the surface-model gallery (
/runes/surface-gallery), which lives on the WORK-380 branch. SvelteKit prerender hard-fails on dangling internal links, so this branch is stacked on claude/work-380-surface-gallery to keep the strict link-check intact and the build green. Merge order: WORK-380 first (or together), then this. The _layout.md nav edits from both branches are additive and merged cleanly on rebase.
Why review, not done
- Visual pass pending (same as WORK-380): no headless browser in this container, so the 5 new
preview clusters are build-verified structurally but not eyeballed in light/dark/mobile. Worth a glance when running the dev server — map-in-card (interactive guest, live), chart-in-bento (cell media sizing / row-track alignment), and diagram-in-card (SVG fit) especially. - Curated starter, not the full Family A — criterion 2 ("each Family A pattern is its own page") is intentionally left unchecked: 5 of the ~10 Family-A patterns ship now (the doc-grounded ones); the rest —
gallery, embed, audio/playlist, design swatch/palette, timeline — are listed on the landing page and join the catalogue as they're verified. Decide at review whether to finish the remaining patterns here or split them into a follow-up item.
Completed: 2026-09-24
Closing note — milestone audit, 2026-09-24
Flipped from review to done during a v0.20.1 close-out audit. The item had sat in review since 2026-06-10, holding v0.20.1 open long after it shipped.
The page-per-pattern criterion is checked as superseded, not as met. The "Compositions" category it describes was deliberately reorganised into a single consolidated site/content/runes/media-guests.md under the Essentials nav group — the Update section above records that IA decision and why (duplication forming between the surface docs and the composition docs). Page-per-pattern is no longer the intended shape, so the criterion cannot be met as written and is closed rather than left dangling.
Two things this item deliberately does not carry to completion, neither of which should reopen it:
- The remaining Family-A patterns (
gallery, embed, audio/playlist, design swatch/palette, timeline) are listed on the page and join it as they are verified. That is ongoing docs work, not an open work item. - Families B–E stay deferred, as the original scope stated.
The light/dark/mobile visual pass was never performed — no headless browser in the container. A regression found on media-guests.md should be filed as a bug against that page rather than reopening this item.