KehanLiu/anim-slides

anim-slides은(는) 무엇을 하나요?

슬라이드 덱을 위한 애니메이션 SVG 일러스트레이션. 기존 슬라이드나 문서에서 생성합니다. 출력은 항상 **조각(fragment)**입니다: <style> 과 <svg> 를 포함하는 하나의 HTML 파일, 스크립트나 외부 파일 없음, CSS 변수로 테마 적용, 어떤 덱에든 바로 삽입 가능합니다. references/fragment-contract.md 가 계약서입니다. 무엇이든 만들기 전에 반드시 읽으세요.

사용 시기

• 슬라이드가 텍스트 카드 행, 글머리 기호 목록 또는 스크린샷이고, 내용이 프로세스, 흐름, 의존성 구조, 타임라인, 비교, 아키텍처 또는 시계열 데이터인 경우
• 문서(Markdown, Confluence 내보내기, README, Mermaid 블록)가 프로세스나 의존성을 설명하고 있으며 사용자가 이를 슬라이드나 페이지에서 애니메이션으로 보여주길 원하는 경우
• 호스트가 HTML 덱(frontend-slides, reveal.js, impress.js, Slidev, 직접 작성) 또는 일반 웹 페이지인 경우. .pptx 또는 Markdown 소스는 먼저 덱 스킬(0단계)에 의해 디자인된 HTML 덱으로 변환됩니다. 그런 다음 이 스킬이 일러스트레이션을 추가합니다.

워크플로우

아래 <skill-dir> 은 이 SKILL.md가 포함된 폴더입니다(Claude Code는 이를 $CLAUDE_SKILL_DIR 로 노출합니다; 다른 환경에서는 이 파일을 로드한 경로를 사용하세요). 스크립트는 Python 3.9+와, 렌더링을 위해 Chrome 또는 Chromium 바이너리가 필요합니다. anim/<name>/ 은 사용자 덱 옆에 있는 폴더입니다.

0. 입력

먼저 HTML 덱을 확보하세요. anim-slides는 HTML 덱에 그림을 추가하는 것이지, 덱 자체를 디자인하지 않습니다.

• 소스가 이미 HTML 덱(reveal.js, impress.js, <section> 또는 .slide 덱)인 경우: 진행합니다.
• 소스가 .pptx, Markdown, remark, 문서 또는 HTML 덱이 아닌 다른 것인 경우: 덱 스킬이 먼저 HTML 덱을 만듭니다. anim-slides가 아닙니다. 선호 순서는 다음과 같습니다: (a) 설치된 사용자 또는 조직의 덱 스킬; (b) frontend-slides가 설치된 경우 (pptx와 Markdown을 디자인된 HTML 덱으로 변환합니다; 미학적 미리보기를 제공할 때, 사용자가 새로운 디자인을 원하지 않는 한 소스 덱의 브랜드에 가장 가까운 것을 선택하세요); (c) 덱 스킬이 설치되지 않은 경우에만 scripts/md_to_deck.py를 대체 수단으로 사용하고(아래 대체 수단 글머리 참조), 사용자에게 그 출력이 디자인이 아닌 일반 호스트이며, 덱 스킬이나 디자이너가 스타일을 입힐 때까지 문서처럼 읽힐 것이라고 한 문장으로 알려주세요. (a)와 (b)의 경우 원본 .pptx는 extract_slides.py 및 render_deck.py 분류(차트, 그림, 노트)의 소스로 유지되지만, 통합은 스킬이 생성한 덱을 대상으로 하며, 일치하는 모양은 host_theme.py를 통해 해당 덱의 팔레트에서 가져옵니다. 덱 스킬에게 각 후보 슬라이드의 본문을 <!-- sN-body --> 와 <!-- /sN-body --> 사이에 고정 크기 슬롯 <div id="sN-slot"> 으로 감싸도록 요청하세요(또는 바로 그렇게 하세요). (md_to_deck.py에서 사용하는 id 및 마커 이름이지만, 여기서 슬롯은 본문의 빈 형제입니다): measure_slot.py --selector '#sN-slot' 을 사용하면 정확하며, integrate_fragment.py --anchor/--replace-until 은 마커를 대상으로 합니다. 덱 스킬의 자체 폰트 링크(Google Fonts, Fontshare)는 덱의 로드이며, anim-slides가 추가한 것이 아닙니다. 이를 유지하고, 인계 시 bundle_deck.py --fetch 로 인라인 처리하세요.

그런 다음 어떤 진입점이 적용되는지 결정하세요:

• 기존 덱: python3 <skill-dir>/scripts/extract_slides.py deck.pptx|deck.html|doc.md -o anim/outline.json 을 실행하고 python3 <skill-dir>/scripts/render_deck.py deck -o anim/render 를 실행한 다음, sheet-NN.png 연락처 시트(각각 12개의 번호가 매겨진 슬라이드)를 페이지별로 보지 말고 확인하세요(outline.json의 슬라이드 그림 수가 렌더링의 그림 수와 다른 경우 슬라이드 레이아웃의 그림을 확인하세요: 레이아웃의 커버 사진을 놓치기 쉽습니다); 그런 다음 references/input-stage.md로 분류하고 테이블을 anim/triage.md에 작성하세요: 모든 슬라이드에 대해 결정과 이유를 기재하고, 묵묵히 건너뛰지 마세요(30개 슬라이드당 38개의 일러스트레이션이 일반적입니다; 짧은 덱의 경우 모든 프로세스, 구조, 타임라인, 비교 또는 데이터 슬라이드에 하나씩 할당됩니다). 그런 다음 전체 덱에 대해 **룩(look)**을 한 번 결정하세요: 일치(match)(조각이 호스트의 팔레트와 폰트를 사용함, 브랜드 또는 기업 덱의 기본값) 또는 간결(lean)(조각이 어두운 바탕에 간결한 팔레트를 사용함, 강연 및 발표용). python3 <skill-dir>/scripts/host_theme.py deck.html --mode match -o anim/host-theme.css 는 덱의 CSS에서 일치 글루(glue)를 파생합니다(--mode lean은 간결 글루를 작성합니다). 파생된 블록을 덱의 자체 변수(흐린 텍스트 색상, 보조 배경)와 한 번 비교하고, 파생이 계산된 혼합을 선택한 경우 수동으로 수정하세요. 첫 번째 조각을 두 가지 방식으로 렌더링하고(render-phases.sh --theme anim/host-theme.css ...), 나머지를 만들기 전에 두 스틸을 보여주세요(사용자가 이미 룩을 지정하지 않은 경우). 두 룩 사이에 색상과 글꼴만 변경됩니다: references/style.md의 모양 규칙은 둘 다에 적용됩니다. **제어(control)**는 전체 덱에 대해 once 입니다. 사용자가 클릭 기반 진행을 요청하지 않는 한 말이죠: 각 슬라이드의 그림은 슬라이드가 나타날 때 차분하게 한 번 재생되고 멈춥니다. step을 스스로 추천하지 마세요. outline.json이 builds를 0보다 크게 보고하는 경우에만 한 줄로 언급하세요(소스가 이미 클릭으로 빌드됩니다: reveal.js 조각, PowerPoint 클릭 애니메이션, impress.js 하위 단계, 덱의 자체 빌드 단계): "덱이 클릭으로 빌드됩니다. 그림도 동일하게 할 수 있습니다(step). 원하시면 말씀해 주세요." step에서는 입장이 그려지고 각 클릭마다 다음 단계가 실행됩니다. 단계는 브리프에 설명된 단계(슬라이드당 35개)이며, 조각 파일은 동일하고, 클릭은 덱 자체 탐색을 사용합니다. Step은 키에만 반응하므로, step 덱은 키보드나 클리커로 발표됩니다(휠이나 스와이프로도 탐색하는 덱, 예: frontend-slides는 스크롤 시 단계를 건너뜁니다). Look과 Control을 anim/triage.md 헤더에 작성하세요.
• 대체 수단, 덱 스킬이 설치되지 않은 경우(Markdown, remark, 또는 Markdown으로 추출된 pptx): python3 <skill-dir>/scripts/md_to_deck.py deck.md -o deck.html 은 통합할 수 있는 일반 자체 포함 호스트를 만듭니다(슬라이드당 하나의 <section>, .visible 게이팅, 인쇄 레이아웃, 각 슬라이드 본문을 감싸는 <!-- sN-body --> 마커). 디자인된 덱이 아닙니다: 사용자에게 한 문장으로 알려주세요. 먼저 Markdown이 참조하는 이미지(상대 경로)를 같은 폴더로 가져오세요. 그렇지 않으면 덱에 플레이스홀더가 표시됩니다. 그런 다음 원본 소스(있었다면 .pptx) 또는 Markdown에서 추출하세요.
• 문서: 소스를 읽고, references/archetypes.md의 테이블로 원형을 선택하고, 사양을 추출하세요(1단계).
• 단일 슬라이드 요청: 해당 슬라이드에 대해 바로 1단계로 이동하세요. 소스가 순서, 방향 또는 그룹화에 대해 모호한 경우에만 사용자에게 물어보세요. 그렇지 않으면 브리프에서 가정을 명시하고 계속 진행하세요.

1. 사양

references/spec-format.md 에 따라 anim/<name>/spec.yaml 을 작성하세요: 이름, 원형, 노드, 엣지, 그룹, 두 번째 표시가 있는 단계, 사이클(패스 길이), 제어(입력에서 덱의 선택: once, 슬라이드가 현재가 될 때 4~10초 동안 차분한 패스 한 번, 정지 프레임에서 종료; step, 단계 표시에서 잘린 동일한 패스로 각 클릭이 다음 단계를 실행하도록 함; loop, 사용자가 연속 루프를 요청한 경우에만). 조각 파일은 once와 step에서 동일합니다. 단계 표시는 data-anim-phases가 됩니다. 소스의 단어를 레이블로 재사용하세요. 사양은 약 12개 노드 미만으로 유지하세요. 그렇지 않으면 분할하세요.

1b. 풀 확인

<skill-dir>/pool/index.yaml 을 읽은 다음, $ANIM_POOL/index.yaml (또는 $ANIM_POOL/*/ 나열)을 읽고(해당 변수가 설정된 경우), 동일한 원형과 유사한 스토리 또는 태그가 있는 항목을 찾으세요.

• 근접 일치: 폴더를 anim/<name>/ 에 복사하고, 조각과 모든 접두사를 <name> 으로 이름을 바꾼 다음, 3단계에서 스캐폴딩 대신 레이블, 데이터, 타이밍 및 viewBox를 사양에 맞게 조정하세요. 그 spec.yaml은 있다면, 당신의 사양의 시작점입니다.
• 동일한 원형만: 평소처럼 스캐폴딩하고, 밀도, 모션 및 정지 프레임에 대한 품질 기준으로 풀 조각을 참조하세요.
• 일치하는 항목 없음: 사양에서 빌드하세요. 가장 가까운 풀 항목을 한 번 살펴볼 가치가 있습니다. 풀 조각을 변경하지 않고 덱에 복사하지 마세요: 그 스토리는 예제일 뿐, 사용자의 것이 아닙니다.

2. 슬롯 및 브리프

슬라이드의 빈 상자를 측정하세요: python3 <skill-dir>/scripts/measure_slot.py deck.html --slide N [--selector SEL] [--ignore .body] 는 상자를 스테이지 픽셀, 일치하는 viewBox 및 검사기 플래그로 출력합니다. (references/layouts.md 는 수동 방식을 설명합니다). 절대 위치 레이아웃에서 --selector 없이 측정하면 잘못된 결과가 나옵니다. 슬롯 div를 측정하세요(--selector '#sN-slot', 0단계). 동일한 종횡비의 viewBox를 선택하고, anim/<name>/brief.md 를 references/brief-template.md 에서 채우세요. 브리프는 viewBox와 렌더링된 크기, 구성, 단계, 정지 프레임, 테마 토큰 및 최소 텍스트 크기를 고정하고, 조각이 슬라이드에서 무엇을 대체하는지(알약, 상자 다이어그램, 글머리 기호 열)를 지정합니다. 조각의 품질은 브리프의 품질에 달려 있습니다.

3. 빌드

python3 <skill-dir>/scripts/scaffold_from_spec.py anim/<name>/spec.yaml -o anim/<name>/<name>.html --rendered-width <px> 는 사양의 유효성을 검사하고 계약을 준수하는 스켈레톤(레이아웃, 단계, 패킷, 노트, 정지 프레임; 글꼴 크기는 렌더링된 너비의 최소값으로 올림됨)을 작성한 다음, 체커를 실행합니다. 출력 상단의 주석은 수동으로 정제해야 할 사항을 나열합니다. 브리프가 설명하는 일러스트레이션으로 정제하세요. references/archetypes.md (구성 및 모션), references/motion-rules.md (타이밍 및 이징), references/style.md (룩: 간결: 링과 가는 선, 상자 없음, 하나의 빛나는 악센트, 모노 하위 레이블, 일반 캡션)을 사용하세요. 여러 일러스트레이션의 경우, 공유된 브리프에서 한 번에 하나의 조각을 빌드하거나, 환경이 허용하면 조각당 하나의 병렬 하위 에이전트를 사용하세요. 통합은 항상 메인 스레드에서 이루어집니다.

4. 시각적으로 확인

1. python3 <skill-dir>/scripts/check_fragment.py anim/<name>/<name>.html --name <name> --rendered-width <px> --stage-width <덱 스테이지 너비> 는 통과해야 합니다(접두사, 토큰, 게이팅, 텍스트 크기, 금지된 콘텐츠). --stage-width 는 텍스트 최소값을 설정합니다(1920에서 18px, 1280에서 12px); outline.json 은 스테이지를 보고합니다.
2. <skill-dir>/scripts/render-phases.sh anim/<name> <W> <H> 1.5 4 7 10 rest 는 일시 중지 및 음수 지연 방법을 사용하여 단계 PNG와 연락처 시트를 임시 폴더에 렌더링합니다(해당 폴더를 출력합니다. --out DIR 을 전달하여 선택하세요). 통합 후, render-phases.sh --page deck.html 1920 1080 rest 는 호스트 페이지의 정지 프레임을 확인합니다. 여러 슬라이드 페이지의 경우 --slide N (또는 #hash, 또는 CSS 선택자)를 추가하세요. 타이밍 마크 또는 단계 프레임에는 --no-script를 사용하고, 페이지 자체 스크립트가 게이트 클래스를 토글할 때 절대 rest에 사용하지 마세요: frontend-slides 덱에서 .visible은 게이트이자 슬라이드를 표시하는 클래스이며, rest 렌더링은 이를 제거하고, 슬라이드는 덱의 스크립트도 .active를 설정하기 때문에 계속 표시됩니다. 스크립트 없이 rest 프레임은 비어 있습니다. 이미지 보기 도구로 모든 PNG를 여세요. 클리핑, 겹침, 읽을 수 없는 텍스트, 빈 패널을 수정하세요. 적어도 한 번 반복하세요.
3. 정지 프레임은 완전한 정지 이미지로 읽혀야 합니다(PDF 내보내기는 그것만 표시합니다).
4. python3 <skill-dir>/scripts/verify_facts.py anim/<name>/<name>.html --source anim/outline.json --slide <N> (또는 --source doc.md) 는 통과해야 합니다: 조각의 모든 숫자는 소스에서 오거나 설명용으로 표시되어야 합니다. 각 WARN을 읽고 추적할 수 없는 단어를 소스의 단어로 바꾸거나 제거하세요. references/accuracy.md 의 규칙. 이 검사가 통과될 때까지 그림은 완료된 것이 아닙니다. 절대 --virtual-time-budget 를 신뢰하지 말고, 절대 PNG 대신 소스를 읽는 것을 신뢰하지 마세요.

5. 통합

python3 <skill-dir>/scripts/integrate_fragment.py deck.html anim/<name>/<name>.html --name <name> --anchor '<슬라이드의 고유 문자열>' [--replace-until '<문자열>'] [--gate 'section.present'] [--control once|step] --backup 는 스타일을 head로 올리고, <!-- anim:<name>:start --> 와 <!-- anim:<name>:end --> 마커 사이에 조각을 삽입하며(스타일은 anim-style 마커 사이에; 재실행하면 두 복사본을 모두 교체), 호스트 덱의 게이트를 다시 작성하고, 빠져나간 모든 클래스에 접두사를 추가합니다. 일반 페이지의 경우 <skill-dir>/scripts/snippets/observer.html 을 페이지에 복사하세요. --control 은 래퍼에서 덱의 제어를 설정합니다. --control step 은 또한 scripts/snippets/step-host.html (작은 일반 스크립트, 라이브러리 없음)을 head에 한 번 넣고 --gate 에서 게이트를 설정합니다. 제어는 통합 시 덱 전체 스위치입니다. 다른 값으로 재실행하여 변경하세요. 조각은 그대로 유지됩니다. 앵커와 until-string은 유지됩니다. 그 사이의 내용이 교체됩니다. 게이트는 호스트의 "현재 슬라이드" 마커입니다: section.present (reveal.js), .visible (일반 페이지, scripts/snippets/observer.html 및 md_to_deck.py의 덱). md_to_deck.py 덱 및 0단계의 슬롯 마커가 있는 덱 스킬 덱에서 조각은 본문을 대체합니다: --anchor '<!-- sN-body -->' --replace-until '<!-- /sN-body -->'. 슬라이드의 제목과 본문 텍스트가 덱 스크립트 없이도 표시되고 인쇄되는지 확인하세요. 덱 스킬의 입장 애니메이션은 종종 현재 슬라이드 클래스에서만 공개를 키로 설정합니다(frontend-slides는 .slide.visible 아래에서만 .reveal 요소를 표시하므로, rest 렌더링과 PDF는 빈 슬라이드를 표시합니다). 이러한 공개를 덱의 활성 클래스(.slide.active)에서도 키로 설정하고, 이를 표시하는 인쇄 규칙을 추가하세요. (클래스 이름 .reveal 은 host_theme.py의 슬라이드 선택자에서 reveal.js 감지와도 일치합니다. 지금까지는 무해하지만, 어떤 슬라이드를 찾았는지 확인하세요.) 또한 PDF 내보내기(reveal의 ?print-pdf는 모든 슬라이드를 현재로 표시함)가 정지 프레임을 표시하도록 인쇄 가드를 추가합니다. 작업 중인 덱을 가볍게 유지하세요: 조각은 작은 SVG 텍스트이며 마커로 들어가지만, 작업 중에 글꼴, 이미지, 라이브러리 또는 스타일시트를 인라인하지 말고, 절대 전체 덱을 컨텍스트로 읽지 마세요. 앵커 주위의 조각을 읽고(grep -n, sed -n), 스크립트가 편집하도록 하세요. 그런 다음 실제 브라우저에서 덱을 열고 지켜보세요.

(번역 과정에서 SKILL.md의 일부가 생략되었습니다. 전체 내용은 원본을 참조하세요.)