토큰 시스템을 만들어놓고 아무도 안 쓰고 있었다 — Tailwind 임의값을 걷어낸 이야기

관련 프로젝트: 멀티테넌트 예약 SaaS

배경

컴포넌트 라이브러리에 디자인 토큰 파이프라인(색상·간격·타이포 등을 코드로 관리하는 체계)을 이미 갖춰둔 상태였다. 그런데 다른 작업을 하다가 컴포넌트 파일을 열어보니, 토큰 대신 Tailwind의 임의값 문법이 곳곳에 그대로 남아 있었다. w-[16px], top-[100px] 처럼 대괄호 안에 값을 직접 박아 넣는 방식이다.

토큰 시스템은 있는데, 컴포넌트는 그 토큰을 쓰지 않고 있었다.

문제 — 매직넘버가 디자인 변경을 막는다

임의값 자체가 항상 나쁜 건 아니다. 문제는 재사용해야 할 값까지 임의값으로 박혀 있을 때다.

• 간격 하나를 디자인 스펙에 맞춰 바꾸려면, 토큰 하나만 고치면 될 일을 컴포넌트 파일 여러 개를 열어 값을 하나씩 찾아 고쳐야 했다.
• 같은 의미의 값(예: 카드 사이 간격)이 파일마다 [16px], [15px], [1rem]처럼 미세하게 다르게 박혀 있어, 의도한 불일치인지 실수인지 구분이 안 됐다.
• 토큰 파이프라인을 만든 목적 자체가 "값을 한 곳에서 관리"였는데, 임의값이 그 목적을 무력화하고 있었다.

접근 — 전수조사 후 두 그룹으로 분류

감으로 몇 군데만 고치는 대신, 컴포넌트 디렉토리 전체를 grep으로 훑어 임의값 패턴을 전수조사했다. 100개가 넘는 값이 나왔다.

찾아낸 값들을 두 그룹으로 나눴다.

두 번째 그룹을 걸러낸 게 이번 작업에서 제일 중요한 판단이었다. 애니메이션 키프레임의 -50% 같은 값이나 calc(100%-4px) 같은 표현식은 그 자리에서만 의미가 있는 값이라, 억지로 토큰화하면 오히려 읽기 어려워진다.

결과

• 전수조사로 찾은 100개가 넘는 임의값 중 대다수를 토큰 참조로 치환했다.
• 정리 후에도 남은 건 한 자릿수 — 전부 애니메이션 퍼센트·z-index·backdrop-blur·calc/min 표현식처럼 토큰화가 부적절하다고 판단한 값들이다.
• 이후 간격·크기 관련 디자인 변경은 토큰 파일 하나만 고치면 컴포넌트 전체에 반영되게 됐다.

배운 점

• 토큰 시스템은 있다고 저절로 지켜지지 않는다. 파이프라인을 만드는 것과, 그 파이프라인을 실제로 쓰게 만드는 것은 다른 일이다. 이후로는 새 컴포넌트를 리뷰할 때 임의값 사용 여부를 체크리스트에 넣었다.
• "전부 토큰화"가 정답은 아니다. 컨텍스트에 종속적인 값(애니메이션, 레이어링)까지 토큰으로 강제하면 오히려 코드가 억지스러워진다. 어떤 값을 예외로 남길지 판단하는 기준을 세우는 것도 토큰화 작업의 일부였다.