Dispersa

A DTCG-native build system for design tokens. Resolve, transform, and render to any platform.

Resolver + Tokens

{
  "version": "2025.10",
  "sets": {
    "core": {
      "sources": [{
        "color": {
          "palette": {
            "$type": "color",
            "blue-500": { "$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8] } }
          },
          "action": {
            "$type": "color",
            "brand": { "$value": "{color.palette.blue-500}" }
          }
        },
        "spacing": {
          "scale": {
            "$type": "dimension",
            "md": { "$value": { "value": 16, "unit": "px" } }
          },
          "gap": {
            "$type": "dimension",
            "md": { "$value": "{spacing.scale.md}" }
          }
        }
      }]
    }
  },
  "modifiers": {
    "theme": {
      "default": "light",
      "contexts": {
        "light": [{ "$ref": "./themes/light.json" }],
        "dark": [{ "$ref": "./themes/dark.json" }]
      }
    }
  },
  "resolutionOrder": [
    { "$ref": "#/sets/core" },
    { "$ref": "#/modifiers/theme" }
  ]
}

Output

:root {
  --color-palette-blue-500: #0066cc;
  --color-action-brand: var(--color-palette-blue-500);
  --spacing-scale-md: 16px;
  --spacing-gap-md: var(--spacing-scale-md);
}

[data-theme="light"] {
  --color-text-default: var(--color-palette-gray-900);
  --color-background-default: var(--color-palette-white);
}

[data-theme="dark"] {
  --color-text-default: var(--color-palette-gray-100);
  --color-background-default: var(--color-palette-gray-900);
}

// tokens-light.json
{
  "color-palette-blue-500": "#0066cc",
  "color-action-brand": "#0066cc",
  "spacing-scale-md": "16px",
  "spacing-gap-md": "16px",
  "color-text-default": "#1a1c1f",
  "color-background-default": "#ffffff"
}

// tokens-dark.json
{
  "color-palette-blue-500": "#0066cc",
  "color-action-brand": "#0066cc",
  "spacing-scale-md": "16px",
  "spacing-gap-md": "16px",
  "color-text-default": "#f5f5f7",
  "color-background-default": "#1a1c1f"
}

Quick Start

Scaffold a project
Terminal window
```
pnpm create dispersa
```

Explore and customize the scaffold

import { build, css } from 'dispersa'
import { colorToHex } from 'dispersa/transforms'

await build({
   resolver: './tokens.resolver.json',
   buildPath: './output',
   outputs: [css({
     name: 'css',
     file: 'tokens.css',
     preset: 'bundle',
     preserveReferences: true,
     transforms: [colorToHex()],
   })],
})

Build and ship

pnpm run build

:root {
  --color-palette-blue-500: #0066cc;
  --color-action-brand: var(--color-palette-blue-500);
  --spacing-scale-md: 16px;
}

Why Dispersa?

DTCG 2025.10

Full support for the stable Design Tokens spec — resolver documents, sets, modifiers, and every token type.

6 Output Formats

CSS, JSON, JS/TS, Tailwind v4, Swift/SwiftUI, and Kotlin/Compose — all from one source of truth.

Schema Validation

Tokens and resolver documents are validated against the official DTCG 2025.10 JSON schemas. Catch structural errors before they reach production.

Extensible Pipeline

Plug in custom filters, transforms, and renderers. See how the pipeline works.

Keep Going

Your First Build Walk through the scaffolded project and explore what each file does.

Understanding Design Tokens New to tokens? Learn the DTCG standard from the ground up.

Output Formats CSS, JSON, JS, Tailwind, iOS, and Android -- see every built-in renderer.