broken-ref · missing-primary
빌드 막는 치명 에러와, 거의 필수인 경고
M5에서 본 lint가 실제로 어떤 규칙으로 파일을 검사하는지 하나씩 봐요. 전체 8개 규칙 중 이번 챕터는 가장 엄격한 두 개를 먼저.
broken-ref — 유일하게 "에러(error)"로 처리되는 규칙
토큰 참조 {path.to.token}이 실제로 존재하지 않는 경로를 가리킬 때. 종료 코드 1 반환.
언제 깨질까
- 토큰 이름을
colors.primary에서colors.brand로 바꿨는데, 컴포넌트 참조에 옛 이름이 남아 있음 —"{colors.primary}" - 단순 오타:
"{colors.primay}"(primary→primay) - 존재하지 않는 묶음 참조:
"{shadows.md}"—shadows는 토큰 묶음에 없음
왜 이것만 에러일까
참조가 깨지면 AI가 실제로 UI를 못 만들어요. "이 버튼 배경색이 뭐지?" → 정의되지 않은 값. 결과물이 없어요.
다른 규칙들은 "더 좋게 만들면 좋겠어" 수준이지만, 이건 기능 자체가 깨지는 문제라 빌드를 막는 게 맞아요.
missing-primary — "있어야 하지만 없을 수도 있음"
colors 묶음이 있는데 primary 색이 정의 안 됐을 때.
앞에서 봤죠? 스펙에 "최소한 primary 팔레트는 정의해야 해요"라고 박혀 있어요. 엄밀히 보면 필수 조건인데, 왜 경고로만 두고 에러로 안 막았을까요?
경고로 둔 이유
L261Colors are defined but no primary color exists — agents will auto-generate one.
색은 정의됐는데 primary만 없는 상황이에요. 이 경우 AI가 다른 색에서 자동으로 하나 만들어 채워요. 그래서 빌드를 막을 정도는 아니에요.
현실적으로 초기 디자인 시스템은 secondary·neutral 같은 색부터 정하고 primary는 나중에 확정하는 경우가 많아요. 이런 상황을 "무조건 실패"로 만들면 실제 사용에 불편해요.
두 규칙의 대조로 보는 설계 원칙
AI가 메울 수 없음 — 참조가 가리키는 값이 없으니 추측도 불가. 그래서 에러.
AI가 메울 수 있음 — 다른 색에서 유추해 자동 생성 가능. 그래서 경고.
심각도를 나누는 기준은 "AI가 스스로 메울 수 있는가"예요. 기능이 깨지면 에러, 관행을 어기면 경고, 통계 정보는 정보. 이 3층 구조가 DESIGN.md 검사 도구 전체 설계의 뼈대예요. 이 기준은 다른 린터·검증기를 설계할 때도 그대로 응용할 수 있어요.
체크리스트
broken-ref가 8개 규칙 중 유일한 에러인 이유를 설명할 수 있다missing-primary가 엄밀히 필수인데도 경고로 처리되는 이유를 안다- 심각도를 "AI의 수복 가능성"으로 해석하는 원리를 이해한다