HTML 우선 데크은(는) 무엇을 하나요?

사용자가 PowerPoint에서 편집할 수 있는 맞춤형 고품질 데크를 제작하는 2단계 방식입니다.

이 워크플로우를 사용하는 이유

PowerPoint는 시각 디자인을 반복하기에 가장 나쁜 도구입니다. 느리고, 까다롭고, 일관성을 유지하기 어렵습니다. HTML/CSS는 반복하기에 가장 좋은 도구입니다. 슬라이드를 배치하고, 미리보고, 간격, 색상, 계층을 몇 초 안에 다듬을 수 있습니다. 하지만 최종 결과물은 사용자가 자신의 도구에서 문구와 브랜딩을 수정할 수 있는 실제 편집 가능한 .pptx여야 합니다(슬라이드당 이미지 내보내기는 쓸모가 없습니다).

따라서: HTML로 디자인하고, 네이티브 PPTX로 전달하세요. 빠른 반복과 편집 가능한 결과물을 모두 얻을 수 있습니다.

이 폴더에 포함된 파일:

파일	설명
`references/html_prototype.html`	1단계 시작점: 세 개의 슬라이드, CSS 변수로 된 브랜드 색상, 슬라이드쇼 탐색
`scripts/pptx_helpers.py`	2단계 헬퍼 라이브러리: 기하학, 팔레트, 헤더/푸터/카드/필/핵심 요약 컴포넌트
`scripts/render_diagram.py`	코드로 그린 SVG를 고해상도 PNG로 렌더링
`scripts/render_pptx.ps1`	.pptx의 모든 슬라이드를 PNG로 내보내 확인(Windows + PowerPoint 필요)
`examples/example_deck.py`	헬퍼를 기반으로 한 실행 가능한 3슬라이드 데크
`examples/example_diagram.py`	다이어그램 섹션의 모든 기법을 보여주는 실행 가능한 다이어그램 생성기

말투 — 카피라이터가 아닌 컨설턴트처럼 제목을 쓰세요

제목, 부제, 본문 한 줄을 쓰기 전에 이것을 먼저 읽으세요. 레이아웃을 올바르게 잡고 단어를 잘못 쓰면 사용자가 데크를 다시 작성해야 하며, 이는 데크가 없는 것보다 더 나쁩니다. 이는 클라이언트나 동료 앞에 나가는 모든 것(데크, HTML 슬라이드쇼, 대시보드, 상태 보고서, 원페이지)에 적용됩니다.

슬라이드의 기본 LLM 말투는 자극적인 광고 카피입니다. 대부분의 비즈니스 청중은 이를 원하지 않습니다. 사용자가 다른 것을 요청하지 않는 한, 임원 청중을 위해 글을 쓰는 시니어 컨설턴트의 말투로 작성하세요: 평이하고, 단정적이며, 구체적이고, 한 번에 끝내는 스타일.

규칙

제목은 슬라이드가 무엇인지 진술합니다. 연기하지 않습니다.

내용의 이름을 명시하세요. 제목만 훑어 본 독자가 논지를 재구성할 수 없다면 제목은 실패한 것입니다. 레이블과 번호 매기기는 매번 재치보다 뛰어납니다. 1단계: 환불 누수는 독자에게 자신의 위치를 알려주지만, 우리가 시작하는 그 장표는 아무것도 알려주지 않아 독자가 더 읽어야 합니다.

피해야 할 구성

하지 마세요	실패 이유	올바른 예
`대시보드가 보고합니다.` / `설명하지 않습니다.`	2박자 "설정 후 반전". 슬로건처럼 읽히고, 발견으로 읽히지 않음.	`현재 대시보드는 숫자를 보고하지만 분석하지는 않습니다`
`그들은 대시보드 때문에 마지막 도구를 폐기했습니다.` / `그들에게 다른 대시보드를 팔지 마세요.`	동일한 2박자, 게다가 독자에게 강의합니다.	`왜 다른 대시보드가 이 문제를 해결하지 못하는가`
`우리가 시작하는 그 장표:`	답을 숨겨 긴장감을 만드는 콜론-티저.	`1단계: 환불 누수`
`그리고 여기 고치는 방법이 있습니다.`	수다스럽고, 아무도 묻지 않은 질문에 답합니다.	`권장 수정 및 구축 견적`
`세 가지. 그럼 증명하러 갑니다.`	리듬을 위한 단절적 파편.	`이번 미팅에서 필요한 것`
`테이블 위에 올려지는 것.`	관용어를 설명 대신 사용.	`우리가 전달하는 것`
`격주로, 숫자가 붙은 하나의 발견.`	레이블이 필요한 곳에 태그라인.	`일정`
`네 공급업체를 모두 보는 사람만이 이것을 찾을 수 있을 것입니다.`	수사적 빌드업.	`왜 우리 팀이 이 작업을 수행하기에 적합한가`

또한 피해야 할 것: 문장 부호 질문을 제목으로 사용; 단어 하나로 된 드라마(덫, 작전, 마감)를 주제목으로 사용; 펀치를 위한 문장 파편; 엠대시 공개; "여기서 중요한 것은"; 소리 내어 읽고 싶어하는 듯한 모든 표현.

구체적으로

제목: 명사구 또는 평이한 진술. 분석 방법. 데이터 요구사항 및 전달 날짜. 고객을 위한 질문. 1단계 실행에 필요함.
작업에 번호를 매기세요. 단계, 계층, 단계. 1단계부터 8단계까지, 계층 1/2/3. 번호 매기기는 프로그램을 읽기 쉽게 만들고 회의에서 참조할 대상을 제공합니다.
부제목은 한정어를 담고, 농담이 아닙니다: 1단계 · 방법, 데이터 요청 · 계층 1.
본문: 주어와 동사가 있는 완전한 문장. 한 번 제대로 말하고, 강조를 높여 세 번 말하지 마세요.
구체성을 유지하세요. 평이함이 모호함을 의미하지 않습니다. 연간 누계 840만 달러, 12.5% 환불률이 정확히 옳습니다. 숫자, 이름, 날짜, 출처가 신뢰성을 만듭니다.
굵게는 드물게 사용 — 단락에서 무게를 지탱하는 한 구절에만, 리듬을 위해 사용하지 마세요.
인용문은 예외입니다. 고객의 그대로의 인용문은 그대로 남길 수 있고, 진정으로 강력한 단일 문장은 인용문으로 배치할 수 있습니다. 하지만 태그라인이 아닌 발견 결과로 제시하세요.

백분율은 기준을 함께 제시해야 함

백분율은 좋습니다. 계속 사용하세요. 그러나 기준이 없는 백분율은 판단할 수 없습니다. "상위 10%의 에이전트"는 에이전트가 20명이면 2명을 의미하고, 1,000명이면 100명을 의미합니다. 독자는 그것이 패턴인지 두 개체인지 알 수 없습니다.

사람, 사물 또는 사건의 비율일 때마다 백분율 옆에 개수를 제시하세요. 상위 6명의 에이전트(60명 중 10%) · 4,100명의 고객(820,000명 중 0.5%) · 공급업체 A가 1200만 달러를 수령, 전체 환불 금액(2400만 달러)의 절반.
그룹이 작을 때는 백분율이 아니라 숫자로 시작하세요. 약 30개 미만 항목에서는 개수가 발견 결과입니다: 6명의 에이전트가 18,000달러 발행이 에이전트의 10%가 20% 발행보다 낫습니다.
두 백분율이 나란히 있을 때는 두 기준이 모두 필요합니다. 연락처의 12%에 자금의 20%는 독자가 그것이 90,000달러 중 18,000달러이고 30,000개 연락처 중 3,600개라는 것도 알아야만 유용합니다.
분모의 이름을 명시하세요. 백분율이 무엇의 비율인지 말하세요: 8월 환불 금액의, 한 번 이상 청구한 고객의, 10일 이상 근무한 에이전트의.
가능할 때 백분율이 금액이나 인원으로 무엇을 의미하는지 말하세요. "3%가 다른 계좌로 지급됨"은 1,500건의 환불(15만 달러), 연간 총액의 3%가 됩니다.
전체 중 비율 발견은 100% 누적 막대 차트와 같은 전체 대비 비율 차트가 필요합니다. 그래야 독자가 산수를 하지 않고도 절반을 볼 수 있습니다.

셀프 체크: 페이지의 모든 %에 대해 독자가 문장을 떠나지 않고 "얼마나 많은 중에?"에 답할 수 있습니까? 그렇지 않으면 개수를 추가하세요.

배송 전 셀프 체크

데크의 제목을 순서대로, 독립적으로 읽어보세요. 목차처럼 읽히면 옳은 것입니다. 피치처럼 읽히면 다시 작성하세요.

1단계 — HTML로 프로토타입

16:9 캔버스(1280×720)에 슬라이드당 하나의 .slide div로 deck.html을 만드세요. 브랜드 색상을 :root CSS 변수에 넣으세요(사용자의 템플릿에서 가져오세요 — 아래 "브랜드" 참조). 헤더, 섹션 제목, 카드, 콜아웃, 표를 배치하세요. 디자인이 올바를 때까지 여기서 반복하세요 — 열어서 / 스크린샷으로 미리보고, 구조와 모양에 대한 사용자의 승인을 받으세요.

references/html_prototype.html은 바로 사용 가능한 시작점입니다(커버, 헤더 + 3카드 + 핵심 요약 슬라이드, 그림 슬라이드, 푸터)와 CSS 변수 팔레트가 포함되어 있습니다. 읽고 적응시키세요.

이 단계는 디자인 샌드박스입니다. 모든 단어를 완벽하게 할 필요는 없습니다. 레이아웃 시스템(헤더/푸터 크롬, 카드 스타일, 글꼴 크기 척도, 강조 사용법)을 완성하세요. 2단계가 이를 반영하기 때문입니다.

프로토타입을 슬라이드쇼처럼 탐색 가능하게 만드세요

항상 </body> 앞에 이 작은 스크립트를 추가하여 HTML 미리보기가 PowerPoint처럼 작동하게 만드세요 — 클릭(또는 →/↓/Space)으로 다음 슬라이드로 이동, ←/↑로 이전 슬라이드로 이동. 이렇게 하면 1단계 검토가 발표하는 것처럼 느껴지고 HTML 전용입니다(2단계로 가져갈 것이 없습니다).

텍스트 선택 시 페이지가 넘어가면 안 됩니다. 사람들은 슬라이드에서 텍스트를 복사하기 위해 선택합니다. 드래그는 click 이벤트로 끝나므로, 일반적인 클릭 핸들러는 복사 중간에 다음 슬라이드로 이동합니다. 아래 스크립트는 마우스가 누름과 해제 사이에 5px 이상 움직였거나 텍스트가 선택된 경우 클릭을 무시합니다. 실제 클릭은 여전히 이동합니다.

클릭은 클릭된 슬라이드에서 이동해야 합니다. 스크롤 위치를 기반으로 추측해서는 안 됩니다. 추측은 일부 창 크기에서 잘못된 슬라이드를 선택하여 클릭 한 번에 두 슬라이드가 이동합니다. 키(→/←)는 클릭할 것이 없으므로 스크롤 위치를 사용할 수 있습니다.

<script>
  /* 슬라이드쇼처럼 미리보기: 클릭 또는 →/↓/Space = 다음 슬라이드, ←/↑ = 이전 슬라이드. 텍스트 선택 시 이동하지 않음 */
  (function(){
    var slides=[].slice.call(document.querySelectorAll('.slide'));
    function next(){ var y=scrollY+10; return slides.find(function(s){return s.offsetTop>y;}) || null; }
    function prev(){ var y=scrollY-10, p=null; slides.forEach(function(s){ if(s.offsetTop<y) p=s; }); return p; }
    function to(s){ if(s) s.scrollIntoView({behavior:'smooth',block:'start'}); }
    var downX=0,downY=0;
    addEventListener('mousedown',function(e){ downX=e.clientX; downY=e.clientY; });
    addEventListener('click',function(e){
      if(e.target.closest('a,button,input,textarea,select'))return;
      /* 텍스트 강조 표시 또는 마우스 드래그는 슬라이드 클릭이 아님 */
      var sel=window.getSelection&&String(window.getSelection()); if(sel&&sel.trim())return;
      if(Math.abs(e.clientX-downX)>5||Math.abs(e.clientY-downY)>5)return;
      /* 클릭된 슬라이드에서 이동, 스크롤 위치 기반 추측이 아님 */
      var s=e.target.closest('.slide'); to(s ? slides[slides.indexOf(s)+1] : next());
    });
    addEventListener('keydown',function(e){
      if(['ArrowRight','ArrowDown',' ','PageDown'].indexOf(e.key)>-1){e.preventDefault();to(next());}
      else if(['ArrowLeft','ArrowUp','PageUp'].indexOf(e.key)>-1){e.preventDefault();to(prev());}
    });
  })();
</script>

데크가 브라우저에만 머무는 경우(HTML 슬라이드쇼), 여기서 멈추세요: 1단계가 결과물입니다.

2단계 — 네이티브 편집 가능한 PPTX 생성

승인된 디자인을 python-pptx로 다시 만들어 모든 요소를 편집 가능하게 만드세요. 번들 헬퍼 라이브러리 scripts/pptx_helpers.py를 사용하여 데크 폴더에 복사하세요. 16:9 기하학, 브랜드 팔레트 블록, 모든 슬라이드에서 재사용할 컴포넌트를 제공합니다:

new_prs(), blank_slide(prs), body_bg(slide)
add_header(slide, title, meta), add_footer(slide, left, right)
add_section_title, add_subtitle
add_text(...) — 문자열, 단락 목록 또는 혼합 스타일 실행([[("굵은 부분", {"bold": True}), ("일반 부분", {"color": MUTED})]]) 지원
add_rect, add_card(상단/왼쪽 강조 줄무늬), add_pill, bulleted, add_takeaway
add_image(slide, path, x, y, w) — 그림을 고유 비율로 배치
save_deck(prs, path) — 저장하고, 파일이 잠겨/열려 있으면 새 파일 이름으로 전환

구조(실행 가능한 3슬라이드 예제는 examples/example_deck.py 참조):

from pptx_helpers import *
def slide_intro(prs): ...      # 슬라이드당 하나의 빌더 함수
def slide_cards(prs): ...
def main():
    prs = new_prs()
    slide_intro(prs); slide_cards(prs)
    print(save_deck(prs, DECK_DIR / "내 데크.pptx"))

어렵게 얻은 규칙 (흔한 실패를 방지합니다)

사용자가 열고 있는 파일을 절대 덮어쓰지 마세요. PowerPoint가 파일을 잠그면 일반 prs.save()가 PermissionError를 발생시킵니다. save_deck()이 v2, v3…으로 증가시켜 처리합니다. 작업 복사본을 눈에 띄는 곳에 두고 사용자에게 가장 최신 파일을 알려주세요.
모든 것을 도형/텍스트로 빌드하고, 그림으로 하지 마세요. 이것이 핵심입니다. 편집할 수 있어야 합니다. 밀도 높은 비교에는 실제 표(slide.shapes.add_table)를 사용하세요.
모든 실행에서 명시적으로 글꼴을 설정하세요. python-pptx는 테마 글꼴을 안정적으로 상속하지 않습니다.
자동 도형의 기본 그림자를 제거하고(shape.shadow.inherit = False) 기본 텍스트를 지우세요. 헬퍼가 이미 이 작업을 수행합니다.
**슬라이드당 하나의 빌더 + 순서대로 나열하는 main()**으로 구성하세요. 거기서 푸터 번호를 다시 매기세요.

미리보기/확인 루프 (이 작업을 수행하세요 — 보지 않고 배송하지 마세요)

각 빌드 후 슬라이드를 PNG로 렌더링하고 실제로 확인하고, 넘침/간격을 수정하고, 다시 빌드하세요.

Windows(PowerPoint 설치됨):
```
powershell -NoProfile -File scripts/render_pptx.ps1 -pptx "내 데크.pptx" -outdir preview
```
preview/s1.png, s2.png…를 작성합니다. 읽기 전용으로 파일을 열므로 사용자가 데크를 열고 있어도 작동하며, PowerPoint가 이미 실행 중이면 계속 실행 상태로 둡니다.
PowerPoint 없음: 가능importable하면 libreoffice --headless --convert-to pdf(또는 PNG로).

그런 다음 PNG를 읽고, 빌더를 조정하고, 다시 실행하세요. 깨끗해질 때까지 반복하세요.

브랜드 (색상 + 글꼴)

하나의 팔레트를 기본값으로 사용하지 마세요. 사용자의 컨텍스트에서 브랜드를 가져오세요: .pptx 템플릿의 테마(ppt/theme/theme1.xml → <a:clrScheme>), 회사 사이트/CSS를 읽거나, 2-3가지 색상을 물어보세요. 두 단계가 일치하도록 한 번 :root 변수(HTML)와 pptx_helpers.py(PPTX) 상단의 BRAND 블록에 설정하세요. 헤더에 브랜딩할 로고 PNG로 WORDMARK_PATH를 설정하거나 None으로 남겨두세요. 두 파일에 포함된 색상은 중립적인 자리 표시자이므로 교체하세요.

슬라이드 내부의 다이어그램 — 생성하지 말고 코드로 그리세요

슬라이드의 핵심 시각물(흐름, 파이프라인, 깔때기, 아키텍처 또는 프로세스 다이어그램)의 경우, 수십 개의 PowerPoint 도형을 수동으로 배치하지 말고 AI 이미지 생성기를 사용하지 마세요. 이미지 모델은 사진과 예술에 최적화되어 있습니다. 다이어그램의 경우 실패합니다: 흐릿한 텍스트, 잘못된 레이블, 정렬되지 않는 도형, 브랜드에서 벗어난 색상, 그리고 아무것도 편집할 수 없습니다.

대신 SVG(코드로 정의된 벡터 드로잉: <path>, <circle>, <rect>, <text>, 그라데이션 및 필터 포함)를 작성하고 고해상도 PNG로 렌더링하세요. 컴퓨터가 모든 선을 사양대로 그리므로 픽셀 단위로 선명하고, 정확히 브랜드에 맞으며, 반복 가능하고, 쉽게 편집 가능합니다(16진수 코드나 단어를 변경하고 다시 렌더링).

사용자를 위한 비유: 이미지 모델에 다이어그램을 요청하는 것은 기억으로 청사진을 손으로 그려 달라고 예술가에게 부탁하는 것과 같습니다. 코드로 그리는 것은 CAD — 자와 컴퍼스 — 매번 정확합니다.

사용처: 파이프라인/흐름/깔때기 다이어그램, 아키텍처 다이어그램, 프로세스 맵, 개념 그림...

HTML 우선 데크