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.
All of these features come together in the Specify Advanced Repository.
Useful links
In a more practical sense, the SDTF opens up compatibility with and as a source alongside the existing Figma local styles compatibility. It also creates opportunities to create code output that includes aliases, modes, and collections.
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.
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.
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.
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
Fill PRIVATE-TOKEN in the key field
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
Following your choice, fill in the key field either with X-MASTER-KEY or X-ACCESS-KEY
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)
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).
Type Query = { where: Where | Array<Where> }
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:
Select all tokens from a collection and from groups matching a naming pattern
.specifyrc.json
{
"version": "2",
"repository": "@organization/repository",
"personalAccessToken": "<your-personal-access-token>",
"rules": [
{
"name": "Get color tokens from the 'Android' collection and from all groups named 'components'",
"parsers": [
{
"name": "filter",
"options": {
"where": {
"collection": "^Android$",
"andWhere": {
"group": "^components$",
"andWhere": {
"token": ".*",
"withTypes": {
"include": ["color"]
},
"select": {
"token": true,
"parents": true
}
}
}
}
}
}
]
}
]
}
Select tokens from several groups with different names
.specifyrc.json
{
"version": "2",
"repository": "@organization/repository",
"personalAccessToken": "<your-personal-access-token>",
"rules": [
{
"name": "Get tokens from the group named 'Components' and/or from the group named 'Semantic'",
"parsers": [
{
"name": "filter",
"options": {
"where": {
"collection": "^Android$",
"andWhere": {
"group": "^Components$|^Semantic$",
"andWhere": {
"token": ".*",
"select": {
"token": true,
"parents": true
}
}
}
}
}
}
]
}
]
}
A account
The plugin installed in your Figma
A , , , or account
Select "Sync from Figma Variables & Tokens Studio" ()
Create and Paste this GitHub file URL such as: https://api.github.com/repos///contents/
Select "Bearer Token" as the auth system & paste your personal access token from GitHub ( and be sure to check the repo section)
Select "Basic Auth" as auth system. Use your Azure DevOps email and a new Azure DevOps personal access token with Full Access or Code -> Read permissions.
Depending on your choice, you can use your master key or an access key. on JSONBin.
They will be released in future updates. However, if you have urgent needs for Specify to be compatible with one of them, .
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
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
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
to-style-dictionary
This parser helps you generate Style Dictionary raw token files for all your design tokens coming from Specify.
A collection will generate a folder at the top level
The default level refers to the SDTF Token Type associated SD Category → {collectionName?}/{SDCategory}
The next folder level is the name of the potential first group containing the token → {collectionName?}/{SDCategory}/{1stLevelGroupName?}
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
{
"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"
}
}
}
}
}
}
}
}
}
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.
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
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"
4. Connect the Specify Repository in your Widget
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.
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.
npm install @specifyapp/cli
yarn global add @specifyapp/cli
2. Create your Specify configuration file
To create your Specify config file, you need to follow these steps:
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.
to-css-custom-properties
This parser helps you transform design tokens into CSS Custom Properties.
Interface
Options
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.
to-javascript
This parser helps you pull design tokens as JavaScript objects for all token types and their respective helper functions.
Interface
Basic usage
to-sdtf
This parser helps you get your design tokens as a SDTF graph in JSON.
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
Go to the applications catalog
Name for your configuration file ()
Unlike , this one doesn't have any options yet.
A Token type is a type of design token or asset supported by Specify like a colors, a text style or an icon. .
Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards. .
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.
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.
Select "Advanced Repository" ()
Select the design tokens format you want to collect from your Figma file.
Use the Sync button to update your Variables and/or Styles with Specify. Now you are ready to ! 🎉
Get a personal access token .
Parameter
Required
Type
Default
Description
Head towards our to see how you can use this parser with others to suit a common use case when working with CSS.
{
"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]
}
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"
}
}
]
}
]
}
{
"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"
}
}
]
}
]
}
{
"version": "2",
"repository": "@organization/repository",
// Only use the personalAccessToken when working with the CLI
"personalAccessToken": "<your-personal-access-token>",
"rules": [
{
"name": "To React Native theme",
"parsers": [
{
"name": "to-react-native",
"output": {
"type": "file",
"filePath": "public/theme.js"
}
}
]
}
]
}
tokens.js
/**
* @typedef {'primitive.spacing.1'} DimensionPath - All the valid paths for the tokens of type dimension.
* To use this type you can do: `@type {import('path/to/myTokensFile').DimensionPath}`
*/
/**
* @typedef {'themedColor.highEmphasis'} ColorPath - All the valid paths for the tokens of type color.
* To use this type you can do: `@type {import('path/to/myTokensFile').ColorPath}`
*/
/**
* @typedef {DimensionPath | ColorPath} AllPath - All possible paths
*/
/**
* @typedef {typeof pathsByType} PathsByType - All the paths for a given token type. Needed for `getTokensByType`
*/
const pathsByType = /** @type {const} */ ({
dimension: [ 'primitive.spacing.1' ],
color: [ 'themedColor.highEmphasis' ]
});
/**
* @typedef {typeof colorModes[number]} ColorModes - All the valid modes of color.
* To use this type you can do: `@type {import('path/to/myTokensFile').ColorModes}`
*/
export const colorModes = /** @type {const} */ ([ 'dark', 'light' ]);
/**
* @typedef {typeof themedColorModes[number]} ThemedcolorModes - All the valid modes of themedColor.
* To use this type you can do: `@type {import('path/to/myTokensFile').ThemedcolorModes}`
*/
export const themedColorModes = /** @type {const} */ ([ 'light', 'dark' ]);
/**
@typedef {ColorModes | ThemedcolorModes} AllMode - All the available modes
*/
/**
* @typedef {typeof tokens} Tokens - All the tokens.
* Use `getTokenByMode` to retrieve one.
*/
export const tokens = /** @type {const} */ ({
'primitive.spacing.1': '4px',
'themedColor.highEmphasis': { dark: '#ffffff', light: '#000000' }
});
/**
* Retrieve any token for a given mode. If available, the default mode will be: 'default'
* @template {AllPath} Path - A generic extending all the possible paths
* @template {Tokens[Path] extends Record<string, any>
? keyof Tokens[Path]
: undefined} Mode - A generic representing all the valid modes for a given path
* @template {Tokens[Path] extends Record<string, any>
? Tokens[Path][Mode extends undefined ? never : Mode]
: Tokens[Path]} Return - The return type
* @param {Path} path - The path to the token
* @param {Mode} mode - The mode of the token you want to retrieve
* @returns {Return} - The value of a token for a given mode
*/
export function getTokenByMode(path, mode) {
if (!tokens[path]) {
throw new Error("Path: '" + path + "' doesn't exist. Here are all the valid paths:\n- " + Object.keys(tokens).join('\n- '))
}
if (typeof tokens[path] !== 'object') {
return tokens[path] ;
}
if (!mode) throw new Error('Mode is undefined but it should be one of ' + Object.keys(tokens[path]).join(', ') + ' for path: ' + path);
if (!tokens[path][mode]) {
throw new Error("Invalid mode '" + mode.toString() + " at path '" + path + "', here are all the valid modes:\n- " + Object.keys(tokens[path]).join('\n- '))
}
return tokens[path][mode]
}
/**
* Retrieve all the tokens for a specific type (color, dimension, etc...).
* Note that the value will either be a string or an object if the token has modes
* @template {keyof PathsByType} Type - A generic extending all the possible types
* @template {Tokens[PathsByType[Type][number]]} Token - A generic representing a union of all the outputs
* @param {Type} type - The path to the token
* @returns {Array<Token>} - An array with all the values
*/
export function getTokensByType(type) {
if (!pathsByType[type]) {
throw new Error('The type: \'' + type + '\' does not exist')
}
return pathsByType[type].map(path => tokens[path]);
}
Whether to resolve the aliases of the graph.
Thus, preventing aliases to become unresolvable when their source is not included in the selected items.
allowUnresolvableAliases
optional
boolean
true
Whether to allow unresolvable aliases to flow through.
This option is only available when resolveAliases = true
deduplicate
optional
true | undefined
undefined
When you target tokens from different areas in your graph you can end up with tokens that will have the same name which will lead to an override. When set to true, this option will suffix tokens with a -{number} to prevent the override.
failOnMutate
optional
true | undefined
undefined
By default, this parser mutates your graph. When set to true this option will make your pipeline return an error when your tokens respective path differ from their original one in the graph. Set this option to true if you want to be 100% aligned between design and code.
Basic usage: select all tokens from a group in a collection
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.
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.
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;
}
Get design tokens and assets from a Specify repository. You can only execute a single rule with this endpoint.
Path Parameters
Request Body
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:
The pattern used to generate the CSS selector name(s). It must match template syntax.
You can use collection, mode and groups names.
The pattern used to generate token names. It must match template syntax.
You can use collection, mode,groups and token names.
The query that select items in the graph. Learn more about .
Make sure to read the to better understand how configuration file works with Specify.
Template
Description
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 template helps you pull your design tokens in the SDTF format in a JSON file.
This template helps you generate your design tokens as a Tailwind theme.
We're currently working on making compatible with the SDTF. We'll update this page accordingly.
This parser helps you generate raw token files for all your design tokens coming from Specify.
The target color format to convert to. Actual value conversion is done by the package.
The selection where to apply the transformation.
collection, group, token take a Regex string or true to select anything of the kind.
An SDTFQuery can be used for advance use cases. Learn more about .
We then generate our transformed SDTF graph in a JSON file thanks to the parser.
New to Specify? Head over to the existing REST API to learn more about why it can be useful for your team and how to use it.
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".
parsers*
Object or Array
Can contain an object or an array of objects. Each object corresponds to a specific parser.
{
"version": "2",
"repository": "@organization/repository",
// Only use the personalAccessToken when working with the CLI
"personalAccessToken": "<your-personal-access-token>",
"rules": [
{
"name": "To TypeScript",
"parsers": [
{
"name": "to-typescript",
"output": {
"type": "file",
"filePath": "tokens.ts"
}
}
]
}
]
}
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'
} as const;
export type colorsColorPathType = keyof typeof colorsColorPath;
export type colorsPathType = colorsColorPathType;
/**
* All the modes of the collection colors.
* Use it when calling `getColorsTokenByMode`
*/
export const colorsModes = [ 'light', 'dark' ] as const;
export type colorsModesType = typeof colorsModes[number];
/**
* 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)' }
} as const;
/**
* 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<T extends colorsPathType, M extends keyof typeof colors[T]>(path: T, mode: M) {
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]
}
This template helps you generate your design tokens as a Tailwind theme.
This example uses the following parser:
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:
CLI configuration
When using the CLI, you need to fill three properties:
repository is @organization/repository
rules lets you transform tokens by chaining parsers
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).
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.
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.
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:
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.
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.
Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards.
Why you need parsers
By default, without any parsers, Specify will return your design data as raw data:
Design tokens are returned in JSON
Assets are returned as files
There are high chances you need to transform those design data to fit your needs. Parsers help you do just that.
What are parsers?
Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards.
A parser does the following job:
Receives design data as input
Transforms this design data
Returns the transformed data
The data returned by a parser can either be:
Design data that can be used by another parser coming next in your transformation pipeline
A file so it can be used by people, frameworks, or scripts
Parsers are what make Specify powerful and flexible. They help you be in total control of the design data you pull from Specify.
Parsers are ordered and takes specific input to generate specific output. This way, we can easily test the input coming from the previous parser to check if the whole parsers process will work.
Categories
Parsers are classified in 2 categories: technology and utility.
Technology
Technology parsers help you transform your design tokens to specific technologies and formats (CSS Custom properties, SCSS, Tailwind, a Javascript theme object compatible with React Native...)
Some examples:
Utility
Utility parsers take care of "smaller" transformation. Like converting a pixel value to rem or transforming a string to kebabcase.
Some examples:
All parsers available
REST API
The Specify API lets you extend Specify functionalities beyond what we provide out of the box.
Introduction
The Specify API is based on REST structure. We support authentication via access tokens. Requests are made via HTTP endpoints with clear functions and appropriate response codes. Endpoints allow you to request design tokens and assets from a Specify repository.
What you can do with the REST API
However, you cannot directly generate files using the REST API as it only returns text. You'll have to write custom scripts to generate design files (e.g., colors.css).
Endpoint
Specify provides the following endpoint to help you get design tokens and assets from a Specify repository.
Get design tokens and assets from a Specify repository.
Path Parameters
Request Body
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 colors in CSS variables from a repository called all-design-datain the @acme-inc workspace:
Errors
Specify uses standard HTTP response codes for success and failure notifications. Our errors are further classified by type. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Specify servers.
Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.
Attributes
Overview
List of all apps you can use with Specify to sync, read and transform your design tokens and assets.
Playground
Learn how to use the Specify Playground to iterate more easily on your configuration files
Introduction
The Specify Playground helps you run parsers against a token graph and see the generated output in live. It's a great tool to help you iterate on your configuration files or try new parsers on the go.
Usage
The middle panel contain your Specify configuration rule.
The right side panel displays the generated code
Configuration
Learn more about how to configure Specify to generate design tokens and assets fitting your company standards.
Introduction
Design tokens are returned in JSON
Assets are returned as files
A configuration file helps you:
request design tokens and assets from a Specify repository
transform them to fit your company standards thanks to rules, token types and parsers.
Properties
A configuration is composed of 3 main properties:
repository
personalAccessToken
rules
Repository
The name of the Specify repository you want to pull your design tokens and assets from.
Let's say we have the following repository in Specify called "all-design-data" located in the "@acme-inc" organization.
We target it like this:
You can only target one repository per configuration file. Want to pull design tokens from several Specify repositories? Create a several configuration files and run them with the Specify CLI.
Personal Access Token
The Specify personalAccessToken used to authenticate your actions.
Rules
Rules help you transform your design tokens and assets the way you want.
A rule is composed of the following properties:
Parsers
Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards.
Inside a configuration, a parser has the following properties:
Example
Here's a rule named "Design Tokens" that:
targets color and measurement design tokens
sorts them alphabetically by their name
transforms them as CSS Custom Properties
writes them in a design-tokens.css file inside a styles folder
Examples
How to run these examples
The following examples are made to be used with the Specify CLI.
Requirements:
a Specify repository containing design tokens
Run all examples by copying the code and running the specify pull command.
Basic
Here's a basic configuration file that targets a Specify repository called all-design-data from the @acme-inc organization:
This example config file will return a design-tokens.json file containing all design tokens and assets stored in the all-design-data repository.
Here's an example of a token value returned by Specify:
Pull colors as CSS Custom Properties
Now let's update our previous configuration to only pull colors and transform them as CSS Custom Properties in HSL.
Here is the input returned by Specify and the output generated by Specify after executing our configuration.
Set your personal access token as an environment variable and interpolate it in the CLI wit .
You can use this method to sync Specify with git repositories in , , or .
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
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
The target color format to convert to. Actual value conversion is done by the package.
The selection where to apply the transformation.
collection, group, token take a Regex string or true to select anything of the kind.
An SDTFQuery can be used for advance use cases. Learn more about .
We then generate our transformed SDTF graph in a JSON file thanks to the parser.
The case transformation to apply. Actual transform is done by the package.
The selection where to apply the transformation.
collection, group, token take a Regex string or true to select anything of the kind.
An SDTFQuery can be used for advance use cases. Learn more about .
We eventually generate our transformed SDTF graph in a JSON file thanks to the parser.
All parsers are open source and available on .
Parser
Description
Usage Example
Specify's REST API is useful if you want to use design data coming from Specify through custom scripts like a Figma plugin or a .
In short, our REST API helps you request design data through HTTP requests. Like with our you can use parsers to transform design data.
To sum things up, to generate files from Specify (e.g., colors.css or icon.svg) containing design tokens or assets use the or our .
Name
Type
Description
Name
Type
Description
Property
Type
Description
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.
By default, without any , Specify returns your design data as raw data:
Need a personal access token?
You can have as many rules as you want and you can have rules that transform several at once.
Name
Type
Required
Description
Name
Type
Required
Description
a valid personal access token ()
Make sure you have connected your GitHub account with your Specify account. Head toward to learn more.
Make sure you have connected your GitHub account with your Specify account. Head toward to learn more.
Apply camelcase function on specific keys from a design token.
Convert font in several formats.
Filter tokens and assets by their name using a regular expression.
Replace all the stroke and fill attribute raw color value by its corresponding design token as a CSS variable. If no design token match, the raw value will be left as is.
Apply kebabcase function on specific keys from a design token.
Have design tokens referencing other ones.
Omit keys from a design token not given in parameters.
Apply pascalcase function on specific keys from a design token.
Get only specific keys from a design token given in params.
Concatenate two strings.
Convert the value of a measurement design token from pixel to rem.
Replace any string matched by a regex by a new string.
Round any measurement design token with specific precision.
Apply snakecase function on specific keys from a design token.
Loop on several design tokens and sort them according to their respective key values.
Concatenate two strings.
Wrap SVG files within a JSX component.
Transform design tokens in CSS Custom Properties.
Create CSS @font-face rules to import your font files.
Create text styles as CSS classes.
Transform design tokens in JSS.
Generate .scss files containing Scss map and function / mixin to access the values of the tokens.
Transform design tokens in SCSS variables.
Format design tokens to create their corresponding TypeScript types.
The path in your project where you want Specify to generate your design data.
filter
Record<'types', Array<TokenType>>
false
parsers
Array<Parser>
false
name
string
true
options
Record<string, any>
false
The options relative to the parser you apply. Each parser has its own options you can find in their respective README file.
npm
Learn how to distribute your design tokens and assets from Specify as npm or GitHub packages.
Workflow
This integration helps you generate design tokens and assets as private or public packages in a npm or a GitHub registry.
Choose npm if...
Choose npm if you already have a private npm registry, we suggest you distribute your npm packages there. It will prevent you from creating a public npm package that will take an unnecessary public namespace.
Choose GitHub if...
Choose GitHub if you want to keep your packages private to your GitHub organization without paying for an npm team account.
Choose a custom registry if...
Choose a custom registry if your company uses its own registry. If you have specific security constraints like IP whitelisting or custom authentication.
Prerequisites
Please make sure you have:
An npm account, a GitHub account, or access to a custom registry
A Specify account
A Specify repository containing some design tokens and/or assets
Installation
Go to your Specify repository you want to distribute your design tokens from
Go to the "Destinations" page and click on "Create pipeline"
Select "npm packages"
Configure your package name, access type (public / private), and module type (Common JS / ES Modules)
Useful resources
GitHub
Learn how to distribute your design tokens and assets from Specify to your GitHub repositories via automated Pull Request.
By default, Specify can only syncs your GitHub repository if you have a config file .specifyrc.json at the root of your GitHub repository. If you want to sync design tokens from several Specify repositories you need to run the Specify CLI inside a GitHub Action.
Prerequisites
Please make sure you have:
A GitHub account
A Specify account
A Specify repository containing some design tokens and/or assets
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
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 repository page 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
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 🎉
Fixing sync issues
Useful resources
Notion
Learn how to automatically document your design tokens and assets from Specify to your Notion workspace.
Introduction
Use our Notion integration to:
Document your brand guidelines
Create public pages for press and brand kits
Automate the maintenance of your design system documentation
Prerequisites
Please make sure you have:
A Notion account
A Specify account
A Specify repository containing some design tokens and/or assets
Want to connect a Notion page from your Notion workspace? Please make sure you have the correct access rights. Otherwise, you'll need for an owner to approve your installation request.
Supported Token types
color
measurement
textStyle
bitmap
font
vector
Installation
Raycast
Learn to get and use your design tokens and assets right from Raycast.
Our Raycast extension helps you search your design tokens and assets and use them in your favorite tools: Notion pages, Pitch presentations, Slack discussions, etc.
Prerequisites
Please make sure you have:
A Specify account
A Specify repository containing some design tokens and/or assets
Generated a Personal Access Token for Raycast
Supported Token types
color
bitmap
vector
Installation
Install the Specify Raycast extension from the Raycast store
Set your newly created Personal Access Token in Raycast
Usage
Search colors
Are you looking for a specific color from your design system? Open Raycast and type in Search Colors.
The main action is to copy the hexadecimal value of your color. You can also access other actions like copying the value in RGBA or the name of the color by accessing the action menu via Cmd + K.
Search bitmaps
Are you looking for a .jpg or .png file, such as a logo or photo of a team member? As with the previous search, open Raycast and type in Search Bitmaps.
Search vectors
Are you looking for a .svg file, such as a logo or an icon? Just open Raycast and type in Search Vectors.
CLI
The Specify CLI helps you pull design tokens and assets from Specify right from your terminal.
Introduction
Use the Specify CLI to integrate Specify in your workflow.
You can use the Specify CLI to:
Pull your design tokens in the right format using parsers
Test your configuration before using it in a GitHub repository
Sync a Specify repository
Installation
Install @specifyapp/cli via npm or Yarn.
npm install -g @specifyapp/cli
yarn global add @specifyapp/cli
Commands
Init
specify init
Pull
Pull design tokens and assets from your Specify repository.
specify pull [flags]
Sync
Sync a Specify repository to update its design tokens and assets.
specify sync [flags]
Flags
Flags are parameters you can pass while launching the command. All of these parameters are optional if you use a config file.
-C, --config-path
Relative path to your Specify config file.
-r, --repository
The name of the Specify repository you want to pull your design tokens and assets from.
-p, --personal-access-token
The Specify Personal Access Token used to authenticate your actions.
-R, --rules
Rules Specify will follow to generate design tokens and assets in your desired output format.
--dry-run
Execute command without actually writing files. Use this flag to test the output of a configuration without generating files.
Set a structured filename on your assets. It won't rename your asset but only add a new filename property on the asset object. The filename structure uses as a template engine.
Optimize vectors using .
Create a .
Format design tokens to create a theme compatible with the .
Transform design tokens to a JavaScript theme object compatible with .
Create text styles formatted as .
Generate configuration files for all your design tokens coming from Specify.
Format design tokens to create a theme compatible with the .
Format design tokens to create a theme compatible with the .
Set all the you want to target.
Can contain an object or an array of objects. Each object corresponds to a specific .
If you want to pull , or token types you must set a directory ().
The list of you want your rule to target.
The parsers you want to apply to transform your . For further details see .
The name of the parser. Choose from .
Also, , so make sure your package needs to be public before making it as is 👍
Select your existing npm app, or create a new one by setting your or personal access token, then set your registry
Set your Specify configuration file. If you host your config file on an external service like JSONBIN make sure to make your BIN public (). Also, your config only needs the property.
Go to the applications catalog
Select your configuration template ()
Have trouble getting Pull Requests in your GitHub repository? Learn more about .
You can sync the following in Notion:
installed
Need a personal access token?
You can sync the following in Raycast:
Initialize a Specify configuration tailored for a specific output format. .
