Introduction

The Specify GitHub app enables you to synchronise your design data between your Specify and GitHub repositories.

Like our REST API, you can configure Specify to automatically sync your design tokens and assets to your GitHub repositories.

Follow the installation guide to set up our Specify GitHub app.

Installation

Install the Specify GitHub app by:

  1. Installing GitHub from Specify's applications catalog
  2. Creating a .specifyrc.json containing your configuration at the root level of your GitHub repository

By the way, during the installation, you can control which GitHub repositories Specify can have access to.

Config File

The file must be named .specifyrc.json and must be put at the root of your project.

The config file accepts the following properties:

  • repository string required

    The repository containing the design tokens you're requesting. It follows the pattern @owner/repositoryName.

  • rules Array required

    The list of all the rules that will be applied during the design tokens extraction.

  • head string optional

    The name of the branch used to create pull requests.

  • base string optional

    The name of the branch where pull requests will be merged.

Example .specifyrc.json

{
  "repository": "@owner/repositoryName",
  "head": "specify",
  "rules": [
    {
      "name": "Design Tokens / Colors",
      "path": "assets/styles/variables/colors.css",
      "filter":{
        "types": ["color"]
      },
      "parsers": [
        {
          "name": "sort-by",
          "options": {
            "keys": ["name"]
          }
        },
        {
          "name": "to-css-custom-properties"
        }
      ]
    }
  ]
}

Usage

Learn how to configure the Specify configuration to tailor it for your project requirements.

Simple use case: Get colors in CSS Custom Properties

We want all colors in a single file named colors.css placed in a assets/styles/variables/ folder.

This use case requires a single rule in addition to the repository:

  • Repository name: The name of the Specify repository containing your design tokens and assets. In format @owner/repositoryName.
  • Rule: This rule requires a path to write the CSS file, a filter to retrieve only design tokens of type color, and a parser named to-css-custom-properties to transform colors in CSS Custom Variables.

Advanced use case: Get many design tokens in CSS Custom Variables and optimized icons

We want all our colors CSS variables in:

  1. kebabcase
  2. hsl
  3. sorted by name in a single file named dark-theme.scss with the :root[data-theme='dark'] CSS selector
  4. placed in a assets/styles/variables/ folder

We will get other design tokens in:

  1. kebabcase
  2. a file named general.scss
  3. placed in the same assets/styles/variables/ folder

Also, we will write all vectors in:

  1. separate SVG files named in kebabcase
  2. a folder named assets/

Finally, our pull request to be:

  1. Created on a branch named design/specify/brand
  2. Merged on a branch named staging

We need want to generate three different outputs for our colors, other styles and vectors. Hence we need to create three additional rules in addition to the repository one.

Let's go through all our configuration properties:

  • Repository: The name of your Specify repository containing your design tokens and assets. In format @owner/repositoryName.
  • Rule for our colors: This rule requires a path to write our scss file, a filter to retrieve only design tokens of type color, and one parser: to-css-custom-properties.
  • Rule for other design tokens: This rule requires a path to write our scss file, a filter to retrieve all design tokens except assets and color, and one parser: to-css-custom-properties.
  • Rule for vectors: This rule requires a path to write our SVG files, a filter to only pull design tokens of type vector, and one parser to optimize them: svgo.

Example .specifyrc.json for colors in CSS Custom Variables

{
  "repository": "@owner/repositoryName",
  "rules": [
    {
      "name": "Design Tokens / Colors",
      "path": "assets/styles/variables/colors.css",
      "filter":{
        "types": ["color"]
      },
      "parsers": [
        {
          "name": "to-css-custom-properties"
        }
      ]
    }
  ]
}

Example .specifyrc.json for advanced flow

{
  "repository": "@owner/repositoryName",
  "base": "staging",
  "head": "design/specify/brand",
  "rules": [
    {
      "name": "Design Tokens / Colors",
      "path": "assets/styles/variables/colors.scss",
      "filter": {
        "types": ["color"]
      },
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "options": {
            "formatTokens": {
              "color": "hsl"
            },
            "formatConfig": {
              "selector": ":root[data-theme='dark']"
            }
          }
        }
      ]
    },
    {
      "name": "Design Tokens",
      "path": "assets/styles/variables/general.scss",
      "filter": {
        "types": ["border", "depth", "duration", "gradient", "measurement", "opacity", "shadow"]
      },
      "parsers": [
        {
          "name": "to-css-custom-properties"
        }
      ]
    },
    {
      "name": "Assets",
      "path": "assets/",
      "filter": {
        "types": ["vector"]
      },
      "parsers": [
        {
          "name": "svgo",
          "options": {
            "svgo": {
              "plugins": [
                {
                  "removeDimensions": true
                },
                {
                  "removeAttrs": {
                    "attrs": "*:(fill|stroke)"
                  }
                },
                {
                  "addAttributesToSVGElement": {
                    "attributes": ["width=\"1em\"", "height=\"1em\""]
                  }
                }
              ]
            }
          }
        }
      ],
    }
  ]
}