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

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.

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

Please make sure you have:

• A GitHub account

• A Specify account

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

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.

Please make sure you have:

• installed

• A Specify account

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.

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

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

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

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.

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.

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.

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

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

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 (Learn more ↗)

1. Install the CLI

Install @specifyapp/cli via npm or Yarn.

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

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

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

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

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

Please make sure you have:

• A Notion account

• A Specify account

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

You can sync the following in Notion:

• color

• measurement

• textStyle

• bitmap

This example uses the following parser:

• to-sdtf to generate your design tokens in SDTF

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

2. Select GitHub

3. Click on "Connect"

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

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"

Have trouble getting Pull Requests in your GitHub repository? Learn more about .

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

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

Install the @specifyapp/cli via npm or Yarn.

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

• Create an empty file named .specifyrc.json

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

• A Specify Account

• A Figma file containing Variables and/or Styles

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

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

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

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

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

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

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

1. The name is the name of the parser

2. The output

Interface

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

Basic usage

{
  "colors": {

{
  "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-javascript';
  output: {
    type: 'file';
    filePath: string;
  };
  options?: {
    typescript?: boolean;
    moduleExport?: 'es6' | 'commonjs';
  };
}

Basic usage

{
  "colors": {

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

Interface

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

Options

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.

This example uses four different parsers:

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

• convert-color to convert our colors in HSL

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

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

• repository is @organization/repository

• personalAccessToken which you can generate

• rules

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

• repository is @organization/repository

• rules lets you transform tokens by chaining parsers

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.

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