Skip to content

std/theme ​

From the spec

This page is spec/std/theme.md, the specification the compiler and the backends are written from. It is rebuilt from the spec with every deploy (how).

A project's theme is Weft: theme.weft at its root exports theme, a Theme from std/theme, and the build evaluates it into the style model's theme tokens (styles.md, Theme): the colours of each scheme, and the fonts, radii and shadows the class tokens read. The module's signatures are core/crates/weft-check/src/std/theme.weft; the evaluation is weft-check's theme.rs.

weft
// theme.weft
import { Theme, oklch, rgba, rem } from "std/theme"

let radius = rem(0.625)

export let theme: Theme = {
  light: { background: oklch(1, 0, 0), primary: oklch(0.205, 0, 0), black: "#000" },
  dark: { background: oklch(0.145, 0, 0), border: oklch(1, 0, 0, 0.1) },
  fontSans: "'Geist Variable', Geist, ui-sans-serif, system-ui, sans-serif",
  radius,
  radiusSm: radius * 0.6,
  shadowXs: [{ y: 1, blur: 2, color: rgba(0, 0, 0, 0.05) }],
}

Tokens ​

  • Every field is a token, and classes name it in kebab case: cardForeground is card-foreground (bg-card-foreground), chart1 chart-1, radius2xl radius-2xl (rounded-2xl), fontSans the class font-sans, shadow2xs the class shadow-2xs. A digit after a letter starts a word, as a capital does.
  • light and dark are the colour schemes, each a Colors record (shadcn/ui's tokens: background, foreground, card, …, sidebarRing, and the code editor's syntaxKeyword, …, syntaxInvalid, codeSelection, codeMatch); a scheme's colour is oklch(l, c, h, alpha?) (oklch(1 0 0 / 10%) for an alpha of 0.1) or #hex text ("#000"), which every renderer reads. rgba(r, g, b, alpha?) is for shadows' layers: the desktop can't read it, or any other colour text, in a scheme. The colour tokens are those the schemes name.
  • font… fields are font stacks (text), radius… fields lengths, shadow… fields shadows: lists of layers { x?, y?, blur?, spread?, color }, in pixels, the colour an rgba(…).
  • A token the theme leaves out keeps the standard theme's value (the schema's: shadcn/ui's neutral theme, registry/theme.weft written out).

Lengths and derived tokens ​

Length is a number of pixels: rem(n) is n * 16 and px(n) is n when the module runs as code, so the theme is ordinary Weft. The build keeps how a length was written, as a Length of the style model (styles.md, Values): rem(0.625) is { rem: 0.625 }, and a length computed from another token stays computed from it. A top-level let the theme sets as a token (radius, or radius: radius) stands for that token wherever else the theme uses it: radiusSm: radius * 0.6 is { mul: [{ token: "radius" }, 0.6] }, so it is recomputed when radius changes, on every renderer. A length times or divided by a number and two lengths added or subtracted are length expressions; a let the theme doesn't set as a token is written out where it is used.

Evaluation ​

  • The theme is evaluated from the file's text when the project is checked, built or served, before the rest of the project is checked (which class tokens exist depends on it): literals, records and lists (with spreads: dark: { ...light, background: oklch(0.145, 0, 0) }), std/theme's functions, the file's own top-level lets and arithmetic on lengths. Anything else (another function, a condition, an import of another module) is an error at its place in theme.weft, as is a field that isn't a scheme, a font, a length or a shadow.
  • The checker checks theme.weft as any module: a field Theme doesn't have, or a value of the wrong type, is a type error.
  • What the evaluation gives is the schema overlay renderers and hosts read ({ "style": { "theme": { colors, schemes, fonts, lengths, shadows } } }), merged over the schema: weft check, weft build (which writes it beside the build as theme.json), weft run and weft dev (read when they start), weft lsp, weft mcp.
  • A project holding a theme.json and no theme.weft is an error that says how to move it.

On the web ​

The web renderer emits each token as a CSS variable named for it (styles.md, On the web): cardForeground is --card-foreground, radius2xl --radius-2xl, fontSans --font-sans, shadow2xs --shadow-2xs. A length expression is a calc(): radiusSm: radius * 0.6 is --radius-sm: calc(var(--radius) * 0.6), so a page that changes --radius changes the scale with it.

Editing it ​

weft component writes the registry's theme.weft into a project that has none, and later adds the tokens a component needs that the project's theme lacks, with the registry's expressions, through the edit API's set_field and add_import (edit.md): the project's values, order and comments stay. The editor's theme panel edits the same file the same way.

Decided here ​

  1. The theme is one typed record whose field names are the tokens in camel case, not maps of names: the checker and the editor know every token.
  2. Derived lengths are written as arithmetic on a let the theme sets as a token, and stay derived in the style model.
  3. Evaluated from the text, not run: the schema is needed before the project is checked.

Weft is in development. The reference is the spec as it stands today.