Oaty 타이포그래피 시스템

1. 개요

Oaty의 타이포그래피 시스템은 본문 읽기 경험과 서비스 UI 경험을 분리해 관리한다. 글 본문, 고정 페이지 본문, About markdown, 관리자 본문 에디터는 장문 독서에 맞춘 .prose 기준을 따른다. 반면 내비게이션, 카드, 검색, 관리자 패널 UI, 글 제목 영역은 별도의 UI 타이포그래피 기준을 유지한다.

이 문서는 현재 프로젝트의 공식 타이포그래피 기준을 정의한다. 기준은 웹 표준의 의미 구조, CSS 표준, WCAG 접근성 원칙, Google Search Central의 검색 친화적 HTML 원칙을 따른다.

2. 설계 목표

Oaty의 본문 타이포그래피는 다음 목표를 갖는다.

한국어 장문을 안정적으로 읽을 수 있는 기본 본문 크기와 줄간격을 제공한다.
공개 렌더링과 관리자 에디터의 본문 리듬을 일치시킨다.
HTML의 의미 구조는 유지하고, CSS는 시각 표현만 담당한다.
rem, em, semantic token, container query를 사용해 브라우저 확대 설정과 다양한 컨테이너 폭에 대응한다.
검색엔진과 보조 기술이 문서 구조를 이해할 수 있도록 h1, h2, h3 계층을 보존한다.

3. 타이포그래피 계층

Oaty의 타이포그래피는 4계층으로 구분한다.

전역 UI 타이포그래피
body, 내비게이션, 카드, 검색, 관리자 패널 UI가 사용하는 기본 인터페이스 글자 체계다. 장문 본문 기준과 분리한다.
공개 본문 .prose
게시글 본문, 고정 페이지 본문, About markdown, 시리즈 본문에 적용되는 장문 독서 기준이다.
관리자 에디터 본문
Milkdown/ProseMirror 기반 글 에디터와 고정 페이지 에디터는 공개 .prose와 같은 본문 기준을 사용한다.
미리보기와 FAQ 보조 영역
글/페이지 로컬 미리보기와 FAQ H2는 공개 본문 계층과 같은 기준을 따른다. FAQ 카드 내부 질문·답변 텍스트는 보조 UI로 별도 리듬을 유지한다.

4. 본문 기준값

Oaty의 장문 본문 기준은 다음과 같다.

항목	데스크톱/기본	좁은 컨테이너
본문	17px / 1.65	17px / 1.65
H2	30px / 1.4	26px / 1.35
H3	23px / 1.45	21px / 1.4
문단 간격	1em	1em
H2 하단 간격	24px	20px
H3 하단 간격	16px	14px
H2 섹션 상단 간격	48px	48px

본문 크기는 CSS상 1.0625rem으로 구현한다. 이는 기본 브라우저 글꼴 크기 16px 기준 17px에 해당하며, 사용자의 브라우저 확대 및 기본 글꼴 크기 설정과 함께 확장된다. 줄간격은 단위 없는 값 1.65를 사용한다. 단위 없는 line-height는 상속과 확대 환경에서 예측 가능하게 동작한다.

5. 적용 범위

다음 영역은 본문 타이포그래피 기준을 따른다.

게시글 본문
고정 페이지 본문
About markdown 영역
시리즈 본문
관리자 글 에디터의 ProseMirror 본문
관리자 고정 페이지 에디터의 ProseMirror 본문
글/페이지 로컬 미리보기 본문
공개 글과 로컬 미리보기의 FAQ H2

다음 영역은 본문 기준으로 강제하지 않는다.

전역 body
헤더와 내비게이션
카드 목록과 archive UI
검색 다이얼로그
관리자 사이드바와 폼 UI
글 제목, 페이지 제목, 설명문, 날짜, 태그 칩
에디터 툴바, 버튼, 입력 필드, 상태 표시 UI

이 분리는 의도된 구조다. 전역 body를 장문 본문 기준으로 바꾸면 관리자 UI, 카드 밀도, 검색 UI, 내비게이션의 균형이 함께 변하므로 금지한다.

6. 반응형/좁은 컨테이너 기준

Oaty는 본문 반응형 기준을 viewport만으로 판단하지 않는다. 본문 컨테이너의 폭을 기준으로 H2/H3 크기를 낮춘다. 따라서 같은 모바일 화면이라도 실제 본문 컨테이너 폭이 충분하면 본문 리듬은 안정적으로 유지된다.

좁은 컨테이너에서도 본문은 17px을 유지한다. 모바일에서 본문을 더 줄이지 않는 이유는 한국어 장문 가독성과 접근성 때문이다. 대신 H2와 H3만 축소해 제목 줄바꿈, 문단 밀도, 화면 내 정보량의 균형을 맞춘다.

7. 관리자 에디터 기준

관리자 글 에디터와 고정 페이지 에디터는 공개 본문과 같은 본문 기준을 사용한다. 작성자가 에디터에서 보는 문단, H2, H3, 목록, 코드, 표, 이미지의 리듬은 공개 렌더링과 최대한 일치해야 한다.

Milkdown/ProseMirror 목록은 브라우저 기본 리스트와 다른 커스텀 라벨 구조를 사용할 수 있다. 따라서 번호, 불릿, 체크박스 라벨의 높이는 본문 줄간격 기준에 맞춰 정렬한다. 본문 줄간격이 바뀌어도 목록 라벨이 첫 줄 중심에서 어긋나지 않아야 한다.

8. SEO와 접근성 원칙

Oaty의 타이포그래피는 HTML 의미 구조를 변경하지 않는다.

h1은 글 또는 페이지의 대표 제목에 사용한다.
본문 섹션은 h2를 기준으로 나눈다.
세부 항목은 h3를 사용한다.
TOC는 H2/H3를 추적한다.
CSS는 시각적 크기와 간격을 조정하지만, 제목 계층 자체를 바꾸지 않는다.

WHATWG HTML 표준은 heading이 문서 outline과 목차 생성에 사용될 수 있음을 설명한다. Google Search Central도 검색엔진이 페이지를 이해할 수 있도록 semantic HTML과 DOM에 접근 가능한 텍스트를 사용할 것을 권장한다. 따라서 Oaty의 본문 디자인은 “시각적으로 예쁜 제목”보다 “구조적으로 올바른 제목”을 우선한다.

줄간격은 WCAG의 텍스트 간격 원칙을 고려해 본문 기본값을 1.65로 둔다. 이 값은 장문 문단에서 1.5 이상의 줄간격을 확보하며, 사용자가 브라우저나 보조 도구로 텍스트 간격을 늘려도 콘텐츠가 잘리거나 겹치지 않도록 레이아웃을 유연하게 유지해야 한다.

9. 한국어 줄바꿈 기준

본문은 한국어 문장이 불필요하게 음절 단위로 끊기지 않도록 word-break: keep-all을 사용한다. 동시에 긴 URL, 긴 영문 단어, 코드 조각이 컨테이너를 넘치지 않도록 overflow-wrap: anywhere를 함께 사용한다. line-break: strict는 CJK 문장부호와 줄바꿈 품질을 안정화하기 위한 기준이다.

이 조합의 목적은 다음과 같다.

한국어 문장은 가능한 자연스러운 어절 단위로 유지한다.
긴 비한국어 문자열은 레이아웃을 깨지 않도록 예외적으로 줄바꿈을 허용한다.
제목과 문단이 모바일에서 겹치거나 부모 영역을 넘치지 않게 한다.

10. 미디어, 표, 코드, 목록 기준

이미지는 본문 흐름에서 독립된 블록으로 취급한다. 이미지 주변에는 충분한 block 여백을 두고, 본문 폭을 넘지 않아야 한다. 긴 글의 성능을 위해 본문 섹션과 이미지에는 content-visibility와 intrinsic size 추정값을 사용할 수 있다. 이때 콘텐츠는 DOM에서 사라지는 것이 아니며, 의미 구조와 검색 접근성을 해치지 않아야 한다.

표는 좁은 화면에서 본문 폭을 깨지 않도록 래퍼를 통해 가로 스크롤을 허용한다. 코드블록은 본문 줄간격과 별도 리듬을 사용하며, 긴 줄은 가로 스크롤로 처리한다. 인라인 코드는 본문 흐름을 방해하지 않도록 em 기반 크기를 사용한다.

목록은 문단과 같은 본문 크기와 줄간격을 사용한다. 중첩 목록은 들여쓰기와 리스트 마커 체계를 단계적으로 구분한다.

11. 예외와 금지사항

다음 변경은 금지한다.

전역 body를 본문 기준으로 강제 변경하지 않는다.
본문 작성자가 H1을 반복 사용하지 않는다.
공개 본문과 관리자 에디터 본문 기준을 다르게 만들지 않는다.
본문 H2/H3 크기를 개별 페이지에서 임의 px 값으로 덮어쓰지 않는다.
문단 간격을 고정 px로 흩뿌리지 않는다.
제목 크기를 키우기 위해 HTML heading level을 바꾸지 않는다.
줄바꿈 문제를 해결하기 위해 word-break: break-all을 본문 전체에 적용하지 않는다.
표, 코드, 긴 URL 때문에 본문 컨테이너가 가로로 밀려나게 두지 않는다.

12. 점검 체크리스트

배포 전 다음 항목을 확인한다.

본문 문단이 17px / 1.65 기준으로 보이는가?
공개 본문과 관리자 에디터의 H2/H3 크기와 간격이 일치하는가?
H2는 본문 섹션의 시작으로 충분히 구분되는가?
H3는 H2보다 작지만 세부 제목으로 명확한가?
모바일 또는 좁은 컨테이너에서 H2는 26px, H3는 21px 기준으로 전환되는가?
본문 안에 불필요한 H1이 없는가?
TOC가 H2/H3를 정상적으로 추적하는가?
긴 URL, 영문 단어, 코드 조각이 본문 폭을 깨지 않는가?
목록 번호, 불릿, 체크박스가 첫 줄 기준으로 정렬되는가?
표와 코드블록이 모바일에서 가로 overflow를 안전하게 처리하는가?
이미지 주변 여백이 문단 리듬을 해치지 않는가?
관리자 UI, 카드, 검색, 내비게이션 글자 크기가 본문 개편 때문에 변하지 않았는가?