One base theme, refracted into every brand — and you see what changes before you ship.

Installation

refract is a small family of packages — a core compiler plus one package per output format. Install the core and just the adapter(s) you need; nothing you don't use lands in your dependency tree (the styled-components peer, for one, only ships with that adapter). The @theme-registry namespace is an intentional home for a family of theming packages — refract is its first member, standalone by design: it depends on none of the others and works entirely on its own.

npm install @theme-registry/refract @theme-registry/refract-css

import { createTheme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";

const theme = createTheme(raw, { adapter: createCssAdapter() });

// theme.css · theme.tokens · theme.classes · theme.resolveToken()
document.head.append(
  Object.assign(document.createElement("style"), { textContent: theme.css })
);

Start from a colour, not a blank file

Answer a few questions and get a complete RawTheme — palettes with tonal ladders, semantic colours, a type scale with derived leading, a spacing ramp. Every colour is checked against WCAG contrast before the file is written. The generator runs once; what it produces is an ordinary theme file you own and edit.

1 · Two ways in

The first two run the same interview and the same generator — the difference is only whether a project is created around the result.

2 · The interview

Ten prompts, most of them Enter-through. Every one has a flag, and with no TTY each takes its default instead of blocking — so this is safe in a script or in CI.

npx refract create

  ? Primary colour › #4c6ef5
      parsed · lightness 59% — lands at ≈400 on the ladder
  ? How many brand colours? › 2   → complement #9a7800
  ? Also add › semantic colours · neutral ramp · shadow tints
  ? Contrast target › WCAG AA
  ? Base font size › 16      ? Type scale › major-third
  ? Overall feel › Neutral   ? CSS reset › preflight
  ? Format › theme.raw.ts

  Contrast · 7 pairings checked
    primary     4.32  −1  4.51 AA
    secondary   4.15  −2  4.54 AA
    success     3.45  −7  4.54 AA
    warning     6.04      unchanged

  theme.raw.ts   7 subsystems · 151 tokens · 0 recipes

Or skip the questions entirely:

npx refract create --yes                              # every default
npx refract create --seed "#e64980" --colors 3 \
                    --scheme triadic --feel editorial   # fully scripted

3 · What it writes

One file. Literal where a value came from the generator's judgement, declarative where the engine already synthesizes — so retuning a scale stays a one-word edit instead of a regenerated table:

const ladder = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];

export const raw = {
  colors: {
    // each brand colour is its own palette, with its own ladder
    primary:   { base: "#496bf1", text: "#ffffff", steps: ladder },
    secondary: { base: "#937200", text: "#ffffff", steps: ladder },
    success:   { base: "#09882e", text: "#ffffff", steps: ladder },
    /* … info · warning · danger · neutral · shadow … */
  },
  typography: {
    // a declaration — the engine synthesizes xs…4xl from these two
    fontSize: { base: 16, ratio: "major-third" },
    // derived per step, and named after the step they were tuned for
    lineHeight: { base: 1.5, variants: { "4xl": 1.17, "3xl": 1.23, xs: 1.65 } },
  },
  // linear curve — every stop lands on the 4px grid
  layout: { spacing: { base: 4, step: 4, steps: { xs: 1, sm: 2, md: 4, lg: 6, xl: 8 } } },
} satisfies RawTheme;

The derived leading and tracking are named after the size step, so the pairing documents itself with no recipe holding it together:

.hero h1 {
  font-size:      var(--dt-typography-fontsize-4xl);
  line-height:    var(--dt-typography-lineheight-4xl);
  letter-spacing: var(--dt-typography-letterspacing-4xl);
}

4 · What it doesn't write

Also absent by design: no @keyframes (nothing would reference one without a recipe), and no component definitions.

5 · Decisions baked in

Worth knowing before you edit, so you don't undo something deliberate:

6 · Retuning it

Don't replace fontSize: { base, ratio } with a hand-listed ladder, or the spacing curve with literal pixels — that discards the intent the engine synthesizes from.

7 · Wiring the build

refract init looks for a theme.raw.* and writes a config that imports it, rather than carrying a starter palette of its own. Run create first, then:

npx refract init     # found theme.raw.ts — wired it up
npx refract build    # → dist/theme/theme.css
npx refract audit    # 7/7 pass, 0 fail

From here, Quickstart walks the same ground by hand if you'd rather understand the grammar before generating it, and Recipes is where these tokens become classes.

Your first theme

Author a small RawTheme, compile it, and render a themed button — end to end in five steps. Every snippet below is real; the output is exactly what the library emits.

1 · Author a RawTheme

A plain object, one key per subsystem. Here: a brand colour (its tonal steps are synthesized for you) with a solid recipe, and one components recipe that references it.

const raw = {
  colors: {
    brand: { base: "#4c6ef5", text: "#ffffff" },
    recipes: {
      solid: { brand: { background: "brand", color: "brand.text",
        states: [{ state: "hover", background: "brand.dark" }] } } },
    },
  },
  components: {
    recipes: {
      buttons: {
        // compose: reference the colours recipe, add an own style delta
        // css is literal-first: bare strings are raw CSS; ref() marks a token
        primary: { colors: "solid.brand",
          css: { color: ref("colors.brand.text"), cursor: "pointer", border: "none", borderRadius: "8px",
                 padding: "10px 16px", fontWeight: "600" } },
      },
    },
  },
};

2 · Compile it with createTheme

Pass an adapter — the output format. The CSS adapter is the common choice; core ships no default, which is what keeps the Model format-neutral.

import { createTheme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";

const theme = createTheme(raw, { adapter: createCssAdapter() });

3 · Inject the stylesheet

theme.css is the full stylesheet — :root custom properties plus recipe classes. Add it to the document once.

document.head.append(
  Object.assign(document.createElement("style"), { textContent: theme.css }),
);

That theme.css contains — brand steps synthesized, the recipe lowered to a class:

:root {
  --dt-colors-brand: rgb(76, 110, 245);
  --dt-colors-brand-text: rgb(255, 255, 255);
  --dt-colors-brand-light: rgb(114, 148, 255);   /* synthesized (OKLCH) */
  --dt-colors-brand-dark: rgb(51, 77, 210);      /* synthesized (OKLCH) */
}
.dt-components-buttons-primary {
  color: var(--dt-colors-brand-text);   /* the "colors.brand.text" ref */
  cursor: pointer; border: none; border-radius: 8px;
  padding: 10px 16px; font-weight: 600;
}

4 · Use the class

theme.classes mirrors your recipes — subsystem → group → variant. Composition is a class list (the referenced recipe + the component's own delta), exposed as a ready-to-use className.

theme.classes.components.buttons.primary.className;
// → "dt-colors-solid-brand dt-components-buttons-primary"

<button className={theme.classes.components.buttons.primary.className}>Save</button>

5 · Re-theme live with override()

Derive a child theme by passing only what changes. Untouched branches keep their reference; the parent is left byte-identical — so override() is a real child theme, not a re-run. Swap dark.css in to re-theme.

const dark = theme.override({ colors: { brand: { base: "#93a4ff", text: "#0b1020" } } });
dark.css;   // full stylesheet for the child — brand steps re-derived
theme.css;  // unchanged

Decision cheatsheet

Reach for the right tool at a glance:

Playground

Edit a RawTheme on the left; it compiles in your browser as you type, and the preview and emitted CSS update live. This is the real library — the same createTheme that drives every panel on this site.

Agent-native

refract is built to be the design system an AI agent can't drift from. An agent doesn't guess your tokens or invent class names — it binds to a fixed, named vocabulary and a machine-readable contract it can read, query, and validate against. The headline is consistency: the same theme, named the same way, every time. (Fewer tokens is a real but secondary bonus — an agent emits a short path like colors.brand.dark, not a hex pasted everywhere.)

A live query surface

Beyond the static contract, a Model Context Protocol server turns the theme into live tools an agent calls directly — resolveToken, getClass, listRecipes, validateTheme — so it queries and validates against the real compiled theme instead of guessing. It's the one capability a plain token file can't offer. The MCP server, with examples ▸

AI skills

The agent-native surface in practice: refract ships a catalog of AI skills — short, procedural guides that teach a coding agent how to work with the package across the whole workflow: authoring, the token subsystems, adapters, the build, consuming the output, and migration. Install them into your agent with one command, version-locked to the refract you have.

Install

refract skills install writes the skills into your agent's own config. Run it once per project (or --global for your whole machine); re-run update after upgrading refract so the guidance never drifts from your version.

refract skills list                          # show the catalog
refract skills install --agent claude          # install for one agent (interactive if --agent omitted)
refract skills install --agent all --optional  # every agent + the opt-in skills
refract skills update                        # re-sync after upgrading refract

Each agent loads skills differently, so the installer adapts the output per target. Claude gets native per-skill files it loads automatically; every other agent gets a small router in its own instructions file that points at on-demand bodies under .refract/skills/ — so a non-Claude agent doesn't load all fifteen every turn. A .refract/skills.lock manifest records what's installed for a clean update.

Flags mirror the interactive prompts: --agent <a,b|all>, --global / --local (default local, to the project), --only <names> for a subset, and --optional to include the opt-in tier.

The catalog

Fifteen skills, hub-and-spoke: theme-authoring is the hub that orients and routes; the rest are focused spokes that own their vocab once so they never drift. Thirteen are core (installed by default); two are opt-in. Wording is agent-neutral, so they read as plain reference files too.

MCP server

A Model Context Protocol server that exposes your project's theme as live tools an agent calls directly — so it answers "what class do I use here?" against the real compiled theme, and validates its own work as it goes. It's the one capability a plain token file can't offer.

The tools

Eleven read/validate tools over the loaded theme:

Connect

Register the server with your agent — any MCP client works the same way over stdio. Once published:

claude mcp add refract -- npx -y @theme-registry/refract-mcp

…or from a local build (it auto-discovers theme.config.* in the cwd; pass --config to point elsewhere):

pnpm --filter @theme-registry/refract-mcp build          # → dist/server.js
claude mcp add refract -- node ./packages/refract-mcp/dist/server.js

For project scope, commit a .mcp.json — anyone who opens the repo gets an agent wired to that theme:

{ "mcpServers": { "refract": {
    "command": "npx",
    "args": ["-y", "@theme-registry/refract-mcp", "--config", "theme.config.ts"] } } }

Examples

Ask for a class. The agent calls getClass — no theme in the call, it's the loaded one — and gets the exact class-list to put on an element:

// → request
{ "method": "tools/call", "params": { "name": "getClass",
    "arguments": { "subsystem": "components", "group": "buttons", "variant": "primary" } } }

// ← result (inside the MCP content block)
{ "className": "dt-components-buttons-primary",
  "classList": ["dt-colors-solid-brand", "dt-components-buttons-primary"] }

Validate before writing. validateTheme returns every problem in one pass with a stable code — the agent fixes them all, then proceeds:

// → validate a theme with a bad colour
{ "name": "validateTheme",
  "arguments": { "theme": { "colors": { "x": { "base": "nope" } } } } }

// ← result
{ "ok": false, "code": "REFRACT_E_COLOR_INPUT",
  "errors": ["Invalid colour \"nope\". Author a colour as a hex string (\"#4dabf7\"), …"] }

Resolve a value. When an agent needs a literal (a chart colour, an inline style), resolveToken hands back exactly what the CSS variable holds:

// → { path: "colors.brand.dark" }
// ← result
{ "path": "colors.brand.dark", "value": "rgb(51, 77, 210)" }

Blast radius — refract diff

Every value in a refract theme is a { ref, fn, arg } graph, not a frozen literal — so refract can answer a question a plain token file can't: what will this change break, before I ship it? refract diff <candidate> builds a candidate theme against your config's targets and prints exactly what moves — tokens re-valued, recipe classes changed, and any contrast pairing that crossed a threshold. It's the most defensible thing refract does: nothing else in the category stores the reference graph, so nothing else can tell you the blast radius up front.

On the command line

Point it at a candidate theme — a theme.config.* or a DTCG document. With no thresholds it just reports the diff; add thresholds and any breach exits nonzero, turning it into a PR gate.

refract diff candidate.ts                                    # print the blast radius (report only)
refract diff candidate.ts \
  --max-token-changes 20 --max-class-changes 5 --fail-below AA     # gate: fail the run on a breach

The gate flags: --max-token-changes <n> and --max-class-changes <n> fail when more than n tokens or recipe classes move; --fail-below <AAA|AA|AA-large> fails when any pairing drops below that WCAG-2 level. Point at a non-default config with --config <path>.

As a CI gate — GitHub Actions

Drop this in .github/workflows/theme-diff.yml. On every pull request it diffs the candidate theme against your committed config and fails the check if a change moves more than the thresholds allow or drops a colour pairing below AA — so a token tweak can't silently re-skin the app or break contrast.

name: theme-diff
on: pull_request
jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - name: Theme blast-radius gate
        run: >
          npx -y @theme-registry/refract diff candidate.ts
          --max-token-changes 20 --max-class-changes 5 --fail-below AA

Programmatic

The same diff is a plain export for custom tooling or a dashboard: diffThemes(base, candidate) from @theme-registry/refract/build returns the { tokens, classes, contrast, summary } structure the CLI and the MCP diffTheme tool both render.

import { diffThemes } from "@theme-registry/refract/build";

const { tokens, classes, contrast, summary } = diffThemes(base, candidate);
// summary → { tokenChanges, classChanges, worstPairing } for your own gate

createTheme & the Theme

createTheme(raw, options) is the one entry point. It normalizes your RawTheme into the format-neutral Model, binds the adapter, and returns a Theme — the object you read output and tokens from.

createTheme(raw: RawTheme, options: { adapter: ThemeAdapter; media?: MediaConfig; units?: UnitsConfig; baseFontSize?: number }): Theme

Options

The Theme surface

The base surface is format-neutral; the adapter adds its own output getters via extend (the CSS adapter adds css / variablesCss / recipesCss / nodes / classes).

theme.override() — child themes

A delta merge, not a re-run. Only the partial's changed subsystem slices are re-normalized and immutably merged into the current Model at property / rule-set-variant granularity; untouched branches keep their reference. The parent Model (and its bound output) is left byte-identical — so it's a real child theme. Overriding a colour base re-derives its synthesized steps for free.

const theme = createTheme(raw, { adapter: createCssAdapter() });

// a dark child — only the touched slices re-normalize; parent untouched
const dark = theme.override({ colors: { brand: { base: "#8aa2ff", text: "#0b1020" } } });
dark.css;   // a full stylesheet for the child
theme.css;  // unchanged

RawTheme anatomy

The RawTheme is a plain object — one top-level key per subsystem, nothing else. Every key is optional: emit only the subsystems you author. There is no adapter-specific syntax anywhere in it — the same object drives every adapter.

const raw: RawTheme = {
  colors:     { /* palettes → synthesized tonal steps */ },
  typography: { /* type scale, families, weights, headings */ },
  effects:    { /* shadow, transitions, opacity, blur, z-index */ },
  borders:    { /* width, style, radius, offset + edge recipes */ },
  animation:  { /* durations, easings, keyframes, motion recipes */ },
  layout:     { /* spacing, sizes, columns, grids, stacks, containers */ },
  components: { /* recipes only — compose the subsystems above */ },
  globals:    { preset: "preflight" /* + themed element rules */ },
};

Every subsystem slice shares one shape

Learn the pattern once and it holds across all of them. A slice is an open map of properties, plus a reserved recipes block. A property is either a bare value or an extended property:

Properties vs. recipes

Two things every subsystem emits, and the split is the whole mental model:

components is the special case: it declares recipes only — its whole job is to compose properties and recipes from the other subsystems into one class. See Components.

Build-time

Compile once in your build or CI and ship static files — plain CSS, tokens, SCSS. Zero runtime: the browser just loads the stylesheet, and refract never reaches the client bundle.

The CLI reads a theme.config.ts, runs each target's adapter, and writes the emitted files to disk. This layer uses Node (fs, TypeScript) — it runs at build, not in the browser.

import { defineConfig } from "@theme-registry/refract/build";
import { createCssAdapter } from "@theme-registry/refract-css";
import { createScssAdapter } from "@theme-registry/refract-scss";
import { raw } from "./theme.raw";

export default defineConfig({
  raw,
  targets: [
    { name: "css",  adapter: createCssAdapter(),  outDir: "dist/theme" },
    { name: "scss", adapter: createScssAdapter(), outDir: "dist/scss" },
  ],
});

defineConfig(config) — config reference

EmitTarget — target reference

refract create              # design a theme.raw.(ts|js|json) from one seed colour
refract init                # scaffold theme.config.ts (imports theme.raw.* if present)
refract import tokens.json   # seed theme.raw.ts (+ config) from a DTCG tokens.json
refract build               # compile every target → write files
refract tokens --out tokens.json   # DTCG export (adapter-free)
refract audit --strict      # score colour contrast (WCAG + APCA); fail on a miss
refract skills install      # install the AI skills into your agent (claude/codex/…)

:root {
  --dt-colors-brand: #4c6ef5;
  --dt-colors-brand-dark: #334dd2;
}
.dt-colors-solid-brand {
  background: var(--dt-colors-brand);
  color: var(--dt-colors-brand-text);
}

The emit API — output modes

Set emit on any target. Four modes; every field is optional and defaults are filled by the build layer. The CSS adapter is the reference realization — other adapters honor a subset and throw a clear error on a mode they don't map.

Options per mode

Self-documenting output — guide

Set guide: true on any target and refract writes two extra files into that target's outDir: an llms.txt narrative and a manifest.json index. They name the theme's real identities — the emitted class names / export ids / dotted token paths — so a developer (or their coding agent) can consume the theme from the folder alone, with no refract, no skills, and no guessing at names. The files travel inside outDir, so they accompany the theme however it ships: an npm package, a CI zip, or a vendored folder.

export default defineConfig({
  raw,
  targets: [
    {
      name: "css",
      adapter: createCssAdapter(),
      outDir: "dist/theme",
      guide: { packageName: "@acme/theme" },  // or just `guide: true`
    },
  ],
});

# Theme consumption guide (css)

This folder is a self-contained theme built with refract. You do NOT need refract to use it …

## How to use
Import the stylesheet once, then apply the recipe class names below to your elements.
Example: `import "./theme.css";` then `<button class="<class>">`.

If this theme is installed as the `@acme/theme` package, you may import the same
files by specifier (e.g. `@acme/theme/theme.css`) instead of by relative path.

## Recipes — real names
| Recipe                      | Identity                                          |
| --------------------------- | ------------------------------------------------- |
| `colors.solid.brand`        | `dt-colors-solid-brand`                           |
| `components.buttons.primary`| `dt-colors-solid-brand dt-components-buttons-primary` |

Human-facing preview — preview

guide writes for an agent; preview writes for a person. Set preview: true on any target and refract writes a preview.html into that target's outDir — a rendered specimen of the theme you double-click, forward, or hand a designer. By default it inlines its stylesheets, so the page is a single self-contained file that keeps working after it's moved out of outDir.

export default defineConfig({
  raw,
  targets: [
    {
      name: "css",
      adapter: createCssAdapter(),
      outDir: "dist/theme",
      preview: true,  // or { file, title, inline: false }
    },
  ],
});

It reads as a proper style guide rather than a token dump. The page is a light paper and each plate a card: a masthead in your theme's own first palette with headline counts (including a WCAG pass ratio across declared pairings), an index whose entries are the shape of the theme, one card per colour family with a large base swatch and its lightness ladder, the type ramp set in its own sizes, spacing shown as a measure and as an applied inset (there is no separate padding token — spacing is the padding scale), a state matrix per recipe, and a copy-on-click identifier beside every specimen. Sections appear only when the theme has tokens of that kind.

Two things follow from what refract knows. Each value is tagged src or gen — whether you authored it or refract synthesised it — read from the model, since the token export resolves both to plain literals. And the sheet is deliberately light-only: colour can't be judged against a moving backdrop, and a flipping page would make it impossible to tell whether a swatch changed because the theme's mode changed or because the page did. The appearance control moves the specimen, not the sheet.

The page has two halves, and they degrade independently:

For a target whose output isn't browser-loadable, the page still renders every token and still lists every recipe by its real identity — it just says, in that adapter's own words, why it can't render them live. SCSS needs compiling first; styled-components emits JS modules that need React; JSON is data with no rendered form. For a live design-review page from a styled-components or SCSS theme, add a CSS target to the same config — it compiles the same recipes through the same core, so it's a faithful specimen.

Run-time

Compile in memory in the app or browser and use the output live — inject theme.css, apply theme.classes, read theme.resolveToken(), and derive child themes with theme.override().

The runtime graph is browser-safe (no Node deps), so createTheme runs client-side. That unlocks live theming, user-editable themes, and per-request themes on the server.

import { createTheme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";

const theme = createTheme(raw, { adapter: createCssAdapter() });

// inject once, then use the emitted classes
document.head.append(Object.assign(document.createElement("style"), { textContent: theme.css }));
button.className = theme.classes.components.buttons.primary.className;

// derive a CHILD theme — only the delta is re-normalized, parent untouched
const dark = theme.override({
  colors: { brand: { base: "#8aa2ff", text: "#0b1020" } },
});
document.head.append(Object.assign(document.createElement("style"), { textContent: dark.css }));

DTCG interop

DTCG — the Design Tokens Community Group format — is the standard interchange for design tokens; Figma, Style Dictionary and the wider token ecosystem speak it. refract speaks it both ways. It is not an adapter: it's a small, format-neutral interop boundary at the @theme-registry/refract/dtcg subpath, so a Node / build script can use it without pulling the runtime graph.

Import — DTCG → RawTheme

fromDTCG returns a plain RawTheme input you pass to createTheme — and can edit first. Import is a build-time transform, not a runtime step: DTCG groups are mapped to subsystems (auto-detected from $type and group name by default).

import { fromDTCG } from "@theme-registry/refract/dtcg";
import { createTheme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";

const raw = fromDTCG(dtcgDoc);   // a RawTheme input — edit it freely
const theme = createTheme(raw, { adapter: createCssAdapter() });

Export — Theme → DTCG

toDTCG walks the flat theme.tokens map, resolves each path to a concrete literal (following aliases and running lighten/darken), and re-groups into DTCG. Property tokens only — recipes and composition are out of standard scope; colours emit as hex (the DTCG convention); synthesized tonal steps are included.

Recipe round-trip (opt-in). toDTCG(theme, { includeRecipes: true }) additionally stashes the built rule-set IR under a reverse-DNS $extensions key — com.theme-registry.refract (with a version) — so a document can round-trip refract → DTCG → refract without losing recipes. Restore it with fromDTCGTheme(doc, { adapter }) (property tokens and recipes in one call), or read the raw payload with readRefractExtension(doc). This is refract-specific and not portable: other DTCG tools ignore the extension and see property tokens only, and standard output is byte-identical when the flag is off.

import { toDTCG } from "@theme-registry/refract/dtcg";

const doc = toDTCG(theme, { name: "acme" });   // a DTCG document

// …or at build time, the CLI sugar over the same call:
// $ refract tokens --out tokens.json

{
  "$name": "acme",
  "color": {
    "$type": "color",
    "brand": {
      "base":  { "$value": "#4c6ef5" },
      "light": { "$value": "#708bf7" },   // synthesized, resolved to hex
      "dark":  { "$value": "#3d58c4" },
      "text":  { "$value": "#ffffff" }
    }
  },
  "breakpoint": { "$type": "dimension", "md": { "$value": "768px" } /* … */ }
}

Supported token types

Import and export cover the DTCG $types that map onto refract's subsystems:

color · dimension · fontFamily · fontWeight · duration · cubicBezier · number · typography · shadow · border · transition · strokeStyle · gradient

Dark mode

Dark mode is a property mode, not a second theme. Author a dark value on the properties that change; the CSS adapter emits both an OS-preference @media block and a manual [data-theme] toggle from the same variable names — so it follows the system with zero JavaScript, and a one-line attribute forces it.

1 · Author the mode

Put modes: [{ mode: "dark", … }] on the properties that differ — usually a handful of surface / ink / border colours. Everything that references those tokens flips for free; you don't mode every property.

const raw = {
  colors: {
    surface: { base: "#ffffff", modes: [{ mode: "dark", base: "#0b0d12" }] },
    ink:     { base: "#0e1117", modes: [{ mode: "dark", base: "#e9ecf3" }] },
    recipes: { solid: { panel: { background: "surface", color: "ink" } } },
  },
};

2 · What the CSS adapter emits

Each moded property is redeclared under two selectors — the same --dt-… names, so one redefinition flips every downstream var(--…) through the cascade:

:root {
  --dt-colors-surface: rgb(255, 255, 255);
  --dt-colors-ink: rgb(14, 17, 23);
}
@media (prefers-color-scheme: dark) {   /* follows the OS — no JS */
  :root {
    --dt-colors-surface: rgb(11, 13, 18);
    --dt-colors-ink: rgb(233, 236, 243);
  }
}
:root[data-theme="dark"] {              /* manual toggle — wins over the OS block */
  --dt-colors-surface: rgb(11, 13, 18);
  --dt-colors-ink: rgb(233, 236, 243);
}
.dt-colors-solid-panel { background: var(--dt-colors-surface); color: var(--dt-colors-ink); }

3 · Toggle at run-time

Do nothing and it follows the OS. To let the user override, set data-theme on the root element — its higher specificity wins over the media block. Remove it to fall back to the OS.

const root = document.documentElement;

root.setAttribute("data-theme", "dark");   // force dark
root.setAttribute("data-theme", "light");  // force light
root.removeAttribute("data-theme");         // back to the OS preference

modes vs override()

Both give you a dark UI; they solve different problems.

They compose: an override() child still emits its own modes blocks. Reach for modes first for dark mode; reach for override() when you need a distinct theme object.

White-labeling

One product, N brands. Author one base theme, then derive each brand as an override() child. Every brand shares the base's recipe structure, so the emitted class names are identical — only the variable values differ. Switching brands is a stylesheet swap; your markup never changes.

1 · One base, many brands

Author the shared structure once. Each brand overrides only what differs — usually a brand colour or two; the tonal steps re-synthesize from the new base for free.

const base = createTheme(raw, { adapter: createCssAdapter() });

const acme   = base.override({ colors: { brand: { base: "#e8590c", text: "#ffffff" } } });
const globex = base.override({ colors: { brand: { base: "#2f9e44", text: "#ffffff" } } });

2 · Same classes, different values

The composition is structural, so every brand resolves to the same class list. Only each brand's stylesheet redefines the variables — which means your components are brand-agnostic:

acme.getClass("components","buttons","primary") === base.getClass(...);  // → true
// every brand: "dt-colors-solid-brand dt-components-buttons-primary"

// only the emitted variable differs per brand:
//   base.css   → --dt-colors-brand: rgb(76, 110, 245);
//   acme.css   → --dt-colors-brand: rgb(232, 89, 12);
//   globex.css → --dt-colors-brand: rgb(47, 158, 68);

3 · Serve the right brand

Because markup is identical, delivering a brand is just choosing its stylesheet:

Why override(), not N full themes

override() is a delta merge, not a re-run: only the changed subsystem slices re-normalize, everything untouched keeps its reference (structural sharing), and the base is left byte-identical. So spinning up dozens of brands off one base is cheap — each is a thin delta, not a full theme rebuild.

Migrating CSS variables

Already have a hand-written :root of custom properties and a few utility classes? Moving to a RawTheme is mostly re-homing: variables become properties (grouped by subsystem), and your styled classes become recipes. In return you get tonal synthesis, composition, override(), and multi-format emit.

Before — hand-written CSS

:root {
  --color-brand: #4c6ef5;
  --color-ink: #0e1117;
  --radius: 8px;
}
.btn {
  background: var(--color-brand); color: #fff;
  padding: 8px 14px; border: none; border-radius: var(--radius); cursor: pointer;
}

After — a RawTheme

Map each variable to a property under its subsystem; turn .btn into a colours recipe plus a component recipe that composes it. Raw values move into the css delta as bare literals; token references there use ref("…").

const raw = {
  colors: {
    brand: { base: "#4c6ef5", text: "#ffffff" },   // text = the on-colour
    ink:   { base: "#0e1117" },
    recipes: { solid: { brand: { background: "brand", color: "brand.text" } } },
  },
  borders: { radius: { base: 8 }, recipes: { edge: { button: { radius: "base" } } } },
  components: { recipes: { buttons: { primary: {
    colors: "solid.brand", borders: "edge.button",
    css: { padding: "8px 14px", border: "none", cursor: "pointer" },
  } } } },
};
// theme.getClass("components","buttons","primary")
// → "dt-colors-solid-brand dt-borders-edge-button dt-components-buttons-primary"

Theming a component library

refract contributes two things — CSS variables (tokens) and classes (recipes). How you theme a third-party library depends on which one it consumes.

Libraries driven by CSS variables

Most modern libraries expose their design tokens as CSS custom properties (--lib-primary, …). Point them at refract's tokens with a thin bridge — refract owns the values, the library keeps its API:

/* map the library's variable names → refract's tokens */
:root {
  --lib-primary: var(--dt-colors-brand);
  --lib-on-primary: var(--dt-colors-brand-text);
  --lib-radius: var(--dt-borders-radius-base);
}

Because these are var() references, the library re-themes automatically when refract's tokens change — including dark mode and override(). If the library lets you set its variable prefix, you can even set refract's adapter prefix to match and skip the bridge.

Libraries driven by their own classes

If a component ships fixed styles under its own classes, refract's classes can't restyle it from outside (its own CSS wins). Two options: feed the library's theme API with resolved values via theme.resolveToken("colors.brand"), or wrap the component and apply a refract class to your element around it.

DTCG round-trip

Design tools and token pipelines speak DTCG. The full loop: bring tokens in from Figma / Style Dictionary, compile a theme, and (optionally) send tokens back out — all through the ./dtcg interop boundary.

import { fromDTCG, toDTCG } from "@theme-registry/refract/dtcg";
import { createTheme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";

// 1 · IN — a DTCG export (Figma / Style Dictionary) → a RawTheme input
const raw = fromDTCG(dtcgFromDesign);

// 2 · enrich — add what DTCG can't carry: recipes, states, composition
raw.colors.recipes = { solid: { brand: { background: "brand", color: "brand.text" } } };

// 3 · compile — a real theme, any adapter
const theme = createTheme(raw, { adapter: createCssAdapter() });

// 4 · OUT — property tokens back to DTCG for the design tool (or `refract tokens`)
const doc = toDTCG(theme, { name: "acme" });

React

refract is framework-agnostic — there's no React binding to install. With the CSS adapter you inject theme.css once and apply theme.classes.*.className. Here's the idiomatic wiring: a provider, class usage, and switching override() children in state.

1 · Load the stylesheet & provide the theme

theme.css is the entire stylesheet as a string — the :root custom properties plus every recipe class. Load it the way you'd load any CSS: inject a <style> tag at run-time (below), or emit it to a .css file at build time and <link> it (then you can drop refract from the client bundle). The provider does the run-time injection once and exposes the theme via context so components can read their classes.

import { createContext, useContext } from "react";
import type { Theme } from "@theme-registry/refract";

const ThemeContext = createContext<Theme | null>(null);
export const useTheme = () => useContext(ThemeContext)!;

export function ThemeProvider({ theme, children }) {
  return (
    <ThemeContext.Provider value={theme}>
      {/* inject the stylesheet once, at the root */}
      <style dangerouslySetInnerHTML={{ __html: theme.css }} />
      {children}
    </ThemeContext.Provider>
  );
}

2 · Use a class

The quickest way to a class is theme.getClass(subsystem, group, variant) — it returns the ready-to-apply string (the fully composed list for a components variant), or undefined for an unknown address. refract has already built the composition; you're just reading it.

function SaveButton() {
  const theme = useTheme();
  return <button className={theme.getClass("components", "buttons", "primary")}>Save</button>;
}
// → <button class="dt-colors-solid-brand … dt-components-buttons-primary">

Prefer the data form? theme.classes.components.buttons.primary is a { className, classList } pair — classList (the array) pairs well with a clsx-style helper for conditional classes. Recipes from the other subsystems are a plain class-name string.

3 · Switch themes at run-time

Keep the active theme in state and swap between the base and an override() child. Because the provider injects theme.css, changing the state value re-themes the whole tree — the child is a real, parent-untouched theme.

import { useState } from "react";
import { createTheme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";

const base = createTheme(raw, { adapter: createCssAdapter() });
const warm = base.override({ colors: { brand: { base: "#e8590c", text: "#ffffff" } } });

export function App() {
  const [theme, setTheme] = useState(base);
  return (
    <ThemeProvider theme={theme}>
      <button onClick={() => setTheme(theme === base ? warm : base)}>Swap brand</button>
      <SaveButton />
    </ThemeProvider>
  );
}

Inline styles?

Prefer classes. Inline style={{…}} can't express :hover/:disabled states, @media responsive, container queries, or @keyframes — which is most of what a recipe emits — so a class carries far more than an inline value can. The one fair use is a one-off dynamic value; even then:

// ✅ a var() reference still flips with the theme / dark-mode cascade
<div style={{ color: "var(--dt-colors-brand)" }} />

// ⚠️ a resolved literal is frozen — it will NOT re-theme
<div style={{ color: theme.resolveToken("colors.brand") }} />

Use resolveToken for logic (canvas, measurement, a computed value) — not for styling that should stay themable. The var(--…) name follows the naming grammar.

Using styled-components instead

If your app is on styled-components, use the styled-components adapter — it emits a literal theme object and tree-shakeable css recipes instead of a stylesheet. Wrap the app in one <ThemeProvider theme={theme}> and drop recipes into styled blocks (styled.button`${componentsButtonsPrimary}`); dark mode is an @media block inside each recipe, no provider swap.

Next.js / SSR

Because theme.css is just a string, server-rendering is straightforward: pick the theme per request, render its <style> into the initial HTML, and the page arrives already themed — no flash. This uses the App Router; nothing here is refract-specific beyond theme.css.

1 · Compile once, pick per request

Compile at module scope so themes are built once per server process, not per request — then select by tenant. override() children are cheap, so a brand map costs almost nothing.

import { createTheme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";

const base = createTheme(raw, { adapter: createCssAdapter() });

const brands = {
  acme:   base.override({ colors: { brand: { base: "#e8590c", text: "#ffffff" } } }),
  globex: base.override({ colors: { brand: { base: "#2f9e44", text: "#ffffff" } } }),
};

export const getTheme = (brand?: string) => brands[brand] ?? base;

2 · Inject in the root layout (no FOUC)

The root layout is a Server Component — derive the tenant from the request, render the theme's <style> in <head>. It's server-rendered into the first byte, so there's no unthemed flash.

import { headers, cookies } from "next/headers";
import { getTheme } from "@/lib/theme";

export default async function RootLayout({ children }) {
  const host = (await headers()).get("host") ?? "";
  const theme = getTheme(host.split(".")[0]);        // tenant from subdomain
  const mode = (await cookies()).get("theme")?.value;   // "dark" | "light" | undefined

  return (
    <html lang="en" data-theme={mode}>
      <head>
        <style dangerouslySetInnerHTML={{ __html: theme.css }} />
      </head>
      <body>{children}</body>
    </html>
  );
}

3 · Dark mode without a flash

Author modes and the OS preference is handled automatically by the emitted @media block. For a manual choice, set data-theme on <html> server-side from a cookie (as above) — the attribute is in the first byte, so the manual theme applies before paint, with no client flip flash.

Using the classes

In any component — server or client — read classes exactly as in the React guide: import the theme and call theme.getClass("components", "buttons", "primary"). Server Components can import the theme module directly.

Angular

Same story as everywhere: a small injectable service holds the theme, keeps theme.css injected, and exposes getClass; templates bind [class]. Shown with standalone components and signals.

1 · A theme service

A root service owns the theme as a signal and mirrors theme.css into a <style> element via an effect — so setting a new theme re-themes the app.

import { Injectable, signal, effect, inject } from "@angular/core";
import { DOCUMENT } from "@angular/common";
import { createTheme, type Theme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";
import { raw } from "./theme.config";

@Injectable({ providedIn: "root" })
export class ThemeService {
  private doc = inject(DOCUMENT);
  private styleEl = this.doc.createElement("style");
  readonly theme = signal<Theme>(createTheme(raw, { adapter: createCssAdapter() }));

  constructor() {
    this.doc.head.appendChild(this.styleEl);
    effect(() => (this.styleEl.textContent = this.theme().css));   // keep <style> in sync
  }

  setTheme(theme: Theme) { this.theme.set(theme); }
  getClass(sub: string, group: string, variant: string) {
    return this.theme().getClass(sub, group, variant);
  }
}

2 · Use a class

Inject the service and bind [class] to getClass. The class list is composed by refract; the template just applies it.

import { Component, inject } from "@angular/core";
import { ThemeService } from "./theme.service";

@Component({
  selector: "app-save-button",
  standalone: true,
  template: `<button [class]="theme.getClass('components', 'buttons', 'primary')">Save</button>`,
})
export class SaveButtonComponent {
  protected theme = inject(ThemeService);
}

3 · Switch themes

Swap in an override() child; the service's effect re-injects its CSS and every bound [class] updates.

const warm = base.override({ colors: { brand: { base: "#e8590c", text: "#ffffff" } } });
themeService.setTheme(warm);   // re-injects theme.css via the effect

Vue

Same shape as everywhere: a shared theme ref, a watcher that keeps theme.css injected, and getClass in templates. Shown with the Composition API and <script setup>.

1 · A theme ref + provide it

Hold the theme in a ref, provide it to the tree, and mirror theme.css into a <style> with watchEffect — so replacing the ref re-themes the app.

import { ref, type Ref, type InjectionKey } from "vue";
import { createTheme, type Theme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";
import { raw } from "./theme.config";

export const ThemeKey: InjectionKey<Ref<Theme>> = Symbol("theme");
export const createThemeRef = () => ref<Theme>(createTheme(raw, { adapter: createCssAdapter() }));

<script setup lang="ts">
import { provide, watchEffect } from "vue";
import { ThemeKey, createThemeRef } from "./theme";

const theme = createThemeRef();
provide(ThemeKey, theme);

watchEffect(() => {                              // keep <style> in sync
  let el = document.getElementById("refract");
  if (!el) { el = document.createElement("style"); el.id = "refract"; document.head.appendChild(el); }
  el.textContent = theme.value.css;
});
</script>

<template><SaveButton /></template>

2 · Use a class

<script setup lang="ts">
import { inject } from "vue";
import { ThemeKey } from "./theme";
const theme = inject(ThemeKey)!;
</script>

<template>
  <button :class="theme.getClass('components', 'buttons', 'primary')">Save</button>
</template>

3 · Switch themes

theme.value = base.override({ colors: { brand: { base: "#e8590c", text: "#ffffff" } } });
// watchEffect re-injects the new theme.css; every :class updates

Token paths & naming

Everything in a theme has one format-neutral identity — its token path. The path is what theme.tokens keys, what resolveToken takes, and what every ref points at. Adapters then render that path into their own names — the CSS adapter into a --dt-… variable, the JSON adapter into a key, and so on. The path is the constant; the prefix is per-adapter.

The token path

A path mirrors what you authored, dot-separated. Two shapes cover everything:

Synthesized things get paths too — a tonal step you didn't author, like colors.brand.dark, is addressable the moment it's derived. And refs are just paths: a colour variant's ref, a ref("…") in a component's css delta, a globals element's ref("…") — each names a path. That's the whole reference system.

theme.tokens            // a flat  path → Ref  map, keyed by these paths
theme.resolveToken("colors.brand.dark")   // → "rgb(59, 91, 219)"

// a recipe references a path — no CSS anywhere in the Model:
components: { recipes: { buttons: { primary: { css: { color: ref("colors.brand.text") } } } } }

How each adapter renders a path

An adapter turns a path into whatever its format needs. Same path, different names — this is what keeps the Model format-neutral:

The text adapters (CSS · SCSS · styled-components) flatten the path — dots to dashes — and add a prefix. The JSON adapter keeps the path verbatim as the key. A custom adapter names however its target needs. So a --dt-… name is one adapter's rendering, not the identity.

The text-adapter prefix

Only the text adapters carry a prefix. The default is dt (think design token); two options control it — nothing else about the naming changes:

const theme = createTheme(raw, { adapter: createCssAdapter({ prefix: "acme" }) });
// same paths → --acme-colors-brand-dark … .acme-components-buttons-primary

Segments are sanitized into identifiers — lowercased, non-identifier characters collapsed to a dash (a palette named "Brand Accent" → brand-accent) — but the path itself stays the canonical key. Container-context classes follow the same rule: .<classPrefix>-cq-<name>.

Naming overrides — full control of names

When a prefix isn't enough — a host framework expects a specific class stem, or you need to match an existing variable convention — the two text adapters (createCssAdapter and createStyledComponentsAdapter) take an optional naming option: two formatters that each receive the structured address plus the computed default, and return a name to decorate or replace. Return defaults.name for the cases you don't want to touch — omit naming entirely and output is byte-identical.

const theme = createTheme(raw, { adapter: createCssAdapter({
  naming: {
    // stem component classes as app-<group>-<variant>; leave the rest default
    className: (a, d) => a.subsystem === "components" ? `app-${a.group}-${a.variant}` : d.name,
    // rename colour variables --brand-…; other subsystems keep --dt-…
    variableName: (a, d) => a.segments[0] === "colors" ? `--brand-${a.segments.slice(1).join("-")}` : d.name,
  },
}) });

--brand-primary: rgb(77, 171, 247);        /* :root definition */
.app-button-primary { background: var(--brand-primary); }   /* usage + own class */
// theme.getClass("components","button","primary") → "dt-colors-solid-primary app-button-primary"
//   (the referenced colours class stays default; only the own delta class is remapped)

Each result is held to a three-part contract: deterministic (a pure function of the address — definitions and usages call it repeatedly), collision-free (two distinct addresses producing one name throw), and a valid identifier (run through the segment sanitizer; variableName is normalized to -- + a sanitized body). One remap is applied at both pure choke points, so a variable's definition and every reference, and a recipe's class rule, its resolved classList / component-reference lookup, theme.classes and getClass, all stay in lock-step. CSS and styled-components share this one path; the JSON adapter keys its data its own way and stays out.

Precedence & cascade layers

refract emits low, even specificity — recipe rules are single classes and globals are zero-specificity :where() — and relies on source order at equal specificity (the later rule wins). That keeps its output easy to override with your own CSS, but source order depends on where the stylesheet loads.

Responsive

Any property or recipe can carry a responsive list. refract lowers each entry to an @media override — on the :root variable for token properties, or on the class for recipes.

Breakpoints are named (xs … xl); each entry picks one with a min or max query. The emitted media unit (px / em / rem) is a build-time config, so authoring stays unit-agnostic.

// declare the named scale once, on the theme
breakpoints: {
  xs: 0, sm: 576, md: 768, lg: 1024, xl: 1440,
}

Then any property or recipe references those names in a responsive entry:

spacing: {
  base: 8, variants: { xl: 28 },
  responsive: [
    { breakpoint: "sm", query: "min", target: "xl", base: 40 },
  ],
}

// lowers to →  @media (min-width: 576px) { :root { --…-spacing-xl: 40px } }

Worked example

A recipe that changes its background above a breakpoint — authored, then exactly what the CSS adapter emits:

solid.brand: {
  background: "brand", color: "brand.text",
  responsive: [{ breakpoint: "md", query: "min", background: "accent" }],
}

.dt-colors-solid-brand { background: var(--dt-colors-brand); color: var(--dt-colors-brand-text); }
@media (min-width: 768px) {
  .dt-colors-solid-brand { background: var(--dt-colors-accent); }
}

Rules & edge cases

• Property vs recipe. A property's responsive lowers to a :root variable override (@media { :root { --… } }); a recipe's lowers to a class override, as above. Same authoring, two lowerings.
• Query kind. Each entry is min, max, or exact — commit to mobile-first (min) or desktop-first (max) deliberately.
• Source order is cascade order. Entries emit after the base in author order; at equal specificity the later rule wins, so order breakpoints so the intended one lands last.
• Composes with the other axes. A responsive entry may also carry a state (→ @media { .cls:hover { … } }); container queries are a separate axis.
• Unknown breakpoint is a build error — declare it in breakpoints first.

Live

Container queries

A top-level containers config declares named query containers. A recipe override keyed by { container, size } lowers to an @container rule — styling by the container's width, not the viewport's.

The emitted .dt-cq-card utility establishes the context (container-type: inline-size); any descendant recipe responds. It's a distinct condition axis that composes with viewport @media.

containers: { card: { sizes: { sm: 280, md: 440 } } },

// a recipe override, keyed by container + size
solid.accent: {
  background: "accent",
  responsive: [
    { container: "card", size: "md", background: "brand" },
  ],
}

Worked example

containers: { card: { type: "inline-size", sizes: { sm: 280, md: 440 } } },
solid.brand: {
  background: "brand",
  responsive: [{ container: "card", size: "md", background: "brand.dark" }],
}

/* the context class establishes the container */
.dt-cq-card { container-type: inline-size; container-name: card; }
/* the recipe override responds to the CONTAINER's width, not the viewport's */
@container card (min-width: 440px) {
  .dt-colors-solid-brand { background: var(--dt-colors-brand-dark); }
}

Rules & edge cases

• You must place the context class. A descendant only responds if an ancestor carries .dt-cq-<name> — that's what establishes container-type: inline-size.
• Inline size only. Container queries respond to the container's width; orientation / height / aspect-ratio are rejected as a build error (that's what viewport @media is for).
• min is the default query for container entries.
• A separate axis from @media. Container and viewport queries compose — a rule can be inside both.
• Unknown container or size is a build error — declare them under containers.

Live — resize the container

States

A recipe's states map compiles to selector rules — :hover, [disabled], focus, and so on. The adapter owns the set of known states; core validates every state: ref against it (so a typo is a build error, not silent CSS).

solid.brand: {
  background: "brand", color: "brand.text",
  states: [
    { state: "hover",    background: "brand.dark" },
    { state: "disabled", background: "brand.lighter", color: "brand.dark" },
  ],
}

Worked example

.dt-colors-solid-brand { background: var(--dt-colors-brand); color: var(--dt-colors-brand-text); }
.dt-colors-solid-brand:hover { background: var(--dt-colors-brand-dark); }
.dt-colors-solid-brand[disabled] { background: var(--dt-colors-brand-lighter); color: var(--dt-colors-brand-dark); }

Each state key maps to a selector — hover → :hover, disabled → [disabled] — on the recipe's own class.

Rules & edge cases

• The adapter owns the known states. The CSS adapter knows hover, disabled, focus, … ; an inline or JSON adapter may know none. A state the target adapter doesn't declare is a build error — not silent CSS.
• States ride on the shared class. A component that references a recipe inherits that recipe's :hover etc. for free — see Components.
• Own delta wins. A component's own state delta and a referenced recipe's state both apply; the delta wins at equal specificity by later source order.
• Composes with responsive. A responsive entry may carry a state → @media { .cls:hover { … } }.

Live — hover & disabled

Variants & targets

A property's variants become suffixed tokens (--…-dark, spacing-xl). In a responsive entry, variant: swaps a recipe to a sibling's base, and target: scopes the override to one specific step.

outline.brand: {
  color: "brand", borderColor: "brand",
  responsive: [
    { breakpoint: "lg", variant: "subtle" }, // adopt sibling ≥lg
  ],
}
// target: scope an override to ONE step
spacing.responsive: [{ breakpoint: "sm", target: "xl", base: 40 }]

variant — swap to a sibling

In a recipe responsive entry, variant makes the recipe adopt a sibling variant's declarations above the breakpoint.

solid: {
  brand: { background: "brand", color: "brand.text",
    responsive: [{ breakpoint: "lg", query: "min", variant: "muted" }] },
  muted: { background: "brand.light", color: "brand.dark" },
}

/* ≥lg, solid.brand takes on solid.muted's declarations */
@media (min-width: 1024px) {
  .dt-colors-solid-brand { background: var(--dt-colors-brand-light); color: var(--dt-colors-brand-dark); }
}

target — scope to one token

In a property responsive entry, target scopes the override to a single variant token, leaving the base untouched.

surface: {
  base: "#ffffff", variants: { raised: "#f5f5f5" },
  responsive: [{ breakpoint: "sm", query: "min", target: "raised", base: "#e9ecef" }],
}

:root { --dt-colors-surface: rgb(255, 255, 255); --dt-colors-surface-raised: rgb(245, 245, 245); }
@media (min-width: 576px) {
  :root { --dt-colors-surface-raised: #e9ecef; }   /* only the raised token */
}

Rules & edge cases

• Opposite meanings. variant names a source to adopt (a whole sibling recipe); target names a destination to scope to (one token). Setting both on one entry is a build error.
• variant is a recipe thing; target is a property thing. They live in different lowerings — a class swap vs a single-var override.
• Variant tokens are always addressable. A property's variants emit as --…-<variant> alongside the base, whether or not any responsive entry touches them.

Live

Recipe variants

Recipes come in three tiers: a recipe group (solid) is a family; a recipe (brand) is a named bundle of refs + css that resolves to a class; a variant is an optional modifier delta layered on a recipe. A recipe's variants map desugars to flat sibling recipes named <recipe>-<variant> — DRY siblings that share a base. Opt-in and additive on every subsystem's recipes; no variants key ⇒ output is byte-identical.

buttons: {
  primary: {                     // the recipe — its own props ARE the base
    colors: "solid.primary", typography: "button.large", borders: "box.default",
    css: { gap: "8px" },
    variants: {                  // modifiers on THIS recipe
      sm:   { typography: "button.small", css: { gap: "6px" } },
      flat: { borders: null },   // null drops the inherited ref
    },
  },
}

.dt-components-buttons-primary       /* the bare recipe still emits */
.dt-components-buttons-primary-sm    /* base + sm delta */
.dt-components-buttons-primary-flat  /* base, minus the borders ref */

How a variant merges onto the recipe

• A ref / scalar prop replaces — a ref is one atomic pointer; if the variant sets it, it wins, else it inherits.
• css shallow-merges by property — { …base.css, …delta.css }, so sm nudges only gap.
• states merge by state name — union of keys; a shared state's declarations shallow-merge (delta wins).
• responsive[] concatenates — base ++ delta, delta appended (higher source order).

Rules & edge cases

• null removes, "none" keeps. A prop set to null drops an inherited ref (borders: null). Not "none" — that stays a real value (border: none, effects "none", the radius.none variant).
• Flat axis, no nesting — matching token variants. Multi-axis modifiers are out of scope.
• Collisions throw. A desugared <recipe>-<variant> that collides with an existing sibling recipe is a build error — never a silent last-wins.
• Same pattern as properties. A responsive variant: / target: on a recipe references a sibling recipe — and because variants desugar into group members, target: "primary-sm" resolves against the same pool. See Variants & targets.

Length units

A length's unit is a property of the value, not a global switch. You author magnitudes; a single build-time units config resolves each length to a concrete { value, unit } — once, format-neutrally — so every adapter (CSS, SCSS, JSON, DTCG) emits the same unit.

A length can be written three ways. A bare number is deferred — its unit is resolved from units. A <number><unit> string is pinned — trusted verbatim, never converted. Anything else (calc(), clamp(), var(), a keyword) is a raw-string escape and passes through untouched.

createTheme(raw, {
  adapter: createCssAdapter(),
  units: {
    default: "px",        // global fallback
    typography: "rem",     // fontSize → rem
    layout: "rem",        // layout lengths — spacing / gutters / sizes
    borders: "px",         // hairlines stay crisp
  },
  baseFontSize: 16,        // divisor when a deferred length → rem
});
// fontSize 24 → "1.5rem"   ·   borders.width 1 → "1px"   ·   letterSpacing "-0.02em" → verbatim

Keys are token-path prefixes; the most-specific wins, over a built-in seed. So units.typography = "rem" converts fontSize, but the seed keeps lineHeight unit-less and letterSpacing in em unless you override them at the property grain.

The same units and baseFontSize are accepted at run-time on createTheme (above) and at build-time on defineConfig — so refract build resolves lengths identically and emits the chosen unit straight to disk.

Length leaves covered: typography fontSize / letterSpacing / lineHeight, layout spacing / gutters / sizes, borders width / offset / radius, effects blur and shadow geometry. Non-lengths (opacity, z-index, aspect-ratio, transition/animation ms) are never touched.

Top-level registries

A handful of top-level keys are registries — declared once, referenced by name everywhere else (the name is typo-validated, like a scale). Everything else at the top level is a subsystem slice.

{
  breakpoints: { "[breakpoint name]": 0 },                // name → min-width px
  containers:  { "[container name]": { type: "inline-size", sizes: { "[size name]": 0 } } },
  modes:       [ "[mode name]" ],                       // appearance-mode registry (defaults to ["dark","light"])
  extends:     { prefix: "[parent var prefix]" },        // for external tokens (default "dt")

  "[subsystem]": { /* … a subsystem slice … */ },       // colors / typography / layout / …
}

Values — the generic leaf

A value is the atom every field holds. Four leaf forms; each subsystem restricts which it accepts (colours take hex/tuple/CSS-colour, scalars take numbers, …). external is a whole-property passthrough, not a leaf.

"value"                          // string — a literal value / keyword
0                                // number — a unitless literal; the subsystem gives it meaning
[ 0, 0, 0 ]                        // tuple — fixed-length list (today only the [r,g,b] colour tuple)
{ "[leaf field]": "value" }          // object leaf — flat field map (shadow/transition); an array of these = multi-part

{ external: "[token path]" }          // external — a whole-property passthrough (see below)

References

In composition fields (recipe props) a bare string names a token, ref-first. In a css block it is literal-first — a bare string is raw CSS; mark a token with ref("[path]") or { ref: "[path]" }. See Token paths & naming.

External tokens

An external value aliases a variable a parent theme owns — { external: "[token path]" } lowers to var(--[prefix]-[token-path]) (path form, via extends.prefix), or { external: "--[some var]" } for a literal var (leading --). It replaces the whole property, is referenceable everywhere (including recipes), is never defined locally, and survives override(). See White-labeling.

Properties

A property is a uniform map of named fields (each → a CSS variable) plus the three override axes. The reserved field base is the primary value → the unsuffixed --<prop> var; any other name is an extra → --<prop>-<field>.

// (a) bare form — shorthand for { base: value }. Single-primary-field props only.
"[property name]": "value",

// (b) full form — a field map + the override axes.
"[property name]": {
  base: "value",               // the primary field → the unsuffixed var
  "[field name]": "value",       // an extra field → the --…-[field] var

  variants:   { "[variant name]": { /* override set */ } },  // §4 · a NEW named token per variant
  modes:      [ { mode: "[mode name]", /* override set */ } ], // §4 · a conditional re-declaration per mode
  responsive: [ { breakpoint: "[breakpoint name]", /* override set + routing */ } ],
}

• One uniform field map. Every field is the same kind (a name → a var); base is just the reserved primary. Adapters emit one variable per field.
• Object-leaf props omit base. shadow / transitions compose the primary value from flat leaves (Effects), so the bare form isn't available for them.
• The axes carry override sets. variants, modes, and responsive each hold an override set — see Override axes for what each does.

Override sets

The value carried by each entry of variants / modes / responsive is an override set — one of three forms. The two object forms are mutually exclusive: base/fields and ref never coexist.

// (a) bare — just the primary value (variants / modes only)
"value"

// (b) literal object — the same field map as a property; omitted fields INHERIT the property's
{ "[field name]": "value" }

// (c) derivation — read `ref`, then fold the `modifiers` chain over it (mutually exclusive with b)
{ ref: "[source token]", modifiers: [ { "[fn]": "[args]" } ] }

• ref defaults to the own base. Omit it to derive from the property's own primary value; name another variant/step, or a cross-property token path — resolved post-build and re-derived on override().
• modifiers is an ordered chain. Single-key dials applied left-to-right (colours' { darken } / { lighten } / { alpha } / { adjust } — see Colors). No modifiers = a plain ref swap.
• Base is optional and inherits. A literal set may override only an extra field, leaving the primary as-is.

Override axes

variants, modes, and responsive all carry override sets — they differ in what the engine does with them. modes / responsive (and recipe states) are arrays of overrides over one spine: WHEN (mode/state/breakpoint) · WHERE (target) · WHAT (the override set). variants is a map, because the name mints an identity.

variants: {                                       // MAP — each key mints a NEW named token
  "[variant name]": { /* override set */ },
},
modes: [                                          // LIST — a conditional re-declaration per mode
  { mode: "[mode name]", /* override set */ },
  { mode: "[mode name]", target: "[variant name]", /* … */ }, // target → scope into a variant's var
],
responsive: [                                     // LIST — override set + routing
  { breakpoint: "[breakpoint name]", query: "min|max|exact", ref: "[variant name]" },
  { breakpoint: "[breakpoint name]", mode: "[mode name]", /* override set */ },
]

Recipes

A subsystem's recipes block bundles declarations that reference tokens (recipes never define tokens). Two levels: group → item, each item → one class. Its axes mirror a property, one level up.

recipes: {
  "[group name]": {                             // group
    "[item name]": {                            // item → one class
      "[recipe prop]": "[variant name]",          // REF-FIRST props (name a variant)
      states:     [ { state: "[state name]", target: "[recipe variant]", /* prop deltas */ } ],
      responsive: [ { breakpoint: "[breakpoint name]", state: "[state name]", /* prop deltas */ } ],
      variants:   { "[recipe variant]": { /* prop deltas */ } },  // → sibling recipe [item]-[recipe variant]
    },
  },
}

• states / responsive are lists of override entries ({ state, target?, … } / routing) — same spine as property modes. See States.
• variants desugars each modifier into a flat sibling [item]-[variant] (a new class), so a state/responsive target scopes onto it. See Recipe variants.
• components compose. A component item references OTHER subsystems' recipes and adds its own css delta — see Components.

components: { recipes: { "[group name]": {
  "[item name]": {
    "[subsystem]": "[group.item]",             // reference another subsystem's recipe (REF-FIRST)
    css: { "[css prop]": "value", "[css prop]": { ref: "[token path]" } }, // LITERAL-FIRST; ref for tokens
  },
} } }

A full theme

The shapes from every page above, nested into one RawTheme — registries, a property with all three axes, a derivation, an external token, and a recipe. Generic throughout ([bracketed] = author-chosen; "value" = a leaf).

{
  breakpoints: { "[breakpoint name]": 0 },
  modes: [ "[mode name]" ],
  extends: { prefix: "[parent var prefix]" },

  "[subsystem]": {
    "[property name]": {
      base: "value", "[field name]": "value",
      variants: { "[variant name]": { ref: "[source token]", modifiers: [ { "[fn]": "[args]" } ] } },
      modes:    [ { mode: "[mode name]", base: "value" } ],
    },
    "[external property]": { external: "[token path]" },
    recipes: { "[group name]": { "[item name]": {
      "[recipe prop]": "[variant name]",
      states: [ { state: "[state name]", "[recipe prop]": "[variant name]" } ],
    } } },
  },

  components: { recipes: { "[group name]": { "[item name]": {
    "[subsystem]": "[group.item]", css: { "[css prop]": "value" },
  } } } },
}

Adapters — one theme, many formats

You author one RawTheme; it lowers to a format-neutral Model. An adapter refracts that Model into a concrete format. The Model holds no CSS syntax — the adapter owns all naming, units and output — so the same theme can emit CSS, SCSS, JSON tokens, or styled-components, side by side. And the four built-ins aren't a ceiling: an adapter is a standalone package against a stable contract, so you (or the community) can target any format — React Native, Compose, a token pipeline — without touching core.

The adapter is a required argument to createTheme — core ships no default, which is what keeps the Model format-neutral. All four run in the browser and at build time; every preview on this site is compiled live by the CSS adapter.

The same theme, four formats — live

Below is the current preset — the exact RawTheme behind every panel on this site — refracted through each adapter in your browser. One source object; four outputs. Switch the preset in the top bar and all four re-emit.

CSS adapter createCssAdapter

Renders a Theme to a plain-CSS stylesheet — :root custom-property blocks plus the recipe class rules that reference them — and adds a class surface for using them in markup. The full surface it adds to the theme is below.

import { createTheme } from "@theme-registry/refract";
import { createCssAdapter } from "@theme-registry/refract-css";

const theme = createTheme(raw, { adapter: createCssAdapter({ prefix: "acme" }) });
theme.css; // the full stylesheet

Every option is optional. Two prefix knobs — one for variables, one for classes — cover the common case (for full control there's the naming override), plus value/delivery knobs. Subsystems are namespaced by the token path, so by default a variable is --<prefix>-<subsystem>-<group>-<variant> and a recipe class is .<classPrefix>-<subsystem>-<group>-<variant>.

The theme surface

On top of the base theme (model · tokens · resolveToken · override, from core), the CSS adapter adds:

theme.getClass("components", "buttons", "primary");
// → "dt-colors-solid-brand … dt-components-buttons-primary"
theme.getClass("colors", "solid", "brand");   // → "dt-colors-solid-brand"
theme.getClass("colors", "nope", "x");      // → undefined

Helper functions

Beyond the stylesheet, the adapter hands you helpers for the two places you write CSS outside a recipe — at run time, and after a build-time emit.

Run-time — theme.media

A media-query builder over your named breakpoints, so custom CSS (or a styled block) stays in sync with the theme instead of hard-coding pixel widths. It returns the @media string; max / between use the next breakpoint's edge automatically.

theme.media.min("md");            // "@media (min-width: 768px)"
theme.media.max("md");            // "@media (max-width: 1023.98px)"
theme.media.between("sm", "lg");  // "@media (min-width: 576px) and (max-width: 1023.98px)"

// per-breakpoint group — precomputed strings:
theme.media.md.min;             // "@media (min-width: 768px)"

Build-time — vendored color-math

When you emit static CSS and drop refract from the runtime, you sometimes still need to compute a colour live (a user-picked accent, say). Opt a build target into the color-math helper and refract writes a standalone color-math.js next to your CSS — the exact functions it used to synthesize your palette, so a value computed in the browser matches the emitted variables.

{ adapter: createCssAdapter(), outDir: "./theme", helpers: ["color-math"] }

// → ./theme/color-math.js  (no refract dependency)
import { lighten, darken, alpha } from "./theme/color-math.js";
lighten("#4c6ef5", 14);   // same maths as the emitted --dt-colors-…-light

Options

colorFormat — palette colour output

Choose how palette colour values are written into the :root variables — base, text, variants, responsive overrides, and appearance modes. The colour is identical across formats; this is presentation only. The Model always stores the canonical rgb(); hex / oklch re-serialize that same colour at emit time. oklch unlocks the browser's native OKLCH interpolation for anything reading these variables.

createCssAdapter();                         // --dt-colors-primary: rgb(77, 171, 247);
createCssAdapter({ colorFormat: "hex" });   // --dt-colors-primary: #4dabf7;  (#rrggbbaa with alpha)
createCssAdapter({ colorFormat: "oklch" }); // --dt-colors-primary: oklch(71.8% 0.1422 246.06);

prefix — variable names (and the MFE story)

prefix sets the identifier segment on every CSS variable, and is the default for classPrefix, so on its own it rebrands the whole output:

:root { --acme-layout-spacing: 16px; }
.acme-layout-container-full { gap: var(--acme-layout-spacing); }

Micro-frontend isolation. Two independently-built bundles on one page must not share variable names, or their --* custom properties collide. Give each build a distinct prefix:

// App A
createCssAdapter();                       // → --dt-*        / .dt-*
// App B
createCssAdapter({ prefix: "checkout" }); // → --checkout-*  / .checkout-*

Because a variable's first segment is the prefix by construction, choosing the prefix is the whole isolation mechanism — there's no separate “scope” concept.

classPrefix — class names

By default classes inherit prefix. Set classPrefix only when you want the class names to differ from the variable names:

:root { --acme-layout-spacing: 16px; }        /* variables → prefix */
.ui-layout-container-full { gap: var(--acme-layout-spacing); }  /* classes → classPrefix */

This one prefix covers every class the adapter emits, including the container-query context utility classes — there is no per-family override:

.ui-cq-card { container-type: inline-size; container-name: card; }

inline — bake values, drop variables

By default the adapter emits var(--…) references plus the :root blocks that define them. inline: true resolves each reference to its concrete value, bakes it into the declaration, and omits the variable blocks entirely.

/* default */
:root { --dt-colors-primary: #4dabf7; }
.dt-colors-solid-primary { background: var(--dt-colors-primary); }

/* inline: true */
.dt-colors-solid-primary { background: #4dabf7; }

Value units

The length unit for declaration values is not a CSS-adapter option — it's resolved format-neutrally in core from createTheme's units config and baked onto the Model, so every adapter emits the same unit. See Length units.

SCSS adapter createScssAdapter

Emits Sass source — $variables + classes ($<prefix>-…, .<prefix>-…). Surfaces: theme.scss · .classes.

import { createScssAdapter } from "@theme-registry/refract-scss";

const theme = createTheme(raw, { adapter: createScssAdapter({ indent: 2 }) });
theme.scss; // → $dt-colors-brand: …;  .dt-components-buttons-primary { … }

Tokens lower to compile-time $variables (not :root custom properties), and rule-sets nest state / breakpoint overrides idiomatically with & and @media. Synthesized colour steps are baked as concrete values — the same class surface as CSS, from a Sass source:

// tokens → $variables (tonal steps synthesized at build)
$dt-colors-brand: rgb(76, 110, 245);
$dt-colors-brand-light: rgb(145, 167, 255);
$dt-colors-brand-dark: rgb(59, 91, 219);
$dt-colors-brand-text: rgb(255, 255, 255);

// recipes → classes; state overrides nest with &
.dt-components-buttons-primary {
  cursor: pointer;
  border: none;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 8px;
  &:hover { transform: translateY(-1px); }
}

JSON adapter createJsonAdapter

Emits refract's own format-neutral token document — tokens, rule-sets, keyframes and containers as data (recipes and composition survive, which a plain-tokens export can't represent). No CSS. Surface: theme.json. For standardized DTCG interchange instead, see DTCG interop.

import { createJsonAdapter } from "@theme-registry/refract-json";

const theme = createTheme(raw, { adapter: createJsonAdapter({ refs: "both" }) });
JSON.stringify(theme.json);  // { breakpoints, containers, tokens, ruleSets, keyframes }

Every bucket is a flat map keyed by a Model address. A leaf mirrors the Model's Ref: in the default both mode a derived token carries its ref/fn/arg and the resolved value — so palette synthesis, states, responsive overrides and composition-by-reference all survive as data (things a tokens-only DTCG export cannot represent):

{
  "tokens": {
    "colors.brand": { "value": "rgb(76, 110, 245)" },
    // a synthesized step keeps its derivation AND the resolved value
    "colors.brand.lighter": {
      "ref": "colors.brand.light", "fn": "lighten", "arg": 14,
      "value": "rgb(160, 179, 255)"
    }
  },
  "ruleSets": {
    "components.buttons.primary": {
      "kind": "recipe",
      // composition survives as cross-subsystem token-path refs
      "references": [
        "colors:solid.brand", "typography:button.base",
        "layout:padding.button", "effects:surface.focusable", "borders:edge.button"
      ],
      "declarations": { "cursor": { "value": "pointer" } /* … */ },
      "overrides": [ /* per-state / per-breakpoint deltas */ ]
    }
  }
}

styled-components adapter createStyledComponentsAdapter

Emits TypeScript/JavaScript modules, not a stylesheet — a literal theme object and tree-shakeable css recipes whose values read straight from the theme (no var()), a base-layer GlobalStyle (from the globals subsystem), and the types that make props.theme typed. Runtime surfaces: theme.theme · recipes · GlobalStyle · media · scheme.