# Font Build

> 폰트 빌드·릴리스 스킬. SVG 글리프를 fontTools로 컴파일해 설치 가능한 TTF 폰트 파일을 생성 — 번들 스크립트(build_font.py), manifest 규약, macOS 호환 name 테이블 규칙, 라이선스 임베드, 빌드 전 검증, fonts/ 릴리스·GitHub 배포 절차 포함. 폰트 빌드, TTF/OTF 생성, 폰트 파일 만들기, 폰트 설치 테스트, 버전 올리기, 폰트 배포/릴리스, fonts 폴더 갱신, 깃헙 업로드 요청 시 반드시 이 스킬을 사용할 것.

- Skill: `revfactory/font-build` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add revfactory/font-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/revfactory/font-build/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: revfactory (https://skillmd.com/u/revfactory)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/revfactory/font-build

---


# 폰트 빌드 파이프라인

SVG 글리프 → TTF 컴파일은 반드시 번들 스크립트로 수행한다. 매번 새 스크립트를 작성하면 y축 변환·메트릭 처리가 미묘하게 달라져 라운드 간 비교가 오염된다.

## 사전 조건

- fontTools 필요: `python3 -c "import fontTools"` 실패 시 `pip3 install --user fonttools`
- 입력 SVG는 glyph-design 스킬 규약 준수 (viewBox 0 0 1000 1000, 최상위 path만, stroke 금지, 베이스라인 y=880)

## manifest 규약

빌드 입력은 SVG 디렉토리가 아니라 manifest다. 각 글리프 디렉토리에 `manifest.json`:

```json
{
  "glyphs": {
    "한": "han.svg",
    "A": { "file": "A.svg", "advance": 620 }
  }
}
```

- 키는 반드시 1글자. 경로는 manifest 위치 기준 상대 경로
- `advance` 생략 시 1000 (한글 전각). 라틴·부호는 반드시 advance 명시

## 빌드 절차

1. **빌드 전 검증** (위반 글리프는 제작자에게 반환):
```bash
grep -l 'stroke' _workspace/glyphs/{콘셉트}/**/*.svg   # 결과가 있으면 규약 위반
```
2. **컴파일**:
```bash
python3 .claude/skills/font-build/scripts/build_font.py \
  --manifest _workspace/glyphs/{콘셉트}/generated/manifest.json \
  --family "Cheonjiin" --family-ko "천지인" --version 0.{N} \
  --out _workspace/build/Cheonjiin-v0.{N}.ttf
```
   - **`--family`는 반드시 ASCII.** 이유: PostScript명(nameID 6)은 ASCII만 허용되고, 비ASCII 기본 이름은 macOS Font Book이 "서체 이름 없음"으로 설치를 거부한다 (v0.4에서 실제 발생). 한국어 표시명은 `--family-ko`로 — 로컬라이즈 레코드(0x0412)에 들어가 한국어 환경에서는 한글 이름으로 표시된다
   - 라이선스(SIL OFL 1.1)·저작권 name 레코드는 스크립트가 자동 임베드한다
3. **산출물 검증**:
```bash
python3 -m fontTools.ttx -l _workspace/build/{파일}.ttf   # 테이블 목록 확인
```
   - 글리프 수가 manifest 합계 +1(.notdef)인지 확인
   - 스크립트가 출력한 실패 목록이 비어 있는지 확인 — 실패 글리프는 빈 글리프로 대체되므로 방치하면 투명 글자가 된다
4. **설치 안내**: macOS는 `open _workspace/build/{파일}.ttf` → Font Book에서 설치. 사용자에게 경로를 알려준다

## 버전 규칙

- 라운드와 동기화: round-3 시안 → v0.3
- 이전 빌드를 덮어쓰지 않는다 — `_workspace/build/`에 버전별 보존 (회귀 비교용)

## 알려진 함정

- **stroke로 그린 획은 컴파일 시 소실된다** — 빌드 전 검증이 이를 잡는다
- 카운터(ㅇ 속공간)가 채워져 나오면 안팎 윤곽 방향이 같은 것이다 — 글리프 수정 필요 (fill-rule은 폰트에 없다)
- transform 속성·중첩 그룹은 무시될 수 있다 — 규약대로 최상위 path만
- 3차 베지어(C)는 스크립트가 cu2qu로 자동 변환한다 (TrueType glyf는 2차만 허용) — 별도 처리 불필요
- 비ASCII `--family`는 macOS 설치 오류를 낳는다 — 스크립트가 경고를 출력하니 무시하지 말 것

## 릴리스 절차 (사용자가 배포·업로드를 요청할 때)

1. 최신 버전 TTF를 `fonts/`에 복사한다 — `fonts/`는 배포 폴더로 **최신 릴리스 1개만 유지** (구버전은 `_workspace/build/`와 git 이력에 보존)
2. README.md 갱신: 설치 경로의 파일명, 버전 표에 변경 내용 한 줄 추가
3. CLAUDE.md 변경 이력에 기록
4. 커밋(메시지는 한글) 후 `git push` — 저장소: github.com/revfactory/font-harness (public, OFL 1.1)
5. 라이선스 변경 시 OFL.txt와 스크립트의 name 테이블 문자열을 함께 갱신한다