다이어그램 AI 에이전트 스킬, diagram-design 해설

AI 에이전트가 그려도 예쁜 다이어그램

"플로차트 그려줘." AI 코딩 에이전트한테 이렇게 말하면 요즘은 그럴듯한 그림이 나와요. 그런데 가만 보면 하나같이 같은 인상이에요. 둥근 박스에 그림자, 어중간한 구도 말이죠.

대표 주자인 Mermaid 결과물을 커뮤니티에서 "Mermaid 슬롭(웃음 거리)"이라 부르는 이유가 있어요. 3만 5천 스타를 넘으며 GitHub 트렌딩에 오른 diagram-design은 정확히 그 지점을 노린 오픈소스 스킬이에요. AI가 그려도 디자이너가 봐줄 만한 에디토리얼 품질의 다이어그램을 목표로요.

만든 사람은 캐스린 레이버리(Cathryn Lavery)예요. BestSelf.co를 운영하는 창업자이자 littlemight.com에서 글을 쓰는 사람이죠. 레이버리는 매번 Claude한테 다이어그램을 부탁할 때마다 사이트 분위기와 전혀 안 맞는 "제네릭 둥근 박스"가 나오는 게 답답했다고 해요.

Figma에서 30분 씨름하거나, 그냥 다이어그램을 포기하거나. "Figma 30분의 대안"으로 만든 스킬이 지금의 diagram-design이에요.

출처: cathrynlavery/diagram-design GitHub 저장소

39종 다이어그램과 디자인 시스템

핵심은 다이어그램 타입이 무척 많다는 점이에요. 현재 main 브랜치 기준 39종의 시각 타입을 지원해요. 아키텍처, 플로차트, 시퀀스, 상태 머신, ER, 타임라인, 스윔레인 등 폭이 넓고, 산키(Sankey), 피시본, Wardley 맵, UML 클래스, 데이터베이스 스키마 같은 전문 타입도 있어요.

2.5.10 버전에서 10개 레이아웃이 추가되며 지금 규모가 됐죠.

모든 타입은 미니멀 라이트, 미니멀 다크, 풀 에디토리얼의 세 가지 정적 변형으로 제공돼요. 결과물은 단일 HTML 파일 하나고, 빌드 단계도 자바스크립트도 외부 이미지 의존성도 없어요. 파일만 더블클릭하면 오프라인으로 열리죠.

일관된 느낌이 나오는 건 디자인 시스템 덕분이에요. 대표 규칙 몇 가지를 정리하면 이래요.

README가 이렇게 못 박아둬요. "한 다이어그램에서 초점은 1~2개, 액센트 색은 독자가 가장 먼저 봐야 할 곳에만." 목표 밀도는 10점 만점에 4점으로, 빽빽하게 채우기보다 덜어내는 쪽을 권하죠. 아이콘은 모두 currentColor를 써서 어떤 스킨이든 상속받기 때문에, 브랜드 온보딩 후에도 깨지지 않아요.

60초 브랜드 온보딩 — 내 사이트 색으로

이 스킬의 차별점은 그림만 예쁜 게 아니라 "내 브랜드에 맞춰" 그린다는 점이에요. onboard diagram-design to https://yoursite.com처럼 말하면 에이전트가 사이트를 읽고 색상 팔레트와 폰트 스택을 추출해요. 그걸 paper·ink·muted·accent·link 같은 시맨틱 역할에 매핑한 뒤, 승인을 받아 스타일 가이드에 반영해요.

흰 화면(paper)은 내 사이트 배경색이 되고, CTA 색은 액센트가 되는 식이에요.

온보딩 시 WCAG AA 대비 검사를 자동으로 돌려요. ink가 paper 위에서 몇 픽셀 크기로도 읽히는지 확인하고, 기준을 통과하지 못하면 보정된 값을 제안해요. 결과물에는 어떤 색·폰트·소스가 쓰였는지 알려주는 "피델리티 영수증"도 함께 나와요.

브랜드는 프로필로 저장해 두면 클라이언트 여러 곳에 재사용할 수 있어요. 프로젝트에 .diagram-design 마커를 만들어 프로필을 지정하면, 다른 작업 공간을 건드리지 않고 각각 다른 브랜드를 유지할 수 있죠.

출처: cathrynlavery/diagram-design GitHub 저장소

draw.io·Mermaid를 에디토리얼하게 — 4개 다이얼

이미 draw.io나 Mermaid로 만든 다이어그램이 있다면? 그 파일을 가리키며 "이거 이 스킬로 다시 그려줘"라고 말하면 같은 내용을 이 디자인 시스템으로 다시 그려요. .drawio, .drawio.xml, .drawio.png, .drawio.svg 파일과 Mermaid의 .mmd·.mermaid·마크다운 펜스 블록을 받아요. 다만 텍스트만 파싱하기 때문에 렌더링이나 브라우저, 네트워크 호출은 없어요.

변환의 핵심은 "그대로 복붙"이 아니라 목적지에 맞게 맞추는 거예요. 같은 소스도 네 가지 다이얼로 다르게 나와요.

변환할 때마다 무엇이 합쳐지고 과감히 버려졌는지 피델리티 원장을 보여줘요. "12개 소스 노드 → 8개로 그렸어요, '토큰 유효?' 판정은 엣지 라벨로 통합했어요" 같은 기록이죠. 소스를 안 봐도 뭐가 남고 사라졌는지 그냥 보여주는 거예요.

최종 결과물이 마음에 들면 /export-diagram으로 SVG·PNG로 뽑을 수도 있어요.

시맨틱 패턴과 선택적 모션

플로차트처럼 명확한 흐름이 없어도 대응해요. 이 스킬은 "무엇을 그리고 싶은지(행동)"와 "어떤 모양으로(레이아웃)"를 분리해서 생각해요. 팬인(fan-in) 큐 병목, 반복 스테이지, 정책 추적, 신뢰 경계 같은 8종의 시맨틱 패턴을 먼저 고르고, 그에 맞는 시각 타입을 뒤에 붙이죠.

타입 수를 무한정 늘리지 않으면서도 다양한 상황을 소화하는 방식이에요. 모션도 선택적으로 넣을 수 있어요. none·reveal·step·loop 네 모드가 있고, 어떤 모드든 첫 프레임은 완결된 정적 화면이에요.

접근성 때문에 prefers-reduced-motion 환경에선 전체 정적 프레임만 보여주고 재생 컨트롤을 숨겨요. 기본값은 none, 즉 평소엔 스크립트 없는 정적 HTML이에요. 스크린 리더에는 다이어그램 제목과 설명이 role="img"와 aria-labelledby로 전달돼요.

어디에 쓰나 — 지원 클라이언트와 한계

설치 범위가 넓은 것도 특징이에요. **Claude Code, Codex, Factory Droid, Pi, Kiro, OpenCode, Claude Cowork(조직 마켓플레이스)**까지 지원해요. 각자 고유한 플러그인 마켓플레이스 경로로 설치하지만 구조는 같아요.

# Claude Code
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

# Codex
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

주의할 점도 몇 가지 있어요. 서드파티 마켓플레이스 자동 업데이트가 기본값으로 꺼져 있어서, 설치 후 마켓플레이스에서 업데이트를 켜야 최신 버전을 따라가요. 이전에 npx skills add로 따로 설치해 둔 복사본이 있으면 새 마켓플레이스 경로를 따라오지 않으니 지우고 다시 설치해야 해요.

첫 사용 시 브랜드 온보딩 여부를 묻는 게이트가 있어 자동화 파이프라인에서 흐름이 멈출 수 있고요. 다이어그램 디테일을 줄일 때 노드 수에 상한이 걸리니(심플화 기준 7노드) 복잡한 시스템은 타협이 필요해요. 트위터용 유니코드 도표나 한 줄 박스처럼 가벼운 그림은 이 스킬의 대상이 아니에요 — "잘 쓴 문단보다 배울 게 없는 다이어그램은 그리지 말라"는 게 저장소의 철학이에요.

참고 링크

• diagram-design GitHub 저장소
• 라이브 갤러리 — 39종 미리보기
• 만든 사람의 블로그 littlemight.com