Giter VIP home page Giter VIP logo

figma-tokens-with-style-dictionary's Introduction

Use Figma Tokens Plugin with Style Dictionary

This repository serves as an example to illustrate how you can locally transform your tokens stored on Figma Tokens so they are up and ready for Style Dictionary to compile.


  1. Why the need for Token Transformer?
  2. Tokens Structure
  3. How to use this project in 3 steps
  4. Other considerations

First of all, let me begin with why we need Token Transformer in the first place.

Why the need for Token Transformer?

The short answer is: The way tokens are referenced across Token Sets in the Figma Plugin is not reflected in the Token Keys after tokens are exported. This results in Style Dictionary not being able to retrieve the token references.

For more information, please read this thread on Github and the suggested workflow by @jam-awake.

In the end, Token Transformer helps us remove any aliases that would result in errors during the Style Dictionary build. Token Transformer prepares a file that only output raw values that Style Dictionary can process.

Tokens Structure

At Apart, our tokens follow a multi-layers approach.

Layer Layer name Description
1 Core
(private tokens)
Tokens in this Layer store the raw values and with this build the basis of the Design Tokens. This Layer is mainly responsible for the look of the final product by defining all the values that can be used.
2 Semantic
(public tokens)
Tokens in this Layer reference Core Tokens. Their name describes the intended use of the Token. Tokens in this Layer are those which are used the most throughout the application. They represent the choices the Design team made in regards to when to use which Token.
3 Component
(scoped and overwrite tokens)
Tokens in this Layer reference Semantic Tokens and tie them to a specific Component value. A Component Token abstracts the value of a Semantic Token for use in a specific context or for a specific purpose. The name of the Component Token makes it clear where and how it applies.

for more information read our Design Tokens Guide.

Tokens structure in the Figma Tokens Plugin

To replicate this layers structure in the Figma Tokens Plugin we use Token Sets. A feature that allows us to semantically separate tokens and keep having the ability to make references (aliases) between them.

In a basic setup, we usually end up with two main Token Sets:

  • core (all the private tokens)
  • public (all the semantic and component tokens that reference core tokens)

A third Token Set can also co-exist but is not useful for developers: mobile-overrides. This Token Set can be ignored. This is for design purposes only.

Tokens structure after Figma Tokens file export

Figma Tokens generates for you a single file with all your tokens organised by Token Set. The exported file should look something like this:

// ./tokens/tokens.json
{
    "core": {...},
    "public": {...}
    // mobile-overrides if it exists
    // ... Plus any other Token Sets you might have created
}

With this file, references between public tokens and core tokens do not work out of the box with Style Dictionary. That is where Token Transformer comes into play.

Tokens structure after the Token Transformer compilation

Token Transformer generates a tokens file that get rid off any math operations or aliases only resulting in raw values. Your transformed tokens file should look something like this:

// ./transformed-tokens/tokens.json
{
    "core": {...},
    // List of all the basic public tokens you make use of organized by family:
    "font": {...},
    "color": {...},
    "space": {...},
    "size": {...},
    "opacity": {...},
    "borderWidth": {...},
    "borderRadius": {...},
    "boxShadow": {...},
    // ... Plus any component tokens
}

From there, you can use this file for your Style Dictionary build.

How to use this project in 3 steps

Do not forget to run npm i to install all dependencies first.

Step 1 - Export your tokens from the Figma Tokens Plugin

If your tokens are not sync anywhere:

  1. Open your Figma Project
  2. Open the Figma Tokens Plugin
  3. Click Export at the bottom of the window
  4. Check "All token sets"
  5. Check "Expand Typography" and "Expand Shadows"
  6. Click download and name your file tokens.json

If your tokens are sync and stored somewhere, maybe you can automate a flow and query this file at build time (this workflow is not documented here).

Step 2 - Transform your tokens with Token Transformer

With your tokens.json file available locally in your project you can run the transform-tokens command. This command expect your tokens.json file to be under a tokens directory at the root of your project: tokens/tokens.json.

This command will generate a transformed-tokens directory with a tokens.json file inside.

Step 3 - Compile your tokens with Style Dictionary

Define whatever you want Style Dictionary to do with your tokens in the sd.config.json file. Then, you can run the style-dictionary command. This command expect your transformed tokens to be in the transformed-tokens directory: transformed-tokens/tokens.json.

This command will generate a build directory with the output results configured in your Style Dictionary config file: sd.config.json.

For example, the default configuration integrated to this project will generate a _variables.sass file and a variables.js file.

For more information, see Style Dictionary configuration options.

Other considerations

Use transformers to get unit formats

By using this project without any additional Style Dictionary configuration you might end up with font, size or shadows properties without unit formats like %, em, px, ... You can use transformers to do that at build time. Read this github thread for more information.

figma-tokens-with-style-dictionary's People

Contributors

jptrinh avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.