orphaned-tokens · missing-typography
쓰이지 않는 토큰과 빠져 있는 폰트를 잡아요
앞 챕터들이 "깨짐·부족함"을 잡았다면, 여기 두 규칙은 "군더더기·빠진 기본값"을 잡아요. 둘 다 경고 수준이에요.
orphaned-tokens — 쓰이지 않는 고아 색
색 토큰이 정의는 돼 있는데 어떤 컴포넌트도 참조하지 않는 상황.
디자인 시스템을 오래 쓰면 흔한 문제예요. 아무도 안 쓰는 색이 계속 쌓여요. 리팩터링하면서 옛 색을 지우지 않고, 새 색만 추가하는 거죠. 결국 파일에 50개 색이 있는데 실제 사용은 12개, 이런 일이 생겨요.
colors묶음에 있는 모든 색 이름을 모아요components의backgroundColor·textColor에서{colors.XXX}참조를 전부 찾아요- 정의됐는데 참조가 없는 색 = 고아(orphan)
본문 설명에서 색 이름을 언급하는 건 집계 대상이 아니에요. 컴포넌트 참조만 기준으로 해요.
가끔 false positive — 의도된 보수성
어떤 색은 본문 설명에만 쓰이기도 해요(예: "그라디언트 배경에 #FF7F00을 쓰세요" 같은 문장). 이 경우 검사 도구는 고아로 분류해요. 이건 버그가 아니라 의도된 엄격함이에요 — "진짜 살아있는 색은 컴포넌트에서 참조해라"는 규율을 강제하는 거죠.
missing-typography — 색은 있는데 폰트가 없음
colors는 정의됐는데 typography 토큰이 하나도 없을 때.
메시지: "agents will use default fonts"(AI가 기본 폰트를 쓰게 돼요). 폰트 토큰이 없어도 AI는 UI를 만들긴 해요 — 단 시스템 기본 폰트(Helvetica·Arial 등)가 나와요. 브랜드가 정성스레 골랐을 폰트 의도가 통째로 날아가요. 경고로 알려주는 이유예요.
두 규칙의 공통 원칙
"정의는 있는데 쓰이지 않아요" → 청소하세요
"쓸 자리는 있는데 정의가 없어요" → 채우세요
둘 다 "선언과 사용의 대칭"을 강제해요. 정의만 있고 사용이 없거나, 사용할 자리만 있고 정의가 없는 비대칭을 줄여서 디자인 시스템을 깔끔하게 유지하게 해요.
이 두 규칙의 공통 철학은 "쓰이지 않는 것은 혼란을 만든다"예요. 아무도 안 쓰는 토큰이 가득하면, 신입이 와서 "이 색은 어디에 쓰는 건가요?"를 물을 때 답이 없어요. 검사 도구가 주기적으로 청소를 권고함으로써 디자인 시스템이 의도적으로 작고 살아있게 유지되도록 도와줘요.
체크리스트
orphaned-tokens가 본문 설명은 집계하지 않는 이유를 안다missing-typography가 경고에 그치는 이유(AI가 기본 폰트로 메움)를 설명할 수 있다- 두 규칙이 "선언과 사용의 대칭"을 강제하는 걸 이해한다