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
  • Introduction
  • Properties
  • Repository
  • Personal Access Token
  • Parser Rules
  • Examples
  • How to run these examples
  • Basic
  • Pull colors as CSS Custom Properties

Was this helpful?

Export as PDF
  1. Guides

Configuration file 101

Learn more about how to setup your Specify configuration file to generate design tokens and assets fitting your company standards.

PreviousSpecify Design Token FormatNextSpecify CLI usage 101

Last updated 1 year ago

Was this helpful?

Introduction

Whenever you want to work with the or the destination, you need to create a Configuration file to instruct the how to transform your design data, so it generate tokens that match your technical requirements.

A configuration file helps you:

  1. request design tokens and assets from a Specify repository

  2. transform them to fit your company standards thanks to

Properties

A configuration is composed of 3 main properties:

  • repository

  • personalAccessToken

  • rules

Repository

The name of the Specify repository you want to pull your design tokens and assets from.

Let's say we have the following repository in Specify called "all-design-data" located in the "@acme-inc" organization.

We target it like this:

.specifyrc.js
module.exports = {
  version: '2'
  repository: '@acme-inc/all-design-data-v2',
  personalAccessToken: '<your-personal-access-token>',
  rules: [],
};
.specifyrc.json
{
  "version": "2"
  "repository": "@acme-inc/all-design-data-v2",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

Personal Access Token

The Specify personalAccessToken used to authenticate you.

module.exports = {
  version: '2'
  repository: '@workspace/repository',
  personalAccessToken: '<your-personal-access-token>',
  rules: [],
};
{
  "version": "2"
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

Parser Rules

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

You can have as many rules as you want and you can have rules that transform several Token types at once.

Here are different kind of rules and parsers you can use to generate color tokens as CSS Custom Properties:

.specifyrc.js
{
  version: '2',
  repository: '@organization/repository',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: 'css',
      parsers: [
        {
          name: 'filter',
          options: {
            query: {
              where: {
                collection: '^Colors$',
                select: {
                  children: true
                }
              }
            }
          }
        },
        {
          name: 'convert-color',
          options: {
            toFormat: 'hsl',
            applyTo: {
              collection: true
            }
          }
        },
        {
          name: 'change-case',
          options: {
            change: 'names',
            toCase: 'kebabCase',
            applyTo: {
              collection: true
            }
          }
        },
        {
          name: 'change-case',
          options: {
            change: 'modes',
            toCase: 'kebabCase',
            applyTo: {
              collection: true
            }
          }
        },
        {
          name: 'to-css-custom-properties',
          output: {
            type: 'file',
            filePath: 'tokens.css'
          },
        },
      ],
    },
  ],
};
.specifyrc.json
{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "css",
      "parsers": [
        {
          "name": "filter",
          "options": {
            "query": {
              "where": {
                "collection": "Colors",
                "select": {
                  "parents": true,
                  "children": true
                }
              }
            }
          }
        },
        {
          "name": "convert-color",
          "options": {
            "toFormat": "hsl",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "change-case",
          "options": {
            "change": "names",
            "toCase": "kebabCase",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "change-case",
          "options": {
            "change": "modes",
            "toCase": "kebabCase",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "tokens.css"
          }
        }
      ]
    }
  ]
}

Examples

How to run these examples

The following examples are made to be used with the Specify CLI.

Requirements:

  • a Specify repository containing design tokens

Run all examples by copying the code and running the specify pull command.

Basic

Here's a basic configuration file that targets a Specify repository called design-system from the @acme-inc organization:

.specifyrc.js
module.exports = {
  version: '2',
  repository: '@acme-inc/design-system',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: 'Generate colors as CSS Custom Properties',
      parsers: [
        {
          name: 'to-css-custom-properties',
          output: {
            type: 'file',
            filePath: 'colors.css'
          },
        },
      ],
    },
  ],
};
.specifyrc.json
{
  "version": "2",
  "repository": "@acme-inc/color-themes",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate colors as CSS Custom Properties",
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "colors.css"
          }
        }
      ]
    }
  ]
}

This example config file will return a colors.css file containing all design tokens stored in the design-system repository.

Here's an example of a token value returned by Specify:

{
  "colors": {
    "$collection": {
      "$modes": [
        "Light",
        "Dark"
      ]
    },
    "core": {
      "blue-100": {
        "$type": "color",
        "$description": "token 1 aliased with n modes within collection within n groups",
        "$value": {
          "Light": {
            "red": 219,
            "blue": 254,
            "alpha": 1,
            "green": 236,
            "model": "rgb"
          }
        }
      }
    }
  }
}

Pull colors as CSS Custom Properties

Now let's update our previous configuration to only pull colors and transform them as CSS Custom Properties in RGB.

.specifyrc.js
module.exports = {
  version: '2',
  repository: '@acme-inc/design-system',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: 'Generate colors as CSS Custom Properties',
      parsers: [
        {
          name: 'convert-color',
          options: {
            toFormat: 'rgb',
            applyTo: {
              collection: true
            }
          }
        },
        {
          name: 'to-css-custom-properties',
          output: {
            type: 'file',
            filePath: 'colors.css'
          },
          options: {
            tokenNameTemplate: '--{{groups}}-{{token}}',
            selectorTemplate: '[data-theme=\'{{mode}}\']',
            includeCoreTokensInScopes: true
          },
        },
      ],
    },
  ],
};
.specifyrc.json

{
  "version": "2",
  "repository": "@acme-inc/design-system",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate colors as CSS Custom Properties",
      "parsers": [
        {
          "name": "convert-color",
          "options": {
            "toFormat": "rgb",
            "applyTo": {
              "collection": true
            }
          }
        },
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "colors.css"
          },
          "options": {
            "tokenNameTemplate": "--{{groups}}-{{token}}",
            "selectorTemplate": "[data-theme=\"{{mode}}\"]",
            "includeCoreTokensInScopes": true
          }
        }
      ]
    }
  ]
}

Here is the input returned by Specify and the output generated by Specify after executing our configuration.

{
  "colors": {
    "$collection": { "$modes": ["Light", "Dark"] },
    "core": {
      "blue-100": {
        "$type": "color",
        "$description": "token 1 aliased with n modes within collection within n groups",
        "$value": {
          "Light": {
            "red": 219,
            "blue": 254,
            "alpha": 1,
            "green": 236,
            "model": "rgb"
          },
          "Dark": {
            "red": 41,
            "blue": 67,
            "alpha": 1,
            "green": 52,
            "model": "rgb"
          }
        }
      },
      "blue-700": {
        "$type": "color",
        "$description": "token 2 aliased with n modes within collection within n groups",
        "$value": {
          "Light": {
            "red": 17,
            "blue": 249,
            "alpha": 1,
            "green": 125,
            "model": "rgb"
          },
          "Dark": {
            "red": 96,
            "blue": 250,
            "alpha": 1,
            "green": 168,
            "model": "rgb"
          }
        }
      }
    },
    "semantic": {
      "background": {
        "button": {
          "primary": {
            "hover": {
              "$type": "color",
              "$description": "alias token with n modes within collection within n groups",
              "$value": {
                "Dark": {
                  "$mode": "dark",
                  "$alias": "colors.core.blue-100"
                },
                "Light": {
                  "$mode": "light",
                  "$alias": "colors.core.blue-700"
                }
              }
            }
          }
        }
      }
    }  
  }
}
colors.css
[data-theme="dark"] {
  --core-blue-100: rgb(41, 52, 67);
  --core-blue-700: rgb(96, 168, 250);
  --semantic-background-button-primary-hover: var(--core-blue-100);
}
[data-theme="light"] {
  --core-blue-100: rgb(219, 236, 254);
  --core-blue-700: rgb(17, 125, 249);
  --semantic-background-button-primary-hover: var(--core-blue-700);
}

You can only target one repository per configuration file. Want to pull design tokens from several Specify repositories? Create several configuration files and run them with the Specify CLI ().

Need a personal access token?

Looking for the rules configuration? 👉 review the reference.

to target on a specific collection named "Colors" that contains our colors

to convert our colors in HSL

to change the name of our tokens and modes to kebabCase

to generate a CSS file containing our tokens

a valid personal access token ()

See example script
Generate one ↗
filter
convert-color
change-case
to-css-custom-properties
Generate one ↗
GitHub
Specify CLI
Parsers Engine
parsers
Parser Rule
An example Specify repository called "all-design-data-v2" located in the "@acme-inc" organization.