Skip to content

Specify helps you unify your brand identity by collecting, storing and distributing design tokens and assets — automatically.

License

Notifications You must be signed in to change notification settings

Specifyapp/parsers

Repository files navigation

contributions welcome GitHub Workflow Status Coverage Status Contributors

Specify Parsers

Repository Header


Explore the docs »

Report Bug · Request Feature · Join Our Discord · Twitter

What is Specify?

Specify helps you unify your brand identity by collecting, storing and distributing design tokens and assets—automatically.

Possibilities offered by design apis like specify Possibilities offered by design apis like specify

Parsers

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

There are high chances you need to transform those design data to fit your needs. Parsers help you do just that.

What are parsers?

Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards.

How parsers work 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.

Parsers are ordered and takes specific input to generate specific output. This way, we can easily test the input coming from the previous parser to check if the whole parsers process will work.

All parsers available

Parser Description Usage example
camelcasify Apply camelcase function on specific keys from a design token. Example
convert-font Convert font files in several formats. Example
filter Filter tokens and assets by their name using a regular expression. Example
inline-css-variables-in-svg Replace harcoded design token values in a SVG by their corresponding CSS custom property. Example
kebabcasify Apply kebabcase function on specific keys from a design token. Example
link-design-tokens Have design tokens referencing other ones. It replaces absolute values by their potential corresponding design token. Example
name-assets-files-by-pattern Set a structured filename on your assets. It won't rename your asset but only add a new filename property on the asset object. The filename structure uses mustache as a template engine. Example
omit Omit keys from a design token not given in parameters. Example
pascalcasify Apply pascalcase function on specific keys from a design token. Example
pick Get only specific keys from a design token given in params. Example
px-to-rem Convert the value of a measurement design token from pixel to rem. Example
prefix-by Prefix a string or a whole file by a string. Example
replace-string Replace any string matched by a regex by a new string. Example
round-number Round any measurement design token with specific precision. Example
snakecasify Apply snakecase function on specific keys from a design token. Example
sort-by Loop on several design tokens and sort them according to their respective key values. Example
suffix-by Concatenate two strings. Example
svg-to-jsx Wrap SVG files within a JSX component. Example
svgo Optimize vectors using svgo. Example
to-css-custom-properties Transform design tokens in CSS Custom Properties. Example
to-css-font-import Create CSS @font-face rules to import your font files. Example
to-css-text-style Create text styles as CSS classes. Example
to-dsp Create a Design System Package (DSP). Example
to-jss Transform design tokens in JSS. Example
to-flutter Transform design tokens for Flutter. Example
to-react-native Transform design tokens to a JavaScript theme object compatible with React Native. Example
to-scss-map Generate .scss files containing SCSS map and function / mixin to access the values of the tokens. Example
to-scss-mixin-text-style Create text styles formatted as SCSS mixins. Example
to-scss-variables Transform design tokens in SCSS variables. Example
to-style-dictionary Generate Style Dictionary configuration files for all your design tokens coming from Specify. Example
to-tailwind Create a theme compatible with the TailwindCSS specification. The theme is also compatible with WindiCSS. Example
to-theme-ui Create a theme compatible with the theme-ui specification. Example
to-typescript-definition Generate TypeScript types corresponding to Specify Token types. Their respective values match the name of your design tokens returned by Specify. Example

How to create your own parser?

Let's say you want to create a parser named my-parser.

  1. Fork the current repository
  2. Git clone the forked repository
  3. In the directory parsers, create a directory named my-parser
  4. Create your valid parser
  5. Make a PR

Creating a valid parser

To be valid, your parser needs:

Usable libraries

For now, our parsers only use the following libraries:

If you need another library to develop your parser:

  1. Install it using yarn or npm
  2. Import and export it in the parsers/global-libs.ts file

Testing

To easily create and test your parsers, we advise you to use them on design tokens provided in the seeds.json file. It will allow you to use our fake tokens to test your parsers.

To use our design tokens seed:

  1. Import it in your [parser].spec.ts using import * as seeds from '../../seeds.json';
  2. Use the seeds.tokens variable according to your needs.
  3. Launch yarn test to tests your parsers

Using your own tokens as seed data

If you want to use your own tokens to test your parsers against, you can pull down your tokens in JSON format using the Specify CLI with the following configuration:

rules: [
    {
      "name": "design tokens",
      "path": "tokens.json"`,
    },
  ],