Presets

What Presets Are

Presets control how multiple permutations (e.g. light/dark themes, compact/comfortable density) map to output files. Choose bundle, standalone, or modifier based on how you want to deliver tokens.

Bundle Preset

All permutations in one file.

• CSS — :root { ... } for base, [data-theme="dark"] { ... } for each modifier context
• JSON — Single file with keys per permutation
• JS — Single file with named exports per permutation

Example:

css({
  name: 'tokens',
  file: 'tokens.css',
  preset: 'bundle',
  selector: ':root',
})

Output (conceptual):

:root {
  --color-background: #ffffff;
  --color-text: #111111;
}

[data-theme="dark"] {
  --color-background: #111111;
  --color-text: #eeeeee;
}

Standalone Preset

One file per permutation. Each file is complete and self-contained.

Use modifier key placeholders (e.g. {theme}) in the filename:

css({
  name: 'tokens',
  file: 'tokens-{theme}.css',
  preset: 'standalone',
})

Produces: tokens-light.css, tokens-dark.css, etc.

Modifier Preset

CSS only. Emits a base file with all set tokens, plus separate diff files for each modifier context containing only the tokens that change. The base file groups tokens by set with comments, just like the bundle preset.

css({
  name: 'tokens',
  file: '{theme}/tokens.css',
  preset: 'modifier',
  selector: ':root',
})

Produces: base/tokens.css, light/tokens.css, dark/tokens.css

The {modifier} placeholder is replaced with base for the base file and the context value for each modifier file. If there are no set tokens, the base file is not emitted.

Dynamic selector: selector can be a function:

selector: (modifierName, context, isBase, allModifierInputs) => string

Comparison

Preset	Files	Content	Use case
bundle	1	All permutations	Single-file delivery
standalone	N	One per permutation	Platform-specific builds
modifier	N	Base sets + per-modifier diffs	Overlay/patch files

Dynamic File Patterns

Placeholders like {theme}, {density} are replaced with the modifier context value:

• file: 'tokens-{theme}.css' → tokens-light.css, tokens-dark.css
• file: 'tokens-{theme}-{density}.json' → tokens-light-compact.json, etc.

Dynamic Selectors

For preset: 'bundle' or preset: 'modifier', selector can be a function:

selector: (modifierName, context, isBase, allModifierInputs) => {
  if (isBase) return ':root'
  return `[data-${modifierName}="${context}"]`
}

Error Handling How Dispersa reports errors and the difference between build() and buildOrThrow().