1 of 1

Configuration

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

Introduction

By default, without any parsers, Specify returns your design data as raw data:

Design tokens are returned in JSON
Assets are returned as files

A configuration file helps you:

request design tokens and assets from a Specify repository
transform them to fit your company standards thanks to rules, token types and parsers.

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 = {
  repository: '@acme-inc/all-design-data',
  personalAccessToken: '<your-personal-access-token>',
  rules: [],
};

.specifyrc.json

{
  "repository": "@acme-inc/all-design-data",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

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

Personal Access Token

The Specify personalAccessToken used to authenticate your actions.

Need a personal access token? Generate one ↗

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

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

Rules

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.

A rule is composed of the following properties:

interface Rule {
  name: string;
  path: string;
  filter?: {
    types: Array<TokenType>
  };
  parsers?: Array<Parser>;
};

Parsers

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

Inside a configuration, a parser has the following properties:

interface Parser {
  name: string;
  options?: Record<string, any>;
}

Example

Here's a rule named "Design Tokens" that:

targets color and measurement design tokens
sorts them alphabetically by their name
transforms them as CSS Custom Properties
writes them in a design-tokens.css file inside a styles folder

.specifyrc.js

[
  {
    name: 'Design Tokens',
    path: 'styles/design-tokens.css',
    filter: {
      types: ['color', 'measurement']
    },
    parsers: [
      {
        name: 'sort-by',
        options: {
          keys: ['name']
        }
      },
      {
        name: 'to-css-custom-properties'
      }
    ]
  },
]

.specifyrc.json

[
  {
    "name": "Design Tokens",
    "path": "styles/design-tokens.css",
    "filter": {
      "types": ["color", "measurement"]
    },
    "parsers": [
      {
        "name": "sort-by",
        "options": {
          "keys": ["name"]
        }
      },
      {
        "name": "to-css-custom-properties"
      }
    ]
  }
]

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
a valid personal access token (Generate one ↗)

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 all-design-data from the @acme-inc organization:

.specifyrc.json

{
  "repository": "@acme-inc/all-design-data",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "All design tokens in JSON",
      "path": "design-tokens.json",
      "parsers": []
    }
  ]
}

.specifyrc.js

module.exports = {
  repository: '@acme-inc/all-design-data',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: 'All design tokens in JSON',
      path: 'design-tokens.json',
      parsers: [],
    },    
  ],
};

This example config file will return a design-tokens.json file containing all design tokens and assets stored in the all-design-data repository.

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

{
  "id": String,
  "createdAt": String,
  "updatedAt": String,
  "name": String,
  "value": Object,
  "meta": Object,
  "type": String,
  "originId": String,
  "sourceId": String,
  "description": String,
  "repositoryId": String
}

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

.specifyrc.js

module.exports = {
  repository: '@acme-inc/all-design-data',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: 'All design tokens in JSON',
      path: 'colors.css',
      filter: {
        types: ['color']
      },
      parsers: [
        {
          name: 'to-css-custom-properties',
          options: {
            formatTokens: {
              color: 'hsl'
            },
          },
        },
      ],
    },
  ],
};

.specifyrc.json

{
  "repository": "@acme-inc/all-design-data",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Colors as CSS Custom Properties",
      "path": "colors.css",
      "filter": {
        "types": ["color"]
      },
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "options": {
            "formatTokens": {
              "color": "hsl"
            }
          }
        }
      ]
    }
  ]
}

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

[
  {
    "name": "Primary/100",
    "value": {
      "a": 1,
      "b": 254,
      "g": 233,
      "r": 237
    },
    "type": "color",
    "description": ""
  },
  {
    "name": "Primary/200",
    "value": {
      "a": 1,
      "b": 254,
      "g": 214,
      "r": 221
    },
    "type": "color",
    "description": ""
  },
  {
    "name": "Primary/300",
    "value": {
      "a": 1,
      "b": 253,
      "g": 181,
      "r": 196
    },
    "type": "color",
    "description": ""
  }
]

colors.css

:root {
  /* COLOR */
  --primary-100: hsl(251, 91%, 95%);
  --primary-200: hsl(251, 95%, 92%);
  --primary-300: hsl(252, 95%, 85%);
}

Configuration

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

Introduction

By default, without any parsers, Specify returns your design data as raw data:

Design tokens are returned in JSON
Assets are returned as files

A configuration file helps you:

request design tokens and assets from a Specify repository
transform them to fit your company standards thanks to rules, token types and parsers.

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 = {
  repository: '@acme-inc/all-design-data',
  personalAccessToken: '<your-personal-access-token>',
  rules: [],
};

.specifyrc.json

{
  "repository": "@acme-inc/all-design-data",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

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

Personal Access Token

The Specify personalAccessToken used to authenticate your actions.

Need a personal access token? Generate one ↗

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

{
  "repository": "@workspace/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": []
}

Rules

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.

A rule is composed of the following properties:

interface Rule {
  name: string;
  path: string;
  filter?: {
    types: Array<TokenType>
  };
  parsers?: Array<Parser>;
};

Name

Type

Required

Description

Parsers

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

Inside a configuration, a parser has the following properties:

interface Parser {
  name: string;
  options?: Record<string, any>;
}

Name

Type

Required

Description

Example

Here's a rule named "Design Tokens" that:

targets color and measurement design tokens
sorts them alphabetically by their name
transforms them as CSS Custom Properties
writes them in a design-tokens.css file inside a styles folder

.specifyrc.js

[
  {
    name: 'Design Tokens',
    path: 'styles/design-tokens.css',
    filter: {
      types: ['color', 'measurement']
    },
    parsers: [
      {
        name: 'sort-by',
        options: {
          keys: ['name']
        }
      },
      {
        name: 'to-css-custom-properties'
      }
    ]
  },
]

.specifyrc.json

[
  {
    "name": "Design Tokens",
    "path": "styles/design-tokens.css",
    "filter": {
      "types": ["color", "measurement"]
    },
    "parsers": [
      {
        "name": "sort-by",
        "options": {
          "keys": ["name"]
        }
      },
      {
        "name": "to-css-custom-properties"
      }
    ]
  }
]

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
a valid personal access token (Generate one ↗)

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 all-design-data from the @acme-inc organization:

.specifyrc.json

{
  "repository": "@acme-inc/all-design-data",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "All design tokens in JSON",
      "path": "design-tokens.json",
      "parsers": []
    }
  ]
}

.specifyrc.js

module.exports = {
  repository: '@acme-inc/all-design-data',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: 'All design tokens in JSON',
      path: 'design-tokens.json',
      parsers: [],
    },    
  ],
};

This example config file will return a design-tokens.json file containing all design tokens and assets stored in the all-design-data repository.

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

{
  "id": String,
  "createdAt": String,
  "updatedAt": String,
  "name": String,
  "value": Object,
  "meta": Object,
  "type": String,
  "originId": String,
  "sourceId": String,
  "description": String,
  "repositoryId": String
}

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

.specifyrc.js

module.exports = {
  repository: '@acme-inc/all-design-data',
  personalAccessToken: '<your-personal-access-token>',
  rules: [
    {
      name: 'All design tokens in JSON',
      path: 'colors.css',
      filter: {
        types: ['color']
      },
      parsers: [
        {
          name: 'to-css-custom-properties',
          options: {
            formatTokens: {
              color: 'hsl'
            },
          },
        },
      ],
    },
  ],
};

.specifyrc.json

{
  "repository": "@acme-inc/all-design-data",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Colors as CSS Custom Properties",
      "path": "colors.css",
      "filter": {
        "types": ["color"]
      },
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "options": {
            "formatTokens": {
              "color": "hsl"
            }
          }
        }
      ]
    }
  ]
}

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

[
  {
    "name": "Primary/100",
    "value": {
      "a": 1,
      "b": 254,
      "g": 233,
      "r": 237
    },
    "type": "color",
    "description": ""
  },
  {
    "name": "Primary/200",
    "value": {
      "a": 1,
      "b": 254,
      "g": 214,
      "r": 221
    },
    "type": "color",
    "description": ""
  },
  {
    "name": "Primary/300",
    "value": {
      "a": 1,
      "b": 253,
      "g": 181,
      "r": 196
    },
    "type": "color",
    "description": ""
  }
]

colors.css

:root {
  /* COLOR */
  --primary-100: hsl(251, 91%, 95%);
  --primary-200: hsl(251, 95%, 92%);
  --primary-300: hsl(252, 95%, 85%);
}