API reference

createTheme

stable
function createTheme<T extends TokenMap>(def: {
readonly name: string;
readonly tokens: T;
readonly fonts?: readonly FontFace[];
readonly root?: ThemeRootStyles;
readonly reducedMotion?: ReducedMotionMode;
}): Theme & { readonly tokens: T }
def.namestringrequired

Theme name. Used as the data-theme attribute value on web. Must be unique among themes registered with a single ThemeProvider.

def.tokensTokenMaprequired

Full token tree (primitives interleaved with semantics). Top-level keys are scale names — colors, space, radii, fontSizes, etc. Leaves are literal values or $-prefixed token references.

def.fontsreadonly FontFace[]

Web-only. @font-face declarations ThemeProvider emits into the document. No effect on native.

def.rootThemeRootStyles

Web-only. Base styles applied to the document root — body resets and the like — emitted by ThemeProvider.

def.reducedMotionReducedMotionMode

Web-only. The prefers-reduced-motion policy for this theme. No effect on native.

Updated 3 days agoEdit on GitHubWeb & native

Description

A thin factory. The returned object is exactly the input — createTheme does no transformation at runtime. The type parameter T extends TokenMap narrows the resulting Theme.tokens so $-references against this theme autocomplete in your editor.

Pass the result to ThemeProvider's themes array. The provider emits the CSS variables and sets data-theme to one of the theme names.

fonts, root, and reducedMotion are optional web-only emission hints — <ThemeProvider> picks them up to emit @font-face rules, document-root styles, and the reduced-motion policy. They have no effect on native, where there is no stylesheet to emit into.

Examples

example.tsx
import { createTheme } from 'usemotif';
 
export const lightTheme = createTheme({
name: 'light',
tokens: {
  colors: {
    ink: '#1C1917',
    paper: '#FBF7F2',
    blue: { 500: '#2563EB', 600: '#1D4ED8' },
    surface: { base: '$colors.paper' },
    text: { default: '$colors.ink' },
    action: { primary: { bg: '$colors.blue.600', fg: '$colors.paper' } },
  },
  space: { 1: 4, 2: 8, 4: 16 },
  radii: { sm: 4, md: 8, lg: 12 },
},
});

Both primitive and semantic tokens live in the same tree. Semantic tokens reference primitives by $colors.<path>; the resolver walks the dotted path until it reaches a literal value.

  • Tokens — the token model, primitive vs semantic layers.
  • Theming — how a theme becomes active at runtime.
  • ThemeProvider — <ThemeProvider> and <Theme> boundary.