왜 디자인 토큰과 CSS가 아마도 동기화되지 않았는지 (그리고 확인 방법)
Source: Dev.to
문제: 토큰과 CSS가 동기화되지 않음
토큰을 정의하고 문서화했으며, 변수 이름이 표시된 전체 팔레트를 보여주는 Storybook 페이지까지 만들었을 수도 있습니다. 하지만 6개월 뒤에는 코드베이스 곳곳에 color: #1A1A1A 같은 하드코딩된 값, 컴포넌트 전반에 흩어져 있는 12px 간격 값, 그리고 마지막 리브랜딩 이후 한 번도 참조되지 않은 토큰들이 존재하게 됩니다.
이러한 불일치는 의도된 것이 아니라 조용히 쌓여갑니다:
- 마감 압박 – 컴포넌트를 급히 배포하고, 토큰 이름이 바뀐 뒤 일부 CSS 파일만 업데이트됩니다.
- 온보딩 – 새로운 개발자가 몇몇 컴포넌트에서 하드코딩된 값을 보고 그것이 관례라고 착각합니다.
- 리브랜딩 – 토큰 값은 바뀌지만 하드코딩된 값은 남아있습니다. 아무도 존재한다는 것을 모릅니다.
드리프트는 아무것도 깨지지 않기 때문에 눈에 띄지 않지만, 시스템을 감사해야 할 때는 유지보수가 악몽이 됩니다.
드리프트가 발생하고 있다는 신호
- 토큰 값은 바뀌었지만 하드코딩된 버전은 그대로 남아 있음.
- CSS에 숨겨진 직접 값을 찾을 방법이 없음.
- 새로운 디자이너가 “실제 진실의 출처가 어디인가요?”라고 묻는데 명확히 답하지 못함.
이 시점에서 감사는 수동적이고 고통스럽습니다: CSS를 grep으로 검색하고, 토큰 파일과 교차 참조하며, 커버리지를 스프레드시트에 정리하는 작업이 필요합니다.
알아야 할 내용
문제를 해결할 때 스스로에게 물어보세요:
- 정의는 되었지만 CSS에서 전혀 사용되지 않은 토큰은?
- 하드코딩된 값은 어디에 숨겨져 있는가?
- 카테고리별(색상, 간격, 타이포그래피 등) 커버리지는?
- 가장 낮은 토큰 커버리지를 보이는 컴포넌트는?
TokenLens 소개
TokenLens는 브라우저 기반 감사 도구로 다음을 입력받습니다:
- JSON 형식의 디자인 토큰 정의 파일.
- CSS 파일들.
작동 방식
-
여러 JSON 및 CSS 파일을 받아들임(토큰 세트가 분리돼 있거나 컴포넌트 기반 CSS인 경우에 유용).
-
계정, 설치, 빌드 단계가 필요 없음.
-
다음과 같은 보고서를 생성함:
- 카테고리별 토큰 커버리지(토큰을 참조하는 CSS 속성 비율 vs. 하드코딩된 값).
- 사용되지 않은 토큰 – JSON에 정의됐지만 어떤 CSS 파일에서도 발견되지 않음.
- 하드코딩된 값 인스턴스 – 직접 값이 사용된 구체적인 라인, 속성 유형별로 그룹화.
- 컴포넌트 별 분석 – 커버리지가 가장 낮은 CSS 선택자(클래스 이름에서 추정).
예시 출력
40개의 색상 토큰과 여러 컴포넌트 CSS 파일이 있다고 가정합니다. TokenLens를 실행하면 다음과 같은 결과가 나올 수 있습니다:
- 색상 토큰 40개 중 28개가 CSS에서 참조됨.
- 정의에는 12개의 토큰이 존재하지만 어디에서도 사용되지 않음.
- 8개의 컴포넌트 파일에 걸쳐 23개의 하드코딩된 hex 값이 발견됨.
이를 통해 정리 작업에 집중할 영역과 디자인 팀에 물어볼 질문을 명확히 파악할 수 있습니다.
왜 중요한가
디자이너와 개발자 모두 이 보고서를 공유된 어휘로 활용할 수 있습니다. “우리 디자인 시스템이 지켜지지 않는다”는 막연한 주장 대신, “여기 컴포넌트별로 하드코딩된 값이 23곳 발견됐다”는 구체적인 근거를 제시할 수 있습니다.
권장 사항
디자인 시스템을 유지하거나 인수받았다면 TokenLens로 감사를 진행해 보세요. 결과는 예상보다 더 실행 가능할 때가 많습니다.
여기서 사용해 보세요: https://tokenlens.app
댓글로 의견을 알려 주세요!