The Pipeline

Overview

Dispersa processes design tokens through a pipeline from resolution to rendered output. Tokens flow from a resolver document through shared stages (run once) and per-output stages (run for each output), being resolved, filtered, transformed, and formatted along the way.

Resolve → Preprocess → Parse → Global Filter → Global Transform → Filter → Transform → Render

Click any stage below to see what it does:

1Resolve2Preprocess3Parse4Global Filter5Global Transform

6Filter6Filter6Filter7Transform7Transform7Transform8Render8Render8RenderCSSJSON...

Resolve

Loads the DTCG resolver document, merges sets in order, and applies modifier contexts (themes, platforms, densities) to produce the raw token tree for each permutation.

Input:Resolver document + modifier inputs

Output:Raw token tree per permutation

Stages

Stage	Scope	Description
1. Resolve	Shared	Load the resolver document, merge sets, apply modifier contexts
2. Preprocess	Shared	Run optional preprocessors on the raw token tree
3. Parse	Shared	Resolve references, flatten groups to dot-paths, resolve aliases
4. Global Filter	Shared	Remove tokens globally before per-output processing
5. Global Transform	Shared	Transform all tokens before per-output processing
6. Filter	Per-output	Further narrow tokens for each specific output
7. Transform	Per-output	Convert token values and names for the target platform
8. Render	Per-output	Format tokens into CSS, JSON, JS, Tailwind, Swift, Kotlin, etc.

Global vs. Per-Output

Stages 1-5 run once for the entire build and produce a resolved, flat token set. Stages 6-8 run per output, so each output can have its own filters, transforms, and renderer.

Stages 1-5: Shared (run once)

1. Resolve — Loads and parses the resolver document. Merges sets in order, then applies modifier contexts (themes, platforms, densities) to produce the raw token tree for each permutation.

2. Preprocess — Runs optional preprocessors on the raw token tree. Use this to strip vendor metadata, inject computed tokens, or normalize legacy formats before parsing.

3. Parse — Resolves JSON Pointer $ref references (including external files), flattens nested groups to dot-path keys (e.g. color.brand.primary), inherits group-level $type, and resolves {token.name} alias references with circular dependency detection.

4. Global Filter — Global filters from BuildConfig reduce the token set for all outputs. Tokens excluded here never reach any output.

5. Global Transform — Global transforms from BuildConfig run on all tokens (e.g. nameKebabCase()). These apply before any per-output transforms.

Stages 6-8: Per-output

6. Filter — Per-output filters from each OutputConfig further narrow the globally transformed set for that specific output.

7. Transform — Per-output transforms run after global transforms (e.g. colorToHex() for CSS). They convert token values and names for the target format.

8. Render — The renderer formats the final tokens into the target output: CSS custom properties, JSON, JS/TS modules, Tailwind @theme blocks, Swift/SwiftUI, Kotlin/Compose, or any custom format via defineRenderer.

Processing Order

await dispersa.build({
  // Global: applied to ALL outputs (stages 4-5)
  filters: [byType('color')],
  transforms: [nameKebabCase()],

  outputs: [
    css({
      name: 'css',
      // Per-output: applied AFTER global (stages 6-7)
      transforms: [colorToHex()],
    }),
    json({
      name: 'json',
      // Per-output: different transforms for this output
      transforms: [colorToRgb()],
    }),
  ],
})

Same pipeline everywhere

The pipeline is the same whether you use build(), buildOrThrow(), or the CLI.

Resolution Engine How sets are merged and modifiers create permutations.