Specify Docs
Specify ↗︎Changelog ↗︎Guide ↗︎
V2
V2
  • Getting started
    • Introduction
    • What is Specify?
    • Pulling your first tokens with the CLI
    • Glossary
  • Collect
    • What is a Source?
    • Available sources
      • Figma Variables & Styles
      • Tokens Studio
  • Distribute
    • What is a Destination?
    • Available destinations
      • GitHub
      • Specify CLI
      • Specify SDK
      • HTTP API
  • Concepts
    • Overview
    • Parsers Engine
    • SDTF Client
      • SDTF Engine
    • Specify Design Token Format
  • Guides
    • Configuration file 101
    • Specify CLI usage 101
      • Getting started
      • Authentication
      • Generate Files
    • Specify SDK usage 101
      • Getting started
      • Retrieving and working with the tokens
      • Updating tokens
      • Converting a token to XXX
      • Executing generation parsers
    • Specify SDK Cheatsheet
    • Manage font files
    • Querying a SDTF graph
  • Reference
    • Parsers Engine
    • Parsers
      • change-case
      • convert-color
      • convert-dimension
      • make-line-height-relative
      • filter
      • register-view
      • select-modes
      • prefix-by
      • suffix-by
      • replace-string
      • to-css-custom-properties
      • to-css-text-style
      • to-css-font-import
      • to-flutter
      • to-javascript
      • to-json
      • to-json-list
      • to-kotlin
      • to-react-native
      • to-scss-mixin-text-style
      • to-scss-map
      • to-sdtf
      • to-style-dictionary
      • to-swift
      • to-tailwind
      • to-typescript
      • svgo
      • svg-to-jsx
      • svg-to-tsx
      • to-svg-file
      • to-bitmap-file
      • to-file
    • Specify SDK
      • SpecifyClient
      • SDTFClient
      • Converters
        • CSS
      • ParsersEngineResults
    • SDTF Engine
      • Query API
      • Mutation API
      • SDTF Query Language
      • SDTF QueryResult
      • TokenState
        • Stateful Value
    • HTTP API
      • POST /parsers-engine-rpc
    • Specify CLI
  • Resources
    • Parser Rules templates
      • CSS Custom Properties
      • Tailwind
      • React Native
      • Flutter
      • SDTF
      • JSON
    • Specify CLI VS Specify SDK
    • Playground
    • Best practices
  • Useful links
    • Discord
    • YouTube
    • Twitter
    • Help Center
    • Canny
Powered by GitBook
On this page
  • Overview
  • Parser Rules
  • Parser rules templates
  • Remote execution
  • Configuration file
  • Local execution
  • The Parsers functions
  • Utility parsers
  • Generation parsers

Was this helpful?

Export as PDF
  1. Concepts

Parsers Engine

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

PreviousOverviewNextSDTF Client

Last updated 1 year ago

Was this helpful?

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 designed to transform design data, in parallel and/or chained. By configuring , you customize how and where design tokens and assets are exported.

The Parsers Engine can operate both , using the Pipe Engine API over HTTP, and , through the . 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 , 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

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

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

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

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

Remote execution

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

Configuration file

A Specify configuration file allows you to:

  • Provide a personal access token as authentication credentials for your user.

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

Local execution

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

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.

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.

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.

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

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

are compatible with the remote execution.

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

Define the source from which to fetch design data.

Describe the to configure your ouput.

Looking for the configuration file details? 👉 review the reference

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

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

Get started with local execution 👉 review the guide.

Looking for the parsers settings? 👉 review the .

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

Parser Rules templates
All destinations
Github
Specify CLI
Specify SDK
Parsers reference
parsers rule(s)
SDTFClient
generation parsers
Remote execution
Parsers
Specify SDK
Parser Rules
remotely
locally
Parsers functions
parser configuration
parsers list
repository
parsers list
Rule Output type
Configuration file
Execute a parser locally