디자인 시스템 배럴(`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
홈(`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
셸·페이지 템플릿·카드 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
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
셸 헤더의 세션 버튼과 로그인 안내(StatusPage)의 로그인·복구 버튼이 처리 중에
`disabled`가 된다. 템플릿 action API(`PageActionDefinition`)에는 `pending`이
없어 상태 화면은 끄는 길밖에 없었다. 꺼진 버튼은 키보드 포커스를 잃는다.
키보드로 "로그인 시작"을 누르고 sign-in이 실패하면 실패 알림이 뜰 때 포커스는
이미 body에 있다(결함 패턴 C11). 모든 파생 서비스의 셸이 복제한다. 같은
모양으로 Pagination의 「이전」을 2쪽에서 누르면 1쪽이 되며 그 버튼이 꺼져
포커스가 떨어진다.
고른 방법: `PageActionDefinition` 버튼에 `pending`·`pendingLabel`을 더해
`Button`으로 넘긴다(추가만). 라우터 상태 화면과 셸 세션 버튼은 `disabled`
대신 `pending`을 쓴다. 버튼은 켜진 채 `aria-busy="true"`이고, 처리 중에 그 버튼이나
다른 세션 버튼(셸과 상태 화면)을 누르면 `useSessionAction().run`이 무시한다.
`SessionProvider`가 세션 버튼 모두에 잠금 하나를 준다(중복 실행을
`disabled`에 기대지 않는다). Pagination 끝 버튼은 `aria-disabled`와 누름 무시로 바꾸고, 같은
모양(`.ui-button[aria-disabled="true"]`)으로 그린다. 버린 대안: `Button`의
`pending`이 클릭을 삼키게 하기(폼은 이미 자기 `pendingRef`로 막고, 공개
primitive의 동작이 바뀐다).
위험·한계: 다운스트림이 `PageActionDefinition`에 `disabled: pending`을 넘기고
있으면 그대로 동작하지만 포커스를 잃는다. `pending`으로 옮기면 된다. jsdom은
꺼진 버튼의 포커스를 떨어뜨리지 않아 component 시험은 `disabled`가 아님과
`aria-busy`, 실패 뒤 포커스를 본다.
검증: `tests/component/route-status-surfaces.test.tsx` 세 사례와
`tests/component/pagination.test.tsx` 끝 버튼 두 사례가 고치기 전 코드에서
실패하고 고친 뒤 통과한다(desktop, PR 본문).
Refs: 1112/05-03, 1112/04-05
앞 커밋(1112/01-01) 뒤 확인 리뷰가 완료 기준의 남은 셋과 결함 둘을 찾았다.
- 생성 작성 페이지에 마운트 표시(useRef)와 저장 뒤 이동이 남았다. 저장이
끝나면 페이지가 폼보다 먼저, 폼이 pending인 동안 상세로 옮겼다. 다시
마운트한 폼에서 재전송이 성공하면 사용자가 돌아와 입력한, 보낸 적 없는
값을 이탈 확인 없이 버렸다(1112/01-02 영향).
- 폼이 재전송 결과로 결과 불명을 다시 판정했다(resendLeftUnknown).
코디네이터와 401에서 갈린다. 코디네이터는 결과 불명을 쥐고 폼은 다시
로그인으로 가는데, FormSaveFeedback이 결과 불명을 먼저 그려 다시 로그인
안내를 가렸다(D-2 위반).
- 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 생성 페이지 시험에만
있었다.
고른 방법: useAppForm에 onSaved를 더한다(추가만). 폼이 결과를 보이고
pending을 끈 뒤, 마운트된 동안만 부른다. confirmUnknownEffect(then)도
마운트된 동안만 then을 부른다. resendUnknownEffect의 then 인자와
FormSaveFeedback의 onResent는 지운다(앞 커밋에서 생겨 아직 내보낸 적이
없다). 재전송 뒤 결과 불명인지는 코디네이터의 새 holdsUnknownEffect로
묻는다. mutation 없이 쓰는 폼(이미 생성한 페이지)은 물을 곳이 없어 같은
거절 표(isRefusedOnEveryAttempt)로 본다. FormSaveFeedback은 다시 로그인
실패를 결과 불명보다 먼저 그린다. 생성 페이지는 mutation.submit을 그대로
넘기고 onSaved와 onConfirmed에서 옮기기만 한다. VD-04 머리 칸에 넣었던
문장은 보완 절로 옮긴다(머리 칸의 백틱 낱말을 문서 검사가 경로로 본다).
페이지가 FormSaveFeedback을 늘 넘기므로, 할 말이 없는 피드백 칸은 자리를
차지하지 않는다(templates.css, 빈 칸이 그리드 간격을 한 줄 더했다).
위험·한계: 저장 뒤 이동이 폼이 결과를 그린 뒤로 한 번 늦어진다. 다시
마운트한 폼에 보내지 않은 값이 있으면 이동이 이탈 확인을 띄운다(의도).
검증: form-foundation 새 시험 일곱과 create-feature 생성 페이지 시험
(RED·GREEN, 막기·다른 저장·충돌 안내 변이 셋), 생성 기능 e2e의 피드백 칸 간격 시험은 desktop에서 돌려 PR
본문에 적는다.
Refs: 1112/01-01, 1112/01-02, 1105/08-02, 1105/08-04, 1106/08-02, 1112/04-02
공통 primitive가 디자인 시스템 설계 8.1·8.2절과 WCAG 2.2 AA 약속을
어긴다.
- Popover가 이름 없는 role="dialog"를 그린다(1112/05-10).
- Dialog 안의 Menu·Popover·Tooltip에서 Escape를 누르면 Dialog까지
닫힌다. Dialog가 안쪽이 처리한 Escape를 보지 않는다(05-11).
- SearchField는 required 기호만, Checkbox는 상태만 있다(05-13).
- Toast를 닫기 버튼으로 닫으면 포커스가 body로 떨어진다(05-14).
- TextArea 글자 수가 <output>(암묵 status)이라 글자마다 발표되고 입력과
이어지지 않는다(05-17).
- 라우트 h1의 :focus outline 제거가 layer 순서로 키보드 :focus-visible
표시까지 지운다(05-02). Tooltip이 pointer-events: none과 틈 때문에
포인터를 설명 위로 옮기면 사라진다(1.4.13, 05-06).
- 홈 readiness 목록이 role 없는 div에 aria-label을 단다(05-15).
- fe-a11y·fe-ux 스킬이 제출 실패 때 오류 요약으로 포커스가 간다고 적는다.
코드는 첫 오류 필드로 보낸다(05-09).
고른 방법: Popover는 trigger id로 이름을 받는다. Popover·Tooltip은
Escape를 capture 단계에서 받아 preventDefault하고, Dialog는 기본 동작이
막힌 Escape(과 그 뒤 cancel)를 넘긴다. Tooltip은 보일 때(hover·focus)만
Escape를 가진다. 숨은 tooltip이 다른 Dialog의 Escape를 막지 않게 하려는
것이다. Toast 닫기는 다음 toast의 닫기 버튼, 없으면 toast로 들어오기 전
요소로 포커스를 돌린다. TextArea 글자 수는 aria-describedby로 잇고 0에
닿을 때만 따로 발표한다. h1은 :focus:not(:focus-visible)만 outline을
지운다. Tooltip은 보일 때만 포인터를 받고 ::before 다리로 틈을 메운다.
버린 대안: Dialog가 안쪽 layer 목록을 들고 Escape를 나누기(primitive끼리
묶인다).
위험·한계: native <dialog>가 막힌 keydown 뒤에도 cancel을 쏘는지는
브라우저마다 다를 수 있어, Dialog는 같은 task의 cancel 하나를 넘긴다.
Toast가 돌려줄 요소가 지워졌으면 포커스를 옮기지 않는다. 시각 골든이
바뀌는지는 desktop test:visual로 본다.
검증: 새 component 시험(tests/component/design-system-a11y.test.tsx,
starter-pages), e2e(app-shell focus ring, 세 엔진), storybook(tooltip
hover)의 RED·GREEN은 desktop에서 돌려 PR 본문에 적는다.
Refs: 1112/05-02, 1112/05-06, 1112/05-09, 1112/05-10, 1112/05-11,
1112/05-13, 1112/05-14, 1112/05-15, 1112/05-17
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.
참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.
위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.
검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
문제: :root의 scrollbar-gutter: stable(1105/15-05)은 일반 스크롤바를 쓰는
브라우저에서 문서가 스크롤되지 않아도 오른쪽 15 px를 비워 둔다. 그 자리에는
root의 배경색이 보인다. 고정 위치 상자와 top layer의 ::backdrop은 그 자리
앞에서 끝나서, drawer·modal을 열면 오른쪽 끝에 가림막이 덮지 않은 밝은
세로 띠가 남는다. compact 골든(390 px, drawer 열림)이 가림막이 375 px에서
끝나는 모습을 정답으로 고정했다. header 띠도 같은 자리 앞에서 끝난다.
고른 방법:
- modal이 열린 동안 root 배경색을 가림막을 페이지 바탕 위에 겹친 불투명한
색으로 바꾼다. primitives.css의 :root:has(.ui-dialog[open])이
background-color: var(--dialog-backdrop-on-surface)를 쓴다.
- 새 컴포넌트 토큰 셋(component.css). --dialog-backdrop-weight(55%)를
--dialog-backdrop(::backdrop이 칠하는 반투명 가림막, 값은 전과 같다)과
--dialog-backdrop-on-surface(color-mix in srgb로 페이지 바탕과 섞은 색)가
같이 읽는다. 브라우저는 반투명 색을 sRGB에서 겹치므로 두 색이 맞는다.
- body가 페이지 바탕(--color-surface)을 직접 칠한다. 그래서 root 배경은
스크롤바 자리(와 overscroll)에만 보이고, 열린 modal 아래 페이지가 두 번
어두워지지 않는다. modal이 없으면 둘이 같은 색이라 화면이 그대로다.
- 검사: tests/visual/scrollbar-gutter.visual.spec.ts. 시각 프로젝트에서
Chromium을 --hide-scrollbars 없이 띄우고, 스크롤되지 않는 /not-found
(390x844)에서 스크롤바 자리와 바로 옆 가림막의 평균 픽셀 색을 비교한다.
닫힘 → drawer 열림 → 다시 닫힘 세 번 본다. 실패 메시지에 root의 계산된
배경(색·이미지)과 열린 .ui-dialog 수를 적어, 규칙이 안 맞은 것과 맞았는데
그 자리에 안 그려진 것을 구분한다. 08-R2 probe의 잘못된 단언 둘을
고쳤다. 자리가 비어 있으면 clientWidth가 창 폭이라 자리 위치는 body의
오른쪽 끝으로 찾는다. 그 자리의 hit test는 늘 null이라 픽셀을 본다.
허용 차이 12는 drawer 그림자(70 px blur)가 옆 띠를 약 3단계 어둡게 하는
몫이다. 덮지 않은 띠는 약 120 차이 난다.
- header 띠는 받아들이고 design-system-platform.md 8.2에 적었다. header
색으로 칠하려면 root 배경이 셸의 header 높이·색을 알아야 하고, 셸이 없는
화면에서는 그 띠를 빼야 한다. 완료 기준은 가림막만 요구한다.
버린 대안:
- 첫 시도: :root:has(.ui-dialog:modal)에서 가림막 색 gradient 한 겹을 페이지
바탕 위에 얹었다. desktop batch에서 그 자리가 페이지 바탕색 그대로였다
(gutter rgb(248 250 252), 옆 가림막 rgb(122 128 136)). 그 실행만으로는
규칙이 안 맞았는지(:modal의 :has() 무효화), 이미지 층이 그 자리에 안
그려졌는지 가를 수 없다. 그래서 둘 다 피한다. 배경색 자체를 바꾸고,
showModal()이 세우는 [open] 속성으로 고른다. Dialog primitive는 브라우저에서
늘 showModal()로 열기 때문에 열린 .ui-dialog는 modal이다.
- ::backdrop에 음수 inset(right: -N px): 스크롤바 자리는 viewport의
padding box 밖이라 고정 위치 상자가 잘린다(스펙 기준, 화면 확인은 안 함).
- scrollbar-gutter를 거두기: 15-05의 첫 화면 shift를 다시 연다.
- modal이 열린 동안 root 배경만 바꾸고 body를 비워 두기: 페이지 전체가
가림막 아래에서 한 번 더 어두워진다.
위험·한계: :has()를 모르는 브라우저(Firefox 121 미만 등)는 이 규칙을 버리고
전처럼 띠가 남는다. 그 자리 색은 가림막의 blur(2px)를 따르지 않는 평평한
색이다. 오른쪽 drawer(placement="end")는 drawer와 창 끝 사이에 가림막 색 띠가
남는다(템플릿은 쓰지 않음, 미확인). RTL, Firefox, WebKit은 보지 않았다.
문서가 스크롤되면 그 자리의 스크롤바는 전처럼 가림막 밖이다.
--hide-scrollbars로 찍는 compact 골든은 전체 페이지(1377 px)를 찍으므로,
열린 modal 동안 어두워진 root 배경이 창 높이(844 px) 아래의 오른쪽 15 px
띠에도 보인다. 실제 브라우저에서 그 부분은 스크롤바 아래에 있다. compact
골든 1장은 desktop에서 다시 찍었다(test:visual:update). 바뀐 것은 x 375~390
띠가 높이 전체에서 가림막 색이 된 것뿐이다. 나머지 골든 4장은 바뀌지
않았다(body와 root가 같은 색). 레이아웃은 바꾸지 않았다.
검증: desktop batch에서 확인.
corepack pnpm test:visual tests/visual/scrollbar-gutter.visual.spec.ts
corepack pnpm test:visual:update 뒤 corepack pnpm test:visual
node scripts/r5-15-scrollbar.mjs 3 <out.json> (15-R3, 첫 화면 shift 0 유지)
Refs: 1106/08-03
문제: 라우트 로딩 화면(280 px)은 720 px 창에 들고 홈 화면(732 px 문서)은
넘친다. 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 홈이 그려지는
프레임에 세로 스크롤바가 생겨 너비가 15 px 줄고 header 오른쪽(세션 영역)이
15 px 밀린다(1280x720·1366x657에서 CLS 0.0002, 리뷰 15-R2 12회). lab과 모든
게이트의 Playwright Chromium은 --hide-scrollbars로 떠서 이 shift를 못 본다.
고른 방법:
- base.css의 :root에 scrollbar-gutter: stable을 둔다. 스크롤바 자리가
첫 프레임부터 있어 내용이 길어져도 너비가 바뀌지 않는다. overlay
스크롤바(macOS 기본)는 어느 쪽이든 자리를 쓰지 않는다.
- lab(scripts/test-performance.ts)은 labBrowserLaunchOptions()로
--hide-scrollbars를 빼고 띄운다. lab.json context.browser에
scrollbars: "visible"을 남긴다. 이제 lab의 `/` CLS가 같은 회귀를 본다.
- 단위 테스트: 실행 옵션이 --hide-scrollbars를 빼는지, :root에
scrollbar-gutter: stable이 있는지.
- 시각 골든 5장을 새 gutter에 맞춰 desktop에서 다시 찍는다
(test:visual:update).
버린 대안: html { overflow-y: scroll } — 짧은 화면에도 빈 스크롤바를
그린다.
위험·한계: 스크롤바 폭만큼 오른쪽 여백이 짧은 화면에서도 늘 생긴다.
--hide-scrollbars로 뜬 Chromium도 gutter 자리를 잡는다. 그래서 시각 골든
5장이 모두 바뀌었다. 바뀐 것은 내용 폭 15 px다(main 1040 → 1025 px).
compact(390 px) 골든은 줄바꿈이 늘어 1297 → 1377 px로 길어졌다. 실제
휴대폰은 overlay 스크롤바라 자리를 쓰지 않으므로, compact 골든은 휴대폰
화면보다 15 px 좁게 그린다. 열린 drawer의 가림막은 gutter를 덮지 않는다
(일반 스크롤바 브라우저에서는 그 자리에 스크롤바가 그려진다). lab의 CLS 예산
0.1은 그대로라 0.0002 shift가 다시 생겨도 lab은 통과한다(값만 남는다).
Firefox·Windows 스크롤바 폭은 재지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
corepack pnpm test:visual (부모 d5b6aeba에서 6건 통과, 이 변경은 옛
골든과 5건이 달라 실패, 다시 찍은 골든에서 통과)
corepack pnpm build && corepack pnpm test:performance -- --runs=5
Refs: 1105/15-05
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의
제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의
상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서
h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다.
상태 화면 제목을 <p>로 바꾸는 변이(M5)를 잡는 테스트도 없었다.
고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에
headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와
AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서
뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다.
갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다.
상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만
했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목
수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop
계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은
VD-05 재수출 경로를 건드려 이번 범위에서 뺐다.
위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태
h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더
제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언).
검증:
- RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected
[ <h2></h2> ] to have a length of +0 but got 1").
- GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복
통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과,
eslint 통과. e2e accessibility·typography·reference-form·reference-save
chromium 27/27.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05
문제: 스타일·토큰 어디에도 word-break가 없어 브라우저 기본값으로
한국어를 음절마다 끊는다. 골든에 "마운 / 트", "계 / 속할"이 있고, 텍스트
200%에서 로그인 버튼이 "로그 / 인"으로 쪼개졌다. PRODUCT.md의 한국어
기본 원칙과 맞지 않고 모든 파생 서비스가 받는다.
고른 방법: base.css에 :lang(ko) { word-break: keep-all; overflow-wrap:
break-word; }를 둔다. :lang(ko)라 en-US 문서 안의 lang="ko-KR" 구역에도
적용된다. 버린 대안: 리뷰 제안의 overflow-wrap: anywhere — min-content
계산에도 끊을 자리를 더해, 공간이 좁은 flex 항목(헤더 버튼)이 줄어들며
라벨을 다시 쪼갠다. break-word는 넘칠 때만 끊는다. 긴 영문·코드
토큰은 기존 pages.css의 anywhere 두 곳이 그대로 받는다.
위험·한계: 화면이 바뀐다. 좁은 칸에서 줄 수가 늘 수 있다. 시각 골든은
오케스트레이터가 갱신한다. 실제 브라우저 "글자만 확대" 설정에서의
줄바꿈은 눈으로 확인하지 않았다.
검증:
- RED: typography.spec.ts 새 테스트가 수정 전 chromium에서 실패
(wordBreak "normal", overflowWrap "normal").
- GREEN: typography.spec.ts chromium·firefox·webkit 6/6 통과.
accessibility·i18n(320px 가로 넘침 포함)·ui-gallery·app-shell·
responsive·theme·compact-smoke·platform-overview chromium/compact
34/34 통과. check-design-system PASS. 시각 회귀는 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-06
문제: theme.css가 넣는 Tailwind preflight가 제목의 크기·굵기를 본문으로
되돌린다. base.css는 h1 크기와 h2 줄 간격만 정해, 6개 라우트 모두
h2·h3이 16px/400으로 본문과 같았다. 구획을 훑어볼 수 없고, 제품마다
제목 크기를 따로 만들게 된다.
고른 방법: 리뷰의 최소 개선 방향대로 primitive에 --font-size-xl(1.25rem)
·--font-size-2xl(1.5rem)을 더하고, semantic에 제목 단계 토큰
(--font-size-heading-2/3/4, --font-weight-heading = semibold)을 둔 뒤
base.css에서 h2·h3·h4에 적용했다. 컴포넌트 제목(카드 h3, 상태 화면
h2)은 자기 수준의 기본 스타일을 그대로 받는다. 제품은 semantic 토큰
값만 바꿔 단계를 조정한다. 값(24/20/16px, 650)은 1.2배 안팎의 단계로
골랐다. 버린 대안: 컴포넌트마다 크기를 주기 — 같은 값이 여러 곳에
흩어진다. token-contract 필수 목록에 추가 — 다운스트림 토큰 파일이
바로 실패하고, 결과는 아래 e2e가 지킨다.
위험·한계: 화면이 바뀐다. 시각 골든(app-shell, state-surfaces 등)은
오케스트레이터가 갱신한다. 상태 화면이 카드(h3) 안에서 h2로 더 크게
보이는 문제는 08-05가 다룬다. 값 자체는 디자인 결정이라 바꿀 수 있다.
검증:
- RED: 새 tests/e2e/typography.spec.ts가 수정 전 chromium에서 실패
(h2 16px, h3 16px: "Expected: > 16, Received: 16").
- GREEN: 같은 spec chromium·firefox·webkit 3/3 통과. accessibility·i18n·
ui-gallery·app-shell·responsive·theme·design-system-interactions·
compact-smoke + typography chromium/chromium-compact 32/32 통과(별도
playwright 설정, vite preview, pnpm 없이 빌드).
- check-design-system PASS(48 tokens). 시각 회귀는 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-04
문제: 폭 48rem 미만(휴대폰, 1280px 창의 약 170% 이상 확대)에서
responsive.css가 머리글의 색상 테마 선택, 세션 상태, 브랜드를
display: none으로 숨긴다. 메뉴 서랍에는 주요 탐색만 있어서 이 기능과
정보를 쓸 곳이 없다. WCAG 2.2 1.4.10(Reflow)의 "기능·정보 손실 없이"
조건을 어긴다.
고른 방법: 머리글은 지금처럼 두고, 서랍에 브랜드 이름(탐색 위)과 색상
테마 선택·세션 상태(탐색 아래)를 넣는다.
- 테마 선택과 세션 상태를 app-shell.tsx 안의 ThemePreferenceSelect,
SessionStatus로 뽑아 머리글과 서랍이 같은 컴포넌트를 쓴다. 둘 다
기존 ThemeProvider·SessionProvider를 직접 읽어 따로 든 상태가 없다.
- 서랍 쪽 select id는 mobile-theme-preference로 달리 줘서 id가 겹치지
않는다. 머리글 #theme-preference는 그대로다(시각 테스트가 쓴다).
- 서랍 쪽은 라벨을 보이게 두고 theme-selector 클래스를 붙이지 않는다.
그래서 i18n.spec의 "머리글 선택 상자 2개" 검사가 그대로 맞는다.
- 브랜드는 화면을 보고 서랍 위쪽에 링크가 아닌 글자로 넣었다. 서랍에
"홈" 링크가 이미 있어 링크로 두면 같은 곳으로 가는 Tab 정지가 는다.
- 숨김 규칙(responsive.css)과 머리글(app-shell.tsx)에 서랍이 대신
보여 준다는 주석을 달았다.
버린 대안:
- 머리글에 테마 아이콘 메뉴 버튼(리뷰 5.3 (C)): 새 컴포넌트가 필요하고
320px 머리글 공간을 다툰다. 머리글은 단순하게 두기로 정했다.
- 서랍이 열릴 때만 서랍 쪽 컨트롤을 렌더: DOM 중복은 없어지지만 탐색은
항상, 나머지는 조건부로 그리는 이유가 코드에 드러나지 않는다. 탐색이
이미 사이드바와 서랍에 두 벌 있는 방식에 맞췄다.
- 서랍 제목을 앱 이름으로 바꾸기: 대화상자 이름 "메뉴"가 바뀌어 기존
접근성 이름과 테스트가 깨진다.
위험·한계:
- 세션 상태 문구와 테마 select가 DOM에 두 벌 있다. 접근성 트리에는
한 번만 나온다(좁은 폭은 머리글 쪽이 display: none, 넓은 폭은 닫힌
dialog). 다만 페이지 전체에서 getByText로 셸 문구를 찾는 테스트는
strict mode에 걸린다. reference-route.spec의 "인증됨"을 banner로
좁혔다. 다운스트림 테스트도 같은 수정이 필요할 수 있다.
- 640x400(200% 확대)에서는 테마 선택이 서랍 첫 화면 아래에 있어 서랍을
스크롤해야 보인다.
- 좁은 화면 서랍 화면이 바뀐다. 시각 골든
app-shell-compact-pseudo-drawer.png는 이 커밋에서 갱신하지 않았다.
- 초기 JS gzip 203,572 -> 203,648 B(+76 B, 예산 204,800 B). check:bundle은
pnpm을 불러 돌리지 않았고, 같은 분류(classifyViteJavascript)와
gzipSync로 직접 쟀다.
- 실제 기기 터치, 스크린 리더 발표는 확인하지 않았다.
검증:
- RED: tests/e2e/responsive.spec.ts 새 테스트(320·375·640px)가 수정 전
chromium·firefox·webkit 9/9 실패. getByRole('dialog', { name: '메뉴' })
.getByRole('combobox', { name: '색상 테마' }): element(s) not found.
- GREEN: 같은 테스트 9/9 통과. 마지막 탐색 링크에서 Tab으로 테마 선택에
닿고, dark·light 선택에 html[data-theme]이 바뀐다. 서랍에 "로그인 전"과
브랜드가 보인다.
- 회귀 e2e: responsive·i18n·theme·accessibility·app-shell·reference-route
(세 엔진) + compact-smoke(chromium-compact) 85/85 통과. app-shell.spec의
Esc 닫기·포커스 복원·서랍 링크 뒤 h1 포커스 포함. 수정 전에는
reference-route가 세 엔진에서 strict mode로 실패하는 것을 확인했다.
- 열린 서랍 axe(375px, light·dark, 세 엔진) 위반 0(일회성, 커밋 안 함).
- node scripts/run-vitest.ts run tests/component: 211/211 통과.
- tsc(app·test·node) 0, eslint(바꾼 tsx·spec) 0, check-design-system
PASS, check-architecture(pnpm 대신 exec 전용 shim) PASS.
- Playwright는 webServer만 `npx vite preview`로 바꾼 임시 설정으로
돌렸다(빌드는 node scripts/build-frontend.ts).
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-01
문제: .ui-field__input 테두리는 계약 토큰 --field-border 대신
color-mix(in oklab, var(--color-content-muted) 55%, var(--color-panel))
를 직접 쓴다. 제품이 --field-border로 입력란 테두리를 바꿔도 화면이
그대로다. 이 식은 패널 대비 라이트 2.53:1, 다크 2.98:1이라 WCAG
1.4.11이 입력란 경계에 요구하는 3:1보다 낮다. check:design-system은
var(--field-border-invalid) 글자를 --field-border의 독자로 세어 이것을
놓쳤다(검사 수정은 다음 커밋).
고른 방법: 테두리가 var(--field-border)를 읽게 한다. 토큰값은 계약
그대로 --color-border-strong이다.
버린 대안: 토큰값을 지금 계산식으로 바꾸기. 화면은 안 바뀌지만 3:1
미달을 토큰에 굳히고, 다크 테마에서도 계약의 border-strong과 따로
노는 색이 남는다.
위험·한계: 입력란 테두리가 두 테마 모두 진해진다(화면 변경). 시각
골든은 이 커밋에서 갱신하지 않았다. 대비는 계산값이고 브라우저 실측은
하지 않았다.
검증: scripts/lib/oklch-contrast.ts로 --field-border 대비를 계산했다.
- light: panel 6.52, surface 6.24, surface-muted 5.47, elevated 6.52
- dark: panel 4.19, surface 4.54, surface-muted 3.74, elevated 3.90
- 바꾸기 전 식(oklab로 직접 섞은 값): light 2.53, dark 2.98(panel 대비)
node scripts/check-design-system.ts PASS.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-01
max-width 8.5rem과 7rem 때문에 모든 언어에서 선택값이 잘렸다
("Light then", "Englisl", "라이트 테ㅁ"). 커밋된 시각 골든에도 잘린
머리글이 들어 있어, 시각 테스트가 결함을 정답으로 지키고 있었다.
고정 폭을 지웠다. 좁은 화면은 기존 메뉴 서랍 배치가 그대로 맡는다.
새 i18n e2e 테스트가 ko-KR, en-US, en-XA에서 선택 상자 폭을 브라우저가
옵션에 필요한 폭과 비교한다.
위험: 중간 폭에서 머리글이 넓어진다. responsive·app-shell·theme·compact
테스트가 통과했다.
검증: 새 테스트가 고치기 전 실패했고, 고친 뒤 chromium·firefox·webkit
모두 통과했다.
계약에 있는 컴포넌트 토큰 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곳을 보고했고, 바꾼 뒤 통과했다.
A direct link to /page#target stayed at the top: the target renders with the
lazy page, after the router scrolled up. PageHeader now scrolls to it below
the sticky header, focus never scrolls, and POP no longer scrolls to top.
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>