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.