cdesiles/design-doc

문서

문서는 순차적으로 읽히고 종이에 인쇄됩니다. 이 두 가지 사실은 레이아웃을 제약합니다: 단일 텍스트 폭, 실제 페이지 나눔, 호버에 의존하는 요소는 없습니다.

먼저 페이지 매김 방식 결정

• 흐름형(Flowing) (기본값) — 하나의 연속적인 텍스트 흐름; 브라우저의 인쇄 엔진이 페이지를 나눕니다. 보고서, 메모, 편지, 에세이 등 길이가 고정되지 않은 문서에 적합합니다.
• 고정 페이지(Fixed pages) — 명시적인 <section class="page"> 블록, 각각 한 장씩. 페이지 수가 디자인의 일부일 때 적합합니다: 한 페이지 이력서, 양면 전단지, 증명서, 포스터.

사용자가 "두 페이지"를 요청했다면 고정 페이지를 의미합니다. "보고서"를 요청했다면 흐름형을 의미합니다. 명확하지 않은 경우 물어보세요 — 잘못된 방식을 선택하면 문서 전체가 낭비됩니다.

기하학

토큰 파일을 <head>에 연결하고, 문서가 구성 요소를 사용하는 경우 components.css도 함께 연결하세요. 그리고 색상, 글꼴, 간격에 해당 변수를 사용하세요. 아래 규칙은 종이 기하학에만 해당합니다:

@page { size: A4; margin: 0; }        /* 또는: size: letter; */
body  { margin: 0; background: white; }
.page { width: 210mm; min-height: 297mm; padding: 24mm 22mm; box-sizing: border-box; }
.page + .page { break-before: page; }

@media screen {
  body { background: gainsboro; padding: 32px 0; }
  .page { margin: 0 auto 24px; box-shadow: 0 2px 24px color-mix(in srgb, black 12%, transparent); }
}

흐름형 문서의 경우 고정된 .page를 제거하고 @page { margin: 22mm }와 max-width: 66ch 열을 설정하세요. 용지 크기는 사용자가 미국인이 아니면 A4, 미국인이면 Letter를 사용하세요. 사용자가 크기를 지정했다면 그 크기를 사용하세요.

타이포그래피

• 본문 11–12pt, 줄 간격 1.5–1.6. 읽어야 하는 내용은 절대 10.5pt 미만으로 설정하지 마세요.
• 측정값 60–75자. 그 이상이면 눈이 줄을 놓칩니다.
• 본문용 글꼴 하나, 제목용 글꼴 하나(선택 사항). 디자인 시스템이 있다면 동일한 짝을 사용하세요.
• 제목은 크기 체계에 따라 지정하며, 최상위 제목은 눈에 띄게 크게(28–36pt) 설정해야 합니다. 14pt 굵기는 안 됩니다.
• 강조는 굵기와 공백을 사용하고, 색상만으로 강조하지 마세요. 흑백으로 인쇄되는 문서도 여전히 읽을 수 있어야 합니다.

구조

• 실제 시맨틱 요소 사용: h1–h3, p, ul, table, figure, blockquote. 스타일이 적용된 div는 사용하지 마세요.
• 페이지 번호는 문서가 두 페이지를 넘을 경우 @page 카운터를 사용하세요:

  @page { @bottom-center { content: counter(page); } }
  

  지원이 불완전합니다 — 각 고정 페이지에 각주 스타일 번호를 넣는 것이 안정적인 대안입니다.
• 표: 숫자는 오른쪽 정렬, 텍스트는 왼쪽 정렬, 전체 테두리 대신 얇은 선 사용, thead { display: table-header-group }으로 페이지 나눔 시 머리글 반복.
• 페이지의 1/3보다 긴 요소에는 break-inside: avoid를 사용하지 마세요.
• 그림에는 캡션을 추가하세요. 캡션이 없으면 그림도 없습니다.

내용

사용자의 단어를 유지하세요. 요청 시 잘라내거나 순서를 바꿀 수 있지만, 의역해서는 안 됩니다. 사용자가 작성하지 않아 섹션이 비어 있는 경우, 내용을 지어내지 말고 명확하게 표시된 빈 공간을 남겨두세요.

스톡 사진이나 장식용으로만 생성된 이미지는 사용하지 마세요. 문서에 실제 이미지가 필요한 경우 FLUX 도구를 사용할 수 있으면 사용하고, 그렇지 않으면 모노스페이스 글꼴로 메모를 남긴 자리 표시자 상자를 사용하여 무엇이 들어가야 하는지 표시하세요.

마무리

인쇄 너비로 design-verify를 실행하고 스크린샷을 확인하세요:

node ~/.config/opencode/lib/design/verify.mjs "design/Report.html" \
  --width 900 --height 1200 --full --out design/.verify/report.png

다음 사항을 확인하세요: 페이지 가장자리에서 텍스트 잘림, 페이지 하단에 고립된 제목, 표가 잘못 나뉘는 현상, 가로 오버플로(인쇄 시 오른쪽 가장자리에서 내용이 사라짐).

그런 다음 직접 한 번 PDF로 인쇄(Cmd-P, PDF로 저장)하여 페이지 수와 실제 용지 크기에서 아무것도 이동하지 않는지 확인하세요.