도구 없이 14개의 프로젝트에서 디자인 토큰을 관리하는 방법

• 인프라 구축 없이 하나의 tokens.json 소스로 14개의 프로젝트를 지원

• 30줄짜리 Node 스크립트가 CSS, JS, JSON을 출력

• Style Dictionary는 1인 스튜디오가 감당할 수 없는 설정 오버헤드를 추가함

• 두 번째 팀이 협의를 시작해야 하는 날, 이 패턴은 깨짐

저는 한 대의 컴퓨터에서 14개의 프로젝트를 운영하며, 이들은 모두 동일한 색상(color), 간격(spacing), 타이포그래피 스케일(type scale)을 공유합니다. 디자인 도구도, 플랫폼도, 플러그인도 사용하지 않습니다. 단 하나의 JSON 파일과 30줄짜리 빌드 스크립트가 모든 작업을 수행하며, 저는 단 한 번도 더 많은 기능이 필요하다고 느낀 적이 없습니다.

Style Dictionary를 완전히 건너뛴 이유

디자인 토큰을 어떻게 관리하느냐는 질문에 대한 표준적인 답변은 Style Dictionary입니다. 그것은 좋은 도구입니다. 하지만 제가 겪고 있지 않은 문제를 해결하기 위해 만들어진 도구이기도 합니다. Style Dictionary의 핵심 목적은 많은 사람이 다양한 플랫폼에서 공유된 토큰 형식에 합의하고, 논쟁 없이 이를 iOS, Android, 웹, Figma 출력물로 변환할 수 있도록 하는 것입니다. 그 협의(negotiation) 계층이 바로 가치입니다. 하지만 혼자 작업할 때는 협의할 대상이 없습니다.

초기에 저도 시도해 보았습니다. 설정(config), 변환(transforms), 플랫폼 정의를 구성했습니다. 오후가 지나기도 전에 제가 설명하려는 토큰보다 더 긴 설정 파일 폴더가 생겼습니다. 저는 토큰을 관리하는 기계를 관리하고 있었습니다. 1인 스튜디오에게 이는 역행하는 방식입니다. 도구는 그 도구가 제거하는 조정 비용(coordination cost)이 추가하는 설정 비용(setup cost)보다 클 때 제 역할을 다합니다. 한 명의 제작자와 하나의 의견 체계가 있는 상황에서는 조정 비용이 0이므로, 어떤 설정 비용이든 순수한 손실입니다.

그래서 저는 그것을 삭제했습니다. 대신 tokens.json이라는 단일 파일과 이를 읽는 스크립트를 도입했습니다. 이 파일에는 색상(colors), 간격(spacing), 반경(radii), 글꼴 크기(font sizes), 그리고 몇 가지 모션 값(motion values)에 걸쳐 약 80개의 항목이 들어 있습니다. 스크립트는 세 가지 형식을 출력합니다: 사용자 정의 속성(custom properties)이 포함된 CSS 파일, 동일한 값을 상수로 내보내는 JS 모듈, 그리고 원시 데이터(raw data)를 원하는 곳을 위한 평면 JSON(flat JSON) 복사본입니다. 세 가지 출력물, 하나의 소스, 설정 없음.

이 이야기의 솔직한 버전은 대부분의 토큰 도구(token tooling)가 20명 규모의 팀에 맞춰져 있다는 것입니다. 만약 팀원이 5명 미만이라면 계산법이 뒤바뀝니다. 도구가 정의하는 "변환 (transform)" 개념을 배우는 데 쓰는 시간이 직접 변환 로직을 작성하는 시간보다 더 많이 걸리게 됩니다. 저는 결코 읽지 않을 30,000줄을 가져오느니, 차라리 제가 완전히 이해하고 있는 30줄을 직접 소유하겠습니다. 거대한 도구를 채택하는 대신 작은 도구를 만드는 것에 대한 더 넓은 논거를 알고 싶다면, Claude Blueprint에서 제가 스튜디오 전체에 걸쳐 어떻게 그런 결정을 내리는지 설명합니다.

모든 것에 공급되는 단 하나의 tokens.json

소스 파일은 의도적으로 지루하게 구성되어 있습니다. 카테고리별로 그룹화된 중첩 객체(nested object)이며, 모든 리프(leaf) 노드는 값(value)입니다. 색상은 color 아래에, 간격은 space 아래에 배치되는 식입니다. 저는 간단한 규칙을 사용합니다: 키 경로(key path)가 곧 토큰 이름이 됩니다. 따라서 color.brand.primary는 CSS에서는 --color-brand-primary가 되고, JS에서는 colorBrandPrimary가 됩니다. 별칭(alias), 참조(reference), 또는 파일 자체에 내장된 테마(theme)는 없습니다. 다크 테마(dark theme)가 필요하면 dark라는 두 번째 최상위 키를 추가하며, 빌드 스크립트는 이를 스코프가 지정된 블록(scoped block)으로 출력하는 법을 알고 있습니다.

이 방식이 14개의 프로젝트에서 살아남을 수 있게 만드는 핵심은 다음과 같습니다: 파일은 공유되는 것이 아니라 복사됩니다. 각 프로젝트는 자신만의 tokens.json을 가집니다. 이상하게 들릴 수도 있습니다. 토큰의 매력은 단일 진실 공급원(single source of truth)에 있는데, 저는 방금 14개의 소스를 가지고 있다고 말했으니까요. 하지만 공유 패키지를 사용하면 모든 프로젝트가 발맞추어 업그레이드해야만 하며, 제 프로젝트들은 발맞추어 움직이지 않습니다. 하나는 Shopify 기반의 스토어프론트이고, 하나는 비디오 파이프라인이며, 하나는 정적 마케팅 페이지입니다. 이들은 각기 다른 리듬을 가지고 있습니다.

이들이 공유하는 것은 값(values)이 아니라, 파일의 _형태(shape)_와 빌드 스크립트입니다. 저는 템플릿으로서 표준이 되는 tokens.json을 유지합니다. 프로젝트를 시작할 때 이를 복사한 다음, 상황에 맞게 값을 조정(drift)합니다. 스크립트에 구조적인 개선을 할 때는 이를 수동으로 각 프로젝트에 복사하는데, 프로젝트당 2분 정도 걸리며 일 년에 네 번 정도 발생합니다. 수동 전파(manual propagation)에 드는 비용은 실제로 존재하지만 매우 미미하며, 그 대가로 공유 의존성(shared dependency)을 변경함으로써 라이브 프로젝트를 망가뜨리는 일을 절대 겪지 않습니다.

JSON이 수행하는 또 다른 역할은 문서화(documentation)를 겸한다는 것입니다. 키(keys)가 사람이 읽을 수 있고 그룹화되어 있기 때문에, 파일을 여는 것만으로 한 화면에서 전체 디자인 언어를 파악할 수 있습니다. Storybook도, 토큰 익스플로러(token explorer)도, 호스팅된 참조 문서도 필요 없습니다. 새로운 협업자(또는 6개월 뒤의 저 자신)는 파일 하나만 읽으면 사용 가능한 모든 값을 이해할 수 있습니다. JSON 자체에는 주석을 허용하지 않으므로 JSON 내부에는 주석을 넣지 않는 대신, 스케일(scale) 선택의 의도를 설명하는 짧은 tokens.md 파일을 옆에 둡니다.

30줄짜리 빌드 스크립트, 한 줄씩 살펴보기

이 스크립트는 의존성이 없는 순수한 Node.js 코드입니다. tokens.json을 읽고, 객체를 재귀적으로 탐색(walk)하며, 모든 리프(leaf) 노드를 이름과 값의 쌍으로 평탄화(flatten)합니다. 재귀(recursion)가 유일하게 영리한 부분이며, 약 8줄 정도 됩니다. 값이 객체라면 재귀를 호출하고 키에 접두사(prefix)를 붙이며, 문자열이나 숫자라면 평탄화된 리스트에 추가합니다. 이것이 바로 Style Dictionary가 설정 파일(config file)을 요구하며 제공하는 변환 엔진의 전부입니다.

평탄화가 완료되면 나머지는 포맷팅(formatting)입니다. CSS의 경우, 각 쌍을 --name: value; 형태로 결합하고 :root 블록으로 감쌉니다. 다크 테마(dark theme)의 경우, 동일한 내용을 [data-theme="dark"] 선택자로 감쌉니다. JS의 경우, 각 쌍에 대해 export const name = value;를 생성합니다. JSON의 경우, 평탄화된 객체를 그대로 다시 씁니다. 전체 과정은 1초도 채 걸리지 않으며, 이를 프로젝트의 빌드 단계에 연결하여 tokens.json에 변경이 생기면 앱이 컴파일되기 전에 세 가지 출력물이 모두 재생성되도록 합니다.

이것을 가능하게 하는 핵심 원칙은 명명 (Naming)입니다. 토큰 이름은 키 경로 (Key paths)로부터 기계적으로 파생되기 때문에, 키를 변경하지 않고는 토큰의 이름을 바꿀 수 없으며, 키를 변경하면 모든 출력물이 동시에 업데이트됩니다. 이름이 존재하는 곳은 단 한 곳뿐이므로, 이름이 서로 어긋날(drift out of sync) 여지가 없습니다. 이것이 직접 손으로 쓰는 대신 생성 (Generating) 방식을 사용할 때 얻는 조용한 초능력입니다. 일관성은 제가 지켜야 하는 규칙이 아니라, 시스템 자체의 속성입니다.

또한 한 번의 검증 (Validation) 단계를 추가했습니다. 스크립트는 출력하기 전에 평탄화된(flattened) 두 개의 키가 충돌하지 않는지, 그리고 모든 색상 값이 유효한 hex 또는 rgb 문자열인지 확인합니다. 아마 6줄 정도 될 것입니다. 이 과정은 실제 실수들을 잡아냈는데, 대부분은 제가 중첩된 키 (Nested key)를 잘못 입력하여 두 경로가 동일한 이름으로 평탄화되는 경우였습니다. 프로덕션 (Production) 단계가 아닌 빌드 (Build) 단계에서 이를 잡아내는 것은 6줄의 코드 값어치를 두 배로 해냅니다.

모션 (Motion) 값들도 동일한 파일에 존재합니다. 지속 시간 (Durations)과 이징 (Easings)은 다른 토큰들과 마찬가지로 토큰이며, 이를 시스템의 일급 객체 (First-class members)로 취급함으로써 여러 프로젝트에 걸쳐 애니메이션의 일관성을 유지할 수 있었습니다. 저는 Motion Design Tokens That Actually Compose에서 이 아이디어를 깊이 있게 다루었는데, 타이밍 값 역시 색상과 마찬가지로 단일 소스 (Single-source) 처리를 통해 이득을 얻기 때문입니다. 만약 당신이 오후 한나절 만에 이 스크립트를 구축할 수 있다면, 당신은 모든 줄을 이해하고 있는 것이며, 그 이해도가 파일 자체가 아니라 실제 자산입니다.

규모가 커질 때 이 패턴이 무너지는 지점

저는 한계점에 대해 솔직해지고 싶습니다. 제 설정을 맹목적으로 복사했다가는, 규모가 커져 감당할 수 없게 되는 날 고통을 겪게 될 것이기 때문입니다. 이 접근 방식은 한 사람이 전체 디자인 언어를 머릿속에 담고 모든 변경 사항을 수행한다는 것을 전제로 합니다. 두 번째 팀이 토큰을 추가해야 하는 순간, 제가 설명한 수동 전파 (Manual propagation) 방식은 기능이 아니라 부채 (Liability)가 됩니다. 두 사람이 스크립트 변경 사항을 수동으로 복사하다 보면 서로 어긋나고, 업데이트를 놓치게 되며, 결국 동일한 토큰 세트의 서로 호환되지 않는 두 버전을 배포하게 될 것입니다.

두 번째 임계점은 플랫폼(platforms)입니다. 저는 제가 배포하는 모든 것, 즉 웹(web) 전체를 다루기 위해 CSS, JS, JSON을 출력합니다. 만약 네이티브 iOS 값, Android XML, 그리고 Figma 동기화가 필요한 날이 온다면, 저의 30줄짜리 스크립트는 300줄의 플랫폼 변환(platform transforms) 코드로 변하게 될 것이며, 그 정도 길이에 이르면 여러분은 Style Dictionary를 조잡하게 재구축하고 있는 셈이 됩니다. 바로 그 지점이 진정한 도구가 제 가치를 발휘하기 시작하는 임계점입니다. 도구가 요구하는 설정 비용(setup cost)이 도구가 제거해 주는 조정 비용(coordination cost)보다 마침내 작아지는 시점이죠.

세 번째는 대규모 테마(themes at scale)입니다. 저의 '두 번째 키로서의 다크 테마(dark-theme-as-second-key)' 트릭은 두 개의 테마에는 효과적입니다. 하지만 각각의 오버라이드(overrides)와 상속 규칙(inheritance rules)을 가진 수십 개의 브랜드 변형(brand variants)에는 작동하지 않습니다. 제대로 된 테마 엔진(theming engines)이 존재하는 데에는 이유가 있으며, 그 이유는 테마가 네 번째 정도에 도달할 때 드러납니다.

따라서 규칙은 간단합니다. 혼자 작업하고, 웹만 다루며, 테마가 두세 개라면: 저의 패턴이 압도적으로 유리하며 주저 없이 추천할 것입니다. 하지만 두 번째 독립적인 팀, 네이티브 플랫폼, 또는 실제 테마 매트릭스(theming matrix)가 추가된다면, 고통이 찾아온 후가 아니라 찾아오기 전에 더 무거운 도구를 채택해야 합니다. 실수는 작은 도구를 선택하는 것이 아닙니다. 실수는 그 도구의 전제 조건이 더 이상 유효하지 않은 시점 이후에도 작은 도구를 계속 유지하는 것입니다.

여러 프로젝트에 걸쳐 디자인 리프레시(design refresh)를 알리는 소셜 포스트를 예약하기 위해, 저는 Buffer에 의존합니다. 덕분에 제가 14개의 대시보드를 일일이 수동으로 건드리지 않고도 단 한 번의 토큰 업데이트로 눈에 띄는 결과물을 배포할 수 있습니다. 하나의 소스가 많은 출력물로 이어지는 이 동일한 직관이 제가 만드는 모든 것의 핵심 원칙입니다.

결론 (Bottom Line)

디자인 토큰 도구는 팀 단위에 맞춰져 있으며, 온라인상의 대부분의 조언은 당신이 팀이라는 가정하에 이루어집니다. 만약 혼자 작업한다면, 정직한 선택은 플랫폼을 건너뛰고 자신이 완전히 이해할 수 있는 아주 작은 시스템을 소유하는 것입니다. 프로젝트당 하나의 tokens.json, CSS, JS, JSON을 생성하는 30줄짜리 Node 스크립트, 그리고 모든 프로젝트가 각자의 속도로 움직일 수 있게 해주는 '공유하지 말고 복사하라(copy-not-share)' 규칙 말입니다. 의존성도 없고, 데이터를 설명하는 것보다 긴 설정 파일도 없으며, 시스템을 유지하기 위한 별도의 기계도 필요 없습니다.

이 방식은 정확히 한 명의 규모에 맞춰 확장되며, 그것이 바로 핵심입니다. 세 가지 임계점(두 번째 팀의 등장, 네이티브 플랫폼(native platform)의 도입, 실제 테마 매트릭스(theming matrix)의 필요성)을 인지하고, 그중 어느 하나라도 나타나는 즉시 더 무거운 도구로 전환하십시오. 단 하루도 앞서지 마십시오. 저는 후회 없이 14개의 프로젝트에 걸쳐 이 방식을 실행해 왔으며, 이 방식이 더 이상 맞지 않는 날이 오면 아무런 문제 없이 다음 단계로 넘어갈 것입니다.

거대한 시스템을 채택하는 대신 작게 구축하는 것에 담긴 스튜디오 전체의 사고방식을 알고 싶다면, Claude Blueprint에서 전체적인 접근 방식을 설명하고 있습니다. 스크립트를 가져가서, 값을 변경하고, 배포하십시오.

이 기사는 제휴 링크를 포함하고 있습니다. 이 링크를 통해 가입하시면, 귀하에게 추가 비용 부담 없이 저에게 소정의 수수료가 지급될 수 있습니다. (광고)