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.

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.

Definition

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

You can add many sources into a .

Learn more about the available compatible with Specify.

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.

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.

Introduction

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

Before getting started

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

• A Specify account

• A Specify repository containing design tokens ()

1. Install the CLI

Install @specifyapp/cli

2. Create your Specify config file

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

3. Add your Specify repository

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

4. Add your personal access token

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

5. Set your output format

Add your first rule and use the parser to generate your tokens as CSS variables.

6. Pull your design tokens and assets

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

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.

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.

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

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

Stateful Value API

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

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

Prerequisites

Please make sure you have:

• A GitHub account

• A Specify account

• One or multiple Specify repositories containing some design tokens.

Connecting Specify and GitHub

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

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

2. Go to its "Destinations" page

3. Click on "Create Pipeline"

Useful resources

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.

Overview

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

Then, create several updates:

• with predefined formatters using

• with cherry-picking of a sub-tree using

• with custom implementation using

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

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:

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 .

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 SDK, you're at the right place!

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 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 CLI, you're at the right place!

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

Here are the available syntaxes:

• CSS

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.

The Specify platform is based on the following pillars.

• Organization

• Repository

Above them, sit the engines:

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

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

Organization

As a Specify user, you belong to an organization.

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

Repository

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

A repository is exactly one design token tree built with the .

Source

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

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

Collecting the design data

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

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

Repository with many sources

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

Destination

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

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

Two main APIs at stake here:

• The , 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…

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

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

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

3. Create a repository in Specify

1. Go to your Specify workspace

2. Click on "Create repository"

3. Choose a name

4. Connect the Specify Repository in your Widget

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

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

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

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.

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

Global flags

-h, --help

Instances

The SDTF Engine can be accessed in:

• the @specifyapp/sdk package, by using the specifyClient.getRepositoryTokenTree

Overview

The Specify SDK host several APIs that unwraps as follow

• SpecifyClient

Overview

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

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:

Headers

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

Endpoints

Specify use a Personal Access Token for the authentication. You can create it from the dedicated page on the web app. 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.

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

1. the flag

2. the configuration file

3. the environment variable

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.

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

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.

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.

getPaths

Get the token tree path of the resulting nodes.

toJSON

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

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.

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.

https://iframe.specifyapp.com/sdtf-playground/index.html

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

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.

Interface

Basic usage

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.

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.

Updating tokens

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

Convert a token to XXX

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

Execute a parser

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

Retrieving data

Get a specific token

Get all the tokens

Map over all the tokens

Get a specific group

Get all the groups

Map over all the groups

Get a specific collection

Get all collections

Map over all the collections

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:

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:

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:

You can find all the details about querying the data .

Remove tokens from the SDTF

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

Renaming tokens

Rename a node

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

Rename a collection

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

Rename a group

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

Rename a token

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

Interface

Options

Basic usage

Route

Method: POST

Authentication: required

Url:

Headers

Request Body

Response Body

Example

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

Interface

Options

Basic usage - single mode

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}

Interface

Options

Basic usage

This example uses the following parser:

• to-json to generate your design tokens in JSON

This example uses the following parser:

• to-sdtf to generate your design tokens in SDTF

Interface

Options

Interface

Options

Properties

engine

You access each of the query methods over:

getTokenState

Get a tokenState instance from the tokens token tree.

This example uses the following parsers:

• to generate your design tokens as dart files

• to optimize and generate icons as SVG files