Json 기반 디자인 토큰 관리: Figma에서 Style Dictionary까지 (ver. Android)

이번 글에서는 Design System Token에서 Figma에서 JSON으로 추출해 Style Dictionary 반영하는 과정을 정리하고자 한다.

나는 제조업 환경에서 프로덕트 디자이너로 일하고 있으며, 일반적인 플랫폼/소프트웨어 중심 회사와는 조금 다른 제약이 있다.

이를 먼저 공유하는 이유는, 나와 비슷한 환경의 디자이너들에게도 도움이 되었으면 하기 때문이다.

• 개발환경: Android OS(AOS) 기반
• 언어 호환성: 디바이스 프레임워크 특성상 Kotlin 사용이 제한적 → 주로 Java 기반 개발
• UI 구현 방식: 디바이스는 XML 기반, 리모컨은 Compose 기반으로 분리되어 있으나 이중 관리에 따른 번거로움 존재 → XML로 통일​

이 글은 위와 같은 제약 환경 속에서 디자인 토큰을 어떻게 JSON으로 관리하고, Style Dictionary를 통해 개발 리소스로 연결할 수 있는지 경험을 공유하는 글이다.

 

---

왜 JSON 기반 디자인 토큰 관리가 필요한가

디자인 토큰은 색상, 폰트같은 UI의 최소 단위 값을 코드로 관리하는 방법이다.

현재와 같이 Android XML 기반 환경에서 개발을 진행할 경우, 디자이너가 Figma에서 정의한 스타일을 개발자가 직접 XML 리소스에 입력해야 한다. 이 과정에서 휴먼에러가 발생하거나, 서로 다른 네이밍을 사용하면서 불일치가 생기는 경우가 많다.

또한 값이 변경될 때마다 XML을 찾아 수정하는 방식은 공수가 많이 든다. 이러한 문제를 해결하기 위해 JSON 기반 관리가 필요하다.

​

• 범용적이고 표준화된 데이터 포맷

Android(Java/Kotlin) 환경에서 기본적으로 지원되며, iOS(Flutter를 사용하면 호환 가능)나 Web에서도 동일하게 활용 가능하다.

현재는 AOS만 다루더라도, 추후 확장성 측면에서 이점이 있다.

​

• 자동 변환에 적합

Style Dictionary와 같은 툴은 JSON을 입력으로 받아 Android XML 리소스로 변환할 수 있다. 이 과정은 수동 입력을 줄이고 오류 발생을 방지한다.

​

➡ AOS XML 환경에서 JSON은 디자이너와 개발자가 공통으로 사용할 수 있는 중간 언어 역할을 한다. 디자이너는 Figma에서 JSON을 추출하고, 개발자는 Style Dictionary를 통해 XML로 변환해 사용하는 방식으로 효율성과 정확성을 확보할 수 있다.

 

 

Figma에서 디자인 토큰 준비하기

디자인 토큰을 JSON으로 추출하기 위해서는 먼저 Figma 안에서 토큰을 정의해야 한다. 토큰이 일관성 있게 정의되어야만 개발자가 XML로 변환할 때 혼란이 줄어든다.

​

• 토큰 정의 범위 설정

토큰은 크게 Foundation과 Component로 나눈다.

- Foundation: Color, Typography, Spacing, Radius 등 기본 속성

- Component: 버튼, 입력창, 카드와 같이 UI 컴포넌트 단위에서 사용하는 속성

우선순위로는 Foundation 토큰부터 정의하기! Foundation이 안정적으로 관리되어야 Component가 흔들리지 않는다.

 

• 네이밍 설계 → 디자인 시스템 가이드를 만들자!

위 이미지는 실제 디자인 시스템을 만든 이미지다. (내부 자료로 모자이크 처리) 예를 들어 색상 토큰은 다음과 같이 정의할 수 있다.

- color.primary.default

- color.primary.pressed

- color.secondary.default

이런 구조적 네이밍은 Style Dictionary에서 변환할 때 colors.xml의 key로 그대로 매핑된다. 네이밍을 무분별하게 정의하면 XML 변환 시 불필요한 수정 작업이 발생한다.

 

• Figma 플러그인 활용

토큰을 추출하기 위해 플러그인을 활용해야 한다. Plugins 메뉴에 'token'을 검색하면 여러개가 나오는데, 나는 Tokens Studio을 사용했다.

플러그인을 사용하면

- 토큰 값을 JSON 구조로 관리 가능

- 토큰 값을 업데이트하면 일괄 반영

- Export로 JSON 추출 가능

결국 이 단계에서 중요한 것은 Figma 안에서 토큰을 JSON 구조로 맞추는 것이다.  토큰이 잘 구조화되어 있어야 Style Dictionary로 변환할 때 추가 공수가 들지 않는다.

 

• 토큰 제작 시 주의점

JSON을 개발자에게 전달했을 때 오류가 발생할 수 있다. 테스트 작업 과정에서 아래와 같은 문제를 발견했다.

- 소문자 사용

- 오타 발생

- 코드 공백 존재 (json 추출 시 보이지 않아 확인이 어려우니 이 경우 해당 토큰을 삭제하고 다시 만드는 것이 좋다.)

- 경험하지 못한 또 다른 문제가 있을 수도...!!

 

➡ 토큰은 정의할 때부터 네이밍 규칙을 명확히 하고, 오타와 공백 여부를 꼼꼼히 검수하는 것이 필요하다.

 

디자인 토큰 JSON으로 추출하기

Figma에서 정의한 디자인 토큰은 Tokens Studio 플러그인을 통해 JSON 파일로 추출할 수 있다. 플러그인 메뉴에서 Export 기능을 사용하면 정의된 값들이 key-value 구조로 정리된다.

​

• 네이밍 규칙을 XML 리소스 네이밍과 최대한 일치시키기

예를 들어 색상은 color.primary.default, color.primary.pressed와 같은 구조를 유지하면, Style Dictionary 변환 시 colors.xml 내부에서 <color name="color_primary_default"> 형태로 자동 매핑된다.

네이밍 규칙이 일관되지 않으면 변환 후 수동 수정이 필요하다.

​

• 불필요한 계층 구조를 줄이기

JSON 구조가 지나치게 깊어지면 XML 키로 변환될 때 가독성이 떨어지고, 실제 개발자가 접근할 때 불편해진다. 핵심 속성 위주로 단순화된 계층을 유지해야 한다.

 

➡ JSON 구조는 네이밍 규칙, 계층 단순화, 타입 일관성, 파일 매핑까지 고려해 설계해야 한다. 이렇게 준비된 JSON은 Style Dictionary에서 안정적으로 변환되어 XML 리소스로 활용될 수 있다.

 

Style Dictionary에 적용하기 (Android 환경 중심)

준비된 JSON은 개발자한테 전달하면 된다. 먼저 프로젝트에 Style Dictionary를 설치한 뒤, JSON 파일을 config에 연결한다. 이후 빌드 명령을 실행하면 JSON이 Android에 맞는 XML 파일로 자동 변환된다.

 

개발자에 부탁해 나와 사수 컴퓨터에도 실행해보니 build 완료! 이 과정을 거치면, 디자이너가 정의한 토큰이 그대로 Android 개발 환경에 반영된다. (개발자 전달 전, 선 테스트 해봐도 좋을 듯)

​

➡ 개발자는 XML 파일을 직접 수정할 필요가 없고 토큰 업데이트 시에도 JSON만 수정하면 된다.

 

마무리

지금까지 Figma에서 정의한 디자인 토큰을 JSON으로 추출하고, Style Dictionary를 통해 Android XML 리소스로 변환하는 과정을 정리했다.

우리 팀처럼 제조업 환경에서 AOS 전용, XML 기반으로만 개발하는 경우에도 JSON 기반 토큰 관리 방식은 충분히 유용하다!

JSON은 디자이너와 개발자가 공통으로 이해할 수 있는 구조를 제공하고, Style Dictionary는 이를 자동으로 XML로 변환해준다.

결과적으로 휴먼에러를 줄이고, 반복적인 수작업을 최소화하며, 협업 효율성을 크게 높일 수 있다.

​

향후에 토큰 버전 관리를 정교하게 운영한다면, 디자인 변경이 즉시 개발 리소스로 반영되는 환경을 만들 수 있다. 이는 디자인 시스템을 더욱 안정적이고 확장성 있게 운영하는 기반이 된다.

​

참고 자료:

• Style Dictionary 공식 문서: https://styledictionary.com/
• Tokens Studio(Figma Tokens) 플러그인: https://tokens.studio/plugin