Diagram Design
- 추천0
- GitHub 별68K
- 디자인라이선스MIT
말로 부탁하면 HTML+SVG 한 파일로 다이어그램을 그려 주는 스킬. 50가지 종류, 내 브랜드 색 · 글꼴 적용 (Claude Code · Codex · Cursor 등)
요약
말로 부탁하면 HTML+SVG 한 파일로 다이어그램을 그려 주는 스킬. 50가지 종류, 내 브랜드 색 · 글꼴 적용 (Claude Code · Codex · Cursor 등)
설명

다이어그램을 내 브랜드로, 자체 완결형 HTML + SVG 파일 하나로 그려 주는 에이전트 스킬입니다. 다이어그램 종류 50가지. 그림자 없음. 밋밋한 Mermaid 느낌 없음.
npx skills add cathrynlavery/diagram-design

에이전트에게 평범한 말로 부탁하면 돼요.
- 「내 앱의 아키텍처 다이어그램을 만들어 줘. 프런트엔드, 백엔드, 데이터베이스, Redis 캐시.」
- 「2분기 프로젝트를 영향 대 노력으로 보여 주는 사분면이 필요해.」
- 「토큰 갱신(401 응답 시)이 들어간 bearer 호출 시퀀스를 만들어 줘.」
- 「diagram-design을 https://yoursite.com 에 맞춰 줘」 (사이트의 색과 글꼴을 가져와서 앞으로 만드는 모든 다이어그램이 내 사이트와 어울리게 해요)
에이전트가 종류를 고르고 계획을 말한 다음, 더블클릭으로 열 수 있는 .html 파일 하나를 써 줘요.
설치
Agent Skills를 읽는 호스트라면 어디서나 써요(Cursor, Claude Code, Codex, Qoder, GitHub Copilot, Gemini CLI, Cline, Windsurf, Amp 등).
npx skills add cathrynlavery/diagram-design
Claude Code에서는 플러그인 마켓플레이스로 설치하면 업데이트와 슬래시 명령을 함께 쓸 수 있어요.
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
공식 빌드는 이 저장소에서만 나와요. 다른 이름의 목록은 비공식 복사본이에요. 스킬이 네트워크로 보내는 정보는 저장소의 PRIVACY.md에 정리돼 있어요. Codex, Qoder, GitHub Copilot, Factory Droid, Claude Cowork, Pi, Kiro, OpenCode별 설치 방법과 직접 고쳐 쓰는 설치(클론)는 저장소 README의 설치 절을 보세요. 자세한 명령은 이 페이지의 「설치」 탭에도 있어요.
다른 도구와 비교
| Mermaid / PlantUML | draw.io / Excalidraw | Diagram Design | |
|---|---|---|---|
| 만드는 방법 | 텍스트로 작성 | 도형을 손으로 끌어다 놓기 | 에이전트에게 말로 설명 |
| 배치 | 자동 | 수동 | 에이전트가 4px 격자에 배치하고, CI가 겹침 · 잘림을 검사 |
| 모양 | 렌더러의 테마 | 그린 그대로 | 내 브랜드에 맞춘 하나의 고집 있는 에디토리얼 스타일 |
| 결과물 | GitHub에서 렌더링되는 텍스트 | 편집 가능한 .drawio · .excalidraw 파일 | 인라인 SVG가 든 HTML 파일 하나, SVG · PNG로 내보내기 가능 |
| 나중에 고치기 | 텍스트 수정 | 캔버스 수정 | 에이전트에게 다시 부탁하거나 SVG 직접 수정 |
| 이미 있는 다이어그램 | — | — | Mermaid · draw.io · Excalidraw · PlantUML 파일을 다시 그려 줌 |
단점도 분명해요. 결과 품질은 쓰는 모델에 따라 달라지고, 같은 프롬프트도 두 번 하면 배치가 다를 수 있어요. 결과물은 편집 가능한 원본 형식이 아니라서 풀 리퀘스트에서 비교할 텍스트도, 상자를 끌어다 놓을 캔버스도 없어요. Git에 두고 스프린트마다 바뀌는 문서에는 지금도 Mermaid가 더 맞아요. Diagram Design은 공개할 다이어그램을 위한 도구예요.
만든 이유
저자는 블로그 글에 쓸 마음에 드는 다이어그램을 원했어요. 아키텍처 스케치, 플로차트, 중요도 피라미드가 필요할 때마다 Claude에게 부탁하면 사이트의 나머지와 전혀 어울리지 않는 둥근 상자 그림이 나왔고, Figma와 30분을 씨름하거나 다이어그램을 포기해야 했어요.
모델은 내용을 이미 이해하고 있었어요. 없던 것은 취향이라서 그 취향을 글로 적었어요. 중요한 한두 가지에만 쓰는 포인트 색 하나, 1px 헤어라인, 그림자 없음, 모든 좌표는 4px 격자 위.
가장 품질 높은 선택은 대개 삭제예요. 모든 노드는 자리를 얻어야 해요. 포인트 색은 독자가 먼저 봐야 할 한두 가지에만 써요. 목표 밀도는 4/10이에요.
만들 수 있는 것
다이어그램 종류는 50가지이고, 종류마다 미니멀 밝은 판, 미니멀 어두운 판, 설명 카드가 붙은 풀 에디토리얼 판의 세 가지 정적 변형이 있어요. 어느 것이든 브라우저에서 바로 열 수 있고, 빌드 단계도 JavaScript도 외부 이미지도 필요 없어요.
몇몇 종류는 같은 참고 문서를 공유하는 이름 있는 변형이 있어요. Line은 slopegraph · ridgeline · streamgraph · bump를, Scatter는 bubble · beeswarm · box plot을, Treemap은 marimekko를, Dependency는 arc diagram을 포함해요.
- Architecture: 관리 영역(점선 띠)과 트래픽 상자(실선)를 한 장에 중첩해서 보여 줄 수 있어요. 계층 자체가 핵심 주장일 때 써요.
- Architecture delta: 동기화된 두 토폴로지를 「전 · 변경 · 후」 원장으로 비교해요(추가 · 삭제 · 변경 · 이동 · 재연결). 속성만 비교할 때는 표를, 한 시점만 보일 때는 Architecture를 써요.
- Exploded axonometric: 한 물체를 2:1 디메트릭 투영으로 그리고 부품을 같은 간격으로 띄워요. 휴대폰 분해, 언박싱, 앱 스택, AI 에이전트 스택, 기계식 키보드 같은 그림에 맞아요.
- Axonometric plan: 같은 투영으로 한 층 또는 한 부지를 그려요. 책상 높이로 자른 벽 덕분에 모든 방이 한 시점에서 읽혀요.
- SBGN: 생물학적 과정을 종/과정의 이분 지도로 그려요. 구획 안의 거대분자와 과정 사각형, 소비 · 생성 · 가역 · 조절 화살표가 들어가요.
라이브 갤러리: cathrynlavery.github.io/diagram-design. 로컬에서는 skills/diagram-design/assets/index.html을 열면 모든 다이어그램을 밝은 판 · 어두운 판 · 풀 에디토리얼 탭으로 넘겨 볼 수 있어요. 종류마다 01부터 50까지 번호가 하나씩 있고, 변형과 예시는 같은 번호에 글자가 붙어요.
온보딩: 내 브랜드로 보이게 하기
핵심은 범용 템플릿이 아니라 내 색과 내 글꼴의 에디토리얼 다이어그램이에요.
기본값은 제트 블랙 + 탠저린 팔레트예요(화이트 스모크 종이, 제트 블랙 잉크, 글자로 써도 대비 4.5:1을 넘기게 어둡게 만든 탠저린 포인트, 블루 슬레이트 보조색, 은색 헤어라인). 바로 스크린샷으로 써도 될 만큼 괜찮지만, 60초 온보딩이 더 좋아요. 스킬이 웹사이트에서 브랜드를 가져와 모든 다이어그램에 적용해요.
흐름
- 「diagram-design을 https://yoursite.com 에 맞춰 줘」라고 말해요.
- 에이전트가 홈페이지를 가져와 주된 팔레트와 글꼴 스택을 뽑아요.
- 감지한 값을 역할(
paper,ink,muted,accent,link)에 맞춰요. - 바뀌는 점을 보여 주고,
references/style-guide.md에 토큰을 써요. - 「적용해」라고 답하면 끝이에요.
이제 새 다이어그램은 모두 내 색을 써요. 사이트의 종이 색이 다이어그램 배경이 되고, CTA 색이 핵심 포인트가 되고, 본문 글꼴이 노드 이름 글꼴이 돼요. 브랜드를 맞출 때는 샘플링한 주소, 정확한 색 역할, 글꼴 계열과 굵기, 글꼴 출처 주소, 대체 글꼴을 적은 충실도 영수증도 함께 나와요. 공개 사이트 글꼴은 그대로 쓰고 렌더링 뒤에 확인해요.
가져오는 것
| 사이트에서 감지 | 바뀌는 토큰 |
|---|---|
| 본문 배경 | paper |
| 주 글자 색 | ink |
| 보조 · 캡션 글자 색 | muted |
| 카드 · 컨테이너 | paper-2 |
| 가장 많이 쓴 브랜드 색(CTA, 링크, 제목) | accent |
| 제목 글꼴 | title 글꼴 |
| 본문 글꼴 | node-name 글꼴 |
| 보조 · 코드 글꼴 | sublabel 글꼴 |
- 대비 검사는 자동입니다. 토큰을 쓰기 전에
paper위ink의 WCAG AA 대비를 확인하고, 9~12px 크기에서 기준에 못 미치면 조정값과 이유를 제안해요. 기본 스킨도 CI에서 같은 기준(글자 4.5:1, 핵심 표식 3:1)을 지켜요. - 접근성이 기본입니다. 모든 템플릿의 인라인 SVG에 접근 가능한 이름과 설명(
role=img,aria-labelledby, 첫 자식 title / desc)이 있어요. ID는 다이어그램 · 변형마다 접두어가 붙어 한 페이지에 여러 SVG를 넣어도 겹치지 않아요. - 오프라인 글꼴: 기본으로 Google Fonts에서 Instrument Serif, Geist, Geist Mono를 불러오고, 이것이 유일한 네트워크 요청이에요. 시스템 글꼴을 요청하면(스타일 가이드의 글꼴 출처를
system으로) 네트워크 요청이 전혀 없어요. - 직접 고치기:
skills/diagram-design/references/style-guide.md의 표를 직접 편집해도 돼요. 모든 다이어그램이accent같은 역할 이름만 읽어요. - 첫 실행 점검: 브랜드가 있는 프로젝트에 기본 스킨 다이어그램을 슬쩍 내보내지 않아요. 새 프로젝트에서 처음 쓸 때 스타일 가이드가 기본값이면 멈추고 「온보딩을 돌릴까요, 토큰을 직접 붙여 넣을까요, 기본값으로 갈까요?」라고 물어요.
- 여러 고객 작업: 브랜드를 한 번 온보딩하고 이름 있는 프로필로 저장한 다음, 고객 프로젝트마다
profile: <이름>이 든.diagram-design표식 파일을 두면 돼요. 프로필은 Claude Code, Codex, Factory Droid, Pi에서 함께 써요.
빠른 시작
open skills/diagram-design/assets/index.html # macOS
xdg-open skills/diagram-design/assets/index.html # Linux
클론한 저장소에서 갤러리를 열어 모든 다이어그램을 둘러본 뒤, 위의 예시처럼 에이전트에게 다이어그램을 부탁하세요. 템플릿에서 바로 시작할 수도 있어요.
cp skills/diagram-design/assets/template.html my-diagram.html # 미니멀 밝은 판
cp skills/diagram-design/assets/template-full.html my-diagram.html # 요약 카드가 붙은 에디토리얼
cp skills/diagram-design/assets/template-motion.html my-diagram.html # 선택형 접근 가능한 모션
동작이 중요할 때 스킬은 시각적 종류보다 의미 패턴을 먼저 골라요. 아홉 가지 패턴(대기열과 병목, 반복되는 단계 슬롯, 비정형 입력 변환, 짝지은 정책 추적, 보안 포장도로, 거버넌스 카탈로그, 보완 보안 계층, 추적 가능한 블록 분해, 수명 주기 단계 지도)이 있어요. 모션은 선택이고 none · reveal · step · loop 네 가지 방식이 있어요. 기본은 none으로, 일반 출력은 스크립트 없는 정적 파일이에요. 움직임을 줄이는 설정에서는 완성된 정적 프레임을 보여 줘요.
draw.io · Mermaid · Excalidraw · PlantUML에서 가져오기
이미 draw.io / diagrams.net, Mermaid, Excalidraw, PlantUML로 만든 다이어그램이 있다면 원본을 가리키기만 하세요. 같은 내용을 이 디자인 시스템으로, 목적지가 필요로 하는 크기로 다시 그려 줘요.
![]()
/diagram-design:import-drawio platform.drawio
/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9 --detail=simplified
/diagram-design:import-plantuml sequence.puml
또는 「이 drawio 파일을 발표용으로 다시 그려 줘」, 「이 Mermaid 블록을 에디토리얼로 만들어 줘」처럼 말로 부탁해도 돼요. 읽을 수 있는 형식은 draw.io(.drawio, .drawio.xml, .drawio.png, .drawio.svg), Mermaid(.mmd, .mermaid, 마크다운의 mermaid 블록), Excalidraw(.excalidraw, .excalidraw.json), PlantUML(.puml, .plantuml, .pu, 시퀀스와 클래스 다이어그램만)이에요. 텍스트만 해석하고 렌더링 · JavaScript · 브라우저 · 네트워크는 쓰지 않아요.
네 가지 조절 항목
핵심은 변환이 아니라 출력을 가는 곳에 맞추는 것이에요. 같은 원본으로 서로 다른 세 가지 다이어그램을 만들 수 있어요.
| 항목 | 선택지 | 바뀌는 것 |
|---|---|---|
| Format | html · svg · png · html+png | 결과물 형식. Figma에는 SVG, 슬라이드에는 PNG, 웹에는 HTML |
| Size | doc-inline · doc-wide · slide-16x9 · slide-4x3 · social-og · social-square · print-a4-landscape · print-a3-landscape · print-letter-landscape · fit | viewBox와 글자 크기 체계(슬라이드는 노드 이름 16px) |
| Detail | faithful(24노드 이하, 영역 구분) · balanced(12 이하) · simplified(7 이하) | 원본이 얼마나 남는가. 장식, 중복, 말단 묶음, 인프라 순으로 줄여요 |
| Audience | engineer · mixed · executive | 개수가 아니라 표현. Auth Service / JWT · RS256 · :8443 → Auth Service / token check → Sign-in |
가져오기는 항상 충실도 원장으로 끝나요. 합친 것, 접은 것, 뺀 것이 무엇인지 적혀 있어요.
Detail: balanced · 12 source nodes → 8 drawn
Collapsed: "Token valid?" decision → edge label on Gateway → Auth
Dropped: 1 sticky note ("legacy path, to be retired"), unconnected in source
Kept in full: the request path (Web/Mobile → Gateway → Orders → Postgres)
원본의 좌표 · 팔레트 · 글꼴, draw.io의 대각선 연결선, Mermaid의 자동 배치, Excalidraw의 손그림 도형, PlantUML의 skinparam은 가져오지 않아요. 구성 요소, 관계, 묶음, 방향은 항상 가져와요.
PNG / SVG로 내보내기
다이어그램은 자체 완결 HTML로 나오지만, Figma · 슬라이드 · 소셜 카드용으로 다이어그램 자체를 내보낼 수 있어요.
/diagram-design:export-diagram path/to/diagram.html
/diagram-design:export-diagram path/to/diagram.html --svg-only
/diagram-design:export-diagram path/to/diagram.html --png-only --scale=3
/diagram-design:export-diagram path/to/diagram.html --registry
(Pi에서는 /export-diagram, Claude Code에서는 /diagram-design:export-diagram을 써요.) 「이 다이어그램을 SVG와 PNG로 내보내 줘」처럼 말해도 돼요.
- SVG:
<svg>노드를 꺼내고 Google Fonts를 넣어 브라우저 · Figma · Illustrator에서 단독으로 그려져요. 오프라인용은--system-fonts로 글꼴 불러오기를 빼요. - PNG: Playwright로 기본 2배 해상도로 래스터화해요. 최초 한 번
pip install playwright && playwright install chromium이 필요해요. - 두 형식 모두 다이어그램만 담아요(풀 에디토리얼 판의 카드와 머리글은 빠져요).
--registry: 추적 가능한 블록 분해 패턴을 쓴 다이어그램은 모든 블록의data-block-*메타데이터를 구조화한.registry.json도 내보내요.
구조
점진적 공개 방식이에요. 시작할 때 에이전트는 스킬 이름과 설명만 보고, 요청이 맞으면 SKILL.md를 읽고, 종류 · 의미 패턴 · 모션 참고 문서는 필요할 때만 불러와요. 저장소에는 마켓플레이스 설정(Claude · Codex · Factory Droid · Qoder), 슬래시 명령과 프롬프트 템플릿(commands/, prompts/), 스킬 본체(skills/diagram-design/의 SKILL.md, references/, scripts/, assets/), CI 검사 스크립트(scripts/), 문서(docs/)가 있어요.
| 이렇게 부탁하면 | 에이전트가 읽는 것 |
|---|---|
| 「플로차트 만들어 줘」 | SKILL.md + references/type-flowchart.md |
| 「아키텍처 다이어그램을 만들어 줘」 | SKILL.md + references/type-architecture.md |
| 「이 마이그레이션에서 추가 · 삭제 · 변경된 것을 보여 줘」 | SKILL.md + references/type-architecture-delta.md |
| 「내 사이트에 맞춰 줘」 | SKILL.md + references/onboarding.md + references/style-guide.md |
| 「이 .drawio 파일을 발표용으로 다시 그려 줘」 | SKILL.md + references/import-drawio.md + references/output-spec.md + 고른 종류의 참고 문서 |
| 일반적인 정적 다이어그램 | SKILL.md + 그 종류 참고 문서 하나 |
종류가 몇 개로 늘어도 에이전트는 필요한 것만 읽어요. 내일 종류를 하나 더해도 다른 것은 바뀌지 않아요.
잘 되고 있다는 신호
- 일반 요청은
SKILL.md, 종류 참고 문서 하나, 핵심 참고 문서 최대 둘만 읽어요. - 그리기 전에 에이전트가 고른 종류 · 패턴 · 크기 · 줄일 것을 먼저 말해요.
- 결과물은 더블클릭으로 열리는
.html파일 하나이고, 오프라인에서 Google Fonts 말고는 네트워크 요청이 없어요(시스템 글꼴이면 전혀 없어요). - 스크린 리더가 다이어그램의 제목과 설명을 읽고, 움직임 줄이기 설정에서는 완성된 정적 프레임이 나와요.
python3 skills/diagram-design/scripts/self_check.py <파일>이OK를 출력해요.- 브랜드 온보딩 뒤에는 새 다이어그램이 내 사이트의 종이 · 잉크 · 포인트 · 글꼴을 쓰고, 충실도 영수증에 각각이 적혀요.
디자인 시스템 (한 단락)
포인트 색은 하나, 다이어그램마다 핵심 요소는 한두 개. 글꼴은 세 가지(Instrument Serif: 제목과 이탤릭 주석, Geist 산세리프: 노드 이름, Geist Mono: 기술적인 보조 글). 1px 헤어라인 테두리, 그림자 없음, 둥근 모서리는 최대 10px. 모든 좌표 · 너비 · 간격은 4로 나누어떨어져야 해요. 이 규칙은 타협하지 않아요. AI가 만든 느낌이 안 나게 하는 것이 바로 이것이에요. 모노는 포트 · URL · 필드 타입 같은 기술 내용에만 쓰고, 포인트 색을 입힌 핵심 노드가 독자의 눈을 한두 곳으로 이끌어요. 전체 명세는 SKILL.md에 있어요.
더 알아보기
- 프리미티브(Primitives): 에디토리얼 주석 말풍선(이탤릭 세리프와 점선 곡선 리더), 손그림 느낌, 터미널 창 느낌, IT · 클라우드 아이콘 라이브러리 같은 핵심 마크업 부품이에요. 참고 문서는
skills/diagram-design/references/의primitive-*.md에 있어요. - 이 스킬을 쓰지 말아야 할 때: Git에 두고 계속 바뀌는 다이어그램에는 Mermaid가 더 낫고, 정적 목록이나 비교는 글이나 표가 더 맞아요.
- 기여하기(Contributing): 새 종류, 가져오기 형식, 예시, 도구에 대한 풀 리퀘스트를 환영해요. 모든 PR은 Linux · Windows · macOS에서 검증 단계를 거쳐요. CONTRIBUTING.md를 보세요.
- 만든 사람: Cathryn Lavery. 공개 출하 리더보드 ShipRank, 쉬운 말 기술 사전 The Non-Technical Technical Dictionary, 생산성 저널 BestSelf.co도 만들었어요.
라이선스
MIT 라이선스예요.
평점
- 5점
- 0
- 4점
- 0
- 3점
- 0
- 2점
- 0
- 1점
- 0