[ARCHIVED 2026-08-19] 역사 자료 — 현행 규범이 아니다. 아카이브 사유와 대체 문서는 docs/README.md의 Archive 섹션을 참조.

Desktop Scroll Ownership Handoff

목적

Claude Design 프리뷰와 실제 배포 환경의 렌더링 차이를 흡수하면서 다음 계약을 유지한다.

문서와 데스크톱 앱 외곽에는 상하좌우 스크롤이 없다.
화면의 주요 카드, 헤더, 요약 영역은 한 뷰포트 안에 유지된다.
데이터가 넘칠 때는 명시된 콘텐츠 컬럼만 독립적으로 세로 스크롤한다.
가로 스크롤은 문서, 카드, 컬럼 어디에서도 생기지 않는다.

프리뷰는 기준 캔버스 1913x1063을 직접 렌더링한다. 실제 앱은 브라우저 뷰포트와 호스트의 runtime zoom을 함께 사용하므로 프리뷰만으로 배포 크기를 보장할 수 없다.

확인된 배포 차이

루트 캔버스

기존 호스트는 높이에만 맞춰 확대했다. 1920x1080에서는 확대된 캔버스 폭이 약 1943.6px이 되어 뷰포트보다 약 24px 넓어진다.

Codex 호스트는 다음 contain 규칙을 사용한다.

const zoom = Math.min(
  viewportWidth / 1913,
  viewportHeight / 1063,
);

훈련 리포트

배포 화면 실측에서 훈련 리포트 외곽 스크롤 컨테이너는 약 950px 높이에 약 974px 콘텐츠를 가지고 있었다. 이 상태에서는 컬럼이 아니라 카드 전체가 약 24px 세로 스크롤된다.

Codex 소유 범위

Codex는 이 handoff의 scroll layout·CSS·시각 구성을 수정하지 않는다. props, events, controller 연결 같은 디자인 불변의 기능 배선은 docs/process/claude-free-design-contract.md의 R&R에 따라 Codex가 소유한다.

대상:

src/react/vite/desktopRoot.tsx
src/react/vite/app-host.css
호스트 동작을 고정하는 테스트
이 역할 분담 문서

책임:

기준 캔버스를 현재 뷰포트 안에 contain한다.
호스트 자체는 확대된 캔버스 폭이 아닌 뷰포트 크기를 유지한다.
캔버스를 호스트 중앙에 배치한다.
document root와 앱 호스트의 외곽 overflow를 차단한다.
모바일 전환점인 900px 이상에서는 항상 1913x1063 기준 캔버스를 유지한다.
900px 이상 데스크톱에서는 뷰포트 폭과 높이 중 더 제한적인 축에 맞춰 캔버스 전체를 확대하거나 축소한다.
900px 미만에서만 별도의 모바일 UI로 전환한다.
resize와 브라우저 배율 변경 시 확대율을 다시 계산한다.

Claude Design 소유 범위

대상:

src/react/ui/desktop/**
각 화면의 card, grid, column presentation
훈련 리포트의 스크롤 소유권

기능 요구사항:

훈련 리포트 외곽과 전체 카드는 스크롤되지 않는다.
히어로와 요약 영역은 고정한다.
데이터 grid는 고정 영역을 제외한 남은 높이를 사용하고 축소 가능해야 한다.
데이터가 넘치는 각 컬럼만 독립적으로 세로 스크롤한다.
지정된 세로 스크롤 영역은 가로 overflow를 차단한다.
한 컬럼 안에 불필요한 중첩 스크롤을 만들지 않는다.
데이터 없음, 로딩, 긴 이름, 많은 기록에서도 외곽 카드 크기는 변하지 않는다.

DOM 구조, 클래스 구성, 레이아웃, 시각 표현은 Claude Design이 결정한다. Codex가 특정 presentation 구현을 강제하지 않는다.

권장 통합 순서

Codex 호스트 변경을 먼저 반영한다.
Claude Design은 최신 기준 브랜치에서 UI 스크롤 소유권을 수정한다.
독립 프리뷰뿐 아니라 실제 Vite 앱 호스트에 연결해 검증한다.
배포 후 document와 지정 컬럼의 scroll metrics를 다시 확인한다.

검증 매트릭스

뷰포트:

1366x768
1920x1080
2560x1440

브라우저 배율:

90%
100%
110%

데이터 상태:

빈 상태
일반 데이터
각 컬럼의 콘텐츠가 화면 높이를 넘는 상태
긴 종목명과 긴 보조 문구
로딩 오버레이 표시 상태

완료 조건

document root의 scrollWidth와 clientWidth가 같다.
document root의 scrollHeight와 clientHeight가 같다.
데스크톱 호스트와 외곽 카드에서 휠 또는 트랙패드 스크롤이 발생하지 않는다.
데이터가 넘치는 지정 컬럼 위에서만 세로 스크롤이 작동한다.
모든 화면 레벨에서 가로 스크롤이 없다.
900px 이상 모든 데스크톱 폭에서 동일한 1913x1063 내부 레이아웃이 유지된다.
900px 미만에서만 모바일 UI가 렌더링된다.

Desktop Scroll Ownership Handoff ​

목적 ​

확인된 배포 차이 ​

루트 캔버스 ​

훈련 리포트 ​

Codex 소유 범위 ​

Claude Design 소유 범위 ​

권장 통합 순서 ​

검증 매트릭스 ​

완료 조건 ​