40장. Design Token을 변경 가능한 API로 운영한다

token은 색상 변수 모음이 아니라 제품 의미의 API다. --color-blue-500을 component가 직접 쓰기보다 --surface-default, --text-danger, --focus-ring처럼 역할을 둔다. primitive→semantic→component 계층을 만들고 theme는 semantic mapping을 바꾼다. contrast와 forced-colors에서 의미가 유지되는지 확인한다. 숫자 이름만 보고 새 브랜드에 재사용하지 않는다.

spacing·type·radius·shadow·motion도 token으로 관리하되 모든 값을 변수로 만들지는 않는다. 변경 빈도와 여러 consumer가 있는 결정만 공개 API로 둔다. token rename은 component와 문서, visual baseline, downstream package를 함께 바꾸는 versioned migration이다. deprecated alias에는 제거 일자와 사용 탐지 lint를 둔다.

실습은 danger color를 dark theme에서 바꾸고 button, inline error, chart legend, focus와 print를 회귀한다. 색만 바꿔 의미를 전달하지 않고 icon/text를 유지한다. Storybook 같은 catalog는 production CSS와 같은 build를 사용하고 별 CSS로 성공 화면을 꾸미지 않는다. token package release에는 before/after matrix, 접근성 결과, consumer 영향과 rollback version을 기록한다.

시니어 review는 “값이 통일됐는가”보다 “누가 이 token을 소유하고 어떤 의미가 안정적인가, 변경이 어느 consumer를 깨뜨리는가”를 묻는다. 이 계약이 있어야 AI가 생성한 화면도 일회성 CSS 덩어리가 아니라 팀의 제품 언어 안으로 들어온다.