1 of 100

V2

Getting started

Introduction

Learn about our API and how to sync and transform design tokens in your design system.

What is Specify?

The first Design Token Engine allowing you to send your design tokens across your design system tools. Specify is built with this idea: configure once, synchronize anytime.

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.

Glossary

Looking for a definition? We've got your back!

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 .

Source

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

Destination

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

Specify Design Token Format (SDTF)

The SDTF stands for . 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 is the high-level design data transformation and export API.

Parser Rule

A 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

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

SDTF Client

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

SDTF Engine

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

Collect

What is a Source?

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.

You can review your sources status by heading to any repository page on the Specify webapp.

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.

Figma Variables & Styles

In this guide, you’ll learn how to sync your Figma Variables and/or Styles to a Specify Repository and how to keep them updated.

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.

2. Connect your Specify account

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.
Click "Connect"
Choose Advanced Repository

Note: the widget can be used for syncing Figma Styles from the Classic repositories as well, you can switch between the two by clicking "Switch to".

3. Create a repository in Specify

Go to your Specify workspace
Click on "Create repository"
Choose a name
Select "Advanced Repository" ()
Click "Create repository"

Go back to your Figma file that includes the Variables and/or Styles
Click on "Create Source" in the Specify Widget
It will show you the local collections and styles that are detected
Select the design tokens format you want to collect from your Figma file.
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).
Click "Save to Specify"
You will immediately see the repository listed with the latest syncing time

Make sure to understand that only Advanced repositories are listed here.

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 ! 🎉

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.

Distribute

What is a Destination?

Definition

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

You can add many destinations into a single repository. Read more about the available 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.

Getting started with templates

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.

Available destinations

List of all integrations you can use with Specify to distribute design tokens and assets to.

GitHub

Distribute your design tokens and assets via automated Pull Requests.

Specify will sync your GitHub repository if you have a config file .specifyrc.json saved at the root of your GitHub repository.

Prerequisites

Please make sure you have:

A GitHub account
A Specify account
One or multiple Specify repositories containing some design tokens.

Want to connect a GitHub repository from your GitHub organization? Please make sure you have the correct access rights. Otherwise, you'll need an owner to approve your installation request.

Connecting Specify and GitHub

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

Go to the Specify Advanced Repository you want to distribute design data from
Go to its "Destinations" page
Click on "Create Pipeline"
Select "GitHub application"
Connect or select your GitHub account
Select the GitHub repository you want to distribute your design data to
Name for your configuration file ()
Create the Pull Request containing your configuration file
Merge the PR created by Specify containing your configuration file
Specify will now automatically sync design data to your GitHub repository 🎉

Useful resources

Specify CLI

Build for the CI/CD

The Specify CLI enables you to generate your code in any environment. Built on top of the Specify SDK, built with our newly released format (SDTF), and compiled with Bun, this tool will help you create your CI/CD workflows.

Let's jump in!

How to get started? Easy as pie, follow our Getting started.

Specify SDK

Distribute your design tokens and assets from Specify right from your codebase.

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 section to grasp the best usage of the SDK.

HTTP API

Consume your design tokens and assets over HTTP requests.

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

The HTTP API leverage the Parsers Rules to let you instruct transformations to your SDTF design tokens right when you make the request making sure the data you receive is up to date with your repository.

Get started

The Specify HTTP API is read-only upon your design data.

To use the HTTP API, you'll need:

A Specify account with at least one repository, filled with design data from any source.
A personal access token 👉 generate one.

Jump to the HTTP API section to get started.

Concepts

Parsers Engine

Configure automated pipelines and deliver the design data to battle-tested technologies like CSS, Style Dictionary, Javascript, TypeScript, Swift, Kotlin — and more.

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 designed to transform design data, in parallel and/or chained. By configuring , you customize how and where design tokens and assets are exported.

The Parsers Engine can operate both , using the Pipe Engine API over HTTP, and , through the . 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 , 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

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

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

Looking for how to configure the output property? 👉 review the reference.

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

Looking for a precise parser option? 👉 review the full .

Example of a parser rule for a CSS custom properties output

Parser rules templates

To get started with the parser rules 👉 heads up to the resources.

Remote execution

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

are compatible with the remote execution.

For some destinations, like & the 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 source from which to fetch design data.
Provide a personal access token as authentication credentials for your user.
Describe the to configure your ouput.

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

Looking for the configuration file details? 👉 review the reference

Local execution

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

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

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

Get started with local execution 👉 review the guide.

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.

Looking for the parsers settings? 👉 review the .

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.

The utility parsers are only available to the of the Parsers Engine.

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.

SDTF Client

Step into the Specify SDK APIs to get fined grained access to your design data.

Introduction

The Parsers Engine 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 SDTF token tree.

Looking for how to get started with the SDK? 👉 heads up to the Specify SDK usage 101 guide.

Overview

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.

To access your organization data, you use the Specify Client API. You can then fetch a repository and use the SDTF Client API to manipulate the data and transform to your desired custom format.

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

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.

You can create several instances of the same initial token tree - using clone()

Then, create several updates:

with predefined formatters using update()
with cherry-picking of a sub-tree using pick()
with custom implementation using forEachTokenState()
and many more

Convert tokens to XXX

Converting tokens is always a matter of iterating over the tokens of your tree and decide what to do with their value(s), their modes and potential aliases.

Looking for usage? 👉 heads up to the Convert a token to XXX guide.

SDTF Engine

Leverage the Specify core APIs to manipulate the SDTF token tree and produce any output you need.

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.

You can access the SDTF Engine APIs over the Specify SDK.

all parsers written by Specify uses the SDTF Engine under the hood.

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.

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.

updateTokenModeValue, updateTokenValue, moveToken, addToken, deleteToken, renameToken… and many more - 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.

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.

const query: SDTFQuery = {
  where: {
    collection: '^MyCollection$',
    andWhere: {
      group: '^MyGroup$',
      andWhere: {
        token: '.*',
        select: true,
      },
    },
  },
};

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

Looking for the SDTF Query Language details? 👉 review the SDTF Query Language reference

The SDTF Query Language is accessible in the Specify SDK and in some parsers via a dedicated option.

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.

Guides

Specify CLI usage 101

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!

Getting started

Getting started with the Specify CLI

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

Authentication

Specify use a Personal Access Token for the authentication. You can create it from the . Once you have a personal access token, you can use it in two ways:

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.

The personal access token in a config file is useful if you need to execute some custom business logic. To stay safe, you should use a library like to store credentials outside of the code.

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

the flag
the configuration file
the environment variable

Generate Files

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.

Example: Export All Tokens and Assets In JSON

Specify SDK usage 101

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!

Updating tokens

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.

All the updates will be performed locally on the loaded SDTF, but that's it, there's no side effects

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:

Update the colors

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

You can refer to 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:

You can refer to 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:

You can refer to 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:

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:

Creating your custom updater

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

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

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

Specify SDK Cheatsheet

On this page you'll find a lot of common actions you'll probably want to perform when using the SDK

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'
});

Reference

make-line-height-relative

This parser helps you transform your text style lineheight values relative to their font size.

Interface

Basic usage

select-modes

This parser helps you select design tokens from specific mode(s).

Interface

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

Options

Parameter

Required

Type

Default

Description

modes

true

Array

The query that select items in the graph.

Basic usage: select all tokens from a mode named "light"

{
  "colors": {
    "$collection": {
      "$modes": ["light", "dark"]
    },
    "info": {
      "infoToken": {
        "$type": "color",
        "$value": {
          "light": {
            "model": "rgb",
            "red": 219,
            "green": 234,
            "blue": 254,
            "alpha": 1
          },
          "dark": {
            "model": "rgb",
            "red": 219,
            "green": 234,
            "blue": 254,
            "alpha": 1
          }
        }
      }
    },
    "danger": {
      "dangerToken": {
        "$type": "color",
        "$value": {
          "light": {
            "model": "rgb",
            "red": 209,
            "green": 204,
            "blue": 204,
            "alpha": 1
          },
          "dark": {
            "model": "rgb",
            "red": 19,
            "green": 34,
            "blue": 54,
            "alpha": 1
          }
        }
      }
    }
  }
}

We want to get all design tokens from the mode named "light"
We eventually generate our design tokens ass CSS variables in a CSS file thanks to the to-css-custom-properties parser.

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Only get tokens from the mode named 'light' and gererate tokens in CSS",
      "parsers": [
        {
          "name": "select-modes",
          "options": {
            "modes": ["light"]
          }
        },
        {
          "name": "to-css-custom-properties",
          "options": {
            "selectorTemplate": "[data-theme=\"{{mode}}\"]"
          },
          "output": {
            "type": "file",
            "filePath": "public/css-custom-properties.css"
          }
        }
      ]
    }
  ]
}

tokens.json

[data-theme="light"] {
  --danger-dangerToken: rgb(209, 204, 204);
  --info-infoToken: rgb(219, 234, 254);
}

to-scss-map

This parser helps you generate .scss files for each token type containing SCSS map and function / mixin to access the values of the tokens.

Interface

Options

Parameter

Required

Type

Default

Description

Basic usage

svgo

This parser help you optimize and transform your SVG strings with svgo.

Interface

interface Parser {
  name: "svgo";
  output: {
    type: "directory";
    directoryPath: string;
  };
  options?: {
    // https://github.com/svg/svgo/blob/main/lib/svgo.d.ts#L29-L49
    svgo?: Config;
  };
}

Options

Parameter

Required

Type

Default

Description

svgo

false

null

The configuration.

Basic usage

{
  "icons": {
    "array": {
      "$type": "vector",
      "$value": {
        "default": {
          "variationLabel": null,
          "format": "svg",
          "url": "https://static.specifyapp.com/sdtf-seeds/array.svg"
        }
      }
    }
  }
}

menu.svg

<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none">
    <path d="M9.25 9.25V3.5H4C3.72386 3.5 3.5 3.72386 3.5 4V9.25H9.25ZM9.25 10.75H3.5V16C3.5 16.2761 3.72386 16.5 4 16.5H9.25V10.75ZM10.75 16.5H16C16.2761 16.5 16.5 16.2761 16.5 16V10.75H10.75V16.5ZM4 18C2.89543 18 2 17.1046 2 16V4C2 2.89543 2.89543 2 4 2H10H16C17.1046 2 18 2.89543 18 4V10V16C18 17.1046 17.1046 18 16 18H4ZM16.5 9.25V4C16.5 3.72386 16.2761 3.5 16 3.5H10.75V9.25H16.5Z" fill="#788BA5" />
</svg>

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Optimize and transform SVG with svgo + Generate SVG files",
      "parsers": [
        {
          "name": "svgo",
          "output": {
            "type": "directory",
            "directoryPath": "output/assets"
          },
          "options": {
            "svgo": {
              "plugins": [
                {
                  "name": "removeDimensions"
                },
                {
                  "name": "convertColors",
                  "params": {
                    "currentColor": true
                  }
                }
              ]
            }
          }
        }
      ]
    }    
  ]
}

menu.svg

<svg viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M9.25 9.25V3.5H4C3.72386 3.5 3.5 3.72386 3.5 4V9.25H9.25ZM9.25 10.75H3.5V16C3.5 16.2761 3.72386 16.5 4 16.5H9.25V10.75ZM10.75 16.5H16C16.2761 16.5 16.5 16.2761 16.5 16V10.75H10.75V16.5ZM4 18C2.89543 18 2 17.1046 2 16V4C2 2.89543 2.89543 2 4 2H10H16C17.1046 2 18 2.89543 18 4V10V16C18 17.1046 17.1046 18 16 18H4ZM16.5 9.25V4C16.5 3.72386 16.2761 3.5 16 3.5H10.75V9.25H16.5Z" fill="currentColor" />
</svg>

svg-to-jsx

This parser helps you generate JSX or TSX components from your vector assets.

Interface

Options

Parameter

Required

Type

Default

Description

Basic usage

svg-to-tsx

This parser helps you generate TSX components from your vector assets.

Interface

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

Options

Parameter

Required

Type

Default

Description

reactVersion

false

string

The React version you're using. Depending on your version, this parser will automatically import React in your JSX component.

filePrefix

false

string

''

Add an arbitrary content at the beginning of the generated file.

fileSuffix

false

string

''

Add an arbitrary content at the end of the generated file.

exportDefault

false

boolean

true

Whether use named or default export.

tokenNameTemplate

false

string

'{{token}}'

Change the template of the generated named export.

Basic usage

{
  "icons": {
    "menu": {
      "$type": "vector",
      "$value": {
        "default": {
          "variationLabel": null,
          "format": "svg",
          "url": "<url-of-your-svg-file>"
        }
      }
    }
  }
}

.specifyrc.json

{
  "name": "Generate vectors as TSX components",
  "parsers": [
    {
      "name": "svg-to-tsx",
      "output": {
        "type": "directory",
        "directoryPath": "output/assets"
      }
    }
  ]
}

output/assets/icons/menu.tsx

export default () => (
    <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
        <path d="M9.25 9.25V3.5H4C3.72386 3.5 3.5 3.72386 3.5 4V9.25H9.25ZM9.25 10.75H3.5V16C3.5 16.2761 3.72386 16.5 4 16.5H9.25V10.75ZM10.75 16.5H16C16.2761 16.5 16.5 16.2761 16.5 16V10.75H10.75V16.5ZM4 18C2.89543 18 2 17.1046 2 16V4C2 2.89543 2.89543 2 4 2H10H16C17.1046 2 18 2.89543 18 4V10V16C18 17.1046 17.1046 18 16 18H4ZM16.5 9.25V4C16.5 3.72386 16.2761 3.5 16 3.5H10.75V9.25H16.5Z" fill="#788BA5" />
    </svg>
);

to-bitmap-file

This parser helps you generate PNG and JPG files from your bitmap assets.

Interface

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

Options

Parameter

Required

Type

Default

Description

filenameTemplate

false

string

"{{parents}}/{{name}}[-{{mode}}]{{extension}}"

The mustache template used to generate the file path to write to the file system. Available variables: parents: group and collection names of the token's parents name: the name of the asset token mode: the name of the current mode extension: the file extension extracted from the token

Basic usage - single mode

{
  "assets": {
    "image": {
      "$type": "bitmap",
      "$value": {
        "1x": {
          "url": "<url-of-your-bitmap-file>",
          "format": "png",
          "width": 623,
          "height": 415,
          "variationLabel": null
        }
      }
    }
  }
}

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate images",
      "parsers": [
        {
          "name": "to-bitmap-file",
          "output": {
            "type": "directory",
            "directoryPath": "public"
          }
        }
      ]
    }
  ]
}

This will generate a single bitmap file like so:

public/assets/image.png

Advanced usage - Several modes by definition (@1x, @2x...)

Our bitmap is named "image", is in a group named "assets", and has 2 modes for each definition parameter: 1x and 2x.

By default, this parser will generate the following output: {directoryPath}/{groups}/{bitmapName}.{png|jpg}

{
  "assets": {
    "image": {
      "$type": "bitmap",
      "$value": {
        "1x": {
          "url": "<url-of-your-bitmap-file>",
          "format": "png",
          "width": 623,
          "height": 415,
          "variationLabel": null
        },
        "2x": {
          "url": "<url-of-your-bitmap-file>",
          "format": "png",
          "width": 1246,
          "height": 830,
          "variationLabel": null
        }
      }
    }
  }
}

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate images",
      "parsers": [
        {
          "name": "to-bitmap-file",
          "output": {
            "type": "directory",
            "directoryPath": "public"
          }
        }
      ]
    }
  ]
}

This will generate the following bitmap files:

public/assets/image-1x.png
public/assets/image-2x.png

to-file

This parser helps you generate files from any asset token: Bitmap, Font and Vector.

Interface

Options

Parameter

Required

Type

Default

Description

Basic usage

This will generate the corresponding font file binary, named after the filenameTemplate.

public/inter-regular.ttf

Specify SDK

Specify SDK API Reference

Overview

The Specify SDK host several APIs that unwraps as follow

SpecifyClient
- SDTFClient
  - SDTFEngine
    TokenState | CollectionState | GroupState
    Query & Mutation
    Query Runner

Usage

Follow the guide.

Package

The @specifyapp/sdk TypeScript package is available on npm.

SpecifyClient

The main Specify client to interact with Specify repositories and the SDTF token tree.

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

authenticate(personalAccessToken: string): Promise<void>;

whoAmI

Returns the current user if authenticated.

whoAmI(): {
  email: string;
  id: string;
  username: string;
  fullname: string;
  organizations: {
    id: string;
    namespace: string;
    domain: string | null;
  }[];
} | null;

logout

Logs out the current user.

logout(): void;

getRepositories

Returns the repositories list of the current organization.

getRepositories(): Promise<{
  name: string;
  id: string;
  version: number;
  createdAt: string;
  updatedAt: string;
}[]>;

getSDTFClientByRepositoryName

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

getSDTFClientByRepositoryName(repositoryName: string): Promise<SDTFClient>;

transformTokenTreeWithRemoteParsers

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

transformTokenTreeWithRemoteParsers(
  sdtfTree: SpecifyDesignTokenFormat,
  parsers: PipeEngineParserConfiguration
): Promise<{
  fromRule: string;
  output: PipeEngineRuleOutput
}>;

SDTFClient

The client to use SDTFEngine and Parsers Pipeline APIs. It provides methods for interacting with the token tree of a repository.

Properties

engine

This property represents the SDTF engine used by the SDTFClient.

repository

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

Methods

getJSONTokenTree

Returns the JSON token tree from the current repository.

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.

pick

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

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.

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.

Example

update

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

withQuery

Execute multiple updater functions with the same query.

resolveAliases

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

remove

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

reset

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.

executeEngine

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

forEachTokenState

Iterate against the tokenStates of the current token tree.

mapTokenStates

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

getTokenState

Get a token state for a given path.

getAllTokenStates

Get all the token states.

forEachCollectionState

Iterate against the collectionStates of the current token tree.

mapCollectionStates

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

getCollectionState

Get a collection state for a given path.

getAllCollectionStates

Get all the collection states.

forEachGroupState

Iterate against the groupStates of the current token tree.

mapGroupStates

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

getGroupState

Get a group state for a given path.

getAllGroupStates

Get all the group states.

forEachQueryResult

Iterate against the nodeStates given by the query.

mapQueryResults

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

createParsersPipelines

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.

createParsersPipelinesFromRules

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.

Converters

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

Here are the available syntaxes:

ParsersEngineResults

ParsersEngineResults class API reference

A parsersEngineResults instance is returned by the parsers engine execution.

Example:

Properties

all

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

hasError

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

hasWarning

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

allErrorMessages

This getter gathers the error messages from all the pipelines.

allWarningMessages

This getter gathers the warning messages from all the pipelines.

allInformationMessages

This getter gathers the information messages from all the pipelines.

Methods

logErrorMessages

This method prints error messages to the console.

logWarningMessages

This method prints warning messages to the console.

logInformationMessages

This method prints information messages to the console.

debug

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

mapOutput

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

mapFiles

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

writeToDisk

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

serialize

This method serializes the results before HTTP transmission.

SDTF Engine

The SDTF Engine API reference.

Instances

The SDTF Engine can be accessed in:

the @specifyapp/sdk package, by using the specifyClient.getRepositoryTokenTree method.
the @specifyapp/specify-design-token-format package, by using the exported createSDTFEngine function.

Public API

sdtfEngine.[method]

Query methods

The Query API provides methods for locally accessing and iterating the token tree.

Query runner

The SDTF Query Language is used into the sdtfEngine.query.run(query: SDTFQuery)

Mutation methods

The Mutation API provides methods for locally mutating the token tree.

Top level

`renderJSONTree`

Get the JSON representation of the token tree.

function renderJSONTree(param: {
  renderOptions:
    | {
        resolveAliases: true;
        allowUnresolvable?: AllowUnresolvable;
        targetMode?: TargetMode;
      }
    | { resolveAliases: false };
}): JSON;

Query API

Methods for locally accessing and iterating the token tree.

You access each of the query methods over:

`getTokenState`

Get a tokenState instance from the tokens token tree.

`getGroupState`

Get a groupState instance from the tokens token tree.

`getCollectionState`

Get a collectionState instance from the tokens token tree.

`getNearestCollectionState`

Get the collectionState instance enclosing the given path.

`getAllTokenStates`

Get all tokenState instances from the tokens token tree.

`getAllGroupStates`

Get all groupState instances from the tokens token tree.

`getAllCollectionStates`

Get all collectionState instances from the tokens token tree.

`getAllNodeStates`

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

`getTokenChildrenOf`

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

`getGroupChildrenOf`

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

`getCollectionChildrenOf`

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

`getChildrenOf`

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

`getParentsOf`

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

`getGroupChildren`

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

`getTokenChildren`

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

`getCollectionChildren`

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

`renderJSONTree`

Get the JSON representation of the tokens token tree.

`getAliasReference`

Get the aliasReference instance from given coordinates.

`getAllAliasReferences`

Get all aliasReference instances from the tokens token tree.

`getAliasReferencesTo`

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

`getAliasReferencesFrom`

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

`getStatefulAliasReference`

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

`getStatefulAliasReferencesTo`

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

`getStatefulAliasReferencesFrom`

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

SDTF QueryResult

The QueryResult class API reference

The QueryResult class provides an abstraction to work with the tree node returned by a SDTF query.

Properties

isContinuous

Indicates whether the selected nodes are part of the same resulting JSON tree.

Methods

merge

Produces a new tree state with the resulting nodes.

hasNodeType

Check if the result contains some nodes of the specified type.

hasOnlyNodeType

Check if the result contains only nodes of the specified type.

render

Produces an analysis of the resulting nodes.

When the result is continuous, the render function returns an array of length 1

getPaths

Get the token tree path of the resulting nodes.

toJSON

Renders the resulting nodes as a JSON object using the QueryResultDetail structure.

Stateful Value

This page is work in progress 🚧

HTTP API

Specify HTTP API reference

Overview

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

https://api.specifyapp.com/v2

The Specify HTTP API is currently read-only upon your design data.

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>

Get a Personal Access Token from your user settings ↗︎

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

Verb

Route

Description

POST

Execute the against a given input and

POST /parsers-engine-rpc

Execute the Parsers Engine against a given input and Parsers Rules.

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;
  };
};

Name

Type

Description

dataBox

The initial state to launch the parsers engine from.

rules

Array<>

The parser rule definitions to instruct the transformation and generation pipelines.

returnedKeys

Record<string, boolean | undefined> | undefined

Select which response keys should be present. Defaults to true.

Response Body

type ParsersEngineResults = Array<{
  pipelineName: string;
  isFromRule: boolean;
  status: "success" | "error";
  output:
    | {
        type: "files";
        files: Array<{
          path: string;
          content:
            | { type: "text"; text: string }
            | { type: "url"; url: string };
        }>;
      }
    | {
        type: "JSON";
        json: unknown;
      }
    | {
        type: "text";
        text: string;
      }
    | {
        type: "SDTF";
        graph: SpecifyDesignTokenFormat;
      }
    | null;
  next: ParsersEngineDataBox | undefined;
  errorMessages: Array<{
    type: "error";
    content: string;
    errorKey: string;
  }>;
  warningMessages: Array<{
    type: "warning";
    content: string;
    errorKey: string;
  }>;
  informationMessages: Array<{
    type: "information";
    content: string;
  }>;
}>;

The response is an array where each item is the result of the rule given in the request, at the same index.

The output type matches the output configured within the rule given in the request.

The route always respond with a 200 code. Error state is represented by the status property in response object.

Example

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

curl -X POST 'https://api.specifyapp.com/v2/parsers-engine-rpc' \
--header 'Authorization: PAT <YOUR-PERSONAL-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "dataBox": {
    "type": "repository",
    "owner": "@acme-inc",
    "name": "all-design-data"
  },
  "rules": [
    {
      "name": "HTTP Extract",
      "parsers": [
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}'

Specify CLI

Here you can find all the detailed informations about the CLI

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.

Need a personal access token?

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

For now it will only generate an empty config file, but we will bring back the template selection soon

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

Pull the tokens from the repository following the configs

Flags

No flags for now

Resources

Parser Rules templates

Automatically distribute your design tokens and assets according to your organization's standards with our ready-to-use configuration templates.

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.

Make sure to read the concept to better understand how configuration file works with Specify.

Template

Description

Tailwind

This template helps you generate your design tokens as a Tailwind theme.

This example uses the following parsers:

to generate your design tokens as a Tailwind theme
to generate icons as JSX components

If you use the CLI, you need to fill three properties:

repository is @organization/repository
personalAccessToken which you can generate
rules are where you provide parsers and compatible options

If you use the GitHub, you need to fill 4 properties:

repository is @organization/repository
head lets you set the branch your PR will be created on
base lets you set the branch your PR will be merged on
rules lets you transform tokens by chaining parsers

Make sure you have connected your GitHub account with your Specify account. Head toward to learn more.

Flutter

This template helps you generate your design tokens in a dart file and icons as SVG files.

This example uses the following parsers:

to-flutter to generate your design tokens as dart files
svgo to optimize and generate icons as SVG files

If you use the CLI, you need to fill three properties:

repository is @organization/repository
personalAccessToken which you can generate in your account settings
rules are where you provide parsers and compatible options

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate tokens for Flutter",
      "parsers": [
        {
          "name": "to-flutter",
          "output": {
            "type": "file",
            "filePath": "public/tokens.dart"
          }
        }
      ]
    },
    {
      "name": "Optimize and generate icons as SVG files",
      "parsers": [
        {
          "name": "svgo",
          "output": {
            "type": "directory",
            "directoryPath": "public/vectors"
          }
        }
      ]
    }
  ]
}

If you use the GitHub, you need to fill 4 properties:

repository is @organization/repository
head lets you set the branch your PR will be created on
base lets you set the branch your PR will be merged on
rules lets you transform tokens by chaining parsers

Make sure you have connected your GitHub account with your Specify account. Head toward this article to learn more.

{
  "version": "2",
  "repository": "@organization/repository",
  "head": "specifyrc-json",
  "base": "main",
  "rules": [
    {
      "name": "Generate tokens for Flutter",
      "parsers": [
        {
          "name": "to-flutter",
          "output": {
            "type": "file",
            "filePath": "public/tokens.dart"
          }
        }
      ]
    },
    {
      "name": "Optimize and generate icons as SVG files",
      "parsers": [
        {
          "name": "svgo",
          "output": {
            "type": "directory",
            "directoryPath": "public/vectors"
          }
        }
      ]
    }
  ]
}

SDTF

This template helps you pull your design tokens in the SDTF format in a JSON file.

This example uses the following parser:

to generate your design tokens in SDTF

If you use the CLI, you need to fill three properties:

repository is @organization/repository
personalAccessToken which you can generate
rules are where you provide parsers and compatible options

If you use the GitHub, you need to fill 4 properties:

repository is @organization/repository
head lets you set the branch your PR will be created on
base lets you set the branch your PR will be merged on
rules lets you transform tokens by chaining parsers

Make sure you have connected your GitHub account with your Specify account. Head toward to learn more.

JSON

This template helps you pull your design tokens in JSON.

This example uses the following parser:

to generate your design tokens in JSON

If you use the CLI, you need to fill three properties:

repository is @organization/repository
personalAccessToken which you can generate
rules are where you provide parsers and compatible options

If you use the GitHub, you need to fill 4 properties:

repository is @organization/repository
head lets you set the branch your PR will be created on
base lets you set the branch your PR will be merged on
rules lets you transform tokens by chaining parsers

Make sure you have connected your GitHub account with your Specify account. Head toward to learn more.

Playground

Learn how to use the Specify Playground to iterate more easily on your configuration files

Introduction

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.

Usage

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 right side panel displays the generated code

Best practices

Set your Personal Access Token as an environment variable

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.

Using an `.env` file in a JavaScript config file

.env

SPECIFY_ACCESS_TOKEN=ab83f8f49f5c65456c7b1fe70efbc804aa08f87150214aa984d4125945ed8283bash

.specifyrc.mjs

import path from 'node:path';
import process from 'node:process';
import dotenv from 'dotenv';

dotenv.config({
  path: path.resolve(process.cwd(), '.env.specify-cli'),
});

export default {
  version: '2',
  repository: '@workspace/repository',
  personalAccessToken: process.env.SPECIFY_ACCESS_TOKEN,
  rules: [],
};

.specifyrc.cjs

const path = require('path');
const envFile = '.env';
require('dotenv').config({ path: path.resolve(process.cwd(), envFile) });

module.exports = {
  version: '2',
  repository: '@workspace/repository',
  personalAccessToken: process.env.SPECIFY_TOKEN,
  rules: [],
};

Using the `--personal-access-token` CLI flag

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

specify pull -p $SPECIFY_TOKEN

You can use this method to sync Specify with git repositories in GitLab, GitHub, Azure DevOps or Bitbucket.

Retrieving and working with the tokens

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(),
        });
      }
    },
  );

Looking for details about the query? 👉 heads up to the SDTF Query Language concept.

Looking for more methods to retrieve tokens? 👉 heads up to the SDTFEngine reference.

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:

Return the same type:

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

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
})

If you call mapPrimitiveValue, it needs to be the first one to be called in order to avoid remapping results produced by mapUnresolvableValueLevelAlias or mapResolvableValueLevelAlias.

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:

We will check if the token is fully resolvable
We'll use resolveDeepValue to remove the need of handling the resolvable aliases
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.

V2

Getting started

Introduction

What is Specify?

Glossary

Organization (workspace)

Repository

Source

Destination

Specify Design Token Format (SDTF)

Token type

Collection

Group

Alias

Mode

Parsers Engine

Parser Rule

Parser

SDTF Client

SDTF Engine

Configuration file

Collect

What is a Source?

Definition

Collecting the design data

Repository with many sources

Figma Variables & Styles

Before getting started

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

2. Connect your Specify account

3. Create a repository in Specify

4. Connect the Specify Repository in your Widget

5. Sync updates variables and styles on the fly

6. Check or delete your source inside the Specify interface

Distribute

What is a Destination?

Definition

Distributing the design data

Getting started with templates

Available destinations

GitHub

Prerequisites

Connecting Specify and GitHub

Useful resources

Specify CLI

Build for the CI/CD

Let's jump in!

Specify SDK

You are in Control

Leverage the most advanced design token format

Built to suit your standards

Let's jump in!

HTTP API

Access raw data

Work with any language

Generate upon request

Get started

Concepts

Parsers Engine

Overview

Parser Rules

Parser Configuration

Example of a parser rule for a CSS custom properties output

Parser rules templates

Remote execution

Configuration file

Local execution

The Parsers functions

Utility parsers

Generation parsers

SDTF Client

Introduction

Overview

The Specify Client API

The SDTF Client API

Mutate the token tree locally

Convert tokens to XXX

SDTF Engine

Introduction

Token Tree CRUD API