Types Reference

This page documents the key TypeScript types used across the Dispersa API. Import types from dispersa or the relevant subpath.

Core Types

DispersaOptions

type DispersaOptions = {
  resolver?: string | ResolverDocument
  buildPath?: string
  validation?: ValidationOptions
}

ValidationOptions

type ValidationOptions = {
  mode?: ValidationMode
}

ValidationMode

type ValidationMode = 'error' | 'warn' | 'off'

'error' (default) — throw on validation failures
'warn' — log warnings via console.warn but continue processing
'off' — skip validation entirely

BuildConfig

type BuildConfig = {
  resolver?: string | ResolverDocument
  buildPath?: string
  outputs: OutputConfig[]
  filters?: Filter[]
  transforms?: Transform[]
  preprocessors?: Preprocessor[]
  permutations?: ModifierInputs[]
  hooks?: LifecycleHooks
}

BuildResult

type BuildResult = {
  success: boolean
  outputs: BuildOutput[]
  errors?: BuildError[]
}

BuildOutput

type BuildOutput = {
  name: string
  path?: string
  content: string
}

BuildError

type BuildError = {
  message: string
  code: ErrorCode
  path?: string
  tokenPath?: string
  severity: 'error' | 'warning'
  suggestions?: string[]
}

ErrorCode

type ErrorCode =
  | 'TOKEN_REFERENCE'
  | 'CIRCULAR_REFERENCE'
  | 'VALIDATION'
  | 'COLOR_PARSE'
  | 'DIMENSION_FORMAT'
  | 'FILE_OPERATION'
  | 'CONFIGURATION'
  | 'BASE_PERMUTATION'
  | 'MODIFIER'
  | 'UNKNOWN'

Token Types

ResolvedToken

type ResolvedToken = {
  $type?: TokenType
  $value?: TokenValue | TokenValueReference
  $ref?: string
  $description?: string
  $deprecated?: boolean | string
  $extensions?: Record<string, unknown>
  name: string
  path: string[]
  originalValue: TokenValue
}

TokenValue is string | number | boolean | Record<string, unknown> | unknown[]. TokenValueReference is string | { $ref: string }. In practice, resolved tokens always have $type and $value set after resolution, but the type reflects that they originate from Token where these are optional.

TokenType

Union of all DTCG token types (including color).

type TokenType =
  | 'color'
  | 'dimension'
  | 'fontFamily'
  | 'fontWeight'
  | 'duration'
  | 'cubicBezier'
  | 'number'
  | 'shadow'
  | 'typography'
  | 'border'
  | 'strokeStyle'
  | 'transition'
  | 'gradient'

ModifierInputs

type ModifierInputs = Record<string, string>

Token Value Types

Typed shapes for the $value property of each token type. Useful when building custom transforms or renderers.

type ColorValueObject = {
  colorSpace: ColorSpace
  components: [ColorComponent, ColorComponent, ColorComponent]
  alpha?: number
  hex?: string
}

type DimensionValue = { value: number; unit: 'px' | 'rem' }

type DurationValue = { value: number; unit: 'ms' | 's' }

type ShadowValueObject = {
  color: ColorValue
  offsetX: DimensionValue
  offsetY: DimensionValue
  blur: DimensionValue
  spread: DimensionValue
  inset?: boolean
}

type TypographyValue = {
  fontFamily: FontFamilyValue
  fontSize: DimensionValue
  fontWeight: FontWeightValue
  letterSpacing: DimensionValue
  lineHeight: number
}

type BorderValue = {
  color: ColorValue
  width: DimensionValue
  style: StrokeStyleValue
}

type TransitionValue = {
  duration: DurationValue
  delay: DurationValue
  timingFunction: CubicBezierValue
}

type GradientValue = GradientStop[]
// where GradientStop = { color: ColorValue; position: number }

DesignTokenValue

Union of all known DTCG token value types. Provides narrower typing than TokenValue for consumers who want better autocomplete.

type DesignTokenValue =
  | ColorValueObject
  | DimensionValue
  | DurationValue
  | CubicBezierValue
  | ShadowValueObject
  | ShadowValueObject[]
  | TypographyValue
  | BorderValue
  | StrokeStyleValueObject
  | StrokeStyleValue
  | TransitionValue
  | GradientValue
  | FontFamilyValue
  | FontWeightValue
  | number

Narrowed Token Types

For convenience, Dispersa exports narrowed token types that pair ResolvedToken with a specific $type:

type ColorToken = ResolvedToken & { $type: 'color' }
type DimensionToken = ResolvedToken & { $type: 'dimension' }
type ShadowToken = ResolvedToken & { $type: 'shadow' }
type DurationToken = ResolvedToken & { $type: 'duration' }
type TypographyToken = ResolvedToken & { $type: 'typography' }
type BorderToken = ResolvedToken & { $type: 'border' }
type TransitionToken = ResolvedToken & { $type: 'transition' }
type GradientToken = ResolvedToken & { $type: 'gradient' }

Type Guards

Use type guard functions to narrow a ResolvedToken to a specific token type. All type guards are available from the main dispersa entry point.

import { isColorToken, isDimensionToken } from 'dispersa'

Guard	Narrows to
isColorToken(token)	`ColorToken` (`$type: 'color'`)
isDimensionToken(token)	`DimensionToken` (`$type: 'dimension'`)
isShadowToken(token)	`ShadowToken` (`$type: 'shadow'`)
isTypographyToken(token)	`TypographyToken` (`$type: 'typography'`)
isBorderToken(token)	`BorderToken` (`$type: 'border'`)
isDurationToken(token)	`DurationToken` (`$type: 'duration'`)
isTransitionToken(token)	`TransitionToken` (`$type: 'transition'`)
isGradientToken(token)	`GradientToken` (`$type: 'gradient'`)

import type { ResolvedToken } from 'dispersa'
import { isColorToken, isDimensionToken } from 'dispersa'

function processToken(token: ResolvedToken) {
  if (isColorToken(token)) {
    // token.$value narrowed to color value
    console.log(token.$type) // 'color'
  }
  if (isDimensionToken(token)) {
    // token.$value narrowed to dimension value
    console.log(token.$type) // 'dimension'
  }
}

Config Types

OutputConfig

type OutputConfig<TOptions extends FormatOptions = FormatOptions> = {
  name: string
  renderer: Renderer<TOptions>
  file?: string | FileFunction
  transforms?: Transform[]
  filters?: Filter[]
  options?: TOptions
  hooks?: LifecycleHooks
}

LifecycleHooks

type LifecycleHooks = {
  onBuildStart?: (context: {
    config: BuildConfig
    resolver: string | ResolverDocument
  }) => void | Promise<void>
  onBuildEnd?: (result: BuildResult) => void | Promise<void>
}

FileFunction

type FileFunction = (modifierInputs: ModifierInputs) => string

Renderer Types

Renderer

type Renderer<TOptions extends FormatOptions = FormatOptions> = {
  preset?: string
  format: (
    context: RenderContext<TOptions>,
    options?: TOptions,
  ) => RenderOutput | Promise<RenderOutput>
}

The generic TOptions flows through from defineRenderer<T>(), giving you typed options in both the renderer and its RenderContext.

RenderContext

type RenderContext<TOptions extends FormatOptions = FormatOptions> = {
  permutations: PermutationData[]
  output: OutputConfig<TOptions>
  resolver: ResolverDocument
  meta: RenderMeta
  buildPath?: string
}

RenderMeta

type RenderMeta = {
  dimensions: string[]
  defaults: Record<string, string>
  basePermutation: Record<string, string>
}

dimensions — Modifier dimension keys from the resolver (e.g. ['theme', 'density'])
defaults — Default context value per dimension (e.g. { theme: 'light', density: 'comfortable' })
basePermutation — The modifier inputs that identify the base (unmodified) permutation

SelectorFunction

type SelectorFunction = (
  modifierName: string,
  context: string,
  isBase: boolean,
  allModifierInputs: Record<string, string>,
) => string

MediaQueryFunction

type MediaQueryFunction = (
  modifierName: string,
  context: string,
  isBase: boolean,
  allModifierInputs: Record<string, string>,
) => string

MediaQueryFunction has the same signature as SelectorFunction. Return a media query string (e.g. '(prefers-color-scheme: dark)') or an empty string for no media query.

PermutationData

type PermutationData = {
  tokens: ResolvedTokens
  modifierInputs: ModifierInputs
}

One entry per permutation in RenderContext.permutations.

RenderOutput

type RenderOutput = string | OutputTree

The return type of a renderer’s format function. Return a string for single-file output or an OutputTree (via outputTree()) for multi-file output.

FormatOptions

type FormatOptions = Record<string, unknown>

Base type for renderer-specific options. Each built-in renderer defines a narrower options type (e.g. CssRendererOptions).

Builder Config Types

Builder config types combine the common builder options with renderer-specific options. Use these when typing variables passed to builder functions.

type CssBuilderConfig = BuilderConfigBase & CssRendererOptions
type JsonBuilderConfig = BuilderConfigBase & JsonRendererOptions
type JsBuilderConfig = BuilderConfigBase & JsModuleRendererOptions
type TailwindBuilderConfig = BuilderConfigBase & TailwindRendererOptions
type IosBuilderConfig = BuilderConfigBase & IosRendererOptions
type AndroidBuilderConfig = BuilderConfigBase & AndroidRendererOptions

All builder configs share these base options:

// BuilderConfigBase (shared by all builders)
{
  name: string
  file?: string | FileFunction
  transforms?: Transform[]
  filters?: Filter[]
  hooks?: LifecycleHooks
}

See Builder Functions for the renderer-specific options each builder adds.

Resolver Types

ResolverDocument

The resolver document structure.

type ResolverDocument = {
  $schema?: string
  name?: string
  version: '2025.10'
  description?: string
  sets?: Record<string, Set>
  modifiers?: Record<string, Modifier>
  resolutionOrder: (ReferenceObject | InlineSet | InlineModifier)[]
  $defs?: Record<string, unknown>
}

Transform & Filter Types

Transform

type Transform = {
  matcher?: (token: ResolvedToken) => boolean
  transform: (token: ResolvedToken) => ResolvedToken
}

Filter

type Filter = {
  filter: (token: ResolvedToken) => boolean
}

Preprocessor

type Preprocessor = {
  name: string
  preprocess: (
    rawTokens: InternalTokenDocument,
  ) => InternalTokenDocument | Promise<InternalTokenDocument>
}

InternalTokenDocument is a Record<string, InternalTokenNode> representing the raw DTCG token tree before parsing and resolution.

Output Tree Types

outputTree()

function outputTree(files: Record<string, string>): OutputTree

isOutputTree()

function isOutputTree(value: unknown): value is OutputTree

Subpath Exports Where to import each type from.

Dispersa Class Constructor and build methods.