HTML 다이어그램 생성기은(는) 무엇을 하나요?

하나의 인라인 <svg>를 포함한 자체 완결형 .html 파일을 생성하여 단순히 정보를 표시하는 대신 시각적으로 주장합니다. 그런 다음 Playwright로 스크린샷을 찍고, PNG를 검사하여 깔끔해질 때까지 수정합니다.

이 스킬에 포함된 파일

파일	목적	읽어야 할 때
`references/color-palette.md`	모든 색상 및 브랜드 스타일: 유일한 진실 공급원	모든 다이어그램 전
`references/visual-patterns.md`	각 레이아웃 패턴(팬아웃, 타임라인, 트리...)의 스케치	설계 2단계
`references/starter.html`	페이지 셸: CSS 토큰, 텍스트/도형 클래스, 화살표 마커, 각 규칙의 예제 하나	모든 다이어그램의 시작점으로 복사
`scripts/render.py`	HTML을 PNG로 스크린샷하고 형상을 검사	모든 편집 후 실행 (렌더 및 검증 참조)
`examples/`	완성된 두 개의 다이어그램과 해당 PNG	밀도 및 스타일 참조가 필요할 때

모든 다이어그램을 브랜드에 맞게 다시 스타일링하려면 color-palette.md(및 starter.html의 일치하는 토큰)를 편집하세요. 나머지는 보편적인 방법입니다.

이미 결정된 두 가지 사항 (다이어그램마다 재논의하지 않음)

1. 모든 것은 SVG입니다. HTML은 그 주변 페이지일 뿐입니다.

상자, 텍스트, 화살표 및 코드 블록은 모두 하나의 <svg id="diagram"> 안에 있습니다. HTML/CSS(플렉스박스/그리드 div)로 상자를 만들고 그 위에 SVG 오버레이로 커넥터를 연결하지 마세요.

이유: 다이어그램은 기하학 문제이며, 화살표는 양쪽 끝에 정확한 좌표가 필요합니다. 모든 SVG로만 구성하면 모든 노드와 모든 화살표가 하나의 좌표계를 공유하며 이는 파일에 기록되므로 산술로 화살표 끝점을 계산하고 숫자를 편집하여 수정할 수 있습니다. HTML 상자를 사용하면 위치가 브라우저의 레이아웃 엔진에서 나오며, 소스에 없고 글꼴 및 뷰포트 너비에 따라 이동하며, 커넥터는 런타임에 상자를 측정하는 JavaScript가 필요합니다. 이는 디버깅해야 할 두 번째 프로그램이며, 독자의 뷰포트는 검증한 뷰포트와 다를 수 있습니다. 모든 SVG의 비용은 실제로는 있지만 더 작습니다: SVG 텍스트는 줄바꿈되지 않으며(<tspan>으로 직접 줄을 나누어야 함) 너비는 렌더링될 때까지 알 수 없습니다(검사기가 이를 측정하고 오버플로를 보고합니다).

<foreignObject>(SVG 내부의 HTML)는 기본적으로 꺼져 있습니다: 텍스트 줄바꿈을 얻을 수 있는 유일한 곳이지만 브라우저 외부에서는 일관되게 렌더링되지 않고 검사기가 이를 확인할 수 없습니다. 사용자가 도형 내부에 단락이 필요한 경우에만 사용하세요.

2. 레이아웃에 Graphviz 또는 D2를 사용하지 않습니다. 좌표를 수동으로 배치합니다.

이유: 이 방법론은 레이아웃이 개념을 반영해야 한다고 요구합니다: 팬아웃, 타임라인, 사이클, 나란히 비교, 자유롭게 떠다니는 주석, 설명하는 단계 옆에 배치된 코드 블록. 자동 레이아웃 엔진은 다른 목표(간선 교차가 적은 계층 그래프)에 최적화되어 있으므로 모든 다이어그램을 동일한 하향식 계층 구조로 평탄화하며, 이는 이 스킬이 피하고자 하는 정확히 "균일한 상자" 출력입니다. 또한 바이너리 종속성을 추가하고 스타일 재지정 및 주석 추가가 어색한 SVG를 생성합니다.

예외: 교차가 주요 문제인 진정한 그래프 형태의 주제(약 15개 이상의 노드와 많은 교차 링크, 예: 종속성 그래프)입니다. 이 경우 dot -Tplain(Graphviz)을 실행하여 노드 좌표만 얻은 다음, 이 스킬의 스타일과 규칙을 사용하여 직접 노드를 그리세요. 이렇게 하고 있는 이유를 명시하세요.

핵심 철학

다이어그램은 표시하는 것이 아니라 논증해야 합니다.

다이어그램은 형식화된 텍스트가 아닙니다. 말로는 표현할 수 없는 관계, 인과관계 및 흐름을 보여주는 시각적 주장입니다. 형태가 의미여야 합니다.

동형성 검사: 모든 텍스트를 제거했을 때 구조만으로 개념을 전달할 수 있습니까? 그렇지 않다면 다시 설계하세요.

교육 검사: 누군가 이 다이어그램에서 구체적인 것을 배울 수 있습니까, 아니면 단지 상자에 레이블을 붙인 것에 불과합니까? 좋은 다이어그램은 가르칩니다—실제 형식, 실제 이벤트 이름, 구체적인 예를 보여줍니다.

깊이 평가 (먼저 수행)

설계하기 전에 이 다이어그램에 필요한 세부 수준을 결정하세요:

단순/개념적 다이어그램

다음과 같은 경우 추상적인 도형을 사용하세요:

정신 모델이나 철학을 설명할 때
대상 청중이 기술적 세부 사항을 알 필요가 없을 때
개념 자체가 추상화일 때 (예: "관심사의 분리")

포괄적/기술적 다이어그램

다음과 같은 경우 구체적인 예를 사용하세요:

실제 시스템, 프로토콜 또는 아키텍처를 다이어그램으로 나타낼 때
다이어그램이 교육이나 설명에 사용될 때 (예: YouTube 비디오)
대상 청중이 실제로 어떻게 보이는지 이해해야 할 때
여러 기술이 어떻게 통합되는지 보여줄 때

기술적 다이어그램의 경우 증거 아티팩트를 반드시 포함해야 합니다 (아래 참조).

연구 필수 사항 (기술적 다이어그램의 경우)

기술적인 것을 그리기 전에 실제 사양을 조사하세요.

프로토콜, API 또는 프레임워크를 다이어그램으로 나타내는 경우:

실제 JSON/데이터 형식을 조회하세요
실제 이벤트 이름, 메서드 이름 또는 API 엔드포인트를 찾으세요
조각들이 실제로 어떻게 연결되는지 이해하세요
일반적인 자리 표시자가 아닌 실제 용어를 사용하세요

나쁨: "프로토콜" → "프론트엔드" 좋음: "AG-UI는 이벤트(RUN_STARTED, STATE_DELTA, A2UI_UPDATE)를 스트리밍합니다" → "CopilotKit은 createA2UIMessageRenderer()를 통해 렌더링합니다"

연구는 다이어그램을 정확하고 교육적으로 만듭니다.

증거 아티팩트

증거 아티팩트는 다이어그램이 정확함을 입증하고 시청자가 학습하는 데 도움이 되는 구체적인 예입니다. 기술적 다이어그램에 포함시키세요.

증거 아티팩트 유형 (다이어그램에 관련된 것을 선택하세요):

아티팩트 유형	사용 시기	렌더링 방법
코드 스니펫	API, 통합, 구현 세부 사항	어두운 직사각형 + 구문 색상 텍스트 (증거 아티팩트 색상은 색상 팔레트 참조)
데이터/JSON 예제	데이터 형식, 스키마, 페이로드	어두운 직사각형 + 색상 텍스트 (색상 팔레트 참조)
이벤트/단계 시퀀스	프로토콜, 워크플로우, 수명 주기	타임라인 패턴 (선 + 점 + 레이블)
UI 목업	실제 출력/결과 표시	실제 UI를 모방한 중첩 직사각형
실제 입력 콘텐츠	시스템에 들어가는 것 표시	샘플 콘텐츠가 보이는 직사각형
API/메서드 이름	실제 함수 호출, 엔드포인트	문서의 실제 이름 사용, 자리 표시자 금지

예시: 스트리밍 프로토콜에 대한 다이어그램에서는 다음을 보여줄 수 있습니다:

사양의 실제 이벤트 이름 (단순히 "이벤트 1", "이벤트 2"가 아님)
연결 방법을 보여주는 코드 스니펫
스트리밍된 데이터의 실제 모습

예시: 데이터 변환 파이프라인에 대한 다이어그램:

샘플 입력 데이터 표시 (실제 형식, "입력"이 아님)
샘플 출력 데이터 표시 (실제 형식, "출력"이 아님)
관련된 경우 중간 상태 표시

핵심 원칙: 무엇이라고 불리는지가 아니라 실제로 어떻게 생겼는지 보여주세요.

다중 확대/축소 아키텍처

포괄적인 다이어그램은 동시에 여러 확대/축소 수준에서 작동합니다. 국가 경계와 거리 이름을 모두 보여주는 지도와 같다고 생각하세요.

수준 1: 요약 흐름

전체 파이프라인 또는 프로세스를 한눈에 보여주는 단순화된 개요. 종종 다이어그램의 상단이나 하단에 배치됩니다.

예시: 입력 → 처리 → 출력 또는 클라이언트 → 서버 → 데이터베이스

수준 2: 섹션 경계

관련 구성 요소를 그룹화하는 레이블이 지정된 영역. 이것은 시청자가 무엇이 함께 속하는지 이해하는 데 도움이 되는 시각적 "방"을 만듭니다.

예시: 책임별 그룹화 (백엔드 / 프론트엔드), 단계별 (설정 / 실행 / 정리) 또는 팀별 (사용자 / 시스템 / 외부)

수준 3: 섹션 내 세부 사항

각 섹션 내의 증거 아티팩트, 코드 스니펫 및 구체적인 예. 이것이 교육적 가치가 있는 곳입니다.

예시: "백엔드" 섹션 내에서 "API 응답"이라고 레이블이 지정된 상자만이 아니라 실제 API 응답 형식을 보여줄 수 있습니다.

포괄적인 다이어그램의 경우 세 가지 수준을 모두 포함하는 것을 목표로 하세요. 요약은 맥락을 제공하고, 섹션은 구성하며, 세부 사항은 가르칩니다.

나쁨 vs 좋음

나쁨 (표시)	좋음 (논증)
레이블이 있는 5개의 동일한 상자	각 개념은 동작을 반영하는 형태를 가짐
카드 그리드 레이아웃	시각적 구조가 개념적 구조와 일치
텍스트를 장식하는 아이콘	의미 자체인 도형
모든 것에 동일한 컨테이너	개념별로 구별되는 시각적 어휘
모든 것이 상자 안에	선택적 컨테이너가 있는 자유롭게 떠다니는 텍스트

단순 vs 포괄적 (어느 것이 필요한지 파악)

단순 다이어그램	포괄적 다이어그램
일반 레이블: "입력" → "프로세스" → "출력"	구체적: 입력/출력이 실제로 어떻게 생겼는지 표시
명명된 상자: "API", "데이터베이스", "클라이언트"	명명된 상자 + 실제 요청/응답 예제
"이벤트" 또는 "메시지" 레이블	사양의 실제 이벤트/메시지 이름이 있는 타임라인
"UI" 또는 "대시보드" 직사각형	실제 UI 요소와 콘텐츠를 보여주는 목업
설명하는 데 ~30초	~2-3분의 교육 콘텐츠
시청자는 구조를 배움	시청자는 구조와 세부 사항을 모두 배움

단순 다이어그램은 추상적인 개념, 빠른 개요 또는 대상 청중이 이미 세부 사항을 알고 있을 때 적합합니다. 포괄적 다이어그램은 기술 아키텍처, 튜토리얼, 교육 콘텐츠 또는 다이어그램 자체가 가르치도록 하려는 경우에 필요합니다.

컨테이너 대 자유롭게 떠다니는 텍스트

모든 텍스트 조각에 도형이 필요한 것은 아닙니다. 기본값은 자유롭게 떠다니는 텍스트입니다. 목적이 있을 때만 컨테이너를 추가하세요.

컨테이너를 사용해야 할 때...	자유롭게 떠다니는 텍스트를 사용해야 할 때...
섹션의 초점일 때	레이블 또는 설명일 때
다른 요소와 시각적 그룹화가 필요할 때	지원 세부 사항 또는 메타데이터일 때
화살표가 연결되어야 할 때	근처의 것을 설명할 때
도형 자체가 의미를 전달할 때 (결정 다이아몬드 등)	타이포그래피만으로 충분한 계층 구조를 만들 때
시스템의 별개의 "무언가"를 나타낼 때	섹션 제목, 부제목 또는 주석일 때

계층 구조로서의 타이포그래피: 상자 없이 글꼴 크기, 두께 및 색상을 사용하여 시각적 계층 구조를 만드세요. 28px 제목 주위에 직사각형이 필요하지 않습니다.

컨테이너 테스트: 상자 안의 각 요소에 대해 "이것이 자유롭게 떠다니는 텍스트로 작동할까요?"라고 물어보세요. 그렇다면 컨테이너를 제거하세요.

설계 프로세스 (SVG 작성 전에 수행)

0단계: 필요한 깊이 평가

다른 모든 것보다 먼저, 이것이 다음 중 무엇이 필요한지 결정하세요:

단순/개념적: 추상적인 도형, 레이블, 관계 (정신 모델, 철학)
포괄적/기술적: 구체적인 예, 코드 스니펫, 실제 데이터 (시스템, 아키텍처, 튜토리얼)

포괄적인 경우: 먼저 연구하세요. 실제 사양, 형식, 이벤트 이름, API를 조회하세요.

1단계: 깊이 이해

내용을 읽으세요. 각 개념에 대해 물어보세요:

이 개념은 무엇을 합니까? (무엇인지가 아님)
개념 간에 어떤 관계가 있습니까?
핵심 변환 또는 흐름은 무엇입니까?
누군가 이것을 이해하기 위해 무엇을 보아야 합니까? (단지 읽는 것이 아님)

2단계: 개념을 패턴에 매핑

각 개념에 대해 동작을 반영하는 시각적 패턴을 찾으세요. 각 패턴에 대한 스케치와 사용법 노트는 references/visual-patterns.md에 있습니다.

개념이...	이 패턴 사용
여러 출력 생성	팬아웃 (중심에서 방사형 화살표)
입력을 하나로 결합	수렴 (깔때기, 병합되는 화살표)
계층/중첩 있음	트리 (선 + 자유롭게 떠다니는 텍스트)
단계의 시퀀스임	타임라인 (선 + 점 + 자유롭게 떠다니는 레이블)
반복 또는 지속적 개선	나선/사이클 (시작점으로 돌아가는 화살표)
추상적인 상태 또는 컨텍스트임	구름 (겹치는 타원)
입력을 출력으로 변환	조립 라인 (전 → 프로세스 → 후)
두 가지 비교	나란히 (대조와 함께 병렬)
단계로 분리	간격/중단 (섹션 간 시각적 분리)

3단계: 다양성 보장

다중 개념 다이어그램의 경우: 각 주요 개념은 다른 시각적 패턴을 사용해야 합니다. 균일한 카드나 그리드 없음.

4단계: 흐름 스케치

마크업을 작성하기 전에 눈이 다이어그램을 통해 어떻게 움직이는지 정신적으로 추적하세요. 명확한 시각적 스토리가 있어야 합니다.

5단계: HTML/SVG 구축

이제서야 references/starter.html에서 시작하여 파일을 작성하세요. 20px 그리드에 배치하고 아무것도 배치하기 전에 주요 좌표(열, 행, 노드 중심)를 기록하세요. 대형 다이어그램 처리 방법은 아래를 참조하세요.

6단계: 렌더 및 검증 (필수)

파일을 작성한 후에는 다이어그램이 올바르게 보일 때까지 렌더-보기-수정 루프를 반드시 실행해야 합니다. 이것은 선택 사항이 아닙니다 — 전체 프로세스는 아래의 렌더 및 검증 섹션을 참조하세요.

대형 / 포괄적 다이어그램 전략

포괄적 또는 기술적 다이어그램의 경우 SVG를 한 번에 한 섹션씩 구축하세요. 한 번에 전체 파일을 작성하지 마십시오. 포괄적 다이어그램은 응답당 출력 제한을 초과할 수 있으며, 맞더라도 한 번에 한 섹션씩 처리하면 각 섹션에 실제 주의를 기울일 수 있습니다.

섹션별 워크플로우

1단계: 각 섹션 구축

references/starter.html에서 파일 생성: <title>, viewBox를 설정하고 첫 번째 섹션을 추가합니다.
각 편집마다 하나의 섹션 추가, 각각 자체 <g id="sec-..."> 안에 있습니다. 이 섹션의 레이아웃, 간격 및 이미 있는 것과 어떻게 연결되는지 고려하세요.
설명적인 id 사용 (data-node="trigger", id="sec-backend")하여 섹션 간 가장자리를 읽기 쉽게 만듭니다: data-from="trigger" data-to="router".
SVG 상단의 HTML 주석에 좌표 계획 유지 (열 x, 행 y, 섹션 경계). 이후의 모든 섹션과 모든 가장자리가 이를 참조하며, 이것이 추측 없이 간격을 수정하는 방법입니다.

2단계: 전체 검토

전체 파일을 읽고 다음을 확인하세요:

모든 data-from/data-to가 존재하는 data-node를 가리키는가?
간격이 균형 잡혀 있는가, 아니면 일부 섹션은 비좁고 다른 섹션은 드문드문한가?
viewBox가 모든 것을 ~40px 여백으로 포함하는가?

3단계: 렌더 및 검증 (아래).

섹션 경계

…

[번역을 위해 잘림]

HTML 다이어그램 생성기