이 시트는 장식용 무드보드가 아니라 발행물을 실제로 구속하는 규약집이다. 한 문장이라도 여기와 코드가 어긋나면 코드가 아니라 이 문서를 먼저 고친다 — 그 뒤 어느 쪽이 정본인지 §B 의 SSOT 표로 판정한다.

세 가지 읽는 법

분석의 깊이(mode: fast · standard · deep)와 직교하는 축이 장르(report_format)다. 사용자 메시지에 "르포" 토큰이 있으면 르포, 없으면 일반 보고서. 두 장르는 가드를 덧댄 관계가 아니라 다른 템플릿 파일로 완전히 분기한다.

나란히 보기

위 스위처의 장르 칩을 눌러 아래 미리보기를 통째로 전환할 수 있다. 색은 그대로 두고 조판만 바뀌는 것을 확인하는 것이 요점이다.

미리보기 · 르포 전용 컴포넌트(.rep-*). 장르 칩을 일반으로 바꾸면 서체가 G마켓 Sans → Newsreader 계열로, 모서리가 0 → 둥근 값으로 돌아간다.

테마는 스킨이 아니라 계약이다. 모든 테마가 같은 이름의 토큰 20여 개를 반드시 채운다. 그래서 컴포넌트 CSS 는 색을 한 번도 직접 쓰지 않고 var(--accent) 만 부르며, 테마를 늘려도 컴포넌트는 손대지 않는다. 보고서마다 random.choice 로 테마가 바뀌어도 레이아웃이 흔들리지 않는 이유다.

2.1 토큰 사전

토큰은 다섯 층이다. 위층이 아래층을 부르되 역방향은 없다.

2.2 21종 팔레트

아래 카드는 실제 토큰 값으로 칠했다. AA/AAA 배지는 그 테마의 --muted(가장 약한 글자)와 --bg 의 대비를 브라우저에서 지금 계산한 것이다 — 명목이 아니라 실측이다.

르포 전용 이름 (색은 위 8종과 동일, 조판만 다름)

같은 색을 reportage_ 접두로 부르면 플랫 지오메트리 + G마켓 Sans 가 함께 붙는다. 접두가 없으면 붙지 않는다. 이 접두 하나가 두 장르의 경계다.

2.3 액센트 규율

미리보기 · 큰 숫자는 전부 --fg-1. 상승·하락 여부는 숫자 자체가 말하므로 색을 더할 이유가 없다.

서체는 셋이 아니라 세 개의 역할이다. 역할이 먼저 있고 서체는 거기 배정될 뿐이라, 장르가 바뀌면 서체가 통째로 갈려도 화면의 논리는 그대로다.

3.1 폰트 스택

3.2 타입 스케일

아래 각 행은 실제 선언값으로 렌더된다. 값은 freeform_essay.html / reportage.html 의 인라인 스타일이 정본.

미리보기 · 모바일(≤640px)에서는 headline 34→26, heading 24→20, prose 15.5→15 / 1.78 로 내려간다. 본문 하한은 15px — 그 아래로는 어떤 이유로도 내리지 않는다.

3.3 한글 조판 — 반드시 세 줄이 함께

양끝 정렬은 한글에서 특히 위험하다. 아래 세 선언이 한 세트로 붙지 않으면 반드시 깨진다. 새 줄글 블록을 만들 때마다 셋을 함께 복사한다.

.any-prose{
  text-align: justify;      /* ① 양끝을 맞춰 오른쪽 끝단을 단정하게 */
  text-justify: auto;
  text-align-last: left;    /* ② 마지막 줄은 늘리지 않는다 — justify 의 전형적 결함 차단 */
  word-break: keep-all;     /* ③ 한글은 어절 단위로만 줄바꿈 (단어 중간 절단 금지) */
  overflow-wrap: break-word;/* ④ 긴 URL·영문 토큰이 컨테이너를 넘지 않게 */
}

문단 — <br><br> 가 아니라 진짜 <p>

v8.5.7 이전에는 렌더러가 <br><br> 만 내보내서 CSS 의 문단 규칙과 드롭캡이 통째로 죽어 있었다. 지금은 세 단계로 문단을 보장한다.

미리보기 · 드롭캡 + 들여쓰기 예외 + strong(fg-1) · em(accent, 기울이지 않음) 처리. 강조 어휘는 두 개뿐이다.

이 시스템에 다단 조판은 없다. 본문은 언제나 한 열이고, 차트·지도·사진도 같은 열 폭을 꽉 채운다. 본문만 좁히면 데스크탑에서 오른쪽 끝단이 시각물보다 안쪽에서 꺾여 화면이 어긋나 보이기 때문이다(v8.2.15 회귀).

4.1 폭과 여백

4.2 반응형 — 세 개의 분기점

모바일 우선이 아니라 데스크탑 기준 + 축소다. 보고서는 링크로 공유되어 절반 이상 모바일에서 열리지만, 도표의 정보 밀도는 넓은 화면을 기준으로 설계하고 좁은 화면에서 줄이는 편이 판독성이 낫다.

4.3 격자 — minmax(0, 1fr) 규칙

라벨 칸은 min-height: 2.6em 으로 두 줄 높이를 미리 예약한다. 한 줄 라벨과 두 줄 라벨이 섞여도 큰 숫자의 세로 시작선이 모든 칸에서 일치한다.

4.4 지오메트리와 깊이

비유 박스·각주 박스처럼 본문에서 살짝 떨어져 나온 블록은 좌측만 굵은 선을 두고 border-radius: 0 6px 6px 0 을 준다. 왼쪽이 각지고 오른쪽이 둥근 이 비대칭이 "본문에 붙어 있되 별개" 라는 관계를 만든다.

미리보기 · 비유 박스(좌측 4px accent)와 각주 박스(좌측 3px border-soft). 같은 형상, 다른 무게 — 굵기와 색만으로 위계를 만든다.

편집 컴포넌트는 많을수록 좋은 게 아니다. 한 보고서에서 인용 박스가 다섯 개면 어느 것도 인용으로 읽히지 않는다. 그래서 이 카탈로그의 핵심 열은 권장 빈도다.

5.1 머리 — hero · 목차 · 출발점

미리보기 · hero 는 네 줄 고정 — eyebrow(액센트) / headline(세리프 900) / deck(300 웨이트) / meta(가운뎃점 구분). 버전은 eyebrow 뒤에 모노로 따라붙는다.

5.2 본문 블록 — 인용과 사진

미리보기 · 인용은 배경 없이 좌우 2px 룰만 쓴다. 배경 + 둥근 모서리 + 좌측 굵은 선의 "AI 인용 박스" 룩은 v5.8.1 에서 폐기했다. 캡션은 세리프 이탤릭, 크레딧만 산세리프로 톤다운.

5.3 도표 카드 — 여섯 개의 슬롯

차트 카드는 그림 한 장이 아니라 여섯 칸짜리 문서다. 순서가 고정이라 어느 보고서를 열어도 눈이 같은 자리를 찾는다.

미리보기 · 무대(stage) 안의 도표는 이 페이지에서 실제 렌더러 대신 같은 어휘로 손으로 그린 SVG 다. 어휘 자체는 §06 참조.

5.4 맺음 — 쟁점 · 시간 · 감시 신호

미리보기 · 쟁점은 박스가 아니라 문단으로 쓴다. 강조는 전환점(accent) · 근거(fg-3) · 판단(fg-1 굵게) 세 단뿐. 시간 레일은 미래 구간만 점선 + 빈 점 — 투사와 사실을 시각적으로 구분하기 위해서다.

5.5 상태 — 열화 배너

생성이 끝까지 완료되지 못한 보고서는 정상처럼 보이면 안 된다. 절단본을 무경고로 발행한 사고 이후, 열화 플래그가 서면 헤더 바로 아래 배너가 뜨고 텔레그램 알림에도 같은 경고가 붙는다.

미리보기 · 이 배너만은 테마 액센트를 쓰지 않고 고정 경보색(#c0392b)을 쓴다. 테마에 따라 경고가 눈에 안 띄는 일이 없어야 하기 때문이다.

도표는 테마 하나에 맞춰 칠할 수 없다. 크림색 종이에서도, 자정 남색에서도, 진홍 마룬에서도 같은 그림이 읽혀야 한다. 그래서 이 시스템은 색상(hue)으로 카테고리를 나누지 않는다. 구분은 패턴이, 위계는 잉크 농도가 맡는다.

6.1 패턴 — 45° 한 방향만

6.2 잉크 농도 사다리 — 위계에는 패턴을 쓰지 않는다

6.3 선 어휘 — 관계는 dash 로 말한다

값 라벨은 Newsreader 세리프로 대상 옆에 직접 붙인다(막대 끝 · 조각 중앙 · 기둥 위). 범례는 직접 라벨이 물리적으로 불가능할 때만 만든다 — 범례는 시선을 도표와 범례 사이로 왕복시키는 비용이 있다.

6.4 차트 27종

작성 모델이 데이터를 보고 직접 {type, title, data, note} 를 내보낸다. 별도 빌더가 없으므로 데이터가 비면 차트도 없다. 왼쪽 색 띠는 검증 등급이다 — ■ safe 는 기본 가드만, ■ guarded 는 도표 비평 + 시각 정합 게이트를 통과해야 발행된다. ■ 주입 은 작성 모델이 고를 수 없는 타입이다 — 데이터가 있을 때 코드가 결정적으로 꽂거나(브리핑 전용) 특정 장르에만 나온다.

6.5 지도

베이스맵은 d3-geo + world-atlas 110m TopoJSON 한 번 받아 캐시한다. 외부 타일 서비스와 글리프 PBF 호출은 금지 — 비트맵 타일은 모노 리스타일이 불가능하고 패턴 오버레이와 색이 충돌한다.

이 시스템의 애니메이션은 장식이 아니라 읽는 순서를 지시하는 문법이다. 그래서 규칙이 넷뿐이고, 넷 다 어기면 회귀로 잡는다.

르포 전용 주변 모션

아래는 문체 규약이지만 결과는 화면에 직접 나타난다. 조판이 아무리 좋아도 본문에 **굵게** 가 날것으로 박히면 그 페이지는 무너진다.

8.1 기호 금지 — 사용자 최우선 규칙

8.2 평이화 어휘표 (발췌)

세 곳이 항상 정합해야 한다 — 문체 가이드의 어휘표, 작성 프롬프트의 평이화 예시, 발행본 핫픽스 도구의 치환 매핑. 새 매핑을 쓰면 세 곳에 함께 넣는다.

바꿀 수 없는 핵심 용어만 본문에 남기고, 그 섹션 하단 용어 풀이로 내린다. 이 두 단계가 §00 의 제1원칙을 화면에서 실행하는 방식이다.

8.3 시점 앵커링

이 시스템에서 가장 자주 깨지는 것은 코드가 아니라 정합이다. 한 곳만 고치고 짝을 안 고치면 몇 주 뒤 이유를 모르는 회귀로 돌아온다. 아래는 그 짝 목록이다.

10.1 새 테마 추가

1. report.css 에 [data-theme="이름"] 블록 — 토큰 20칸 전부. 빈 칸은 라이트 테마를 상속해 다크에 크림색이 튄다.
2. 지도 3색(--map-water / --map-land / --map-boundary)을 잊지 않는다. 이게 빠져서 다크 테마 지도가 크림색으로 나온 전례가 있다.
3. 테마 풀 상수에 이름 추가 (일반 풀 / 르포 풀 중 어디인지 결정).
4. --muted vs --bg 대비를 4.5 이상으로 확인. 미달이면 색조 유지 + 명도만 상향.
5. 이 시트를 다시 생성해 팔레트 카드와 부록 A 를 갱신.

10.2 새 차트 종류 추가

1. 렌더러 등록 (charts.js 의 RENDERERS)
2. 작성 프롬프트에 데이터 스키마 섹션 추가
3. 검증 가드 추가 (schemas.py 의 타입→가드 매핑) — 그리고 validate_chart_data 분기도 반드시. 분기 누락으로 새 타입이 100% 조용히 버려진 사고가 있었다
4. 시각 역량 레지스트리 등록 (safe / guarded / experimental)
5. 사용량 기록의 알려진 타입 목록에 추가
6. 회귀 시나리오 추가 (타입 목록과 1:1)
7. 회귀 테스트 · 갤러리 샘플 갱신

10.3 새 컴포넌트 추가

1. 가장 가까운 이웃 컴포넌트를 찾아 그 여백·서체·테두리 어휘를 물려받는다. 새 어휘를 만들지 않는다.
2. 줄글이 들어가면 §3.3 의 네 줄 세트를 함께 붙인다.
3. 색은 토큰으로만. 하드코딩된 hex 가 하나라도 있으면 20개 테마에서 깨진다.
4. 권장 빈도를 정한다. 빈도 없는 컴포넌트는 반드시 남용된다.
5. 두 장르 중 어디에 렌더할지 결정. 르포는 기본이 "미렌더" 다.
6. 이 시트 §05 에 미리보기 + 빈도 행 추가.

10.4 발행 전 점검

이 시스템의 문서 규율은 하나다 — 같은 사실을 두 곳에 적지 않는다. 한쪽은 반드시 링크가 된다. 아래 표에서 "정본" 열이 그 한 곳이다.

이 시트를 다시 만드는 법

팔레트와 부록 A 는 report.css 를 파싱해 채웠다. 추출기는 저장소에 들어 있으므로, 테마를 추가·수정했다면 다시 돌려 THEMES 상수만 갈아끼우면 된다. 손으로 hex 를 옮기는 순간 이 문서는 신뢰를 잃는다.

# 저장소 루트에서
python3 scripts/extract_theme_tokens.py > /tmp/themes.json

# 하는 일
# 1. report.css 에서 주석 제거 → [data-theme="X"] { … } 블록 수집
#    (:root 는 editorial_cream 으로 취급, 셀렉터가 여러 테마를 겹쳐 잡으면 각각에 배분)
# 2. 각 블록의 --key: value 를 dict 로
# 3. var(--other) 참조는 같은 테마 안에서 끝까지 재귀 해석
# 4. 선언되지 않은 키는 :root 폴백으로 채우고 _inherited 에 이름을 남김
# 5. JSON 덤프 → 이 페이지의 THEMES 상수로 주입

지금 이 문서의 THEMES 는 위 명령의 출력과 완전히 일치하는 상태로 생성됐다. 불일치가 생겼다면 둘 중 하나가 낡은 것이고, 정본은 언제나 report.css 다.