토큰 기반 디자인시스템 만들기 – 실전 구축기

문서를 읽으시면서 아래 링크로 완성된 전체 코드를 함께 살펴보시는 것을 추천합니다.

1. 왜 디자인 토큰인가?

과거에는 디자인 시스템을 만들 때, 피그마에서 Foundation(컬러, 타이포 등)과 컴포넌트 정보를 하나하나 코드로 옮기고, 색상 팔레트나 타이포그래피를 직접 변수로 변환해서 프로젝트에 적용했습니다.
이 과정은 반복적이고, 토큰이 바뀔 때마다 개발자와 디자이너가 모두 신경 써야 했죠.

하지만!
이제는 디자인 토큰을 활용하면, 피그마에서 정의한 값을 다양한 플랫폼(웹, 앱)에서 자동으로 활용할 수 있습니다. 게다가 웹에서는 css, tailwind(v4, v3), scss, js-in-css 등 다양한 방식을 지원하도록 할수도 있습니다.

2. 디자인 토큰 추출 – Figma → Style Dictionary

2-1. Figma에서 토큰 정의

피그마에서 아래와 같이 컬러, 타이포그래피 등 토큰을 JSON 형태로 정의합니다. 단 이 형태로 바로 토큰을 정의할순 없기에 토큰 스튜디오 플러그인을 설치해야 합니다. https://tokens.studio/

그럼 plugin > token studio 클릭후 표시되는 창을 통해 토큰을 설정할수 있습니다.

{
  "primary": {
    "soil": {
      "50": { "value": "#d9d9d9", "type": "color" },
      "100": { "value": "#a6a6a6", "type": "color" }
    }
  },
  "typo": {
    "regular": {
      "headline1": { "value": { "fontWeight": "400", "fontSize": "48" }, "type": "typography" }
    }
  }
}

이렇게 만든 토큰은 Figma 플러그인(예: Tokens Studio, Guide Map 등)을 활용해 쉽게 관리할 수 있습니다.
토큰이 변경/추가될 때마다 플러그인으로 자동화된 프리뷰와 가이드도 생성할 수 있어, 디자이너의 반복 작업이 크게 줄어듭니다.

2-2. 실제 피그마에서 토큰 기반으로 만든 가이드

피그마 Foundation 가이드 예시

3. Style Dictionary로 멀티 플랫폼 토큰 변환

3-1. 프로젝트 구조 예시

실제 프로젝트에서는 아래와 같이 폴더를 구성했습니다.

design-system-practice/
├── config.json                # style-dictionary 설정
├── design-token/
│   ├── android/               # 안드로이드용 토큰
│   ├── css/                   # CSS 변수
│   ├── ios-swift/             # iOS용 토큰
│   ├── js/                    # JS 변수
│   ├── scss/                  # SCSS 변수
│   └── tailwind/              # Tailwind용 JSON
├── scripts/
│   └── generate-foundation-stories.mjs
├── stories/
│   └── Foundation/            # Storybook용 스토리
├── tokens/
│   └── global.json            # Figma에서 추출한 토큰
└── ...

3-2. Style Dictionary 설정 및 빌드

tokens/global.json에 Figma에서 추출한 토큰을 넣습니다.
config.json에서 각 플랫폼별로 어떤 포맷으로 토큰을 변환할지 정의합니다.
npm run build를 실행하면, design-token/ 아래에 각 플랫폼별 토큰 파일이 자동 생성됩니다.

예시:

design-token/css/_variable.css
design-token/tailwind/_variable.json
design-token/js/_variable.js
등등

4. Storybook, Tailwind, 실제 적용

4-1. Storybook에서 토큰 프리뷰

css/_variable.css를 Storybook의 preview.js에 import하면, 스토리북 내에서 토큰을 바로 사용할 수 있습니다.
stories/Foundation/ 폴더에 컬러, 폰트사이즈, 폰트웨이트, 타이포그래피 등 토큰별 Story를 만들어, 실제 토큰 값이 어떻게 보이는지 바로 확인할 수 있습니다.

4-2. Tailwind v4와의 연동

Tailwind v4부터는 CSS 변수를 직접 유틸리티 클래스에서 참조해 @theme 을 구성할수 있습니다.(아쉽게도 자동으론 안됩니다. 커스텀 로직 짜야해요 현재는 v3 기준으로 설정파일을 뱉어 줍니다) 이 작업을 미리 해 두면 추후 dark/light 모드 구현도 손쉽게 가능합니다 (이 블로그도 같은 방법으로 만들어짐)

tailwind.css 파일에 아래와 같이 설정해 두면 bg-primary-soil-50, text-primary-soil-50 등 tailwind className 을 사용해 바로 색상값 적용이 가능합니다.

@import 'tailwindcss';
@import '../design-token/css/_variable.css';

/* 이 부분까지는 자동화 하지 않고 테스트를 위해 수동으로 작성함. 필요시 이 부분도 자동 생성하도록 코드 커스텀 가능 */
@theme {
  --color-primary-soil-50: var(--primary-soil-50);
  --color-primary-soil-100: var(--primary-soil-100);
  --color-primary-soil-200: var(--primary-soil-200);
  --color-primary-soil-300: var(--primary-soil-300);
  --color-primary-soil-400: var(--primary-soil-400);
  --color-primary-soil-500: var(--primary-soil-500);
  --color-primary-soil-600: var(--primary-soil-600);
}

5. 실전 팁 & 마무리

토큰 관리 자동화: Figma → Style Dictionary → Storybook/Tailwind까지 자동화하면, 디자이너와 개발자 모두 반복 작업이 크게 줄어듭니다.
토큰 변경 대응: 토큰이 바뀌면 Figma에서 export → Style Dictionary 빌드만 하면, 모든 플랫폼에 즉시 반영됩니다.
확장성: Android, iOS, Web 등 다양한 플랫폼에 동일한 토큰을 일관되게 적용할 수 있습니다.

6. 사용시 주의할 점

style-dictionary 는 오픈소스이기에 모든 상황에 항상 완벽하지 않습니다. 하지만 이 오픈소스 개발자도 그 점을 잘 알고 있기에 커스텀 함수를 만들어 토큰을 원하는 방식으로 파싱할수 있도록 기능을 제공하고 있습니다.

tailwindv4 를 사용할 경우 지금은 v3 기준이기에 별도 함수 작업 필요.
Android, iOS 는 값이 객체인 경우(type 이 typography 일때)는 제대로 값을 참조할수 없습니다. 객체를 각각의 값으로 바꿔 파싱해야 합니다.

그래도 전반적으로는 이 동작을 통해 하나하나 수동으로 만들고 있었던 이 동작을 쉽게 할수 있었어요.

참고 코드/리소스

이렇게 하면, 디자인 토큰 기반의 디자인 시스템을 효율적으로 구축하고,
디자이너-개발자 협업도 훨씬 수월해집니다!

혹시 실제 코드 예시나, 각 단계별 상세 설정법(예: style-dictionary config, Storybook 연동법 등)이 더 필요하시면 말씀해 주세요.
실제 프로젝트의 config나 스크립트, 스토리북 설정 등도 구체적으로 추가해드릴 수 있습니다.