---
name: html-explainer
description: >
개념이나 작동 원리를 아무것도 모르는 사람에게 그림으로 설명하는 인터랙티브 HTML
지면을 만들 때 로드한다. 큰 그림과 적은 글자로 단계를 쪼개고, 슬라이더·단계 이동·
토글처럼 만져 보면 이해되는 장치를 넣는다. "쉽게 설명해 줘", "아무것도 모르는 사람에게
설명하듯", "그림으로 보여 줘", "만져 보면서 이해되게", "개념 설명 페이지"가 트리거다.
조사 결과를 산문으로 읽는 리포트는 html-report가, 정적 다이어그램 한 장은
diagram-design이, 제품 결정을 검증하는 목업은 html-prototype이, 수치를 담은 차트는
tufte-charts가 맡는다.
compatibility: >
SaveFile 빌트인이 제시된 런에서는 HTML 파일로 남기고, 없으면 코드 블록으로 낸다.
브라우저가 없어 렌더링과 상호작용을 직접 확인하지 못하므로 확인하지 못한 항목을 밝힌다.
---
# HTML 설명 지면
읽어서가 아니라 **보고 만져서** 알게 되는 지면을 만든다. 글을 줄인 리포트가 아니다.
스크롤했을 때 문단이 나오면 실패한 것이다 — 그건 이미 아는 사람을 위한 문서다.
독자는 이 주제를 처음 본다. 용어를 모르고, 왜 중요한지도 모르고, 끝까지 읽을 생각도
없다. 그 사람이 **한 화면씩 넘기면서** 알게 되도록 짠다.
## 반드시 지킬 것
- **그림이 먼저다.** 한 단계를 문장만으로 설명하고 있다면 그 단계는 아직 설계되지
않았다. 문장을 다듬지 말고 그림을 찾는다.
- **한 단계에 한 가지.** 개념 하나가 단계 하나다. 두 개를 한 화면에 겹치지 않는다.
## 절차
1. **독자가 이미 아는 것 하나를 고른다.** 설명은 거기서 출발한다. **비유는 하나만
쓰고 끝까지 같은 비유로 간다.** 중간에 비유를 갈아타면 독자는 앞 단계를 버린다.
좋은 비유가 없으면 비유 없이 실제 사물을 그린다. 억지 비유는 없는 것만 못하다.
2. **설명 계단을 표로 적는다.** 화면을 짜기 전에 쓴다. 3~7단계.
| 단계 | 이 단계에서 알게 되는 것 (한 문장) | 그것을 보여주는 그림 | 독자가 하는 행동 |
|---|---|---|---|
| 1 | 요청은 한 번에 한 대에만 간다 | 서버 한 대와 화살표 하나 | 없음 (출발점) |
| 2 | 대가 늘면 화살표를 나눠야 한다 | 서버 세 대, 앞에 갈림길 | 서버 수 슬라이더 |
| 3 | 한 대가 죽으면 그 몫이 옮겨간다 | 죽은 대에 X, 화살표 재배치 | 서버를 눌러 끄기 |
그림 칸이 비면 그 단계는 아직 못 만든다. 행동 칸이 전부 "없음"이면 인터랙티브가
아니라 슬라이드다.
3. **용어를 언제 꺼낼지 정한다.** **그림을 보여준 다음에 이름을 붙인다.** 정의문으로
시작하지 않는다 — "로드 밸런서란 ~이다"가 아니라, 갈림길을 그려 놓고 "이 갈림길을
로드 밸런서라고 부른다"로 간다.
4. **장치를 고른다.** `references/interaction-patterns.md`에 유형별 최소 구현과 접근성
조건이 있다.
5. **템플릿에서 시작한다.** `references/template.md`에 단계 전환, 키보드, 알림,
모션 축소, 인쇄 배관이 들어 있다. 이 배관을 다시 짜지 않는다.
6. **마지막 관문을 통과시킨다.** 아래 검사를 돌리고 실패한 항목을 고친다.
## 글자 예산
- 한 단계의 설명은 **두 문장 이내**, 한 문장은 40자 안팎이다.
- 화면에 동시에 보이는 글자가 그림보다 넓은 면적을 차지하면 줄인다. 그림이 주인공이다.
- **라벨은 그림 안에 직접 붙인다.** 범례를 만들지 않는다. 눈이 그림과 범례를 오가는
순간 설명이 끊긴다.
- 한 단계에 처음 나오는 전문 용어는 하나까지. 둘이 필요하면 단계를 쪼갠다.
- 괄호로 보충 설명을 달지 않는다. 보충이 필요하면 그림에서 가리킨다.
넣고 싶은 배경 지식은 `` 안에 접어 두거나 아예 뺀다. 본문 흐름에 끼워 넣으면
설명 계단의 높이가 제각각이 된다.
## 만져서 알게 하는 장치
| 설명할 것 | 장치 |
|---|---|
| 값이 바뀌면 결과가 어떻게 바뀌나 | 슬라이더 — 움직이는 즉시 그림이 반응한다 |
| 순서대로 일어나는 일 | 단계 이동. 다음·이전 버튼이고 자동재생이 아니다 |
| 두 경우의 차이 | 토글, 또는 같은 크기로 나란히 두기 |
| 부분과 전체의 관계 | 그림 위 hotspot — 누르면 그 부분만 남기고 나머지가 물러난다 |
| 왜 그렇게 되는지 | 직접 해보기 — 독자가 **틀릴 수 있는** 선택을 하고 결과를 본다 |
**모든 조작은 되돌릴 수 있어야 한다.** 초기화 경로를 항상 둔다. 망가뜨릴까 봐 안
만지면 인터랙티브 지면이 아니다.
넣지 않는 것: 자동재생, 스크롤 하이재킹, 카운트업 숫자, 맞혀야만 다음으로 넘어가는
퀴즈 게이트. 독자에게서 속도를 뺏는 장치는 전부 설명을 방해한다.
## 모션 예산
**이 장르에서는 모션이 정보를 나른다.** 상자가 어디서 어디로 옮겨 갔는지가 곧 설명일
때가 있어서, 형제 스킬들의 "모션을 줄여라"가 여기서는 그대로 적용되지 않는다. 대신
네 조건을 건다.
- 독자가 시작시킨다. 화면에 들어왔다는 이유로 저절로 움직이지 않는다.
- 되감을 수 있다. 한 번 지나가면 못 보는 설명을 만들지 않는다.
- 짧다. 상태가 바뀌는 데 300ms 안팎이면 충분하다.
- **`prefers-reduced-motion`에서는 꺼지는 게 아니라 최종 상태를 즉시 보여준다.** 그냥
끄면 그 단계의 설명이 통째로 사라진다.
움직임은 위치·크기·불투명도 중 하나만 쓴다. 셋을 동시에 바꾸면 무엇이 바뀌었는지
읽히지 않는다.
## 빌드 계약
자체 완결 HTML 하나로 낸다. CSS와 JavaScript를 전부 인라인하고 빌드 도구나 외부
서비스를 요구하지 않는다.
- **단계 콘텐츠를 JavaScript로 생성하지 않는다.** 모든 단계를 DOM에 두고 보이기만
토글한다. JS가 죽어도, 인쇄해도, 화면 낭독기로도 전체가 남는다.
- **바깥으로 요청하지 않는다.** 웹폰트, CDN, 원격 이미지, `fetch` 전부. 그림은 인라인
SVG로 그리거나 data URI로 넣는다.
- **저장소와 부모 창을 건드리지 않는다.** `localStorage`·`sessionStorage`·쿠키·
`window.parent`는 격리된 자리에서 예외를 던진다. 상태는 DOM과 메모리 안에서만 다룬다.
- **링크는 문서 안(`#id`)이나 절대 주소로.** 상대 경로는 파일이 놓이는 위치에 따라 깨진다.
- 사용자가 입력한 문자열을 화면에 다시 그릴 때 `innerHTML`로 붙이지 않는다.
- 좁은 화면에서 그림이 먼저 살아남게 한다. 그림을 줄여 글자를 지키지 않는다.
## 접근성
- 단계 이동과 모든 장치를 키보드만으로 조작할 수 있게 한다. focus를 보이게 둔다.
- 바뀐 내용을 `aria-live` 영역으로 알린다. 그림만 바뀌고 아무 말이 없으면 화면을
못 보는 사람에게는 아무 일도 일어나지 않은 것이다.
- 슬라이더는 네이티브 ``를 쓰고 **현재 값을 글자로도 보여 준다.**
- `