Tokens Studio와 GitHub Actions

개발자와 디자이너 간의 협업을 지원하는 다양한 도구들이 도입되고 있다.
Figma의 Variables와 Tokens Studio는 이러한 협업 도구 중 일부로, 디자인 변경 사항을 실시간으로 PR에 반영하여 불필요한 커뮤니케이션 비용을 줄일 수 있다. 사내 메신저로 변경 사항을 일일이 전달하고 있다면 이러한 도구를 통해 효율성을 크게 높일 수 있다.

디자인 토큰은 개발자와 디자이너가 동일한 소스 기반으로 작업할 수 있도록 하여, 생산성을 높이고 일관성 있는 서비스를 제공할 수 있게 한다. 개발자가 사용할 수 있도록 디자인 토큰을 변환하는 과정이 필요한데 이를 github actions와 결합해 자동화된 워크플로우를 통해 개발 환경으로 업데이트 되도록 만들 수 있다.

1. GitHub 토큰 발급(Personal access token)

2. Tokens Studio 설정
   플러그인 설치 및 settings

3. GitHub 저장소 연결
   access token을 사용해 피그마와 깃허브 연동하기
   디자인 토큰 JSON 형식으로 내보내기

4. GitHub Actions 워크플로우 생성
   디자인 토큰 변환 스크립트
   SCSS 변환 스크립트
   PR 생성(커밋 메시지, 브랜치, 타이틀 등)

GitHub 토큰 발급(Personal access token)

✅ 토큰 발급 경로

Tokens Studio와 github를 연동하려면 토큰이 필요하기 때문에 아래 경로를 통해 새로운 토큰을 발급받는다.

👉 GitHub > Settings > Developer setting > Personal access tokens > Tokens(classic)
👉 Generate new token > Generate new token(classic)

✅ 각 액션에 필요한 권한 범위 선택

프로젝트에 필요한 범위 안에서 선택하면 되는데 GitHub Actions를 사용하여 CI/CD 파이프라인을 설정하고 관리하기 위해 repo 및 workflow 권한을 선택했다.

• repo
  모든 퍼블릭 및 프라이빗 저장소에 대한 전체 액세스를 허용합니다. 이는 읽기, 쓰기, 삭제 권한을 포함합니다.
• workflow
  GitHub Actions 워크플로우에 대한 읽기 및 쓰기 권한을 허용합니다. 새로운 배포 파이프라인을 설정하거나 기존 파이프라인을 수정할 때 이 권한이 필요합니다.
• admin:repo_hook
  저장소의 웹훅을 관리하여 다양한 자동화 및 통합 작업을 가능하게 합니다. CI/CD 서버에 빌드 트리거를 전송하거나, 슬랙 같은 외부 서비스에 알림을 보낼 수 있습니다.

✅ 토큰 저장

위와 같이 체크 후 generate token 버튼을 클릭하면 토큰이 발행되는데 이때 꼭 토큰을 복사해서 저장해야된다.

☹︎ Caution
Make sure to copy your personal access token now. You won’t be able to see it again!

Tokens Studio 설정

✅ github 연동 경로

Tokens Studio install > New empty file > settings > Add new > GitHub

✅ Add new credentials

• Name : GitHub 계정 이름
• Personal Access Token : GitHub에서 생성한 토큰
• Repository(owner/repo) : GitHub 저장소 소유자 / 저장소 이름
• Branch : 디자인 토큰 파일을 push할 브랜치 👉 ex) design
• File Path : 디자인 토큰 파일 👉 ex) tokens.json (file 확장자: .json)

✅ Push to local

💡 변경 사항이 생길 때마다 커밋 메시지 작성 후 앞에서 연결한 깃허브 레포로 PR을 생성할 수 있다

1. 커밋 메시지 작성
   디자인 토큰을 변경한 후, Tokens Studio에서 변경 사항을 커밋

2. Push Changes
   design 브랜치 커밋 업데이트

3. 팝업 창 확인
   PR 남길 경우 : Create Pull Request 버튼 클릭

4. GitHub PR 생성

📂 tokens.json

Tokens Studio를 통해 받아온 tokens.json 파일은 변수 및 스타일 정보를 포함하고 있지만, SCSS나 CSS에서 바로 사용할 수 없다. SCSS 변수로 변환하기 위해 아래 두 단계를 거쳐야 한다.

1. Token Transformer
   tokens.json 파일의 global 키 값을 참조하여 Token Transformer를 사용해 1차 변환을 수행합니다.

2. style-dictionary
   1차 변환된 데이터를 SCSS 파일에서 사용하기 위해 style-dictionary를 사용하여 2차 변환을 수행합니다.

Token Transformer로 변환하기

Token Transformer는 Figma Tokens Studio plugin에서 추출된 json 파일을 변환하는 도구이다.

npm install token-transformer

✅ 추출하기

node token-transformer [input] [output] [sets] [excludes]
node token-transformer [input.json] [output.json] [global,dark,components] [global]

• input
  변환할 파일의 경로와 이름입니다. 예: token.json
• output
  변환 후 저장할 파일의 경로와 이름입니다. 예: ./tokens/global.json
• sets
  변환할 때 참조할 키 값을 지정합니다.
• excludes
  변환에서 제외할 키 값을 지정합니다.

style-dictionary로 변환하기

npm install style-dictionary

✅ transformToken.js 생성 (공식문서에 제공하는 기본 config 설정)

const StyleDictionary = require('style-dictionary').extend({
  source: ['./tokens/global.json'], //token 파일이 위치하는 경로(프로젝트 경로로 수정하세요.)
  platforms: {
    scss: {
      transformGroup: 'scss',
      buildPath: 'build/scss',
      files: [
        {
          destination: '_variables.scss',
          format: 'scss/variables',
        },
      ],
    },
  },
});

StyleDictionary.buildAllPlatforms();

✅ 추출하기

node transformToken.js

GitHub Actions로 자동화하기

피그마 디자인 수정 → token studio를 사용하여 commit → GitHub PR 생성 → JSON 파일 처리 → core를 참조하는 변수들 변환(Token Transformer) → SCSS 파일로 변환(style-dictionary) → 사용

위의 모든 과정을 개발자가 수동으로 처리하는 대신, GitHub Actions를 사용하여 워크플로우를 개선하고 효율성을 높일 수 있다.

✅ 액션 순서 생각해보기

1. design 브랜치에 push가 발생할 때 tokens.json 파일을 감지합니다.
2. tokens.json 파일이 있다면 npx token-transformer tokens.json ./src/style/global.json core 명령을 실행합니다.(1차 변환)
3. node 스크립트 transformToken.js를 실행합니다.(2차 변환)
4. main 브랜치로 PR을 생성합니다.

📂 .github/workflows/transform-tokens.yml

name: Transform Tokens

on:
  push:
    branches:
      - design
    paths:
      - tokens.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: 20

      - name: Install dependencies
        run: npm install

      - name: Run Token Transformer
        run: |
            npx token-transformer tokens.json ./src/style/global.json core
            git config --global user.name "사용자"
            git config --global user.email "이메일"
            git add .
            git commit -m 'Figma updated styles'
            git push
        env:
            GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}

      - name: Run transform script
        run: node transformToken.js

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v4
        with:
          token: ${{ secrets.ACCESS_TOKEN }}
          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

• commit-message: PR에 포함될 커밋 메시지입니다.
• branch: PR을 생성할 브랜치 이름입니다.
• title: PR의 제목입니다.
• body: PR의 본문 내용입니다.
• base: PR을 병합할 기본 브랜치입니다.(main 브랜치로 설정)

마무리하며

디자인 수정 후 변경사항들이 자동화된 PR로 생성되면서, 명확하게 변경된 부분을 보여주기 때문에 개발자와 디자이너 간의 커뮤니케이션 비용을 크게 줄일 수 있게 된다.

이전에는 디자인 변동 사항을 사내 메신저로 전달하고, 팀별 회의를 통해 변경된 부분을 일일이 설명해야 하는 번거로움이 많았다. 심지어 피그마에 새로운 페이지를 생성하여 변경된 부분을 하나하나 옮기는 수고스러운 작업까지 했었는데, 커뮤니케이션 과정에서 모든 내용을 한 번에 전달하고 적용되는 것은 매우 어려운 일이라 반영되지 않은 부분들은 다시 회의를 통해 전달해야 했다.

디자인 시스템을 위한 플로우를 자동화함으로써 개발자와 디자이너 모두가 보다 원활하게 협업할 수 있는 환경을 만드는 것이 얼마나 중요한지를 다시 한 번 실감했다.