docs: define TechLog content width alignment

2026-08-17 16:34:45 +09:00
parent 47cbf4ddca
commit 72669949bc
1 changed files with 54 additions and 0 deletions
@@ -0,0 +1,54 @@
+# TechLog 본문·콘텐츠 자료 너비 정렬 설계
+
+## 상태
+
+- 승인일: 2026-08-17
+- 우선순위: Decision 작성 기능보다 먼저 적용
+- 결정: 코드 블록, 데이터 표, SVG·이미지 evidence를 본문과 같은 `42rem` 너비에 맞춘다.
+
+## 문제
+
+Public 문서 본문은 `--body-copy: 42rem`이지만 코드 블록과 데이터 표는 최대 `58rem`, evidence figure는 최대 `61rem`으로 가운데 돌출된다. 이 때문에 본문 문장과 자료의 좌우 경계가 달라지고 문서를 읽을 때 시선축이 흔들린다.
+
+## 선택한 접근
+
+본문의 읽기 너비는 유지하고 자료 쪽을 본문 너비에 맞춘다.
+
+- `.code-block`, `.data-table-wrap`, `.evidence-figure`의 기본 너비를 `min(var(--body-copy), 100%)`로 통일한다.
+- 세 요소의 좌우 중앙 정렬은 일반 `margin-inline: auto`로 표현하고, 폭을 넓히기 위한 `50%` 이동과 `translateX`를 제거한다.
+- 긴 코드는 기존처럼 `pre` 내부에서 가로 스크롤한다.
+- 넓은 표는 기존처럼 wrapper 내부에서 가로 스크롤한다.
+- SVG·이미지는 비율을 유지해 컨테이너 너비에 맞추고 기존 확대 dialog를 유지한다.
+- 작은 화면에서는 세 자료가 계속 `width: 100%`를 사용한다.
+
+본문 자체를 `58rem` 이상으로 넓히는 접근은 긴 문장의 가독성을 바꾸므로 사용하지 않는다. 코드·이미지만 계속 돌출시키는 접근도 이번 문제를 유지하므로 사용하지 않는다.
+
+## 범위
+
+다음 표면에 동일하게 적용한다.
+
+- Case 공개 문서
+- Studio 즉시 미리보기
+- 저장·검증된 Public preview
+- 게시 snapshot preview
+- 공유 Public renderer를 사용하는 모든 코드, 표, evidence figure
+
+다음은 이번 변경에 포함하지 않는다.
+
+- 본문 글꼴, 행간, `--body-copy` 값 변경
+- 이미지 업로드와 evidence catalog 자동 등록
+- TOC 위치와 문서 전체 shell 너비 변경
+- Decision 작성 기능
+
+## 반응형·접근성
+
+- 데스크톱에서 본문과 자료의 좌우 경계가 같아야 한다.
+- 모바일에서는 viewport를 넘지 않아야 한다.
+- 코드와 표의 가로 스크롤 가능성을 유지한다.
+- evidence 확대 버튼과 keyboard focus 동작을 유지한다.
+
+## 검증
+
+먼저 style contract에 본문, 코드, 표, evidence figure의 계산된 너비 규칙이 모두 `min(var(--body-copy), 100%)`인지 확인하는 실패 테스트를 추가한다. 그 후 최소 CSS 변경으로 통과시킨다.
+
+공유 renderer 회귀 테스트로 코드의 `pre` overflow, 표 wrapper overflow, evidence 확대 control이 그대로 존재하는지 확인한다. 마지막으로 Case 문서를 데스크톱과 모바일에서 확인해 자료가 본문 경계와 정렬되고 viewport overflow가 없는지 검증한다.