---
name: design-tokens-dtcg-style-dictionary
description: "Author DTCG-format token JSON and build multi-platform outputs with Style Dictionary v4 — CSS, Tailwind, iOS, Android. Production design-token pipelines: authoring DTCG JSON with $value/$type/$description, alias references with {color.base.500} curly-brace syntax, and composite types (typography, shadow, border, gradient). Configures Style Dictionary v4 with the platforms/transformGroups/files schema, custom transforms and formats via the hooks API, ESM config and the buildAllPlatforms API, plus references/outputReferences to emit CSS custom properties, Tailwind theme, SCSS, iOS swift/UIKit, and Android resources. Covers Tokens Studio export, multi-theme/brand builds with filters, and W3C $extensions."
license: MIT
---

# Design Tokens DTCG Pro

Author design tokens in the W3C Design Tokens Community Group (DTCG) JSON format and compile them to platform-specific artifacts with Style Dictionary v4. This skill is for design-system engineers who maintain a single source of truth for color, spacing, and typography and need it to land correctly in CSS, Tailwind, Swift, and Kotlin without hand-syncing values.

## When to use it

- You are starting a token layer and want it DTCG-compliant from day one (`$value`, `$type`, `$description`) rather than the legacy Style Dictionary `value` schema.
- You need one token file to emit CSS custom properties, a Tailwind theme, iOS `UIColor`/Swift, and Android XML resources.
- You have aliases like `{color.brand.primary}` that must resolve across files and tiers (primitive → semantic → component).
- You are migrating an existing Style Dictionary v3 config to v4's new API and transform names.

## How it works

You write token JSON using DTCG keys. References use curly-brace syntax (`"$value": "{color.base.blue.500}"`) and resolve at build time. Composite `$type`s are supported: `typography`, `shadow`, `border`, `gradient`, and `transition`, each with their structured sub-properties.

Builds run through Style Dictionary v4's programmatic API. You instantiate `new StyleDictionary(config)` and call `await sd.buildAllPlatforms()`. The config uses the `platforms` map, each with a `transformGroup` (e.g. `css`, `js`, `ios-swift`, `compose`) or an explicit `transforms` array, plus `files[]` entries that pick a `format` (`css/variables`, `javascript/es6`, `ios-swift/class.swift`, `android/resources`) and `destination`. Custom logic is added via `sd.registerTransform`, `registerFormat`, and `registerFilter`. Note v4 is ESM-first and async.

## Example

```js
// sd.config.js
import StyleDictionary from 'style-dictionary';

const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{ destination: 'vars.css', format: 'css/variables' }],
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'build/ios/',
      files: [{ destination: 'Tokens.swift', format: 'ios-swift/class.swift' }],
    },
  },
});
await sd.buildAllPlatforms();
```

## Tips & gotchas

- Style Dictionary auto-detects DTCG when files use `$value`/`$type`; do not mix `value` and `$value` in the same project or resolution breaks.
- v4 dropped synchronous `.buildAllPlatforms()` — everything returns promises, so top-level `await` or wrap in an async function.
- Several v3 transforms were renamed (e.g. `size/rem`); run with `--verbose` or check the v4 migration notes when a transform "silently" does nothing.
- Composite tokens need a format that understands them; the default `css/variables` flattens shadows fine but custom Swift/Compose output usually needs a `registerFormat`.

## FAQ

**Does it handle multi-tier semantic tokens?** Yes — keep primitives, semantics, and component tokens in separate files under `source`; aliases resolve across the merged tree regardless of file boundaries.

**Can it output Tailwind?** Yes, via a JS/JSON format consumed by `tailwind.config` `theme.extend`, or a custom format that emits the theme object directly.

**Is Figma Tokens / Tokens Studio export compatible?** Tokens Studio exports DTCG-aligned JSON; minor normalization (e.g. `$type` placement) may be needed before it feeds cleanly into the pipeline.