피그마 디자인 토큰, 개발에서 제대로 쓰는 방법

피그마 디자인 토큰, 개발에서 제대로 쓰는 방법

디자인과 개발이 함께 작업하다 보면 자주 부딪히는 부분이 있다. 디자이너는 색상, 폰트, 여백 같은 세세한 요소들을 정리해두고 싶어 하고, 개발자는 이걸 코드로 효율적으로 쓰고 싶어 한다. 이때 등장하는 게 바로 ‘디자인 토큰’이다. 최근에는 피그마에서 토큰을 뽑아내서 개발에 활용하는 흐름이 점점 자리 잡고 있다. 그런데 막상 실무에서 이걸 어떻게 쓰는 건지 헷갈리는 경우가 많다. 오늘은 내가 정리한 내용을 토대로, 초보자도 이해할 수 있게 설명해보겠다.

디자인 토큰이란 뭘까?

디자인 토큰은 쉽게 말해 디자인 속성을 데이터화한 것이다. 예를 들어, "우리 브랜드의 메인 컬러는 빨간색"이라고 정의할 때 그냥 문서에 적어두는 게 아니라, 토큰이라는 이름표를 붙여 저장하는 거다. 이렇게 해두면 “primary-color”라는 이름으로 색상을 불러다 쓸 수 있다. 단순히 색상뿐 아니라 폰트 크기, 간격, 그림자, 모서리 둥글기까지 전부 토큰화할 수 있다.

피그마에서 토큰을 어떻게 뽑아내나?

피그마에는 디자인 토큰을 다룰 수 있는 플러그인들이 있다. 대표적으로 토큰 스튜디오 같은 플러그인이 있다. 디자이너는 여기서 컬러, 폰트, 스페이싱 같은 요소를 정의하고, 그걸 JSON 파일로 내보낼 수 있다. JSON이라고 하면 어렵게 느껴질 수 있는데, 그냥 구조화된 데이터 파일이라고 생각하면 된다.

즉, 디자이너가 피그마에서 “primary-color는 빨강”이라고 정의하면, JSON 파일에 "primary-color: #FF0000" 이런 식으로 저장되는 거다.

JSON 파일을 그대로 쓰면 될까?

여기서 초보자들이 많이 오해하는 부분이 있다. JSON을 그냥 개발에 붙여서 바로 쓰는 게 아니다. JSON은 그저 데이터일 뿐이다. 실제로 개발자가 바로 쓸 수 있는 건 CSS 변수나 SCSS 변수 같은 코드 형태다. 그래서 JSON을 코드로 변환해주는 도구가 필요하다. 그 대표적인 게 style-dictionary라는 도구다.

빌드 과정에서 자동 변환

style-dictionary 같은 도구를 빌드 과정에 추가해두면, JSON을 읽어와서 CSS 변수로 변환해준다. 이렇게 하면 결과물은 보통 이런 식이다. \:root라는 범위 안에 --primary-color 같은 변수가 생기고, 실제 코드에서는 var(--primary-color) 형태로 불러다 쓸 수 있다.

이렇게 되면 디자이너가 토큰을 수정해서 JSON을 다시 뽑으면, 빌드 과정에서 CSS 변수가 자동으로 업데이트된다. 개발자가 일일이 색상 값을 바꿔주지 않아도 된다.

퍼블리셔와 개발자의 역할

여기서 많이 묻는 게 “이 작업을 퍼블리셔가 해야 하느냐, 아니면 개발자가 해야 하느냐”이다. 사실 정답은 팀 상황에 따라 다르다. 다만 보통은 빌드 환경을 세팅하고 style-dictionary 같은 도구를 연결하는 건 개발자가 맡는다. 퍼블리셔는 이렇게 변환된 CSS 변수 파일을 받아 화면 스타일을 구성하는 데 집중하면 된다.

즉, 디자이너는 토큰을 관리하고, 개발자는 변환 파이프라인을 세팅하고, 퍼블리셔는 그 결과물을 실제 화면에 적용하는 구조라고 보면 이해하기 쉽다.

실무에서 주의할 점

첫째, 단위가 일관돼야 한다. 간격을 어떤 건 px로, 어떤 건 rem으로 하면 나중에 꼬인다. 보통 팀에서 규칙을 정해두고 rem이나 px 같은 단위를 통일해서 쓴다.

둘째, 테마 전략을 고려해야 한다. 다크 모드나 브랜드별 테마가 필요한 경우, 토큰 구조를 미리 그렇게 짜둬야 한다. 예를 들어 light와 dark라는 두 개의 그룹을 만들어두고 같은 이름의 토큰을 상황에 따라 다른 값으로 쓰는 방식이다.

셋째, 네이밍이 중요하다. 단순히 “blue-1” 같은 이름보다는 “primary-bg”처럼 의미를 담는 게 좋다. 그래야 디자이너와 개발자가 서로 이해하기 쉽고, 나중에 색상이 바뀌어도 이름을 그대로 유지할 수 있다.

정리

피그마 토큰을 개발에서 쓰는 방식은 이렇게 요약할 수 있다.

1. 디자이너가 피그마에서 토큰을 정의하고 JSON으로 내보낸다.
2. 개발자가 style-dictionary 같은 도구로 JSON을 CSS 변수나 SCSS 변수로 변환한다.
3. 빌드 과정에 이 변환 단계를 넣어서 자동화한다.
4. 퍼블리셔는 변환된 CSS 변수를 실제 화면에 적용한다.

이 과정을 갖추면 디자이너가 색상 하나만 바꿔도 전체 화면 스타일이 자동으로 업데이트된다. 일일이 코드에 색상 값을 넣던 시대는 점점 사라지고 있다.

결국 핵심은 디자인 토큰을 데이터로 관리하고, 빌드 자동화를 통해 코드에 녹여내는 것이다. 이 구조를 제대로 잡아두면 디자인과 개발이 훨씬 효율적으로 협업할 수 있다.



내가 보기엔 지금은 조금 복잡하게 느껴져도, 실제로 팀 단위로 적용해보면 그 편리함이 금방 와 닿을 거다. 초보자라면 우선 “피그마 → JSON → style-dictionary → CSS 변수” 이 흐름만 기억해두면 된다. 그걸 이해하면 나머지는 자연스럽게 따라온다.