다이어그램 디자인
한국어 요청이면 도식 안의 모든 글자(제목·라벨·보조 설명·범례)를 한국어로 쓰고, 영어 보조 라벨은 꼭 필요한 고유명사만 남긴다. 브랜드 스타일을 물으면 사용자가 정하지 않았을 때 기본 스타일로 바로 진행한다. (한국어판 수정: 방구석프로 bangpro.ai.kr · 원본: github.com/cathrynlavery/diagram-design, MIT License)
인라인 SVG와 편집 디자인 시스템을 갖춘 자체 포함 HTML 파일로 다이어그램을 생성합니다.
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. 사용 시기
독자가 산문, 표 또는 글머리 기호 목록보다 시각적 요소에서 더 많은 것을 배울 때 45가지 시각적 유형(§3) 중 하나를 사용하세요.
사용하지 말아야 할 경우:
- 빠른 유니코드 다이어그램 → wiretext와 같은 별도의 일반 텍스트 도구를 사용하세요. 이 스킬은 이를 제공하지 않습니다.
- 항목 목록 → 표 또는 글머리 기호.
- 속성만 있는 전/후 → 표; 토폴로지 변경 → 아키텍처 델타.
- 한 가지 모양의 "다이어그램" → 그냥 문장을 쓰세요.
그리기 전에 스스로에게 물어보세요: 독자가 잘 작성된 단락보다 이것에서 더 많이 배울 수 있을까요? 그렇지 않다면 그리지 마세요.
3. 선택: 의미론적 패턴, 그다음 시각적 유형
동작, 상태, 시행 또는 위험이 의미를 전달할 때 먼저 references/semantic-patterns.md를 로드하고 하나의 기본 패턴을 선택하세요. 그런 다음 레이아웃에 가장 가까운 시각적 유형을 선택하세요. 일치하는 패턴이 없으면 유형을 직접 선택하세요.
| 행동 트리거 | 의미론적 패턴 → 가장 가까운 유형 |
|---|---|
| 팬인, 대기열 깊이, 유한 용량, 병목 | 팬인 대기열 / 병목 → 데이터 흐름 |
| 단계에 걸친 반복 질문/입력/거버넌스/출력 슬롯 | 의미론적 슬롯이 있는 단계 프레임워크 → 프로세스 |
| 대화 또는 느슨한 입력이 구조화된 내구성 있는 아티팩트가 됨 | 비구조적 입력 → 구조화된 아티팩트 → 데이터 흐름 |
| 두 개의 규칙 추적이 통과/실패/건너뜀/도달 안 됨 및 첫 번째 분기를 필요로 함 | 쌍을 이루는 정책 평가 추적 → 순서도 |
| 신뢰 경계 + 허용/금지된 진입 또는 배포 경로 | 안전한 포장 도로 → 아키텍처 |
| 적용되는 위치별로 그룹화된 제어 | 거버넌스/제어 카탈로그 → 계층 스택 |
| 방어가 이전 격차를 보상하고 잔여 위험이 전파됨 | 보안 계층 보상 → 계층 스택 |
| 계층적, ID 주소 지정 가능 분해, 블록별 I/O, 제약 조건 및 코드 링크 필요 | 추적 가능한 블록 분해 → 트리 |
| 한 주제가 단계, 대기, 재시도, 취소 및 최종 결과를 통해 진행됨 | 수명 주기 단계 맵 → 상태 머신 |
패턴은 의미론적 기본 요소와 더 엄격한 예산을 소유하고, 유형은 레이아웃 문법을 소유합니다. 모션이 요청되거나 정렬된 변경을 실질적으로 명확히 하는 경우에만 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 |
| 두 변수의 상관 관계 또는 분포; 거품형(세 변수) 및 비스웜(한 변수, 항목당 점) 변형 | 산점도 | 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 |
| 고객이 하는 일과 서비스가 숨기는 일을 가시성 선으로 단계별로 표시 | 서비스 블루프린트 | 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 산스체로 작성하세요. |
| 모든 노드에 동일한 상자 | 계층 구조를 지움 |
| 다이어그램 영역 내부에 떠 있는 범례 | 노드와 충돌 |
| 마스킹 사각형이 없는 화살표 레이블 | 선을 통해 번짐 |
화살표의 세로 writing-mode 텍스트 | 읽을 수 없음 |
| 기본으로 3개의 동일한 너비 요약 카드 | 일반 그리드 — 너비를 다양화하세요 |
| 모든 요소에 그림자 | 그림자는 이제 그만. 테두리가 대세입니다. |
상자에 rounded-2xl | 최대 반경 6–10px 또는 없음 |
| 모든 "중요한" 노드에 코랄 | 코랄은 1–2개의 편집 강조이지 신호 시스템이 아닙니다. |
| Mermaid의 렌더러 레이아웃 재현 | 편집 레이아웃을 만드는 대신 자동 간격 및 라우팅을 가져옴 |
| 6가지 §6 커넥터 규칙 위반 | 자동 실패: 대각선 기울기, 스트로크에 닿는 레이블, 이후 노드에 의해 잘린 마스크, 겹치는 경로, 공유 부착 지점, 비종점 상자 뒤 통과 |
유형별 안티패턴은 가이드에 연결된 각 유형 참조에 있습니다.
5. 디자인 시스템
디자인 시스템은 스킨 가능합니다. references/style-guide.md는 색상, 타이포그래피, 토큰 및 기본 팔레트의 단일 진실 공급원입니다. 이 파일은 의미론적 역할(용지, 잉크, 음소거, 강조, 링크 등)을 명명합니다. 브랜드를 적용하려면 style-guide.md를 편집하거나 references/onboarding.md의 URL 기반 흐름을 실행하세요.
아래 사양 또는 유형 참조에서 "잉크", "강조", "음소거" 등을 언급하면
style-guide.md에서 현재 16진수 값을 찾으세요.
유형 참조 스니펫은 역할을 자리 표시자로 작성합니다: {ink}, {ink @ 0.40}(불투명도가 있는 역할의 경우), {node-name}, {sublabel}, {eyebrow}, {arrow-label}, {title}, {callout}(글꼴의 경우). 내보내기 전에 style-guide.md에 대해 모든 자리 표시자를 확인하세요.
…
[번역을 위해 잘림]