Distribute design tokens & assets to Destinations

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 page as a destination.

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

Here are all the Destinations you can currently connect to Specify:

• GitHub
• A local directory (using the Specify CLI)
• A Notion page
• Raycast

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.

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.

Notion

Our Notion integration, which is still in Beta, helps you automatically:

• Document your brand guidelines in Notion
• Create public pages for press and brand kits
• Automate the maintenance of your design system documentation

Want to join the beta? Apply here.

Raycast

Raycast is personal command launcher you can connect to Specify to easily access your design data.

The Specify Raycast extension helps you search your design tokens and assets and use them in your favorite tools: Notion pages, Pitch presentations, Slack discussions, etc.

We currently support colors, vectors, and bitmaps but plan to support all design tokens and assets compatible with Specify.

Want to learn more? Read our dedicated blog article.

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.

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.

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.

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.

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

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 templates based on common language and frameworks to help you get started:

• From Specify to a Tailwind theme
• From Specify to CSS Custom Properties

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

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

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.

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

In summary, a Design API opens up much more possibilities than "just" getting design tokens and assets 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.