Appearance
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:
cardForegroundiscard-foreground(bg-card-foreground),chart1chart-1,radius2xlradius-2xl(rounded-2xl),fontSansthe classfont-sans,shadow2xsthe classshadow-2xs. A digit after a letter starts a word, as a capital does. lightanddarkare the colour schemes, each aColorsrecord (shadcn/ui's tokens:background,foreground,card, …,sidebarRing, and the code editor'ssyntaxKeyword, …,syntaxInvalid,codeSelection,codeMatch); a scheme's colour isoklch(l, c, h, alpha?)(oklch(1 0 0 / 10%)for an alpha of 0.1) or#hextext ("#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 anrgba(…).- A token the theme leaves out keeps the standard theme's value (the schema's: shadcn/ui's neutral theme,
registry/theme.weftwritten 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-levellets and arithmetic on lengths. Anything else (another function, a condition, an import of another module) is an error at its place intheme.weft, as is a field that isn't a scheme, a font, a length or a shadow. - The checker checks
theme.weftas any module: a fieldThemedoesn'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 astheme.json),weft runandweft dev(read when they start),weft lsp,weft mcp. - A project holding a
theme.jsonand notheme.weftis 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
- 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.
- Derived lengths are written as arithmetic on a
letthe theme sets as a token, and stay derived in the style model. - Evaluated from the text, not run: the schema is needed before the project is checked.