What the Design Token Converter does
This design token converter reads tokens in the W3C Design Tokens Community Group (DTCG) JSON format and writes them as CSS custom properties, SCSS variables, a JavaScript or TypeScript object, a Tailwind theme, or resolved DTCG JSON. It follows {alias} references, inherits $type from groups, and lists every token it could not translate and why.
It also works the other way: paste --custom-properties or $scss-variables and it builds a DTCG file with inferred types, turning var(--x) references into aliases. Everything runs in your browser.
How to use it
- Paste a DTCG
tokens.json, or CSS/SCSS variable declarations, or drop a .json, .css or .scss file (up to 2 MB). The format is detected from the first character. - Pick the output: CSS custom properties, SCSS, JS, TS, a Tailwind
theme.extendblock, or DTCG JSON with every alias resolved. - Optionally add a name prefix (for example
dsgives--ds-color-brand-500) and change the selector the CSS variables are written into. - Decide whether aliases stay as references. Kept,
color.textbecomesvar(--color-neutral-900), so changing the base colour updates it; resolved, it becomes the literal#0f172a. - Read the notes, then copy or download the output, or export the token-by-token report as CSV.
Reading the results
Names are the token's path joined with hyphens and lower-cased, so color.brand.500 becomes --color-brand-500 or $color-brand-500. JS, TS and JSON keep the nested structure.
Composite tokens are expanded where CSS needs several properties: a typography token becomes one variable per property (-font-family, -font-size, -font-weight, -line-height). A shadow becomes one box-shadow value, with several layers joined by commas.
Errors mean the file breaks the format: circular or missing references, or names containing ., { or }. 'Not converted' means the token is valid but the chosen target has no equivalent, such as a dashed strokeStyle object in CSS or a typography composite in a Tailwind theme.
When reading CSS or SCSS, types are inferred from the value's shape (colour, px/rem/em dimension, ms/s duration, number, cubic-bezier). Anything else is kept as an untyped value and flagged, so you can add $type by hand.
Worked example: 16 tokens become 19 CSS variables
The 'DTCG tokens with aliases' example has 16 tokens: six colours (two of them aliases), three spacing values, a radius, a font family, a font weight, a shadow, a duration, an easing curve and one typography composite.
In CSS with aliases kept, color.text ({color.neutral.900}) becomes --color-text: var(--color-neutral-900); and font.weight.bold ("bold") becomes 700, the value DTCG assigns to that keyword. The shadow {offsetX 0, offsetY 4px, blur 12px, spread 0, color #0f172a26} becomes 0 4px 12px 0 #0f172a26.
The typography token type.heading expands into four variables, so the output has 15 + 4 = 19 entries from 16 tokens. Switch to Tailwind and the typography token is listed as not converted, because a Tailwind theme key holds one value, not a set of font properties.
Limitations: what the result does not prove
- The DTCG format is a Community Group report that is still evolving. This tool follows the published draft's token types and both value styles for dimensions (
"16px"and{value, unit}); vendor extensions under$extensionsare ignored. - Tailwind output targets the
tailwind.config.jstheme.extendshape used by Tailwind v3. Tailwind v4 prefers CSS@themevariables; use the CSS output there. - Colour values are passed through, not converted between colour spaces. A DTCG colour object in a non-sRGB space is written as a CSS
color()function, which older browsers do not support. - Type inference from CSS is a heuristic based on the value's shape. It cannot tell a spacing value from a font size; check the types before sharing the DTCG file.
Privacy: where your data goes
Everything you paste, type or drop is processed in this browser tab. It is not uploaded, logged, stored or sent to analytics. Session recording and tag-manager scripts are switched off on this page.
Standards and sources
- Design Tokens Community Group - Format Module - checked 19 Sep 2026
- W3C - CSS Custom Properties for Cascading Variables Level 1
- Tailwind CSS v3 - Theme configuration
- Sass - Variables
Frequently asked questions
What is the DTCG design token format?
It is a JSON format from the W3C Design Tokens Community Group. Groups are plain objects, and a token is any object with a $value, optionally a $type such as color or dimension and a $description. References to other tokens are written as {group.token}. Tools such as Figma plugins and Style Dictionary can read and write it.
Should aliases stay as var() references or be resolved?
Keep them when the output is your live theme: overriding one base variable, for example in dark mode, then updates everything that refers to it. Resolve them when the consumer cannot follow references, such as an email template, a native app or a JSON file read by another tool.
Why does a typography token turn into several CSS variables?
CSS has no single property for a whole type style (the font shorthand cannot hold letter-spacing and resets other properties). So one typography token becomes one custom property per part, which you apply together in a class.
What happens with circular references between tokens?
If color.primary points to color.secondary and that points back, neither has a value. The converter reports the full chain as an error and leaves both out of the output instead of guessing, so the problem is visible rather than silently becoming a wrong colour.
Can this replace Style Dictionary in a build pipeline?
No. It is for converting and checking tokens by hand, previewing what a file produces, and migrating existing CSS variables into DTCG. A build pipeline that runs on every commit, with platform-specific transforms such as Android XML or iOS Swift, still needs a build tool.
How are CSS variable names split into groups?
Each hyphen starts a new level, so --color-brand-dark becomes color.brand.dark. If a name is also the start of other names, such as --color-brand next to --color-brand-dark, it becomes color.brand.base, because a DTCG token cannot also be a group.
Last reviewed by the A2Z.Tools team against the sources listed above.
