문제
첫 글꼴 규칙(check:design-system)은 --font-sans의 첫 글꼴이 일반
키워드이거나 검사하는 CSS 안의 @font-face로 실릴 때만 통과시킨다. 글꼴
패키지 import, @import url(…), index.html의 <link>로 싣는 글꼴은 볼 수
없어 실패한다. memento 토큰이 이미 이 규칙에 걸린다. 선언할 곳이 없으니
제품은 템플릿 소유 스크립트를 고치게 된다.
고른 방법
- token-contract.ts에 PRODUCT_LOADED_FONT_FAMILIES(템플릿은 빈 목록)를
둔다. 제품은 토큰 계약 파일에서 자기가 싣는 글꼴 이름을 적는다.
- firstFontFamilyFailures가 세 번째 인자로 이 목록을 받아 @font-face로
실은 글꼴과 같이 허용한다. check-design-system.ts가 목록을 넘긴다.
- 실패 메시지에 목록 이름을 넣어 어디에 선언하는지 알린다.
- docs/styling/design-system-platform.md 4.1절 표의 첫 글꼴 행을 고친다.
- 12-04의 (1)~(3)과 (5)는 e714c0d가 했다(deg·음수 색상각, 지원 형식을
적는 포커스 메시지, -apple-system·BlinkMacSystemFont, 규칙 문서). 이
커밋은 (4)만 한다.
버린 대안
- 패키지 import·<link>를 찾아 실제로 싣는지 판정: 진입점·CDN·번들러
설정까지 봐야 해서 규칙이 커진다.
- 목록을 design-system/index.ts로도 내보내기: 앱 코드가 쓰지 않는다.
위험·한계
- 검사는 목록을 믿는다. 글꼴이 실제로 실리는지 보지 않는다. 주석과
문서에 "모든 화면이 싣는 글꼴만 적는다"고 적었다.
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은
tests/unit/design-system-rules.test.ts뿐이다.
- 새 공개 이름 PRODUCT_LOADED_FONT_FAMILIES가 생긴다.
검증
- RED: 새 테스트 "passes a family the product declares it loads, and only
that one"이 실패(expected [ Array(1) ] to deeply equal []).
- GREEN: design-system-rules·oklch-contrast·design-system-contract
22/22 통과.
- 실제 스크립트 probe: CSS 사본의 --font-sans를 "Pretendard Variable"로
시작하게 하고 node scripts/check-design-system.ts → 빈 목록이면 새
메시지로 실패(exit 1), 목록에 넣으면 PASS(exit 0). 저장소 CSS는 PASS.
- tsc(app·node·test), 바꾼 파일 eslint, verify-documentation-readiness
PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
문제: UI-03 규칙은 source.includes(`var(${token}`)로 독자를 찾는다.
"var(--field-border"가 var(--field-border-invalid) 안에도 있어서, 독자가
0곳이던 --field-border를 통과시켰다. 주석 안의 var(--x)도 독자로 셌다.
그리고 이번 브랜치의 디자인 규칙 4개(포커스 대비, oklab 혼합, 토큰
사용, 첫 글꼴)는 스크립트 본문에 바로 있어서, 규칙을 꺼도 잡는 테스트가
없었다(12-02).
고른 방법:
- 규칙 4개를 scripts/lib/design-system-rules.ts의 순수 함수로 옮긴다.
입력은 CSS 글자와 토큰 맵이고 출력은 실패 메시지다. 메시지 문구와
순서는 그대로다.
- 토큰 독자는 var(--name) 또는 var(--name, ...)처럼 이름 전체가 맞아야
한다. "var"는 대소문자를 무시하고, 사용자 정의 속성 이름은 CSS 규칙
대로 대소문자를 구분한다.
- 토큰 사용 규칙과 oklab 혼합 규칙은 CSS 주석을 지우고 본다(리뷰 probe
B5 우회, B12 오탐).
- oklab 혼합 규칙은 대소문자를 무시한다(B1 `in OKLCH` 우회). CSS
키워드는 대소문자를 구분하지 않는다.
- ui-design-audit.md의 UI-03 행에 다섯 번째 토큰을 적는다.
버린 대안: 12-02가 제안한 --root 인자와 CSS 음성 fixture 폴더. 규칙별
검출을 증명하려면 어차피 실패 메시지를 단언하는 테스트가 필요하고,
순수 함수 단위 테스트가 fixture 파일 없이 같은 것을 증명한다. 게이트의
--fixture 모드와 산출물 스키마는 바꾸지 않았다.
위험·한계:
- 주석 제거는 정규식이라 따옴표 문자열 안의 "/*"를 주석 시작으로
본다. 지금 CSS에는 없다.
- 12-03의 나머지 우회(그라디언트, TSX 인라인, base.css 재정의,
outline-offset 0, feature CSS)와 12-04의 오탐(-apple-system, deg,
알파, color-mix 표면)은 그대로다. 포커스·글꼴 규칙은 주석을 지우지
않는다.
- 게이트의 check:design-system:fixture는 여전히 TSX fixture 두 개만으로
"기대 실패"를 채운다. CSS 규칙 회귀는 test:unit이 잡는다.
검증:
- RED(규칙을 동작 그대로 옮긴 상태): tests/unit/design-system-rules.test.ts
11개 중 5개 실패. "does not count a longer token that starts with the
same name"이 "expected [] to deeply equal [ Array(1) ]"로 실패했다.
나머지 4개는 대문자 OKLCH, 주석 안 혼합, VAR( --x , ...) 형태, 주석
안 독자.
- 고친 검사를 앞 커밋 전 CSS(402e1db)에 돌리면 "component token
--field-border is defined but no style reads it"으로 실패했다.
- GREEN: 같은 파일 11/11 통과. tests/unit 166파일 2364개 통과.
- 변이: 대비 기준 < 0, 혼합 정규식 무력화, 토큰·글꼴 판정 무조건
통과로 바꾸면 규칙마다 실패 테스트가 하나 이상 깨졌다(7/11 실패).
- check:design-system PASS, --fixture는 기대대로 실패. tsc(app, node,
test) 통과, 바꾼 파일 eslint 통과, verify-documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-01, 12-02
토큰이 Inter로 시작했지만 Inter를 불러오는 코드가 없었다. Inter가
없는 기기는 자기 글꼴로 그렸고, Inter에는 한글이 없어 한국어는 처음부터
Inter로 그려지지 않았다.
토큰을 시스템 UI 글꼴과 플랫폼별 한국어 글꼴 목록으로 바꿨다(사용자
결정). 한글 웹폰트 배포는 버렸다. 전송량과 글꼴 파일 관리가 생기고,
중립 템플릿에서는 서비스가 브랜드 글꼴로 바꾸면 되기 때문이다.
check:design-system이 첫 글꼴이 기본 키워드도 아니고 @font-face로 싣지도
않으면 실패한다.
위험: OS마다 글꼴 모양이 다르다. 시각 테스트 실행 환경의 글꼴 고정은
아직 남았다(UI-05 후반).
검증: 바꾸기 전 검사가 Inter를 보고했고, 바꾼 뒤 통과했다.
계약에 있는 컴포넌트 토큰 4개를 읽는 스타일이 없었다. 기본 버튼은
bg-action을 직접 썼고, 현재 메뉴는 --navigation-active-background의
계산식을 다시 적었다. 그래서 서비스가 이 토큰으로 브랜드를 바꿔도
화면이 바뀌지 않았다.
기본 버튼과 현재 메뉴가 토큰을 읽게 했다. 변형 버튼은 뒤에 오는 같은
우선순위 규칙이라 그대로 덮어쓴다. check:design-system이 계약의
컴포넌트 토큰을 읽는 스타일이 하나도 없으면 실패한다.
위험: 기본 버튼 배경 지정 방식이 utility에서 토큰으로 바뀐다.
보이는 색은 같다.
검증: 바꾸기 전 검사가 토큰 4개를 보고했고, 바꾼 뒤 통과했다.
라이트 테마에서 현재 메뉴 배경이 파랑이 아니라 분홍으로 그려졌다.
color-mix(in oklch, action 14%, panel)에서 panel이 oklch(1 0 0)으로
색상각 0을 명시해, 보간된 색상각이 255에서 345로 끌려갔다.
15곳의 혼합을 모두 in oklab으로 바꿨다. oklab에는 보간할 색상각이
없다. 흰색을 oklch(1 0 none)으로 바꾸는 방법은 버렸다. 앞으로 생길
무채색 토큰마다 같은 규칙을 기억해야 하기 때문이다.
check:design-system이 oklch·lch·hsl·hwb 혼합을 실패로 처리한다.
위험: 섞인 색이 미세하게 달라진다. 시각 골든을 갱신했다.
검증: 바꾸기 전 검사가 15곳을 보고했고, 바꾼 뒤 통과했다.
라이트 --color-focus가 흰 패널에서 2.33:1, surface-muted에서 1.95:1로
WCAG 1.4.11 기준(3:1)에 못 미쳤다. 포커스 링은 컨트롤에서 3px 떨어져
그려지므로, 대비를 따질 인접색은 컨트롤 뒤의 표면이다.
라이트 포커스를 oklch(0.52 0.15 230)으로 바꿨다. 가장 낮은 대비가
4.24:1이다. 다크는 그대로다. check:design-system이 두 테마에서 포커스
토큰과 표면 토큰 8종의 대비를 계산하고, 3:1 미만이면 실패한다.
안팎 이중 링은 버렸다. 한 색으로 충분하고 링 모양이 바뀌지 않는다.
위험: 포커스 링 색이 진해져 시각 골든이 바뀐다(별도 커밋에서 갱신).
검증: 토큰을 바꾸기 전 검사가 라이트 표면 8종 모두에서 실패했고,
바꾼 뒤 통과했다. 계산식은 브라우저 실측값 2.33:1과 일치한다
(tests/unit/oklch-contrast.test.ts).
Icon vendor, design-system deep import and realtime composition were regular
expressions beside graph rules, and the regex missed relative deep imports
inside presentation. They are graph rules with fixtures now, with the
components/ui facades and page-templates named. package-script-graph.ts stays;
the reason is recorded.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
theme.css (1435 lines) is now an import-order entry point: tailwind, the
three token files, then styles/theme/{base,shell,primitives,templates,
pages,responsive}.css holding the original rules verbatim and in the same
order (components-layer chunks each wrap their part in
`@layer components`). check-design-system now reads every CSS file under
styles/ so the undefined-token check still covers the moved rules; the
design-system doc names the new layout.
Verified: `corepack pnpm build` before and after produce the same CSS
asset, dist/assets/index-6KRF2bCu.css, byte-identical (cmp and sha256
bdaa8521...). A probe undefined token in theme/pages.css fails
check:design-system. Lane gates pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>