Parsers Engine

Parsers Engine API reference

Configuration file

The Configuration file has common properties, and some destination specific ones

interface ConfigurationFileCommon {
  version: '2';
  repository: string; // @owner/repository
  rules: Array<ParserRule>;
}

For Specify CLI

interface CLIConfigurationFile extends ConfigurationFileCommon {
  personalAccessToken?: string; // Can be set using the -p flag
}

For GitHub

interface GitHubConfigurationFile extends ConfigurationFileCommon {
  personalAccessToken: string; // Can be set over secret
}

ParserRule

The Parsers Rules help you transform your design tokens and assets the way you want.

A rule is composed of the following properties:

interface ParserRule {
  name?: string;
  parsers: Array<ParserConfiguration>;
};

Name	Type	Required	Description
name	string	false	The name of your rule.
parsers	Array<BuiltInParserRuleConfiguration>	true	The parsers you want to apply to transform your token tree. For further details see Parsers.

In many places you will use many parser rules in a configuration to parallelize the changes you want to apply.

BuiltInParserRuleConfiguration

The Parser Configuration object helps you configure the behaviour of a given parser.

interface ParserConfiguration {
  name: string; // parser name: to-json, to-tailwind...
  output: 
    | { type: 'directory', directoryPath: string }
    | { type: 'file', filePath: string };
  options?: Record<string, any>; // depends on the selected parser
}

Looking for the parsers list and options? 👉 heads up to the Parsers reference

The object is composed of the following properties:

Name	Type	Required	Description
name	string	true	The name of the parser. Choose from all available parsers.
options	Record<string, any>	false	The options relative to the parser you apply. Each parser has its own options. For further details see Parsers.
output	object	false	The output you want the parser to generate. In most cases, a file or a directory.

ParsersEngineDataBox

The parsers engine can take several input types called parsers engine data boxes. On start, the Parsers engine requires one of the data box types to be passed in as initial input.

SDTF

type SDTFDataBox = {
  type: "SDTF";
  graph: SpecifyDesignTokenFormat;
  metadata?:
    | {
        activeViewName: string | null;
        views: Array<{
          name: string;
          query: SDTFQuery;
        }>;
      }
    | undefined;
};

SDTF Engine

type SDTFEngineDataBox = {
    type: "SDTF Engine";
    engine: SDTFEngine;
}

Specify Repository

type SpecifyRepositoryDataBox = {
    type: "repository";
    owner: string;
    name: string;
}

JSON

type JSONDataBox = {
    type: "JSON";
    json: string | number | boolean | unknown[] | Record<string, unknown> | null;
}

Vector

type VectorDataBox = {
    type: 'vector';
    format: 'svg' | 'pdf';
    provider: 'external' | 'Specify';
    extension: {
      vector?: string, // The text representation of the SVG file
    },
}

Bitmap

type BitmapDataBox = {
    type: 'bitmap';
    format: 'png' | 'wp2' | 'avif' | 'webp' | 'jpg' | 'jxl';
    provider: 'external' | 'Specify';
    extension: {
      bitmap?: Array<number>, // The array buffer representation of the bitmap file
    },
}

Asset

type AssetDataBox = {
    type: 'asset';
    format: 'png' | 'wp2' | 'avif' | 'webp' | 'jpg' | 'jxl' | 'svg' | 'pdf' | 'ttf' | 'woff' | 'woff2' | 'otf' | 'eot';
    provider: 'external' | 'Specify' | 'Google Fonts' | 'Adobe Fonts';
}

ParserOutput

The parsers produce different types of outputs based on your configuration and their proper capabilities. If not all the parsers accept an output configuration property, the ones which do always take a standardized type as input.

File

Use case: the parser is expected to produce exactly one file.

type FileOutput = {
  type: 'file';
  filePath: string;
}

Example with the to-css-custom-properties parser:

"parsers": [
  {
    "name": "to-css-custom-properties",
    "output": {
      "type": "file",
      "filePath": "style.css"
    }
  }
]

Directory

Use case: the parser is expected to produce 0 to N files, all placed in the given base directory.

type DirectoryOutput = {
  type: 'directory';
  directoryPath: string;
}

Example with the to-svg-file parser:

"parsers": [
  {
    "name": "to-svg-file",
    "output": {
      "type": "directory",
      "directoryPath": "./public/assets"
    }
  }
]