Builder Functions

Overview

Builder functions create OutputConfig objects used in the outputs array of BuildConfig. Each builder returns a configured output ready to pass to dispersa.build().

Import from dispersa or dispersa/builders:

import { css, json, js, tailwind, ios, android } from 'dispersa'

Common Options

All builders accept these options (from OutputConfig):

Option	Type	Description
name	string	Unique output identifier
file	string | FileFunction	Output path; supports modifier key placeholders like {theme}, {density}
transforms	Transform[]	Per-output transforms
filters	Filter[]	Per-output filters
hooks	LifecycleHooks	Per-output lifecycle hooks

---

css(config)

Generates CSS custom properties.

css(config: CssBuilderConfig): OutputConfig

CssBuilderConfig (extends OutputConfig)

Option	Type	Default	Description
preset	'bundle' | 'standalone' | 'modifier'	'bundle'	Output preset
selector	string | SelectorFunction	':root'	CSS selector
mediaQuery	string | MediaQueryFunction	—	Media query wrapper
preserveReferences	boolean	false	Emit var() for alias tokens
minify	boolean	false	Minify output

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

---

json(config)

Generates JSON token files.

json(config: JsonBuilderConfig): OutputConfig

JsonBuilderConfig (extends OutputConfig)

Option	Type	Default	Description
preset	'bundle' | 'standalone'	'standalone'	Output preset
structure	'flat' | 'nested'	'nested'	Token structure
includeMetadata	boolean	false	Include $type, $description, etc.
minify	boolean	false	Minify output

json({
  name: 'tokens',
  file: 'tokens.json',
  structure: 'nested',
  includeMetadata: true,
})

---

js(config)

Generates JavaScript/TypeScript module exporting tokens.

js(config: JsBuilderConfig): OutputConfig

JsBuilderConfig (extends OutputConfig)

Option	Type	Default	Description
preset	'bundle' | 'standalone'	'standalone'	Output preset
structure	'flat' | 'nested'	'nested'	Token structure
moduleName	string	'tokens'	Export name
generateHelper	boolean	false	Generate getTokens(modifiers) helper
minify	boolean	false	Minify output

js({
  name: 'tokens',
  file: 'tokens.js',
  moduleName: 'tokens',
  generateHelper: true,
})

---

tailwind(config)

Generates Tailwind CSS theme configuration.

tailwind(config: TailwindBuilderConfig): OutputConfig

TailwindBuilderConfig (extends OutputConfig)

Option	Type	Default	Description
preset	'bundle' | 'standalone'	'bundle'	Output preset
includeImport	boolean	true	Prepend @import "tailwindcss"
namespace	string	''	Theme namespace for @theme namespace(...)
selector	string | SelectorFunction	—	CSS selector for theme variants
mediaQuery	string | MediaQueryFunction	—	Media query wrapper
minify	boolean	false	Minify output

tailwind({
  name: 'tailwind',
  file: 'theme.css',
  includeImport: true,
  namespace: 'ds',
})

---

ios(config) (Experimental)

Generates Swift code for SwiftUI.

Experimental

The iOS builder is experimental. Options and generated output may change.

ios(config: IosBuilderConfig): OutputConfig

IosBuilderConfig (extends OutputConfig)

Option	Type	Default	Description
preset	'standalone'	'standalone'	Output preset
accessLevel	'public' | 'internal'	'public'	Swift access modifier
structure	'enum' | 'grouped'	'enum'	Code structure
enumName	string	'DesignTokens'	Custom enum name (enum mode)
extensionNamespace	string	'DesignTokens'	Namespace enum name (grouped mode)
colorSpace	'sRGB' | 'displayP3'	'sRGB'	Color space
swiftVersion	'5.9' | '6.0'	'5.9'	Swift language version
frozen	boolean	false	@frozen annotation for ABI stability
indent	number	4	Spaces per indentation level

ios({
  name: 'DesignTokens',
  file: 'DesignTokens.swift',
  accessLevel: 'public',
  structure: 'enum',
})

---

android(config) (Experimental)

Generates Kotlin code for Android.

Experimental

The Android builder is experimental. Options and generated output may change.

android(config: AndroidBuilderConfig): OutputConfig

AndroidBuilderConfig (extends OutputConfig)

Option	Type	Default	Description
preset	'standalone' | 'bundle'	'standalone'	Output preset
packageName	string	—	Kotlin package name (required)
objectName	string	'DesignTokens'	Object/class name
structure	'nested' | 'flat'	'nested'	Token structure in output
colorFormat	'argb_hex' | 'argb_float' | 'argb8' | 'argb_floats'	'argb_hex'	Color format (argb8 and argb_floats are aliases)
colorSpace	'sRGB' | 'displayP3'	'sRGB'	Target color space
visibility	'public' | 'internal'	—	Visibility modifier (omitted by default; Kotlin defaults to public)
indent	number	4	Spaces per indentation level

android({
  name: 'DesignTokens',
  file: 'DesignTokens.kt',
  packageName: 'com.example.tokens',
  objectName: 'DesignTokens',
  structure: 'flat',
  colorFormat: 'argb_hex',
})

Presets

Presets control how permutations map to files. bundle = one file per output; standalone = one file per permutation; modifier (CSS only) = files grouped by modifier.

Dispersa Class Constructor and build methods.

Transforms Reference Transform token values and names.

Filters Reference Filter tokens by type, path, or custom criteria.