Parsers Engine

Configure automated pipelines and deliver the design data to battle-tested technologies like CSS, Style Dictionary, Javascript, TypeScript, Swift, Kotlin — and more.

Overview

The Parsers Engine is a set of APIs you interact with anytime you need to transform your design data - tokens & assets - from your repository token tree into pre-configured file outputs.

The Parsers Engine serves as the orchestrator for a series of functions, called Parsers designed to transform design data, in parallel and/or chained. By configuring Parser Rules, you customize how and where design tokens and assets are exported.

The Parsers Engine can operate both remotely, using the Pipe Engine API over HTTP, and locally, through the Specify SDK. This dual capability enables it to be integrated into various workflows, offering flexibility whether working from remote servers, custom CI or directly within local development environments.

The Parsers Engine relies on the Parsers functions, which are actual converter implementations from the SDTF tokens to their representation in various formats and languages.

Parser Rules

As the medium to interact with the Parsers Engine, the parser rules are meant to be configured to follow your output needs.

A parser rule is simply a JSON object with two properties:

name: the name of the rule — we recommend setting up the purpose: CSS variables, Icons export...

parsers: an array of parser configuration

Parser Configuration

name: the name of the parser - to-json, to-tailwind over the parsers list.

output: an object describing the desired output type - can be optional when no output is expected.

Looking for how to configure the output property? 👉 review the Rule Output type reference.

options: an object of arbitrary keys and values defined by the parser - can be optional.

Looking for a precise parser option? 👉 review the full parsers list.

Example of a parser rule for a CSS custom properties output

{
  "rules": [
    {
      "name": "Generate tokens as CSS Custom Properties",
      "parsers": [
        {
          "name": "to-css-custom-properties", // parser name
          "output": {
            "type": "file",
            "filePath": "public/css/tokens.css" // ouput will be a file
          },
          "options": { // parser specific options
            "tokenNameTemplate": "--{{groups}}-{{token}}",
            "selectorTemplate": "[data-theme=\"{{mode}}\"]"
          }
        }
      ]
    }
  ]
}

Parser rules templates

To get started with the parser rules 👉 heads up to the Parser Rules templates resources.

Remote execution

Executed over HTTP, the parser rules are sent over to Specify servers to evaluate, transform and return the structured result.

All destinations are compatible with the remote execution.

For some destinations, like Github & the Specify CLI you need a Configuration file in order to keep track of your desired settings.

Configuration file

A Specify configuration file allows you to:

• Define the repository source from which to fetch design data.
• Provide a personal access token as authentication credentials for your user.

• Describe the parsers rule(s) to configure your ouput.

By default the file is named .specifyrc.js or .specifyrc.json

Looking for the configuration file details? 👉 review the Configuration file reference

Local execution

Executed on the local environment, the parser rules are evaluated by the Specify SDK.

Only the generation parsers are meant to be used in a local execution. In fact, you can apply any mutation on your token tree using the SDTFClient API, before generating the final output.

Once executed, the parsers pipeline yields the result back to the SDK instance.

Get started with local execution 👉 review the Execute a parser locally guide.

The Parsers functions

Parsers play a pivotal role. They are functions acting as interpreters and transformers of design tokens. They process the initial token tree and apply a set of transformations toward the expected output. Each parser, whether it pertains to utilities or generation, contributes to the workflow by either mutating the token tree or generating tangible assets and code snippets respectively.

Looking for the parsers settings? 👉 review the Parsers reference.

Utility parsers

Utility parsers mutate the design token tree, through dedicated functions like filter, convert-color, change-case…

You configure their options property to instruct the changes to apply to your token tree before it get passed to the next step.

The utility parsers are only available to the Remote execution of the Parsers Engine.

Generation parsers

Code generation parsers generate one or several outputs like CSS, JavaScript, TypeScript or assets like SVGs or bitmaps.

You configure their output property to produce the files that will end up in your codebase.

The options property is also available for most of the generation parsers.