WORK-215
ID:WORK-215Status:done

Refrakt site adopts the tint cascade

Update the refrakt site's layout files so the cascade actually does something visible: root locked to dark; docs/, runes/, and plan/docs/ explicitly unlocked and set to auto. The site becomes a live demo of the SPEC-052 cascade pattern.

Note: /plan/* on the site is marketing for refrakt's planning system (the @refrakt-md/plan plugin and CLI), so it correctly inherits the root's locked-dark default. Only /plan/docs/* (the plan system's documentation) flips to auto. The repo-root plan/ directory is dev-only and isn't rendered on the site at all — no concern there.

Priority:mediumComplexity:smallMilestone:v0.14.0Source:SPEC-052
chore/v0.14.0-milestone-closeout View source

Criteria completion

Criteria completion: 7 of 9 (78%) checked; tracking started on May 19, no incremental history yet0%25%50%75%100%May 19Jun 15

Tracking started May 19 — check back for trends.

Relationships

Implements 1
Related 6
Branches 3
chore/v0.14.0-milestone-closeout current done
main doneclaude/v0.14.0-spec-052-site-adoption in-progressclaude/spec-053-tint-authoring-notes ready
History 1
  1. d617243
    Created (done)by bjornolofandersson

Acceptance Criteria

  • site/content/_layout.md adds tint-mode: dark + tint-lock: true in YAML frontmatter at the top
  • site/content/docs/_layout.md adds tint-mode: auto + tint-lock: false
  • site/content/runes/_layout.md adds tint-mode: auto + tint-lock: false
  • site/content/plan/docs/_layout.md adds tint-mode: auto + tint-lock: false
  • /plan/* (plan-system marketing) has no _layout.md between root and /plan/docs/, so it correctly inherits the root's dark-locked default
  • site/src/hooks.server.ts consumes the SSR helpers from @refrakt-md/content: looks up the current page's tintCascade, calls htmlTintAttributes / colorSchemeMetaContent / prePaintScript, and uses transformPageChunk to splice them into <html> and <head> before the response goes out
  • site/src/routes/+layout.svelte adds the ThemeToggle from @refrakt-md/svelte as a fixed top-right element
  • Manual click-through of the site to confirm the behaviour described in WORK-215's bullets (marketing-dark-no-toggle, docs-auto-toggle-visible, navigation flow preserves saved preference) — post-merge spot check; the machinery is all wired
  • Visual regression / SSR snapshot for at least one page in each subtree — deferred; ad-hoc verification post-merge is the v0.14.0 standard

Approach

This is a small content edit (frontmatter updates on four layout files) that puts the whole SPEC-052 machinery on stage.

The /plan/* routes are marketing pages for refrakt's planning system (the @refrakt-md/plan plugin and CLI), not the repo-root plan/ directory — that's dev-only and never rendered on the site. So /plan/* correctly inherits the root's dark-locked default with no special handling needed; only /plan/docs/_layout.md flips to auto.

Manual smoke test pass after deploying to dev server: click through every section of the site, confirm the toggle visibility flips at the expected boundaries, confirm no FOIT.

Dependencies

  • WORK-211 — theme toggle exists and honours data-tint-lock.
  • WORK-212, WORK-213, WORK-214 — cascade machinery shipping.

References

  • SPEC-052 — "Refrakt Site Adoption" section with the configuration table
  • Layout files: site/content/_layout.md, site/content/docs/_layout.md, site/content/runes/_layout.md, site/content/plan/docs/_layout.md

Resolution

Completed: 2026-05-19

Shipped: cascade frontmatter applied to site/content/_layout.md (tint-mode: dark + tint-lock: true), site/content/docs/_layout.md, site/content/runes/_layout.md, and site/content/plan/docs/_layout.md (all three with tint-mode: auto + tint-lock: false). /plan/* marketing routes correctly inherit the root's locked-dark default (no override). site/src/hooks.server.ts consumes the WORK-214 SSR helpers and splices data-theme/data-tint-lock/meta + the pre-paint script into the response via transformPageChunk. ThemeToggle from @refrakt-md/svelte mounted in +layout.svelte. Manual click-through + SSR snapshots remain post-merge spot checks per the work item's deferral note.