AI에게 아키텍처나 사용자 여정을 그려 달라고 하면, 내용은 대체로 맞지만 읽는 순서가 없는 그림이 자주 나옵니다. 같은 모양의 상자와 화살표가 늘어서고, 중요한 흐름과 보조 정보가 같은 무게로 보입니다.
Diagram Design ↗은 이 문제를 다루는 Agent Skill입니다. Claude Code와 Codex 같은 에이전트에게 다이어그램의 내용과 함께 정보 위계, 여백, 색상, 연결선, 접근성 규칙을 줍니다. 에이전트는 이 규칙에 따라 HTML과 SVG 결과물을 만듭니다.
이 프로젝트는 다이어그램 유형을 많이 제공합니다. 그리고 독자가 무엇을 먼저 읽고 어디서 의미를 연결할지까지 설계 규칙으로 정합니다.
2026-09-14 · Diagram Design README의 2026-09-14 확인 내용 기준입니다. 이 공개 저장소는 자주 바뀌므로, 지원 유형과 설치 방식은 공식 문서에서 다시 확인합니다.
문제는 SVG 생성이 아니라 편집 결정입니다
Mermaid, draw.io, Excalidraw, SVG로 다이어그램을 표현할 수 있습니다. 하지만 어떤 정보를 생략하고, 무엇을 강조하고, 독자가 어느 방향으로 읽게 할지는 도구가 정해 주지 않습니다.
Diagram Design의 README ↗는 이 문제를 “generic rounded boxes”의 반복으로 설명합니다. 프로젝트는 아키텍처, 흐름, 시퀀스, ER 모델, 타임라인, 사용자 여정, 배포 같은 39개 유형을 제시합니다. 그리고 유형을 고른 뒤 적용할 편집 규칙을 함께 정합니다.
flowchart TD
A[문서의 핵심 질문] --> B[표현 유형 선택]
B --> C[정보 위계 결정]
C --> D[레이아웃·색상·연결선 규칙 적용]
D --> E[HTML + SVG 생성]
E --> F[접근성·독해성 사람 검토]
이 흐름에서 AI는 요구사항을 적절한 시각 형식으로 옮기고, 정해진 제약 안에서 초안을 만듭니다. 사람은 “이 그림이 독자의 질문에 답하는가”를 검토합니다.
스킬은 다이어그램에 무엇을 강제할까
공식 skill 문서 ↗는 내용의 의미와 레이아웃을 분리합니다. 큐, 신뢰 경계, 정책 추적 같은 의미 패턴은 기존 시각 유형 위에 얹습니다. 그래서 매번 새로운 도형 체계를 만들지 않아도 됩니다.
1. 강조는 적게, 위계는 분명하게
README는 강조색을 독자가 먼저 봐야 할 1~2개 요소에만 쓰고, 나머지는 기본 색과 보조 색으로 처리하는 원칙을 제시합니다. 모든 상자를 같은 크기·같은 색으로 만들면, AI가 정보를 빠뜨리지 않았어도 독자는 중요도를 판별할 수 없습니다.
Atlassian DESIGN.md도 제품 UI에 디자인 의도를 전달합니다. DESIGN.md는 제품 전반의 토큰·컴포넌트 문맥을 다룹니다. Diagram Design은 설명 그림 한 장에서 어떤 메시지를 가장 먼저 보일지를 다룹니다.
2. 연결선도 문장처럼 읽혀야 합니다
스킬은 대각선 연결, 라벨과 선의 충돌, 지나친 교차를 피하라고 명시합니다. 연결선은 노드 뒤에 둡니다. 독자는 화살표로 요소 사이의 관계를 읽습니다.
3. 정적 결과물을 기본으로 둡니다
프로젝트는 결과물을 self-contained HTML과 SVG로 만듭니다. 기본 출력은 별도의 build step이나 JavaScript 없이 브라우저에서 열 수 있습니다. motion은 순서를 설명할 때만 선택적으로 더합니다.
Claude Code에서 HTML을 검토 화면으로 쓰는 방법도 같은 방식을 씁니다. HTML은 인터랙션도 표현할 수 있지만, 문서에는 빠르게 공유하고 검토할 수 있는 정적 결과물이 더 자주 필요합니다.
접근성 규칙을 생성 단계에 넣습니다
다이어그램은 색상과 위치에 의미를 숨기기 쉽습니다. 공식 문서는 색·배경 대비, SVG의 이름과 설명, motion 감소 선호를 고려하도록 안내합니다. 접근성을 마지막에 점검하지 않고, 생성 단계의 제약으로 넣습니다.
DTCG와 DESIGN.md에서 다룬 디자인 토큰은 역할이 다릅니다. 토큰은 색·간격·타이포그래피를 일관되게 쓰게 하지만, 다이어그램의 정보 위계까지 정해 주지는 않습니다. 스킬은 토큰 위에 “표현을 선택하고 검토하는 절차”를 더합니다.
우리 팀 문서에 적용하는 최소 규칙
프로젝트를 설치하지 않아도 규칙은 가져올 수 있습니다. 팀이 반복해서 만드는 다이어그램 하나를 고르고, 아래 네 가지를 짧은 스킬이나 문서 규칙으로 정합니다.
- 독자의 질문을 한 문장으로 적습니다. 아키텍처를 모두 보여 주는 대신, 예를 들어 “요청은 어디서 인증되고 실패는 어디로 가는가”처럼 질문을 좁힙니다.
- 유형을 먼저 고릅니다. 시간의 흐름이면 sequence나 timeline, 소유 관계면 tree나 org chart, 상태 변화면 state diagram처럼 표현의 문법을 맞춥니다.
- 강조와 금지를 정합니다. 핵심 경로 1개, 강조색 1개, 노드당 최대 라벨 길이, 피해야 할 연결선 교차처럼 검토 가능한 규칙을 둡니다.
- 본문에도 결론을 씁니다. 다이어그램만 보고 이해해야 하는 정보를 만들지 말고, 그림 아래에 핵심 해석과 텍스트 대안을 남깁니다.
이 규칙은 Figma MCP와 AI 에이전트 디자인처럼 캔버스와 실제 컴포넌트에 접근하는 도구를 대체하지 않습니다. PR 설명, RFC, 장애 회고, 제품 문서처럼 한 번 읽고 판단해야 하는 시각 자료의 초안 품질을 일정하게 유지합니다.
설치보다 먼저 정해야 할 것
Diagram Design의 공식 README ↗는 Claude Code와 Codex용 marketplace 설치 경로를 제공합니다. 저장소의 공용 스킬 디렉터리는 여러 Agent Skills 호스트에서 쓸 수 있습니다. 팀에 도입한다면 설치 전에 “어떤 문서를 어떤 독자에게 설명할 것인가”를 먼저 정합니다.
다이어그램 규칙이 있어도 디자인 리뷰는 필요합니다. 규칙은 반복되는 실수를 초안 단계에서 줄입니다. 동일한 상자, 과한 강조색, 읽기 어려운 연결선, 색에만 의존한 의미 전달이 그런 실수입니다.
참고 자료
- Diagram Design GitHub 저장소 ↗ — 프로젝트 개요와 라이선스
- Diagram Design README ↗ — 지원 유형, 출력 형식, 설치·브랜드 적용 안내
- Diagram Design SKILL.md ↗ — 디자인·연결선·접근성 규칙
- 공식 갤러리 ↗ — 다이어그램 유형과 테마 예시
- GeekNews 소개 ↗ — 한국어 요약