@quartzds/style-dictionary-extensions NPM

SPDX-License-Identifier: Apache-2.0

Style Dictionary extensions for the Quartz design tokens

💡 Overview

This package provides extensions and helper functions to transform Quartz design tokens into resources for developers using Style Dictionary. Those design tokens are edited using the Tokens Studio Figma plugin.

Prerequisites

A hierarchy of JSON files produced by the Tokens Studio Figma plugin in the "legacy" format (do not enable the DTCG format in the Figma plugin).
node ^18.0.0 || >=20.0.0

Token transformation rules

Translating design tokens into platform-specific assets requires rules. Quartz uses specific rules based on its own conventions. The goal of this library is to package all those transformation rules into a convenient API for Style Dictionary.

Supported platforms

Experimental support:

Android
Swift
XAML

Coming later:

JavaScript
TypeScript

💿 Installation

npm install @quartzds/style-dictionary-extensions

📖 Usage

Create a build script that will configure and run Style Dictionary to output tokens to several formats, using the helpers provided by this package. See the Transformation rules page for the list of transformations provided for each target format.

The general algorithm is as follows:

Create a base StyleDictionary object, pre-configured with Quartz's custom transforms.
For every token set you want to export (desktop, tablet, mobile, dark, light, etc.):
- create a Style Dictionary Config object using the helpers from this package
- call the extend(config) method of the base StyleDictionary object to get a new instance from a specific configuration
- let that Style Dictionary instance generate the files using the buildAllPlatforms() function

Get a base `StyleDictionary` object

The getPresetStyleDictionary() function registers Quartz extensions and returns a fresh Style Dictionary instance to use as the base to export to one or more formats:

import { getPresetStyleDictionary } from '@quartzds/style-dictionary-extensions'

const baseSD = await getPresetStyleDictionary()

Create Style Dictionary configurations

This package provides transform groups for supported target formats, as well as helper functions to help you set up Style Dictionary configuration objects.

Use the get<Format>PlatformConfig(sourceType, destination, options?) functions to get ready-made PlatformConfig objects to use in your Style Dictionary Config object:

import {
  getAndroidPlatformConfig,
  getCSSPlatformConfig,
  getSwiftPlatformConfig,
} from '@quartzds/style-dictionary-extensions'

const sdConfig = {
  platforms: {
    android: getAndroidPlatformConfig(...),
    css: getCSSPlatformConfig(...),
    swift: getSwiftPlatformConfig(...),
  },
  ...other config properties...
},

Run Style Dictionary generation

Finally, let Style Dictionary build all the platforms for your configuration objects:

var sd = baseSD.extend(desktopConfig)
sd.buildAllPlatforms()

sd = baseSD.extend(lightThemeConfig)
sd.buildAllPlatforms()

// etc.

📓 Simple example

This example assumes the following structure of design tokens files generated by the Tokens Studio Figma plugin:

src/
└── tokens
    ├── private.json <-- don't export these tokens (internal bindings)
    ├── platform
    │   ├── desktop.json
    │   └── mobile.json
    └── theme
        ├── dark.json
        └── light.json

We want to transform these tokens into the following platform-specific assets:

dist/
├── platform
│   ├── desktop.css
│   ├── desktop.swift
│   ├── desktop.xml
│   └── mobile.css
│   └── mobile.swift
│   └── mobile.xml
└── theme
    ├── dark.css
    ├── dark.swift
    ├── dark.xml
    └── light.css
    └── light.swift
    └── light.xml

Here is the script to achieve that:

import {
  getAndroidPlatformConfig,
  getCSSPlatformConfig,
  getPresetStyleDictionary,
  getSwiftPlatformConfig,
  SourceType,
} from '@quartzds/style-dictionary-extensions'
import type { Config, FileHeader } from 'style-dictionary/types'

const baseSD = await getPresetStyleDictionary()

const copyrightFileHeader: FileHeader = (defaultMessage, options) => (...)

const lightThemeConfig: Config = {
  platforms: {
    android: getAndroidPlatformConfig(
      SourceType.theme,
      `dist/theme/light.xml`,
      {
        fileHeader: copyrightFileHeader,
      },
    ),
    css: getCSSPlatformConfig(
      SourceType.theme,
      `dist/theme/light.css`,
      {
        fileHeader: copyrightFileHeader,
        selector: '.qds-theme-light',
      },
    ),
    swift: getSwiftPlatformConfig(
      SourceType.theme,
      `dist/theme/light.swift`,
      {
        fileHeader: copyrightFileHeader,
        className: 'Light',
      },
    ),
  },

  include: [`./tokens/private.json`],
  source: [`./tokens/theme/light.json`],
}

const darkThemeConfig: Config = {
  /* ... */
}

const desktopConfig: Config = {
  /* ... */
}

const mobileConfig: Config = {
  /* ... */
}

const allConfigs = [
  lightThemeConfig,
  darkThemeConfig,
  desktopConfig,
  mobileConfig,
]

for (const config of allConfigs) {
  const sd = StyleDictionary.extend(config)
  sd.cleanAllPlatforms() // Optional
  sd.buildAllPlatforms()
}