ppt-grid-deck

name	ppt-grid-deck
description	그리드 기반 PPT 생성 하네스 (공유본). 공개 디자인 캐논(Müller-Brockmann 그리드 · Zelazny 차트)에서 도출한 12×8 모듈러 그리드 + 24 아키타입(7 family)으로 1920×1080 PPTX를 빌드한다. 레이아웃·스타일·팔레트 3축 직교 + 32 완성본 룩(MIT) 통째 선택. 이미지 카드·미디어 슬롯·차트 20종 지원. Use when 사용자가 'ppt-grid-deck', '그리드 덱', '그리드 기반 ppt', '24 아키타입', '그리드 PPT 하네스'를 명시할 때. (일반 'ppt 만들어줘'는 ppt-deck 우선 — 이 스킬은 명시적 호출 시.)

ppt-grid-deck — 그리드 기반 PPT 하네스 (공유본)

그리드(좌표계)는 자작·불변 — 공개 디자인 캐논(Müller-Brockmann)에서 1차 원리로 도출한 12×8 모듈러 그리드(grid.json). 모든 레이아웃이 이 그리드 위에 앉는다. 그 위 두 카탈로그: ① 레이아웃 아키타입 24종(7 family) — 슬라이드 내용에서 추론. ② 룩(look) 32종 — 색·폰트·카드·구성 문법을 한 번에 채우는 자기완결 번들(사용자/지정에서만 선택, 내용 추론 금지).

이 스킬은 완성본 공유 빌드다. 32 룩 = 정체성(구성 문법)까지 흡수된 20룩 + 절제된 클린 격자가 곧 정체성인 12룩. 모두 빌드·시각 QA를 통과한 "다 끝난" 룩만 담았다. (룩 카탈로그를 키우는 흡수 R&D는 별도 연구 하네스 ppt-lab-rebuild.) 출처·자작 범위는 CANON.md, 외부 라이선스 자산은 THIRD-PARTY-NOTICES.md.

직교 4축 + 룩 번들

레이아웃(layout) × 스타일(style) × 팔레트(palette) × 크기(size)   + (옵션) 룩(look = style+palette+문법 번들)

• 레이아웃 = 24 아키타입(7 family). 슬라이드마다 spec variant로 선택. 내용 보고 판단(허용).
• 스타일 = 폰트(latin/ea) + 카드(radius/border/shadow/accent). --style. (house·myeongmungo·consulting·velis)
  • 폰트 블록은 선택적 display: {latin, ea} 티어 지원 — 있으면 표지/페이지헤딩(display·h1·h2)만 이 페이스로, 본문·소제목은 latin/ea로 렌더(없으면 본문 폰트로 폴백 = 무회귀). 세리프 룩이 표지=송명(Song Myung)으로 이 티어를 쓴다.
• 팔레트 = 색 역할 램프. --palette. (7종 — 유효 id: 1,2,3,4,5,6,8 / 7번은 없음)
• 크기 = 글자 크기 티어 소/중/대. --size(또는 spec size). 룩과 직교 — 어떤 룩에든 얹힌다. 본문 위주로 키우고 제목은 소폭(방이 커도 제목만 비대해지지 않게). 룩의 line/tracking은 보존하고 size scale만 교체. 소=룩 본연 크기(무회귀 기본). 본문 환산: 소≈18pt(룩 따라) · 중≈22.5pt · 대≈25pt. 표(matrix)는 큰 크기에서 셀이 2줄로 줄바꿈되고 행 높이가 자동 확장됨.
• 룩(look) = 32종, style+palette(+구성 문법)를 한 번에 채우는 자기완결 번들. --look <slug>. 레이아웃은 항상 직교.

원칙: 레이아웃은 LLM이 내용에서 추론 OK. 스타일·색은 내용에서 추론 금지(슬롭) — 룩/사용자 지정에서만.

실행 워크플로 (필수 — 순서 준수, 건너뛰기 금지)

🚩 룩·스타일·팔레트는 LLM이 임의로 고르지 않는다. 아래 2단계(룩 선택 게이트)를 반드시 거친 뒤에만 빌드한다. 이 확인 없이 빌드하면 규칙 위반.

1. 콘텐츠 파악 — 자료·목적·톤 확인. 레이아웃(아키타입)은 슬라이드 내용에서 추론 OK.
2. 룩 선택 게이트 (STOP — 사용자 확인 필수)
   • 🖼 비주얼 갤러리 자동 오픈 (먼저) — 이름만으로 32 룩을 고르기 어려우므로, 추천 전에 룩 갤러리 HTML을 새로고침 후 브라우저로 띄운다(색·폰트·라이트/다크를 눈으로 보고 고르게). best-effort, 실패 시 경로만 안내:

     cd references && python3 tools/render-look-gallery.py        # 토큰에서 즉석 생성(항상 최신)
     # WSL→Windows: Start-Process가 UNC 경로를 처리(cmd start는 UNC CWD라 거부됨)
     powershell.exe -NoProfile -Command "Start-Process '$(wslpath -w look-gallery.html)'" 2>/dev/null \
       || echo "갤러리: references/look-gallery.html 를 브라우저로 직접 여세요"
     

     (비-WSL/헤드리스 환경이면 자동 오픈 생략하고 경로만 안내한다.) 갤러리는 톤(라이트/다크) 필터 + 이름·폰트 검색을 지원. (PPTX COM 렌더가 아닌 토큰 목업 — 색·폰트·톤 미리보기용. 픽셀 정확 X.)
   • 그 위에서 덱의 목적·톤에 맞는 룩 2~3개를 근거와 함께 추천한다(예: IR/투자 → ppt-samsung-ir-restrained·ppt-goldman-ir-deck / 컨설팅 → ppt-mckinsey-ghost-deck·ppt-bcg-exhibit-deck / 다크 키노트 → ppt-dark-tech·ppt-dark-luxury-keynote / 에디토리얼 세리프 → ppt-luxury-editorial-serif / 강한 포스터 → ppt-neo-brutalism·ppt-swiss-editorial-bold). 전체 목록·토큰은 design-tokens.json의 looks. (레이아웃 슬롯 와이어프레임은 별도 catalog.html.)
   • 사용자가 룩 슬러그를 직접 지정하거나, 룩 대신 --style+--palette 조합을 고를 수도 있다 — 어느 쪽이든 사용자 확인을 받는다.
   • 다크 덱을 원하면 다크 룩(ppt-dark-tech)을 고르거나, 아무 룩 + spec 최상위 "canvas":"#0C1A17"(어두운 hex)로 그 배경 색조의 다크 덱을 만들 수 있다(역할 팔레트 자동 도출). 상세: spec-schema.md §1.
   • 사용자가 "아무거나/알아서 골라"라고 명시하기 전에는 빌드하지 않는다.
3. 글자 크기 게이트 (강의·발표용일 때 필수로 물음) — 글자 크기를 소 / 중 / 대로 묻는다. 매핑은 엔진이 관리:
   • 소 = 룩 본연 크기 (배포·인쇄·미감 우선)
   • 중 ≈ 본문 22.5pt (일반 교실)
   • 대 ≈ 본문 25pt (대형 교실·원거리 — 교실 프로젝터 기본 권장)
   • → build-template.py ... --size 소|중|대 로 전달. 슬라이드당 정보량이 많거나 표/불릿이 빽빽하면 큰 크기에서 줄바꿈이 늘므로, 큰 크기를 고르면 카드 불릿 수를 줄이도록 안내한다.
   • 인쇄/배포·웹 미감용이 명백하면 이 게이트를 생략하고 소(룩 기본)로 가도 된다. 거리 가독성이 중요한 강의/발표 자료에서만 필수.
4. 가독성↔일관성 트레이드오프 게이트 (조건부 STOP — 사용자 확인) — 선택 룩이 번잡한 배경(메시 그라디언트 등)이고 덱에 **fragile 차트(추이=line·산점도·분포)**가 있을 때만 발동. 차트 뒤 가독성 패널의 불투명도가 룩 일관성 ↔ 차트 가독성의 균형점인데, 이건 결정론으로 못 박는 아트디렉팅 판단이라 LLM이 임의로 정하지 말고 사용자에게 묻는다:
   • ① 가독 우선(기본) = 엔진이 도출한 대비 바닥선(가장 약한 마크가 대비 ~3:1 넘는 최소 불투명도).
   • ② 일관 우선 = 카드와 동일(≈16%). 화면 완전 일관, 단 얇은 선이 배경에 묻혀 흐려짐.
   • ③ 절충(≈30%).
   • 고르면 --chart-backdrop-opacity N(0~100) 또는 룩 토큰 grammar.chart_backdrop_opacity로 반영. busy 배경 아니거나 fragile 차트 없으면 미발동.

   💡 일반 원칙(HITL): 중요한 미감 트레이드오프(특히 일관성↔가독성)는 침묵으로 해결하지 않는다 — 옵션+기본값으로 사용자에게 제시. 객관적 바닥선은 엔진이, 그 위 균형은 사람이.

5. 확정 후 빌드 — 선택된 --look(또는 --style+--palette) + --size (+ 게이트 발동 시 --chart-backdrop-opacity)로 build-template.py 실행.
6. 시각 QA → 보고 — qa-runner.sh 렌더 → PNG 직접 확인 → 사용자 보고.

자율 실행(/goal 등)에서도 룩은 합리적 기본값을 1개 골라 "○○ 룩으로 진행합니다" 한 줄 고지하고 즉시 되돌릴 여지를 준다. 룩은 덱의 디자인 정체성이라 묵시적으로 넘어가지 않는다. 크기도 마찬가지 — 강의 덱이면 대(25pt)를 기본으로 한 줄 고지하고 진행한다.

24 아키타입 (7 family) — 권위: archetypes.md

덱 뼈대?       → Frame    cover · section · agenda · closing
한 메시지?     → Focus    statement · feature · showcase
병렬 나열?     → Set      duo · trio · grid · list
명시적 비교?   → Contrast versus · matrix · rank
2축 배치?      → Field    quadrant · map
순서·구조?     → Structure flow · system
데이터?        → Data     share · bars · trend · spread · correlate · kpi

좌표는 전부 grid.json의 grid_box(c0,cspan,r0,rspan)에서 파생(매직넘버 없음). 분류 도출 근거는 archetypes.md.

이미지·미디어 슬롯 (수업·자료용 핵심)

이미지는 아키타입이 아니라 슬롯 fill 종류. feature의 큰 미디어(우측 반쪽), showcase의 좌측정렬 무크롭 미디어 + 불릿(가이드/UI 캡처·도표), duo/trio/grid 카드별 image(이미지 카드 = 사진+설명 2컬럼).

• spec image: {src:"경로", fit:"cover|contain", caption:"…"} → 실제 이미지 삽입(cover 크롭/contain 레터박스).
• 와이드 스크린샷·UI 캡처는 showcase 권장 — 헤더와 좌측정렬·무크롭으로 크게, 불릿은 이미지 종횡비가 자동 배치(세로 여유=우측 / 가로 여유=하단). feature(우측·cover)에 넣으면 잘리거나 작아짐.
• src 없거나 {} → 플레이스홀더 박스("이미지 자리" + 권장 비율 + 도형 픽토, 이모지 없음). 자리만 잡고 나중에 교체.
• 경로는 /mnt/c/....

🎯 이미지 조달 우선순위 (슬롯 만나면 이 순서로)

1. 사용자 콘텐츠에 쓸 이미지 있나? → tools/extract-images.py로 추출해 재활용(생성보다 우선).
2. 없고 코드로 그릴 수 있는 추상/질감인가? → tools/gen-texture.py로 절차적 생성(결정론·무비용).
3. 실사(사람·제품·장소)가 꼭 필요한가? → 웹 검색·다운로드.
4. 그 외 → 빈 {} 플레이스홀더로 자리만. → 어느 경로든 크롭/맞춤은 엔진 media(): fit:cover(크롭)·contain(레터박스) + focal.

사용자 콘텐츠 이미지 추출 (tools/extract-images.py)

PDF·PPTX·DOCX·폴더·이미지·URL 에서 이미지를 떼어내 assets/extracted/에 저장 + 매니페스트(크기·비율·형태) 출력 → 슬롯에 맞는 걸 고른다(아이콘/불릿류 자동 제외, 중복 제거).

cd references
python3 tools/extract-images.py --src /mnt/c/dev/원본.pdf --slides-dir /mnt/c/dev/decks/<deck>
#  → <deck>/assets/extracted/img-NN.* + manifest.json. 와이드=feature/배경, 정사각·세로=카드.

• 떼어낸 경로를 spec media/image/background 의 src 에 넣고 fit:cover(+focal)로 슬롯에 맞춤.

절차적 배경/텍스처 (tools/gen-texture.py — 모델 없음·결정론)

추상 배경·질감(그라디언트·메시·글로우·도트·그레인)은 AI 없이 코드로 그린다 — 키·비용·네트워크 0, 같은 입력=같은 출력(재현). 덱 배경/플레이스홀더 채우기의 1순위. (사람·제품 실사는 이걸로 안 됨.)

cd references
python3 tools/gen-texture.py --kind glow --look ppt-dark-luxury-keynote \
    --slides-dir /mnt/c/dev/decks/<deck> --name cover-glow
#  → <deck>/assets/cover-glow.png 저장 + 경로 출력 → spec 의 background/media/image.src 에 꽂기

• --kind : mesh(4코너 메시) · linear(각도 다중스톱) · glow(다크+가산 라디얼 발광) · dots(미세 도트그리드) · grain(필름 그레인) · solid.
• 채색: --look <slug>(룩 팔레트 canvas/accents 자동) 또는 --colors "#a,#b,.." / --canvas / --accent. → 덱 룩과 결 맞춤이 핵심.
• --size(기본 1920x1080) · --angle(linear) · --seed(grain 결정론) · --blur. 출력은 항상 PNG.

차트 20종 — chart() 헬퍼

• 네이티브(python-pptx): column(clustered/stacked/stacked_100) · bar · line · line_markers · area · pie · doughnut · radar · xy_scatter · bubble
• 합성(도형): waterfall · funnel · gauge · gantt · tam_sam_som · bullet · slope · kpi_cards
• Data 아키타입 spec에서 chart.type으로 선택. 활성 팔레트 색 적용.
• kpi 카드 배열 키: items(권장) · kpis · stats (셋 다 허용, Set·List와 키 일관). 항목 {value, label, note?}.

빌드 / QA

cd references
# 그리드 → layouts.json 재생성 (좌표 SSOT 변경 시에만)
python3 tools/gen-layouts.py
# 빌드 (스타일/팔레트 또는 룩 선택)
python3 tools/build-template.py /tmp/out.pptx --spec demo/all-archetypes.spec.json --style house --palette 1
python3 tools/build-template.py /tmp/out.pptx --spec spec.json --look ppt-samsung-ir-restrained   # 룩 통째
python3 tools/build-template.py /tmp/out.pptx --spec spec.json --look ppt-neo-brutalism --size 대  # 크기 축(강의용 25pt)
# 시각 QA (Windows PowerPoint COM 렌더 → PNG)
bash tools/qa-runner.sh /tmp/out.pptx ppt-neo-brutalism   # 2번째 인자=룩 → 렌더 직전 폰트 자동 보장
# → /tmp/out_qa/images/slide_N.png

spec: { "style":"house", "palette":1, "slides":[ {"archetype":"duo","data":{...}} ] } (variant는 archetype의 alias). data 입력 키 권위는 spec-schema.md — 아키타입별 필수/선택/alias·최소 예시.

파일 맵 (SSOT)

• references/grid.json — 그리드 SSOT(12×8 모듈러, 좌표 파생식)
• references/archetypes.md — 24 아키타입 분류·슬롯·도출 근거
• references/spec-schema.md — 아키타입별 spec data 입력 키(필수/선택/alias·최소 예시). build_* 함수 추출 권위본
• references/layouts.json — gen-layouts.py 생성물(좌표). 직접 수정 금지 → grid.json/gen-layouts.py 수정 후 재생성
• references/design-tokens.json — palettes(7) · styles(4) · looks(32 완성본: grammar 흡수 20 + 스킨완성 12)
• references/catalog.html — 24 아키타입 레이아웃 슬롯 와이어프레임
• references/look-gallery.html — 32 룩 색·폰트·톤 미리보기(render-look-gallery.py 생성물, 항상 재생성 후 사용)
• references/tools/ — build-template.py(엔진) · gen-layouts.py · gen-texture.py · extract-images.py · render-look-gallery.py · render-catalog.py · qa-runner.sh · ensure-fonts.ps1(폰트 자동 프로비저닝)
• CANON.md · THIRD-PARTY-NOTICES.md — 출처/라이선스

환경 메모

• 빌드: WSL python3 + python-pptx. 렌더 QA: Windows PowerPoint COM(soffice 아님).
• 폰트 자동 보장(없으면 다운로드): 룩은 폰트 이름만 배포하고 파일은 품지 않는다. 폰트가 PC에 없으면 PowerPoint가 대체 → 룩 타이포 손실. tools/ensure-fonts.ps1 이 설치확인→로컬캐시 (C:\dev\ppt-fonts)→다운로드(Google=gwfh API / Pretendard=릴리스 zip) 순으로 per-user 설치 (관리자 불필요, WM_FONTCHANGE 브로드캐스트로 COM 인식). MaruBuri·Clash는 자동 미지원→링크 안내. 멱등.
  • 렌더 시 자동: bash tools/qa-runner.sh deck.pptx <look-slug> — 2번째 인자로 룩을 주면 렌더 직전에 그 룩 폰트를 자동 보장(best-effort). 빌드→QA 흐름에서 룩 슬러그를 그대로 넘기면 된다.
  • 수동/새 PC 1회: 스킬이 WSL 네이티브 위치라 powershell.exe 엔 wslpath -w(UNC)로 넘긴다 — powershell.exe -ExecutionPolicy Bypass -File "$(wslpath -w tools/ensure-fonts.ps1)" -All (전체) 또는 -Look <slug>(그 룩만) / -WhatIf(미리보기).
• 산출물 /tmp/ 또는 /mnt/c/....