솔직히 저는 디자인 토큰이 그냥 "색깔에 이름 붙이는 것" 정도라고 생각했습니다. 디자인 시스템을 처음 구축하던 시절, 색상 이름을 red, dark-gray, white-background 식으로 저장해 두고는 꽤 체계적이라고 자부했었으니까요. 그 착각이 얼마나 비싼 대가를 치르게 되는지는, 실제로 무너져봐야 알게 됩니다.
네이밍 컨벤션 — "이름이 틀리면 시스템 전체가 흔들린다"
작년에 B2B SaaS 대시보드 프로젝트에서 디자인 시스템을 처음부터 구축할 때 일입니다. 디자이너 두 명이 각자 익숙한 색상 코드를 쓰다 보니 같은 앱인데 화면마다 분위기가 달랐습니다. 버튼 배경색이 한 화면에서는 #E53935, 다른 화면에서는 #EF5350이었고, 둘 다 "빨간 버튼"으로 통했습니다. 개발자에게 "이 빨간색 어떤 건가요?" 하고 물어보면 돌아오는 대답은 "아, 그 레드요?"였습니다. 의사소통이 완전히 망가진 상태였습니다.
일반적으로 색 이름을 직관적으로 지어야 한다고 알려져 있지만, 제 경험상 그건 오히려 혼란을 키웁니다. red나 dark-gray처럼 색상 자체를 묘사하는 이름은 처음에는 편해 보이지만, 협업자들이 "이게 텍스트용 빨간색인가요, 버튼 배경용인가요?"라고 반드시 되묻게 됩니다. 그 되물음이 쌓이면 결국 누군가 잘못된 색을 잘못된 자리에 쓰게 됩니다.
좋은 네이밍 컨벤션(naming convention)이란 처음 보는 사람도 용도를 유추할 수 있도록 역할 중심으로 이름을 짓는 약속입니다. 여기서 컨벤션이란 팀 전체가 합의한 이름 짓기 규칙을 뜻하며, 이게 흔들리면 토큰 시스템 자체가 새로운 혼란의 원인이 됩니다. 정보 설계(IA, Information Architecture) 관점에서 보면, 토큰 이름은 디자이너와 개발자가 동일한 언어로 대화할 수 있게 해주는 공유 어휘(shared vocabulary)입니다. 쉽게 말해, 이름 하나가 회의 시간 30분을 아끼거나 버그 한 건을 만들거나 합니다.
좋은 네이밍 컨벤션이 갖춰야 할 핵심 요소를 정리하면 다음과 같습니다.
- 명확성: 처음 보는 협업자도 용도를 바로 알 수 있어야 합니다. button/background/primary처럼 역할이 이름에 담겨야 합니다.
- 일관성: button/background/primary였다면 비활성화 버튼은 button/background/disabled처럼 같은 구조를 유지해야 합니다.
- 계층 구조: font-size/heading/1, font-size/body/small처럼 크기나 위계를 이름에 반영해야 합니다.
- 재사용성: 특정 화면에만 종속된 이름보다는 다양한 컴포넌트에서 가져다 쓸 수 있는 이름이 좋습니다.
- 문서화: 이름 규칙 자체를 문서로 남겨야 신규 팀원이 합류해도 일관성이 유지됩니다.
토큰 구조 — Primitive와 Semantic, 2단계가 핵심이다
네이밍 규칙보다 더 중요한 게 있습니다. 바로 토큰을 어떤 층위로 쌓느냐입니다. 저도 처음에는 모든 토큰을 한 레이어에 몰아넣었다가 다크모드에서 참담한 결과를 경험했습니다. 30개 화면의 배경색과 텍스트 색을 일일이 수작업으로 반전시켰는데, 3개 화면에서 텍스트 명도 대비가 접근성 기준에 미달한 채로 배포됐습니다. WCAG(Web Content Accessibility Guidelines) 기준 텍스트와 배경의 명도 대비는 최소 4.5:1을 만족해야 하는데, 당시 저희 화면 중 일부는 2.8:1까지 떨어졌습니다. 여기서 WCAG란 웹 콘텐츠 접근성을 위한 국제 표준 지침으로, W3C(World Wide Web Consortium)에서 제정한 규격입니다(출처: W3C WCAG).
그때부터 Figma에서 Tokens Studio 플러그인을 도입하고 Primitive → Semantic 2단계 토큰 구조를 설계했습니다. Primitive 토큰이란 color.neutral.100처럼 순수한 값 자체를 저장하는 최하위 토큰입니다. 반면 Semantic 토큰이란 text/primary처럼 "어디에 쓰이는 색인지"를 정의하는 상위 토큰으로, Primitive 토큰을 참조하는 구조로 만들어집니다. 쉽게 말해 Primitive는 팔레트이고, Semantic은 그 팔레트에서 색을 골라 용도에 붙인 이름표입니다.
이 구조의 진짜 힘은 다크모드에서 드러납니다. 라이트 모드에서 text/primary가 color.neutral.900을 참조하다가, 다크 모드로 전환할 때는 Semantic 레이어만 color.neutral.50으로 바꿔주면 됩니다. 30개 화면을 손으로 하나씩 뒤집을 필요가 없습니다. 제가 직접 적용해 봤는데, 다크모드 관련 버그 리포트가 월 8건에서 1건으로 줄었습니다. 숫자가 설명을 대신합니다.
글로벌 기업들이 공개한 디자인 시스템 사례를 보면 대부분 이 2단계 이상의 토큰 구조를 채택하고 있습니다. Nielsen Norman Group의 연구에 따르면, 명확한 디자인 시스템을 갖춘 팀은 그렇지 않은 팀에 비해 디자인 일관성 유지에 드는 비용이 평균 31% 낮다고 보고됩니다(출처: Nielsen Norman Group).
자동화 파이프라인 — "진짜 되네"라는 말이 나올 때
구조를 잡고 나면 자연스럽게 다음 질문이 따라옵니다. "그래서 이게 코드랑 어떻게 연결되지?" 일반적으로 디자인 변경이 개발에 반영되려면 디자이너가 스펙을 전달하고, 개발자가 수동으로 값을 바꾸는 과정이 필요하다고 알려져 있습니다. 실제로 써보니 Tokens Studio + Style Dictionary 조합을 쓰면 그 과정이 사라집니다.
여기서 Style Dictionary란 토큰 JSON 파일을 플랫폼별 코드(CSS 변수, Swift 상수, Kotlin 값 등)로 자동 변환해주는 빌드 도구입니다. Figma에서 토큰 값을 수정하면 JSON이 업데이트되고, 이게 GitHub 연동을 통해 자동으로 PR(Pull Request)이 올라오는 구조입니다. 제가 작업하던 프로젝트에서 브랜드 컬러를 수정하자 GitHub PR이 자동으로 올라왔을 때, 개발자가 "이게 진짜 되네?"라고 말했습니다. 그 순간이 디자인 시스템 도입의 가치를 가장 확실하게 체감한 순간이었습니다.
결과적으로 디자인 변경 후 개발 반영까지 평균 3일 걸리던 게 반나절로 줄었습니다. 수치로 보면 간단하지만, 그 3일 안에 쌓이던 오해와 확인 요청과 재작업이 사라졌다는 게 더 큰 변화였습니다.
그렇다고 이 파이프라인이 완벽하다고 말하기는 어렵습니다. 제가 직접 경험한 약점도 있습니다. 타입스크립트 타입 정의가 미비해서 token(colors.red.400)처럼 문자열로 직접 입력해야 하는 경우, 오타 하나로 빌드가 깨지는 상황이 실무에서 종종 발생합니다. 자동완성이 안 되다 보니 개발자 경험(DX, Developer Experience)이 예상보다 낮을 수 있습니다. 도구가 아직 완전히 성숙하지 않은 부분이 있고, 팀 내 합의와 사전 설계 없이 도입하면 오히려 관리 포인트가 늘어날 수 있습니다.
디자인 토큰 시스템의 성패는 도구의 화려함이 아니라 네이밍의 정확성과 팀 내 합의에서 결정됩니다. 아무리 자동화 파이프라인이 잘 구축되어 있어도, 토큰 이름이 제각각이면 그 파이프라인은 혼란을 더 빠르게 전파하는 도구가 될 뿐입니다. 지금 디자인 시스템 도입을 고민 중이라면, 도구 선택보다 먼저 팀원들과 네이밍 규칙을 맞추는 시간을 갖는 걸 권합니다. 30분짜리 회의 한 번이 나중에 몇 주치 수작업을 막아줄 수 있습니다.