API reference

Tokens

The @usemotif/tokens package ships two ready-to-use themes and the sixteen primitive scales they are built from. Reach for it when you want a working design system today; build your own with createTheme when you want full ownership of the values.

Updated todayEdit on GitHubWeb & native

Themes

lightTheme

stable
const lightTheme: Theme

darkTheme

stable
const darkTheme: Theme

Both themes share the same semantic surface (surface.base, surface.muted, text.default, action.primary.bg, …) and the same primitive scales. They differ in which primitive each semantic path resolves to — that is the whole story of light-vs-dark in this token set.

example.tsx
import { ThemeProvider } from 'usemotif';
import { lightTheme, darkTheme } from '@usemotif/tokens';
 
<ThemeProvider themes={[lightTheme, darkTheme]} active="light">
{children}
</ThemeProvider>

Primitive scales

Each scale is exported individually so you can compose a custom theme that reuses the motif defaults selectively.

example.tsx
import {
animations,
borderWidths,
colors,
durations,
easings,
fontFamilies,
fontSizes,
fontWeights,
letterSpacings,
lineHeights,
opacities,
radii,
shadows,
sizes,
space,
zIndices,
} from '@usemotif/tokens';
ScaleShapeNotes
colorsRecord<string, string | Record<string, string>>Hex codes plus the palette ramps (blue.50 … blue.900).
spaceRecord<number | string, number>Numeric scale (0 … 40 in pixels) plus named extras.
sizesRecord<string, number | string>Width / height defaults — xs … 7xl, plus full / screen.
radiiRecord<string, number | string>Border-radius scale: none, sm, md, lg, xl, full.
borderWidthsRecord<string, number>Border-width scale: none, hairline, thin, thick.
fontFamiliesRecord<string, string>Stack strings: sans, serif, mono, display.
fontSizesRecord<string, number>Type scale: xs … 7xl in pixels.
fontWeightsRecord<string, number>100 … 900 plus named aliases (regular, medium, semibold, …).
lineHeightsRecord<string, number | string>Numeric ratios + named (tight, snug, …).
letterSpacingsRecord<string, number>Tracking scale: tighter, tight, normal, wide.
shadowsRecord<string, string>sm … 2xl plus inner / none.
durationsRecord<string | number, string>Millisecond strings used by transition / animation.
easingsRecord<string, string>Named easings: standard, decelerate, accelerate, emphasised.
opacitiesRecord<string, number>0 to 100 in tens, plus semantic (disabled, subtle).
zIndicesRecord<string, number>Named layers: hide, auto, base, docked, dropdown, sticky, banner, overlay, modal, popover, tooltip, toast.
animationsRecord<string, AnimationToken>Reusable keyframe + timing pairs.

Composing your own theme

The presets are the typical case. When the design system demands different values, compose at the scale level rather than reauthoring everything:

example.tsx
import { createTheme } from 'usemotif';
import { space, radii, fontSizes } from '@usemotif/tokens';
 
export const brandTheme = createTheme({
name: 'brand',
tokens: {
  space, radii, fontSizes,
  colors: {
    ink: '#0F172A',
    paper: '#FAFAF9',
    brand: { base: '#7C3AED', accent: '#EC4899' },
    surface: { base: '$colors.paper' },
    text: { default: '$colors.ink' },
    action: { primary: { bg: '$colors.brand.base', fg: '$colors.paper' } },
  },
},
});

createTheme does no transformation — the returned object is the input, narrowed at the type level so $-references autocomplete against this theme's shape.

  • createTheme — build a fresh theme from scratch.
  • Tokens (concept) — the two-layer model these presets are built on.
  • Theming — how a theme becomes active at runtime.