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.

getAllTokenStates, getChildrenOf, getParentsOf, getAliasReference… and many more - give you the opportunity to traverse and iterate over the different instances of TokenState, GroupState, and CollectionState.

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.

updateTokenModeValue, updateTokenValue, moveToken, addToken, deleteToken, renameToken… - assemble into a CRUD API giving you the control to bend your data just right for your use cases, without ever making changes to the original design data from the repository.

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.

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.

Interface

interface parser {
  name: 'select-modes';
  options: {
    modes: string[];
  };
}

Options

Interface

interface parser {
  name: 'to-sdtf';
  output:
    | { type: 'directory'; directoryPath: string }
    | { type: 'file'; filePath: string }
    | { type: 'SDTF' }
    | { type: 'text' }
    | { type: 'JSON'; filePath: string };
}

Basic usage

{
  "colors": {

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate tokens in JSON",
      "parsers": [
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "output/tokens.json"
          }
        }
      ]
    }
  ]
}

{
  "colors": {
    "$collection": {
      "$modes": [
        "light",
        "dark"
      ]
    },
    "Core": {
      "blue-100": {
        "$type": "color",
        "$value": {
          "dark": {
            "red": 229,
            "blue": 29,
            "alpha": 1,
            "green": 29,
            "model": "rgb"
          },
          "light": {
            "red": 255,
            "blue": 255,
            "alpha": 1,
            "green": 255,
            "model": "rgb"
          }
        },
        "$description": "token 1 aliased with n modes within collection within n groups"
      },
      "blue-700": {
        "$type": "color",
        "$value": {
          "dark": {
            "red": 229,
            "blue": 0,
            "alpha": 1,
            "green": 0,
            "model": "rgb"
          },
          "light": {
            "red": 255,
            "blue": 255,
            "alpha": 1,
            "green": 200,
            "model": "rgb"
          }
        },
        "$description": "token 2 aliased with n modes within collection within n groups"
      }
    },
    "semantic": {
      "background": {
        "button": {
          "primary": {
            "hover": {
              "$type": "color",
              "$value": {
                "dark": {
                  "$mode": "dark",
                  "$alias": "colors.Core.blue-100"
                },
                "light": {
                  "$mode": "light",
                  "$alias": "colors.Core.blue-700"
                }
              },
              "$description": "alias token with n modes within collection within n groups"
            }
          }
        }
      }
    }
  }
}

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

• 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.

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.

2. Click "Connect"

3. Choose Advanced Repository

1. Go to your Specify workspace

2. Click on "Create repository"

3. Choose a name

4. Select "Advanced Repository" ()

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.

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

• 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.

Before getting started

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

• A Specify account

• The Tokens Studio plugin installed in your Figma

• A , , , or account

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. 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

1. Go to your Specify workspace

2. Click on "Create repository"

3. Choose "Advanced Repository"

4. Name your repository

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.

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

2. Select "Remote URL"

3. Select "Public"

4. Name your source

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

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:

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

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

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

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

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!

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)

They will be released in future updates. However, if you have urgent needs for Specify to be compatible with one of them, .

You access each of the query methods over:

sdtfEngine.query.[method]

getTokenState

Get a tokenState instance from the tokens token tree.

function getTokenState(
  path: Array<string>
):
  | { status: "resolved"; tokenState: TokenState<Type> }
  | { status: "unresolvable"; reason: "DOES_NOT_EXIST" };

getGroupState

Get a groupState instance from the tokens token tree.

function getGroupState(
  path: Array<string>
):
  | { status: "resolved"; groupState: GroupState }
  | { status: "unresolvable"; reason: "DOES_NOT_EXIST" };

getCollectionState

Get a collectionState instance from the tokens token tree.

function getCollectionState(
  path: Array<string>
):
  | { status: 'resolved'; collectionState: CollectionState }
  | { status: 'unresolvable'; reason: 'DOES_NOT_EXIST' };

getNearestCollectionState

Get the collectionState instance enclosing the given path.

function getNearestCollectionState(
  path: Array<string>
):     | { status: 'resolved'; collectionState: CollectionState }
  | { status: 'unresolvable'; reason: 'DOES_NOT_EXIST' };

getAllTokenStates

Get all tokenState instances from the tokens token tree.

function getAllTokenStates(): Array<TokenState>;

getAllGroupStates

Get all groupState instances from the tokens token tree.

function getAllGroupStates(): Array<GroupState>;

getAllCollectionStates

Get all collectionState instances from the tokens token tree.

function getAllCollectionStates(): Array<CollectionState>;

getAllNodeStates

Get all tokenState, groupState and collectionState instances from the tokens token tree.

function getAllNodeStates(): Array<TokenState | GroupState | CollectionState>;

getTokenChildrenOf

Get the tokenState instances that are children of the given path.

function getTokenChildrenOf(path: Array<string>): Array<TokenState>;

getGroupChildrenOf

Get the groupState instances that are children of the given path.

Get the collectionState instances that are children of the given path.

Get the tokenState, groupState and collectionState instances that are children of the given path.

Get the groupState and collectionState instances that are parents of the given path.

Get groupState instances that are direct children of the given path.

Get tokenState instances that are direct children of the given path.

Get collectionState instances that are direct children of the given path.

Get the JSON representation of the tokens token tree.

Get the aliasReference instance from given coordinates.

Get all aliasReference instances from the tokens token tree.

Get all aliasReference instances that reference the given "to" coordinates.

Get all aliasReference instances that reference the given "from" coordinates.

Get the statefulAliasReference instance of the given "from" coordinates.

Get the statefulAliasReference instances that reference the given "to" coordinates.

Get the statefulAliasReference instances that reference the given "from" coordinates.

Properties

isAuthenticated

A boolean indicating whether the client is authenticated or not.

Methods

authenticate

Authenticates the client with a Personal Access Token. Can be generated at specifyapp.com/user/personal-access-tokens

whoAmI

Returns the current user if authenticated.

logout

Logs out the current user.

getRepositories

Returns the repositories list of the current organization.

getSDTFClientByRepositoryName

Returns a SDTFClient instance to work with the SDTF token tree of the repository.

transformTokenTreeWithRemoteParsers

Generates Design Tokens from the given token tree and configuration parsers.

Interface

interface parser {
  name: 'svg-to-jsx';
  output: {
    type: 'directory';
    directoryPath: string;
  };
  options?:{
    reactVersion?: string;
    tsx?: boolean;
    filePrefix?: string;
    fileSuffix?: string;
    exportDefault?: boolean;
    tokenNameTemplate?: string;
  }
}

Options

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 or get automated Pull Requests. You can also create your custom pipeline thanks to our .

• 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.

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

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

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

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

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

• A Specify account

• A Specify repository containing design tokens ()

Install @specifyapp/cli

The Specify Playground helps you run parsers against a token graph and see the generated output in live. It's a great tool to help you iterate on your configuration files or try new parsers on the go.

• The left side panel contains the SDTF graph you'll run your rules against. It's editable and you're free to use your own SDTF graph which you can get with the parser

• The middle panel contains your Specify configuration rule

The Specify SDK host several APIs that unwraps as follow

• SpecifyClient

  • SDTFClient

    • SDTFEngine

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!

How to get started? Easy as pie, follow our Getting started section to grasp the best usage of the SDK.

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:

To install a specific version, use the flag VERSION:

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

Definition

A destination belongs to a Repository, it represents where the formatted design data flow 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

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:

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

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

If you are planning to use the or , you can head over to our that will help you start distributing your token to the main common use cases.

Overview

The Specify HTTP API is accessible over the following base url:

https://api.specifyapp.com/v2

Authentication

In order to request the routes of the HTTP API, you need to set a Personal Access Token within your request headers like so:

Authorization: PAT <your-personal-access-token>

Headers

To work with the Specify HTTP API, we recommend the use of the following headers:

Content-Type: application/json
Authorization: PAT <your-personal-access-token>

Endpoints

Global flags

-h, --help

Show the help

-v, --version

Show the current version of the CLIx

-C, --config-path [configPath]

The path to your JSON or Javascript config file, or the folder containing all your configs (default: .specifyrc.json)

-p, --personal-access-token <personalAccessToken>

Your personal access token. . It will try to read it from the env var SPECIFY_PAT as well.

-r, --repository <repository>

The repository containing the design tokens you're requesting. It follows the pattern @organizationName/repositoryName. It will try to read it from the env var SPECIFY_REPOSITORY as well.

Init

Generate a Specify ready-to-use configuration to pull your design data from your Specify repository.

Flags

--root [.]

By default everything is generated in the current dir, but you can choose a different path to generate your configuration file (Default: .)

Pull the tokens from the repository following the configs

No flags for now

Ready-to-use configuration templates for your next project

This section will help you get started with ready-to-use configuration template. Each configuration file will be filled by one or several configuration rules.

The produces finite and opinionated outputs, but sometimes you need to have more control over our generated files.

That's where the SDTF Client takes over and provide plenty of methods to work with any token tree.

The SDTF Client offers versatile methods for working with 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.

To access your data, you use the . You can then fetch a and use the to manipulate the data and transform to your desired custom format.

The SDTF Client API wraps up the which holds the lower level methods to work with the token tree.

The Specify Client manages:

Your Specify personal access token must always be private. We highly recommend you to set it in a private environment variable or in a .env file.

You can inject your personal access token through the --personal-access-token, -p CLI flag.

Please make sure you have:

• A GitHub account

• A Specify account

• One or multiple Specify repositories containing some design tokens.

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

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

Converters are the way of converting a token to a specific syntax in the Specify SDK.

Here are the available syntaxes:

Interface

interface parser {
  name: 'to-file';
  options: {
    filenameTemplate: string;
  };
  output: {
    type: 'directory';
    directoryPath: string;
  };
};

Options

Route

Method: POST

Authentication: required

Url:

https://api.specifyapp.com/v2/parsers-engine-rpc

Headers

Content-Type: application/json
Authorization: PAT <your-personal-access-token>

Request Body

type ParsersEngineRPCRequestBody = {
  dataBox: ParsersEngineDataBox;
  rules: Array<ParserRule>;
  returnedKeys?: {
    output?: boolean;
    next?: boolean;
    errorMessages?: boolean;
    warningMessages?: boolean;
    informationMessages?: boolean;
  };
};

Here's a simple example to get the raw tokens in JSON from a repository called all-design-datain the @acme-inc workspace:

Properties

engine

This property represents the SDTF engine used by the SDTFClient.

readonly engine: SDTFEngine;

repository

This property represents the repository that the SDTFClient is interacting with.

readonly repository: {
    readonly id: string;
    readonly name: string;
    readonly version: number;
    readonly createdAt: string;
    readonly updatedAt: string;
};

Methods

getJSONTokenTree

Returns the JSON token tree from the current repository.

getJSONTokenTree(): SpecifyDesignTokenFormat;

clone

Create a new SDTFClient instance to avoid mutating the current token tree. Especially useful when you want to perform multiple distinct operations on the same token tree.

clone(): SDTFClient;

pick

Narrow the current token tree by picking a subtree based on the given path.

pick(path: Array<string>): this;

query

Create a clone of the current SDTF and only keep the selection of the query. When creating a new tree it's possible that tokens, groups and collections names will collide.

query(query: SDTFQuery, dedupeFn?: MergeDedupeFn): SDTFClient;

renameNode

Rename a node to a new name. If you specify a type, it'll rename the node only if it's matching the type parameter. If it doesn't, it'll throw an error.

renameNode(options: {
    atPath: Array<string>;
    name: string;
    type?: 'group' | 'collection' | 'token';
}): this;

Example

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

update

Execute an update on the current token tree. Note that the update won't be applied to the remote repository.

update(...updaters: Array<Updater>): this;

withQuery

Execute multiple updater functions with the same query.

Resolve aliases in the current token tree. Useful before pick to avoid unresolvable aliases.

Narrow the current token tree by removing any matching node based on the given query.

Resets the current token tree to its initial value. The initial value being the token tree of the repository at the time of the creation of the first SDTFClient instance.

Tap into the current token tree to perform custom side effects.

Iterate against the tokenStates of the current token tree.

Iterate against the tokenStates of the current token tree, and accumulate the results in an array.

Get a token state for a given path.

Get all the token states.

Iterate against the collectionStates of the current token tree.

Iterate against the collectionStates of the current token tree, and accumulate the results in an array.

Get a collection state for a given path.

Get all the collection states.

Iterate against the groupStates of the current token tree.

Iterate against the groupStates of the current token tree, and accumulate the results in an array.

Get a group state for a given path.

Get all the group states.

Iterate against the nodeStates given by the query.

Iterate against the nodeStates given by the query, and accumulate the result in an array.

Create a parsers engine executor from the custom or built-in parser functions passed as arguments. All pipelines are executed in parallel, if you need to chain parsers, have a look to the chainParserFunctions util.

Create a parsers engine executor from the built-in parser rules passed as arguments. All pipelines are executed in parallel, if you need to chain parsers, have a look to the chainParserFunctions util.

A parsersEngineResults instance is returned by the parsers engine execution.

Example:

const results: ParsersEngineResults = await SDTFClient.createParsersPipelines({ ... })()

Properties

all

This getter returns the raw results of the parser pipelines execution.

get all: Array<ParsersEngineResult>;

hasError

This getter returns a boolean indicating whether any of the pipelines returned an error.

get hasError: boolean;

hasWarning

This getter returns a boolean indicating whether any of the pipelines returned warnings.

get hasWarning: boolean;

allErrorMessages

This getter gathers the error messages from all the pipelines.

get allErrorMessages: ParsersEngineErrorMessage[];

allWarningMessages

This getter gathers the warning messages from all the pipelines.

get allWarningMessages: ParsersEngineWarningMessage[];

allInformationMessages

This getter gathers the information messages from all the pipelines.

get allInformationMessages: ParsersEngineInformationMessage[];

Methods

logErrorMessages

This method prints error messages to the console.

logErrorMessages(): void;

logWarningMessages

This method prints warning messages to the console.

logWarningMessages(): void;

logInformationMessages

This method prints information messages to the console.

This method prints a summary of the execution results to the console.

This method maps over any output of the parsers. It is quite convenient if you want to run some post-process on the output.

This method maps over output files. It is quite convenient if you want to run some post-process on the files.

This method writes the outputs of the parsers to the file system.

This method serializes the results before HTTP transmission.

You access each of the mutation methods over:

Add a new token to the token tree.

Rename a token.

Update the description of a token.

Update the extensions of a token.

Update the value of a token.

Update the value of a token for a given mode.

Rename a token mode.

Create a new token mode value.

Delete a token mode value.

Delete a token.

The SDTF Query Language is a JSON structure describing several match criteria used to select nodes - tokens, groups and collections - within the token tree.