WORK-338
ID:WORK-338Status:done

Composability authoring contract + CLI coverage audit

The authoring-facing half of SPEC-084: a contract guide for rune authors plus a CLI audit. (The end-user catalog of concrete compositions lives separately in the "Compositions" docs category, WORK-346 — this item is the "how the contract works" reference, not the recipe book.)

Priority:mediumComplexity:moderateMilestone:v0.19.0Source:SPEC-084

Criteria completion

Criteria completion: 5 of 5 (100%) checked; history from Jun 5 to Jun 60%25%50%75%100%Jun 5Jun 6
Branches 3
History 6
  1. 633f0a1
    • ☑ A composability page under `site/content/extend/rune-authoring/` documents the contract: the open-world principle (dependency asymmetry), open containers vs strict `requiresParent` children, the name-agnostic media-zone/slot styling model, and when to reach for a context modifier.
    • ☑ `refrakt inspect`/audit reports context modifiers that lack CSS coverage.
    • ☑ The audit reports `requiresParent` violations (a child outside its self-declared required parent) for a given content tree.
    • ☑ Audit output documented in the tooling docs.
    • ☑ The authoring guide cross-links to the "Compositions" catalog (WORK-346).
    by bjornolofandersson
  2. 6839d7f
    Created (draft)by bjornolofandersson
  3. c09cb5a
    Content editedby Claude
    plan: de-link mutual refs in composition items to keep the dep graph acy
  4. 0543147
    Content editedby Claude
    plan: media-zone composition model — generalize 339, add bento + docs it
  5. 33c6175
    Content editedby Claude
    plan: revise SPEC-084 to an open-world composability model
  6. 33e11b7
    Content editedby Claude
    plan: shape v0.19.0 around polish, composability & rollups

Acceptance Criteria

  • A composability page under site/content/extend/rune-authoring/ documents the contract: the open-world principle (dependency asymmetry), open containers vs strict requiresParent children, the name-agnostic media-zone/slot styling model, and when to reach for a context modifier.
  • refrakt inspect/audit reports context modifiers that lack CSS coverage.
  • The audit reports requiresParent violations (a child outside its self-declared required parent) for a given content tree.
  • Audit output documented in the tooling docs.
  • The authoring guide cross-links to the "Compositions" catalog (WORK-346).

Approach

Extend the existing inspect/audit tooling (packages/cli) — it already derives selectors from config and checks CSS coverage, so the context-modifier check is an extension of that path. The guide is the contract reference; concrete worked patterns live in the compositions category.

References

  • packages/cli (inspect/audit), site/content/extend/rune-authoring/
  • Depends on SPEC-084; complements WORK-337; pairs with WORK-346

Resolution

Completed: 2026-06-05

Branch: claude/v0.19-composability

What was done

  • Authoring guide: site/content/extend/rune-authoring/composability.md — documents the contract: the open-world dependency-asymmetry principle, strict requiresParent children vs open containers, name-agnostic media-zone/slot styling (with the self-declared bleed opt-out), when to reach for a contextModifier, the deferred capability-token generalization, and a Tooling section. Cross-links to the Compositions catalogue (/compositions, WORK-346).
  • CLI audit (AC #2 — already covered, verified): refrakt inspect <rune> --audit already derives and checks context-modifier selectors — e.g. .rf-hint--in-feature → hint.css:88, and any declared-but-unstyled modifier shows NOT STYLED. Documented in the guide.
  • requiresParent surfacing: added the requiresParent line to refrakt inspect output (format.ts) — e.g. inspect tab → "requiresParent: TabGroup (validated…)". Violations on a content tree are reported at build time by the WORK-337 engine validation (and inspect-ing a stranded child prints the diagnostic).

Notes

  • AC #3 (content-tree requiresParent violations) is delivered by the build-time validation from WORK-337 rather than a separate offline CLI pass — the transform runs at build and emits the warning/error with the rune + its actual parent context.