doc-figure

---
name: doc-figure
description: "제안서·공문서·사업기획안·보고서에 들어가는 삽도(도식)를 스타일 고정 그림으로 만드는 스킬. 문서를 주면 어디에 어떤 그림이 필요한지 짚어 제안하고, 말로 지시하면 바로 한 장 그린다. 템플릿 11종(일정도·간트·프로세스·판정 흐름·구성도·계층 스택·추진체계도·논증 도해·비교표·히트맵·레인 매핑)과 프리셋 3벌(공공 네이비·공문서 무채색·기획안 강조)로 렌더하며, 한글 라벨·수치·정렬은 코드가 그려 글자 깨짐이 구조적으로 불가능하다. 삽도·삽화·도식·도해·인포그래픽·개념도·구조도·일정도·추진체계도·조직도·흐름도·다이어그램·비교표 그림을 그리거나, 문서의 그림 자리를 채우거나, 그림을 수정·재렌더·스타일 변경할 때 반드시 사용. 외부 API 키 불필요. ※ 본문 표 조판이나 사진풍 자유 일러스트에는 쓰지 않는다 — 정밀 도식 전용."
---

# doc-figure — 문서 삽도 만들기

문서에 넣을 **도식**을 스타일이 고정된 그림으로 만든다. 한글 라벨·수치·격자 정렬은 전부 코드가 그리므로 글자가 깨질 수 없다.

## 산출 3경로

| 경로 | 언제 | 설치 | 산출 |
|---|---|---|---|
| **기본** | 대부분 | 없음 | 자기완결 HTML → 브라우저로 열어 인쇄·캡처 |
| **정밀** | 여러 장을 반복해 뽑을 때 | 크롬 + 파이썬 | PNG 자동 + 텍스트 검증 |
| **자유형** | 도식이 아닌 삽화가 필요할 때 | 없음 | 이미지 모델용 프롬프트 규격문 |

**기본 경로를 먼저 쓴다.** 정밀 경로는 크롬이 있고 여러 장을 자동으로 뽑을 때만 쓴다.

## 진입 2경로

### 경로 1 — 문서를 받았을 때

1. 본문을 읽고 **삽도 후보표**를 만든다. 각 후보에 위치·유형·템플릿·근거를 적는다.

   | # | 들어갈 위치 | 무엇을 보이나 | 템플릿 | 왜 필요한가 |
   |---|---|---|---|---|
   | 1 | Ⅱ장 추진체계 | 총괄–부문–자문 관계 | `org-chart` | 서술만으로는 책임 소재가 안 보임 |

2. **사용자 승인을 받는다.** 승인된 것만 그린다. 문서에 있지도 않은 내용을 그림으로 지어내지 않는다.
3. 승인분마다 spec을 쓰고 렌더한다.

### 경로 2 — 말로 지시받았을 때

"추진체계도 그려줘, 총괄은 A, 부문은 B·C·D" → 템플릿 고르고 spec 쓰고 바로 1장. 승인 게이트 없이 진행한다.

정보가 모자라면 **비워두지 말고 물어본다.** 도식은 빈칸이 그대로 드러난다.

## 기본 경로 — HTML 만들기 (설치 0)

템플릿은 마커 3개를 치환하면 그대로 완성된 HTML이 된다.

1. `templates/<템플릿>.html` 을 읽는다
2. `presets/<프리셋>.css` 를 읽는다 (기본 `gov-navy`)
3. 세 곳을 치환한다
   - `/*__STYLE_TOKENS__*/` → 프리셋 CSS 전문
   - `/*__FIGURE_DATA__*/ null` → spec JSON 전문
   - `/*__ICONS__*/ {}` → **그대로 둔다** (아이콘 미탑재)
4. `그림_NN_<이름>.html` 로 저장하고, 브라우저로 열어 인쇄(PDF)하거나 캡처하라고 안내한다

spec JSON도 `그림_NN_<이름>.json` 으로 **반드시 함께 남긴다.** "부문 하나 추가"가 재작성이 아니라 한 줄 수정이 되는 이유다.

## 정밀 경로 — PNG 자동 생성 (선택)

```bash
python3 scripts/render_figure.py <spec.json> -o <out.png> --verify
python3 scripts/render_figure.py <spec.json> --preset mono-formal -o <out.png>
python3 scripts/render_figure.py --list          # 템플릿·프리셋 목록
```

`--verify` 는 spec의 모든 텍스트가 렌더 결과 DOM에 실재하는지 대조한다. 통과해야 확정한다.

**단, `--verify` 통과가 "그림이 멀쩡하다"는 뜻은 아니다.** 텍스트가 존재하는지만 보므로 라벨끼리 겹치거나 캔버스 밖으로 밀린 것은 잡지 못한다. **결과 이미지를 반드시 눈으로 확인한다.**

## 템플릿 11종

| 계열 | 템플릿 | 쓰임 |
|---|---|---|
| 일정 | `timeline-gantt` | 간트 + 게이트 + 마일스톤 + 도넛 KPI |
| | `timeline-tracks` | 다중 트랙 연표 (제도축·사업축 대응) |
| 흐름 | `flow-process` | 단계→단계 프로세스 + 게이트 |
| | `decision-flow` | 게이트 판정 + 탈락 분기 + 원칙 그리드 |
| 구조 | `structure-block` | 계층 밴드 + 셀 박스 |
| | `layer-stack` | 상·하 2단 스택 + 구분선 + 추진 밴드 |
| | `org-chart` | 총괄→부문 트리 + 자문 |
| 논증 | `concept-argument` | 중심 개념 + 좌우 지지 근거 |
| 비교 | `comparison-matrix` | 헤더 + 행 비교표 |
| | `matrix-heatmap` | 3단 히트맵 + 그룹 밴드 + 범례 |
| | `pipe-mapping` | 레인–세그먼트 병목 매핑 |

필드 명세는 [references/template-schemas.md](references/template-schemas.md), 문서 유형별 추천 세트는 [references/doc-type-map.md](references/doc-type-map.md). 실물 spec은 `examples/`.

어느 템플릿에도 딱 안 맞으면 **가장 가까운 것에 재구성하고 그 사실을 보고한다.** 새 템플릿을 즉석에서 만들지 않는다.

## 프리셋 3벌

| 프리셋 | 대상 |
|---|---|
| `gov-navy` (기본) | 제안서·연구보고서 |
| `mono-formal` | 공문서·내부 보고 (흑백 인쇄·팩스 대응) |
| `accent-plan` | 사업기획안·민간 제안 |

spec의 `"preset"` 필드나 `--preset` 으로 고른다. 사양은 [references/preset-spec.md](references/preset-spec.md).

**한 문서 안의 그림은 모두 같은 프리셋을 쓴다.** 그림마다 색을 바꾸면 스타일 고정의 값어치가 사라진다.

## 산출물 규약

```
figures/
├─ 그림_01_추진체계도.html   (또는 .png)
├─ 그림_01_추진체계도.json   ← spec. 수정의 출발점
└─ 삽입_가이드.md
```

`삽입_가이드.md` 에는 그림번호·제목·파일경로·삽입 위치·대체텍스트를 적는다. 한글(.hwp) 문서에 넣을 때는 **그림(PNG)으로 삽입**하라고 안내한다 — 복붙하면 개체가 깨진다.

## 자유형 경로 (도식이 아닐 때)

조직도·일정도가 아니라 표지 삽화 같은 게 필요하면 [references/image-prompt-spec.md](references/image-prompt-spec.md) 규격으로 이미지 모델용 프롬프트를 써준다.

**정밀 도표에는 절대 쓰지 않는다.** 확산모델은 한글 라벨·격자 정렬·수치에서 반드시 깨지며, 이 도구가 존재하는 이유가 바로 그것이다.

## 하지 않는 일

- **본문 표 조판** — 표는 문서 편집기가 그린다. 이 스킬은 도식 이미지 전용이다. (단 `comparison-matrix`처럼 표 형태의 *그림*은 그린다.)
- **사진풍 자유 일러스트** — 자유형 경로의 프롬프트까지만.
- **없는 내용 지어내기** — 도식은 빈칸이 드러난다. 모르면 묻는다.

## 검증

- `--verify` 통과 (정밀 경로를 썼다면)
- **결과 이미지 육안 확인** — 라벨 겹침·캔버스 이탈은 자동 검증이 못 잡는다
- 표 형태 도해는 행·열 수가 spec과 1:1인지 확인
- 레포 자체검사: `bash scripts/selftest.sh`