Manage font files

Learn how to add font files to your Specify repositories once you've synced text styles.

Introduction

Sources like Figma and Tokens Studio manages textStyle and font token types as parameters applied to the fonts available on the host machine.

For both technical and legal reasons, Specify cannot extract font files from those sources, even though the SDTF is able to manage font files natively.

To bridge that gap, we'll share with you some techniques you can leverage to keep your font files in sync with your font and text styles tokens.

Prerequisites

Before we start you need:

• A Specify account with a repository

• One or more font files in the following formats: ttf, woff, woff2, otf, eot.

#1 The easy way: upload font files in Specify

#2 Add font files by creating your own SDTF graph

1. Host your font files

You are free to host your font files anywhere you can grab a public link to give Specify the ability to fetch the binaries.

We recommend using a company cloud storage like Amazon S3.

2. Create a SDTF tokens file

To register your font files to Specify, you need to create a SDTF JSON file containing your font tokens with the URLs from your cloud provider.

Example

tokens.json

{
  : {
    : {
      "$type": "font",
      "$value": {
        "default": {
          "family": "Inter Regular",
          "postScriptName": "Inter Regular",
          "weight": "regular",
          "style": "normal",
          "files": [
            {
              : "ttf",
              "url": "https://static.specifyapp.com/sdtf-seeds/inter-regular.ttf",
              "provider": "external"
            }
          ]
        }
      }
    }
  }
}

Type signature

type Font = {
  $type: 'font';
  $value: {
    [mode: string]: {
      family: string;
      postScriptName: string;
      weight:
        | 'thin'
        | 'hairline'
        | 'extra-light'
        | 'ultra-light'
        | 'light'
        | 'normal'
        | 'plain'
        | 'standard'
        | 'regular'
        | 'roman'
        | 'book'
        | 'medium'
        | 'semi-bold'
        | 'demi-bold'
        | 'bold'
        | 'extra-bold'
        | 'ultra-bold'
        | 'black'
        | 'heavy'
        | 'extra-black'
        | 'ultra-black'
        | number; // [100-1000]
      style: 'normal' | 'italic';
      files: Array<{
        url: string;
        format: 'ttf' | 'woff' | 'woff2' | 'otf' | 'eot';
        provider: 'external' | 'Specify' | 'Google Fonts' | 'Adobe Fonts';
      }>;
    };
  };
};

Note that you want to make the family property to match the font family used by your TextStyle or Font tokens.

3. Host your SDTF tokens file

To let Specify synchronize the font tokens into your repository, the SDTF JSON file must be hosted either privately or publicly.

Hosting on GitHub

1. Create a new public or private repository on github.com.
2. Add your SDTF JSON file containing the font tokens

A private GitHub repository containing the tokens.json file

1. Grab the raw file URL by accessing the raw file over your browser

Details over the tokens.json file to grab its raw file url

Hosting on JSONBin

1. Create a new private or public bin on https://jsonbin.io.
2. Place the content of your SDTF JSON file within it

A bin content with font tokens

1. Grab the URL

4. Synchronize your tokens with Specify

You can now navigate to your Specify repository and head to "Sources" -> "Create source"

1. Select the "Remote URL - Tokens Studio"

Specify web app - choose source step

1. Provide the URL to the font tokens file you created at step 3.

Specify web app - provide url step

1. (Optional) Provide authentication credentials for your provider. Read more about managing URL providers authentication.
2. Select the "Specify Design Tokens Format" option

Specify web app - select design token format

1. Create the source. The sync is executed on the source creation and should take few seconds.

5. Sync the font files in your codebase

Once your new font tokens are synced into your Specify repository, you can start pulling the font-files to your codebase.

Let's have a look to one of the parser rule that can be used into any configuration file:

Font Files parser rule

{
  "name": "Font files",
  "parsers": [
    {
      "name": "filter",
      "options": {
        "query": {
          "where": { "group": , "select": { "children": true } }
        }
      }
    },
    {
      "name": "change-case",
      "options": {
        "change": "names",
        "toCase": 
      }
    },
    {
      "name": "to-file",
      "options": {
        "filenameTemplate": 
      },
      "output": {
        "type": "directory",
        "directoryPath": "./public"
      }
    }
  ]
}

Once executed, the font files are available within the ./public/fonts directory.