figma token studio와 github 연동

디자인 시스템을 구축해야하는 일이 생겨서 보일러 플레이트를 만들어 보았다
작동 순서는 다음과 같다.

1. figma 작업, token studio 이용해서 token.json 발행해 git에 push
2. token.json를 각 테마별 (core, dark, light)로 분리
3. 분리된 json을 js로 바꿔 스타일 적용
4. 위의 과정을 git action으로 자동화

token studio가 업데이트가 된 것 같은데, 인터넷에 자료가 많이 없는 것 같아 기록용으로 남겨본다 (o゜▽゜)o☆

0. github token 발급, repository 설정

https://docs.tokens.studio/token-storage-and-sync/sync-provider-github?ref=addprovider

위의 링크대로 설정해준다.

1. token studio 설정

figma에 token studio 플러그인을 설치한다.
https://www.figma.com/community/plugin/843461159747178978/tokens-studio-for-figma

설치 후 plugin을 불러온다.

나는 example을 이용해서 보일러 플레이트를 만들었다.





Setting > Sync providers > Add new sync provider에서 Github을 선택한다.

Name - github 계정 이름
Personal Access Token - 0번에서 만들었던 Access Token
Repository - github 계정 이름/repository 이름
Branch - push할 branch 이름
Token storage location - json file의 위치

그리고 token studio가 업데이트 되면서 json 파일의 형식이 바뀐 것 같다.

W3C DTCG format 버튼을 눌러 json 파일 형식을 오른쪽 방식처럼 변환해야한다.

이렇게 설정을 마쳤으면, github에 수동으로 push할 수 있다. (또는 PR)

성공적으로 push되었으면 git 프로젝트에 token.json이 생성된 것을 확인할 수 있다.

2. token.json을 각 테마별로 분리하기

token studio example을 사용했다면 하나로 추출된 token.json의 metadata에는 core, dark, light 등의 key가 있다.
이 key들로 token.json을 분리한다.

분리 작업을 위해 token transformer를 설치한다.

npm i token-transformer

https://velog.io/@seo__namu/Token-Transformer-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0-u6uwunqe

위의 글을 참고해서 config 파일을 만들었다.

// tt.config.js
const fs = require("fs");
const path = require("path");
const { transformTokens } = require("token-transformer");

// 추출 대상 파일 경로
const filePath = "src/tokens";
const dir = path.join(__dirname, filePath);
// 만약 없다면 생성
if (!fs.existsSync(dir)) {
  fs.mkdirSync(dir, { recursive: true });
}

// 변환 옵션
const transformerOptions = {};

// 파일 읽기
fs.readFile("token.json", "utf8", (err, data) => {
  if (err) throw err;
  const tokens = JSON.parse(data);

  // $metadata에 token key가 있음
  const tokenKeys = [...tokens.$metadata.tokenSetOrder];

  tokenKeys.forEach((key) => {
    // 변환 작업
    const resolved = transformTokens(
      tokens, // 변환할 파일
      key === "light" || key === "dark" ? ["core", key] : tokenKeys, // 참조 대상
      [...tokenKeys].filter((k) => k !== key), // 추출 제외 대상
      transformerOptions // 변환 옵션
    );

    // 파일 생성
    fs.writeFileSync(
      `${filePath}/${key}.json`,
      JSON.stringify(resolved),
      (err) => {
        if (err) throw err;
      }
    );
  });
});

이제 터미널에 node tt.config.js 명령어로 token.js 파일을 분리할 수 있게 되었다.

3. 분리된 json을 js로 바꿔 스타일 적용

프로젝트에 styled component를 이용해 style 적용을 하고 싶었기 때문에 json을 js로 바꾸는 작업을 진행했다.

이 과정에서는 style-dictionary 라이브러리를 사용했다.

npm i style-dictionary

2번에서 분리된 각각의 json들을 js로 변환한다.

//style.dictionary.config.js
const StyleDictionary = require("style-dictionary");
const fs = require("fs");

fs.readFile("token.json", "utf8", (err, data) => {
  if (err) throw err;
  const tokens = JSON.parse(data);

  // $metadata에 token key가 있음
  const tokenKeys = [...tokens.$metadata.tokenSetOrder];

  tokenKeys.forEach((key) => {
    const StyleDictionaryExtended = StyleDictionary.extend({
      source: [`./src/tokens/${key}.json`],
      platforms: {
        js: {
          transformGroup: "js",
          buildPath: `./src/style/${key}/`,
          files: [
            {
              destination: "variables.js",
              format: "javascript/es6",
            },
          ],
        },
      },
    });

    StyleDictionaryExtended.buildAllPlatforms();
  });
});

터미널에 node style.dictionary.config.js 를 입력해서 js로 변환할 수 있게 되었다.

4. git action으로 자동화

# transform-tokens.yml
name: Transform Tokens
 
on:
  push:
    branches:
      - main
    paths:
      - token.json
 
jobs:
  transform-tokens:
    runs-on: ubuntu-latest
 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
 
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
 
      - name: Install dependencies
        run: npm install
 
      - name: Install token-transformer
        run: npm install token-transformer

      - name: Install style-dictionary
        run: npm install style-dictionary@3.8.0
 
      - name: Run Token Separator
        run: |
            node tt.config.js
        env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Use the default GitHub token
 
      - name: Run Token Transformer
        run: |
            node style.dictionary.config.js
        env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Use the default GitHub token
 
      - name: Check for changes
        run: |
          if git diff --exit-code; then
            echo "No changes detected";
            exit 0;
          fi
 
      - name: Commit changes
        run: |
          git config --global user.name ""
          git config --global user.email ""
          git add .
          git commit -m 'Figma updated styles'
          git push
 
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}  # Use default GitHub token if ACCESS_TOKEN is unavailable
          commit-message: Transform tokens and update styles
          branch: transform-tokens-branch
          title: "Transform tokens and update styles"
          body: "This PR transforms tokens and updates styles automatically."
          base: main

git user name, email을 제외한 yml 파일이다.

이렇게 해서 figma에서 token을 변경하면 자동으로 git에 push되고, 그 token.js 파일을 테마별로 분리/ js로 변환까지 자동으로 되게끔 flow를 짜두었다.