Tokens Studio + Tailwind CSS: 피그마 디자인 시스템 자동 업데이트 구축하기

1. Tokens Studio 설치

피그마의 플러그인 마켓에서 Tokens Studio for Figma를 검색하여 설치합니다. 이 플러그인은 디자인 토큰을 관리하고, 다양한 플랫폼과의 동기화 기능을 제공합니다.

2. Tokens Studio Figma 와 Github 연동하기

Tokens Studio for Figma 공식문서

2-1. GitHub 토큰 (Personal access token) 생성

Tokens Studio와 GitHub를 연동하기 위해서는 Personal Access Token이 필요합니다.

• GitHub에서 Settings → Developer settings → Personal access tokens → Tokens (classic)으로 이동합니다.
• Generate new token → Generate new token(classic) 버튼을 클릭합니다.

새로운 토큰을 생성할 때, repo 권한과 workflow 권한을 부여합니다.
이렇게 하면 레포지토리에 접근하고 GitHub Actions를 통해 자동화된 워크플로우를 설정할 수 있습니다.

💡 주의: 토큰 생성 후 화면에서만 확인할 수 있으니 따로 저장해두세요.

2-2. Tokens Studio에서 GitHub 연동 설정

• Tokens Studio 플러그인에서 Settings → Add new sync provider → GitHub 선택

• 설정항목 :
  Name : GitHub 계정이름
  Personal Access Token : 위에서 생성한 GitHub 토큰
  Repository : GitHub 저장소 주인 / 저장소 이름 (아래 사진 참조)
  Branch : 디자인 토큰 파일을 push 할 브랜치
  File Path : 저장될 토큰 파일의 경로와 이름 (.json 확장자 꼭 붙이기)

3. 디자인 토큰 업로드

design token 을 수정 후 활성화 된 업로드 버튼을 클릭하고 커밋 메시지를 작성한 후 Push Changes 버튼을 누르면 위에서 설정한 GitHub design 브랜치에 자동으로 푸시됩니다.

---

4. 디자인 토큰 변환 및 Tailwind CSS 적용

Tokens Studio에서 추출한 JSON 형태의 디자인 토큰을 프로젝트에서 사용하는 css 환경에 맞게 변환하여 사용할 수 있습니다.

CSS-in-JS를 사용한다면 Token Transformer만 사용해서 변환하고, CSS를 사용한다면 Style Dictionary를 사용할 수 있습니다..

Tailwind CSS에서 사용하기 위해서는 style-dictionary, @tokens-studio/sd-transforms ,sd-tailwindcss-transformer 라이브러리를 사용합니다.

1. 필요한 라이브러리 설치

$ pnpm add -D style-dictionary @tokens-studio/sd-transforms sd-tailwindcss-transformer

@tokens-studio/sd-transforms 라이브러리는 tokens studio 에서 받아온 토큰 파일을 style dictionary 를 통해 변환시켜줍니다.
sd-tailwindcss-transformer 라이브러리는 tailwind css 에서 해당 디자인 시스템 토큰을 사용할 수 있도록 tailwind.config.js 파일로 만들어줍니다.

디자인 토큰 파일 평탄화 (Flattening)

디자인 토큰 변환을 원활하게 하기 위해, default-token.json 파일은 1차 평탄화된 형태로 준비되어야 합니다.

예를 들어:

{
  "token-name": { "color": { "gray": "#e2e2e2" }, "font-size": { /* 생략 */ } }
}

위와 같은 구조라면, "token-name"을 제거한 아래와 같은 평탄화된 형태로 준비해야 합니다.

{ "color": { "gray": "#e2e2e2" }, "font-size": { /* 생략 */ } }

여러 토큰 중에서 선별적으로 사용하는 방법은 아래에서 설명합니다.

2. Style Dictionary 설정 파일 생성

sd-tokens-config.js 파일을 프로젝트 최상위 경로에 생성합니다.

// sd-tokens-config.js

import { register } from '@tokens-studio/sd-transforms';
import StyleDictionary from 'style-dictionary';

register(StyleDictionary);

const sd = new StyleDictionary({
  source: ['./tokens/default-token.json'], // Tokens Studio 에서 추출한 토큰
  preprocessors: ['tokens-studio'],
  platforms: {
    css: {
      transformGroup: 'tokens-studio', // <-- apply the tokens-studio transformGroup to apply all transforms
      transforms: ['name/kebab'], // 만들어질 token 이름 형태, 기본값 camel
      buildPath: '', // 생성될 파일 경로
      files: [
        {
          destination: 'tokens.json', // 반환될 토큰 파일 이름
          format: 'json',
        },
      ],
    },
  },
});

await sd.cleanAllPlatforms();
await sd.buildAllPlatforms();

실행방법 :

$ node sd-tokens-config.js

이 스크립트를 실행하면 buildPath 에 정해준 경로에 destination 에 정해준 이름으로tokens.json 파일이 생성됩니다.

3. Tailwind CSS 설정 파일 생성

tw-tokens-config.json 파일을 생성하여 Tailwind 설정을 자동 생성합니다.

import { makeSdTailwindConfig } from 'sd-tailwindcss-transformer';
import StyleDictionary from 'style-dictionary';

const sd = new StyleDictionary(
  makeSdTailwindConfig({
    type: 'all',
    source: ['./tokens.json'], 
    buildPath: '', // 반환될 위치
  }),
);

await sd.hasInitialized;
await sd.buildAllPlatforms();

실행방법 :

$ node tw-tokens-config.json

실행 후 tailwind.config.js 파일이 생성됩니다.

---

🍇 멀티 토큰 분리 및 선택적 사용

피그마의 Tokens Studio 플러그인에서 특정 디자인 토큰을 사용하지 않기 위해 체크 해제(inactive token)하더라도, github 으로 push 될 때에는 모든 디자인 토큰이 넘어옵니다.
일부 토큰만 선택적으로 사용하기 위해 토큰을 분리하는 스크립트를 작성합니다.

// default-tokens.json

// ref, sys 토큰을 사용하고, comp 토큰은 사용하지 않는 경우
{
  "ref" : {
    "font-family": { /* 생략 */ },
    "color": { /* 생략 */ },
  },
   "sys" : {
    "color": { /* 생략 */ },
  },
   "comp" : {
    "color": { /* 생략 */ },
  },
}

// split-tokens.js
import * as fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

// 현재 파일의 절대 경로 가져오기
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// tokens.json 파일 읽기 (절대 경로 사용)
const tokensPath = path.join(__dirname, 'default-token.json');
const tokens = JSON.parse(fs.readFileSync(tokensPath, 'utf-8'));

// `$metadata.tokenSetOrder`에 정의된 키들을 가져오기
const tokenSets = tokens.$metadata.tokenSetOrder;

// 각 키에 따라 파일 생성
await tokenSets.forEach((set) => {
  // tokenSetOrder 의 키가 'comp'인 경우, 해당 키는 파일로 생성하지 않음
  // Tokens Studio for Figma에서 comp 를 inactive 했는데도 파일이 생성되는 이슈가 있어서 추가
  if (set === 'comp') return;

  if (tokens[set]) {
    const data = JSON.stringify(tokens[set], null, 2);
    const outputPath = path.join(__dirname, `sd-${set}.json`);
    fs.writeFileSync(outputPath, data);
    console.log(`sd-${set}.json 파일이 생성되었습니다.`);
  }
});

console.log('JSON 파일 분리가 완료되었습니다.');

실행 :

$ node split-tokens.js

sd-ref.json, sd-sys.json 의 파일이 생성됩니다.
이를 통해 필요한 토큰만 Tailwind 설정에 반영할 수 있습니다.

💡 sd-tokens-config.js 에도 source 에 sd-ref.json, sd-sys.json 파일을 모두 포함하도록 바꿔야 합니다.

// sd-tokens-config.js

const sd = new StyleDictionary({
  source: ['./tokens/sd-*.json'], // sd- 로 시작하는 json 파일을 모두 변환

---

🍅 자동화된 빌드 스크립트 작성

package.json 에 스크립트를 추가하여 빌드를 자동화할 수 있습니다.

// package.json
{
  "scripts": {
    "split:tokens": "node split-tokens.js",
    "build:tokens:tailwind": "node sd-tokens-config.js && node tw-tokens-config.js"
  }
}

---

🍑 다음 단계: GitHub Actions로 자동화

이제 피그마에서 디자인 시스템 토큰을 수정하면 GitHub Actions를 통해 tailwind.config.js 파일이 자동으로 업데이트되도록 워크플로우를 설정할 예정입니다.
이 과정은 다음 포스트에서 자세히 다루겠습니다.

---

참고
프론트엔드에 디자인 시스템 적용하기
Tokens Studio X GitHub Actions-효율적인 시스템 구축하기
Figma design token 을 tailwind에서 사용하기