round9 확인 리뷰 그룹 A의 묶음 A3(디자인 토큰)·A4(story·골든·검사)와, 같은 파일·골든을 바꿔 이 PR로 옮긴 04-06·04-17을 고친다.
1112/04-08 (Low·P2): 셸·템플릿·카드 CSS가 간격·글자·반경·층·그림자 토큰을 건너뛰고 날 값을 쓴다(규칙에 걸리는 선언 118개). 필수 semantic 토큰 7개를 읽는 스타일이 없다. 토큰을 바꿔도 화면이 그대로다.
1112/04-12 (Low·P3): component.css의 가림막 토큰 셋이 REQUIRED_COMPONENT_TOKENS에 없어 UI-03 밖이다.
1112/04-13 (Low·P3): semantic.css가 팔레트를 거치지 않은 날 oklch() 36개를 정의한다. 팔레트만 바꿔 리브랜드하면 status·focus·다크 테마가 그대로다.
1112/04-15 (Low·P3): fe-design-system 스킬의 color-mix 문장과 아이콘 토큰 이름이 규칙·토큰과 다르다.
1112/04-16 (Low·P3): docs/styling/design-tokens.md 「들어 있는 primitive」가 일부만 손으로 적는다.
1112/04-17 (Low·P3): 지운 compact 사이드바의 CSS(가림막 35%, z-index 50·40)가 남았다.
1112/04-10 (Low·P3): 배럴 화면 컴포넌트 37개에 story가 없고, 결과 불명·충돌·stale·저장 중이 갤러리·골든에 없다.
1112/04-11 (Low·P2): 시각 골든 색 허용치가 기본 0.2라 위험 표면 색상 변경을 통과시킨다.
1112/04-14 (Low·P3): primitive의 className·style이 범위 없이 열려 날 색·간격을 얹어도 막는 것이 없다.
1112/04-06 (Low·P3): 홈이 페이지 템플릿과 LinkButton을 손으로 다시 만든다.
1101/12-03 (Low·P3, 지난 발견): 디자인 검사가 gradient 색 공간, TSX color-mix, 기능 폴더 CSS, 토큰 재정의, outline-offset: 0을 못 잡는다.
고른 방법과 버린 대안
(커밋 본문에 발견마다 자세히 적었다.)
토큰: 날 값을 가까운 단계로 반올림해 토큰으로(간격 최대 0.15rem 차이, 3.5·4rem은 --space-14·--space-16을 더함). 층·그림자·반경·가림막은 해당 semantic 토큰을 읽는다. 읽는 곳이 없던 semantic 토큰은 실제 쓰임(skeleton, 꺼진 입력, 누른 primary 버튼)에 잇고, --layer-modal은 native <dialog> top layer라 이유와 함께 예외 목록에 둔다. semantic 색 36개는 값 그대로 팔레트로 옮긴다.
검사: UI-06(styles 날 값), UI-07(semantic 날 색), semantic UI-03, component 계약 대조, 1101/12-03 다섯, 04-14 인라인 style 검사(R9-D6, 공개 props는 그대로).
story: catalog.stories.tsx에 묶음 story 열, 갤러리에 저장 상태 절, 배럴 대조 시험, 새 story 전부와 열린 overlay에 axe.
골든 허용치: threshold 0.05(R9-D8).
버린 대안: 단계마다 primitive를 더하기, --layer-modal 가짜 읽기, 공개 props에서 style 빼기(BREAKING), 0.1(첫 변이가 다시 통과), 문서에 semantic 예외 목록만 적기.
정한 기본값
playwright.visual.config.ts는 이번 brief가 막았다(w2-fe-2가 브라우저 실행 설정을 고치는 중). 그래서 threshold를 tests/visual/platform.visual.spec.ts의 GOLDEN으로 모든 screenshot에 넘기고, 빠뜨리면 tests/unit/visual-golden-threshold.test.ts가 잡는다. 설정 기본값은 0.2 그대로다.
.ui-panel의 Tailwind shadow-sm도 --elevation-panel로 바꿔 카드와 같은 높이가 됐다(시각 변화, 의도).
굵기 800은 --font-weight-bold(750)로 줄었다.
StatusPage는 자기 h1을 그려 갤러리 h1과 겹치므로 갤러리 대신 자기 story에 뒀다.
갤러리에 넣으면서 드러난 두 가지를 같은 커밋에서 고쳤다: 저장 상태 안내의 문장과 버튼이 붙어 있던 것(.async-surface__status 줄 간격), FormFailureStatus가 제목 단계를 받지 못한 것(headingLevel 추가만).
위험과 영향
다운스트림이 따라 할 일(CHANGELOG 후보):
styles·기능 CSS에 날 간격·글자·반경·층·그림자·색을 쓴 곳, :root 토큰 재정의, outline-offset: 0, TSX style의 날 색·간격은 다음 동기화에서 check:design-system이 줄과 함께 실패한다. 토큰으로 바꾼다.
semantic.css에 날 색을 더해 두었으면 팔레트로 옮긴다(UI-07).
component.css에 계약에 없는 토큰을 두었으면 REQUIRED_COMPONENT_TOKENS에 더하고 읽게 한다.
--dialog-backdrop-weight가 없어졌다. 가림막 비율은 --opacity-scrim이다.
시각 골든을 다시 찍는다(간격 반올림, 패널 그림자).
CHANGELOG 알려진 제한의 「골든 색 허용치 0.2」 줄은 지운다.
반올림으로 화면이 조금 바뀐다(골든 5장, 이유는 커밋 본문).
이 PR과 무관한 흔들림 하나(범위 밖, 고치지 않음): 1차 merge의 FE-GATE-008이 Chromium tests/browser-capabilities/cross-context-invalidation.spec.ts:223(localStorage 이벤트 대체 경로, storage 이벤트가 5초 안에 오지 않음) 1건으로 실패했다. desktop에서 그 시험만 20회씩 반복하니 이 PR 트리 0/20 실패, 기준(main 7e5a0bb8의 src·tests) 1/20 실패다(r9a-pr2-flake). 이 PR은 adapter와 그 시험을 건드리지 않는다. 그룹 C(시험 신뢰도)로 넘긴다. 2차 merge의 FE-GATE-008은 통과했다.
이 PR의 base는 ee95573f이고 #47(Firefox 프로필 RAM·browser job /dev/shm 2 GB)을 담지 않는다. runner browser job에서 Firefox 첫 렌더 흔들림이 나면 #51처럼 main을 받아 다시 돈다(총괄이 정한다).
검증
(desktop, scripts/verify.sh, 공유 잠금)
1차 실행 r9a-pr2-run(트리 82f64cbe): 골든 — C1(사이드바 CSS)·C2(팔레트)에서 main 골든 그대로 통과(화면 변화 없음), 토큰 커밋에서 5장 바뀜. X-02: 변이 --color-danger-surface 색상각 145에서 0.05는 state-surfaces-light 실패, 0.2는 통과(구멍 확인). 변이 없이 3회 통과.
2차 실행 r9a-pr2-run2(트리 522fa273, 골든 뺀 최종과 같은 코드):
GREEN: 바뀐 시험 7파일 115개 통과. check:design-system·check:types·lint·check:i18n rc=0, check:design-system:fixture rc=1(기대, 새 raw-inline-style.tsx 두 줄 포함).
RED(새 검사기로 고치기 전 style·토큰 CSS를 검사): UI-06 날 값 121건, UI-07 semantic 날 색 36건, 읽히지 않는 필수 semantic 토큰 6개(--layer-modal은 예외), 계약 밖 component 토큰 --dialog-backdrop-weight. story 대조 시험은 고치기 전 story로 37개 누락에서 실패.
test:storybook 34개 통과(새 catalog story axe 20개와 열린 overlay 3개 포함).
골든: 토큰 커밋 골든으로 그 커밋 통과, 홈 커밋에서 셸 2장, story 커밋에서 상태 화면 1장 갱신. 최종 트리에서 변이 없이 3회 통과.
scripts/verify.sh merge 1차(r9a-pr2-merge, 트리 a2244671): 005 rc=1(기능 모양 기록 낡음: precache 자산 기록 24, 빌드 22), 008 rc=1(아래 「위험과 영향」의 Chromium 1건), 나머지 12개 rc=0. 기록은 홈 커밋이 바꾼 것으로 확인(r9a-pr2-shape: 홈 커밋 직전 24개·파일 17, 홈 커밋 22개·파일 15)하고 측정 스크립트의 --write 결과를 홈 커밋에 넣었다.
scripts/verify.sh merge 2차(r9a-pr2-merge2, 트리 6c9c1371 = 이 PR head 트리, CI env): FE-GATE-001~013·020 14개 모두 rc=0. FE-GATE-013(시스템 컨테이너) 포함. 005 224 s, 008 340 s, 013 322 s, 020 537 s.
문서 단계 FE-GATE-017(r9a-pr2-docs) rc=0, scripts/verify.sh parts FE-GATE-029(r9a-pr2-029) rc=0(음성 fixture는 정해진 진단으로 실패).
노트북 scripts/verify.sh docs·hooks OK(스킬 토큰 이름 시험: 고치기 전 --icon-size-*로 실패, 고친 뒤 통과).
새 눈 리뷰(렌즈 fe-design-system·fe-testing·fe-ux) 1회: High 1(catalog story의 SearchFilterToolbar에 필수 onReset 없음), Low 3(인라인 style 규칙의 거짓 양성·음성, UI-06 문서 범위, story 대조가 주석·문자열도 셈), 넘길 것 1(열린 overlay에 axe 없음) → 모두 고쳤다.
## 무엇을, 왜
round9 확인 리뷰 그룹 A의 묶음 A3(디자인 토큰)·A4(story·골든·검사)와, 같은 파일·골든을 바꿔 이 PR로 옮긴 04-06·04-17을 고친다.
- 1112/04-08 (Low·P2): 셸·템플릿·카드 CSS가 간격·글자·반경·층·그림자 토큰을 건너뛰고 날 값을 쓴다(규칙에 걸리는 선언 118개). 필수 semantic 토큰 7개를 읽는 스타일이 없다. 토큰을 바꿔도 화면이 그대로다.
- 1112/04-12 (Low·P3): component.css의 가림막 토큰 셋이 `REQUIRED_COMPONENT_TOKENS`에 없어 UI-03 밖이다.
- 1112/04-13 (Low·P3): semantic.css가 팔레트를 거치지 않은 날 `oklch()` 36개를 정의한다. 팔레트만 바꿔 리브랜드하면 status·focus·다크 테마가 그대로다.
- 1112/04-15 (Low·P3): fe-design-system 스킬의 `color-mix` 문장과 아이콘 토큰 이름이 규칙·토큰과 다르다.
- 1112/04-16 (Low·P3): `docs/styling/design-tokens.md` 「들어 있는 primitive」가 일부만 손으로 적는다.
- 1112/04-17 (Low·P3): 지운 compact 사이드바의 CSS(가림막 35%, z-index 50·40)가 남았다.
- 1112/04-10 (Low·P3): 배럴 화면 컴포넌트 37개에 story가 없고, 결과 불명·충돌·stale·저장 중이 갤러리·골든에 없다.
- 1112/04-11 (Low·P2): 시각 골든 색 허용치가 기본 0.2라 위험 표면 색상 변경을 통과시킨다.
- 1112/04-14 (Low·P3): primitive의 `className`·`style`이 범위 없이 열려 날 색·간격을 얹어도 막는 것이 없다.
- 1112/04-06 (Low·P3): 홈이 페이지 템플릿과 `LinkButton`을 손으로 다시 만든다.
- 1101/12-03 (Low·P3, 지난 발견): 디자인 검사가 gradient 색 공간, TSX `color-mix`, 기능 폴더 CSS, 토큰 재정의, `outline-offset: 0`을 못 잡는다.
## 고른 방법과 버린 대안
(커밋 본문에 발견마다 자세히 적었다.)
- 토큰: 날 값을 가까운 단계로 반올림해 토큰으로(간격 최대 0.15rem 차이, 3.5·4rem은 `--space-14`·`--space-16`을 더함). 층·그림자·반경·가림막은 해당 semantic 토큰을 읽는다. 읽는 곳이 없던 semantic 토큰은 실제 쓰임(skeleton, 꺼진 입력, 누른 primary 버튼)에 잇고, `--layer-modal`은 native `<dialog>` top layer라 이유와 함께 예외 목록에 둔다. semantic 색 36개는 값 그대로 팔레트로 옮긴다.
- 검사: UI-06(styles 날 값), UI-07(semantic 날 색), semantic UI-03, component 계약 대조, 1101/12-03 다섯, 04-14 인라인 style 검사(R9-D6, 공개 props는 그대로).
- story: `catalog.stories.tsx`에 묶음 story 열, 갤러리에 저장 상태 절, 배럴 대조 시험, 새 story 전부와 열린 overlay에 axe.
- 골든 허용치: threshold 0.05(R9-D8).
- 버린 대안: 단계마다 primitive를 더하기, `--layer-modal` 가짜 읽기, 공개 props에서 `style` 빼기(BREAKING), 0.1(첫 변이가 다시 통과), 문서에 semantic 예외 목록만 적기.
## 정한 기본값
- `playwright.visual.config.ts`는 이번 brief가 막았다(w2-fe-2가 브라우저 실행 설정을 고치는 중). 그래서 threshold를 `tests/visual/platform.visual.spec.ts`의 `GOLDEN`으로 모든 screenshot에 넘기고, 빠뜨리면 `tests/unit/visual-golden-threshold.test.ts`가 잡는다. 설정 기본값은 0.2 그대로다.
- `.ui-panel`의 Tailwind `shadow-sm`도 `--elevation-panel`로 바꿔 카드와 같은 높이가 됐다(시각 변화, 의도).
- 굵기 800은 `--font-weight-bold`(750)로 줄었다.
- StatusPage는 자기 h1을 그려 갤러리 h1과 겹치므로 갤러리 대신 자기 story에 뒀다.
- 갤러리에 넣으면서 드러난 두 가지를 같은 커밋에서 고쳤다: 저장 상태 안내의 문장과 버튼이 붙어 있던 것(`.async-surface__status` 줄 간격), `FormFailureStatus`가 제목 단계를 받지 못한 것(`headingLevel` 추가만).
## 위험과 영향
- 다운스트림이 따라 할 일(CHANGELOG 후보):
- styles·기능 CSS에 날 간격·글자·반경·층·그림자·색을 쓴 곳, `:root` 토큰 재정의, `outline-offset: 0`, TSX `style`의 날 색·간격은 다음 동기화에서 `check:design-system`이 줄과 함께 실패한다. 토큰으로 바꾼다.
- semantic.css에 날 색을 더해 두었으면 팔레트로 옮긴다(UI-07).
- component.css에 계약에 없는 토큰을 두었으면 `REQUIRED_COMPONENT_TOKENS`에 더하고 읽게 한다.
- `--dialog-backdrop-weight`가 없어졌다. 가림막 비율은 `--opacity-scrim`이다.
- 시각 골든을 다시 찍는다(간격 반올림, 패널 그림자).
- CHANGELOG 알려진 제한의 「골든 색 허용치 0.2」 줄은 지운다.
- 반올림으로 화면이 조금 바뀐다(골든 5장, 이유는 커밋 본문).
- 이 PR과 무관한 흔들림 하나(범위 밖, 고치지 않음): 1차 merge의 FE-GATE-008이 Chromium `tests/browser-capabilities/cross-context-invalidation.spec.ts:223`(localStorage 이벤트 대체 경로, storage 이벤트가 5초 안에 오지 않음) 1건으로 실패했다. desktop에서 그 시험만 20회씩 반복하니 이 PR 트리 0/20 실패, 기준(main `7e5a0bb8`의 src·tests) 1/20 실패다(`r9a-pr2-flake`). 이 PR은 adapter와 그 시험을 건드리지 않는다. 그룹 C(시험 신뢰도)로 넘긴다. 2차 merge의 FE-GATE-008은 통과했다.
- 이 PR의 base는 `ee95573f`이고 #47(Firefox 프로필 RAM·browser job `/dev/shm` 2 GB)을 담지 않는다. runner browser job에서 Firefox 첫 렌더 흔들림이 나면 #51처럼 main을 받아 다시 돈다(총괄이 정한다).
## 검증
(desktop, `scripts/verify.sh`, 공유 잠금)
- 1차 실행 `r9a-pr2-run`(트리 `82f64cbe`): 골든 — C1(사이드바 CSS)·C2(팔레트)에서 main 골든 그대로 통과(화면 변화 없음), 토큰 커밋에서 5장 바뀜. X-02: 변이 `--color-danger-surface` 색상각 145에서 0.05는 `state-surfaces-light` 실패, 0.2는 통과(구멍 확인). 변이 없이 3회 통과.
- 2차 실행 `r9a-pr2-run2`(트리 `522fa273`, 골든 뺀 최종과 같은 코드):
- GREEN: 바뀐 시험 7파일 115개 통과. `check:design-system`·`check:types`·`lint`·`check:i18n` rc=0, `check:design-system:fixture` rc=1(기대, 새 `raw-inline-style.tsx` 두 줄 포함).
- RED(새 검사기로 고치기 전 style·토큰 CSS를 검사): UI-06 날 값 121건, UI-07 semantic 날 색 36건, 읽히지 않는 필수 semantic 토큰 6개(`--layer-modal`은 예외), 계약 밖 component 토큰 `--dialog-backdrop-weight`. story 대조 시험은 고치기 전 story로 37개 누락에서 실패.
- `test:storybook` 34개 통과(새 catalog story axe 20개와 열린 overlay 3개 포함).
- 골든: 토큰 커밋 골든으로 그 커밋 통과, 홈 커밋에서 셸 2장, story 커밋에서 상태 화면 1장 갱신. 최종 트리에서 변이 없이 3회 통과.
- `scripts/verify.sh merge` 1차(`r9a-pr2-merge`, 트리 `a2244671`): 005 rc=1(기능 모양 기록 낡음: precache 자산 기록 24, 빌드 22), 008 rc=1(아래 「위험과 영향」의 Chromium 1건), 나머지 12개 rc=0. 기록은 홈 커밋이 바꾼 것으로 확인(`r9a-pr2-shape`: 홈 커밋 직전 24개·파일 17, 홈 커밋 22개·파일 15)하고 측정 스크립트의 `--write` 결과를 홈 커밋에 넣었다.
- `scripts/verify.sh merge` 2차(`r9a-pr2-merge2`, 트리 `6c9c1371` = 이 PR head 트리, CI env): FE-GATE-001~013·020 14개 모두 rc=0. FE-GATE-013(시스템 컨테이너) 포함. 005 224 s, 008 340 s, 013 322 s, 020 537 s.
- 문서 단계 FE-GATE-017(`r9a-pr2-docs`) rc=0, `scripts/verify.sh parts FE-GATE-029`(`r9a-pr2-029`) rc=0(음성 fixture는 정해진 진단으로 실패).
- 노트북 `scripts/verify.sh docs`·`hooks` OK(스킬 토큰 이름 시험: 고치기 전 `--icon-size-*`로 실패, 고친 뒤 통과).
- 새 눈 리뷰(렌즈 fe-design-system·fe-testing·fe-ux) 1회: High 1(catalog story의 `SearchFilterToolbar`에 필수 `onReset` 없음), Low 3(인라인 style 규칙의 거짓 양성·음성, UI-06 문서 범위, story 대조가 주석·문자열도 셈), 넘길 것 1(열린 overlay에 axe 없음) → 모두 고쳤다.
## 발견 ID 표
| ID | 판정 | 커밋 |
|---|---|---|
| 1112/04-17 | 고침 | `009a2991` |
| 1112/04-13 | 고침 | `b384d29c` |
| 1112/04-08 | 고침 | `838ed410` |
| 1112/04-12 | 고침 | `838ed410` |
| 1101/12-03 | 고침 | `5fa4ebe1` |
| 1112/04-14 | 고침(R9-D6) | `5fa4ebe1` |
| 1112/04-15 | 고침 | `f948aa67` |
| 1112/04-06 | 고침 | `d5083f86` |
| 1112/04-10 | 고침 | `2f3ebba4` |
| 1112/04-16 | 고침 | `27da6d8d` |
| 1112/04-11 | 고침(R9-D8) | `91b3aaac` |
## 리뷰어가 볼 곳
- `scripts/lib/design-system-rules.ts`(새 규칙들)와 `tests/unit/design-system-rules.test.ts`
- `src/presentation/design-system/tokens/*.css`, `token-contract.ts`
- `src/presentation/styles/theme/*.css`의 반올림(커밋 본문의 표)
- 시각 골든 5장(토큰 커밋), 홈 2장(홈 커밋), 상태 화면 1장(story 커밋)
- `src/presentation/design-system/catalog.stories.tsx`, `tests/unit/design-system-story-coverage.test.ts`
## 관련
- 리뷰: `docs/reviews/2026-11-round9-04-ux-design-system.md`(DS-01~DS-10, UX-06), `-11-prior-findings-b.md` 3.18절(1101/12-03), 검증 `-15-verify-ux-ds-a11y.md`
- 결정: `docs/work/reference/decisions.md` R9-D6·D8
compact 내비게이션은 2026-11 셸 개편 뒤 Drawer다(`app-shell.tsx`). 그런데
`responsive.css`에 옛 고정 사이드바 배치, `[data-open="true"]`, 가림막
`.app-shell__scrim`(날 z-index 50·40, 가림막 35%)이 남았고 `pages.css`에도
scrim 규칙이 있었다. `data-open`을 세우거나 `app-shell__scrim`을 쓰는
TS·TSX는 0곳이다. 리브랜드할 때 가림막 정의가 둘로 보인다(dialog 55% 토큰,
죽은 35% 날 값).
고른 방법: 죽은 규칙을 지우고 compact의 `.app-shell__sidebar
{ display: none }`만 남긴다. 화면에 닿던 선언은 그것 하나였다.
검증: compact 시각 골든이 바뀌지 않는지 desktop test:visual로 본다(PR 본문).
Refs: 1112/04-17
`semantic.css`가 팔레트를 거치지 않은 날 `oklch()` 36개를 정의한다(밝은
테마의 focus와 info·success·warning·danger 세 쌍 13개, 어두운 테마 23개).
`PRODUCT.md`와 `docs/styling/design-tokens.md`는 토큰이 primitive →
semantic → component로 파생되고 팔레트는 `primitive.css`에 있다고 적는다.
그래서 팔레트만 바꿔 리브랜드하면 status 색, focus, 어두운 테마 대부분이
그대로다.
고른 방법: 36개 값을 그대로 `primitive.css` 팔레트로 옮기고 semantic은
`var()`로 읽는다. 색상 이름 무리(slate·night·blue·sky·green·amber·red)마다
밝기 순서로 단계 이름을 붙였다. 값은 바꾸지 않아 화면은 같다. 그리고
`check:design-system`에 UI-07을 더한다: semantic 선언값이 날 색(#hex,
oklch·oklab·lch·lab·rgb·hsl·hwb·color 함수)이면 실패하고, 토큰과 위치를
말한다. 버린 대안: 문서에 "semantic은 역할 전용 값을 가질 수 있다"와 예외
목록을 적는 것(리브랜드 약속이 그대로 깨진다).
위험·한계: 다운스트림이 `semantic.css`에 날 색을 더해 두었으면 다음
동기화에서 UI-07이 그 줄을 이름과 함께 알린다. 팔레트로 옮기면 된다.
UI-01 대비 계산은 var 사슬을 따라가므로 그대로 돈다.
검증: 규칙 단위 시험(거절 다섯·통과 셋·저장소 파일)과 check-design-system
연결 시험의 RED·GREEN, 시각 골든 불변은 desktop에서 돌려 PR 본문에 적는다.
Refs: 1112/04-13
셸·페이지 템플릿·카드 CSS가 간격·글자·반경·층·그림자 토큰을 건너뛰고 날
값을 쓴다(`src/presentation/styles/theme/*.css`에서 규칙에 걸리는 선언
118개). `shell.css`·`pages.css`·`templates.css`는 `var(--space-*)`를 한
번도 쓰지 않았고, z-index 100·30·10, 카드·헤더의 손 그림자, `999px`,
`min-height: 2.75rem`이 토큰과 같은 값을 다시 적었다. 필수 semantic 토큰
가운데 `--layer-navigation`·`--layer-modal`·`--opacity-scrim`·
`--opacity-skeleton`·`--elevation-panel`·`--color-disabled-content`·
`--color-action-pressed`를 읽는 스타일이 없었다. 그래서 파생 서비스가
밀도·층·그림자를 토큰으로 바꿔도 화면이 그대로다. 그리고 component.css의
가림막 토큰 셋이 `REQUIRED_COMPONENT_TOKENS`에 없어 UI-03 밖이었다(04-12).
고른 방법:
- 날 값을 토큰으로 바꾼다. 맞는 단계가 없는 간격은 가까운 `--space-*`로
반올림했다(0.15~0.35rem → 1, 0.4~0.55 → 2, 0.65~0.85 → 3, 0.9 → 4).
큰 값 3.5rem·4rem은 `--space-14`·`--space-16`을 더했다. 글자 크기도
가까운 단계(0.8 → xs, 0.8125~0.9 → sm, 1.05 → md, 1.1 → lg, 1.35 → xl),
굵기 600·650 → semibold, 700·750·800 → bold, 줄 높이 1.5~1.6 → normal,
1.65·1.7 → relaxed. 페이지 h1은 semantic `--font-size-heading-1`·
`--line-height-heading-1`(새 primitive 단계 3xl·4xl·compact)을 읽는다.
- 층: skip link는 `--layer-navigation`, sticky 헤더와 sticky 폼 버튼은
`--layer-sticky`. 그림자: 카드·패널·갤러리 안내는 `--elevation-panel`,
헤더는 새 `--elevation-sticky`(`--shadow-sticky`). `.ui-panel`의 Tailwind
`shadow-sm`도 `--elevation-panel`로 바꿔 카드와 같은 높이가 됐다. dialog는
`--radius-modal`, 가림막 비율은 `--opacity-scrim`을 읽고
`--dialog-backdrop-weight`는 지웠다.
- 읽는 곳이 없던 semantic 토큰: skeleton 깜박임이 `--opacity-skeleton`,
꺼진 입력이 `--color-disabled-content`·`--color-disabled-surface`, 누른
primary 버튼이 새 component 토큰 `--button-primary-pressed`
(`--color-action-pressed`)를 읽는다. `--layer-modal`은 native `<dialog>`가
top layer에 열려 z-index가 닿지 않으므로 이유와 함께
`SEMANTIC_TOKENS_WITHOUT_TEMPLATE_READER`에 둔다.
- `check:design-system`에 셋을 더한다. UI-06: styles 아래 간격·글자·반경·
z-index·그림자의 날 값을 줄 번호와 함께 거절한다. UI-03을 필수 semantic
토큰으로 넓힌다. component.css `@theme`의 토큰이 모두 계약에 있어야 한다.
계약에 `--button-primary-pressed`, `--dialog-backdrop`,
`--dialog-backdrop-on-surface`를 더했다.
- 버린 대안: 맞는 단계가 없는 값마다 primitive 단계를 더하기(단계가 두 배로
늘어 scale이 무의미해진다). `--layer-modal`을 dialog에 z-index로 읽히기
(top layer에서는 효과가 없는 가짜 읽기다).
위험·한계: 반올림과 패널 그림자 때문에 화면이 조금 바뀐다(간격 최대
0.15rem, 굵기 800 → 750, 패널 그림자 크기). 시각 골든은 이 커밋에서 다시
찍고 차이를 PR 본문에 적는다. 다운스트림이 styles에 날 값을 더해 두었으면
UI-06이 그 줄을 알린다. 너비·높이·위치(top 등)와 opacity는 UI-06 밖이다.
검증: 규칙 단위 시험과 check-design-system 연결 시험, 새 검사기로 고치기
전 CSS를 돌린 결과(RED), 시각 골든은 desktop에서 돌려 PR 본문에 적는다.
Refs: 1112/04-08, 1112/04-12
`check:design-system`이 잡지 못하는 길이 다섯 남았다(1101/12-03, 지금 위반
없음). gradient의 색상각 보간(`linear-gradient(in oklch, …)`)은 UI-02가
`color-mix`만 봐서 지난다. TSX 인라인 `color-mix`도 그렇다. 기능 폴더의 CSS는
아예 읽지 않는다. style sheet에서 `:root`로 토큰을 다시 정의해도, focus ring을
`outline-offset: 0`으로 그려 UI-01의 대비 계산 밖으로 내보내도 지난다. 그리고
primitive의 `className`·`style`이 범위 없이 열려 있어 화면이 primitive 위에
`style={{ color: "red", padding: 13 }}`을 얹어도 막는 것이 없다(04-14).
고른 방법: UI-02 정규식이 gradient의 색 공간까지 보고 TS·TSX 소스에도 돈다.
토큰 파일 밖 CSS는 `src/` 아래 전부를 읽고, 날 색·토큰 재정의·offset 0
focus ring을 거절한다. 04-14는 결정(2026-11-12, 총괄: 공개 props는 두고
검사를 더한다)대로 TSX `style={{ … }}`의 손 색(키워드·`var()` 말고)과 손
간격·글자·반경·층·그림자 값을 거절한다. `className`·`style`의 범위(배치용)를
`docs/styling/design-tokens.md`에 적고, fe-design-system 스킬의 「검사가 안
보는 것」 문장을 새 범위에 맞췄다. 거절 fixture `raw-inline-style.tsx`를
더했다. 버린 대안: primitive 공개 props에서 `style`을 빼기(배럴 표면 BREAKING).
위험·한계: 다운스트림이 기능 CSS나 인라인 style에 날 값을 두었으면 다음
동기화에서 그 줄이 이름과 함께 실패한다. 문자열로 조립한 class와 Tailwind
임의 값은 여전히 보지 않는다.
검증: 규칙 단위 시험, check-design-system 연결 시험(기능 폴더 probe CSS),
`check:design-system:fixture`(FE-GATE-029)는 desktop에서 돌려 PR 본문에 적는다.
Refs: 1101/12-03, 1112/04-14
fe-design-system 스킬의 기준 문장 두 곳이 실제 규칙·토큰과 다르다.
`color-mix()`는 `in oklab`만 쓴다고 적었지만 규칙(UI-02)은 색상각 공간만
거절하고, 코드는 반투명 가림막을 브라우저가 겹쳐 그린 색과 맞추려고
`in srgb`를 일부러 쓴다. `docs/styling/design-tokens.md` UI-02도 같은
문장이었다. 그리고 아이콘 토큰을 `--icon-size-*`라고 적었지만 실제 이름은
`--size-icon-*`·`--icon-stroke-default`다. 스킬을 따르는 리뷰어가 srgb를
oklab으로 "고치면" 스크롤바 자리 색 맞춤이 깨지고, 없는 토큰을 새로 만든다.
고른 방법: 두 문서의 문장을 규칙과 토큰 이름에 맞춘다. 그리고
`scripts/tests/test_claude_setup.py`에 "스킬이 백틱으로 적은 토큰 이름(토큰
이름공간만, 별표는 아무 이름)은 토큰 파일이 정의한다" 시험을 더한다. 버린
대안: 문서만 고치기(같은 어긋남이 다시 생겨도 아무도 모른다).
검증: 노트북 `python3 -m unittest scripts.tests.test_claude_setup`. 고치기 전
스킬에서 새 시험이 `--icon-size-*`로 실패했고, 고친 뒤 전부 통과한다.
Refs: 1112/04-15
홈(`src/presentation/pages/home-page.tsx`)이 페이지 템플릿 대신 자기
`section.ui-page`와 `PageHeader`를 쓰고, 시작 링크를
`<Link className="ui-button …">`으로 `LinkButton`을 손으로 다시 만든다.
`PRODUCT.md`는 홈이 파생 서비스에 남는다고 적는다. 그래서 그대로 복제되고
개발자가 따라 하는 예가 된다. `LinkButton`의 variant·size가 바뀌면 홈만
어긋난다.
고른 방법: `StandardPage`(heading 슬롯에 eyebrow·제목·설명)와
`LinkButton variant="primary"/"secondary"`로 바꾼다. 준비 목록, 런타임 요약,
시작 링크는 템플릿의 본문 자리에 `home-page__sections`(블록 사이 `--space-6`)로
묶어 둔다. 템플릿 본문 자리에는 간격이 없어, 묶지 않으면 런타임 요약이 카드에
붙는다(첫 골든에서 보고 고쳤다). component 시험이 홈의 링크가
standard 템플릿 안의 `ui-button ui-button--primary`인지 본다.
위험·한계: 머리말과 본문 사이는 템플릿 간격(`--space-5`)이라 홈의 세로 간격이
조금 바뀐다. 시각 골든은 이 커밋에서 다시 찍고 이유를
PR 본문에 적는다.
홈이 템플릿과 `LinkButton`을 쓰면서 번들러가 청크 둘을 합쳤다. 초기 JS는
파일 17 → 15개, gzip 194,397 → 194,143 B, Service Worker precache 자산은
24 → 22개다. `config/scale/feature-shape-ceilings.json`은 측정 스크립트
(`node scripts/scale/measure-feature-shape-growth.ts --initial-baseline
--write`, desktop)가 쓴 그대로다.
검증: `tests/component/starter-pages.test.tsx`와 시각 골든은 desktop에서
돌린다(PR 본문).
Refs: 1112/04-06
디자인 시스템 배럴(`src/presentation/design-system/index.ts`)의 값 export
가운데 화면 컴포넌트 37개에 story가 없다: SearchField·ConfirmationDialog·
Drawer·Popover·Breadcrumbs·Pagination·LinkButton·Separator·IconButton 같은
primitive, DataTable 등 pattern 다섯, 페이지 템플릿 다섯, 폼 구성요소, 아이콘
아홉. 결과를 모르는 저장(확인·같은 요청 다시 보내기), 충돌, 오래된 데이터,
저장 중은 갤러리와 골든에 없다. 그래서 파생 서비스가 쓸 컴포넌트의 상태를 볼
곳이 없고, 그 배치 회귀를 골든이 잡지 못한다.
고른 방법:
- `catalog.stories.tsx`에 묶음 story 열을 더한다(겹치는 화면, 탐색과 입력,
아이콘, 화면 패턴, 페이지 템플릿 다섯을 하나씩, 저장 결과). 템플릿 story는
각자 자기 h1을 그린다.
- ScreenStates 갤러리에 저장 상태 절을 더한다: 결과를 모르는 저장(다시 보내기
가능), 충돌, 오래된 데이터, 저장 중, 입력과 무관한 저장 실패
(FormFailureStatus), 입력 오류 요약. `state-surfaces-light` 골든이 이 절을
담는다.
- `tests/unit/design-system-story-coverage.test.ts`가 배럴의 값 export마다
story에서 `<Name`으로 그려지는지 대조한다. 그리지 않는 것(Portal·FocusRing·
VisuallyHidden, 토큰 상수, hook)은 이유와 함께 목록에 둔다.
- 새 story 열은 `tests/storybook/galleries.spec.ts`의 axe 검사(light·dark)에
더했고, 겹치는 화면 셋(확인 대화 상자, 서랍, 팝오버)은 연 상태로도 본다.
대조 시험이 catalog story마다 그 목록에 있는지 본다.
- 갤러리에 넣으면서 드러난 둘을 고쳤다. 저장 상태 안내의 문장과 버튼이 붙어
있었다(`.async-surface__status`: 한 줄로 감싸고 간격, 지원 참조는 아랫줄).
`FormFailureStatus`가 제목 단계를 받지 못해 카드 안에서 h2로 그려졌다
(`headingLevel`, 추가만, 다른 상태 표면과 같은 08-05 계약).
- 버린 대안: 컴포넌트마다 variant 행렬 story를 한 번에 쓰기(이번 범위는 "모든
화면 컴포넌트에 story 하나 이상"이고, 행렬은 컴포넌트를 고칠 때 더한다).
StatusPage를 갤러리에 넣기(자기 h1을 그려 갤러리의 h1과 겹친다. 자기
story로 뒀다).
위험·한계: 갤러리 골든이 바뀐다(이 커밋에서 다시 찍는다). theme·locale
toolbar는 아직 없다. story axe가 20번 늘어 FE-GATE-008이 조금 길어진다.
검증: 대조 시험(고치기 전 story 파일에서 37개 누락으로 실패), story 빌드
(FE-GATE-011), story axe와 시각 골든(FE-GATE-008)은 desktop에서 돌려 PR
본문에 적는다.
Refs: 1112/04-10
`docs/styling/design-tokens.md` 「들어 있는 primitive」가 Button·TextField·
Card·Alert/Badge·Dialog·상태 surface 여섯만 적는다. 실제 배럴에는 primitive
25개, pattern 5개, 페이지 템플릿, 폼 구성요소가 있고, 문서는 스스로 "지금
구현된 primitive 기준선을 적는다"고 한다. fe-a11y 스킬이 이 절을 근거로 든다.
고른 방법: 손 목록을 지우고 정본(배럴 `index.ts`)과 상태를 여는 곳(갤러리·
카탈로그 story), 대조 시험을 가리킨다. 목록이 들고 있던 약속(색에만 기대지
않음, tooltip에만 두지 않음, overlay의 Escape·focus 복원)은 문장으로 남긴다.
fe-a11y 스킬이 이 절을 인용하므로 절 제목은 그대로 둔다.
검증: 노트북 `scripts/verify.sh docs`, desktop `verify:documentation`(PR
본문).
Refs: 1112/04-16
시각 골든은 `maxDiffPixels: 50`만 정하고 색 허용치(threshold)를 두지 않아
Playwright 기본값 0.2를 쓴다. 0.2는 pixelmatch YIQ 거리로 1408.6까지 같은
색으로 본다. 밝은 `--color-danger-surface`의 색상각 25 → 145(분홍 → 초록,
거리 154.5)와 어두운 `--color-danger` 한 단계(거리 1260.1)가 옛 골든과 새
골든을 모두 통과했다. 그래서 위험 표면이 초록빛으로 바뀌어도 골든이 통과한다.
CHANGELOG 알려진 제한으로만 적혀 있었다.
고른 방법: 결정(2026-11-12, 총괄: 흔들림 없는 값을 재서 낮춘다)대로 0.05(거리
88.0)를 쓴다. 기준을 올리는 쪽이다. `playwright.visual.config.ts`는 지금
w2-fe-2가 브라우저 실행 설정을 고치는 중이라 이번에 건드리지 않고, 시각
spec이 모든 screenshot에 `GOLDEN`(threshold 0.05)을 넘긴다. 새 screenshot이
빠뜨리지 않도록 `tests/unit/visual-golden-threshold.test.ts`가 대조한다. 버린
대안: 0.1(거리 352.2라 첫 변이가 다시 통과한다).
위험·한계: 글꼴·래스터 설정을 고정한 깨끗한 빌드는 0 px 차이라는 기존 주장에
기댄다. desktop에서 변이 없이 세 번, 변이로 한 번 돌려 PR 본문에 적는다.
설정 기본값은 0.2 그대로라 다른 Playwright 설정의 screenshot은 이 값을 받지
않는다(지금 다른 곳에는 screenshot이 없다).
검증: 실험 X-02(변이 `--color-danger-surface` 색상각 145에서 0.2는 통과,
0.05는 `state-surfaces-light` 실패, 변이 없이 세 번 통과)는 desktop에서
돌려 PR 본문에 적는다.
Refs: 1112/04-11
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
round9 확인 리뷰 그룹 A의 묶음 A3(디자인 토큰)·A4(story·골든·검사)와, 같은 파일·골든을 바꿔 이 PR로 옮긴 04-06·04-17을 고친다.
REQUIRED_COMPONENT_TOKENS에 없어 UI-03 밖이다.oklch()36개를 정의한다. 팔레트만 바꿔 리브랜드하면 status·focus·다크 테마가 그대로다.color-mix문장과 아이콘 토큰 이름이 규칙·토큰과 다르다.docs/styling/design-tokens.md「들어 있는 primitive」가 일부만 손으로 적는다.className·style이 범위 없이 열려 날 색·간격을 얹어도 막는 것이 없다.LinkButton을 손으로 다시 만든다.color-mix, 기능 폴더 CSS, 토큰 재정의,outline-offset: 0을 못 잡는다.고른 방법과 버린 대안
(커밋 본문에 발견마다 자세히 적었다.)
--space-14·--space-16을 더함). 층·그림자·반경·가림막은 해당 semantic 토큰을 읽는다. 읽는 곳이 없던 semantic 토큰은 실제 쓰임(skeleton, 꺼진 입력, 누른 primary 버튼)에 잇고,--layer-modal은 native<dialog>top layer라 이유와 함께 예외 목록에 둔다. semantic 색 36개는 값 그대로 팔레트로 옮긴다.catalog.stories.tsx에 묶음 story 열, 갤러리에 저장 상태 절, 배럴 대조 시험, 새 story 전부와 열린 overlay에 axe.--layer-modal가짜 읽기, 공개 props에서style빼기(BREAKING), 0.1(첫 변이가 다시 통과), 문서에 semantic 예외 목록만 적기.정한 기본값
playwright.visual.config.ts는 이번 brief가 막았다(w2-fe-2가 브라우저 실행 설정을 고치는 중). 그래서 threshold를tests/visual/platform.visual.spec.ts의GOLDEN으로 모든 screenshot에 넘기고, 빠뜨리면tests/unit/visual-golden-threshold.test.ts가 잡는다. 설정 기본값은 0.2 그대로다..ui-panel의 Tailwindshadow-sm도--elevation-panel로 바꿔 카드와 같은 높이가 됐다(시각 변화, 의도).--font-weight-bold(750)로 줄었다..async-surface__status줄 간격),FormFailureStatus가 제목 단계를 받지 못한 것(headingLevel추가만).위험과 영향
:root토큰 재정의,outline-offset: 0, TSXstyle의 날 색·간격은 다음 동기화에서check:design-system이 줄과 함께 실패한다. 토큰으로 바꾼다.REQUIRED_COMPONENT_TOKENS에 더하고 읽게 한다.--dialog-backdrop-weight가 없어졌다. 가림막 비율은--opacity-scrim이다.tests/browser-capabilities/cross-context-invalidation.spec.ts:223(localStorage 이벤트 대체 경로, storage 이벤트가 5초 안에 오지 않음) 1건으로 실패했다. desktop에서 그 시험만 20회씩 반복하니 이 PR 트리 0/20 실패, 기준(main7e5a0bb8의 src·tests) 1/20 실패다(r9a-pr2-flake). 이 PR은 adapter와 그 시험을 건드리지 않는다. 그룹 C(시험 신뢰도)로 넘긴다. 2차 merge의 FE-GATE-008은 통과했다.ee95573f이고 #47(Firefox 프로필 RAM·browser job/dev/shm2 GB)을 담지 않는다. runner browser job에서 Firefox 첫 렌더 흔들림이 나면 #51처럼 main을 받아 다시 돈다(총괄이 정한다).검증
(desktop,
scripts/verify.sh, 공유 잠금)r9a-pr2-run(트리82f64cbe): 골든 — C1(사이드바 CSS)·C2(팔레트)에서 main 골든 그대로 통과(화면 변화 없음), 토큰 커밋에서 5장 바뀜. X-02: 변이--color-danger-surface색상각 145에서 0.05는state-surfaces-light실패, 0.2는 통과(구멍 확인). 변이 없이 3회 통과.r9a-pr2-run2(트리522fa273, 골든 뺀 최종과 같은 코드):check:design-system·check:types·lint·check:i18nrc=0,check:design-system:fixturerc=1(기대, 새raw-inline-style.tsx두 줄 포함).--layer-modal은 예외), 계약 밖 component 토큰--dialog-backdrop-weight. story 대조 시험은 고치기 전 story로 37개 누락에서 실패.test:storybook34개 통과(새 catalog story axe 20개와 열린 overlay 3개 포함).scripts/verify.sh merge1차(r9a-pr2-merge, 트리a2244671): 005 rc=1(기능 모양 기록 낡음: precache 자산 기록 24, 빌드 22), 008 rc=1(아래 「위험과 영향」의 Chromium 1건), 나머지 12개 rc=0. 기록은 홈 커밋이 바꾼 것으로 확인(r9a-pr2-shape: 홈 커밋 직전 24개·파일 17, 홈 커밋 22개·파일 15)하고 측정 스크립트의--write결과를 홈 커밋에 넣었다.scripts/verify.sh merge2차(r9a-pr2-merge2, 트리6c9c1371= 이 PR head 트리, CI env): FE-GATE-001~013·020 14개 모두 rc=0. FE-GATE-013(시스템 컨테이너) 포함. 005 224 s, 008 340 s, 013 322 s, 020 537 s.r9a-pr2-docs) rc=0,scripts/verify.sh parts FE-GATE-029(r9a-pr2-029) rc=0(음성 fixture는 정해진 진단으로 실패).scripts/verify.sh docs·hooksOK(스킬 토큰 이름 시험: 고치기 전--icon-size-*로 실패, 고친 뒤 통과).SearchFilterToolbar에 필수onReset없음), Low 3(인라인 style 규칙의 거짓 양성·음성, UI-06 문서 범위, story 대조가 주석·문자열도 셈), 넘길 것 1(열린 overlay에 axe 없음) → 모두 고쳤다.발견 ID 표
009a2991b384d29c838ed410838ed4105fa4ebe15fa4ebe1f948aa67d5083f862f3ebba427da6d8d91b3aaac리뷰어가 볼 곳
scripts/lib/design-system-rules.ts(새 규칙들)와tests/unit/design-system-rules.test.tssrc/presentation/design-system/tokens/*.css,token-contract.tssrc/presentation/styles/theme/*.css의 반올림(커밋 본문의 표)src/presentation/design-system/catalog.stories.tsx,tests/unit/design-system-story-coverage.test.ts관련
docs/reviews/2026-11-round9-04-ux-design-system.md(DS-01~DS-10, UX-06),-11-prior-findings-b.md3.18절(1101/12-03), 검증-15-verify-ux-ds-a11y.mddocs/work/reference/decisions.mdR9-D6·D8compact 내비게이션은 2026-11 셸 개편 뒤 Drawer다(`app-shell.tsx`). 그런데 `responsive.css`에 옛 고정 사이드바 배치, `[data-open="true"]`, 가림막 `.app-shell__scrim`(날 z-index 50·40, 가림막 35%)이 남았고 `pages.css`에도 scrim 규칙이 있었다. `data-open`을 세우거나 `app-shell__scrim`을 쓰는 TS·TSX는 0곳이다. 리브랜드할 때 가림막 정의가 둘로 보인다(dialog 55% 토큰, 죽은 35% 날 값). 고른 방법: 죽은 규칙을 지우고 compact의 `.app-shell__sidebar { display: none }`만 남긴다. 화면에 닿던 선언은 그것 하나였다. 검증: compact 시각 골든이 바뀌지 않는지 desktop test:visual로 본다(PR 본문). Refs: 1112/04-17`check:design-system`이 잡지 못하는 길이 다섯 남았다(1101/12-03, 지금 위반 없음). gradient의 색상각 보간(`linear-gradient(in oklch, …)`)은 UI-02가 `color-mix`만 봐서 지난다. TSX 인라인 `color-mix`도 그렇다. 기능 폴더의 CSS는 아예 읽지 않는다. style sheet에서 `:root`로 토큰을 다시 정의해도, focus ring을 `outline-offset: 0`으로 그려 UI-01의 대비 계산 밖으로 내보내도 지난다. 그리고 primitive의 `className`·`style`이 범위 없이 열려 있어 화면이 primitive 위에 `style={{ color: "red", padding: 13 }}`을 얹어도 막는 것이 없다(04-14). 고른 방법: UI-02 정규식이 gradient의 색 공간까지 보고 TS·TSX 소스에도 돈다. 토큰 파일 밖 CSS는 `src/` 아래 전부를 읽고, 날 색·토큰 재정의·offset 0 focus ring을 거절한다. 04-14는 결정(2026-11-12, 총괄: 공개 props는 두고 검사를 더한다)대로 TSX `style={{ … }}`의 손 색(키워드·`var()` 말고)과 손 간격·글자·반경·층·그림자 값을 거절한다. `className`·`style`의 범위(배치용)를 `docs/styling/design-tokens.md`에 적고, fe-design-system 스킬의 「검사가 안 보는 것」 문장을 새 범위에 맞췄다. 거절 fixture `raw-inline-style.tsx`를 더했다. 버린 대안: primitive 공개 props에서 `style`을 빼기(배럴 표면 BREAKING). 위험·한계: 다운스트림이 기능 CSS나 인라인 style에 날 값을 두었으면 다음 동기화에서 그 줄이 이름과 함께 실패한다. 문자열로 조립한 class와 Tailwind 임의 값은 여전히 보지 않는다. 검증: 규칙 단위 시험, check-design-system 연결 시험(기능 폴더 probe CSS), `check:design-system:fixture`(FE-GATE-029)는 desktop에서 돌려 PR 본문에 적는다. Refs: 1101/12-03, 1112/04-14