Vega-Lite를 사용하여 Mermaid의 한계를 넘어 차트를 렌더링하고 LLM을 통해 Markdown에 임베딩하기

Claude Code나 Codex와 같은 AI 에이전트들은 코드를 작성하고, 문서를 다듬으며, 복잡한 작업을 자동화할 수 있습니다. 하지만 이들에게 "이 데이터로 산점도(scatter plot)를 그려줘"라거나 "추세를 히트맵(heatmap)으로 보여줘"라고 요청하면 한계에 부딪힙니다. Mermaid는 기본적인 막대 그래프(bar charts)와 파이 차트(pie charts) 수준에 머물러 있으며, 통계적 시각화(statistical visualization)는 그 범위를 벗어납니다.

dataviz-svg는 이러한 격차를 메우기 위해 구축된 기술(skill)입니다. 이 기술은 Vega-Lite의 선언적 JSON 명세(declarative JSON specs)로부터 SVG 차트를 생성하고 이를 Markdown 문서에 직접 임베딩합니다.

Mermaid가 부족한 점

Mermaid는 훌륭한 도구이지만, 다른 영역에서 탁월한 성능을 발휘합니다.

Mermaid의 강점	dataviz-svg의 강점
플로우차트(Flowcharts), 시퀀스 다이어그램(sequence diagrams), ER 다이어그램(ER diagrams)	산점도(Scatter plots), 히트맵(heatmaps), 히스토그램(histograms)
...

요약하자면: Mermaid는 **구조적 다이어그램(structural diagrams)**을 위한 것이고, dataviz-svg는 **데이터 기반 통계 시각화(data-driven statistical visualization)**를 위한 것입니다. 에이전트가 이 두 가지를 모두 사용할 수 있게 되면, 문서 출력의 표현력이 극적으로 향상됩니다.

지원되는 차트 유형

dataviz-svg는 Vega-Lite의 완전한 표현력을 상속받으므로, 지원되는 차트의 범위가 매우 넓습니다. 무엇이 가능한지 한눈에 확인하려면 공식 Vega-Lite 갤러리를 확인해 보세요.

막대 차트 (Bar charts) — 수직, 수평, 그룹형, 누적형 (100% 누적형 포함)
선 차트 (Line charts) — 단일 시리즈, 다중 시리즈 (strokeDash를 사용하여 인쇄에 적합한 출력 지원)
산점도 (Scatter plots) — 기본 산점도, 버블 차트 (크기 + 색상 + 로그 스케일)
영역 차트 (Area charts) — 누적 영역 차트, 스트림그래프 (streamgraph)
히트맵 (Heatmaps) — 텍스트 레이어가 중첩된 2D 그리드
히스토그램 (Histograms) — 빈닝 (binning)을 통한 분포 표시
박스 플롯 (Box plots) — 사분위수 표시
파이 / 도넛 차트 (Pie / Donut charts) — innerRadius를 통한 도넛 변형
레이어드 차트 (Layered charts) — 선 + 점 + 텍스트 레이블 중첩
패싯 / 연결 (Facet / Concatenation) — 스몰 멀티플즈 (small multiples), 수평/수직 다중 차트 레이아웃

작동 원리

기술 스택 (Tech Stack)

dataviz-svg의 핵심은 간단합니다. Vega-Lite와 Vega가 Vite를 통해 단일 ESM 파일(~1.6 MB)로 번들링되어 있어, Node.js만으로 실행됩니다.

Vega-Lite JSON 명세 (spec)
    ↓ compile()
Vega 명세 (spec)
...

canvas나 puppeteer와 같은 네이티브 의존성(native dependencies)이 필요 없습니다. 추가적인 npm install도 필요하지 않습니다. 번들 자체에 모든 기능이 포함되어 있어 설치 직후 바로 작동합니다.

에이전트 관점에서의 실행 흐름

에이전트가 이 기술을 사용할 때는 다음 5단계를 따릅니다:

데이터 및 시각화 요구사항 이해 — 입력 데이터(인라인 값 / CSV / JSON), 차트 유형, 축/색상 매핑 식별
Vega-Lite JSON 명세 생성 — 번들링된 패턴 컬렉션을 참조하여 JSON 파일로 명세 작성
SVG 렌더링 — render-svg.sh를 실행하여 SVG 생성
Markdown에 임베딩 — ![Chart Title](./assets/chart.svg)으로 참조
검토 및 조정 — SVG를 검사하고, 레이블 각도나 색상 스케일을 미세 조정한 후 다시 렌더링

사용자 관점에서는 그저 "이 데이터를 히트맵으로 바꿔줘"라고 말하기만 하면 됩니다. 그러면 에이전트가 명세 생성, 렌더링, 문서 임베딩까지 모든 과정을 엔드 투 엔드(end to end)로 처리합니다.

예시: 판매 데이터 시각화

예를 들어, 분기별 판매 데이터의 막대 차트를 생성하기 위해 에이전트는 다음과 같은 Vega-Lite 명세를 생성합니다:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "width": 400,
...

이를 render-svg.sh에 전달하면 브라우저 없이도 SVG가 생성됩니다.

설계 트레이드오프 (Design Trade-offs)

실용성이 최우선입니다. 다음과 같은 의도적인 트레이드오프 (Trade-offs)가 적용되었습니다:

SVG 전용: PNG/PDF를 지원하지 않습니다. 네이티브 의존성(canvas / sharp)을 제거함으로써 설정의 번거로움을 없앴습니다.
정적 출력 전용: Vega-Lite의 인터랙티브 (Interactive) 기능(호버, 줌, 선택)은 SVG로 전달되지 않습니다.
폰트 임베딩 없음: 시스템 폰트에 의존합니다. sans-serif가 가장 안전한 선택입니다.
canvas 패키지 미사용: 텍스트 경계 상자 (Bounding box) 계산이 근사치로 이루어지므로, 긴 CJK (예: 일본어) 레이블의 경우 약간의 정렬 어긋남이 발생할 수 있습니다.

이것들은 의도된 사항입니다. 최우선 순위는 "추가 설치 없이 어떤 환경에서도 즉시 작동하는 것"입니다.

설치 (Installation)

# Claude Code용
gh skill install oubakiou/skills dataviz-svg --agent claude-code --scope project

...

유일한 전제 조건은 Node.js 18 이상입니다. Vega와 Vega-Lite가 번들로 포함되어 있어 별도의 설치가 필요하지 않습니다.

요약 (Summary)

dataviz-svg는 단 한 가지, AI 에이전트에게 데이터 시각화 능력을 부여하는 데 집중합니다.

Vega-Lite를 기반으로 Mermaid가 처리할 수 없는 통계 차트를 생성합니다.
브라우저나 추가 의존성 없이 Node.js만 있으면 됩니다.
에이전트가 명세 생성, 렌더링, 문서 임베딩에 이르는 전체 파이프라인 (Pipeline)을 처리합니다.

"이 데이터를 차트로 만들어줘." — 이 단 한 번의 요청만으로, 에이전트는 적절한 차트 유형을 선택하고, 이를 생성하여 문서에 임베딩합니다. 데이터 시각화를 AI 에이전트 워크플로 (Workflow)에 자연스럽게 통합하는 것 — 그것이 바로 dataviz-svg의 목적입니다.