버튼 하나의 컬러를 바꾸는 데 이틀이 걸렸습니다. 수동으로 화면 수십 개를 뒤지고, 개발자에게 헥스코드를 일일이 붙여 넣어서 전달하던 시절 얘기입니다. 디자인 토큰을 도입하고 나서야 그게 얼마나 비효율적인 구조였는지 실감했습니다. 이 글은 그 경험을 바탕으로, 토큰 구조 설계부터 네이밍 컨벤션, 자동화 파이프라인까지 실무에서 어떻게 작동하는지 풀어봤습니다.
손으로 하나씩 고치던 시절, 토큰 구조가 바꾼 것
디자인 시스템을 도입하기 전 저는 프리랜서 UI/UX 디자이너로 B2B SaaS 프로젝트를 진행하고 있었습니다. 당시의 작업 방식은 단순했지만 끔찍했습니다. 디자인 수정이 생기면 Figma에서 화면별로 일일이 컬러를 찾아 바꿔야 했고, 개발자에게 넘길 때는 "#1A1A2E입니다"처럼 헥스코드를 직접 전달했습니다. 커뮤니케이션 비용이 아니라 커뮤니케이션 낭비에 가까웠습니다.
디자인 토큰(Design Token)이란 색상, 타이포그래피, 간격 같은 디자인 속성을 이름과 값의 쌍으로 저장해두고, 디자인 파일과 개발 코드가 동일한 값을 공유할 수 있도록 연결하는 시스템입니다. 여기서 핵심은 단순히 값을 변수로 저장하는 것이 아니라 그 변수에 어떤 구조를 부여하느냐입니다.
제가 실제로 적용한 구조는 Primitive → Semantic 2단계 토큰 설계입니다. Primitive 토큰이란 color.neutral.100처럼 순수한 원시 값 자체를 저장하는 가장 낮은 단계의 토큰을 말합니다. 이 Primitive를 바탕으로 Semantic 토큰이 구성됩니다. Semantic 토큰이란 text/primary, surface/background처럼 '이 색이 어디에 쓰이는가'를 이름에 담아 실제 컴포넌트에서 참조하는 토큰입니다. 단순히 색을 저장하는 것이 아니라, 용도를 이름으로 명시하는 방식입니다.
이 구조가 실무에서 가장 빛나는 순간은 다크모드 전환 작업입니다. 저는 기존에 Styled Components에서 테마 객체를 수동으로 관리하던 방식에 익숙했는데, Semantic 레벨만 교체하면 전체 테마가 자동으로 바뀌는 경험은 솔직히 예상 밖이었습니다. Primitive 값은 그대로 두고 Semantic 참조만 라이트/다크 버전으로 스위칭하면 되니, 다크모드 대응에 들이던 공수가 절반 이하로 줄었습니다.
이름 하나가 시스템의 수명을 결정합니다
제가 디자인 토큰을 도입하면서 가장 많은 시간을 들인 부분은 도구 선택이 아니었습니다. 네이밍 컨벤션(Naming Convention), 즉 토큰에 이름을 붙이는 규칙을 설계하는 일이었습니다. 네이밍 컨벤션이란 시스템 전반에서 토큰 이름을 어떤 규칙으로 짓고 관리할 것인지를 정한 약속입니다. 이 규칙이 무너지면 토큰이 100개가 되든 1,000개가 되든 아무도 관리할 수 없는 상태가 됩니다.
좋은 네이밍 컨벤션의 기준을 저는 이렇게 정리합니다.
- 용도 기반으로 짓는다: color-blue-500이 아니라 text/primary처럼 어디에 쓰이는지가 이름에 드러나야 합니다.
- 디자이너와 개발자가 동일하게 읽을 수 있어야 한다: 이름이 공유 어휘가 되어야 커뮤니케이션 비용이 줄어듭니다.
- 확장을 고려해야 한다: text/primary, text/secondary처럼 계층이 명확하면 토큰이 늘어나도 패턴을 유지할 수 있습니다.
- 상태 변경을 포함한다: surface/primary-hover처럼 인터랙션 상태까지 이름 체계에 담으면 개발자가 별도 협의 없이 적용할 수 있습니다.
실제로 surface/primary, text/secondary 같은 Semantic 이름을 팀 공유 어휘로 굳히고 나서, 개발자와의 핸드오프(Handoff) 시간이 눈에 띄게 줄었습니다. 이전에는 "이 배경색 뭐예요?"라는 질문이 슬랙에서 하루에 서너 번은 올라왔는데, 네이밍 체계를 잡고 나서는 개발자가 Figma에서 토큰 이름만 보고 바로 CSS 변수를 작성할 수 있게 되었습니다.
Tokens Studio 자동화 파이프라인, 기대만큼 완벽하지는 않습니다
Tokens Studio는 Figma 플러그인으로, 디자이너가 Figma에서 토큰을 수정하면 GitHub으로 자동 PR(Pull Request)이 생성되는 파이프라인을 구축할 수 있습니다. PR이란 코드 변경 사항을 팀원들이 검토할 수 있도록 요청하는 GitHub의 협업 기능입니다. 이 파이프라인이 정상 작동하면 디자이너가 토큰 값을 수정하는 즉시 개발 코드에 반영되는 구조가 완성됩니다.
올리브영 테크팀이 이 파이프라인을 도입한 사례에서 디자인 변경 후 개발 반영까지 걸리던 시간이 평균 3일에서 반나절 수준으로 단축되었다고 밝혔습니다. 제가 직접 써봤을 때도 이 수치는 실감이 됐습니다. 수정 사항이 개발자에게 Slack 메시지로 전달되고, 다시 확인 요청하고, 적용 여부를 체크하던 사이클 자체가 사라지니까요.
다만 저는 이 도구를 맹신하지는 않습니다. 실무에서 가장 자주 맞닥뜨린 문제는 TypeScript 타입 정의의 미비였습니다. TypeScript 타입 정의란 변수나 함수에 어떤 형태의 데이터가 들어오고 나가는지를 미리 선언해두는 방식으로, 오타나 잘못된 값 입력을 컴파일 시점에 잡아낼 수 있게 해줍니다. 그런데 Tokens Studio에서 생성된 토큰 이름이 string 타입으로만 처리되다 보니, 자동완성이 작동하지 않고 오타 하나로 빌드 전체가 깨지는 일이 빈번했습니다.
개발자 경험(DX, Developer Experience)이란 개발자가 도구나 시스템을 사용할 때 느끼는 생산성과 편의성을 종합적으로 가리키는 개념입니다. DX 관점에서 보면 Tokens Studio의 자동화 파이프라인은 아직 반쪽짜리입니다. 디자이너 쪽의 작업 흐름은 혁신적으로 개선됐지만, 개발자 쪽에서 토큰을 실제로 사용할 때의 경험은 아직 거칩니다. npm 생태계에서도 이 문제를 해결하려는 시도들이 등장하고 있으며, style-dictionary 기반의 타입 생성 도구들이 대안으로 주목받고 있습니다.
도구를 탓하기보다는, 이 한계를 알고 설계 단계에서 대비하는 것이 현실적인 접근입니다. 타입 안전성을 확보하는 추가 작업을 파이프라인에 포함시키거나, 토큰 이름 자체를 enum 방식으로 관리하는 규칙을 팀 내에서 합의하는 방식이 그 예입니다.
결국 디자인 토큰 시스템의 성패는 어떤 플러그인을 쓰느냐보다 어떤 이름으로 어떤 구조를 짓느냐에서 갈립니다. 제 경험상 이건 좀 다릅니다. 도구는 바꿀 수 있지만, 잘못 설계된 네이밍은 시스템 전체를 갈아엎지 않고는 고치기가 어렵습니다. 지금 디자인 시스템 도입을 고민하고 있다면, 가장 먼저 Semantic 네이밍 원칙부터 팀과 합의하는 것을 권합니다. 도구는 그다음입니다.