726 ／ 733
diagram-design, 코딩 에이전트가 그리는 에디토리얼 다이어그램 42종
AI 에이전트에게 다이어그램을 부탁하면 둥근 사각형을 늘어놓은 비슷비슷한 그림이 돌아오기 쉽다. diagram-design은 이 문제를 겨냥한 오픈소스 에이전트 스킬이다. Claude Code, Codex, GitHub Copilot, Factory Droid, Pi 같은 코딩 에이전트가 42가지 유형의 에디토리얼 다이어그램을 그리게 하고, 색과 글꼴은 사용자의 브랜드에 맞춘다.
AI 에이전트 다이어그램의 한계 극복
만든 사람은 BestSelf.co를 운영하고 littlemight.com에 글을 쓰는 캐스린 래버리(Cathryn Lavery)다. 아키텍처 스케치나 플로우차트, 무엇이 가장 중요한지 보여 주는 피라미드가 필요할 때마다 Claude에 부탁했지만, 돌아오는 것은 사이트의 나머지 디자인과 전혀 어울리지 않는 둥근 상자 그림이었다. 그러면 Figma와 30분을 씨름하거나 다이어그램을 아예 빼야 했다고 래버리는 README에 적었다.
diagram-design은 이 불편에서 출발했다. 다이어그램을 편집 디자인 수준으로 그리고, 사용자의 웹사이트를 읽어 60초 정도의 온보딩으로 브랜드 색과 글꼴을 입히는 것이 목표다.
핵심 기능과 디자인 철학
지원하는 다이어그램 유형은 42가지다. 아키텍처, 플로우차트, 시퀀스 다이어그램, 상태 머신, ER 다이어그램, 타임라인, 스윔레인, 레이더 차트, 산키, 워들리 맵, 칸반, 사용자 여정, UML 클래스, 데이터베이스 스키마 등이 들어 있다. 공개 갤러리(cathrynlavery.github.io/diagram-design)에서 모든 유형을 넘겨 볼 수 있다.
결과물은 HTML과 SVG로만 된 독립 파일이다. 빌드 단계나 자바스크립트, 외부 이미지가 필요 없어 브라우저에서 바로 열린다. 유형마다 세 가지 정적 변형이 함께 나온다.
- 미니멀 라이트: 밝은 배경의 간결한 디자인
- 미니멀 다크: 어두운 배경의 간결한 디자인
- 풀 에디토리얼: 요약 카드가 붙은 편집 디자인
디자인 원칙도 분명하다. README가 내세우는 문장은 “가장 품질 높은 손질은 대개 삭제”다. 노드마다 자리를 차지할 이유가 있어야 하고, 강조색은 독자가 먼저 봐야 할 한두 요소에만 쓴다. 목표 정보 밀도는 10점 만점에 4다. 그림자는 쓰지 않고, 테두리는 1px 헤어라인, 모서리 반경은 최대 10px로 묶는다. 좌표와 너비, 간격은 모두 4의 배수로 맞추는데, README는 이 규칙이 다이어그램을 AI가 만든 것처럼 보이지 않게 하는 핵심이라며 양보할 수 없다고 못 박는다. 글꼴은 제목에 Instrument Serif, 노드 이름에 Geist, 기술 라벨에 Geist Mono를 쓴다.
2.3 버전부터는 시맨틱 패턴이 들어왔다. 동작을 레이아웃과 따로 기술하기 때문에 큐나 정책 추적, 신뢰 경계 같은 것을 그릴 때 유형을 새로 늘리지 않고 가장 가까운 기존 유형으로 표현한다. 순서가 있는 설명에는 접근성을 고려한 모션을 선택적으로 붙일 수 있지만, 기본 출력은 스크립트 없는 정적 HTML이다. 모든 템플릿은 SVG에 접근성 이름과 설명을 넣어 스크린 리더가 다이어그램의 제목과 설명을 읽게 한다.
기존 다이어그램 재활용과 출력 옵션
draw.io, Mermaid, Excalidraw로 이미 만든 다이어그램도 가져올 수 있다. diagram-design은 원본의 구성 요소와 관계, 묶음, 방향은 살리고 원본의 좌표·색·글꼴은 버린 채 자신의 디자인 시스템으로 다시 그린다. 이때 출력 형식, 크기, 세부 수준, 대상 독자를 조절할 수 있다.
다음 표는 원본을 가져와 다시 그릴 때 조절하는 네 가지 다이얼이다.
| 다이얼 | 옵션 | 바뀌는 것 |
|---|---|---|
| 형식 | HTML, SVG, PNG, HTML+PNG | 최종 산출물. Figma용 SVG, 슬라이드용 PNG, 웹용 HTML처럼 용도에 맞게 고른다. |
| 크기 | 문서 인라인, 문서 넓게, 슬라이드 16:9, 슬라이드 4:3, 소셜 OG, 소셜 정사각형, 인쇄용 가로(A4, A3, 레터), 맞춤 | 뷰포트와 글자 크기 체계. 화면에 띄우는 슬라이드는 노드 이름을 12px가 아니라 16px로 쓴다. |
| 세부 수준 | 원본 유지(노드 24개 이하, 구역 나눔), 균형(12개 이하), 단순화(7개 이하) | 원본 내용이 얼마나 남는지. 장식, 중복, 말단 클러스터, 인프라 순으로 덜어낸다. |
| 대상 독자 | 엔지니어, 혼합, 경영진 | 노드 수가 아니라 표현. ‘인증 서비스 / JWT · RS256 · :8443’이 ‘인증 서비스 / 토큰 확인’을 거쳐 ‘로그인’으로 바뀐다. |
같은 원본 파일 하나로 쓰임새와 독자에 맞는 여러 다이어그램을 만들 수 있다. 가져오기가 끝나면 무엇을 합치고 접고 뺐는지 적은 충실도 기록(fidelity ledger)을 남긴다.
생성된 다이어그램은 독립 HTML 파일이지만 SVG나 PNG로도 내보낼 수 있다. SVG는 <svg> 노드만 뽑아 Google Fonts를 넣어 주므로 브라우저나 Figma, Illustrator에서 그대로 열린다. PNG는 Playwright로 기본 2배율 래스터화한다. 두 형식 모두 다이어그램만 담고, 풀 에디토리얼 변형의 카드와 헤더는 빠진다.
브랜드 맞춤 설정
사용자가 웹사이트 주소를 주면 에이전트가 홈페이지를 읽어 주요 색 팔레트와 글꼴 조합을 뽑고, 그 값을 paper, ink, muted, accent, link 같은 시맨틱 역할에 연결한다. 바뀔 내용을 먼저 보여 주고, 사용자가 승인하면 references/style-guide.md에 기록한다. 새 프로젝트에서 처음 다이어그램을 그릴 때 스타일 가이드가 기본값 그대로면 온보딩을 할지, 값을 직접 넣을지, 기본값으로 갈지를 먼저 묻는다.
토큰을 기록하기 전에는 paper 위 ink의 WCAG AA 명암 대비를 자동으로 검사한다. 다이어그램의 작은 글씨(9~12px)에서 대비가 모자란 색이 있으면 조정한 값을 제안하고 이유를 설명한다.
색과 글꼴을 직접 정하고 싶다면 skills/diagram-design/references/style-guide.md의 표를 고치면 된다. 모든 다이어그램은 이 파일에서 색값(#eb6c36)이 아니라 시맨틱 역할 이름(accent)을 물려받는다. 여러 고객사 일을 한다면 브랜드를 한 번 온보딩해 이름 붙인 프로필로 저장하고, 프로젝트마다 profile: <slug>가 적힌 .diagram-design 표시 파일을 두면 된다. 그러면 여러 작업 공간이 공용 스타일 가이드를 덮어쓰지 않고 각자 다른 브랜드를 쓴다.
쓰지 말아야 할 때
README는 이 스킬을 쓰지 말아야 할 경우도 따로 적어 둔다.
- 트윗이나 터미널 출력용 간단한 유니코드 다이어그램은 그런 일에 맞는 다른 스킬에 맡긴다.
- 무엇이든 목록이면 표나 글머리 기호로 충분하다.
- 전후 비교는 표가 낫다.
- 상자 하나에 라벨 하나뿐인 그림이라면 그냥 문장으로 쓴다.
그리기 전에 던질 질문은 하나다. 독자가 잘 쓴 문단보다 이 다이어그램에서 더 많이 배우는가? 아니라면 그리지 않는다.
설치 및 작동 방식
공식 빌드는 이 저장소에서만 나온다. 설치 방식은 에이전트마다 다르다.
- Claude Code:
/plugin marketplace add cathrynlavery/diagram-design다음/plugin install diagram-design@diagram-design. 서드파티 마켓플레이스는 자동 업데이트가 기본으로 꺼져 있어/plugin의 Marketplaces 메뉴에서 한 번 켜 줘야 한다. - Codex, GitHub Copilot, Factory Droid: 각 CLI의
plugin marketplace add명령으로 같은 저장소를 등록한 뒤 플러그인을 설치한다. - Pi:
pi install https://github.com/cathrynlavery/diagram-design. 자동 갱신이 없어pi update --extensions로 업데이트한다. - Kiro: 저장소의
skills/diagram-design하위 경로 URL을 Agent Skill로 가져온다. - OpenCode: 마켓플레이스 패키지가 없어
skills/diagram-design/폴더를 복사하거나 심볼릭 링크로 연결한다.
구조는 점진적 노출(progressive disclosure)을 따른다. 에이전트는 처음에 스킬의 이름과 설명만 안다. 요청이 스킬과 맞으면 SKILL.md를 읽고, 시맨틱·유형·애니메이션 참조 문서는 필요할 때만 더 불러온다. 그래서 유형이 몇 개로 늘어도 에이전트의 작업 맥락은 가볍게 유지된다.
예를 들어 “플로우차트 만들어 줘”라고 하면 SKILL.md와 references/type-flowchart.md만 읽는다. 이어서 “이 정책 추적을 애니메이션으로 만들어 줘”라고 하면 앞서 고른 문서에 references/animation.md를 더한다.
출처
- https://github.com/cathrynlavery/diagram-design
- https://cathrynlavery.github.io/diagram-design/