1 of 46

V1

Getting started

Introduction

Welcome to the Specify docs! Learn about how to use and integrate Specify in your workflow to sync your design tokens and assets in your design system.

What is Specify?

We provide the first Design Data Platform allowing you to send your design tokens and assets 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 applications to collect, store and distribute your design decisions 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 , 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.
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.

Getting started

A 5min guide on collecting and pulling your first design tokens and assets with Specify.

Introduction

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

This guide helps you to sync tokens from Figma local styles and frames to Specify. Want to sync Figma Variables instead? Click here to learn more.

Before getting started

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

A Specify account
A Specify repository containing some design tokens and assets (Learn more ↗)

1. Install the CLI

Install @specifyapp/cli via npm or Yarn.

npm install -g @specifyapp/cli

yarn global add @specifyapp/cli

2. Create your Specify config file

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

specify init

3. Add your Specify repository

Add your Specify repository from which you want to pull your design tokens and assets. Learn more ↗.

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

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

4. Add your personal access token

Generate a personalAccessToken for the CLI and add it in your configuration.

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

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

5. Pull your design tokens and assets

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

specify pull

Glossary

Specify is built on core concepts such as sources, destinations, pipelines, parsers. This page will help you understand all of them.

Design API

A Design API is an API designed to synchronize information in your design system. This includes design tokens, assets, components and documentation.

Source

A source is a place that contains data you want to sync within your design system. Like a Figma file from which you sync your colors from. Or a GitHub repository containing your design tokens in JSON.

Destination

A destination is a place in which you distribute data in. Like a GitHub repository consuming colors coming from your design system or a Notion database in which you document your icons.

Pipeline

A pipeline is the route that connects a Source or a Destination to Specify. It helps you transform and synchronize data (e.g., design tokens) within your design system.

Repository

A repository is like a folder containing your design tokens and assets in Specify. Use repositories to store and organize your design data.

Token type

Configuration

By default Specify returns design tokens and assets in JSON. Configure it to generate design data compatible with your company standards (e.g., CSS Variables).

Rule

A rule is a part of your configuration that helps you transform one or several Token types the way you want. Like a rule to pull colors from Specify as CSS Variables in a CSS file.

Parser

Advanced Repository

Getting started

Here’s a 5 minute guide on how to use different features within the Advanced Repository based on the Specify Design Token Format.

Introducing the Specify Design Token Format

Specify is building an entirely new Design Token Format (SDTF) to base our platform on a new design token graph. In short, this means that we are developing a format that enables more possibilities to add code-type sources and destinations than before. The new graph will facilitate managing a large number of design token types and assets. Next to this, it opens doors to more advanced features such as Aliases, Modes, and Collections.

In a more practical sense, the SDTF opens up compatibility with Figma Variables and Tokens Studio as a source alongside the existing Figma local styles compatibility. It also creates opportunities to create code output that includes aliases, modes, and collections.

All of these features come together in the Specify Advanced Repository.

Useful links

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

2. Connect your Specify account

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

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.

Tokens Studio

In this guide you’ll learn how to sync your design tokens from Tokens Studio to your Specify repository and how to keep them updated.

Before getting started

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

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

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

Head to your Tokens Studio plugin in Figma
Within the settings tab, add a new sync provider
Commit your Tokens Studio JSON file to your repository

You can also manually export your file from Tokens Studio and upload it manually to your code repository. Click on Tools on the bottom left of the plugin and Export to file/folder. Be careful to tick all the boxes before exporting. We are not supporting multiple files at the moment.

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

Go to your Specify workspace
Click on "Create repository"
Choose "Advanced Repository"
Name your repository
Click on "Create repository"
In the "Source" tab, click on "Create a source"
Select "Remote URL"

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

From a public URL

In the "Source" tab, click on "Create a source"
Select "Remote URL"
Select "Public"
Name your source
Paste your raw public URL of your JSON file
Select the format "Tokens Studio"
Let Specify check the connection
And voila!

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

From a private URL

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

GitHub

Requirements:

Have a GitHub account
Have an Advanced Repository created
Have a JSON file containing design tokens from Tokens Studio

To add a private URL source from GitHub to Specify:

In the "Source" tab of your Specify repository, click on "Create a source"
Select "Remote URL"
Select "Private"
Name your source
Select "Tokens Studio Format"
Specify will test your JSON
And voila!

Azure DevOps

Requirements:

Have an Azure DevOps account
Have a Project containing a repository
Have a JSON file containing design tokens from Tokens Studio

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

In the "Source" tab of your Specify repository, click on "Create a source"
Select "Remote URL"
Select "Private"
Name your source
Paste your Azure DevOps file URL such as https://dev.azure.com/{OrgName}/{ProjectName}/_apis/git/repositories/{RepositoryName}/items?path={FilePath}&api-version=7.0&includeContent=true
Select "Tokens Studio Format"
Specify will test your JSON
And voila!

GitLab

Requirements:

Have a GitLab account
Have an Advanced Repository created
Have a JSON file containing design tokens from Tokens Studio

To add a private URL source from GitLab to Specify:

In the "Source" tab of your Specify repository, click on "Create a source"
Select "Remote URL"
Select "Private"
Give a name to your source
Paste your GitLab file URL such as: https://gitlab.com/api/v4/projects/{OrgName}%2F{RepositoryName}/repository/files/{FilePath}?ref={branch}
Create an access token in GitLab: "Settings > Access Tokens". Select a role as Developer or Owner and select the scopes of read_api and read_repository.
In Specify, select Header as auth system
1. Fill PRIVATE-TOKEN in the key field
2. Paste your GitLab project access token
Select "Tokens Studio Format"
Specify will test your JSON
And voila!

JSONBin

Requirements:

Have a JSONBin account
Have an Advanced Repository created
Have a bin with a JSON file containing design tokens from Tokens Studio

To add a private URL source from JSONBin to Specify:

In the "Source" tab of your Specify repository, click on "Create a source"
Select "Remote URL"
Select "Private"
Name your source
Paste your BIN private URL such as https://api.jsonbin.io/v3/b/{bin_id}
Select Header as auth system
1. Following your choice, fill in the key field either with X-MASTER-KEY or X-ACCESS-KEY
2. Paste your key in the value field
Select "Tokens Studio Format"
Specify will test your JSON
And voila!

3. How to update your JSON File

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

Go to the "Source" tab of your Specify repository
Click on the context menu next to your source
Click on "sync"

Your source is now updated!

4. Non-supported design token types

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

Composition
Assets (bitmap & vectors)
Color manipulation (gradients, alpha, darken, lighten & mix)

CLI & Config

In this guide you’ll learn how to transform design data coming from Figma Variables, Figma Styles and/or Tokens Studio into CSS Custom Properties using the Specify CLI.

1. Install the CLI

Install the @specifyapp/cli via npm or Yarn.

2. Create your Specify configuration file

To create your Specify config file, you need to follow these steps:

Create an empty file named .specifyrc.json
Add the following content

3. Properties to update in the configuration file before using it:

A property version is shown which refers to the new Advanced Repository from which we are extracting tokens. Use the version: "2".
Add your organization and repository name under the repository property.
Run the command specify pull to fetch your design tokens.

4. CSS output example

Specify exports your Figma Variables Modes as CSS data-attributes:

We would like to improve this output according to your needs as much as we can. Feel free to share your feedback with us via:

The in-app chat

Things to take into account when using the CLI

The configuration file can handle MJS, CJS, and JSON.
There is no more path property in the parser settings, it is now replaced by an output key inside every parser.

Querying a SDTF graph

Learn more about how to query your SDTF token graph.

Introduction

Your token system can be more complex than it seems. You will often need to interact with your token graph to transform a specific set of design tokens within a Specify configuration.

This article will help you understand how you can query your token graph to select a specific set of tokens.

Compatible parsers

You'll need to query your graph when using the following parsers:

Query structure

Every Query holds a single a where property being an object, to select one branch of the graph, or an array of objects, to select many branches of the graph (OR statement).

The where property splits in 3 kinds: token, group, collection - offering a dedicated set of options to match against the given kind.

The name property accepts a RegExp for a value. These resources will help you debug your regular expressions:

Where Token

Where Group

Where Collection

Use cases

Select tokens from a specific collection

Select tokens from several collections matching a naming pattern

Select tokens from a specific group

Select tokens of a specific type from a collection

Select all tokens from a collection and from groups matching a naming pattern

Select tokens from several groups with different names

GitHub

Learn how to distribute your design tokens from Specify to your GitHub repositories 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 new Advanced Repositories 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.

Installation

Go to the applications catalog on the Destinations page
Select GitHub
Click on "Connect"
Select the repositories you want Specify to have access to
You will now be able to connect your Specify and your GitHub repositories together 🎉

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"
Select your GitHub account
Select the GitHub repository you want to distribute your design data to
Name for your configuration file (Learn More ↗︎)
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

Parsers

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

Not familiar with parsers? Head over to the existing parsers documentation and learn more about why you need them and how to use them.

We're currently working on making our existing parsers compatible with the SDTF. We'll update this page accordingly.

General properties

You must set a name and your desired output for each parser:

The name is the name of the parser
The output property indicates which type of output you want the parser to produce

Output types

Parsers support none, some or more output types, please refer to dedicated parser pages for details.

File

Use case: the parser is expected to produce exactly one file.

type FileOutput = {
  type: 'file';
  filePath: string;
}

Directory

Use case: the parser is expected to produce 0 to N files, all placed in the given directoryPath.

type DirectoryOutput = {
  type: 'directory';
  directoryPath: string;
}

Example with the to-css-custom-properties parser:

"parsers": [
  {
    "name": "to-css-custom-properties",
    "output": {
      "type": "file",
      "filePath": "style.css"
    }
  }
  // ...
]

Available parsers

Parser

Description

Usage example

This parser helps you change the case of names or modes over a SDTF graph.

This parser helps you convert the color formats of color compatible tokens over a SDTF graph.

This parser helps you filter a SDTF graph.

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

This parser helps you transform design tokens in CSS Custom Properties.

This parser helps you get your design tokens as a SDTF graph in JSON.

This parser helps you generate a Tailwind theme from all your design tokens coming from Specify.

This parser helps you pull design tokens as JavaScript objects for all token types and their respective getter functions.

This parser helps you pull design tokens in JSON with token values in JSON or CSS.

This parser helps you pull design tokens as TypeScript objects for all token types and their respective getter functions.

to-css-custom-properties

This parser helps you transform design tokens into CSS Custom Properties.

Interface

interface parser {
  name: 'to-css-custom-properties';
  output: {
    type: 'file';
    filePath: string;
  };
  options?: {
    tokenNameTemplate?: string;
    selectorTemplate?: string;
    includeCoreTokensInScopes?: boolean;
  };
}

Options

Parameter

Required

Type

Default

Description

selectorTemplate

optional

string

tokenNameTemplate

optional

string

includeCoreTokensInScopes

optional

boolean

false

When set to true, you will have both core tokens and alias tokens in each CSS scopes thus making alias tokens always resolvable.

Basic usage

A design token can have modes, be nested in groups and be part of a collection. The following use case will generate a single CSS file containing core tokens and semantic tokens.

{
  "colors": {
    "$collection": { "$modes": ["Light", "Dark"] },
    "core": {
      "blue-100": {
        "$type": "color",
        "$description": "token 1 aliased with n modes within collection within n groups",
        "$value": {
          "Light": {
            "red": 219,
            "blue": 254,
            "alpha": 1,
            "green": 236,
            "model": "rgb"
          },
          "Dark": {
            "red": 41,
            "blue": 67,
            "alpha": 1,
            "green": 52,
            "model": "rgb"
          }
        }
      },
      "blue-700": {
        "$type": "color",
        "$description": "token 2 aliased with n modes within collection within n groups",
        "$value": {
          "Light": {
            "red": 17,
            "blue": 249,
            "alpha": 1,
            "green": 125,
            "model": "rgb"
          },
          "Dark": {
            "red": 96,
            "blue": 250,
            "alpha": 1,
            "green": 168,
            "model": "rgb"
          }
        }
      }
    },
    "semantic": {
      "background": {
        "button": {
          "primary": {
            "hover": {
              "$type": "color",
              "$description": "alias token with n modes within collection within n groups",
              "$value": {
                "Dark": {
                  "$mode": "Dark",
                  "$alias": "colors.core.blue-100"
                },
                "Light": {
                  "$mode": "Light",
                  "$alias": "colors.core.blue-700"
                }
              }
            }
          }
        }
      }
    }  
  }
}

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate tokens as CSS Custom Properties",
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "tokens.css"
          },
          "options": {
            "tokenNameTemplate": "--{{groups}}-{{token}}",
            "selectorTemplate": "[data-theme=\"{{mode}}\"]",
            "includeCoreTokensInScopes": true
          }
        }
      ]
    }
  ]
}

tokens.css

[data-theme="dark"] {
  --core-blue-100: rgb(41, 52, 67);
  --core-blue-700: rgb(96, 168, 250);
  --semantic-background-button-primary-hover: var(--core-blue-100);
}
[data-theme="light"] {
  --core-blue-100: rgb(219, 236, 254);
  --core-blue-700: rgb(17, 125, 249);
  --semantic-background-button-primary-hover: var(--core-blue-700);
}

Head towards our templates section to see how you can use this parser with others to suit a common use case when working with CSS.

to-style-dictionary

This parser helps you generate Style Dictionary raw token files for all your design tokens coming from Specify.

Unlike the existing to-style-dictionary parser, this one doesn't have any options yet.

Interface

interface parser {
  name: 'to-style-dictionary';
  output: {
    type: 'directory';
    directoryPath: string;
  };
}

General output rules

A collection will generate a folder at the top level
1. The default level refers to the SDTF Token Type associated SD Category → {collectionName?}/{SDCategory}
2. The next folder level is the name of the potential first group containing the token → {collectionName?}/{SDCategory}/{1stLevelGroupName?}
3. The default filename is the name of the first group, or the name of the each mode the token might have, or base.json → {collectionName?}/{SDCategory}/{ mode? | 1stLevelGroupName? | base}.json (priority order for filename: groupName > mode > base)
The token path inside the file must match the token file path with the following priority order: collection > SDCategoryType > Mode > Groups
- {collectionName?}/{SDCategory}/{1stLevelGroupName? | mode? | base}.json → { collection: {type: {mode: { groupName: { tokenName: ... }}}}

Basic usage

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

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate Style Dictionary raw token files",
      "parsers": [
        {
          "name": "to-style-dictionary",
          "output": {
            "type": "directory",
            "directoryPath": "output/tokens/"
          }
        }
      ]
    }
  ]
}

color/light/core.json

{
  "colors": {
    "color": {
      "light": {
        "core": {
          "blue-100": {
            "value": "rgb(255, 255, 255)",
            "type": "color",
            "description": "token 1 aliased with n modes within collection within n groups"
          },
          "blue-700": {
            "value": "rgb(255, 200, 255)",
            "type": "color",
            "description": "token 2 aliased with n modes within collection within n groups"
          }
        }
      }
    }
  }
}

color/dark/core.json

{
  "colors": {
    "color": {
      "dark": {
        "core": {
          "blue-100": {
            "value": "rgb(229, 29, 29)",
            "type": "color",
            "description": "token 1 aliased with n modes within collection within n groups"
          },
          "blue-700": {
            "value": "rgb(229, 0, 0)",
            "type": "color",
            "description": "token 2 aliased with n modes within collection within n groups"
          }
        }
      }
    }
  }
}

color/light/semantic.json

{
  "colors": {
    "color": {
      "light": {
        "semantic": {
          "background": {
            "button": {
              "primary": {
                "hover": {
                  "value": "{colors.color.light.core.blue-700}",
                  "type": "color",
                  "description": "alias token with n modes within collection within n groups"
                }
              }
            }
          }
        }
      }
    }
  }
}

to-tailwind

This parser helps you generate a Tailwind theme from all your design tokens coming from Specify.

Interface

interface parser {
  name: 'to-tailwind';
  output: {
    type: 'file';
    filePath: string; // e.g theme.js
  };
  options?: {
    useCssVariable?: boolean;
    cssVariableTemplate?: {
      tokenNameTemplate?: string;
      tokenNotInCollectionNameTemplate?: string;
    }
  };
}

Basic usage

{
  "colors": {
    "$collection": {
      "$modes": [
        "light",
        "dark"
      ]
    },
    "aliases": {
      "border": {
        "active": {
          "$type": "color",
          "$value": {
            "dark": {
              "$alias": "colors.core.label.blue-base",
              "$mode": "dark"
            },
            "light": {
              "$alias": "colors.core.label.blue-base",
              "$mode": "light"
            }
          }
        }
      }
    },
    "core": {
      "label": {
        "blue-base": {
          "$type": "color",
          "$value": {
            "dark": {
              "model": "rgb",
              "red": 96,
              "green": 168,
              "blue": 250,
              "alpha": 1
            },
            "light": {
              "model": "rgb",
              "red": 17,
              "green": 125,
              "blue": 249,
              "alpha": 1
            }
          }
        },
        "blue-lighter": {
          "$type": "color",
          "$value": {
            "dark": {
              "model": "rgb",
              "red": 41,
              "green": 52,
              "blue": 67,
              "alpha": 1
            },
            "light": {
              "model": "rgb",
              "red": 219,
              "green": 236,
              "blue": 254,
              "alpha": 1
            }
          }
        }
      }
    }
  },
  "dimensions": {
    "$collection": {
      "$modes": [
        "desktop",
        "mobile"
      ]
    },
    "base": {
      "dimension-01": {
        "$type": "dimension",
        "$value": {
          "mobile": {
            "value": 2,
            "unit": "px"
          },
          "desktop": {
            "value": 4,
            "unit": "px"
          }
        }
      },
      "dimension-02": {
        "$type": "dimension",
        "$value": {
          "mobile": {
            "value": 4,
            "unit": "px"
          },
          "desktop": {
            "value": 8,
            "unit": "px"
          }
        }
      }
    }
  }
}

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate tokens as a Tailwind theme",
      "parsers": [
        {
          "name": "to-tailwind",
          "output": {
            "type": "file",
            "filePath": "theme.js"
          }
        }
      ]
    }
  ]
}

theme.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: {
        colors: {
          core: {
            label: {
              'blue-lighter': {
                'dark': 'rgb(41, 52, 67)',
                'light': 'rgb(219, 236, 254)'
              },
              'blue-base': {
                'dark': 'rgb(96, 168, 250)',
                'light': 'rgb(17, 125, 249)'
              }
            }
          },
          aliases: {
            border: {
              active: {
                'dark': 'rgb(98, 77, 227)',
                'light': 'rgb(235, 33, 33)'
              }
            }
          }
        }
      },
      spacing: {
        'dimensions-base-dimension-01-desktop': '4px',
        'dimensions-base-dimension-01-mobile': '2px',
        'dimensions-base-dimension-02-desktop': '8px',
        'dimensions-base-dimension-02-mobile': '4px'
      }
    }
  }
}

Advanced usage - token values as CSS variables

{
  "colors": {
    "$collection": {
      "$modes": [
        "light",
        "dark"
      ]
    },
    "aliases": {
      "border": {
        "active": {
          "$type": "color",
          "$value": {
            "dark": {
              "$alias": "colors.core.label.blue-base",
              "$mode": "dark"
            },
            "light": {
              "$alias": "colors.core.label.blue-base",
              "$mode": "light"
            }
          }
        }
      }
    },
    "core": {
      "label": {
        "blue-base": {
          "$type": "color",
          "$value": {
            "dark": {
              "model": "rgb",
              "red": 96,
              "green": 168,
              "blue": 250,
              "alpha": 1
            },
            "light": {
              "model": "rgb",
              "red": 17,
              "green": 125,
              "blue": 249,
              "alpha": 1
            }
          }
        },
        "blue-lighter": {
          "$type": "color",
          "$value": {
            "dark": {
              "model": "rgb",
              "red": 41,
              "green": 52,
              "blue": 67,
              "alpha": 1
            },
            "light": {
              "model": "rgb",
              "red": 219,
              "green": 236,
              "blue": 254,
              "alpha": 1
            }
          }
        }
      }
    }
  },
  "dimensions": {
    "$collection": {
      "$modes": [
        "desktop",
        "mobile"
      ]
    },
    "base": {
      "dimension-01": {
        "$type": "dimension",
        "$value": {
          "mobile": {
            "value": 2,
            "unit": "px"
          },
          "desktop": {
            "value": 4,
            "unit": "px"
          }
        }
      },
      "dimension-02": {
        "$type": "dimension",
        "$value": {
          "mobile": {
            "value": 4,
            "unit": "px"
          },
          "desktop": {
            "value": 8,
            "unit": "px"
          }
        }
      }
    }
  }
}

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate tokens as a Tailwind theme",
      "parsers": [
        {
          "name": "to-tailwind",
          "output": {
            "type": "file",
            "filePath": "theme.js"
          },
          "options": {
            "useCssVariable": true,
            "cssVariableTemplate": {
              "tokenNameTemplate": "--{{groups}}-{{token}}"
            }
          }
        }
      ]
    }
  ]
}

theme.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: {
        colors: {
          core: {
            label: {
              'blue-base': {
                dark: 'var(--core-label-blue-base)',
                light: 'var(--core-label-blue-base)'
              },
              'blue-lighter': {
                dark: 'var(--core-label-blue-lighter)',
                light: 'var(--core-label-blue-lighter)'
              }
            }
          },
          aliases: {
            border: {
              active: {
                dark: 'var(--aliases-border-active)',
                light: 'var(--aliases-border-active)'
              }
            }
          }
        }
      },
      spacing: {
        'dimensions-base-dimension-01-desktop': 'var(--base-dimension-01)',
        'dimensions-base-dimension-01-mobile': 'var(--base-dimension-01)',
        'dimensions-base-dimension-02-desktop': 'var(--base-dimension-02)',
        'dimensions-base-dimension-02-mobile': 'var(--base-dimension-02)'
      }
    }
  }
}

to-sdtf

This parser helps you get your design tokens as a SDTF graph in JSON.

Interface

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

Basic usage

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

.specifyrc.json

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

tokens.json

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

to-javascript

This parser helps you pull design tokens as JavaScript objects for all token types and their respective helper functions.

Interface

interface parser {
  name: 'to-javascript';
  output: {
    type: 'file';
    filePath: string;
  };
  options?: {
    typescript?: boolean;
    moduleExport?: 'es6' | 'commonjs';
  };
}

Basic usage

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

.specifyrc.json

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

tokens.js

/** 
* @enum {string} All the valid paths for the collection colors.
* Use it when calling `getColorsTokenByMode`
*/
export const colorsColorPath = {
  'colors.Core.blue-100': 'colors.Core.blue-100',
  'colors.Core.blue-700': 'colors.Core.blue-700',
  'colors.semantic.background.button.primary.hover': 'colors.semantic.background.button.primary.hover'
};

/**
* All the modes of the collection colors.
* Use it when calling `getColorsTokenByMode`
*/
export const colorsModes = [ 'light', 'dark' ];

/** 
* All the tokens of the collection colors.
* Use `getColorsTokenByMode` to retrieve the tokens
*/
export const colors = {
  'colors.Core.blue-100': { dark: 'rgb(229, 29, 29)', light: 'rgb(255, 255, 255)' },
  'colors.Core.blue-700': { dark: 'rgb(229, 0, 0)', light: 'rgb(255, 200, 255)' },
  'colors.semantic.background.button.primary.hover': { dark: 'rgb(229, 29, 29)', light: 'rgb(255, 200, 255)' }
};

/**
* Retrieve a token for the collection 'colors'.
* @param {keyof typeof colorsPath} path - The path to the token
* @param {'light' | 'dark'} mode - The mode of the token you want to retrieve 
* @returns {number | string} The value of a token for a given mode
*/
export function getColorsTokenByMode(path, mode) {
  if (!colors[path]) {
    throw new Error("Path: '" + path + "' doesn't exist for collection 'colors'. Here are all the valid paths for each type:" + `
- color:
    - colors.Core.blue-100
    - colors.Core.blue-700
    - colors.semantic.background.button.primary.hover`)
  }

  if (!colors[path][mode]) {
    throw new Error("Invalid mode '" + mode.toString() + "' for collection 'colors' at path '" + path + "', here are all the valid modes:\n- " + Object.keys(colors[path]).join('\n- '))
  }

  return colors[path][mode]
}

to-react-native

This parser helps you pull design tokens as a theme compatible with React Native and their respective helper functions.

Interface

Basic usage

to-json

This parser helps you pull design tokens in JSON with token values in JSON or CSS.

Interface

Basic usage - JSON token values

Advanced usage - CSS token values

to-typescript

This parser helps you pull design tokens as TypeScript objects for all token types and their respective helper functions.

Interface

Basic usage

filter

This parser helps you filter a SDTF graph.

Interface

Options

Parameter

Required

Type

Default

Description

Basic usage: select all tokens from a group in a collection

We want to get all tokens in all groups named "info"
We also want to get the parent collection...
... and all children tokens within the "info" group(s)
We eventually generate our transformed SDTF graph in a JSON file thanks to the to-sdtf parser.

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

required

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

change-case

This parser helps you change the case of names or modes over a SDTF graph.

Interface

interface parser {
  name: 'change-case';
  options: {
    change?: 'name' | 'modes';
    toCase:
      | 'camelCase'
      | 'capitalCase'
      | 'constantCase'
      | 'kebabCase'
      | 'noCase'
      | 'pascalCase'
      | 'pascalSnakeCase'
      | 'pathCase'
      | 'sentenceCase'
      | 'snakeCase'
      | 'trainCase';
    applyTo:
      | { collection: string | true }
      | { group: string | true }
      | { token: string | true }
      | SDTFQuery;
  };
}

Options

Parameter

Required

Type

Default

Description

change

optional

'names'

Change the names or the modes of the selected items.

toCase

required

applyTo

required

Basic usage

This example helps you transform in kebabCase the name all collections, groups, tokens and modes. Use this example if you want to generate CSS Custom properties with the to-css-custom-properties parser.

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

We change the case of the token names and the modes to kebabCase. We applyTo the collection level so we transform in kebabCase:

the collection names
the group names
the token names
the mode names

We eventually generate our transformed SDTF graph in a JSON file thanks to the to-sdtf parser.

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Format all token names and modes to kebabCase and generate tokens in JSON",
      "parsers": [
        {
          "name": "change-case",
          "options": {
            "change": "names",
            "toCase": "kebabCase",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "change-case",
          "options": {
            "change": "modes",
            "toCase": "kebabCase",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}

tokens.json

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

convert-color

This parser helps you convert color formats of color tokens.

Interface

Options

Basic usage

We convert all colors from our SDTF graph in hsl.

convert-dimension

This parser helps you convert units of dimension tokens.

Interface

Options

Parameter

Required

Type

Default

Description

Basic usage

We convert all colors from our SDTF graph in hsl.

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 rules, called parsers.

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

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

Template

Description

CSS Custom Properties

This template is dedicated for Web developers using CSS. It helps you generate all types of design tokens as CSS Custom Properties in their respective CSS file.

This example uses four different parsers:

filter to target on a specific collection named "Colors" that contains our colors
convert-color to convert our colors in HSL
change-case to change the name of our tokens and modes to kebabCase
to-css-custom-properties to generate a CSS file containing our tokens

This template is an example among others. Head toward the to-css-custom-properties page to get all available options.

CLI configuration

When using the CLI, you need to fill three properties:

repository is @organization/repository
personalAccessToken which you can generate in your account settings
rules lets you transform tokens by chaining parsers

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

GitHub configuration

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

repository is @organization/repository
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",
  "rules": [
    {
      "name": "css",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "collection": "Colors",
                "select": {
                  "parents": true,
                  "children": true
                }
              }
            }
          }
        },
        {
          "name": "convert-color",
          "options": {
            "toFormat": "hsl",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "change-case",
          "options": {
            "change": "names",
            "toCase": "kebabCase",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "change-case",
          "options": {
            "change": "modes",
            "toCase": "kebabCase",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "tokens.css"
          }
        }
      ]
    }
  ]
}

SDTF

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

This example uses the following parser:

to-sdtf 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 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 in SDTF",
      "parsers": [
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "output/tokens.json"
          }
        }
      ]
    }
  ]
}

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

repository is @organization/repository
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",
  "rules": [
    {
      "name": "Generate tokens in JSON",
      "parsers": [
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "output/tokens.json"
          }
        }
      ]
    }
  ]
}

Tailwind

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

This example uses the following parser:

to-tailwind to generate your design tokens as a Tailwind theme

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 as a Tailwind theme",
      "parsers": [
        {
          "name": "to-tailwind",
          "output": {
            "type": "file",
            "filePath": "theme.js"
          }
        }
      ]
    }
  ]
}

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

repository is @organization/repository
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",
  "rules": [
    {
      "name": "Generate tokens as a Tailwind theme",
      "parsers": [
        {
          "name": "to-tailwind",
          "output": {
            "type": "file",
            "filePath": "theme.js"
          }
        }
      ]
    }
  ]
}

REST API

The Specify API lets you extend Specify functionalities beyond what we provide out of the box.

New to Specify? Head over to the existing REST API documentation to learn more about why it can be useful for your team and how to use it.

Endpoint

Specify provides the following endpoint to help you get design tokens and assets from a Specify repository.

https://api.specifyapp.com/v2/{workspace}/repository/{repository}/execute-rule

Parameters

Get tokens graph

POST https://api.specifyapp.com/v2/{workspace}/repository/{repository}/execute-rule

Get design tokens and assets from a Specify repository. You can only execute a single rule with this endpoint.

Path Parameters

Name

Type

Description

workspace*

String

The name of your organization in Specify. For instance, in this URL https://specifyapp.com/ @specifyapp/Seeds the workspace is "@specifyapp".

name

String

The name of the Specify repository containing the design data you're requesting. For instance, in this URL https://specifyapp.com / @specifyapp/Seeds the repository is "Seeds".

Request Body

Name

Type

Description

parsers*

Object or Array

Can contain an object or an array of objects. Each object corresponds to a specific parser.

name*

The name of your rule

Once you have your personal access token, you can pass it within the Authorization header of your request.

Example

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

curl -X POST 'https://api.specifyapp.com/v2/@acme-inc/repository/all-design-data/execute-rule' \
--header 'Authorization: <your-personal-access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "SDTF",
    "parsers": [
        {
            "name": "as-is",
            "output": {
                "type": "file",
                "filePath": "tokens.json"
            }
        }
    ]
}'

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.

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 to-sdtf parser.
The middle panel contain your Specify configuration rule.
The right side panel displays the generated code

Concepts

Token types

Types define every type of design token and asset Specify is compatible with. Use them to target specific types of design data you want to pull from Specify and manage with rules and parsers.

Introduction

Types define every type of design token and asset Specify is compatible with. Use them to target specific types of design tokens and assets you want to pull from Specify.

In Specify, types are displayed as "categories" of design data you can create and find in your Specify repository.

Specify is compatible with the following design tokens and assets under the TokenType type.

Design tokens

Border

A border is a line surrounding a UI element. According to your target platform capabilities, you can define the border to go inside (inner border), outside (outer border), or between them (center).

Borders are considered as composite design tokens ↗ because they are composed of several design tokens.

Looking for border radius? You can add them as a Measurement type.

interface BorderValue {
  color: {
    value: ColorValue;
  };
  type:
    | 'none'
    | 'hidden'
    | 'dotted'
    | 'dashed'
    | 'solid'
    | 'double'
    | 'groove'
    | 'ridge'
    | 'inset'
    | 'outset';
  width: {
    value: MeasurementValue;
  };
  align?: string;
  radii?: MeasurementValue;
  rectangleCornerRadii?: Array<MeasurementValue>;
  dashes?: Array<MeasurementValue>;
}

Color

Colors have meaning and support the purpose of the content, communicating things like hierarchy of information, interactive states, and the difference between distinct elements in your UI. Among all your design token types, color is surely one of the most important ones.

interface ColorValue {
  r: number;
  g: number;
  b: number;
  a: number;
}

Depth

The Depth token type sets a UI element's position on the z-axis. More commonly called z-index on Web ↗ and zIndex on Android ↗ and iOS ↗.

interface DepthValue {
  depth: number;
}

Duration

Represents the length of time in milliseconds an animation or animation cycle takes to complete, such as 200 milliseconds (cf DTCG ↗).

interface DurationValue {
  duration: number;
  unit: string;
}

Gradient

A gradient is the gradual blending from one color to another. It enables the designer to almost create a new color. It makes objects stand out by adding a new dimension to the design and adding realism to the object. In simple terms, gradients add depth.

Gradients are considered as composite design tokens ↗ because they are composed of several design tokens.

interface StepForGradient {
  type: string;
  color: {
    value: ColorValue;
  };
  position: number;
}

interface Gradient {
  angle: string;
  colors: Array<StepForGradient>;
}

interface GradientValue {
  gradients: Array<Gradient>;
}

Measurement

Measurement or Dimension ↗ design tokens help you define size values.

Common design tokens can be defined from this type:

internal margins
external margins
a spacing scale
a border width
a breakpoint
a font size
border radii...

interface MeasurementValue {
  measure: number;
  unit?: string;
}

Opacity

Opacity design tokens help you set the opacity of UI elements.

interface OpacityValue {
  opacity: number;
}

Shadow

Shadows help you communicate components elevation in your UIs. Popular variations and names include box-shadow, drop shadow, and many more.

Shadows are considered as composite design tokens ↗ because they are composed of several design tokens.

type ShadowValue = Array<{
  color: {
    value: ColorValue;
  };
  offsetX: {
    value: MeasurementValue;
  };
  offsetY: {
    value: MeasurementValue;
  };
  blur: {
    value: MeasurementValue;
  };
  spread?: {
    value: MeasurementValue;
  };
  isInner: boolean;
}>;

Text Style

Text styles or typography helps your UI be usable. They create balance, hierarchy and structure for your content. Some say that "Web is 95% typography". To push this even further let's say UI are 95% typography. In other words, pay a great deal of attention to typography.

A text style is composed of several child design decisions that could be considered as single design tokens like:

a line-height
a font size
a letter spacing
a font name

Text styles are considered as composite design tokens ↗ because they are composed of several design tokens.

export type TextTransformValue =
  | 'none'
  | 'capitalize'
  | 'uppercase'
  | 'lowercase';

export type TextDecorationValue =
  | 'none'
  | 'underline'
  | 'overline'
  | 'line-through'
  | 'dashed'
  | 'wavy';

export type HorizontalAlignValue =
  | 'initial'
  | 'left'
  | 'right'
  | 'center'
  | 'justify'
  | 'start'
  | 'end'
  | 'justify-all'
  | 'match-parent';

export type VerticalAlignValue =
  | 'initial'
  | 'baseline'
  | 'sub'
  | 'super'
  | 'text-top'
  | 'text-bottom'
  | 'middle'
  | 'top'
  | 'bottom';
  
export interface TextStyleValue {
  color?: {
    value: ColorValue;
  };
  font: {
    value: FontValue;
  };
  fontSize: {
    value: MeasurementValue;
  };
  lineHeight?: {
    value: MeasurementValue;
  };
  letterSpacing?: {
    value: MeasurementValue;
  };
  textAlign?: {
    horizontal?: HorizontalAlignValue;
    vertical?: VerticalAlignValue;
  };
  textTransform?: TextTransformValue;
  fontVariant?: Array<string>;
  textDecoration?: Array<TextDecorationValue>;
  textIndent?: {
    value: MeasurementValue;
  };
}

Example

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Borders",
      "path": "borders.json",
      "filter": {
        "types": [
          "border"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Colors",
      "path": "colors.json",
      "filter": {
        "types": [
          "color"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / zIndex",
      "path": "zIndex.json",
      "filter": {
        "types": [
          "depth"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / durations",
      "path": "durations.json",
      "filter": {
        "types": [
          "duration"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Gradients",
      "path": "gradients.json",
      "filter": {
        "types": [
          "gradient"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Measurements",
      "path": "measurements.json",
      "filter": {
        "types": [
          "measurement"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Opacities",
      "path": "opacities.json",
      "filter": {
        "types": [
          "opacity"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Shadows",
      "path": "shadows.json",
      "filter": {
        "types": [
          "shadow"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Text Styles",
      "path": "textStyles.json",
      "filter": {
        "types": [
          "textStyle"
        ]
      }
    }
  ]
}

Assets

Bitmap

Bitmaps are raster images you can use in many contexts. They are basically any image you can display in a UI that is a .png, .jpeg, .webp, .avif...

interface BitmapValue {
  url: string;
  dimension?: number;
  format?: string;
}

Font

Fonts are files containing typefaces used by your text styles.

In Specify, all font files are stored as .ttf files by default. You can pull and convert them on the fly thanks to the convert-font ↗ parser.

export type Provider = 'Custom font' | 'Google Fonts';

export type FontWeightKeys = '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';

export interface FontValue {
  fontFamily: string;
  fontPostScriptName: string;
  fontWeight?: string | number;
  fontFileMissing?: boolean;
  isItalic?: boolean;
  provider?: Provider;
  url?: string;
  format?: 'ttf';
}

Vector

By "vectors" we mean vector images (e.g., SVG and PDF files). You can use them for 2 main purposes: iconography and illustration. In the following section we will only focus on icons.

Icons act a visual aids to help users complete tasks. We advise you to have an harmonic set of icons you can use to draw attention to specific actions.

interface VectorValue {
  url: string;
  format: 'svg' | 'pdf';
}

Example

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Images",
      "path": "bitmaps.json",
      "filter": {
        "types": [
          "bitmap"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Fonts",
      "path": "fonts.json",
      "filter": {
        "types": [
          "font"
        ]
      }
    }
  ]
}

.specifyrc.js

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Design Tokens / Icons",
      "path": "vectors.json",
      "filter": {
        "types": [
          "vector"
        ]
      }
    }
  ]
}

Best practices

Set your personal access token as a variable

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

Using an .env variable in a config file in JavaScript

.env

SPECIFY_TOKEN=ab83f8f49f5c65456c7b1fe70efbc804aa08f87150214aa984d4125945ed8283bash

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

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

Using a variable in a flag with the CLI

Set your personal access token as an environment variable and interpolate it in the CLI wit the flag -p.

specify pull -p $SPECIFY_TOKEN

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

V1

Getting started

Introduction

What is Specify?

Getting started

Introduction

Before getting started

1. Install the CLI

2. Create your Specify config file

3. Add your Specify repository

4. Add your personal access token

5. Pull your design tokens and assets

Glossary

Design API

Source

Destination

Pipeline

Repository

Token type

Configuration

Rule

Parser

Advanced Repository

Getting started

Introducing the Specify Design Token Format

Useful links

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

Tokens Studio

Before getting started

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

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

From a public URL

From a private URL

GitHub

Azure DevOps

GitLab

JSONBin

3. How to update your JSON File

4. Non-supported design token types

CLI & Config

1. Install the CLI

2. Create your Specify configuration file

3. Properties to update in the configuration file before using it:

4. CSS output example

Querying a SDTF graph

Introduction

Compatible parsers

Query structure

Where Token

Where Group

Where Collection

Use cases

Select tokens from a specific collection

Select tokens from several collections matching a naming pattern

Select tokens from a specific group

Select tokens of a specific type from a collection

Select all tokens from a collection and from groups matching a naming pattern

Select tokens from several groups with different names

GitHub

Prerequisites

Installation

Connecting Specify and GitHub

Useful resources

Parsers

General properties

Output types

File

Available parsers

to-css-custom-properties

Interface

Options

Basic usage

to-style-dictionary