CSS

Overview

The css() builder renders design tokens as CSS custom properties (variables). You control selectors, media queries, and theming with flexible options.

import { css } from 'dispersa'

Options

Option	Type	Default	Description
name	string	—	Unique output identifier
file	string or function	—	Output path (supports `{context}` interpolation for modifiers)
preset	’bundle’ \| ‘standalone’ \| ‘modifier'	'bundle’	Output preset
selector	string or SelectorFunction	':root'	CSS selector
mediaQuery	string or MediaQueryFunction	—	Media query wrapper
preserveReferences	boolean	false	Emit `var()` for aliases
minify	boolean	false	Minify output
transforms	Transform[]	—	Per-output transforms
filters	Filter[]	—	Per-output filters

Basic Example

import { Dispersa, css } from 'dispersa'
import { nameKebabCase, colorToHex, dimensionToPx } from 'dispersa/transforms'

const dispersa = new Dispersa({
  resolver: './tokens.resolver.json',
  buildPath: './dist',
})

await dispersa.build({
  outputs: [
    css({
      name: 'tokens',
      file: 'tokens.css',
      preset: 'bundle',
      selector: ':root',
      transforms: [nameKebabCase(), colorToHex(), dimensionToPx()],
    }),
  ],
})

Output:

:root {
  --color-brand-primary: #0066cc;
  --spacing-medium: 16px;
}

Theming with Selector Functions

Use a selector function to target [data-theme] or other modifier-based selectors:

css({
  name: 'themed',
  file: 'tokens.css',
  preset: 'bundle',
  selector: (modifierName, context, isBase, allModifierInputs) => {
    if (isBase) return ':root'
    return `[data-${modifierName}="${context}"]`
  },
  transforms: [nameKebabCase(), colorToHex(), dimensionToPx()],
})

Output:

:root {
  --color-brand-primary: #0066cc;
}

[data-theme="dark"] {
  --color-brand-primary: #66aaff;
}

Preserving References

When preserveReferences is true, aliases emit var(--other-token) instead of resolved values:

css({
  name: 'refs',
  file: 'tokens.css',
  preserveReferences: true,
  transforms: [nameKebabCase()],
})

Tokens that reference other tokens will output var(--token-name) rather than inlining the resolved value.

Media Query Wrapper

Wrap output in a media query for responsive or preference-based theming:

css({
  name: 'dark-mode',
  file: 'tokens.css',
  mediaQuery: '(prefers-color-scheme: dark)',
  selector: ':root',
  transforms: [nameKebabCase(), colorToHex()],
})

Standalone Preset with `{theme}` Pattern

Emit one file per modifier:

css({
  name: 'themes',
  file: 'tokens-{theme}.css',
  preset: 'standalone',
  transforms: [nameKebabCase(), colorToHex()],
})

Modifier Preset (Base + Diffs)

The modifier preset emits a base file with all set tokens, plus separate diff files for each modifier context containing only the tokens that change:

css({
  name: 'diffs',
  file: '{theme}/tokens.css',
  preset: 'modifier',
  selector: ':root',
  transforms: [nameKebabCase(), colorToHex()],
})

Produces:

base/tokens.css — all tokens from the resolver’s sets (colors, typography, spacing, etc.)
light/tokens.css — tokens that change in the light theme
dark/tokens.css — tokens that change in the dark theme

The base file groups tokens by set with descriptive comments, matching the structure of the bundle preset’s base output. If there are no set tokens, the base file is not emitted.

JSON Export design tokens as JSON files with flat or nested structure.

CSS