core
Tint
Section-level color overrides via CSS custom properties
Source
import Markdoc from '@markdoc/markdoc';
import type { Node, Schema, RenderableTreeNodes } from '@markdoc/markdoc';
import { TINT_TOKENS } from '@refrakt-md/transform';
import { declareUniversalPosture, groupByHeading } from '../lib/index.js';
const { Tag } = Markdoc;
export { TINT_TOKENS };
export type TintToken = (typeof TINT_TOKENS)[number];
/** Older names, still read. */
const TOKEN_ALIASES: Record<string, TintToken> = { background: 'bg' };
const ALIAS_WARNED = new Set<string>();
function warnAlias(alias: string, token: string): void {
if (ALIAS_WARNED.has(alias)) return;
ALIAS_WARNED.add(alias);
// eslint-disable-next-line no-console
console.warn(`[refrakt] tint token \`${alias}\` is deprecated — use \`${token}\`.`);
}
const TOKEN_PATTERN = /^\s*(\w+)\s*:\s*(.+)\s*$/;
function textContent(node: Node): string {
const parts: string[] = [];
for (const child of node.walk()) {
if (child.type === 'text' && child.attributes.content) {
parts.push(child.attributes.content);
}
}
return parts.join(' ').trim();
}
function parseTintBody(children: Node[]): {
light: Record<string, string>;
dark: Record<string, string>;
} {
const light: Record<string, string> = {};
const dark: Record<string, string> = {};
groupByHeading<'light' | 'dark'>(children, {
initial: 'light',
heading(heading, section) {
const text = textContent(heading).toLowerCase();
return text === 'dark' || text === 'light' ? text : section;
},
item(item, section) {
const match = textContent(item).match(TOKEN_PATTERN);
if (!match) return;
let token = match[1].toLowerCase();
if (token in TOKEN_ALIASES) {
warnAlias(token, TOKEN_ALIASES[token]);
token = TOKEN_ALIASES[token];
}
if ((TINT_TOKENS as readonly string[]).includes(token)) {
(section === 'dark' ? dark : light)[token] = match[2].trim();
}
},
});
return { light, dark };
}
export const tint: Schema = {
attributes: {
preset: { type: String, required: false, description: 'Named tint preset from the theme' },
mode: {
type: String,
required: false,
matches: ['auto', 'dark', 'light'],
description: 'Whether the tint adapts to auto, dark, or light mode',
},
},
transform(node: Node, config): RenderableTreeNodes {
const preset = node.transformAttributes(config).preset as string | undefined;
const mode = node.transformAttributes(config).mode as string | undefined;
const { light, dark } = parseTintBody(node.children);
const metas: RenderableTreeNodes[] = [];
if (preset) {
metas.push(new Tag('meta', { 'data-field': 'tint', content: preset }));
} else if (Object.keys(light).length > 0 || Object.keys(dark).length > 0) {
metas.push(new Tag('meta', { 'data-field': 'tint', content: 'custom' }));
}
if (mode && mode !== 'auto') {
metas.push(new Tag('meta', { 'data-field': 'tint-mode', content: mode }));
}
for (const [token, value] of Object.entries(light)) {
metas.push(new Tag('meta', { 'data-field': `tint-${token}`, content: value }));
}
for (const [token, value] of Object.entries(dark)) {
metas.push(new Tag('meta', { 'data-field': `tint-dark-${token}`, content: value }));
}
return new Tag('div', { 'data-tint-source': true }, metas as any[]);
},
};
declareUniversalPosture(tint, 'configurator');
Recolor a single rune: a hint, a hero, a card. The tint rune shows nothing itself; it changes the colors of the rune it sits in. To tint a whole page or section of the site from frontmatter, see Tint and color scheme.
Basic usage
Most tints are named ones the theme defines, applied with a tint attribute on the rune itself:
{% hint type="note" tint="warm" %}
This hint uses a **warm** tint from the theme. The colors come from the theme's `tints.warm` definition.
{% /hint %}<section data-rune="hint" data-rune-fields="{"hintType":"note"}">
<div data-name="body">
<p>
This hint uses a
<strong marker="**">warm</strong>
tint from the theme. The colors come from the theme's
<code>tints.warm</code>
definition.
</p>
</div>
<meta data-field="tint" content="warm">
</section>This hint uses a warm tint from the theme. The colors come from the theme's tints.warm definition.
<section class="rf-hint rf-hint--note rf-hint--tinted" data-hint-type="note" data-elevation="sunken" data-tint="warm" data-tint-dark="" data-rune="hint" data-density="compact" style="--tint-bg: var(--rf-color-surface-active); --tint-text: var(--rf-color-text); --tint-primary: var(--rf-color-warning); --tint-border: var(--rf-color-border); --tint-dark-bg: #2a2018; --tint-dark-text: var(--rf-color-text); --tint-dark-primary: var(--rf-color-warning); --tint-dark-border: #4a3f33">
<div data-name="header" data-zone="header" data-zone-layout="bar" class="rf-hint__header" data-section="header">
<span data-field="hintType">
<span data-icon-group="hint" data-icon="note"></span>
<span data-meta-value="">note</span>
</span>
</div>
<div data-name="body" class="rf-hint__body">
<p>
This hint uses a
<strong marker="**">warm</strong>
tint from the theme. The colors come from the theme's
<code>tints.warm</code>
definition.
</p>
</div>
</section>Tints nest: a tinted rune inside another tinted rune takes its own colors.
How Markdown is read
| You write | It becomes |
|---|---|
A list item name: value, such as - primary: #059669 | That color token, set to the value |
A Dark heading | The list items after it are the dark-scheme values |
A Light heading, or no heading | The list items are the light-scheme values |
| A list item whose name is not a tint token, or any other content | Ignored |
Set colors inline
For a one-off color, put {% tint %} first inside the rune and list the colors to change. Colors you don't list keep the page's values.
{% hint type="check" %}
{% tint %}
- bg: #ecfdf5
- primary: #059669
- border: #a7f3d0
{% /tint %}
This hint has custom colors defined inline. Only the listed tokens are overridden — unlisted ones fall through to the page defaults.
{% /hint %}<section data-rune="hint" data-rune-fields="{"hintType":"check"}">
<div data-name="body">
<p>This hint has custom colors defined inline. Only the listed tokens are overridden — unlisted ones fall through to the page defaults.</p>
</div>
<meta data-field="tint" content="custom">
<meta data-field="tint-bg" content="#ecfdf5">
<meta data-field="tint-primary" content="#059669">
<meta data-field="tint-border" content="#a7f3d0">
</section>This hint has custom colors defined inline. Only the listed tokens are overridden — unlisted ones fall through to the page defaults.
<section class="rf-hint rf-hint--check rf-hint--tinted" data-hint-type="check" data-elevation="sunken" data-tint="custom" data-rune="hint" data-density="compact" style="--tint-bg: #ecfdf5; --tint-primary: #059669; --tint-border: #a7f3d0">
<div data-name="header" data-zone="header" data-zone-layout="bar" class="rf-hint__header" data-section="header">
<span data-field="hintType">
<span data-icon-group="hint" data-icon="check"></span>
<span data-meta-value="">check</span>
</span>
</div>
<div data-name="body" class="rf-hint__body">
<p>This hint has custom colors defined inline. Only the listed tokens are overridden — unlisted ones fall through to the page defaults.</p>
</div>
</section>A tint sets up to six colors, each replacing the theme's color of the same role:
| Token | Purpose |
|---|---|
bg | Background |
surface | Raised surfaces, such as cards and panels |
text | Body text |
muted | Secondary text |
primary | Links and accents |
border | Borders and dividers |
Give dark and light values
Under a ## Light and a ## Dark heading, list the colors for each color scheme. Without headings, every value is a light value.
{% hint type="note" %}
{% tint %}
## Light
- bg: #fdf6e3
- text: #5c4a32
- primary: #c47d3b
- border: #e0d5c0
## Dark
- bg: #2a2118
- text: #e8d5b7
- primary: #e0a86e
- border: #4a3f33
{% /tint %}
This section adapts its warm tint to both color schemes.
{% /hint %}<section data-rune="hint" data-rune-fields="{"hintType":"note"}">
<div data-name="body">
<p>This section adapts its warm tint to both color schemes.</p>
</div>
<meta data-field="tint" content="custom">
<meta data-field="tint-bg" content="#fdf6e3">
<meta data-field="tint-text" content="#5c4a32">
<meta data-field="tint-primary" content="#c47d3b">
<meta data-field="tint-border" content="#e0d5c0">
<meta data-field="tint-dark-bg" content="#2a2118">
<meta data-field="tint-dark-text" content="#e8d5b7">
<meta data-field="tint-dark-primary" content="#e0a86e">
<meta data-field="tint-dark-border" content="#4a3f33">
</section>This section adapts its warm tint to both color schemes.
<section class="rf-hint rf-hint--note rf-hint--tinted" data-hint-type="note" data-elevation="sunken" data-tint="custom" data-tint-dark="" data-rune="hint" data-density="compact" style="--tint-bg: #fdf6e3; --tint-text: #5c4a32; --tint-primary: #c47d3b; --tint-border: #e0d5c0; --tint-dark-bg: #2a2118; --tint-dark-text: #e8d5b7; --tint-dark-primary: #e0a86e; --tint-dark-border: #4a3f33">
<div data-name="header" data-zone="header" data-zone-layout="bar" class="rf-hint__header" data-section="header">
<span data-field="hintType">
<span data-icon-group="hint" data-icon="note"></span>
<span data-meta-value="">note</span>
</span>
</div>
<div data-name="body" class="rf-hint__body">
<p>This section adapts its warm tint to both color schemes.</p>
</div>
</section>Adjust a named tint
preset starts from a named tint; the colors you list replace its own.
{% hint type="note" %}
{% tint preset="warm" %}
- primary: #e94560
{% /tint %}
Inherits all tokens from the "warm" preset, with a custom primary color.
{% /hint %}<section data-rune="hint" data-rune-fields="{"hintType":"note"}">
<div data-name="body">
<p>Inherits all tokens from the "warm" preset, with a custom primary color.</p>
</div>
<meta data-field="tint" content="warm">
<meta data-field="tint-primary" content="#e94560">
</section>Inherits all tokens from the "warm" preset, with a custom primary color.
<section class="rf-hint rf-hint--note rf-hint--tinted" data-hint-type="note" data-elevation="sunken" data-tint="warm" data-tint-dark="" data-rune="hint" data-density="compact" style="--tint-bg: var(--rf-color-surface-active); --tint-text: var(--rf-color-text); --tint-primary: #e94560; --tint-border: var(--rf-color-border); --tint-dark-bg: #2a2018; --tint-dark-text: var(--rf-color-text); --tint-dark-primary: var(--rf-color-warning); --tint-dark-border: #4a3f33">
<div data-name="header" data-zone="header" data-zone-layout="bar" class="rf-hint__header" data-section="header">
<span data-field="hintType">
<span data-icon-group="hint" data-icon="note"></span>
<span data-meta-value="">note</span>
</span>
</div>
<div data-name="body" class="rf-hint__body">
<p>Inherits all tokens from the "warm" preset, with a custom primary color.</p>
</div>
</section>Force dark or light
mode keeps the rune in dark or light whatever the reader's setting:
{% hint type="note" %}
{% tint mode="dark" %}
- bg: #1e293b
- text: #e2e8f0
- primary: #38bdf8
- border: #334155
{% /tint %}
This section is forced into **dark mode** with custom token values.
{% /hint %}<section data-rune="hint" data-rune-fields="{"hintType":"note"}">
<div data-name="body">
<p>
This section is forced into
<strong marker="**">dark mode</strong>
with custom token values.
</p>
</div>
<meta data-field="tint" content="custom">
<meta data-field="tint-mode" content="dark">
<meta data-field="tint-bg" content="#1e293b">
<meta data-field="tint-text" content="#e2e8f0">
<meta data-field="tint-primary" content="#38bdf8">
<meta data-field="tint-border" content="#334155">
</section>This section is forced into dark mode with custom token values.
<section class="rf-hint rf-hint--note rf-hint--tinted" data-hint-type="note" data-elevation="sunken" data-tint="custom" data-color-scheme="dark" data-rune="hint" data-density="compact" style="--tint-bg: #1e293b; --tint-text: #e2e8f0; --tint-primary: #38bdf8; --tint-border: #334155">
<div data-name="header" data-zone="header" data-zone-layout="bar" class="rf-hint__header" data-section="header">
<span data-field="hintType">
<span data-icon-group="hint" data-icon="note"></span>
<span data-meta-value="">note</span>
</span>
</div>
<div data-name="body" class="rf-hint__body">
<p>
This section is forced into
<strong marker="**">dark mode</strong>
with custom token values.
</p>
</div>
</section>To switch the scheme without changing any colors, set tint-mode on the rune instead: {% hero tint-mode="dark" %}.
Where named tints come from
A named tint (tint="warm", preset="warm") is defined by the theme, or by the site's tints map in refrakt.config.json — see Sites. A theme that defines no tints ignores tint colors, and the rune keeps the page's colors. How a theme defines tints is covered in theme authoring → tint cascade.
Attributes
| Attribute | Type | Required | Description |
|---|---|---|---|
preset | string | — | Named tint preset from the theme |
mode | "auto" | "dark" | "light" | — | Whether the tint adapts to auto, dark, or light mode |
| Not available | Why |
|---|---|
| bg, dropcap, elevation, frame, inset, motion (reveal, stagger), prominence, reading, spacing, substrate, tint, width | this rune supplies axis values to its parent rather than carrying its own |