실무에서 통하는 색상 팔레트 문서화: 유지보수를 위한 컬러 변수명(토큰) 짓는 가이드

서론

디자인 시스템을 구축하거나 팀 단위로 협업을 시작할 때 가장 먼저 마주하는 난관 중 하나는 색상 팔레트의 문서화입니다. 단순히 예쁜 색상을 고르는 것을 넘어, 이 색상들을 코드와 디자인 툴에서 어떻게 부를 것인가 하는 문제는 프로젝트의 유지보수성에 직결됩니다. 약간 밝은 파란색, 메인 컬러 2번 같은 주관적인 표현이나 헥스(HEX) 코드를 그대로 소통에 사용하게 되면, 프로젝트 규모가 커질수록 혼란이 가중됩니다.

색상 변수명, 즉 컬러 토큰(Color Token)을 체계적으로 짓는 것은 디자이너와 개발자 사이의 공통 언어를 만드는 작업입니다. 제대로 된 이름표를 붙여두면 테마를 변경하거나 다크 모드를 도입할 때 코드를 일일이 수정하는 수고를 덜 수 있습니다. 하지만 처음부터 완벽한 시스템을 만들려다 보면 오히려 복잡성만 높아져 실무에 적용하기 어려워지기도 합니다. 따라서 확장성과 직관성을 동시에 잡을 수 있는 네이밍 규칙을 이해하는 것이 중요합니다.

원색 기반 네이밍과 시맨틱 네이밍의 차이

컬러 토큰을 만들 때 가장 흔히 겪는 고민은 색상의 실제 모습(형태)을 이름으로 할지, 아니면 그 색상이 쓰이는 목적(의미)을 이름으로 할지 결정하는 것입니다. 원색 기반 네이밍은 'Blue-500', 'Gray-100'처럼 색상명과 명도 단계를 직관적으로 조합하는 방식입니다. 이 방식은 팔레트 전체의 구성을 한눈에 파악하기 좋고, 디자이너가 색상을 선택할 때 색상환을 보듯 쉽게 접근할 수 있다는 장점이 있습니다.

반면 시맨틱 네이밍은 'Primary-Action', 'Text-Warning'처럼 해당 색상이 UI에서 어떤 역할을 하는지 의미를 담아 이름을 짓습니다. 버튼 색상을 'Blue-500' 대신 'Button-Primary-Background'로 지정해 두면, 나중에 브랜드 컬러가 파란색에서 보라색으로 바뀌더라도 변수명을 수정할 필요 없이 값만 변경하면 됩니다. 실무에서는 이 두 가지 방식을 섞어 쓰는 경우가 많으며, 어떤 방식을 주력으로 삼을지는 프로젝트의 성격과 팀의 숙련도에 따라 달라져야 합니다.

확장성을 위한 3단계 토큰 시스템

가장 이상적인 컬러 변수명 체계는 글로벌 토큰, 시맨틱 토큰, 컴포넌트 토큰의 3단계로 구성됩니다. 글로벌 토큰(또는 원시 토큰)은 앞서 언급한 'Blue-500'처럼 색상 자체를 정의하는 기초 자원입니다. 여기에는 절대적인 컬러 값(HEX)이 할당되며, UI 요소에 직접적으로 사용하기보다는 상위 토큰의 재료로써 기능하게 됩니다.

시맨틱 토큰은 글로벌 토큰을 참조하여 의미를 부여한 계층입니다. 예를 들어 'Text-Danger'라는 시맨틱 토큰에 'Red-600'이라는 글로벌 토큰을 연결하는 식입니다. 마지막으로 컴포넌트 토큰은 'Button-Primary-Hover-Background'처럼 특정 UI 컴포넌트의 상태까지 아주 세밀하게 지정할 때 사용합니다. 처음 디자인 시스템을 도입하는 단계라면 컴포넌트 토큰까지 모두 정의하기보다는, 글로벌 토큰과 핵심적인 시맨틱 토큰만을 정의하는 2단계 구조로 시작하는 것이 관리 측면에서 훨씬 수월합니다.

실전 변수명 짓기: 상태와 역할을 담는 조합 공식

토큰 이름을 지을 때는 팀 내에서 누구나 예측 가능한 일정한 패턴(구문)을 따르는 것이 핵심입니다. 일반적으로 카테고리, 역할, 속성, 상태의 순서를 조합하여 변수명을 구성합니다. 예를 들어 'Color-Action-Background-Hover'와 같은 식입니다. 여기서 카테고리는 Color, Typography 등 큰 분류를 의미하고, 역할은 Action, Danger, Surface 등 UI에서의 목적을 나타냅니다.

이 공식을 적용할 때 가장 중요한 것은 약어나 모호한 단어의 사용을 피하는 것입니다. 'Bg' 대신 'Background', 'Btn' 대신 'Button'을 사용하는 것이 초기에는 길고 번거로워 보일 수 있습니다. 하지만 검색 기능과 자동 완성 기능이 발달한 현대의 개발 및 디자인 환경에서는, 이름이 길더라도 의도가 명확한 풀네임을 적는 것이 동료의 인지적 부담을 크게 줄여줍니다.

도입 시 주의점과 흔히 발생하는 실수

컬러 토큰 시스템을 구축할 때 가장 경계해야 할 것은 오버엔지니어링입니다. 일어날 수 있는 모든 경우의 수를 대비해 수백 개의 컴포넌트 토큰을 미리 만들어두면, 결국 관리가 안 되어 아무도 쓰지 않는 방치된 시스템이 되기 쉽습니다. 특히 다크 모드를 고려하여 시맨틱 토큰을 짤 때, 밝은 테마에서의 색상 대비만 생각하고 이름을 지으면 어두운 환경에서 의미가 완전히 꼬여버리는 상황이 발생합니다.

또한 기존 레거시 코드가 있는 상태에서 새로운 토큰 시스템을 덧붙일 때는 점진적인 교체가 필수적입니다. 한 번에 모든 하드코딩된 색상 값을 토큰으로 바꾸려다 보면 필연적으로 시각적 버그를 놓치게 됩니다. 따라서 주요 버튼이나 배경색 같은 굵직한 공통 요소부터 시맨틱 토큰을 적용해 나가며 팀원들이 새로운 네이밍 규칙에 익숙해질 수 있는 적응 기간을 두어야 합니다.

결론

색상 팔레트를 문서화하고 변수명을 짓는 과정은 단순한 이름 짓기 대회가 아니라, 디자인의 의도를 개발 언어로 번역하는 아키텍처 설계입니다. 훌륭한 네이밍 컨벤션은 누가 보더라도 해당 색상이 어디에, 왜 쓰여야 하는지 직관적으로 설명해 줄 수 있어야 합니다. 완벽한 하나의 정답이 존재하기보다는 프로젝트의 규모와 팀의 협업 방식에 맞는 최적점을 찾는 것이 중요합니다.

초기 구축에 드는 시간이 다소 부담스럽게 느껴질 수 있지만, 명확한 규칙 하에 정의된 컬러 토큰은 훗날 디자인 개편이나 다크 모드 추가와 같은 대규모 변경 작업에서 그 진가를 발휘합니다. 거창한 3단계 토큰 시스템이 아니더라도, 자주 쓰이는 색상 10가지에 제대로 된 의미를 부여하고 문서화하는 것부터 시작해 보시길 권장합니다.