Doc HTML Report

doc-html-report: 단일 파일 HTML 보고서 렌더러

목적과 범위

moai-officer:doc-html-report는 cowork 텍스트 산출 파이프라인의 터미널 렌더러입니다. moai-coworker:collab-exec-summary, moai-accountant:finance-financial-statements, moai-consultant:consult-sbiz365 등이 생성한 마크다운 보고서를 단일 파일·자체 완결형(self-contained) HTML로 변환합니다.

핵심 원칙:

• 외부 JS 라이브러리(Chart.js, D3, htmx) 0 의존
• 외부 CSS 프레임워크(Tailwind, Bootstrap) 0 의존
• 인라인 SVG로 차트 직접 렌더링
• 한국어 가독성을 위한 폰트 CDN 단일 예외 허용

이 스킬은 마크다운 출력을 대체하지 않습니다. 마크다운은 단일 진실(source of truth)로 유지되며, HTML 렌더링은 추가 분기로만 작동합니다.

입력

출력

단일 .html 파일 (<cwd>/reports/<slug>-<YYYYMMDD>.html):

• 크기: ≤ 50KB (폰트 CDN 트래픽 제외, 본문 압축 전 기준)
• 외부 의존성: 폰트 CDN <link> 1건 + preconnect 2건 (한국어 폰트)
• 자체 완결형: 브라우저에서 바로 열기 가능, 이메일 첨부·오프라인 사용 가능

6개 모드

구현된 모드

모드별 입력 항목 요약

각 서식이 채우는 주요 항목입니다(템플릿 내부 변수명 기준).

한국어 폰트 정책

본 스킬은 한국어 가독성을 위해 단일 폰트 CDN <link>를 유일한 외부 의존성으로 허용합니다.

시스템 폰트만 사용하면 OS별 폴백(macOS: Apple SD Gothic Neo, Windows: Malgun Gothic)으로 일관성이 깨지므로, 폰트 CDN은 필수입니다.

모드별 폰트 매핑

상세 CDN URL 및 preconnect 패턴: references/fonts.md

디자인 토큰 (CSS 변수 계약)

모든 모드는 :root에 동일한 CSS 변수 8개를 선언합니다.

:root {
  /* 팔레트 */
  --ivory: #FAF9F5;   /* 배경 warm off-white */
  --paper: #FFFFFF;   /* 카드·패널 배경 */
  --slate: #141413;   /* 본문 텍스트 warm black */
  --clay:  #D97757;   /* 강조·링크 terracotta */
  --clay-d:#B85C3E;   /* clay hover 상태 */
  --oat:   #E3DACC;   /* 보조 배경·구분선 light tan */
  --olive: #788C5D;   /* 보조 강조 sage green */

  /* 폰트 */
  --sans:  "Pretendard", system-ui, -apple-system, sans-serif;
  --serif: "Pretendard", ui-serif, Georgia, serif;
  --mono:  "JetBrains Mono", ui-monospace, "SF Mono", monospace;

  /* 레이아웃 */
  --max-width:    860px;
  --radius-panel: 12px;
  --radius-row:   8px;
  --border:       1.5px solid var(--g300);
}

그레이 스케일: --g100: #F0EEE6, --g300: #D1CFC5, --g500: #87867F, --g700: #3D3D3A

상세 명도 대비 검증표 및 인쇄 토큰: references/design-tokens.md

디자인 시스템 적용 (design_system 파라미터)

design_system 입력을 지정하면 moai-officer:doc-design-library에서 브랜드 토큰을 로드해 Tailwind Play CDN + shadcn vanilla 컴포넌트로 렌더합니다.

두 가지 렌더 엔진 (하위 호환 유지):

3개 기본 테마 자동 추천

적용 절차

1. design_system 값으로 systems/<name>.md 토큰 로드
2. mapping/tailwind.md 규칙으로 tailwind.config 객체 생성
3. shadcn vanilla 컴포넌트(card/button/table/badge)로 구조 치환
4. 단일 파일 HTML로 출력 (CDN script + config + 마크업)

주의: design_system 지정 산출물은 Tailwind Play CDN을 런타임 로드하므로 오프라인에서는 스타일이 적용되지 않습니다. 오프라인·인쇄·이메일 첨부 용도라면 design_system을 미지정(0의존 템플릿)하세요.

체인 통합 권장

[텍스트 스킬] → moai-coworker:ai-slop-reviewer → moai-writer:korean-humanize → moai-officer:doc-html-report (서식 선택)

최소 체인 (빠른 렌더링):

[텍스트 스킬] → moai-officer:doc-html-report (서식 선택)

브랜드 디자인 시스템 적용 체인:

[텍스트 스킬] → ai-slop-reviewer → doc-html-report (design_system: clickhouse)

design_system 지정 시 moai-officer:doc-design-library에서 토큰을 자동 로드합니다 — 별도 선행 스킬 호출 불필요.

사용 예시

예시 1: 주간 현황 보고서

경영 요약 결과를 받아서 한울 엔지니어링 11주차 현황 보고서 HTML로 만들어줘.

예시 2: 재무제표 HTML 보고서

재무제표 결과를 HTML 보고서로 변환해줘.

예시 3: 인시던트 리포트

결제 게이트웨이 502 장애 내용을 정리해서 인시던트 리포트 HTML로 만들어줘. 심각도는 SEV-2.

예시 4: PR 설명 문서

PR #312 실시간 알림 채널 통합 내용을 HTML 리뷰 문서로 만들어줘.

시각 품질 게이트 (필수)

[HARD] 렌더가 끝나면 산출 HTML을 브라우저에서 열어 아래 4축을 실측하고 PASS/FAIL을 보고한다.

공통 4축 — 렌더 후 DOM 실측으로 판정한다. 눈으로 훑는 것으로 갈음하지 않는다.

아이콘을 쓸 때 — 아이콘은 레이아웃상 빈 자리로 보여서, 근거를 요구하지 않으면 손에 잡히는 몇 개를 돌려쓰게 된다.

• 문구의 동사에서 고른다 (적는다 → 메모, 멈춘다 → 정지). 명사가 아니라 그 자리가 시키는 행동에 맞춘다.
• 한 문서에서 같은 아이콘을 3회 넘게 쓰지 않는다.
• 마땅한 것이 없으면 비운다. 빈 자리가 틀린 아이콘보다 낫다.
• [HARD] 아이콘을 썼으면 PASS/FAIL 증거표에 넣는다. 슬롯 문구·아이콘·고른 이유를 나란히 적어 보고한다. "아이콘이 필요해서" 같은 동어반복은 근거가 아니며, 근거를 한 줄로 못 쓰면 비운다.

이 4축은 doc-html-slide/references/deck-quality-rubric.md의 hard-fail에서 문서형(연속 스크롤)에 해당하는 것만 옮겨온 것이다. 프로젝터 투사 기준인 pt 하한(24pt)은 문서형에 적용하지 않고 화면 읽기 기준(16px)으로 대체한다.

하지 않는 것

• 마크다운 기본 출력을 대체하지 않습니다 — HTML은 추가 렌더링 분기입니다.
• React / Vue / Tailwind CDN / Chart.js / D3 같은 외부 라이브러리를 쓰지 않습니다.
• 빌드 단계(webpack, vite, esbuild)를 도입하지 않습니다.
• 슬라이드는 moai-officer:doc-pptx, 독립 차트는 moai-analyst:data-visualizer가 맡습니다.
• 여러 파일로 나누지 않습니다 — 모든 산출물은 단일 .html 파일입니다.

참고 문서

설계 문서

• references/design-tokens.md — CSS 변수 계약·팔레트·접근성
• references/fonts.md — 폰트 매핑·CDN URL·preconnect 패턴

템플릿

• references/templates/status.html.tmpl — status 모드
• references/templates/incident.html.tmpl — incident 모드
• references/templates/plan.html.tmpl — plan 모드
• references/templates/explainer.html.tmpl — explainer 모드
• references/templates/financial.html.tmpl — financial 모드
• references/templates/pr.html.tmpl — pr 모드

샘플 출력

• references/samples/status-sample.html — status 모드 렌더링 예시
• references/samples/incident-sample.html — incident 모드 렌더링 예시
• references/samples/plan-sample.html — plan 모드 렌더링 예시
• references/samples/explainer-sample.html — explainer 모드 렌더링 예시
• references/samples/financial-sample.html — financial 모드 렌더링 예시
• references/samples/pr-sample.html — pr 모드 렌더링 예시

설계 참고: Thariq Shihipar, "The Unreasonable Effectiveness of HTML" — 외부 라이브러리 없이 HTML 한 파일로 끝내는 접근의 출처.

P1 컨슈머 통합

4개 P1 컨슈머 스킬의 마크다운 출력을 doc-html-report 템플릿으로 렌더링한 통합 테스트 결과입니다.

상세 호환성 분석: references/integration-tests/COMPATIBILITY.md