문서 / docs/superpowers/specs/2026-08-18-self-hosted-typefaces-design.md

서체 적재 설계

선언만 하고 적재하지 않던 서체를 자가호스팅으로 실제로 적재한 설계.

작성일: 2026-08-18 상태: 사용자 승인(IBM Plex Sans 폐기, Pretendard·JetBrains Mono 자가호스팅, 등폭은 라틴 전용)

배경

라이브 사이트를 계측하니 폰트 네트워크 요청이 0건이고 document.fonts가 비어 있다. CSS는 IBM Plex SansNoto Sans KR → system, JetBrains Mono → system을 선언하지만 @font-facenext/font도 폰트 자산도 없다. 방문자 PC에 그 서체가 설치돼 있을 때만 적용되고, 아니면 OS 기본 서체로 떨어진다 — Windows는 맑은 고딕, macOS는 애플 SD 산돌고딕, Linux·Android는 Noto. 같은 화면이 사람마다 다른 서체로 보인다.

기준문서와도 어긋난다. design-system/5240lab-harness/MASTER.md는 이렇게 적고 있다.

Fonts are loaded with next/font or self-hosted assets so core content does not depend on third-party font requests.

이것이 그냥 미관 문제가 아닌 이유는, 이 저장소가 08-15부터 08-17까지 제목 스케일을 세 번 손보고 heading-scale·heading-lines 테스트까지 붙였기 때문이다. 글자꼴이 방문자마다 다르면 그 수치의 전제가 매번 달라져서, 그 작업이 무엇을 보장하는지 말할 수 없게 된다.

결정

1. IBM Plex Sans를 버린다

한글 글리프가 없다. 이 사이트 본문의 대부분이 한글이므로, 제대로 적재해도 실제로 보이는 글자에는 거의 적용되지 않는다. 그런데 스택 첫머리에 있어서 "우리 서체는 IBM Plex Sans"라는 착각을 만든다 — MASTER.md도 그렇게 적고 있다. 적재되지 않은 라틴 전용 서체가 한국어 사이트의 대표 서체로 기준문서에 박혀 있는 것이 지금 상태의 핵심이다.

2. 본문은 Pretendard Variable을 자가호스팅한다

한국어 화면용 서체의 사실상 기본값이고 라틴 글자꼴도 함께 갖고 있어 한 벌로 본문 전체를 감당한다. 가변 폰트라 이 사이트가 쓰는 400·600·700을 파일 하나로 덮는다.

배포 형태는 동적 서브셋을 쓴다. 후보를 셋 재보았다.

형태 저장소 브라우저가 받는 양
가변 전체 1파일 2.0MB 2.0MB 통째로
정적 서브셋(KS X 1001) 2벌 0.5MB 0.5MB 통째로, 굵기마다 별도
가변 동적 서브셋 92파일 3.1MB 화면에 실제로 쓰인 유니코드 범위만

동적 서브셋은 unicode-range로 92조각을 갈라 두어 브라우저가 그 화면에 필요한 조각만 받는다. 저장소가 제일 무겁지만 그 비용은 한 번이고, 방문자가 치르는 비용은 가장 작다. 공개 사이트에서는 뒤쪽이 더 중요하다.

next/font가 아니라 직접 @font-face를 쓰는 이유는 조각마다 unicode-range가 달라야 하는데 next/font/local이 그것을 표현하지 못하기 때문이다. 자산은 public/fonts/ 아래 저장소에 함께 두므로 빌드 시점 네트워크에도, 서드파티 요청에도 의존하지 않는다 — 기준문서가 요구하는 조건을 그대로 만족한다.

3. 등폭은 JetBrains Mono, 라틴 전용으로 적재한다

경로·명령·릴리스 ID·plan.md 같은 파일명이 이 사이트의 "기술" 표기이고 그 정체성이 등폭에 있다. 라틴 400·600 두 벌이면 되고 각 21KB라 비용이 거의 없다.

4. 등폭 스택의 한글 대체를 Pretendard로 못 박는다

--font-mono: "JetBrains Mono", "Pretendard Variable", …monospace

글꼴 대체는 글자 단위로 일어나므로, 라틴은 JetBrains Mono가, 한글은 Pretendard가 그린다. .technical-label에 이미 한글이 여럿 들어가 있고(통과 조건, 읽는 것, 권장 문서 · 사용자가 씁니다) 지금은 등폭에 한글 글리프가 없어 OS 서체로 다시 떨어진 뒤 자간만 남아 성기게 보인다. 마크업을 건드리지 않고 이 스택 한 줄로 닫는다.

애초에 한글에는 등폭 서체라는 것이 사실상 없으므로, 등폭 스택에 비례 서체를 대체로 두는 것은 편법이 아니라 그 자리의 정답이다.

검증

  • document.fonts에 Pretendard Variable과 JetBrains Mono가 실제로 적재됐음을 브라우저 테스트로 확인한다. 지금은 이 값이 0이므로 그 자체가 회귀 방지선이 된다.
  • 적재 전후 전송량을 실측해 보고한다.
  • 기존 heading-scale·heading-lines가 계속 통과해야 한다 — 글자꼴이 바뀌면 줄바꿈이 달라질 수 있고, 그것이 바로 이 작업이 고정하려는 대상이다.

매뉴얼 영향

manual-impact: affectedMASTER.md의 Typography 절을 고친다(대표 서체 교체, 적재 방식 명시). 공개 경로 다섯은 불변이다.