Distribute design tokens & assets to Destinations

Destinations

Several applications connected to a Design API as destinations.

In opposition to sources, destinations are environments consuming your design data.

UI Engineers often come to mind when thinking about people consuming design data. This is why you could consider code repositories as the most common destinations.

However, some teams could be using specific tools like Notion to document their design system. Thus, it would make perfect sense to define a Notion document as a destination.

Destinations can vary from a Dropbox folder to a GitHub repository or a local directory.

Here are all the sources and destinations you can currently connect to Specify:

  • Figma (as a source application)
  • GitHub (as a destination application)
  • A local directory (as a destination using the CLI)

📣 Check our public roadmap and let us know what app should be available next in Specify: specify.canny.io/app-requests.

Connecting Specify to your destinations

Learn how to connect and configure Specify to pull design data in your favorite platforms.

REST API

The Specify API lets you extend Specify's functionality beyond what we provide out of the box.

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

In short, our REST API helps you request design data through HTTP requests. Like with our CLI 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 CLI or our GitHub application.

📣 For more in depth documentation visit specifyapp.com/developers. If you have a question the docs don't answer, post it in the #help-workflow channel in our Discord community.

CLI

In case you're not familiar with a CLI here's a quick introduction: CLI stands for "Command Line Interface". It helps you get data from a service by giving it instructions through the terminal. The "Interface" is the terminal in which you write "commands".

To precisely dictate Specify what to sync and how in your projects, you need to provide to Specify a configuration.

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

👉 Learn more about our CLI in our documentation.

GitHub

Specify helps you sync your design tokens and assets directly to your GitHub repositories.

To precisely dictate Specify what to sync and how in your projects you need to provide to Specify a configuration.

👉 Learn more about our GitHub application in our documentation.

Video

Distributing Design Tokens from Specify to GitHub, by Louis Chenais ↗︎

Learn how to connect GitHub as a Destination for your Specify repository.

Build and customize delivery pipelines for your destinations

Create your configuration file

You need to configure Specify to precisely dictate Specify what to sync and how in your projects.

Whether you are a web developer, an iOS, or an Android one, you need design tokens and assets to be compatible with your project.

Raw design data in JSON being distributed to several target platforms.

Let's say you need to synchronize colors from Specify and make them compatible with your targeted end platforms: web, iOS, and Android.

You will need to transform them:

  1. In the right naming convention: kebab-case, camelCase, PascalCase...
  2. For the right platform or framework: CSS Custom Properties, Theme UI, Style Dictionary...
  3. In the right format: hsl, hex8, rgba...
  4. In the right path and in the right file (e.g., assets/styles/variables/colors.css)

Well, our configuration file helps you do exactly that 💪

In short, this configuration helps you define

  1. From which Specify repository do you want to pull design data from
  2. Define how your design tokens and assets will be transformed and synchronized in your project.

Video

Writing A Configuration File for Specify, by Louis Chenais ↗︎

Learn how to define a custom transformation pipeline for your design data.

Add parsers

Transform raw design data coming from Specify to make it compatible with your projects.

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

Without any parsers, here's what a color design token coming from Specify looks like:

{
  "id": "6b5fbe98-bff8-4156-8720-98d9eb776cd4",
  "createdAt": "2021-07-23T09:26:45.164Z",
  "updatedAt": "2021-07-23T09:26:45.164Z",
  "name": "Colors/White",
  "value": {
    "a": 1,
    "b": 255,
    "g": 255,
    "r": 255
  },
  "meta": {
    "source": "localStyles"
  },
  "type": "color",
  "originId": "12:153",
  "sourceId": "6232b157-22db-4ef1-9437-f7f8066849e1",
  "repositoryId": "927e26f6-da29-40d6-b9de-530bdcddf1ed"
}

As you can see, the information is here but it could be optimized.

It means you need to transform this raw design data to make it compatible with your project technical requirements.

Use parsers to transform design data you're pulling from the Design API.

If you want to get your colors as CSS Custom Properties you must transform your colors from JSON to CSS.

If you want your icons to be optimized and renamed you must tell Specify to do so.

If you want your design tokens to be created as Style Dictionary configuration files you need to tell Specify to do it.

ℹ️ Parsers help you transform design data coming from Specify to make them compatible with your destinations.

Also, our parsers are open source as we want to give you maximum flexibility when using Specify. When transforming design data, we're all in the same boat. It means that your needs may also be the ones of another team. Open-sourcing our parsers was part of our vision from day 1.

👉 See all our available parsers in our public GitHub repository.

How parsers work

A parser does the following job:

  1. Receives design data as input
  2. Transforms this design data
  3. Returns the transformed data
A transformation pipeline transforming colors from JSON to CSS Custom Properties.

A transformation pipeline transforming colors from JSON to CSS Custom Properties.

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

Not only parsers are what make Specify powerful and flexible, but above all, they help you be in total control of the design data you synchronize.

Here's a list of several examples projects based on common language and frameworks to help you get started:

Pulling design data in your destinations

Let's learn more about how to sync your design data between your Sources and your Destinations.

We're almost there! Now you have collected your design data in Specify it's time to pull them from your Specify repositories. When pulling design data, Specify will read and execute your configuration file to generate in your project the design data you desire.

Depending on your destination, this pull can be automatic:

  • If you've defined a GitHub repository as a destination to your Specify repository, Specify will automatically create a Pull Request containing your design data.
  • If you're using the CLI or the REST API, you'll have to pull design data manually

👉 Learn more about how Specify synchronizes your design data from Sources to Destinations.

If you are using the Specify CLI, you must use the specify pull command to pull your design data in your project.

Video

Syncing Design Tokens between Figma and GitHub, by Louis Chenais ↗︎

Learn how to sync a Specify repository with the CLI

Automation

Learn more about possibilities offered by setting up a Design API like Specify at the heart of your design system.

Specify is a middleware facilitating the distribution of your design data within your design system.

It means, we've built Specify to be:

  • integrated with the tools you're already using
  • extended with custom workflows

This chapter will help you understand how you can use Specify to build custom and automated workflows for your design data.

At the time of this writing, Specify helps you mostly collect design data from Figma and distribute it to your codebases.

A Design API synchronizing design tokens from Figma to users end platforms.

However, the possibilities offered by a Design API like Specify are legion.

The many different possibilities offered by a Design API from an l point of view.

In summary, a Design API opens up much more possibilities than "just" getting design tokens from design to code.

Thanks to a Design API you can automatically:

  • Let people know when design tokens are updated in Slack or Discord
  • Update your styleguide, documentation website or Storybook
  • Create new versioned design tokens and assets packages on NPM thanks to GitHub Actions or GitLab CI/CD
  • Run tests every night to ensure your colors adhere to web standards like WCAG
  • Setup A/B tests on your UI using different design tokens and assets

And this list could go on and on. Possibilities are endless and this is for the better.

Your brand.
Your products.
Always in sync.

Meet the design data platform you ever dreamt of.