Design Token KitGet Started

Core API

Core API overview

Use Design Token Kit as a TypeScript library in applications and custom tooling.

Core API overview

@design-token-kit/core is the runtime library behind Design Token Kit.

Use it when you need to integrate token parsing, validation, conversion, showcase generation, or statistics into your own application.

Node.js 18 or newer is required.

Install

npm install @design-token-kit/core

Quick start

import {
  DtcgChecker,
  DtcgListLoader,
  CssTokenConverter,
  ScssTokenConverter,
  SwiftUiTokenConverter,
  createTokenHtmlShowcase,
  createTokenStats,
} from "@design-token-kit/core";

const sources = [
  "./tokens.json",
  "./tokens.dark.yaml",
];

const issues = await new DtcgChecker().validate(sources);

if (issues.some((issue) => issue.severity === "error")) {
  console.error(issues);
  process.exit(1);
}

const list = await new DtcgListLoader().load(sources);

const css = new CssTokenConverter().convertList(list);
const scss = await new ScssTokenConverter().convert([
  "./tokens.json",
]);
const swift = new SwiftUiTokenConverter().convertList(list);

const html = await createTokenHtmlShowcase().showcase(sources);
const stats = await createTokenStats().stats(sources);

console.log(css);
console.log(scss);
console.log(swift.slice(0, 120));
console.log(html.slice(0, 120));
console.log(stats);

Main APIs

Checking

  • DtcgChecker
  • DtcgSchemaValidator
  • HrdtTokenValidator

Loading and parsing

  • DtcgListLoader
  • DtcgJsonReader
  • HrdtTokenReader
  • DesignMdReader

Writing documents

  • DtcgJsonWriter
  • HrdtTokenWriter
  • DesignMdWriter
  • DtcgToDesignMdMapper

Generating outputs

  • CssTokenConverter
  • ScssTokenConverter
  • TailwindTokenConverter
  • SwiftUiTokenConverter
  • SwiftUiColorValueConverter
  • createTokenCssConverter()
  • createTokenScssConverter()
  • createTailwindCssConverter()

Compatibility aliases for older Dtcg* converter names are still exported. Use the primary names above in new code and documentation.

Reports and previews

  • createTokenHtmlShowcase()
  • createTokenStats()

Source model

Core APIs can work with:

  • local files;
  • standard input;
  • URLs;
  • raw token content strings prefixed with content:.

Supported token formats:

  • DTCG JSON;
  • HRDT YAML;
  • DESIGN.md.

When multiple token sources are provided:

  1. the first source is the base token set;
  2. remaining sources are theme overrides.

Parsed documents and source lists

Use a source-based method when your application starts with file paths or other input sources.

Use document- or list-based methods when the tokens are already loaded:

  • convertDocument() for a parsed document;
  • convertList() for a prepared DtcgList.

Avoid loading the same sources again when a parsed document or list is already available.