Commit Graph
21 Commits
Author SHA1 Message Date
DongHyeonka 91b3aaac46 test(visual): 시각 골든의 색 허용치를 0.05로 좁힌다
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m14s
frontend-quality-gates / merge / tests (pull_request) Successful in 16m3s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m32s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
시각 골든은 `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
2026-11-13 23:27:47 +09:00
DongHyeonka 2f3ebba46b test(storybook): 배럴의 모든 화면 컴포넌트에 story를 두고 저장 상태를 골든에 넣는다
디자인 시스템 배럴(`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
2026-11-13 23:27:47 +09:00
DongHyeonka d5083f862d fix(home): 홈이 StandardPage와 LinkButton을 쓴다
홈(`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
2026-11-13 23:27:47 +09:00
DongHyeonka 838ed410f7 fix(styles): 스타일이 간격·글자·층·그림자 토큰을 읽고 검사가 날 값을 거절한다
셸·페이지 템플릿·카드 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
2026-11-13 23:27:47 +09:00
DongHyeonka ceafab6638 test(visual): 첫 화면 route heading의 포커스 링을 시각 골든에 담는다
이 PR은 route heading의 outline 제거를 `:focus`에서
`:focus:not(:focus-visible)`로 좁혔다(1112/05-02). PageHeader는 전부터 첫
로드에도 heading에 포커스를 준다. Chromium은 포인터 조작 전의 프로그램
포커스를 :focus-visible로 보므로, 이제 첫 화면 heading에 포커스 링이 보인다.
그래서 FE-GATE-008의 시각 골든 넷(앱 셸 wide, 갤러리 dark, 상태 화면, 플랫폼
구성)이 heading 자리에서만 달라졌다(diff 이미지로 확인).

고른 방법: 첫 로드 포커스 동작은 그대로 두고 골든 넷을 test:visual:update로
다시 찍는다. 포커스가 있는 곳에 표시가 보이는 것이 2.4.7이 요구하는 것이고,
전에 안 보였던 것이 이 결함이었다. 버린 대안: 첫 로드에는 heading에 포커스를
주지 않기(라우트 포커스 동작이 바뀌는 일이라 이 PR 범위 밖이다).

위험·한계: base.css·templates.css를 받은 제품은 자기 시각 골든도 다시 찍어야
한다(round9 CHANGELOG에 적는다).

검증: 다시 찍은 골든으로 test:visual 7 passed(desktop). 바뀐 파일은 이 넷뿐이다.

Refs: 1112/05-02
2026-11-13 03:53:27 +09:00
DongHyeonka c7e80f2f8a test(visual): 갤러리를 Storybook story로 옮기고 골든 대상을 바꾼다
예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).

두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.

위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.

검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
2026-11-08 13:51:54 +09:00
DongHyeonka 7625dc4548 fix(theme): 열린 modal의 가림막이 스크롤바 자리까지 덮게 한다
문제: :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
2026-11-06 07:24:02 +09:00
DongHyeonka e02f252d57 fix(theme): 스크롤바 자리를 첫 화면부터 잡고 lab을 스크롤바와 함께 잰다
문제: 라우트 로딩 화면(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
2026-11-06 01:23:48 +09:00
DongHyeonka 0a6ff6e5ed test(visual): 시각 골든에서 설치된 기능의 링크와 목록을 뺀다
문제
merge 게이트 test:visual(FE-GATE-008)의 셸 전체 페이지, 좁은 서랍,
플랫폼 구성 스크린샷이 설치된 기능의 내비게이션 링크와 목록을 같이
찍었다. create:feature로 기능 하나를 더하면 세 장이 실패했고(185 px,
3,106 px, 이미지 높이 3814 -> 3964), 통과시키려면 템플릿 소유 PNG를
고정 글꼴 환경에서 다시 찍어야 했다.

고른 방법 (결정 D3 (a), 영역 밖 요소만 찍기)
- 스크린샷 직전에 style 태그로 설치된 기능이 정하는 부분을
  display: none으로 뺀다. mask는 목록이 길어지면 높이가 바뀌어 같은
  실패를 낸다.
  - 셸·홈: 기능 라우트로 가는 링크 전부(내비게이션은 li째). 목록은
    ROUTE_REGISTRY·ROUTE_FEATURE_OWNER에서 만들어서 기능을 더해도 spec을
    고치지 않는다. 09-04 뒤로 UI·상태·인증 예제 링크도 기능 링크라 같이
    빠진다.
  - 플랫폼 구성: 설치 요약, 라우트 표, 계약·오퍼레이션 표, 제품 기능
    절. 릴리스 신원의 계약 집합 다이제스트 값은 visibility: hidden(생성
    기능의 계약 패키지가 바꾼다). 서버 상태 표(DataTable)·실행 상한·능력
    카드·나머지 릴리스 신원은 남긴다.
- 15-01 뒤로 계약 표가 나중에 채워지므로 로딩이 끝난 뒤 찍는다.
- 골든 3장을 고정 글꼴 환경(tests/visual/fonts.conf, visual-fonts 통과)
  에서 한 번 다시 찍었다. 갤러리·상태 2장은 바뀌지 않았다.
- 버린 대안: 고정 fixture 제품으로 따로 빌드(빌드 경로가 하나 늘어남),
  골든을 제품 소유로 선언(동기화마다 PNG 충돌).

위험·한계
- 링크 목록·기능 표의 모양 회귀는 시각 검사 밖이 된다. 개수와 순서는
  component·e2e 테스트가 본다.
- 셸 골든에는 플랫폼 링크("홈", "플랫폼 구성")와 홈 화면의 "플랫폼 구성
  보기" 버튼만 남는다.

검증
heavy lock 안, 같은 worktree(.tmp/r1103/visual.sh), 부하 5.7~8.6:
- test:visual:update로 3장만 바뀜(셸 넓은 화면·좁은 서랍·플랫폼 구성).
- 깨끗한 상태 6/6 통과.
- create:feature probe-feature(새 context) 뒤 6/6 통과.
- probe-two·three·four(같은 context)를 더해 기능 4개에서 6/6 통과.
  생성 파일은 지웠다.
- 변이: shell.css .app-navigation__link padding 0.75rem -> 0.5rem.
  넓은 셸 847 px, 좁은 서랍 4,207 px 차이로 2건 실패. 되돌렸다.
- 다이제스트를 가리기 전 첫 시도에서는 기능 1개·4개 모두 플랫폼 구성이
  710·636 px로 실패했다(원인 확인 뒤 위 규칙 추가).
- eslint, check:types:test, check:test-evidence:source 통과(mask 전체
  가림 규칙에 걸리지 않음).

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-01
2026-11-04 22:59:03 +09:00
DongHyeonka b0195e3d59 ci(visual): 브라우저 설치 단계가 시각 테스트 글꼴 패키지를 설치한다
문제
tests/visual/fonts.conf는 Noto Sans·Noto Sans CJK·Liberation Mono가
있는 OS 글꼴 디렉터리만 읽는다. 생성 workflow의 브라우저 설치 단계는
`playwright install --with-deps` 한 줄이고, Playwright 의존 패키지에는
이 글꼴이 없다. 그래서 빈 러너에서는 FE-GATE-008이 코드와 무관하게
`visual-fonts` 단계에서 실패한다(1101/11-02의 남은 절반).

고른 방법
- 생성기(scripts/generate-ci-workflow.ts)의 browser-install 단계가
  `--with-deps` 뒤에 글꼴 패키지 4개를 apt-get으로 설치한다.
  `--with-deps`가 이미 패키지 목록을 갱신했으므로 update를 다시 하지
  않는다. root가 아닌 러너에서만 sudo를 붙인다.
- 패키지 목록을 scripts/lib/visual-test-fonts.ts 한 곳에 두고 생성기와
  tests/visual/fonts.setup.ts의 설치 안내가 같이 읽는다.
- 글꼴이 필요한 것은 FE-GATE-008뿐이지만 브라우저 단계 두 곳 모두에
  넣었다. 게이트 ID로 갈라 쓰면 생성기가 게이트 목록에 묶인다.
- 버린 대안: job container 고정(러너의 컨테이너 지원 미확인),
  ci:gate가 패키지 설치(개발자 PC에서도 sudo 요구).

위험·한계
- 실제 러너나 깨끗한 Ubuntu 24.04 컨테이너에서 이 단계를 돌리지
  않았다. 패키지 이름과 디렉터리는 이 호스트(Ubuntu)와 fonts.conf로만
  확인했다.
- CJK 패키지 때문에 브라우저 job 설치 시간이 수십 MB만큼 는다.
- gates.json은 바꾸지 않았다(단계 종류는 그대로 browser-install).

검증
- ci-workflow-generation 새 테스트: 생성기 수정 전 실패, 수정 뒤 통과.
  파일 전체 424건 통과(스냅샷 1건 갱신).
- generate:ci-workflow로 workflow 재생성. check:ci PASS.
- lint, check:types:node, check:types:test, verify:documentation PASS.

Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-02
2026-11-04 20:18:40 +09:00
DongHyeonka 373b27b09c test(visual): 야간 수정 뒤 시각 골든 5장을 고정 글꼴로 다시 찍는다
입력란 테두리 토큰(12-01), 좁은 화면 서랍(08-01), 제목 단계 크기(08-04),
한국어 단어 단위 줄바꿈(08-06)이 화면을 바꿨다. 허용치를 절대 50 px로
줄인 뒤(11-03) 기존 골든 5장이 모두 달랐다.

fonts.conf로 글꼴을 고정한 상태(11-02)에서 test:visual:update로 다시 찍고
눈으로 확인했다. 서랍에 브랜드·테마 선택·세션 상태가 보이고, 상태 화면
제목이 굵어지고, 한국어가 단어 사이에서만 줄바꿈된다.

위험: 이 호스트의 Noto·Noto CJK·Liberation 패키지 버전으로 찍었다.
검증: test:visual 6 passed(글꼴 검사 포함).
2026-11-01 23:24:00 +09:00
DongHyeonka 08b5ccc86e test(visual): 시각 테스트 글꼴을 fonts.conf로 고정하고 먼저 검사한다 (11-02)
시각 골든은 작성자 PC가 고른 글꼴 4종(Noto Sans, Noto Sans CJK KR
Regular·Black, Liberation Mono)으로 찍혀 있는데, 설정은 글꼴을 고정하지
않는다. 같은 dist에서 FONTCONFIG_FILE만 Playwright가 맨 Ubuntu에 까는
글꼴 구성으로 바꿔도 5장이 모두 실패한다. 실패는 화면 전체가 밀린 pixel
diff라서 원인이 글꼴이라는 것을 알기 어렵다. CI 러너도 같은 처지다.

고른 방법 (리뷰 4.1절 c′, 사용자 결정):
- tests/visual/fonts.conf가 Debian/Ubuntu 경로의 세 디렉터리
  (truetype/noto, opentype/noto, truetype/liberation)만 보이게 한다.
  playwright.visual.config.ts가 use.launchOptions.env로 그 파일을
  FONTCONFIG_FILE에 넣는다. 바깥 FONTCONFIG_FILE은 덮어쓴다. CI
  workflow는 바꾸지 않았다.
- 같은 파일에서 래스터 설정(antialias, hintslight, rgb, lcddefault,
  autohint 끔)을 호스트 규칙 뒤에 고정한다. 글꼴 이름이 같아도 hint와
  sub-pixel 기본값이 다른 호스트에서는 5장이 모두 실패했다(검증 참고).
- visual-fonts setup 프로젝트(tests/visual/fonts.setup.ts)를
  chromium-visual의 의존으로 둔다. 실제 앱 페이지에 탐침 요소를 넣고
  CDP CSS.getPlatformFontsForNode로 실제로 그려진 글꼴을 비교한다.
  다르면 설치할 패키지 이름과 함께 실패하고, 스크린샷 테스트는 돌지
  않는다. 글꼴이 하나도 없으면 렌더러가 죽으므로 그 경우도 같은 안내로
  감싼다. test:visual:update도 같은 검사를 먼저 거친다.

버린 대안:
- fc-match 사전 검사: fontconfig CLI가 러너에 있다는 보장이 없고,
  Chromium이 실제로 고르는 글꼴과 다를 수 있다. 앱 페이지의 code는
  Liberation Mono인데, lang 없는 빈 페이지에서는 Noto Mono가 잡혔다.
  그래서 탐침도 앱 페이지 안에 넣는다.
- document.fonts.check: 시스템 글꼴은 없어도 true를 돌려준다.
- /etc/fonts/conf.d를 빼고 별칭 규칙을 직접 쓰기: system-ui와
  Courier New(Chromium 기본 monospace) 해석을 다시 만들어야 한다.
  리뷰 실험 D(호스트 규칙 포함, 5/5)에서 벗어난다.
- 컨테이너 이미지, 글꼴 파일 커밋, 임계값 완화: 리뷰 4.1절에서 기각.

위험·한계:
- 바이트가 아니라 패키지 이름을 고정한다. 배포판이 글꼴 버전을 바꾸면
  이름 검사는 통과하고 pixel diff로 실패할 수 있다.
- generic family 별칭(sans-serif → Noto Sans, Courier New → Liberation
  Mono)은 호스트의 /etc/fonts/conf.d를 따른다. 별칭이 다른 호스트
  (예: Noto Sans를 우선하지 않는 fontconfig 2.14 미만)에서는
  visual-fonts가 실패한다. 조용히 다른 글꼴로 바뀌지는 않는다.
- 사용자 fontconfig(50-user.conf)가 디렉터리를 더하면 그 글꼴도
  보인다. 탐침 4종이 바뀌면 검사가 잡는다.
- Linux 전용이다. macOS와 Windows의 Chromium은 fontconfig를 읽지 않는다.
- 실제 Gitea 러너에서는 돌려 보지 못했다(U-1). CI에 apt 설치 단계를
  넣지 않았고, 필요한 패키지는 테스트 전략 문서 13.4절에 적었다.
- 골든은 다시 찍지 않았다.

검증 (같은 dist, flock, `npx playwright test --config
playwright.visual.config.ts`. pnpm을 부르지 않으려고 webServer만
vite preview로 바꾼 로컬 사본으로 실행):
- 수정 전, 바깥 FONTCONFIG_FILE=A(Playwright Ubuntu 글꼴 + DejaVu):
  5 failed, toHaveScreenshot diff(46,356 px, 4%)
- 검사만 넣고 같은 A: 1 failed, 5 did not run. 설치 안내와 함께
  latin=DejaVu Sans, korean=WenQuanYi Zen Hei
- RED, fonts.conf가 빈 디렉터리만 볼 때: 1 failed, 5 did not run.
  같은 설치 안내 + "The font probe page did not render"
- GREEN, 호스트 환경: 6 passed. 바깥 A: 6 passed(기존 골든 5/5)
- 러너 근사(호스트 conf.d에서 language-selector, ubuntulegacy,
  sub-pixel-rgb 제외): 6 passed
- 다른 래스터 기본값(hinting-full, sub-pixel-none): 고정 블록 없이
  5 failed(setup만 통과, diff 2%), 고정 블록 포함 6 passed
- tsc(app·node·test), eslint, check-test-evidence --source-only PASS,
  verify-documentation-readiness PASS_SCOPED, vitest supply-chain과
  tests/architecture 53 passed

Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-02, 4.1절
2026-11-01 21:00:06 +09:00
DongHyeonka c0c5d9c7de test(visual): UI 감사 수정 뒤 시각 골든을 다시 찍는다 (UI-01~06)
예전 앱 셸 골든에는 잘린 선택 상자(UI-04)와 분홍 현재 메뉴(UI-02)가
들어 있었다.

test:visual:update로 5장을 다시 찍고 눈으로 확인했다. 선택값이 다
보이고, 현재 메뉴가 파랗고, 예제 머리글의 반복 라벨이 없다.

위험: 이 Linux 호스트의 글꼴로 찍었다. 시각 테스트 실행 환경의 글꼴
고정은 UI-05의 남은 절반이다.
검증: test:visual 5건 통과.
2026-11-01 18:34:28 +09:00
donghyeon-kaandClaude Opus 5.5 2dc1b3af6d test(visual): refresh the state surface and platform overview baselines (08-08, 08-13)
Both screens changed on purpose. 08-08 (dbe6b76) adds scroll-padding-top
for the sticky header, so the element screenshot of main no longer has
the header drawn over its top edge. 08-13 (d7b81c6) moves the reference
detail route under items/, and the longer path wraps one more line in
the overview's route table. The rest of both images is unchanged; at
4626b73 the old baselines still pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 01:22:30 +09:00
DongHyeonkaandClaude Opus 5.5 f17572a4be test(a11y): scan the rendered route, signed in and per state (08-05, 11-02)
axe ran as soon as `main` showed, which is the app shell's loading surface,
and protected routes were scanned on the sign-in prompt. The specs now wait
for the route's h1, sign in first, and scan the reference list, detail, form
and status states. The state-surfaces baseline was the loading surface.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:25:46 +09:00
DongHyeonkaandClaude Opus 5.5 861383283c test(visual): refresh the pseudo-locale home baseline (08-04)
The home page copy now comes from the catalog, so en-XA pseudo-localizes it
and the compact drawer screenshot grows from 1128 to 1263 px.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:23:02 +09:00
DongHyeonkaandClaude Opus 5 711d61e73f feat: make product features a declared selection with a runtime kill switch
Which features a build contains was not a decision anybody could express. The
reference feature was spread directly into the route, API, schema, codec and
adapter registries, so shipping without it meant editing five files by hand and
hoping nothing still referred to it — and there was no way at all to take it out
of service on a running deployment. The removability gate proved the editing
worked; nothing made it a choice.

There is now one manifest. `VITE_PRODUCT_FEATURES` narrows it at build time and
`FEATURE_OVERRIDES` in the runtime document takes an installed feature out of
service without a rebuild. Every registry composes from the manifest, and a test
fails if a new one forgets to.

Both inputs are subtractive, and the vocabulary is what enforces it rather than
a check somewhere downstream: the override enum has no `ENABLED`, and a
build-time selection naming something the source tree does not declare is
refused instead of ignored. A configuration document that could name a feature
into existence would be a configuration document choosing which code runs.

Disabling is not just hiding. Withdrawing a route from navigation would leave a
typed deep link that still mounts the feature, so the router refuses it too and
answers with a surface that says the deployment switched it off. The platform
overview now distinguishes the three states an operator actually needs: serving,
switched off, and not in this build.

What this is not: an env var does not shrink the bundle. A static import cannot
be undone by a value, and making the import graph itself depend on a
configuration string is the thing §3.5 exists to prevent — measured, `none`
changes the output by 58 bytes. Physical removal remains FE-GATE-020's job, and
the code comments say so rather than implying otherwise.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 20:45:19 +09:00
DongHyeonkaandClaude Opus 5 7485cd86e4 fix: let the browser, visual and performance evidence describe the product again
Four browser-capability specs never reached the code they were named for. The
`PRESIGNED_TRANSFER_V1` envelope gained a top-level `protocol` field, and the
fixtures kept answering without it, so every capability was refused before any
object request was made: the download and part-upload success paths were
asserting against an empty transcript rather than exercising a real GET or PUT.
The fixtures now speak the protocol they claim to, and the part-deletion
expectation carries the physical effect the adapter reports.

A refused capability document also answered `recovery: NONE`, telling the
caller there was nothing to be done. The design record fixes this class of
refusal as re-issuable and the vault already answers `REISSUE_CAPABILITY` for
it, so the HTTP decoder disagreed with both. It now agrees.

Lab performance produced no evidence at all. Playwright matches accessible
names by substring, so the navigation entry "플랫폼 구성" also matched the home
page's "플랫폼 구성 보기" call to action; the locator resolved to two links and
the run died on a strict-mode violation before the first measurement. With an
exact match the metrics are collected, and they show the named-interaction
budget is missed on this machine — a real signal that was previously invisible.

The platform overview baseline was captured before the reference routes moved
from `integration-defined` to `session-required` and was never regenerated, so
the only visual gate that could catch a regression on that page was failing for
its own staleness. Regenerated after confirming the diff is exactly that label.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 16:49:48 +09:00
DongHyeonka c6da03369c refactor: 리펙토링 2026-08-01 19:39:59 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00
donghyeon-ka 98d4fd4960 feat: harden test and registry evidence 2026-07-26 17:15:26 +09:00