Definition

A Source represents where the original design data come from - think of Figma (Variables or Local Styles) or Tokens Studio.

You can add many sources into a repository.

Learn more about the available Sources compatible with Specify.

Collecting the design data

Once a source is configured, Specify starts to collect your design data. Over this process, the SDTF Engine acquires, validates and converts the original data into a SDTF token tree that get stored within the repository.

From this point on, you can synchronize your source(s) with Specify anytime, at a click of a button.

Repository with many sources

Data from many sources get automatically merged into a consolidated SDTF token tree. If Specify detects a conflict over sources, it will refuse to synchronize the first source that cause the conflict and turn it into an error state.

Specify is a central and tool-agnostic platform. It means you can integrate your daily tools to collect, store and distribute your design data to the right teams, in the right format, at the right time. To sum things up, see Specify as the synchronization layer for your design data at the heart of your design system.

• Designers, connect your favorite design tool, like Figma or Tokens Studio, and let Specify monitor and collect your design tokens and assets automatically. This way, you control what is sent to developers and reduce the risk of inconsistencies.

• Developers, configure tailored transformation pipelines for every project and get design tokens and assets from wherever you want. Use our CLI or get automated GitHub Pull Requests. You can also create your custom pipeline thanks to our SDK.

• Teams can benefit from a single source of truth and a continuous delivery system that ensures brand consistency.

In short, you have more time to focus on what matters most: your products and your end-users.

Introduction

In this guide you’ll learn how to pull your first design tokens to CSS Custom Properties using the Specify CLI.

Before getting started

To get the most out of this guide, you’ll need:

• A Specify account

• A Specify repository containing design tokens (Learn more ↗)

1. Install the CLI

Install @specifyapp/cli

curl -sL https://static.specifyapp.com/cli/install.sh | sh

2. Create your Specify config file

Create a configuration file for your desired output format using one of our templates ↗️

3. Add your Specify repository

Add your Specify repository and workspace from which you want to pull your design tokens. You can find your workspace name and repository name in the URL of the app when inside a repository.

module.exports = {
  version: "2",
  repository: '@workspace/repository',
  personalAccessToken: '<your-personal-access-token>',
  rules: [],
};

{
  "version": "2",
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

4. Add your personal access token

Generate a personalAccessToken for the CLI and add it in your configuration. You can generate a personal access token from you Specify account settings.

module.exports = {
  version: "2",
  repository: '@workspace/repository',
  personalAccessToken: '<your-personal-access-token>',
  rules: [],
};

{
  "version": "2",
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

5. Set your output format

Add your first rule and use the to-css-custom-properties parser to generate your tokens as CSS variables.

module.exports = {
  version: "2",
  repository: '@workspace/repository',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: "Generate tokens as CSS Custom Properties",
      parsers: [
        {
          name: "to-css-custom-properties",
          output: {
            type: "file",
            filePath: "tokens.css"
          }
        }
      ]
    }
  ]
};

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate tokens as CSS Custom Properties",
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "tokens.css"
          }
        }
      ]
    }
  ]
}

6. Pull your design tokens and assets

Our configuration is ready and we can now pull our design tokens and assets using the pull command.

specify pull

Organization (workspace)

An organization, sometimes called workspace, is the Specify place you share with your team.

Repository

A repository is like a directory containing your design tokens and assets. The design data is stored within a JSON compatible tree built upon the Specify Design Token Format.

Source

A source belongs to a repository, it represents where the original design tokens and/or assets come from - think of Figma (Variables or Local Styles) or Tokens Studio.

Destination

A destination belongs to a repository, it represents where the formatted design data get distributed on updates - think of GitHub or any automation you can come up with our CLI and SDK.

Specify Design Token Format (SDTF)

The SDTF stands for Specify Design Token Format. It's a token format that helps you sync design tokens from Figma Styles, Figma Variables, and Tokens Studio. Your design tokens are created and saved as a token tree you can query and transform thanks to the Specify API. The SDTF is composed of more than 50 token types. In a SDTF token tree, design tokens can be organized in Collections, Groups, and Modes.

Token type

A Token type is a type of design token or asset supported by Specify like a color, a textStyle or a vector.

Collection

A collection is a way to group design tokens while ensuring the modes of the tokens they contain within the SDTF. A Collection can contain groups, and design tokens with one or several modes.

Group

A group is way to semantically group design tokens in the SDTF. A group contains design tokens, other groups and exists in the context of a collection.

Alias

An alias design token is a design token whose value is not a raw value but a reference to another design token's value.

Mode

A Mode is a way to associate the value of a design token to a specific context. For instance, a color named background can have several values associated to different modes like Light or Dark.

Parsers Engine

The Parsers Engine is the high-level design data transformation and export API.

Parser Rule

A parser rule is a JSON object describing a series of parsers and options, responsible to transform and export your design tokens and assets to your code base.

Parser

Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards. See all parsers.

SDTF Client

The SDTF Client offers versatile methods for working with SDTF token trees, enabling data manipulation, transformation, and conversion into various formats or languages, bridging the gap between stored and live token instances within your repository.

SDTF Engine

The SDTF Engine brings together the core APIs that enable most of Specify features to seamlessly integrate, whether you're working in Figma or Token Studio, managing GitHub pull-requests, or directly within your codebase with the SDK or the CLI.

Configuration file

A Specify configuration file is a JSON or JavaScript file, made of one or many rules and the credentials to authenticate. The configuration is used to communicate with the Parsers Engine.

Before getting started

To get the most out of this guide, you will need:

Specify automatically fetches design tokens through the JSON file created by Tokens Studio. The best way to keep your design tokens in sync with both tools is to host your JSON file in a repository like GitHub.

1. Sync your design tokens from Tokens Studio to a provider

1. Head to your Tokens Studio plugin in Figma

2. Within the settings tab, add a new sync provider

3. Commit your Tokens Studio JSON file to your repository

2. Add your JSON file from a provider to your Specify Repository

1. Go to your Specify workspace

2. Click on "Create repository"

3. Choose "Advanced Repository"

4. Name your repository

6. Click on "Create repository"

7. In the "Source" tab, click on "Create a source"

8. Select "Remote URL"

At this point, you have two ways to sync your JSON file. Either with a public hosting link or a private one. We will go through both options below.

From a public URL

1. In the "Source" tab, click on "Create a source"

2. Select "Remote URL"

3. Select "Public"

4. Name your source

5. Paste your raw public URL of your JSON file

6. Select the format "Tokens Studio"

7. Let Specify check the connection

8. And voila!

Your JSON file is now detected as a source and your design tokens appear within your repository.

From a private URL

On the opposite of the public URL, Specify will ask you for some additional information so its system is able to fetch your file. Let’s see how to proceed with the main versioning tools:

GitHub

Requirements:

• Have a GitHub account

• Have an Advanced Repository created

• Have a JSON file containing design tokens from Tokens Studio

To add a private URL source from GitHub to Specify:

1. In the "Source" tab of your Specify repository, click on "Create a source"

2. Select "Remote URL"

3. Select "Private"

4. Name your source

7. Select "Tokens Studio Format"

8. Specify will test your JSON

9. And voila!

Azure DevOps

Requirements:

• Have an Azure DevOps account

• Have a Project containing a repository

• Have a JSON file containing design tokens from Tokens Studio

To add a private URL source from Azure DevOps to Specify:

1. In the "Source" tab of your Specify repository, click on "Create a source"

2. Select "Remote URL"

3. Select "Private"

4. Name your source

5. Paste your Azure DevOps file URL such as https://dev.azure.com/{OrgName}/{ProjectName}/_apis/git/repositories/{RepositoryName}/items?path={FilePath}&api-version=7.0&includeContent=true
7. Select "Tokens Studio Format"

8. Specify will test your JSON

9. And voila!

GitLab

Requirements:

• Have a GitLab account

• Have an Advanced Repository created

• Have a JSON file containing design tokens from Tokens Studio

To add a private URL source from GitLab to Specify:

1. In the "Source" tab of your Specify repository, click on "Create a source"

2. Select "Remote URL"

3. Select "Private"

4. Give a name to your source

5. Paste your GitLab file URL such as: https://gitlab.com/api/v4/projects/{OrgName}%2F{RepositoryName}/repository/files/{FilePath}?ref={branch}
6. Create an access token in GitLab: "Settings > Access Tokens". Select a role as Developer or Owner and select the scopes of read_api and read_repository.

7. In Specify, select Header as auth system

   1. Fill PRIVATE-TOKEN in the key field

   2. Paste your GitLab project access token

8. Select "Tokens Studio Format"

9. Specify will test your JSON

10. And voila!

JSONBin

Requirements:

• Have a JSONBin account

• Have an Advanced Repository created

• Have a bin with a JSON file containing design tokens from Tokens Studio

To add a private URL source from JSONBin to Specify:

1. In the "Source" tab of your Specify repository, click on "Create a source"

2. Select "Remote URL"

3. Select "Private"

4. Name your source

5. Paste your BIN private URL such as https://api.jsonbin.io/v3/b/{bin_id}

6. Select Header as auth system

7. 1. Following your choice, fill in the key field either with X-MASTER-KEY or X-ACCESS-KEY

   2. Paste your key in the value field

8. Select "Tokens Studio Format"

9. Specify will test your JSON

10. And voila!

3. How to update your JSON File

After adding your source. All you have to do is to:

1. Go to the "Source" tab of your Specify repository

2. Click on the context menu next to your source

3. Click on "sync"

Your source is now updated!

4. Non-supported design token types

Please keep in mind Specify is yet not compatible with the following data coming from Tokens Studio:

• Composition

• Assets (bitmap & vectors)

• Color manipulation (gradients, alpha, darken, lighten & mix)

Definition

Distributing the design data

Once your repository is filled in, you will start to distribute your design data throughout your design system consumers, starting with development teams.

The destinations offer several levels of control over the transformation required to meet your company standards.

Two main APIs at stake here:

Getting started with templates

Prerequisites

Please make sure you have:

• A GitHub account

• A Specify account

• One or multiple Specify repositories containing some design tokens.

Connecting Specify and GitHub

Once you've connected your GitHub account, Specify has to know what design tokens to synchronize and how.

1. Go to the Specify Advanced Repository you want to distribute design data from

2. Go to its "Destinations" page

3. Click on "Create Pipeline"

4. Select "GitHub application"

5. Connect or select your GitHub account

6. Select the GitHub repository you want to distribute your design data to

7. Name for your configuration file (Learn More ↗︎)

8. Create the Pull Request containing your configuration file

9. Merge the PR created by Specify containing your configuration file

10. Specify will now automatically sync design data to your GitHub repository 🎉

Useful resources

• How to sync design tokens in a GitHub monorepo

• How to run Style Dictionary with a GitHub Action

Before getting started

To get the most out of this guide, you will need:

• A Specify Account

• A Figma file containing Variables and/or Styles

1. Sync your Figma Variables and Styles with a Specify Repository

• Access your Figma file which includes the Variables and/or Styles you would like to sync to Specify

• Download ↗ the Specify Widget in the Figma file which includes your Variables and/or Styles. Or update the widget if you already have it. To update the Specify Widget you have to disconnect it, remove the entire frame in all of your Figma files, and reopen the latest version of the Widget.

2. Connect your Specify account

1. Follow the steps in the widget to connect your account. You will need to create a personal access token and you will need to add the link to the Figma file to which the widget is added. Watch tutorial ↗

2. Click "Connect"

3. Choose Advanced Repository

3. Create a repository in Specify

1. Go to your Specify workspace

2. Click on "Create repository"

3. Choose a name

4. Select "Advanced Repository" (Learn more ↗︎)

5. Click "Create repository"

4. Connect the Specify Repository in your Widget

1. Go back to your Figma file that includes the Variables and/or Styles

2. Click on "Create Source" in the Specify Widget

3. It will show you the local collections and styles that are detected

4. Select the design tokens format you want to collect from your Figma file. Learn More ↗︎

5. Select the Specify repository you want to sync with. You should be able to see the Repository you have just created in Specify (if not, reload the list).

6. Click "Save to Specify"

7. You will immediately see the repository listed with the latest syncing time

5. Sync updates variables and styles on the fly

Use the Sync button to update your Variables and/or Styles with Specify. Now you are ready to export your design tokens! 🎉

6. Check or delete your source inside the Specify interface

• You will see the category of design tokens that are synced on the left-hand side

• In the Sources section (left-hand menu), you will see your connection(s) and when the last sync between your Figma file and Specify repository has occurred.

• Delete your source by clicking on the 3 dots option menu in the source card.

You are in Control

The Specify SDK is here to give you more power and freedom toward design token code generation. Built on top of our newly released format (SDTF), this brand new tool will help you build custom solutions tailor-shaped to your design token workflow. In a few words, the SDK provides all the necessary pieces and architecture you will need to ensure that you are in control of your design tokens system delivery. Written in TypeScript, it can also be used in a JavaScript environment.

Leverage the most advanced design token format

By levering your design token graph, the SDK provides all the methods needed to manipulate and transform the data coming from Specify. Whether it is about filtering and renaming tokens, groups and collections, deleting modes in tokens or transforming your data into any languages. Based on the Specify engine and parsers technology, you'll benefit from their flexibility without any maintenance.

Built to suit your standards

The idea behind the SDK is also for you to have more freedom on the output. Meaning that if the current parser technology doesn't meet your standards entirely, you can add custom codes among the pipeline chain. Everything is executable locally so you are not tied to a vendor, which allows you to create your own dedicated delivery engine that follows your company standards.

Let's jump in!

Build for the CI/CD

Let's jump in!

Overview

The Parsers Engine is a set of APIs you interact with anytime you need to transform your design data - tokens & assets - from your repository token tree into pre-configured file outputs.

The Parsers Engine serves as the orchestrator for a series of functions, called Parsers designed to transform design data, in parallel and/or chained. By configuring Parser Rules, you customize how and where design tokens and assets are exported.

The Parsers Engine can operate both remotely, using the Pipe Engine API over HTTP, and locally, through the Specify SDK. This dual capability enables it to be integrated into various workflows, offering flexibility whether working from remote servers, custom CI or directly within local development environments.

The Parsers Engine relies on the Parsers functions, which are actual converter implementations from the SDTF tokens to their representation in various formats and languages.

Parser Rules

As the medium to interact with the Parsers Engine, the parser rules are meant to be configured to follow your output needs.

A parser rule is simply a JSON object with two properties:

name: the name of the rule — we recommend setting up the purpose: CSS variables, Icons export...

parsers: an array of parser configuration

Parser Configuration

name: the name of the parser - to-json, to-tailwind over the parsers list.

output: an object describing the desired output type - can be optional when no output is expected.

options: an object of arbitrary keys and values defined by the parser - can be optional.

Example of a parser rule for a CSS custom properties output

{
  "rules": [
    {
      "name": "Generate tokens as CSS Custom Properties",
      "parsers": [
        {
          "name": "to-css-custom-properties", // parser name
          "output": {
            "type": "file",
            "filePath": "public/css/tokens.css" // ouput will be a file
          },
          "options": { // parser specific options
            "tokenNameTemplate": "--{{groups}}-{{token}}",
            "selectorTemplate": "[data-theme=\"{{mode}}\"]"
          }
        }
      ]
    }
  ]
}

Parser rules templates

Remote execution

Executed over HTTP, the parser rules are sent over to Specify servers to evaluate, transform and return the structured result.

All destinations are compatible with the remote execution.

For some destinations, like Github & the Specify CLI you need a Configuration file in order to keep track of your desired settings.

Configuration file

A Specify configuration file allows you to:

• Define the repository source from which to fetch design data.

• Provide a personal access token as authentication credentials for your user.

• Describe the parsers rule(s) to configure your ouput.

By default the file is named .specifyrc.js or .specifyrc.json

Local execution

Executed on the local environment, the parser rules are evaluated by the Specify SDK.

Only the generation parsers are meant to be used in a local execution. In fact, you can apply any mutation on your token tree using the SDTFClient API, before generating the final output.

Once executed, the parsers pipeline yields the result back to the SDK instance.

The Parsers functions

Parsers play a pivotal role. They are functions acting as interpreters and transformers of design tokens. They process the initial token tree and apply a set of transformations toward the expected output. Each parser, whether it pertains to utilities or generation, contributes to the workflow by either mutating the token tree or generating tangible assets and code snippets respectively.

Utility parsers

Utility parsers mutate the design token tree, through dedicated functions like filter, convert-color, change-case…

You configure their options property to instruct the changes to apply to your token tree before it get passed to the next step.

Generation parsers

Code generation parsers generate one or several outputs like CSS, JavaScript, TypeScript or assets like SVGs or bitmaps.

You configure their output property to produce the files that will end up in your codebase.

The options property is also available for most of the generation parsers.

Access raw data

Using the Specify HTTP API, you access the most barebone data directly out of our generation services. Thus, you can fetch your design tokens, manipulate them programmatically, and integrate them smoothly into any development workflow.

Work with any language

Your project cannot support JavaScript or TypeScript? Bring your own language and integrate seamlessly with Specify resources.

Generate upon request

Get started

To use the HTTP API, you'll need:

• A Specify account with at least one repository, filled with design data from any source.

Introduction

Overview

The Specify Client API

The Specify Client manages:

• your authentication credentials - personal access token

• your access to your organization repositories

The SDTF Client API

The SDTF Client bridges the gap between the raw token tree stored into your repository - in Specify database - and the live token tree instance provided by the SDK.

Mutate the token tree locally

Since the client is instantiated locally, all changes made to the token tree are only affecting the current version of the client.

Then, create several updates:

Convert tokens to XXX

The Specify platform is based on the following pillars.

• Organization

• Repository

• Source

• Destination

Above them, sit the engines:

• The Parsers Engine, accessible via all destinations, offers an high level abstraction to directly transform any SDTF token tree into many well-known technologies like CSS, tailwind, style-dictionary…

• The SDTF Client, accessible via the SDK, offers a fine grained control over your SDTF token tree by allowing any mutation and post-process hooks, directly in your codebase.

Organization

As a Specify user, you belong to an organization.

In this organization, you create repositories to structure your projects.

Repository

The repository is where the design data get stored, merged and eventually deleted over iterations.

A repository is exactly one design token tree built with the Specify Design Token Format.

Source

A source belongs to a Repository, it represents where the original design data come from - think of Figma (Variables or Local Styles) or Tokens Studio.

You can add many sources into a single repository. Read more about the available Sources compatible with Specify.

Collecting the design data

Once a source is configured, Specify starts to collect your design data. Over this process, the SDTF Engine acquires, validates and converts the original data into a SDTF token tree that get stored within the repository.

From this point on, you can synchronize your source(s) with Specify anytime, at a click of a button.

Repository with many sources

Data from many sources get automatically merged into a consolidated SDTF token tree. If Specify detects a conflict over sources, it will refuse to synchronize the first source that cause the conflict and turn it into an error state.

Destination

A destination belongs to a Repository, it represents where the formatted design data get distributed on updates - think of GitHub or any automation you can come up with our CLI and SDK.

You can add many destinations into a single repository. Read more about the available Destinations compatible with Specify.

Distributing the design data

While the source part is highly automated and managed by Specify internals, the destination offers many levers of control over the transformation required to meet your company standards.

Two main APIs at stake here:

• The Parsers Engine, accessible via all destinations, offers an high level abstraction to directly transform any SDTF token tree into many well-known technologies like CSS, tailwind, style-dictionary…

• The SDTF Client, accessible via the SDK, offers a fine grained control over your SDTF token tree by allowing any mutation and post-process hooks, directly in your codebase.

Automatic Installation

If you are on OS X or Linux, you can use the automated downloader, which will fetch the latest release version for you and install it:

curl -sL https://static.specifyapp.com/cli/install.sh | sh

To install a specific version, use the flag VERSION:

curl -sL https://static.specifyapp.com/cli/install.sh | VERSION="x.y.z" sh

Installation via JS ecosystem

npm install -D @specifyapp/cli

yarn install -D @specifyapp/cli

pnpm install @specifyapp/cli -D

bun add @specifyapp/cli --dev

Installation via Homebrew

Coming soon

Installation via Scoop

Coming soon

Introduction

The SDTF Engine brings together the core APIs that enable most of Specify features to seamlessly integrate, whether you're working in Figma or Token Studio, managing GitHub pull-requests, or directly within your codebase with the SDK or the CLI.

Token Tree CRUD API

At the core of the SDTF Engine, the query and mutation methods.

Query

The SDTF Engine provides a set of built-in getter functions to access tokens, groups, collections and aliases over the loaded token tree.

Mutation

The SDTF Engine provides a set of built-in mutation functions to locally manipulate the underlaying token tree in order to meet your project and/or company standards.

SDTF Query Language

Elevating your control over the data, the SDTF Query Language offers sophisticated techniques to navigate and cherry-pick the token tree with precision. You will find functions that allow complex querying patterns, matching specific criteria and conditions, vital for advanced manipulation and data extraction tasks.

With this powerful language at your disposal, it becomes easy to implement custom scenarios and data transformations.

Stateful Value API

The Stateful Value API grants direct access to examine the values assigned to tokens.

Through an exhaustive map interface, the API simplifies the process of keeping your design tokens and their implementations in sync despite the creation of aliases along the way.

Otherwise, if you're here to learn how to use the CLI, you're at the right place!

Environment variable (recommended)

You can use the environment variable named SPECIFY_PAT

Flag

If you prefer a flag, you can use --personal-access-token or -p

Configuration file (not recommended)

You can also write the personal access token directly in the config file.

If multiple credentials are used together, Specify will choose following this order:

1. the flag

2. the configuration file

3. the environment variable

The Specify CLI can be configured by default with a configuration file named .specifyrc.json . You can also override these settings from command line parameters.

The configuration file lets you describe your transformation pipelines (aka Parser Rule) following the Parser Engine API to generate your output. The configuration file 101 guide provides full documentation of the configuration file API.

Example: Export All Tokens and Assets In JSON

SPECIFY_PAT=xxxxxxxxxxxxxxxxxx specify pull \
    -C "my-custom-config.json" \
    -r "<@your-organization/your-repository-name>"

{
  "version": "2",
  "rules": [
    {
      "name": "Export All Tokens and Assets In a JSON File In SDTF",
      "parsers": [
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "sdtf.json"
          }
        }
      ]
    }
  ]
}

This page is the starting point of multiple guides that will help you to learn how to use our SDK. If you still don't know what our SDK is, you can have a look right here.

If you're not sure if you should use the Specify CLI or the Specify SDK, you can have a look to this comparison.

Otherwise, if you're here to learn how to use the SDK, you're at the right place!

Prerequisites

• NodeJS >= 18.x

• [Optional] Typescript >= 4.9

TypeScript vs JavaScript

We recommend using TypeScript for a better developer experience. TypeScript's autocompletion in your editor can save you numerous trips to the documentation by suggesting methods and options from the Specify APIs.

Installation

Let's pretend you have a front-end application structured as follows:

Create a specify directory

You'll start by creating a specify directory at the application level.

Initialize a JavaScript module

Using your terminal, navigate to the directory.

Within this directory, you initialize a JavaScript module by using the package manager of your choice - preferably the one you use to manage your application.

The init command creates a minimal package.json file where the dev dependencies will be added too. Then, you complete/override the content to match the following:

Setup TypeScript

Within the specify directory, you create a tsconfig.json file which matches the following configuration:

Prepare the environment secrets

Thus, create a .env file within the specify directory:

Create a Specify Client

Within the specify directory, you create an extract.ts file. This TypeScript script will handle the extraction process by utilizing the personal access token specified in your .env file.

Authenticate

In order to consume the private data from a Specify repository, you must authenticate using your personal access token stored in .env.

Test your script

From your terminal, launch the script.

You should get a log such as:

List your organization repositories

Get a list of repositories belonging to your organization.

One of the benefits to work directly with the SDK is that you can update the tokens value on the fly to match exactly your needs. Before explaining you how to do it, it's important that you note that updating tokens won't run a remote update in your repository.

Importing the updaters

Before even updating the tokens, we need to import the updaters that will help us to perform the updates. Everything is grouped inside the updaters object:

import { updaters } from '@specifyapp/sdk'

Update the colors

If you need to have your colors to be converted to a specific format, you can use the prebuilt color updater:

import { updaters } from '@specifyapp/sdk'

sdtfClient.update(updaters.color({ toFormat: 'hex' }, { where: { token: '^color-' }}))

You can refer to the spec to see all the available colors.

Update the token's name casing

If you need to have your token's name to be formatted in a specify way: camelCase, snakeCase, etc... You can use the changeCase updater:

import { updaters } from '@specifyapp/sdk'

sdtfClient.update(updaters.changeCase({ toFormat: 'kebabCase' }, { where: { token: '.*' }}))

You can refer to the spec to see all the available casing.

Update the dimensions

If you need to have your dimensions to be converted to a specific format, you can use the prebuilt dimension updater:

import { updaters } from '@specifyapp/sdk'

sdtfClient.update(updaters.dimension(
  { toFormat: 'rem', baseValue: { rem: 12 } }, 
  { where: { token: '^spacing-' }}
)

You can refer to the spec to see all the available units.

Executing multiple updates

The update method actually takes as much parameter as you want, so you can do the following:

import { updaters } from '@specifyapp/sdk'

sdtfClient.update(
  updaters.dimension(
    { toFormat: 'rem', baseValue: { rem: 12 } }, 
    { where: { token: '^spcacing-' }}
   ),
   updaters.nameCase({ toFormat: 'kebabCase' }, { where: { token: '.*' }}),
   updaters.color({ toFormat: 'hex' }, { where: { token: '^color-' }})
)

Avoid query repetition

If you want to perform multiple updates with the same query, it can quickly become quite verbose. To avoid it, you can use the withQuery method:

import { updaters } from '@specifyapp/sdk'

sdtfClient
  .withQuery({ where: { token: '*' }})
  .update(
    updaters.dimension(
      { toFormat: 'rem', baseValue: { rem: 12 } }, 
    ),
    updaters.nameCase({ toFormat: 'kebabCase' }),
    updaters.color({ toFormat: 'hex' })
   )

Creating your custom updater

An updater is in reality a function that looks like this:

import type { SDTFQuery, SDTFEngine } from '@specifyapp/specify-design-token-format'

function myUpdater(
  options?: {}
  applyTo?: SDTFQuery,
): Updater {
  return (engine: SDTFEngine, applyToInner?: SDTFQuery) => {
    const query = applyTo ?? applyToInner;

    // Do the conversion
  };
}

So if you want to create a custom updater, feel free to copy/paste the above function and implement it the way you want. You can refer to the SDTF Engine to understand how to perform updates on the SDTF.

If you're wondering why there's 2 applyTo, it's because the first one is the one that you're passing when calling the function, and the second one is passed if the updater is called with withQuery.

Once implemented, you can use it the same way we're using the updaters above:

sdtfClient.update(myUpdater())

The above implementation works for a reusable updater, but if you exactly know what you want, you can do the following as well:

import type { SDTFEngine } from '@specifyapp/specify-design-token-format'

function myUpdater(engine: SDTFEngine) {
    // Do something
}

sdtf.update(myUpdater)

Introduction

The Specify Design Token Format (SDTF) is a JSON based notation made to capture the architecture of information of design tokens regardless of its source. Supporting 50+ token types, the SDTF allows to compose the most complex types by referencing/aliasing others. Its primary focus is compatibility among design (system) tools and the frontend technologies used to build design systems.

In Specify, each repository is home to one SDTF token tree.

JSON Tree Structure

With the SDTF, you organize design tokens as a regular JSON tree with some remarkable signatures such as token, group and collection.

With groups and collections, you create sets of tokens to convey meaning like color.primary where color is the group and where my primary is a token, nested in color.

There is no technical limitation to the level of nesting you can achieve, yet good practices would drive the usage to a couple or so.

Tree node (token, group, collection)

A tree node is any of token, group or collection that live within a SDTF token tree.

Naming

Token, group and collection names are free to use any character except the following:

• . (dot/period) used for aliasing

• $ reserved for SDTF

Common properties

Any group, collection or design token can hold extra properties:

• $description a string aimed to complement the name.

• $extensions a JSON object to complement the value for a given provider.

Note on $extensions

Tree path

The tree path is the unique identifier of a tree node within the token tree. It is formed from the enumeration of the node's parent names.

In the following example, the token base is nested into the spacing group. Thus, its path is ['spacing', 'base'] or "spacing.base".

Representations

Among the Specify APIs, you'll find 2 path representations.

• the string based representation concatenates the path with . (dot/period) . Mainly used for aliasing. Giving for our previous example "spacing.base".

• the array based representation with an array of string, where each item is the name of a tree node. Mainly used for working with the SDTF Engine. Giving for our previous example ['spacing', 'base'].

Design token

A design token represents the value of a design decision for all the possible modes you want to attach. It is defined by its $type and its corresponding $value, where the $value is a JSON object, Record<mode: string, value: any>, where the mode name is the key and holds to the actual value.

A design token can be placed anywhere within a group or a collection.

Token value

Value defines at least one mode

Any Token Value MUST define at least one mode.

Default mode, by convention, is: default such as $value: { default: ... }

Modes naming

Modes names are free to use any character except the following:

• . (dot/period) used for aliasing

• $ reserved for SDTF

Modes outside a collection

A token placed outside of a collection can define any mode as far as it defines at least one mode.

Modes inside a collection

A token placed inside of a collection must strictly define the modes allowed by the collection.

Aliasing (reference)

Within a design token value, we can declare { $alias: 'path.to.token' } to reference another token, thus avoiding information duplication.

You can alias tokens through three levels.

Top-level aliasing

You can alias an entire Token. Hence you also inherit from its modes.

Note that $mode does not apply here.

Mode-level aliasing

You can alias on one or many modes of a Token. The value resolution will follow the indicated target $mode.

Note that $mode is mandatory

Value-level aliasing

You can alias on (almost) all sub-values composing the SDTF. The value resolution will follow the indicated target $mode.

Note that $mode is mandatory

Aliasing validation

Aliases must reference compatible Tokens. Each type has a unique mapping to other types defining which ones can be referenced at which place.

Supported types

The SDTF defines a large variety of token types in order to capture (almost) any design decision.

• bitmap

• blur

• border

• breakpoint

• color

• dimension

• duration

• font

• gradient

• gradients

• opacity

• radius

• radii

• shadow

• shadows

• spacing

• spacings

• textStyle

• transition

• vector

• zIndex

Group

A group is meant to order and nest design tokens semantically, it can be placed in any parent group or collection.

A group is a simple JSON object that can contain none to many groups, collections or tokens. With no mandatory keys or children, a group can be empty and represented as an empty object {}.

Collection

A collection is a special kind of group defining a mandatory $collection property. It constrain any enclosed token to respect a given set of modes.

A Collection can be placed within any group, nested at any level. But a Collection cannot be nested within another Collection.

$collection property

The $collection property is an object strictly containing the $modes key.

The $modes property is an array of mode names (string) defining the allowed modes for any token within the collection.

When it comes to generate code from your SDTF client with the SDK, you can leverage Specify's built-in parsers and / or add your own custom implementation.

The SDK provides two main methods to face either the need of the flexibility or increased performance.

By default, the generation is run locally utilizing the host machine resources. To meet some environment limitation, any Specify's built-in parser can be executed remotely, on Specify servers.

Create parsers pipelines

With your SDTF client, you can create as many parsers pipelines as you need to generate your outputs.

import { parsers } from "@specifyapp/sdk";

const executePipelines = sdtfClient.createParsersPipelines(
  parsers.toTailwind({ output: { type: "file", filePath: "./tailwind.theme.js" } })
);

The executePipelines is an asynchronous function that will actually execute the generation. Hence:

const results = await executePipelines();

results.debug();

The results is a ParsersEngineResults instance, which comes with its own set of helper methods to work with the outputs and messages issued over the generation.

Write the outputs to the file system

While being executed, the parsers engine produces outputs that gets returned within the ParsersEngineResults instance which comes with few helper methods like writeToDisk

// ...
const results = await executePipelines();

const report = await results.writeToDisk('./public');

writeToDisk takes an optional base path and returns a promise containing a report of the written files and errors if any.

Run many concurrent parsers pipelines

All parsers pipelines passed to createParsersPipelines are run concurrently out of the box. It means, you can write the following:

import { parsers } from "@specifyapp/sdk";

const results = await sdtfClient.createParsersPipelines(
  parsers.toTailwind({ output: { type: "file", filePath: "./tailwind.theme.js" } }),
  parsers.toJsonList({ output: { type: 'file', filePath: 'tokens-list.json' } })
)()

And have both pipelines executed concurrently from the same initial token tree.

Chain parsers to run specific pre-generation

In some cases, you need to chain the parser functions to act like A -> B -> C where you are only interested in C. For that matter, you can leverage the chainParserFunctions util.

import { parsers, chainParserFunctions } from "@specifyapp/sdk";

const results = await sdtfClient.createParsersPipelines(
  chainParserFunctions(
    svgo({ options: { svgo: { ... }}}),
    svgToJsx({ output: { type: 'directory', directoryPath: 'icons' } })
  )
)()

In this example, we want to optimize the content of the vector tokens with SVGO, and then, generate JSX components.

Execute a built-in parser function remotely

In some cases, you might need to deal with few host machine resources (like in many CI). To help with this, any Specify's built-in generation parser can be executed remotely by passing the shouldExecuteRemotely: true option.

import { parsers, chainParserFunctions } from "@specifyapp/sdk";

const results = await sdtfClient.createParsersPipelines(
  svgo({
    options: {
      shouldExecuteRemotely: true,
      svgo: { ... }
    },
    output: { type: 'directory', directoryPath: 'icons' }
  }),
)()

Doing so, the SVGO process will be run on Specify's servers and the results will be returned to the SDK to be further processed / written on disk.

Create pipelines from parser rules configuration

A Parser rule is a JSON object representing a parsers pipeline where all parsers will be run sequencially. Rules configuration are primarily utilized within the configuration file for the CLI or GitHub.

With the SDK, the use of parser rules configuration reduces the interoperability with custom code, but can significantly increase the speed of a remote execution.

In order to build parsers pipelines from the SDTF client we need to call the createParsersPipelinesFromRules method.

const executePipelines = await sdtfClient.createParsersPipelinesFromRules({
  name: 'Icons to JSX',
  parsers: [
    {
      name: 'svgo',
      options: { svgo: { ... } },
    },
    {
      name: 'svg-to-jsx',
      output: { type: 'directory', directoryPath: 'icons' },
    },
  ],
});

Doing so, it creates an async parsers engine executor in the exact same manner it did for parser functions.

Run faster remote executions

Any built-in generation parser holds a shouldExecuteRemotely: boolean option to treat its inner execution as remote.

Yet, rules configuration also implement that option, allowing the SDK to collect all the remote rules and parsers, then sends out a single HTTP request for the whole execution.

const executePipelines = await sdtfClient.createParsersPipelinesFromRules({
  name: 'Icons to JSX',
  shouldExecuteRemotely: true,
  parsers: [ ... ],
});

Create your custom parser function

If the parsers that Specify is providing are not enough for your use case, you can create your own parser function!

Now that we are able to execute parsers locally, it means that parsers are simple functions, so creating a custom parser is only about writing a function. But before creating your own parser, you have to understand how a parser is working.

The anatomy of a parser

A parser is a function that will take 3 parameters:

1. An input will be one of the type of ParsersEngineDataBox :

   1. SDTFEngineDataBox: { type: 'SDTF Engine'; engine: SDTFEngine; }

   2. SDTFDataBox: { type: 'SDTF'; graph: SpecifyDesignTokenFormat; }

   3. JSONDataBox: { type: 'JSON'; json: Record<string, unknown>; }

   4. SVGDataBox: { type: 'SVG'; svg: Array<{ ... }> }

   5. UrlDataBox: { type: 'urls'; files: Array<{...}> }

   6. BitmapDataBox: { type: 'bitmap'; files: Array<{...}> }

   7. CustomDataBox: { type: 'custom'; custom: unknown }

2. The ParserToolbox, which helps accumulate the output that will be written to your file system

An important thing to understand is that a parser has 2 outputs:

1. The return type of the function, that can be passed to another parser if chained

2. The output that you want to write to the file system (files, text, JSON, SDTF), and that'll be accumulated into the ParserToolbox

There's actually 2 reasons for this choice:

1. There's only 1 return value, but you can append as much output as you want to an accumulator

2. We need a difference between the output of a parser, and what we want to send to the next parser

Let's have a look to the output in itself.

The parser output

First, let's focus on the return. The output will be the input of the next parser if you use it inside a ParserChainer. So as the return is the input of the next parser, you probably guessed it: it's the same one for the input, which means one of ParsersEngineDataBox :

• SDTFEngineDataBox: { type: 'SDTF Engine'; engine: SDTFEngine; }

• SDTFDataBox: { type: 'SDTF'; graph: SpecifyDesignTokenFormat; }

• JSONDataBox: { type: 'JSON'; json: Record<string, unknown>; }

• SVGDataBox: { type: 'SVG'; svg: Array<{ ... }> }

• BitmapDataBox: { type: 'bitmap'; files: Array<{...}> }

• UrlDataBox: { type: 'urls'; files: Array<{...}> }

• CustomDataBox: { type: 'custom'; custom: unknown }

Now, let's see how we can output files. To do so, we need to push into the outputsAccumulator one of the types of the ParserOutput:

• TextOutput: { type: 'text'; text: string }

• SDTFOutput: { type: 'SDTF'; graph: SpecifyDesignTokenFormat }

• JSONOutput: { type: 'JSON'; graph: string }

• FilesOutput: { type: 'files'; files: Array<{ path: string; content: { type: 'text'; text: string; } | { type: 'url'; url: string; }}> }

Most of the parsers take an SDTFDataBox as an input, and return it as the output as they don't modify anything and only output some files. So if you're not sure about what to return, just return the input.

So now that we know what is a parser, let's have a look to an example of parser that create a file with all the token's name:

import { SpecifyDesignTokenFormat } from '@specifyapp/specify-design-token-format'
import { ParserToolbox, SDTFEngineDataBox } from '@specifyapp/sdk/bulk'

function parserName(
  input: SDTFEngineDataBox,
  toolbox: ParserToolbox,
) {
  const engine = input.engine;
  const names = engine
    .query
    .getAllTokenStates()
    .map(tokenState => tokenState.name);
  
 toolbox.populateOutput(
   {
     type: 'files',
     files: [{ path: 'names.txt', content: { type: 'text', text: names.join('\n') } }] 
   }
 )
 
 return input
}

Let's break down the example:

1. We use the engine to get all the names

const names = tokenTreeClient
  .engine
  .query
  .getAllTokenStates()
  .map(tokenState => tokenState.name);

1. We populate the output into the accumulator

toolbox.populateOutput(
  {
    type: 'files',
     files: [{ path: 'names.txt', content: { type: 'text', text: names.join('\n') } }] 
  }
)

1. Finally, we return the input as we didn't modify anything and don't need to return something else

return input

Now that we have our custom parser, we can use it freely in the ParserPipeline or ParserChainer.

If your goal is to create your own output, you'll have to go through 2 steps:

• Converting the tokens to the desired output, e.g: CSS, Js, Swift, etc...

• Formatting the converted tokens into the desired template

We can't know what's the perfect template for your needs, but we can definitely help you converting tokens to your desired output. That's why we created the converters.

What's a converter?

A converter is a function that takes a resolvable alias strategy, an unresolvable alias strategy, and returns a function that takes a TokenState and will convert it to any available format. This is the way to build your custom output with the SDK. We provide you the conversion, and you only have to format it the way you want. Here is an example:

import {
  dimensionToCss,
  breakpointToCss,
  textStyleToCss,
  createResolveAliasStrategy 
} from '@specify/sdk/css'

const strategy = createResolveAliasStrategy()

const output = tokenState.matchByType(
  {
    dimension: dimensionToCss(strategy),
    breakpoint: breakpointToCss(strategy),
    textStyle: textStyleToCss(strategy)
  }, 
  _ => undefined
)

This is as straightforward as it looks, but you're probably wondering what is the strategy const.

The alias strategies

Let's focus on what are the strategies. When working with the SDTF, you are probably aware that a token can contains an alias at a top level, mode level, or value level. When converting a token, we need to decide what we want to do with the aliases. In the case of resolvable aliases, there will be generally 2 strategies:

• Resolve the alias to retrieve the value and use the value as is

• If the target language supports it, convert the alias itself to a variable, alias, etc... Although it may sounds simple, the reality is that there's a lot of pitfalls, especially when trying to work with the aliases without resolving them. This is the reason why we provide premade strategies, so you don't have to go through all the pain of implementing it.

Note that there is strategies both for resolvable and unresolvable aliases. Generally speaking, the recommended way to work with a token is the following:

import { dimensionToCss } from '@specify/sdk/css'

if (!tokenState.isFullyResolvable) {
  return
}

const strategy = createResolveAliasStrategy()

tokenState.matchByType(
  {
    dimension: dimensionToCss(strategy)
  }, 
  _ => undefined
)

The most important here are the first lines. If the token is not fully resolvable, we just ignore it, and you should do it this way as much as possible. Working with unresolvable aliases is not really desirable, so it's better to just avoid doing it. That's why the default unresolvable alias strategy is to throw an error, and checking if the token is fully resolvable or not is enough to make sure you'll avoid a lot of problems.

Using a strategy

Let's take CSS as example, and compare the output of various strategies.

Resolve alias strategy

This strategy will resolve the token in order to retrieve the value and convert it to CSS:

const strategy = createResolveAliasStrategy()

// Token value: [{ value: 12, unit: 'px'}, { $alias: 'mySpacing', $mode: 'default' }]
tokenState.matchByType(
  {
    spacings: spacingsToCss(strategy) // -> 12px 24px
  }, 
  _ => undefined
)

Alias to var strategy

Because CSS supports the aliasing through the var(...) notation, we can rely on it to convert our aliases to a CSS variable:

const strategy = createAliasToVarStrategy({ tokenNotInCollectionNameTemplate: '--{{token}}}' })

// Token value: [{ value: 12, unit: 'px'}, { $alias: 'mySpacing', $mode: 'default' }]
tokenState.matchByType(
  {
    spacings: spacingsToCss(strategy) // -> 12px var(--mySpacing)
  }, 
  _ => undefined
)

Throw on unresolvable strategy

This strategy is the default one for the unresolvable aliases. As the name is saying it, It'll throw an error if we encounter an unresolvable alias during the conversion:

const resolvableStrategy = createResolveAliasStrategy()
const unresolvableStrategy = createThrowOnUnresolvableStrategy()

// Token value: [{ value: 12, unit: 'px'}, { $alias: 'wrong.token', $mode: 'default' }]
tokenState.matchByType(
  {
    // -> Error: 'wrong.token' is unresolvable
    spacings: spacingsToCss(resolvableStrategy, unresolvableStrategy)
  }, 
  _ => undefined
)

Note that this strategy is the default one, so you don't need to pass anything.

Ignore unresolvable strategy

This strategy is ignoring all the unresolvable aliases if it finds one, which mean that it'll return undefined instead.

const resolvableStrategy = createResolveAliasStrategy()
const unresolvableStrategy = createIgnoreUnresolvableStrategy()

// Token value: [{ value: 12, unit: 'px'}, { $alias: 'wrong.token', $mode: 'default' }]
tokenState.matchByType(
  {
    // -> 12px undefined
    spacings: spacingsToCss(resolvableStrategy, unresolvableStrategy)
  }, 
  _ => undefined
)

Unresolvable alias to variable

This strategy is actually quite special. It'll convert unresolvable aliases to a CSS variable. Even if an alias is unresolvable, we still have a lot of informations on the target based on the path, mode, and the token referencing the alias.

const resolvableStrategy = createResolveAliasStrategy()
const unresolvableStrategy = createUnresolvableAliasToVarStrategy({
  tokenNotInCollectionNameTemplate: '--{{token}}'
})

// Token value: [{ value: 12, unit: 'px'}, { $alias: 'wrong.token', $mode: 'default' }]
tokenState.matchByType(
  {
    // -> 12px var(--wrong-token)
    spacings: spacingsToCss(resolvableStrategy, unresolvableStrategy)
  }, 
  _ => undefined
)

Note that top level aliases lacks to much informations, so if this strategy encounter one, it'll throw an error.

Create your own strategy

If the provided strategies don't satisfy you, you can still decide to create your own strategy! In the case of a resolvable alias strategy, you'll have to create a function that follows this type:

type ResolvableAliasStrategy<
  Return, 
  Composites extends SpecifyDesignTokenTypeName
> = <
  Alias extends AllResolvableAlias = AllResolvableAlias,
>(
  alias: Alias,
) => Alias extends ResolvableTopLevelAlias
  ? {
      [mode: string]: Alias extends AllResolvableAlias<Composites>
        ? Record<string, Return>
        : Return;
    }
  : Alias extends AllResolvableAlias<Composites>
    ? Record<string, Return>
    : Return;

Let's breakdown the signature:

• Return is the desired return type for your strategy. Generally it'll be the same than the converters

• Composites is a union of the types of the composites tokens. Those tokens are expected to be converted to a Record<string, Return> as they have multiple outputs

• About the Alias, it's a generic that will be one of these:

type AllResolvableAlias<
  Type extends SpecifyDesignTokenTypeName = SpecifyDesignTokenTypeName,
> =
  | ResolvableValueLevelAlias<Type>
  | ResolvableModeLevelAlias<Type>
  | ResolvableTopLevelAlias<Type>;

Finally, you can notice that in the case of a top level alias, you need to return an object containing the modes, and then the return value.

Here is an example of the CSS resolvable alias strategy:

type CssResolvableAliasStrategy = ResolvableAliasStrategy<
  string,
  'font' | 'textStyle' | 'transition'
>;

We expect the return type to be a string, and the tokens font, textStyle and transition to return multiple values, thus, a Record<string, string>.

In general, you'll probably don't want to work with ResolvableAliasStrategy, but rather with the converter strategy, e.g: CssResolvableAliasStrategy. Here is an example of an implementation:

import {
  ResolvableValueLevelAlias,
  ResolvableModeLevelAlias,
  ResolvableTopLevelAlias
} from '@specify/specify-design-token-format'
import { CssResolvableAliasStrategy } from '@specifyapp/sdk/css'

const myCustomStrategy: CssResolvableAliasStrategy = (alias) => {
  if (alias instanceof ResolvableTopLevelAlias) {
    ...
  } else if (alias instanceof ResolvableModeLevelAlias) {
    ...
  } else {
    ...
  }
}

tokenState.matchByType({
  dimension: dimensionToCss(myCustomStrategy)
}, _ => undefined)

The output of a converter

Primitives tokens

Primitives tokens are generally quite straightforward to convert to a different output. So almost every time, the output of a primitive token will be a single output. Here is an example with a dimension token converted to CSS:

Input:

{
    value: 12,
    unit: "px"
}

Output:

"12px"

Composites tokens

Composites tokens are a bit more complex than the simples ones. The main issue is that they contain a lot of informations, and most of the time we need multiple outputs to convert all the data. To do so, a converted composites token will output an object containing all the outputs. Here is an example with a transition token that we convert to a CSS output.

Input:

{
  duration: {
    value: 12,
    unit: 's',
  },
  delay: {
    value: 0,
    unit: 'ms',
  },
  timingFunction: [0.1, 0.2, 0.1, 0.4]
}

Output:

{
  delay: "12s",
  duration: "0ms",
  "timing-function": "cubic-bezier(0.1, 0.2, 0.1, 0.4)"
}

In the case of a transition, we can't assume on which property the transition will be applied, so we have to split everything in different tokens so you can build your transition on the property that you want.

If you want more informations on which tokens are primitives and which ones are composites, and on the inputs and outputs, you can have a look to the reference of each converters:

• CSS

Get a SDTFClient

The SDTFClient is a class providing numerous methods to work with the design data stored using the Specify Design Token Format (SDTF).

It's the way of interacting with your tokens and generating content.

// Fetch a Repository
const SPECIFY_REPOSITORY_NAME = "MY-REPOSITORY-NAME";
const sdtfClient = await specifyClient.getSDTFClientByRepositoryName(
  SPECIFY_REPOSITORY_NAME,
);

console.log(`Fetched repository: ${sdtfClient.repository.name}`);

Get the SDTF JSON token tree

You would want to grab the SDTF JSON token tree of a repository anytime you want to: send the token tree over the network or debug an intermediate manipulation.

const jsonTokenTree = sdtfClient.getJSONTokenTree();

console.log(jsonTokenTree) // the object literal representation of the Specify Design Token data

Now that we know how to retrieve our SDTF, let's see how we can manipulate and retrieve our tokens.

Retrieving the tokens

There's multiple way to retrieve a token. If you want to work with a specific one you'll probably want to only get one, if you're developing a generic solution, you'll probably prefer iterating over many tokens. Let's have a look on how to do this.

Retrieving a single token

To retrieve a single token, you can just pick it by its path:

const tokenState = sdtfClient.getTokenState(['path', 'to', 'token'])

Retrieving all the tokens

Tokens

const tokens = sdtfClient.getAllTokenStates()

Groups

const groups = sdtfClient.getAllGroupStates()

Collections

const collections = sdtfClient.getAllCollectionStates()

Retrieving specific tokens

If you need specifically some tokens, for example, based on the name, type, path, etc... You can perform a query and map over the results:

const results = sdtfClient
  .mapQueryResults(
    { where: { collection: '^My Collection$', select: true, children: { tokens: true } } },
    (treeNodeState, engine, queryResult) => {
      if (treeNodeState.isCollection) {
        return treeNodeState.name
      }
      
      if (treeNodeState.isToken) {
        return treeNodeState.stringPath
      }
      
      return undefined
    },
  );

Or, you can only iterate over the results of your query if you need to perform mutations for example:

sdtfClient
  .forEachQueryResult(
    { where: { token: '.*', select: true } },
    (treeNodeState, engine, queryResult) => {
      if (treeNodeState.isToken) {
        engine.mutation.renameToken({
          atPath: treeNodeState.path,
          name: treeNodeState.name.toLowerCase(),
        });
      }
    },
  );

The token architecture

The TokenState instance will be your main access to your tokens. Through this, you can retrieve your token data or perform updates. But first, let’s put some context and try to figure out what this TokenState is trying to solve.

If we take a look at the token representation in the SDTF, it’s basically a JSON value where a lot of keys can be an alias rather than a value. Let’s have a look at all the possible cases with an example. Note that the following examples are 4 different ways of achieving the same result from a value point of view.

A basic token

{
  mySize: {
    $type: 'dimension',
    $value: {
      small: { unit: 'px', value: 12 },
      large: { unit: 'px', value: 24 },
    }
  }
}

An alias at the value level

{
  sizeValue: {
    $type: 'number',
    $value: {
      default: 12
    }
  },
  mySize: {
    $type: 'dimension',
    $value: {
      small: {
	unit: 'px',
	value: { $alias: 'sizeValue', $mode: 'default' }
      },
      large: {
	unit: 'px',
	value: 24
      },
    }
  }
}

An alias at the mode level

{
  anotherSize: {
    $type: 'dimension',
    $value: {
      customMode: {
	unit: 'px',
	value: 12
      }
    }
  },
  mySize: {
    $type: 'dimension',
    $value: {
      small: { $alias: 'anotherSize', $mode: 'customMode' },
      large: {
	unit: 'px',
	value: 24
      },
    }
  }
}

An alias at the top level

{
  anotherSize: {
    $type: 'dimension',
    $value: {
      small: {
	unit: 'px',
	value: 12
       },
       large: {
         unit: 'px',
	 value: 24
       },
    }
  },
  mySize: {
    $type: 'dimension',
    $value: { $alias: 'anotherSize' },
  }
}

As you can see, there’s a lot of way to express a token, and dealing with all the possible cases is quite difficult. That’s why one of the goal of the TokenState is to help you to deal with everything.

How to differentiate the tokens?

Before even thinking about retrieving the value of a token, we need to know what type of token we’re working with.

It’s actually quite easy to know as there’s a type property in the TokenState :

console.log('Token type:', tokenState.type) // Token type: <type>

But even if we know the type, a problem will remain: Typescript doesn’t. TokenState is quite a generic class as the default type is something that looks like this: TokenState<'dimension' | 'font' | 'breakpoint' | ...> .

So the first mission is to be able to narrow down the type to be able to work with it. To do so, there’s a pretty convenient function:

tokenState.matchByType(
  {
    // TokenState<'dimension'>
    dimension: (v) => { ... },
    // TokenState<'font'>
    font: (v) => { ... },
    // TokenState<'textStyle'>
    textStyle: (v) => { ... },
  },
  notMatched => { ... }
)

You can match as much type as you need, and if some are not matched, they’ll be caught by the callback in the 2nd argument.

If you're working with Typescript, you may face some type issues while using matchByType. A common example would be this:

tokenState.matchByType(
  {
    dimension: _ => 1,
    breakpoint: _ => 'hello',
  },
  _ => undefined,
)

If you copy/paste this code inside your editor, Typescript will complain and gives you the following error: Type '(_: TokenState<"breakpoint", Value, Mode>) => string' is not assignable to type '(token: TokenState<"breakpoint", Value, Mode>) => number | undefined'.

Basically Typescript is unhappy that we return a number and a string. To fix the issue, there's 2 solutions:

1. Return the same type:

tokenState.matchByType(
  {
    dimension: _ => 1.toString(),
    breakpoint: _ => 'hello',
  },
  _ => undefined,
)

1. Excplicitely set the return type:

tokenState.matchByType<string | number>(
  {
    dimension: _ => 1,
    breakpoint: _ => 'hello',
  },
  _ => undefined,
)

Depending on the use case, you'll prefer the first over the second solution, or the second over the first.

How to get the token value ?

Now that we know how to get the TokenState that we want, we want to extract the value from it. As mentioned before, a token can have a lot of places that can contains an alias, so when retrieving the value, there’s 2 ways of doing it.

Ignoring aliasing

If you only want to get the raw value of a token and ignore the aliases, you can use the following function:

tokenState.getJSONValue({
  resolveAliases: true,
  allowUnresolvable: false,
  targetMode: tokenState.modes[0],
})

Also, as combining matchByType and getJSONValue can become a bit heavy. For that case, you can use the following function:

tokenState.matchJSONValueByType(
  {
    // { unit: 'px', value: 12 }
    dimension: (v, mode) => { ... },
    // { family: 'MyFont', weight: 700, ... }
    font: (v, mode) => { ... },
    // { lineHeight: { unit: 'px', value: 24 }, ... }
    textStyle: (v, mode) => { ... },
  },
  notMatched => { ... }
)

Handling the aliases

Overview of the API

If you want to support the aliases in your output, you’ll need to handle them when they are some at the top level, mode level, or value level. To do so, we provide the Stateful Value API that helps you to make sure you handle all the possible cases. Let’s see an example and then break down everything.

// TokenState<'dimension'> -> { value: 12, unit: 'px' }
tokenState
  .getStatefulValueResult()
  .mapResolvableTopLevelAlias(alias => { ... })
  .mapUnresolvableTopLevelAlias(alias => { ... })
  .mapTopLevelValue(modeLevel =>
    modeLevel
      .mapResolvableModeLevelAlias((alias, mode) => { ... })
      .mapUnresolvableModeLevelAlias(_ => { ... })
      .mapRawValue((rawValue, mode) => 
        rawValue
	  .value
	  .mapPrimitiveValue(value => { ... })
	  .mapResolvableValueLevelAlias(alias => { ... })
	  .mapUnresolvableValueLevelAlias(alias => { ... })				
      )
      .unwrap(),
  )
  .unwrap();

Although this API is a bit verbose, it’ll make sure that you cannot miss a case. So, what’s happening?

When you retrieve the value of a token, we put it inside a StatefulResult , and it’ll expose the following type union at each level:

• Top level: ResolvableTopLevelAlias | UnresolvableTopLevelAlias | TopLevelValue

• Mode level: ResolvableModeLevelAlias | UnresolvableModeLevelAlias | RawValueSignature

• Value level: ResolvableValueLevelAlias | UnresolvableValueLevelAlias | string | number | ...

Each mapping function is dedicated to handling one case.

First, you’ll need to handle the top level:

tokenState
  .getStatefulValueResult()
  .mapResolvableTopLevelAlias(alias => { ... })
  .mapUnresolvableTopLevelAlias(alias => { ... })
  .mapTopLevelValue(modeLevel => { ... })
  .unwrap()

Note the unwrap at the end which is the way to extract the value.

Then you’ll want to handle the mode level:

.mapTopLevelValue(modeLevel =>
  modeLevel
    .mapResolvableModeLevelAlias((alias, mode) => { ... })
    .mapUnresolvableModeLevelAlias(_ => { ... })
    .mapRawValue((rawValue, mode) => { ... })
    .unwrap()

All you need to do for the mode level is to return a value, and it'll be mapped to the right mode.

And finally the value level (we take a dimension token as an example):

.mapRawValue((dimension, mode) => {
  const value = dimension
    .value
    // mapPrimitiveValue is not required if you only need the value inside
    // without updating it
    .mapPrimitiveValue(value => { ... })
    .mapUnresolvableValueLevelAlias(alias => { ... })
    .mapResolvableValueLevelAlias(alias => { ... })
    .unwrap()
    
    return value
})

As you can see each step is always the same: handling unresolvable alias, resolvable alias and the value.

Resolving an alias

Sometimes, you need to use the precision of the stateful result API, but don't want to deal with the aliases at some levels. To avoid doing so, you can resolve an alias by calling resolveDeepValue, and you'll be left with handling the unresolvable alias and value case. Here is an example:

tokenState
  .getStatefulValueResult()
  .resolveDeepValue()
  .mapUnresolvableTopLevelAlias(alias => ...)
  .mapTopLevelValue(modeLevel => 
    modeLevel
      .resolveDeepValue()
      .mapUnresolvableModeLevelAlias(alias => ...)
      .mapRawValue((dimension, mode) => 
        dimension
          .value
          .resolveDeepValue()
          .mapUnresolvableValueLevelAlias(alias => ...)
          .unwrap()
      )
      .unwrap()
  )
  .unwrap()

Handling only the value case

Although we could get rid of the resolvable alias case, handling the unresolvable case might still be too verbose. So let me introduce you to a nice pattern to only deal with values:

1. We will check if the token is fully resolvable

2. We'll use resolveDeepValue to remove the need of handling the resolvable aliases

3. We'll use unwrapValue to remove the need of handling the unresolvable case at the type level

if (!tokenState.isFullyResolvable) {
  return
}

const output = tokenState
  .getStatefulValueResult()
  .resolveDeepValue()
  .mapTopLevelValue(modeLevel => 
    modeLevel
      .resolveDeepValue()
      .mapRawValue((dimension, mode) => 
        dimension
          .value
          .resolveDeepValue()
          .unwrapValue()
      )
      .unwrapValue()
  )
  .unwrapValue()

Thanks to this pattern, we went from a really verbose API to something lighter.

Creating Specify and SDTF clients

You will first create a Specify client, then authenticate, then create a SDTF client by fetching the repository token tree.

import { createSpecifyClient } from "@specifyapp/sdk";

const specifyClient = createSpecifyClient();
await specifyClient.authenticate("<YOUR_PERSONAL_ACCESS_TOKEN_VAR>");

const sdtfClient = 
  await specifyClient.getSDTFClientByRepositoryName("<YOUR_SPECIFY_REPO_NAME>");
  
  console.log('Repository name',sdtfClient.repository.name)

Updating tokens

The following example is only an overview, if you need more details you can have a look here.

import { updaters } from '@specifyapp/sdk'

sdtfClient.update(
  updaters.color({ toFormat: 'hex' }, { where: { token: '^color-' }}),
);

Convert a token to XXX

The following example is only an overview, if you need more details you can have a look here.

import {
  dimensionToCss,
  breakpointToCss,
  colorToCss,
  createResolveAliasStrategy 
} from '@specify/sdk/css'

const strategy = createResolveAliasStrategy();

const outputs = sdtfClient.mapTokenStates(tokenState => 
  tokenState.matchByType(
    {
      dimension: dimensionToCss(strategy) // Output example: '12px'
      breakpoint: breakpointToCss(strategy) // Output example: '12px'
      color: colorToCss(strategy) // Output example: '#ff00ff'
    }, 
    _ => undefined
  )
);

Execute a parser

The following example is only an overview, if you need more details you can have a look here.

import { parsers } from '@specify/sdk'

const executePipelines = sdtfClient
  .createParsersPipelines(
    parsers.toCssCustomProperties({ filePath: 'myFile.css' }),
  );
const parsersEngineResults = await executePipelines();

Retrieving data

Get a specific token

const tokenState = sdtfClient.getTokenState(['path', 'to', 'token']);

Get all the tokens

const tokenStates = sdtfClient.getAllTokenStates();

Map over all the tokens

const results = sdtfClient.mapTokenStates(tokenState => ...);

Get a specific group

const group = sdtfClient.getGroupState(['path', 'to', 'myGroup']);

Get all the groups

const groups = sdtfClient.getAllGroupStates();

Map over all the groups

const results = sdtfClient.mapGroupStates(tokenState => ...);

Get a specific collection

const collection = sdtfClient.getCollectionState(['path', 'to', 'myCollection']);

Get all collections

const collections = sdtfClient.getAllCollectionStates();

Map over all the collections

const results = sdtfClient.mapCollectionStates(tokenState => ...);

Filtering data

Keeping a sub-graph from a path

If you only want a specific portion of the graph, you can cherry-pick using the pick function:

const colors = sdtfClient.pick(['colors']);

Keeping the children of a path

If you only want the children of a specific portion of the graph you can use the pick function this way:

const colors = sdtfClient.pick(['colors', '*']);

Query a specific set of data

You can use the query method of the SDTFClient to create a copy of the current SDTF with only the tokens that'll match your query:

const colorAndTextStyleOnlySdtf = sdtfClient.query({
  where: {
    token: '.*',
    withTypes: {
      include: ['color', 'textStyle']
    }
  }
});

You can find all the details about querying the data here.

Remove tokens from the SDTF

You can use the remove method to delete tokens based on a query:

sdtfClient
  .remove({ where: { token: '^Blue$', select: true } })

Renaming tokens

Rename a node

By not specifying any type, the method will rename any node as long as the path is valid.

sdtfClient.renameNode({ atPath: ['my', 'path' ], name: 'newName' });

Rename a collection

By specifying the type, the method will rename only a collection node.

sdtfClient.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'collection'
});

Rename a group

By specifying the type, the method will rename only a group node.

sdtf.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'group'
});

Rename a token

By specifying the type, the method will rename only a token node.

sdtf.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'token'
});

Introduction

Whenever you want to work with the GitHub or the Specify CLI destination, you need to create a Configuration file to instruct the Parsers Engine how to transform your design data, so it generate tokens that match your technical requirements.

A configuration file helps you:

1. request design tokens and assets from a Specify repository

2. transform them to fit your company standards thanks to parsers

Properties

A configuration is composed of 3 main properties:

• repository

• personalAccessToken

• rules

Repository

The name of the Specify repository you want to pull your design tokens and assets from.

Let's say we have the following repository in Specify called "all-design-data" located in the "@acme-inc" organization.

We target it like this:

module.exports = {
  version: '2'
  repository: '@acme-inc/all-design-data-v2',
  personalAccessToken: '<your-personal-access-token>',
  rules: [],
};

{
  "version": "2"
  "repository": "@acme-inc/all-design-data-v2",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

Personal Access Token

The Specify personalAccessToken used to authenticate you.

module.exports = {
  version: '2'
  repository: '@workspace/repository',
  personalAccessToken: '<your-personal-access-token>',
  rules: [],
};

{
  "version": "2"
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

Parser Rules

The Parsers Rules help you transform your design tokens and assets the way you want.

You can have as many rules as you want and you can have rules that transform several Token types at once.

Here are different kind of rules and parsers you can use to generate color tokens as CSS Custom Properties:

1. filter to target on a specific collection named "Colors" that contains our colors

2. convert-color to convert our colors in HSL

3. change-case to change the name of our tokens and modes to kebabCase

4. to-css-custom-properties to generate a CSS file containing our tokens

{
  version: '2',
  repository: '@organization/repository',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: 'css',
      parsers: [
        {
          name: 'filter',
          options: {
            query: {
              where: {
                collection: '^Colors$',
                select: {
                  children: true
                }
              }
            }
          }
        },
        {
          name: 'convert-color',
          options: {
            toFormat: 'hsl',
            applyTo: {
              collection: true
            }
          }
        },
        {
          name: 'change-case',
          options: {
            change: 'names',
            toCase: 'kebabCase',
            applyTo: {
              collection: true
            }
          }
        },
        {
          name: 'change-case',
          options: {
            change: 'modes',
            toCase: 'kebabCase',
            applyTo: {
              collection: true
            }
          }
        },
        {
          name: 'to-css-custom-properties',
          output: {
            type: 'file',
            filePath: 'tokens.css'
          },
        },
      ],
    },
  ],
};

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "css",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "collection": "Colors",
                "select": {
                  "parents": true,
                  "children": true
                }
              }
            }
          }
        },
        {
          "name": "convert-color",
          "options": {
            "toFormat": "hsl",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "change-case",
          "options": {
            "change": "names",
            "toCase": "kebabCase",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "change-case",
          "options": {
            "change": "modes",
            "toCase": "kebabCase",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "tokens.css"
          }
        }
      ]
    }
  ]
}