다이어그램 디자인
자체 포함된 HTML 파일(인라인 SVG 포함)과 편집 디자인 시스템으로 다이어그램을 생성합니다.
45가지 시각적 유형. 의미론적 패턴은 동작을 설명하고, 유형 참조는 레이아웃을 설명합니다.
0. 첫 번째 설정 — 스타일 가이드 게이트
새 프로젝트에서 첫 번째 다이어그램을 생성하기 전에 스타일 가이드가 사용자 지정되었는지 확인하세요.
기본 스킨으로 다이어그램을 브랜드 프로젝트에 무음으로 배포하지 마십시오.
먼저 references/profiles.md 기준에 따라 프로젝트의 .diagram-design 마커를 확인하세요. 마커가 성공적으로 확인되면 해당 프로필이 선택되고 이 게이트를 우회합니다. 해당 참조 문서가 실패, 보호된 기본값 및 저장 동작을 관리합니다.
references/style-guide.md를 열고 기본 토큰을 확인하세요. 여전히 배송 기본값(배경 #f5f5f5, 잉크 #2d3142, 강조색 #bf4520)인 경우 일시 중지하고 사용자에게 묻습니다:
"이 프로젝트의 첫 번째 다이어그램이며 스타일 가이드가 여전히 기본값입니다. 지금 사용자 지정하시겠습니까? 옵션: (a) 웹사이트 URL, (b) 설치된 스킬, (c) 로컬 폴더/디자인 시스템, (d) 토큰 붙여넣기, (e) 기본값 유지, (f) 저장된 프로필 불러오기."
그런 다음 references/onboarding.md의 해당 섹션에 따라 분기합니다. (f) 의 경우 references/profiles.md를 따릅니다.
스타일 가이드가 사용자 지정되거나 사용자가 명시적으로 기본값을 선택한 경우 이후 실행 시 이 게이트를 건너뜁니다. 선행 프로필 헤더는 복사된 활성 프로필의 이름을 지정합니다. 헤더가 없고, 배송 기본값과 다른 의미론적 역할 값이나 타이포그래피 패밀리가 있는 경우 사용자 지정-저장되지 않음을 의미합니다. 게이트를 건너뛰고 프로필로 저장하도록 제안합니다. 마커나 헤더가 없는 모든 기본값 토큰은 게이트를 트리거합니다. 온보딩 후에는 references/profiles.md에 따라 명명된 클라이언트 프로필로 저장하도록 제안합니다.
1. 철학
가장 고품질의 움직임은 대개 삭제입니다.
도식에 적용하면:
- 모든 노드는 별개의 아이디어를 나타냅니다. 항상 함께 이동하는 두 노드는 하나의 노드입니다.
- 모든 연결은 정보를 전달합니다. 레이아웃에서 관계가 명확하면 선을 제거하세요.
- 산호색은 편집적 강조이며 플래그가 아닙니다. 다이어그램당 1-2개의 초점 노드. 5개 노드에 사용하면 신호가 사라집니다.
- 도식은 모든 것이 추가되었을 때 완성되는 것이 아니라, 아무것도 제거할 수 없을 때 완성됩니다.
목표 밀도: 4/10. 기술적으로 완전할 정도로 충분합니다. 가이드가 필요할 정도로 밀집되지 않아야 합니다. 9노드 이상이면 두 개의 다이어그램일 가능성이 높습니다.
2. 사용 시기
독자가 산문, 표 또는 글머리 기호 목록보다 시각 자료에서 더 많은 것을 배울 수 있을 때 §3의 45가지 시각적 유형 중 하나를 사용하세요.
사용하지 말아야 할 경우:
- 빠른 유니코드 다이어그램 → wiretext와 같은 별도의 일반 텍스트 도구. 이 스킬은 이를 제공하지 않습니다.
- 목록 → 표 또는 글머리 기호.
- 속성만 있는 이전/이후 → 표; 토폴로지 변경 → 아키텍처 델타.
- 단일 도형 "다이어그램" → 그냥 문장을 작성하세요.
그리기 전에 질문하세요: 독자가 잘 쓰여진 단락보다 이것에서 더 많이 배울까요? 아니라면 그리지 마세요.
3. 선택: 의미론적 패턴, 그다음 시각적 유형
동작, 상태, 시행 또는 위험이 의미를 전달할 때 먼저 references/semantic-patterns.md를 로드하고 하나의 기본 패턴을 선택하세요. 그런 다음 레이아웃에 가장 가까운 시각적 유형을 선택하세요. 일치하는 패턴이 없으면 유형을 직접 선택하세요.
| 동작 트리거 | 의미론적 패턴 → 가장 가까운 유형 |
|---|---|
| 팬인, 큐 깊이, 유한 용량, 병목 | 팬인 큐 / 병목 → 데이터 흐름 |
| 단계별로 반복되는 질문/입력/거버넌스/출력 슬롯 | 의미론적 슬롯을 가진 단계 프레임워크 → 프로세스 |
| 대화 또는 느슨한 입력이 구조화된 지속적 아티팩트가 됨 | 비정형 입력 → 구조화된 아티팩트 → 데이터 흐름 |
| 두 개의 규칙 추적이 통과/실패/건너뜀/미도달 및 첫 번째 분기점이 필요함 | 쌍을 이루는 정책 평가 추적 → 순서도 |
| 신뢰 경계와 허용/금지 진입 또는 배포 경로 | 안전한 포장 도로 → 아키텍처 |
| 시행 위치별로 그룹화된 제어 | 거버넌스/제어 카탈로그 → 계층 스택 |
| 방어 체계가 이전 격차를 보완하고 잔여 위험이 전파됨 | 보안 계층 보완 → 계층 스택 |
| 블록별 I/O, 제약 조건 및 코드 링크가 필요한 계층적, ID 주소 지정 가능 분해 | 추적 가능한 블록 분해 → 트리 |
| 한 주제가 단계를 진행하고, 대기, 재시도, 취소 및 최종 결과를 거침 | 라이프사이클 단계 맵 → 상태 머신 |
패턴은 의미론적 기본 요소와 더 엄격한 예산을 소유하고, 유형은 레이아웃 문법을 소유합니다. 모션이 요청되거나 순서 변경을 실질적으로 명확히 할 때만 references/animation.md를 사용하세요. 정적 상태가 기본값입니다.
시각적 유형 가이드 (45가지)
| 보여주려는 내용이… | 사용 | 참조 |
|---|---|---|
| 한 스냅샷의 구성 요소 + 연결; 중첩된 관리 vs 트래픽 범위 | 아키텍처 | type-architecture.md |
| 동기화된 이전 / 이후 토폴로지 간의 구조적 변경(변경 명세서 포함) | 아키텍처 델타 | type-architecture-delta.md |
| 단계 또는 부서별 레거시 IT 환경; 이전 상태 표시 | IT 현황 | type-it-state.md |
| 분기가 있는 의사 결정 로직 | 순서도 | type-flowchart.md |
| 행위자 간의 시간 순서 메시지 | 시퀀스 | type-sequence.md |
| 상태 + 전환 + 가드 | 상태 머신 | type-state.md |
| 엔터티 + 필드 + 관계 | ER / 데이터 모델 | type-er.md |
| 시간에 배치된 이벤트 | 타임라인 | type-timeline.md |
| 핸드오프가 있는 교차 기능 프로세스 | 스윔레인 | type-swimlane.md |
| 2축 위치 지정 / 우선순위 지정 | 쿼드런트 | type-quadrant.md |
| 3-5개 정량적 기준에 걸쳐 점수가 매겨진 여러 엔터티 | 레이더 / 스파이더 | type-radar.md |
| 순환 범주에 걸친 하나의 정량적 계열; 각도=범주, 반경=크기 | 폴라 차트 | type-polar.md |
| 강화 순환; 마지막 단계가 첫 번째 단계를 공급하고 허브가 상태를 축적함 | 루프 | type-loop.md |
| 포함/범위를 통한 계층 구조 | 중첩 | type-nested.md |
| 부모 → 자식 관계 | 트리 | type-tree.md |
| 인간/에이전트/팀 소유권, 보고, 라우팅, 에스컬레이션 | 조직도 | type-org-chart.md |
| 쌓인 추상화 수준 | 계층 스택 | type-layers.md |
| 하나의 객체 부품을 한 축을 따라 분해: 분해, 개봉, 조립 순서 | 분해 축측도 | type-exploded.md |
| 한 층 또는 부지를 위에서 각도로 본 모습: 가구가 있는 방, 단계별 건물 | 축측 평면도 | type-axonometric-plan.md |
| 집합 간의 중첩 | 벤 | type-venn.md |
| 순위가 매겨진 계층 구조 또는 전환 드롭오프 | 피라미드 / 퍼널 | type-pyramid.md |
| 범주 간 정량적 비교 | 막대 차트 | type-bar.md |
| 시작 합계에서 끝 합계로 부호 있는 기여(예산 브리지, 인원 델타)로 연결 | 워터폴 | type-waterfall.md |
| 상대적 크기가 핵심인 전체의 부분 | 트리맵 | type-treemap.md |
| 교차 집계된 데이터; 채우기가 셀당 값을 인코딩 | 히트맵 | type-heatmap.md |
| 시간에 따른 연속 추세, 정확히 두 상태 간의 변화(경사 그래프), 계열당 하나의 분포(릿지라인), 여러 스냅샷 간 순위 이동(범프) | 라인 차트 | type-line.md |
| 타임라인의 작업 및 단계 | 간트 차트 | type-gantt.md |
| 두 변수의 상관 관계 또는 분포; 버블(세 변수), 비즈웜(한 변수, 항목당 점) 및 상자 그림(그룹당 5수 요약) 변형 | 산점도 | type-scatter.md |
| 컨테이너 클러스터의 엔드 투 엔드 데이터 스택 | 하이 레벨 | type-high-level.md |
| 데이터 핸드오프가 포함된 다중 행위자 순차 프로세스 | 프로세스 | type-process.md |
| 품질 수준 및 액세스 정책이 포함된 다중 계층 데이터 스토리지 | 메달리온 | type-medallion.md |
| 역할 범위 데이터 흐름: 각 파이프라인 단계에서 누가 무엇을 하는지 | 데이터 흐름 | type-data-flow.md |
| 데이터 플랫폼의 통합 토폴로지 — 소스 → 코어 → 소비자 | DP 통합 | type-dp-integration.md |
| 역할/구성 요소별 액세스 권한 매트릭스 | DP 보안 매트릭스 | type-dp-security-matrix.md |
| 단계를 거치면서 분할 및 병합되는 수량, 대역폭=양 | 산키 | type-sankey.md |
| 범주별로 그룹화된 하나의 관찰된 효과의 원인(근본 원인 분석) | 피쉬본 | type-fishbone.md |
| 진화에 대한 가치 사슬 — 무엇을 구축, 구매할지, 그리고 무엇이 움직이는지 | 워들리 맵 | type-wardley.md |
| 상태별 진행 중인 작업(WIP 한도 및 차단 항목 포함) | 칸반 | type-kanban.md |
| 경험 단계에서 사람이 하는 일과 그 느낌 | 사용자 여정 | type-journey.md |
| 고객이 하는 일 vs 서비스가 숨기는 일(가시성 선 포함) | 서비스 블루프린트 | type-service-blueprint.md |
| 소프트웨어가 실행되는 위치 — 영역, 호스트, 아티팩트, 복제본, 포트 | 배포 | type-deployment.md |
| 무엇이 무엇에 의존하는지(팬인 및 트리로 표현할 수 없는 순환 포함) | 의존성 그래프 | type-dependency.md |
| 연산, 상속, 구성을 포함한 클래스(다른 UML 경로는 별도) | UML 클래스 | type-uml-class.md |
| 릴리스로 분할된 내러티브 백본(컷 라인 포함) | 스토리 맵 | type-story-map.md |
| 물리적 테이블: SQL 유형, 제약 조건, 인덱스, 열 수준 FK | 데이터베이스 스키마 | type-db-schema.md |
경험상 규칙:
- 3열 표가 동일한 내용을 전달한다면 표를 선택하세요.
- 두 유형이 유용해 보이면 기본 축을 선택하세요. 의미론적 패턴은 두 번째 레이아웃 문법이 아닌 동작별 기본 요소를 추가할 수 있습니다.
- 복잡도 예산(§7)을 초과했다면 개요 + 세부 정보로 분할하세요.
그리기 전에 가이드에 링크된 선택한 유형 참조를 항상 로드하세요. 위에서 라우팅된 경우 semantic-patterns.md도 로드하세요. 애니메이션이 선택된 경우 animation.md를 로드하세요.
그리기 전에 확인
렌더링하기 전에 하나의 짧은 메시지로 계획을 명시하세요: 선택한 시각적 유형(및 라우팅된 경우 의미론적 패턴), 크기 사전 설정, 복잡도 예산(§7)이 강제로 제외할 모든 것. 사용자에게 연락이 가능하면 그리기 전에 방향을 바꾸도록 하세요. 연락이 불가능하면 진행하고 결과물 옆에 가정 사항을 기록하세요. 요청이 이미 유형, 크기 및 내용을 정확히 지정한 경우에만 일시 중지를 건너뜁니다.
4. 범용 안티패턴
다음은 모든 유형의 "AI 슬롭" 도식을 나타냅니다:
| 안티패턴 | 실패 이유 |
|---|---|
| 다크 모드 + 시안/보라색 글로우 | 디자인 결정 없이 "기술적으로" 보임 |
| JetBrains Mono를 포괄적인 "개발자" 글꼴로 사용 | 모노는 기술적 콘텐츠(포트, 명령어, URL)용입니다. 이름은 Geist sans를 사용하세요. |
| 모든 노드에 동일한 상자 사용 | 계층 구조를 지움 |
| 다이어그램 영역 내에 떠 있는 범례 | 노드와 충돌 |
| 마스킹 사각형이 없는 화살표 레이블 | 선을 통해 새어 나옴 |
화살표의 세로 writing-mode 텍스트 | 읽을 수 없음 |
| 기본값으로 3개의 동일한 너비 요약 카드 | 일반적인 그리드 — 너비를 다양하게 |
| 모든 요소에 그림자 | 그림자는 아웃. 테두리가 인. |
상자에 rounded-2xl | 최대 반경 6–10px 또는 없음 |
| 모든 "중요한" 노드에 산호색 사용 | 산호색은 1-2개의 편집적 강조이며 신호 시스템이 아님 |
| Mermaid의 렌더러 레이아웃 재현 | 편집 레이아웃 대신 자동 간격 및 라우팅 가져오기 |
| 여섯 가지 §6 커넥터 규칙 위반 | 자동 실패: 대각선 기울기, 선에 닿는 레이블, 이후 노드에 의해 잘린 마스크, 겹치는 경로, 공유 부착 지점, 비종단점 상자 뒤를 통과하는 이동 |
유형별 안티패턴은 가이드에 링크된 각 유형 참조에 있습니다.
5. 디자인 시스템
디자인 시스템은 스킨을 변경할 수 있습니다. references/style-guide.md는 색상, 타이포그래피, 토큰 및 기본 팔레트의 단일 진실 공급원입니다. 이 파일은 의미론적 역할(paper, ink, muted, accent, link, …)의 이름을 지정합니다. 브랜드를 적용하려면 style-guide.md를 편집하거나 references/onboarding.md의 URL 기반 흐름을 실행하세요.
아래 또는 유형 참조의 사양이 "ink", "accent", "muted" 등을 언급하는 경우
style-guide.md에서 현재 16진수 값을 조회하세요.
유형 참조 스니펫은 역할을 자리 표시자로 작성합니다: {ink}, 투명도의 역할에 대해 {ink @ 0.40}, 글꼴에 대해 {node-name}, {sublabel}, {eyebrow}, {arrow-label}, {title}, {callout}. 방출하기 전에 모든 자리 표시자를 style-guide.md에 대해 확인하세요.
의미론적 역할 (한눈에)
| 역할 | 목적 |
|---|---|
paper, paper-2 | 페이지 배경 및 컨테이너 배경 |
ink | 기본 텍스트 / 선 |
muted, soft | 보조 텍스트 / 보조 선 |
accent | 핵심 강조 색상 |
link | 하이퍼링크 색상 |
success, warning, error | 상태 표시기(초록, 노랑, 빨강) |
coral | 편집적 강조(1-2개 노드에만 사용) |
border | 기본 테두리 |
surface, surface-hover | 카드 및 대화형 요소 배경 |
타이포그래피
style-guide.md에서 글꼴 계층 구조를 조회하세요. 유형 참조는 특정 요소에 대한 명명된 글꼴 변수를 참조합니다. 헤드라인, 본문, 코드 및 라벨 글꼴을 혼합하지 마십시오.
6. 커넥터 규칙
- 염가형 경로 없음. 대각선 기울기는 자동 실패입니다. 모든 커넥터는 직교(맨해튼) 또는 직선이어야 하며, 각도가 없어야 합니다.
- 레이블은 선 위에 떠 있어서는 안 됩니다. 각 레이블에는 불투명도
bg-paper마스킹 사각형이 있어야 합니다. - 마스크는 이후 노드에 의해 잘려서는 안 됩니다. 레이블을 올바른 z-순서로 배치하거나 잘림을 방지하기에 충분한 간격을 두십시오.
- 경로가 겹쳐서는 안 됩니다. 교차 지점에서 연결 해제되거나 간격을 유지하십시오.
- 부착 지점은 공유되지 않습니다. 각 노드는 고유한 진입/종료 가장자리 포트를 가집니다.
- 이동은 비종단점 상자 뒤를 통과하지 않습니다. 항상 앞으로 라우팅하거나 충분히 멀리 우회하십시오.
이러한 규칙을 위반하면 자동 실패입니다. 유형별 참조는 추가 규칙을 추가할 수 있습니다.
7. 복잡도 예산
- 한 다이어그램에 최대 15개 노드. 15개 이상은 개요 + 세부 정보로 분할하세요.
- 최대 3개 노드 깊이 (트리, 중첩).
- 화살표당 하나의 라벨 (분할 또는 조건부 화살표는 예외).
- 최대 2개 수준의 그룹화 (예: 경계 상자 내의 경계 상자).
- 커넥터당 하나의 굽힘. 더 복잡한 라우팅은 중간 노드를 제안합니다.
이 예산을 초과하면 생성하기 전에 사용자에게 경고하고 분할을 제안하세요.
8. 출력 형식
기본 출력은 인라인 SVG가 포함된 자체 포함 HTML 파일입니다. 명시적으로 요청된 경우에만 SVG 또는 PNG로 내보내기를 지원하세요.
HTML 파일 구조:
<!DOCTYPE html><html><head><style>...</style></head><body><svg>...</svg></body></html>- 모든 CSS는
<style>블록에 인라인으로 포함됩니다. 외부 스타일시트 없음. - SVG는
<svg>요소 내에 포함됩니다. 외부 참조 없음. <meta charset="UTF-8">및 적절한 뷰포트 설정을 포함하세요.
파일 이름: diagram-[type]-[brief-description].html
9. 가져오기 지원
이 스킬은 가져오기를 위해 다음 형식을 지원합니다:
| 형식 | 동작 |
|---|---|
.drawio | XML 구문 분석. 오프셋을 수정하고 레이블을 정리합니다. 그리드 vs 자유형 레이아웃을 감지합니다. |
.excalidraw | JSON 구문 분석. 요소를 매핑하고, 서식을 깔끔하게 하고, 그룹 구조를 유지합니다. |
.mmd (Mermaid) | 순서도, 시퀀스, 상태 다이어그램 및 간트 차트의 하위 집합을 가져옵니다. 자동 라우팅을 편집 레이아웃으로 변환합니다. |
가져오기 요청을 감지하려면 파일 확장자 또는 import: 지시문을 확인하세요.
가져온 콘텐츠는 디자인 시스템을 다시 적용해야 합니다. 원래 스타일을 제거하고 관련 유형 참조를 적용하세요.
10. 버전 및 프로필 관리
references/profiles.md는 클라이언트/프로젝트 프로필을 저장하고 로드하는 방법을 설명합니다. 프로필은 다음을 저장합니다:
style-guide.md에 저장된 맞춤형 디자인 토큰.diagram-design프로젝트 마커- 선호하는 출력 형식, 크기 사전 설정
최초 온보딩 또는 스타일 가이드 저장 요청 후에만 프로필을 저장하세요.
11. 절차 요약
- 첫 번째 사용 시 스타일 가이드 사용자 지정 게이트를 실행합니다.
- 의미론적 패턴(
semantic-patterns.md)을 선택하거나 유형을 직접 선택합니다. - 레이아웃 참조(가이드의
type-*.md)를 로드합니다. - 복잡도 예산을 확인합니다.
- 다이어그램을 렌더링하기 전에 계획을 확인합니다.
- 자체 포함 HTML, SVG 또는 PNG를 출력합니다.
- 저장 제안, 프로필 저장, 그렇지 않으면 완료합니다.