Diez ·

The Design Token Framework

Diez is an open-source developer toolkit for building & maintaining design tokens at scale.

Write & maintain styles in one place, then compile & consume them everywhere: Diez supports any UI component library or codebase written in Swift, Objective-C, Kotlin, Java, TypeScript, JavaScript/JSON, CSS, or SCSS.

Diez reduces the cost of delivering a consistent visual identity across your company's apps & websites.

What's in the box?

Diez's toolkit comes in four parts:

Compiler — Diez includes a novel open-source compiler that converts (transpiles) TypeScript tokens into native packages for iOS, Android, and Web.
<img src="https://static.haiku.ai/diez/readme/compiler.gif" />
Framework — Diez's framework is a library of common design token patterns, including pre-written prefabs for Typography, Colors, Images, Drop Shadows, Dimensions, and more. Prefabs can be configured, nested, and reused to express any style, brand, or theme you can imagine.
<img src="https://static.haiku.ai/diez/readme/framework.png" />
You can also write your own custom prefabs. Open-source contributions welcome!
Extractors — Diez's extractors automate the retrieval of design tokens from Figma, Sketch, Adobe XD, and InVision DSM. These command-line utilities are powerful tools for customizing your own design/developer hand-offs and are a great fit for CI servers.
<img src="https://static.haiku.ai/diez/readme/extractors.jpg" />
Documentation Generator — Diez DocsGen builds customizable static HTML docs from any Diez project, complete with markdown-rendered code comments. Technically implemented as an additional compiler target, Diez DocsGen helps keep your styleguide and documentation perfectly up-to-date with your design token source of truth.

See an example Diez project and its DocsGen output.
<img src="https://static.haiku.ai/diez/readme/docsgen.gif" />

Getting Started & Installation

Generate a new Diez project with:

yarn create diez

npx diez create

Check out diez.org/getting-started for more thorough installation instructions and a robust set of guides.

Examples

Basic example

const tokens = {
  // Use for all primary type and monochromatic assets.
  foregroundColor: Color.hex('#AE0000'),
  // Use this sparingly, as it's very strong.
  foregroundAccent: Color.hex('#FF0000'),
  // This is our "canvas" color and default background.
  backgroundColor: Color.hex('#231020'),
}

The above TypeScript definition will compile to native packages on iOS and Android, where you can access your tokens like:

tokens.foregroundColor

From the above definition, Diez will also generate SCSS variables that can be used like:

#some-element {
  background-color: $tokens-background-color;
}

The inline comments and static values will also be built into the native SDKs, where developers can read the comments from autocomplete prompts.

Semantic tokens example

Diez robustly supports the "semantic tokens" pattern, of separating the value of design tokens from their semantic purpose, for example maintaining a separate set of "raw colors" vs. a semantic mapping of their intended use.

This example also shows one of Diez's several built-in helpers, [Color].lighten — these helpers make it easy to avoid duplicating "sources of truth" in your tokens.

//colors.ts
import {Color} from '@diez/prefabs';

export const rawColors = {
  tiger: Color.rgba(241, 93, 74, 1),
  marigold: Color.rgba(255, 172, 57, 1),
  clover: Color.rgba(163, 206, 50, 1),
  cyan: Color.rgba(4, 182, 203, 1),
};

export const semanticColors = {
  foreground: rawColors.tiger,
  foreground50: rawColors.tiger.lighten(.5),
  background: rawColors.clover,
  background50: rawColors.clover.lighten(.5),
}

Nesting & reuse example

This slightly more complex example shows how multiple prefabs (in this case Typograph, Color, and the primitive type number) naturally compose to express complex hierarchies of data — without needing to maintain multiple declarations of the same data.

This example also shows how tokens can be separated into multiple files and easily imported/reused.

//typography.ts
import {Typograph} from '@diez/prefabs';
import {sizes} from './sizes';
import {semanticColors} from './colors'; //from example above

export const typography = {
  heading1: new Typograph({
    color: semanticColors.foreground,
    font: fonts.PoppinsExtraBold.Regular,
    fontSize: sizes.xxl
  }),
  heading2: new Typograph({
    color: semanticColors.foreground50,
    font: fonts.PoppinsExtraBold.Regular,
    fontSize: sizes.xl
  }),
  body: new Typograph({
    color: semanticColors.foreground,
    font: shibuiFonts.Poppins.Regular,
    fontSize: sizes.sm
  }),
}

//sizes.ts
export const sizes = {
  xxl: 66,
  xl: 41,
  l: 35,
  md: 24,
  sm: 18,
  xs: 12,
}

Design file Extractor example

From this example Figma File:

Diez's Extractor generates design token code that looks like:

/**
 * GENERATED CODE
 * This file is generated by a Diez Extractor and is not intended to be edited by hand.
 * This file may be overwritten.
 *
 * FromFigma.ts
 *
 */
import { Color, DropShadow, File, Font, GradientStop, Image, LinearGradient, Point2D, Typograph } from "@diez/prefabs";

const fromFigmaColors = {
    teal50: Color.rgba(77, 197, 208, 1),
    teal40: Color.rgba(119, 221, 231, 1),
    // abbreviated for terseness
};

const fromFigmaGradients = {
    grad1: new LinearGradient({ stops: [GradientStop.make(0, Color.rgba(141, 245, 255, 1)), GradientStop.make(1, Color.rgba(183, 162, 255, 1))], start: Point2D.make(0.865941961194631, 0.131944384027248), end: Point2D.make(0.105072476657214, 0.937499990588448) })
};

const fromFigmaShadows = {
    shad20: new DropShadow({ offset: Point2D.make(0, 1), radius: 4, color: Color.rgba(0, 0, 0, 0.25) }),
    // abbreviated for terseness
};

export const fromFigmaFonts = {
    Poppins: {
        Bold: Font.fromFile("assets/FromFigma.figma.contents/fonts/Poppins-Bold.otf"),
        Regular: Font.fromFile("assets/FromFigma.figma.contents/fonts/Poppins-Regular.otf")
    }
};

const fromFigmaTypography = {
    heading1: new Typograph({ color: Color.rgba(0, 0, 0, 1), font: fromFigmaFonts.Poppins.Bold, fontSize: 18 }),
    body: new Typograph({ color: Color.rgba(0, 0, 0, 1), font: fromFigmaFonts.Poppins.Regular, fontSize: 12 })
};

export const fromFigmaImagesFiles = {
    iconFastFoodHotDog: new File({ src: "assets/FromFigma.figma.contents/images/IconFastFoodHotDog.png" }),
    iconFastFoodHotDog2x: new File({ src: "assets/FromFigma.figma.contents/images/IconFastFoodHotDog@2x.png" }),
    iconFastFoodHotDog3x: new File({ src: "assets/FromFigma.figma.contents/images/IconFastFoodHotDog@3x.png" }),
    iconFastFoodHotDog4x: new File({ src: "assets/FromFigma.figma.contents/images/IconFastFoodHotDog@4x.png" }),
    // abbreviated for terseness
};

export const fromFigmaImages = {
    iconFastFoodHotDog: Image.responsive("assets/FromFigma.figma.contents/images/IconFastFoodHotDog.png", 24, 24),
    iconBinocular: Image.responsive("assets/FromFigma.figma.contents/images/IconBinocular.png", 24, 24),
    // abbreviated for terseness
};

export const fromFigmaTokens = {
    colors: fromFigmaColors,
    gradients: fromFigmaGradients,
    shadows: fromFigmaShadows,
    typography: fromFigmaTypography
};

Extracted tokens are intended to be imported and referenced by other files in your project — then updated through design tools, and extracted again. As another application of "semantic tokens," this separation of concerns allows you to treat design files as versionable code assets.

For example:

//colors.ts, pulling data right out of Figma
import {fromFigmaColors} from './designs/FromFigma';

const semanticColors = {
  foreground: fromFigmaColors.teal50,
  background: fromFigmaColors.purp60,
}

More Examples

See complete, compilable examples here, or at the Haiku Team's Diez-powered design language, Shibui.

When you run yarn create diez or npx diez create, you will also be given an option to generate a starter project that includes several functional examples.

FAQ

What are design tokens?

Think of design tokens as "design data": concepts like colors, typography definitions, spacings, sizings, and drop shadows — agnostic of any particular design tool or programming language. Design tokens are the basic building blocks that allow you to express any design language as pure data.

The magic of design tokens is they sit right at the gap between design and code — they're design concepts, but since they have no opinions about rendering or technologies, they're adaptable into any cod

Diez

Install / Use

README