핵심 요약
- SVG의 viewBox는 최소 x값, 최소 y값, 너비, 높이의 네 값으로 표현됩니다([SVG 구조 명세](https://www.w3.org/TR/SVG2/struct.html)).
- 이 범위가 잘렸다면 미리보기가 정상이어도 내보낸 그림은 일부가 잘릴 수 있습니다.
- 미리보기만 보고 승인하지 마세요.
- 원본 HTML과 SVG·PNG를 차례로 비교해 오류가 처음 생긴 단계를 찾고, 그림 속 연결 관계는 코드나 설계 자료로 따로 확인해야 합니다.
- 증상 → 가장 빠른 조치: 미리보기와 파일이 다르면 같은 원본을 각 단계에서 비교하고, 파일은 정상인데 관계가 틀리면 근거 자료로 그림을 다시 검증합니다.
SVG의 viewBox는 최소 x값, 최소 y값, 너비, 높이의 네 값으로 표현됩니다(SVG 구조 명세). 이 범위가 잘렸다면 미리보기가 정상이어도 내보낸 그림은 일부가 잘릴 수 있습니다.
미리보기만 보고 승인하지 마세요. 원본 HTML과 SVG·PNG를 차례로 비교해 오류가 처음 생긴 단계를 찾고, 그림 속 연결 관계는 코드나 설계 자료로 따로 확인해야 합니다.
증상 → 가장 빠른 조치: 미리보기와 파일이 다르면 같은 원본을 각 단계에서 비교하고, 파일은 정상인데 관계가 틀리면 근거 자료로 그림을 다시 검증합니다.
이 글은 AI가 만든 그림을 문서나 코드 저장소에 넣으려는 엔지니어, 여러 형식의 파일을 검사하는 문서 담당자, 내보내기 검증을 자동화하려는 플랫폼 담당자를 위한 안내입니다.
먼저 오류가 생긴 단계를 분리합니다
브라우저 미리보기는 최종 전달 파일과 같지 않습니다. 원본 HTML, 브라우저에서 본 결과, SVG 파일, PNG 파일을 각각 확인해야 합니다. 어디서 처음 차이가 생겼는지 찾으면 렌더링 문제와 원본 구성 문제를 구분하기 쉽습니다.
| 확인 대상 | 여기서 확인할 내용 | 이상이 있으면 우선 볼 곳 |
|---|---|---|
| 원본 HTML | 노드와 연결, 스타일, 글꼴이 의도와 맞는지 | 생성된 소스와 제공한 근거 |
| 브라우저 미리보기 | 화면 안에서 잘리거나 겹치는 곳이 있는지 | 뷰포트와 화면 렌더링 |
| SVG 파일 | 요소, 스타일, 참조가 보존됐는지 | 내보내기 결과와 파일 구조 |
| PNG 파일 | 글자, 색, 배치, 바깥쪽 영역이 온전한지 | 글꼴과 이미지 렌더링 환경 |
같은 입력을 사용했는지 확인할 수 있도록 내보내기 명령, 실행 위치, 출력 경로, 사용한 도구 버전을 함께 기록하세요. diagram-design의 공식 내보내기 안내와 내보내기 명령 문서를 기준으로 실제 프로젝트의 사용법을 확인하고, 문서에 없는 형식이나 동작을 지원한다고 가정하지 마세요.
SVG 내보내기에서 구조와 스타일을 확인합니다
생성된 SVG가 온전한지 확인하려면
SVG 파일을 텍스트 편집기로 열어 필요한 도형과 글자가 들어 있는지 확인합니다. viewBox가 그림 전체를 포함하는지, 스타일 선언과 정의 영역이 남아 있는지도 살펴보세요. <defs> 안에 정의한 요소나 스타일 참조가 빠지면 파일이 열려도 일부 모양이 사라질 수 있습니다. SVG의 <style> 요소가 어떻게 작동하는지는 MDN의 SVG 스타일 요소 설명에서 확인할 수 있습니다.
요소의 id가 겹치는지도 점검하세요. 여러 요소가 같은 식별자를 사용하면 참조가 의도한 대상을 가리키지 않을 수 있습니다. 반대로 CSS가 파일 안에 있다고 해서 모든 뷰어에서 같은 방식으로 처리된다고 단정해서도 안 됩니다. 내보낸 파일 자체를 실제 전달 환경에서 열어 비교해야 합니다.
PNG가 HTML 미리보기와 다르면 렌더링 환경을 비교합니다
글꼴이나 잘림 때문에 PNG가 달라졌는지 확인하려면
PNG는 SVG와 달리 이미지로 굳어진 결과이므로, 글꼴이나 확대 비율, 잘라내기 범위, 색상 표현이 환경마다 달라지면 최종 모습도 바뀔 수 있습니다. 원본 HTML의 배치가 이미 잘못됐다면 렌더링 환경만 바꿔서는 해결되지 않습니다. 같은 원본을 개발 환경과 실제 배포 과정에서 각각 내보내고 차이를 기록하세요.
화면 캡처를 자동화한다면 사용하는 도구의 기능과 옵션을 확인하세요. 예를 들어 Playwright 페이지 캡처 인터페이스는 페이지 캡처 방법을 설명하지만, 이를 근거로 모든 렌더링 환경의 글꼴과 화면 결과까지 같다고 볼 수는 없습니다. 생성된 PNG를 최종 문서에 넣어 다시 확인하고, 검수에 사용한 파일도 함께 보관하세요.
내보낸 그림은 정상인데 연결 의미가 틀린 경우
보기 좋은 그림과 사실에 맞는 아키텍처 그림은 다릅니다. 예를 들어 AI가 서비스와 데이터 저장소 사이에 직접 연결선을 그렸더라도, 코드에서는 중간 인터페이스를 거칠 수 있습니다. 선의 방향이나 호출 순서를 그림의 배치만 보고 맞다고 판단하면 안 됩니다.
각 노드와 연결선을 코드, 인터페이스 약속, 승인된 설계 자료에 하나씩 대조하세요. 확인할 수 없는 연결은 사실처럼 확정하지 말고, 검토가 필요한 가정으로 표시합니다. 제공된 근거에 없는 구성 요소를 자동으로 보완한 그림이라면, 내보내기 성공 여부와 관계없이 내용 검수를 통과한 것이 아닙니다.
검수와 자동화를 서로 다른 책임으로 나눕니다
실무에서는 파일을 열 수 있는지, 전체 그림이 잘리지 않았는지, 글자를 읽을 수 있는지, 각 관계에 근거가 있는지, 실제 문서에서 쓸 수 있는지를 별도 검사 항목으로 두면 놓치는 부분이 줄어듭니다. 문서 배포 자동화는 파일 생성 실패나 예상 경로에 결과가 없는 상황을 찾아내는 데 적합합니다. 그러나 관계의 뜻이나 설계와의 일치는 사람이 코드와 근거 자료를 확인해야 합니다.
실행 순서는 다음처럼 잡을 수 있습니다.
- 첫째, 입력으로 사용한 HTML이나 원본 그림과 내보내기 명령을 저장합니다.
- 둘째, 미리보기와 SVG를 열어 배치, 글자, 잘림 여부를 대조합니다.
- 셋째, SVG 구조와 스타일, 식별자 및 참조가 실제 파일에 남았는지 확인합니다.
- 넷째, 같은 입력을 목표 문서 환경에서도 PNG로 만들고 결과를 비교합니다.
- 다섯째, 노드와 연결선을 코드 또는 승인된 설계 자료에 대조하고, 근거가 없는 관계를 표시합니다.
- 여섯째, 검사 결과와 실패 로그, 생성된 파일을 함께 보관해 다시 검증할 수 있게 합니다.
배포 자동화를 사용한다면 검사 결과와 내보낸 파일을 작업 결과물로 보존할 수 있습니다. 워크플로 결과물 보관 안내를 참고해 성공 여부뿐 아니라 검토에 필요한 파일과 로그도 남기세요. HTML과 그림을 실제로 대조하는 방법은 kvmboot 도움말 센터에서 이용 환경과 지원 범위를 확인할 때도 참고할 수 있습니다.
로컬 환경에서 이미 검증할 수 있다면 먼저 그 환경으로 원인을 좁히는 편이 합리적입니다. 다만 기존 작업 환경은 글꼴이나 실행 조건을 맞추기 어렵고, 담당자가 바뀌면 결과를 재현하기 힘들 수 있습니다. 반대로 원격 실행 환경도 내보내기 문제를 자동으로 해결하지는 않으며, 장기간 무거운 작업을 계속하거나 물리 인터페이스가 필요한 경우에는 적합하지 않을 수 있습니다. 단기간에 에이전트 작업물을 재현하고 파일 검수 환경을 마련해야 한다면 kvmboot의 맥 대여를 검토할 수 있습니다. 도입 전에 필요한 실행 조건과 전달 방식을 kvmboot에 문의해 확인하고, 현재 가진 HTML과 SVG부터 이 절차대로 비교해 보세요.