Backgrounds & color›Tint

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');

View packages/runes/src/tags/tint.ts on GitHub

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="{&quot;hintType&quot;:&quot;note&quot;}">
  <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>
note

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 writeIt becomes
A list item name: value, such as - primary: #059669That color token, set to the value
A Dark headingThe list items after it are the dark-scheme values
A Light heading, or no headingThe list items are the light-scheme values
A list item whose name is not a tint token, or any other contentIgnored

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="{&quot;hintType&quot;:&quot;check&quot;}">
  <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>
check

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:

TokenPurpose
bgBackground
surfaceRaised surfaces, such as cards and panels
textBody text
mutedSecondary text
primaryLinks and accents
borderBorders 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="{&quot;hintType&quot;:&quot;note&quot;}">
  <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>
note

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="{&quot;hintType&quot;:&quot;note&quot;}">
  <div data-name="body">
    <p>Inherits all tokens from the &quot;warm&quot; preset, with a custom primary color.</p>
  </div>
  <meta data-field="tint" content="warm">
  <meta data-field="tint-primary" content="#e94560">
</section>
note

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 &quot;warm&quot; 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="{&quot;hintType&quot;:&quot;note&quot;}">
  <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>
note

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

AttributeTypeRequiredDescription
presetstring—Named tint preset from the theme
mode"auto" | "dark" | "light"—Whether the tint adapts to auto, dark, or light mode
Not availableWhy
bg, dropcap, elevation, frame, inset, motion (reveal, stagger), prominence, reading, spacing, substrate, tint, widththis rune supplies axis values to its parent rather than carrying its own