---
name: html-report
description: >
데이터·메모·조사 결과를 브라우저에서 읽을 리포트로 내보낼 때 로드한다. 외부 파일
없이 혼자 열리는 HTML 한 개를 만들고, 편집 지면처럼 여백과 활자로 읽히게 한다. "리포트 만들어줘", "HTML로 뽑아줘", "결과를 보기 좋게 정리해줘"가
트리거다. DOCX·PPTX·PDF·HWPX 파일로 건네야 하면 document-authoring이, 차트의 데이터
표현 원칙은 tufte-charts가, 화면 구조 탐색은 html-wireframe이, 눌러보는 목업과
프로토타입은 html-prototype이, 제품에 들어갈 UI 코드는 frontend-design이, 개념을 처음
접하는 사람에게 큰 그림으로 설명하는 지면은 html-explainer가 맡는다.
compatibility: >
SaveFile 빌트인이 제시된 런에서는 리포트를 파일로 남기고, 없으면 코드 블록으로 낸다.
둘 다 같은 HTML 이고 산출 방법만 다르다.
---
# HTML 리포트
**혼자 열리는 HTML 하나**를 쓴다. CSS와 JS를 전부 인라인해서, 브라우저로 열거나 PDF로
인쇄하면 그대로 끝나야 한다. 파일로 남길지 코드 블록으로 줄지는 이번 런에 `SaveFile`이
있느냐가 정한다 — 아래 "산출"을 따른다.
읽는 사람은 대시보드를 원해서 온 게 아니라 **무엇을 알게 됐는지**를 알러 온다. 장식을
넣을지 말지 고민되면 뺀다.
## 절차
1. **재료를 정리한다.** 핵심 주장 한 문장, 그것을 지지하는 수치, 읽는 사람이 누구인지.
데이터 덤프를 받았으면 그대로 옮기지 말고 이야기를 찾는다 — 절 구성과 만들 차트
두세 개를 먼저 정하고 시작한다.
2. **디자인 시스템을 읽는다.** 마크업을 쓰기 전에 `references/design-system.md`의 토큰과
활자 단계를 확인한다. 차트를 만들기 전에 `references/charts.md`를 읽는다.
3. **템플릿에서 시작한다.** `references/template.md`의 HTML을 복사해서 내용을 채운다.
토큰, 목차 스크롤 추적, 표 정렬, 인쇄·모션 축소 스타일이 이미 들어 있다. 이 배관을
다시 짜지 않는다.
4. **구조를 잡는다.** 아래 골격을 따르고 절 이름만 내용에 맞게 바꾼다.
5. **시각화를 만든다.** 기본은 인라인 SVG다. 차트 라이브러리는 그 프로젝트가 외부 스크립트
로드를 허용할 때만 쓴다.
6. **낸다.** 아래 "산출" 규칙을 따른다.
## 산출
**이번 런에 `SaveFile`이 있으면 그것으로 낸다.** `mime_type`은 `text/html`, `content`는 완성된
HTML 전문, `name`은 내용을 알아볼 수 있는 이름이다. 파일은 따로 전달되므로 **답변에 본문을
다시 붙이지 않는다** — 무엇을 만들었는지 한두 문장으로 말하고, 브라우저에서 열어 보면 된다고
알린다.
`SaveFile`이 도구 목록에 없으면 완성된 HTML 전문을 `html` 코드 블록 하나로 주고, 사용자가
`.html`로 저장해서 열면 된다고 알린다. 이때 **파일을 만들었다거나 저장했다고 말하지 않는다.**
DOCX·PPTX·PDF·HWPX 파일로 건네야 하는 문서는 이 스킬이 아니라 `document-authoring`이다.
리포트가 그대로 브라우저에 얹힐 것을 전제로 쓴다. 아래 셋은 저장해서 열든 다른 문서 안에
끼워 열든 똑같이 지켜야 하는 조건이다.
- **바깥으로 요청하지 않는다.** 웹폰트, CDN 스크립트, 외부 이미지, `fetch` 전부. 필요한
것은 전부 파일 안에 있어야 한다. 이미지는 data URI로 넣거나 SVG로 그린다.
- **저장소와 부모 창을 건드리지 않는다.** `localStorage`·`sessionStorage`·쿠키·`window.parent`
는 격리된 자리에서 예외를 던진다. 상태는 DOM 안에서만 다룬다.
- **링크는 문서 안이나 절대 주소로.** 상대 경로(`./data.json`, `../img/a.png`)는 이 파일이
어디에 놓이느냐에 따라 깨진다. 문서 안 이동은 `#id`로 한다.
## 골격
```
제목 블록 머리말(kicker) · 제목 · 부제(한 문장 요약) · 날짜·작성자
[목차] 화면이 넓을 때만 왼쪽 고정
요약 두세 문장. 이 리포트의 결론
핵심 수치 2~4개. 숫자와 라벨, 비교 대상
본문 절 1..N 산문 + 차트 + 표 + 주석
방법과 한계 데이터를 어떻게 만들었는지, 무엇을 못 봤는지
출처 번호를 붙이고 본문에서 링크로 연결
```
제목 블록, 요약, 출처는 빼지 않는다. 이 셋이 없으면 슬라이드 묶음이지 리포트가 아니다.
## 반드시 지킬 것
- **색은 `document` MCP의 `executive` 프로파일과 같은 값을 쓴다.** 같은 내용이 화면으로도
파일로도 나가므로 두 벌의 색을 만들지 않는다. 값은 `references/design-system.md`가 source다.
- **본문 지면은 흰색이다.** 색은 표지 블록과 표 머리행처럼 색을 공짜로 받는 자리에만 준다.
본문 먹색은 순검정이 아니라 `--ink`다.
- **브랜드색이 나가는 자리는 정해져 있다.** 제목, 표 머리행, 표지 규칙선, 링크, 차트의
주 계열. 넓은 면적을 브랜드색으로 채우지 않는다.
- **본문 단은 65~75자.** 차트와 표는 그보다 넓게 빠져나와도 되지만 산문은 좁게 둔다.
- **표는 격자가 아니라 정렬로 읽힌다.** 세로선을 넣지 않고, 숫자는 오른쪽 정렬에
등폭 숫자(`font-variant-numeric: tabular-nums`)로 둔다.
- **수치에는 출처를 단다.** 어느 기간, 어떤 모집단, 어떻게 센 값인지 캡션이나 방법 절에
적는다. 근거를 못 대는 숫자는 싣지 않는다.
- **접근성.** 본문 대비 4.5:1 이상, 의미를 색으로만 전달하지 않기, 차트에 텍스트 대안
두기, 키보드로 목차와 표 조작 가능하게 하기.
- **모션은 옵션이다.** `prefers-reduced-motion: reduce`에서 전부 꺼지게 한다.
- **인쇄를 확인한다.** 목차와 인터랙션은 숨기고, 절이 페이지 중간에서 끊기지 않게 한다.
- **다크 모드를 만들지 않는다.** 같은 리포트가 PDF로도 나가는데 화면에서만 반전되면 두
개의 다른 문서가 된다.
- **웹폰트를 링크하지 않는다.** 시스템 스택으로 가고 ``를 선언한다.
## 상호작용은 읽기를 돕는 것만
- 목차 스크롤 추적과 부드러운 이동
- 표 정렬·필터 (행이 스무 개를 넘을 때만)
- 접이식 상세(``) — 본문 흐름에서 뺄 수 있는 근거 자료
- 차트 요소의 값 툴팁
스크롤에 따라 나타나는 애니메이션은 한 번만, 그리고 모션 축소 설정에서 꺼지게 한다.
자동 재생 캐러셀, 시차 스크롤, 카운트업 숫자는 넣지 않는다. 숫자가 올라가는 동안
독자는 그 값을 읽지 못한다.
## 하지 않는 것
- 절마다 다른 배경색을 깔지 않는다. 여백과 얇은 선으로 나눈다.
- 그림자를 겹쳐 카드를 띄우지 않는다. 리포트는 종이에 가깝다.
- 이모지로 절을 구분하지 않는다.
- 데이터가 없는 자리를 채우려고 스톡 이미지나 장식 도형을 넣지 않는다.
- 3D, 그라데이션 채움, 도넛 가운데 총합 같은 차트 장식을 넣지 않는다.
이 목록은 리포트에 해당하는 부분만 추린 것이다. 나머지는 같은 플러그인의
`frontend-design` 스킬 안에 있다 — **그 스킬을 열면 그 디렉터리의**
`references/ai-visual-tells.md`다. 이 스킬의 `references/`가 아니다. 다크 모드와 지면
색처럼 리포트가 일부러 다르게 정한 항목은 이 절이 이긴다.
## 문장
리포트 본문도 사람이 읽는 글이다. 요약과 절 도입부는 결론부터 쓰고, 형용사로 결과를
부풀리지 않는다. "크게 개선됐다" 대신 "12.4%에서 15.1%로 올랐다"라고 쓴다. 한국어로
쓸 때는 한 문서 안에서 종결어미를 섞지 않는다.