token-sync

Generate CSS, SCSS, Tailwind theme, and TypeScript output from a single W3C Design Tokens (DTCG) source file — so your tokens live in one place instead of being hand-mirrored across formats.

This was pulled out of design-system, where tokens were originally maintained by hand in both src/tokens/*.ts and src/index.css.

Install

npm install --save-dev @aiuxmasters/token-sync

Usage

npx token-sync build --input tokens.json --output ./dist --formats css,ts,tailwind

Flag	Description	Default
-i, --input <path>	Path to a DTCG-format tokens JSON file	required
-o, --output <dir>	Output directory	required
-f, --formats <list>	Comma-separated: css, scss, ts, tailwind	css,ts

Given:

{
  "color": {
    "$type": "color",
    "brand": { "500": { "$value": "#5b8def" } }
  },
  "spacing": {
    "$type": "dimension",
    "sm": { "$value": "4px" },
    "md": { "$value": "{spacing.sm}" }
  }
}

--formats css produces:

:root {
  --color-brand-500: #5b8def;
  --spacing-md: 4px;
  --spacing-sm: 4px;
}

--formats tailwind produces a theme.extend-shaped object:

export const tailwindTheme = {
  "colors": { "brand": { "500": "#5b8def" } },
  "spacing": { "sm": "4px", "md": "4px" }
} as const;

Token references

Alias one token to another with {group.path.to.token} — token-sync resolves the chain (with cycle detection) before writing output, so every generated format gets the final, literal value.

Programmatic API

import { parseTokens, toCss, toTailwindTheme } from "@aiuxmasters/token-sync";

const tokens = parseTokens(JSON.parse(tokensJson));
writeFileSync("tokens.css", toCss(tokens));

Supported $types

Values are passed through as-is ($type is preserved on the parsed token and available to consumers of the programmatic API), so anything DTCG allows as a string or number value works — colors, dimensions, font weights, etc. Composite token types (shadows, typography, gradients as objects) aren't flattened yet; contributions welcome.

Development

npm install
npm test
npm run build

License

MIT — see LICENSE.