Acceptance Criteria
/docs/themes/tint-cascade page exists, rendered by the site- Opens with a one-paragraph framing of what the cascade is and why it exists (Linear/Stripe/Vercel patterns referenced briefly)
- Documents the four cascade levels (global → layout → page → rune) with a worked example for each
- Documents the three frontmatter fields with type signatures and value semantics
- Explains locked-vs-preferred — when
tint-lock: true matters, what the toggle UI does in each case - Calls out the YAML null-vs-missing idiom —
tint: null (or tint: ~) explicitly resets, missing inherits — with a small worked example - Uses refrakt's own site configuration as the canonical full example: the actual
_layout.md frontmatter for marketing-vs-docs split - Links to SPEC-052 for the full design rationale (rather than rewriting it)
- Cross-links to WORK-208's preset docs pages where appropriate
- Page renders cleanly on
cd site && npm run dev
Approach
Documentation page authored in site/content/docs/themes/tint-cascade.md. Uses Markdoc with design-plugin runes where useful — palette to visualise the tint surface tokens, preview for live examples of pages rendering under different cascade states (if practical to mock up).
Use refrakt's own configuration as the worked example throughout — it's already the live demo of the cascade (per WORK-215), so the docs page can point at the running site as "see this in action, the page you're reading right now is the docs subtree behaving the way this page describes."
The YAML null-vs-missing section deserves a clear example because it's a foot-gun:
# This resets an inherited named tint to nothing:
tint: ~
# This inherits the named tint from the layer above:
# (no tint field at all)
Dependencies
- WORK-212, WORK-213, WORK-214 — cascade must be implemented before the docs describe it.
- WORK-215 — the refrakt site's adoption is the canonical example.
References
- SPEC-052 — the spec this docs page documents
- WORK-208 — preset documentation pages that this should cross-link with