search

lukasoppermann / design-token-transformer

Base repo to transform json design tokens from the figma design token plugin via amazon style dictionary.
MIT License
151 stars 225 forks source link

readme

Design Token Transformer

This package is supposed to be used together with the Design Tokens plugin for Figma. It transforms the exported design tokens using Amazon style dictionary.

Installation

1. Download or clone the repo to your computer

You can download this package or clone it via the terminal.

git clone https://github.com/lukasoppermann/design-token-transformer.git

2. Install dependencies

  1. From within the terminal cd (navigate) this folder.
  2. Run npm i to install the dependencies.

Usage

Option 1: Local transformation

To use an exported json file and transform it locally on your machine, follow the 3 steps below:

  1. Save the .json file you exported using the Design Token plugin to the tokens folder (and remove the example files).
  2. In the terminal cd (navigate) to this folder.
  3. Run npm run transform-tokens.
  4. 🎉 Your converted tokens should be in the build folder.

Option 2: Transformation in github repository (or on server)

1. Fork this repository.

It is recommended to create a fork of this repository and adapt it to your needs.
Should you decide to instead create a new repo, make sure to set up a .github/workflows file that handles the data.

2. Enable github actions in the actions tab

Go to the actions tab in your fork of this repository and enable the github actions by clicking the enable actions button.

3. Create a personal access token.
4. Add repo url & access token to plugin settings

In the plugin settings you need to add two items:

  1. Add the url to your repository in the format https://api.github.com/repos/:username/:repo/dispatches to the server-url field (See server-url for details)
  2. Add the personal access token to the access token field.
5. Run the Send Design Tokens to Url command from the plugin.
6. 🎉 You are done.

You should be able to see the action running in your GitHub repo and have all the converted files in the build folder once it is done.

7. Optional: Adapt the transform-tokens script in the package.json.

If you want to you can do something else when the tokens are pushed to the server you can change the transform-tokens script in the package.json. However note that the name of the script transform-tokens should not be changed.

8. Optional: Adapt the github workflow

You can adapt the workflow file if you need to. Just make sure the keep the current setup working.

Personal access token

The access token should be specifically for this plugin and only have the minimal permissions needed:

The token is not stored with the Figma file but only locally on your machine.

Here you can find more information about creating personal access tokens in the docs.

Custom dev server

If you want to set up a custom server that responds to a push from this plugin, check out the setup for GitHub and adapt it to your needs. If you run into problems, please create an issues in the main Design Tokens plugin for Figma repository.

Customization

To customize the output please view the Amazon style dictionary documentation.

FAQ

Sending tokens to the server

I don't see the tokens in the github repositiory

  1. Make sure you have a .github/workflows
  2. Make sure you enabled github actions in the actions tab of your repositiory.
  3. Verify that you specified the correct server url in the plugin settings: https://api.github.com/repos/{username}/{reponame}/dispatches (replace {username} with your username e.g. lukasoppermann and {reponame} with the name of your repo e.g. design-token-transformer)
  4. Verify that the action runs without any error

I can't enable github actions

If you only see the Get started with GitHub Actions page without an option to enable actions you either deleted the .github/workflows file from your forked repository, or you created a new repositiory without adding a .github/workflows file. See step 1.

Bugs, issues & feature requests

If you have issues concerning the Design Tokens plugin for Figma please create an issue in the plugin repo.

Only create an issue in this repository if you have an issue with this transformation package.