GitHub 트렌딩 1위 diagram-design: Claude Code로 에디토리얼급 다이어그램을 만드는 방법

diagram-design이란 무엇이고, Mermaid의 어떤 문제를 해결하는가?

diagram-design은 Claude Code 등 AI 코딩 에이전트에서 사용하는 오픈소스 다이어그램 스킬로, 자연어 요청만으로 에디토리얼급 HTML+SVG 다이어그램을 만들어냅니다. Mermaid의 촌스러운 기본 박스 출력 문제를 해결하기 위해 탄생했으며, 29가지 타입과 브랜드 자동 적용이 핵심 차별점입니다.

diagram-design은 Claude Code, Codex 등 AI 코딩 에이전트에서 사용하는 오픈소스 다이어그램 스킬입니다. 핵심 차별점은 세 가지입니다. 첫째, 29가지 에디토리얼 다이어그램 타입을 지원합니다. 아키텍처, 시퀀스, 플로차트, ER 다이어그램부터 사분면, 레이더, 피라미드, 간트 차트, 타임라인까지 실무에서 필요한 거의 모든 유형을 커버합니다.

둘째, 완전한 HTML+SVG 단일 파일로 출력됩니다. 외부 의존성이 없고 빌드도 불필요하며, 더블클릭으로 바로 열리고 오프라인에서도 작동합니다. 셋째, 라이트/다크/풀 에디토리얼 3가지 테마를 기본 제공하며, 기본 팔레트는 제트 블랙과 아토믹 탠저린(검정 잉크에 주황 포인트)으로 전문적인 느낌을 줍니다.

제작자 Cathryn Lavery는 BestSelf Co. 창업자(부트스트랩으로 5,500만 달러 매출 달성)로, '블로그에 아키텍처 스케치가 필요할 때마다 Claude에게 그려달라고 하면 촌스러운 박스 다이어그램이 나왔다. Figma에서 30분 씨름하는 것과 선택해야 했다. 그래서 직접 만들었다'고 동기를 밝혔습니다.

diagram-design 설치 방법과 브랜드 온보딩은 어떻게 하는가?

Claude Code 마켓플레이스 설치 또는 git clone 후 심볼릭 링크 생성으로 빠르게 시작할 수 있습니다. 설치 후 references/style-guide.md에 웹사이트 URL만 입력하면 60초 안에 컬러 팔레트와 폰트를 자동 추출해 이후 모든 다이어그램에 브랜드를 자동 적용합니다. Claude Code 활용법이 더 궁금하다면 삼성 반도체 AI 칩 설계 사례도 참고해보세요.

설치는 두 가지 방법이 있습니다. Claude Code에서는 마켓플레이스를 통해 설치하고 자동 업데이트를 활성화하면 됩니다. 수동 설치는 'git clone https://github.com/cathrynlavery/diagram-design.git'으로 클론한 뒤, 'ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design'으로 심볼릭 링크를 생성합니다. Codex에서는 'codex plugin marketplace add cathrynlavery/diagram-design'으로 설치합니다.

설치 후 가장 먼저 해야 할 것은 브랜드 온보딩입니다. references/style-guide.md에 웹사이트 URL을 입력하면 Claude가 홈페이지를 읽어 주요 컬러 팔레트와 폰트 스택을 자동 추출합니다. WCAG 명도 대비 검사까지 수행한 후 시맨틱 색상 역할에 매핑하여 이후 모든 다이어그램이 자동으로 브랜드에 맞게 렌더링됩니다. 60초면 완료되며, 사이트 배경색은 다이어그램 배경으로, CTA 색상은 핵심 강조색으로, 본문 폰트는 노드 레이블 폰트로 자동 변환됩니다.

diagram-design으로 퀄리티를 극대화하는 실전 사용팁 6가지는?

다이어그램 타입을 명시적으로 지정하고, 로컬 갤러리에서 29가지 타입을 미리 확인하는 것이 기본입니다. 기존 Mermaid 파일을 그대로 변환할 수 있고, 출력 포맷은 목적에 따라 PNG·HTML·SVG로 선택하면 됩니다. 밀도 원칙(노드 30~40개, 강조색 1~2가지)을 지키면 전문적인 에디토리얼 느낌이 완성됩니다.

첫째, 다이어그램 타입을 명시적으로 요청하세요. '시스템 아키텍처 그려줘'보다 '마이크로서비스 간 메시지 큐 흐름을 시퀀스 다이어그램으로, 신뢰 경계와 폴리시 트레이스 포함해서 그려줘'가 훨씬 정확한 결과를 냅니다. 스킬은 시맨틱 패턴을 레이아웃과 분리해서 처리하기 때문입니다.

둘째, 로컬 갤러리를 먼저 확인하세요. skills/diagram-design/assets/index.html을 브라우저에서 열면 29가지 타입을 라이트/다크/에디토리얼 탭으로 미리 볼 수 있습니다. 온라인 갤러리는 cathrynlavery.github.io/diagram-design에서 확인 가능합니다.

셋째, 기존 Mermaid와 draw.io 파일을 그대로 변환할 수 있습니다. '.mmd, .mermaid 파일이나 마크다운 내 Mermaid 코드 블록, .drawio 파일을 에디토리얼 스타일로 다시 그려줘'라고 요청하면 됩니다. 넷째, 출력 포맷을 목적에 맞게 선택하세요. 슬라이드용은 PNG, 웹 삽입용은 HTML, Figma 후속 작업용은 SVG가 적합합니다.

다섯째, 디자인 밀도 원칙을 이해하세요. 이 스킬의 철학은 밀도 4/10입니다. 모든 노드는 존재 이유가 있어야 하고, 강조 색상은 독자가 가장 먼저 봐야 할 1~2가지에만 사용하며, 노드 수는 30~40개 이하로 유지합니다. 여섯째, 새 세션 시작 시 /reload-plugins를 실행하여 최신 다이어그램 타입을 반영하세요.

Mermaid와 diagram-design 중 언제 어떤 도구를 선택해야 하는가?

두 도구는 경쟁 관계가 아닌 용도 분리 관계입니다. GitHub·Notion 등 마크다운 내장 렌더링이 필요하면 Mermaid, 블로그·발표·기술 문서 등 외부 공개 자료에는 diagram-design이 적합합니다. 실무에서는 내부용 Mermaid를 외부 공개 시 diagram-design으로 변환하는 워크플로도 유효합니다. 프롬프트·컨텍스트 엔지니어링 기초도 함께 읽으면 AI 도구 활용 폭이 넓어집니다.

Mermaid(75K Stars)와 diagram-design(11.5K Stars)은 용도가 다릅니다. Mermaid는 GitHub, GitLab, Notion 등 마크다운 안에서 직접 렌더링되는 것이 최대 강점입니다. README.md나 PR 설명에 코드 블록으로 바로 다이어그램을 넣을 수 있어 문서 내장용으로는 여전히 최선입니다.

diagram-design은 블로그 포스트, 발표 자료, 기술 문서 등 외부 공개용 다이어그램에 적합합니다. 출력물 퀄리티가 에디토리얼급이고 브랜드 자동 적용이 가능하므로, 디자이너 없이도 전문적인 시각 자료를 만들 수 있습니다.

실무에서는 두 도구를 병행하는 것을 권장합니다. 내부 코드 리뷰와 PR에는 Mermaid를, 외부 발표와 블로그에는 diagram-design을 사용하면 됩니다. 또한 diagram-design은 Mermaid 파일을 직접 변환할 수 있으므로, 내부용으로 작성한 Mermaid 다이어그램을 외부 공개 시 에디토리얼 스타일로 업그레이드하는 워크플로도 가능합니다.

이 외에도 알아두면 좋은 도구들이 있습니다. Excalidraw(90K Stars)는 손그림 스타일 실시간 협업 화이트보드로 브레인스토밍에, D2(20K Stars)는 선언적 언어로 복잡한 시스템 정밀 제어에, mingrammer/diagrams(40K Stars)는 Python으로 AWS/GCP/Azure 아키텍처를 코드로 그리는 데 각각 강점이 있습니다.