Design Token KitGet Started

CLI

Convert tokens

Convert token documents and generate CSS, SCSS, Tailwind CSS v4, or SwiftUI output.

Convert tokens

Use dtokens convert to transform token documents or generate production outputs.

dtokens convert tokens.json

CSS is the default output format.

Command

dtokens convert [options] [files...]

Input formats

Use --inform or -i to set the input format:

  • dtcg
  • hrdt
  • design-md

Input format is detected automatically by default.

dtokens convert tokens.yaml --inform hrdt

Output formats

Use --outform or -f:

  • dtcg
  • hrdt
  • design-md
  • css
  • scss
  • tailwind-v4
  • swiftui
dtokens convert tokens.json --outform hrdt

Use --out or -o to write the result to a file:

dtokens convert tokens.json \
  --outform hrdt \
  --out ./tokens.yaml

Without --out, regular text output is written to stdout. Multi-theme SCSS is the exception: it writes a tar archive to stdout.

Convert token documents

DTCG JSON to HRDT YAML

dtokens convert tokens.json --outform hrdt

HRDT YAML to DTCG JSON

dtokens convert tokens.yaml \
  --inform hrdt \
  --outform dtcg

DTCG JSON to DESIGN.md

dtokens convert tokens.json --outform design-md

This conversion is intentionally lossy. DESIGN.md supports a compact flat model, so unsupported DTCG token types such as border, shadow, transition, gradient, duration, fontFamily, fontWeight, cubicBezier, and strokeStyle are skipped.

DESIGN.md to DTCG JSON

dtokens convert DESIGN.md \
  --inform design-md \
  --outform dtcg

Multiple input sources are not supported for serialized token-document output.

Generate CSS custom properties

dtokens convert tokens.json \
  --outform css \
  --out ./tokens.css

The generated stylesheet contains:

  • base variables under :root;
  • theme overrides under :root[data-theme="<theme>"];
  • token aliases as var(--token-name) references.

Pass a base source followed by theme sources:

dtokens convert \
  tokens.json \
  tokens.dark.json \
  --outform css \
  --out ./tokens.css

Generate SCSS

dtokens convert tokens.json \
  --outform scss \
  --out ./tokens.scss

Use --separator to replace dots in token paths:

dtokens convert tokens.json \
  --outform scss \
  --separator _

For multiple themes, SCSS emits separate outputs instead of one stylesheet:

dtokens convert \
  tokens.json \
  tokens.dark.json \
  --outform scss \
  --out ./tokens.scss

This creates tokens.base.scss and tokens.dark.scss. The output directory must already exist. Without --out, multi-theme SCSS writes a tar archive to stdout. With --out ./tokens.tar, it writes that archive to a file.

Generate Tailwind CSS v4

dtokens convert tokens.json \
  --outform tailwind-v4 \
  --out ./tokens.tailwind.css

With themes:

dtokens convert \
  tokens.json \
  tokens.dark.json \
  --outform tailwind-v4 \
  --out ./tokens.tailwind.css

Tailwind-specific selector options:

dtokens convert \
  tokens.json \
  tokens.dark.json \
  --outform tailwind-v4 \
  --base-selector :host \
  --theme-selector ":host([data-theme='{theme}'])"

Default Tailwind output contains @import 'tailwindcss';, one @theme block for base values, and theme selectors for overrides. Dimension tokens map to spacing by default, but names containing breakpoint, radius, font-size, line-height, or letter-spacing map to the matching Tailwind namespaces. The only explicit design-token-kit.tailwindNamespace value currently supported is breakpoint.

Generate SwiftUI

dtokens convert tokens.json \
  --outform swiftui \
  --out ./DesignTokens.swift

Default SwiftUI output contains nested enums with typed static let members. Token references are preserved as Swift constant paths.

Use --swift-type struct to add a Theme struct layer:

dtokens convert \
  tokens.json \
  tokens.dark.json \
  --outform swiftui \
  --swift-type struct \
  --out ./DesignTokens.swift

With multiple sources, the first file is the base token set. Remaining files are emitted as theme variants.

Read from standard input

Use -:

cat tokens.json | dtokens convert - --outform css

You can omit the source when stdin is the only input:

cat tokens.json | dtokens convert --outform css

Multiple sources

Multiple sources are supported when generating:

  • CSS;
  • SCSS;
  • Tailwind CSS v4.
  • SwiftUI.

The first source is the base token set. Remaining sources are theme overrides.