DTCG — Design Tokens Community Group

DTCG is a JSON file format for exchanging design tokens between tools. Vanilla Breeze supports it as a sibling artifact to its CSS-native theme system, so designers and developers can move VB themes through Figma, Tokens Studio, Style Dictionary, and other DTCG-aware tools without a per-tool integration.

Why DTCG matters for VB

VB's runtime token system — CSS custom properties, OKLCH, light-dark(), relative-color computation — is expressive and platform-native. But until DTCG, every design tool spoke its own dialect: Figma Variables, Tokens Studio JSON, Style Dictionary's legacy format, Sketch shared styles. Sharing a theme across tools meant manual translation each time.

DTCG gives the ecosystem a common JSON shape with explicit $type + $value per token, hierarchical groups, alias references, and composite types for typography / shadow / border. When VB themes are emitted as DTCG, they become consumable in any DTCG-aware tool. When DTCG files arrive (from Figma exports, public design systems, or hand-authored sets), VB can apply them as themes.

What VB supports

Export

<theme-export> has a format="dtcg" mode that emits stable-spec 2025.10 JSON. The format selector is in the toolbar; the download saves as theme.tokens.json with MIME application/design-tokens+json.

Import

<theme-import> takes DTCG JSON via paste, file upload, or URL fetch and applies the resulting tokens to a target preview scope. Tokens that don't map to a known VB prefix are surfaced in an ignored panel rather than dropped silently.

Catalog

<theme-catalog> lets you start from a known design system in one click — Material 3, IBM Carbon, Salesforce Lightning, GOV.UK, Atlassian, Tailwind defaults, Bootstrap defaults, Catppuccin Mocha. Each entry carries license and attribution metadata.

Theme library

Every theme in VB ships as a .tokens.json sibling next to its CSS at /cdn/themes/. See the theme library for the full list with download links.

Color, dimension, and the parametric round-trip

DTCG 2025.10 supports OKLCH and all CSS Color Module 4 spaces natively, so VB's OKLCH primitives translate cleanly. Dimensions in px and rem are spec-supported; for em and percent units (which VB uses in places like --letter-spacing-tight), VB stores the unit hint under $extensions["com.vanilla-breeze"].unit so it round-trips exactly.

The interesting case is parametric themes. VB themes often define state colors as derivations:

--color-primary: oklch(var(--lightness-primary) var(--chroma-primary) var(--hue-primary));
--color-primary-hover:  oklch(from var(--color-primary) calc(l - 0.08) calc(c + 0.02) h);
--color-primary-active: oklch(from var(--color-primary) calc(l - 0.12) c h);

The CSS oklch(from …) relative-color syntax has no direct DTCG equivalent — DTCG aliases are pass-through references, not derivations. So when VB exports a parametric theme:

• The resolved value goes into $value — other tools see a real, usable color.
• The original CSS expression is preserved under $extensions["com.vanilla-breeze"].expression.
• On re-import into VB, the importer prefers the preserved expression over the resolved value, so a round-trip through VB tooling is lossless.
• A round-trip through a third-party tool that strips unknown extensions will downgrade to the resolved value — functional but no longer parametric. This is a known and documented trade-off.

The same pattern applies to light-dark(a, b) values: VB emits a $root/light/dark variant triplet for cross-tool fidelity AND preserves the literal under $extensions["com.vanilla-breeze"].lightDark.

Composite typography

DTCG's composite typography token bundles related primitives (fontFamily, fontSize, fontWeight, lineHeight) into one object. VB's runtime stores those as separate scalars. On import, VB unpacks composite typography tokens into the matching scalars (--font-{name}, --font-size-{name}, etc.). On export, VB emits scalars by default; future revisions may synthesize composite tokens for tools that prefer them.

Tooling pointers

Design Tokens Community Group

The W3C community group and canonical spec.

Style Dictionary

Multi-platform code generator. Run sd build against any .tokens.json VB emits to produce iOS, Android, Flutter, or alternative CSS output.

Tokens Studio for Figma

The dominant Figma plugin for managing tokens. Imports / exports DTCG; pipes through Style Dictionary.

Penpot

Open-source design tool with native DTCG export.

What's next

See the Theme Composer for the hands-on workflow: edit specimens, browse the catalog, paste DTCG, and export your result. The theme library lists every shipped theme with one-click DTCG downloads.