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

A Token type is a type of design token or asset supported by Specify like a colors, a text style or an icon. See all token types.

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

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

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.

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

• Download the Specify Figma Widget ↗

• Figma Example File ↗

Introduction

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

Before getting started

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

• A Specify account

• A Specify repository containing some design tokens and assets ()

1. Install the CLI

Install @specifyapp/cli via npm or Yarn.

2. Create your Specify config file

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

3. Add your Specify repository

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

4. Add your personal access token

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

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.

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

• Download ↗ the Specify Widget in the Figma file which includes your Variables and/or Styles. Or update the widget if you already have it. To update the Specify Widget you have to disconnect it, remove the entire frame in all of your Figma files, and reopen the latest version of the Widget.

2. Connect your Specify account

1. Follow the steps in the widget to connect your account. You will need to create a personal access token and you will need to add the link to the Figma file to which the widget is added. Watch tutorial ↗

2. Click "Connect"

3. Choose Advanced Repository

3. Create a repository in Specify

1. Go to your Specify workspace

2. Click on "Create repository"

3. Choose a name

4. Select "Advanced Repository" (Learn more ↗︎)

5. Click "Create repository"

4. Connect the Specify Repository in your Widget

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

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

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

4. Select the design tokens format you want to collect from your Figma file. Learn More ↗︎

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

6. Click "Save to Specify"

7. You will immediately see the repository listed with the latest syncing time

5. Sync updates variables and styles on the fly

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

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.

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

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

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

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

1. Go to your Specify repository you want to distribute your design tokens from

2. Go to the "Destinations" page and click on "Create pipeline"

3. Select "npm packages"

4. Select your existing npm app, or create a new one by setting your or personal access token, then set your registry

5. Configure your package name, access type (public / private), and module type (Common JS / ES Modules)

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

Useful resources

This example uses the following parser:

• to-sdtf to generate your design tokens in SDTF

{
  "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"
          }
        }
      ]
    }
  ]
}

{
  "version": "2",
  "repository": "@organization/repository",
  "rules": [
    {
      "name": "Generate tokens in JSON",
      "parsers": [
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "output/tokens.json"
          }
        }
      ]
    }
  ]
}

Prerequisites

Please make sure you have:

• A GitHub account

• A Specify account

• One or multiple new Advanced Repositories Specify repositories containing some design tokens.

Installation

1. Go to the applications catalog on the Destinations page

2. Select GitHub

3. Click on "Connect"

4. Select the repositories you want Specify to have access to

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

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

2. Go to its "Destinations" page

3. Click on "Create Pipeline"

4. Select "GitHub application"

5. Select your GitHub account

6. Select the GitHub repository you want to distribute your design data to

7. Name for your configuration file (Learn More ↗︎)

8. Create the Pull Request containing your configuration file

9. Merge the PR created by Specify containing your configuration file

10. Specify will now automatically sync design data to your GitHub repository 🎉

Useful resources

• How to sync design tokens in a GitHub monorepo

• How to run Style Dictionary with a GitHub Action

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

Supported Token types

You can sync the following Token types in Notion:

• color

• measurement

• textStyle

• bitmap

• font

• vector

Installation

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

Initialize a Specify configuration tailored for a specific output format. See all configuration templates.

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.

This example uses the following parser:

• to generate your design tokens as a Tailwind theme

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:

• installed

• A Specify account

• A Specify repository containing some design tokens and/or assets

• Generated a Personal Access Token for Raycast

Supported Token types

You can sync the following in Raycast:

• color

• bitmap

• vector

Installation

1. Install the Specify Raycast extension from the Raycast store

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

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

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:

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"
            }
        }
    ]
}'

Prerequisites

Please make sure you have:

• A GitHub account

• A Specify account

• A Specify repository containing some design tokens and/or assets

Installation

1. Go to the applications catalog on the Destinations page

2. Select GitHub

3. Click on "Connect"

4. Select the repositories you want Specify to have access to

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

1. Go to the Specify repository page you want to distribute design data from

2. Go to its "Destinations" page

3. Click on "Create Pipeline"

4. Select "GitHub application"

5. Select your GitHub account

6. Select the GitHub repository you want to distribute your design data to

7. Select your configuration template (Learn more)

8. Create the Pull Request containing your configuration file

9. Merge the PR created by Specify containing your configuration file

10. Specify will now automatically sync design data to your GitHub repository 🎉

Fixing sync issues

Have trouble getting Pull Requests in your GitHub repository? Learn more about how to fix the most common issues.

Useful resources

• How to pull design tokens from several Specify repositories in GitHub

• How to run Style Dictionary with a GitHub Action

Interface

Options

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

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

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.

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

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 .

Endpoint

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

https://api.specifyapp.com/repository/{workspace}/{repository}/design-tokens

Parameters

POST https://api.specifyapp.com/repository/{workspace}/{repository}/design-tokens

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

Before getting started

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

• A account

• The plugin installed in your Figma

• A , , , or account

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

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

1. Head to your Tokens Studio plugin in Figma

2. Within the settings tab, add a new sync provider

3. Commit your Tokens Studio JSON file to your repository

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

1. Go to your Specify workspace

2. Click on "Create repository"

3. Choose "Advanced Repository"

4. Name your repository

5. Select "Sync from Figma Variables & Tokens Studio" ()

6. Click on "Create repository"

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

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

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

2. Select "Remote URL"

3. Select "Public"

4. Name your source

5. Paste your raw public URL of your JSON file

6. Select the format "Tokens Studio"

7. Let Specify check the connection

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

1. In the "Source" tab of your Specify repository, click on "Create a source"

2. Select "Remote URL"

3. Select "Private"

4. Name your source

5. Create and Paste this GitHub file URL such as: https://api.github.com/repos/{owner}/{repo}/contents/{file_path}

6. Select "Bearer Token" as the auth system & paste your personal access token from GitHub ( and be sure to check the repo section)

7. Select "Tokens Studio Format"

8. Specify will test your JSON

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

1. In the "Source" tab of your Specify repository, click on "Create a source"

2. Select "Remote URL"

3. Select "Private"

4. Name your source

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

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

7. Select "Tokens Studio Format"

8. Specify will test your JSON

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

1. In the "Source" tab of your Specify repository, click on "Create a source"

2. Select "Remote URL"

3. Select "Private"

4. Give a name to your source

5. Paste your GitLab file URL such as: https://gitlab.com/api/v4/projects/{OrgName}%2F{RepositoryName}/repository/files/{FilePath}?ref={branch}

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

7. In Specify, select Header as auth system

   1. Fill PRIVATE-TOKEN in the key field

   2. Paste your GitLab project access token

8. Select "Tokens Studio Format"

9. Specify will test your JSON

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

1. In the "Source" tab of your Specify repository, click on "Create a source"

2. Select "Remote URL"

3. Select "Private"

4. Name your source

5. Paste your BIN private URL such as https://api.jsonbin.io/v3/b/{bin_id}

6. Select Header as auth system

7. Depending on your choice, you can use your master key or an access key. on JSONBin.

   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

8. Select "Tokens Studio Format"

9. Specify will test your JSON

10. And voila!

3. How to update your JSON File

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

1. Go to the "Source" tab of your Specify repository

2. Click on the context menu next to your source

3. Click on "sync"

Your source is now updated!

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)

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

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.

• Get a personal access token .

• 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

Interface

interface parser {
  name: 'to-typescript';
  output: {
    type: 'file';
    filePath: string;
  };
  options?: {
    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"
            }
          }
        }
      }
    }
  }
}

{
  "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"
          }
        }
      ]
    }
  ]
}

/** 
* @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]
}

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

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

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

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

{
  "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"
          }
        }
      ]
    }
  ]
}

/** 
* @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]
}

Unlike , this one doesn't have any options yet.

Interface

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

Interface

Options

Basic usage

This example uses four different parsers:

• to target on a specific collection named "Colors" that contains our colors

• to convert our colors in HSL

• to change the name of our tokens and modes to kebabCase

• to generate a CSS file containing our tokens

This template is an example among others. Head toward the 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

• rules lets you transform tokens by chaining parsers

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