“이게 왜 blue-10인가요? 어제는 분명 blue-5 아니었나요?” 디자인 시스템 회의실에서 이런 소모적인 논쟁이 오가고 있다면, 이미 시스템의 기초인 ‘언어’가 무너지고 있다는 증거입니다. 디자인 토큰의 이름은 단순히 색상이나 수치를 지칭하는 라벨이 아니라, 디자이너의 의도와 개발자의 로직을 연결하는 유일한 인터페이스입니다.

이름 짓기에 실패한 시스템은 결국 유지보수의 늪에 빠지게 됩니다. 브랜드 컬러가 살짝 바뀌었을 뿐인데 수백 개의 컴포넌트 코드를 직접 수정해야 하거나, 피그마와 코드의 변수명이 달라 매번 소통 비용을 지불해야 하죠. 이 글에서는 20년 차 개발자로서 수많은 협업 현장을 겪으며 정립한, 절대로 싸우지 않는 ‘필승 토큰 명명 전략’을 공유합니다.

나쁜 이름의 함정: Red-500이 위험한 이유

가장 흔하게 저지르는 실수는 ‘보이는 그대로’ 이름을 짓는 것입니다. red-500, blue-primary, font-size-16과 같은 이름은 직관적이지만 치명적인 약점이 있습니다. 만약 브랜드 리뉴얼로 인해 주요 색상이 빨간색에서 보라색으로 바뀐다면 어떻게 될까요? 이름은 red-500인데 실제 값은 #6366F1(보라색)인 기괴한 상황이 벌어집니다.

이를 해결하기 위해서는 ‘무엇인가(What)’가 아니라 ‘어떻게 쓰이는가(How/Why)’에 집중해야 합니다. 우리는 이를 ‘시맨틱(Semantic) 명명법’이라고 부릅니다. 색상의 본질적인 이름은 시스템 내부에서만 관리하고, 외부로 노출되는 이름은 그 역할에 충실해야 합니다. 이렇게 의도를 담은 이름은 테마 전환이나 대규모 리뉴얼 상황에서도 코드의 변경 없이 디자인만 교체할 수 있는 유연함을 제공합니다.

[💡 에디터의 실무 팁: 토큰 이름에 구체적인 수치(16px, red)를 넣지 마세요. 대신 scale(sm, md, lg)이나 역할(primary, danger)을 사용해야 시스템의 생명이 길어집니다.]

3단계 토큰 체계: 위계가 질서를 만든다

성공적인 디자인 시스템은 토큰을 단일 계층으로 두지 않습니다. 저는 실무에서 보통 3단계 계층 구조를 권장합니다. 이 구조를 이해하면 디자이너와 개발자가 서로 어떤 수준의 토큰을 참조해야 할지 명확해집니다.

첫 번째는 Global(Base) 토큰입니다. 이는 시스템에서 사용하는 모든 원천 데이터를 의미합니다. color-palette-blue-500이나 spacing-scale-8 등이 여기에 해당합니다. 이 단계는 시스템 관리자만 접근하며, 일반적인 UI 설계에서는 직접 참조하지 않는 것이 원칙입니다.

두 번째는 Alias(Semantic) 토큰입니다. 글로벌 토큰에 ‘의미’를 부여한 단계입니다. action-primary-default는 글로벌의 blue-500을 참조하고, text-error는 red-600을 참조하는 식입니다. 실무자들은 대부분 이 단계의 토큰을 사용하여 디자인하고 코딩합니다.

세 번째는 Component 토큰입니다. 특정 컴포넌트에서만 사용하는 가장 구체적인 단계입니다. button-primary-bg나 input-border-focused 등이 해당합니다. 컴포넌트별로 세밀한 튜닝이 필요할 때 사용하며, 시맨틱 토큰을 한 번 더 래핑하여 사용합니다.

실무에서 바로 쓰는 명명 템플릿 (Category-Type-Item-State)

이름을 지을 때마다 고민하지 않으려면 정해진 문법(Grammar)이 필요합니다. 제가 가장 선호하는 표준 템플릿은 [Category]-[Type]-[Item]-[State] 구조입니다.

• Category: 토큰의 대분류를 나타냅니다. (color, spacing, size, elevation)

• Type: 해당 카테고리 내에서의 역할을 정의합니다. (action, surface, text, border)

• Item: 토큰이 적용되는 구체적인 대상을 지칭합니다. (primary, secondary, success, danger)

• State: 컴포넌트의 상태를 나타냅니다. (default, hover, active, disabled)

예를 들어, color-action-primary-hover라는 이름만 봐도 우리는 “클릭 가능한 주요 요소에 마우스를 올렸을 때의 색상”임을 즉각적으로 이해할 수 있습니다. 개발자는 이 규칙을 바탕으로 CSS 변수나 테마 객체를 자동 생성할 수 있고, 디자이너는 피그마에서 해당 이름을 검색해 바로 적용할 수 있습니다.

[💡 에디터의 실무 팁: 대소문자 규칙(kebab-case 추천)을 미리 정하세요. Figma Variables와 CSS 변수명을 1:1로 매칭하면 개발자 모드에서의 혼선이 0에 수렴합니다.]

트러블슈팅 사례: 다크 모드에서의 이름 중돌 해결

실제로 한 핀테크 프로젝트에서 라이트 모드 전용으로 이름을 지었다가 다크 모드 도입 시점에 전체 토큰을 갈아엎은 적이 있습니다. 당시 background-white라는 이름을 사용했는데, 다크 모드에서는 이 배경이 검은색이 되어야 했기 때문입니다. background-white의 값이 #000000인 상황은 개발자들에게 엄청난 혼란을 주었습니다.

해결책은 이름을 추상화하는 것이었습니다. background-white를 surface-default로 변경했습니다. ‘표면의 기본 색상’이라는 뜻이므로 라이트 모드에서는 흰색, 다크 모드에서는 어두운 회색이어도 논리적으로 완벽합니다. 명명 규칙을 정할 때 “이 이름이 테마가 바뀌어도 여전히 유효한가?”를 자문해 보는 것이 가장 중요한 검증 단계입니다.

자주 묻는 질문(FAQ)

Q1. 이름이 너무 길어지면 코딩할 때 불편하지 않나요? 이름이 긴 것보다 의미가 불분명한 것이 훨씬 위험합니다. 최근에는 IDE의 자동 완성 기능이 워낙 잘 되어 있어 color-action-p... 정도만 쳐도 금방 찾을 수 있습니다. 명확성을 위해 길이를 희생하는 것이 유지보수 측면에서 훨씬 이득입니다.

Q2. 약어를 사용해도 될까요? (예: primary -> pri) 절대 추천하지 않습니다. pri가 primary인지 priority인지 사람마다 해석이 달라질 수 있습니다. 팀 내 용어 사전(Glossary)을 만들고, 약어 사용을 지양하여 누구나 읽을 수 있는 풀네임을 사용하세요.

Q3. 디자이너와 개발자의 의견이 갈릴 때는 어떻게 조율하나요? 이름 짓기의 주도권은 ‘소비자’에게 있습니다. 디자인 시스템의 최종 소비자는 결국 코드를 작성하는 개발자입니다. 개발 환경의 제약 사항(예: 특수문자 사용 불가 등)을 우선 고려하되, 디자이너가 이해할 수 있는 수준의 논리 구조를 협의하는 워크숍을 한두 번 가지는 것만으로도 충분합니다.