이 글은 누구를 위한 것인가
디자이너·프론트엔드·브랜드 담당이 같은 색 이름으로 말하고 싶은 팀을 위한 글입니다. “이 블루 말이야?”가 아니라 “primary 액션 색”으로 끝나게 만드는 게 토큰의 목적입니다.
프리미티브와 시맨틱
프리미티브는 blue-500, 시맨틱은 color.action.primary처럼 역할을 드러냅니다. 혼용하면 다크 모드 전환이 어렵습니다. 시맨틱 토큰은 “왜 이 색인가”를 제품 맥락에 묶어 둡니다.
네이밍 규칙
팀에서 한 번 정한 접두사·구분자를 문서 한 페이지에 고정합니다. 신규 토큰은 리뷰 게이트를 통과해야 합니다. 이름이 길어지는 것보다 중복·모호함이 더 큰 비용입니다.
코드 동기화
Style Dictionary·Figma Variables·CSS 변수 중 무엇이 진실인지 합의하고, 빌드 파이프라인에 넣습니다. 수동 복붙이 남아 있으면 언젠가 틀어집니다.
비개발자에게
토큰이 있으면 “캠페인 배너 색만 바꿔줘” 같은 요청이 몇 파일을 건드리는지 예측 가능해집니다. 반대로 토큰이 없으면 디자인 QA가 매번 픽셀 단위가 됩니다.
맺으며
토큰은 ‘변수 모음’이 아니라 변경에 대한 합의입니다. 폐기 정책까지 있어야 레거시가 쌓이지 않습니다.