Concepts›Tint and color scheme

Tint and color scheme

Refrakt's tint cascade lets you express "all marketing pages are locked to dark mode" alongside "docs respect user preference" and "this one launch announcement gets the brand-warm tint" — without inventing a separate route-rules config surface. Every page resolves a (tint, tintMode, locked) tuple from four layers of input; later layers override earlier ones per field.

This page covers the frontmatter cascade. The {% tint %} rune and the tint / tint-mode attributes on a single rune are documented on the tint rune page; how a theme or adapter implements the cascade is in theme authoring → tint cascade.

The refrakt documentation site you're reading is the canonical live example. Open the homepage — locked dark, no toggle. Navigate to /docs/getting-started — auto, toggle visible in the top-right. Pick light. Navigate back to / — locked dark again; your light preference is preserved silently and reapplies the moment you return to a docs page.

The four levels

Cascade order, last writer wins per field:

LevelWhereUse it for
1. Site configtheme.colorScheme in refrakt.config.jsonSite-wide default mode (rarely needed)
2. Layout frontmatter_layout.md filesSubtree defaults — "all marketing is dark"
3. Page frontmatterThe page itselfPer-page overrides
4. Rune attributetint-mode="..." on a runeSingle-rune override (predates the cascade) — see tint

undefined at any level means inherit from the layer above. Explicit null for tint is the canonical reset to no named tint idiom — useful when you want to break out of a parent layout's named tint without applying a new one.

The three fields

tint: brand-warm           # named tint preset from theme config
tint-mode: auto            # 'auto' | 'light' | 'dark'
tint-lock: false           # true = ignore user preference, hide the toggle
FieldTypeDefaultWhat it does
tintstring | nullnullApplies a named tint preset (defined in theme config)
tint-mode'auto' | 'light' | 'dark''auto'Forces a color scheme on the page (or subtree)
tint-lockbooleanfalseWhen true, ignores user preference and hides the theme-toggle UI

Named tints come from your theme's tint presets, or from the site-level tints map in refrakt.config.json — see Sites.

The refrakt site as worked example

The site's content tree:

site/content/
├── _layout.md          # tint-mode: dark, tint-lock: true   (marketing default)
├── blog/_layout.md     # (no tint frontmatter — inherits root: locked dark)
├── docs/_layout.md     # tint-mode: auto, tint-lock: false  (reading surface)
├── runes/_layout.md    # tint-mode: auto, tint-lock: false
├── plan/
│   ├── (no _layout.md) # marketing pages for the plan system, inherit root
│   └── docs/_layout.md # tint-mode: auto, tint-lock: false  (reading surface)
└── ...

Resulting behavior by URL:

URLModeLockedToggle
/darkyeshidden
/blog/announcementdarkyeshidden
/plan (marketing)darkyeshidden
/docs/getting-startedautonovisible
/runes/hintautonovisible
/plan/docs/overviewautonovisible

A user with a saved light preference visiting / sees the dark-locked marketing page; their preference is preserved in localStorage. When they navigate to /docs/getting-started, the toggle reappears and their saved preference applies.

YAML idioms

Reset a named tint without applying a new one

When a layout sets tint: warm and a page below it wants to clear that without applying a different tint:

---
tint: ~        # YAML for null — explicit reset
---

Inherit from above (do nothing)

Just omit the field:

---
title: My page
# No tint / tint-mode / tint-lock — the layout chain wins.
---

Lock a single page to dark

Useful for a one-off launch announcement under an otherwise-auto docs subtree:

---
title: Launch day
tint-mode: dark
tint-lock: true
---

What's intentional vs incidental

A few choices in the cascade design that might not be obvious:

  • The site-wide theme.colorScheme field exists but is rarely used. Most sites want layout-level granularity; theme.colorScheme is for the edge case where you want the entire site to be dark/light by default.
  • tint-mode: auto is the default, not the absence of tint-mode. A layout explicitly setting tint-mode: auto overrides a parent's tint-mode: dark — that's how the docs subtrees unlock themselves from the root's locked-dark default.
  • tint-lock is independent of tint-mode. You can lock a page to tint-mode: auto (the user's system preference is final, no toggle UI). Useful for embedded surfaces where you don't want users fiddling but also don't have a brand preference.
  • The cascade doesn't merge tint overlays. A layout's tint: warm plus a page's tint: brand-special → the page wins, the layout's warm is gone. There's no concept of "stacked tints." Use a named tint preset that already combines what you want.