다이어그램 디자인
한국어 요청이면 도식 안의 모든 글자(제목·라벨·보조 설명·범례)를 한국어로 쓰고, 영어 보조 라벨은 꼭 필요한 고유명사만 남깁니다. 브랜드 스타일을 물으면 사용자가 정하지 않았을 때 기본 스타일로 바로 진행합니다. (한국어판 수정: 방구석프로 bangpro.ai.kr · 원본: github.com/cathrynlavery/diagram-design, MIT License)
인라인 SVG와 편집 디자인 시스템이 포함된 독립형 HTML 파일로 다이어그램을 생성합니다.
45가지 시각적 유형. 의미 패턴은 동작을 설명하고, 유형 참조는 레이아웃을 설명합니다.
0. 첫 설정 — 스타일 가이드 게이트
새 프로젝트에서 첫 번째 다이어그램을 생성하기 전에 스타일 가이드가 사용자 정의되었는지 확인하세요.
기본 스킨의 다이어그램을 브랜드 프로젝트에 자동으로 배포하지 마세요.
먼저 [references/profiles.md](references/profiles.md)에 따라 프로젝트의 .diagram-design 마커가 있는지 확인하세요. 마커가 성공적으로 해석되면 해당 프로필이 선택되어 이 게이트를 건너뜁니다. 해당 참조는 실패, 보호된 기본값 및 저장 동작을 관리합니다.
[references/style-guide.md](references/style-guide.md)를 열고 기본 토큰을 확인하세요. 아직 배포된 기본값(용지 #f5f5f5, 잉크 #2d3142, 악센트 #bf4520)인 경우 잠시 멈추고 사용자에게 물어보세요:
"이 프로젝트의 첫 번째 다이어그램이며 스타일 가이드가 아직 기본값입니다. 지금 사용자 정의하시겠습니까? 옵션: (a) 웹사이트 URL, (b) 설치된 스킬, (c) 로컬 폴더/디자인 시스템, (d) 토큰 붙여넣기, (e) 기본값 유지, (f) 저장된 프로필 불러오기."
그런 다음 [references/onboarding.md](references/onboarding.md)의 해당 섹션에 따라 분기하고, **(f)**의 경우 [references/profiles.md](references/profiles.md)를 따르세요.
스타일 가이드가 사용자 정의된 후(또는 사용자가 명시적으로 기본값을 선택한 경우) 이후 실행에서는 이 게이트를 건너뜁니다. 선행하는 프로필 헤더는 복사된 활성 프로필의 이름을 지정합니다. 헤더가 없고, 배포된 기본값과 다른 의미적 역할 값이나 타이포그래피 패밀리가 있는 경우 사용자 정의-저장되지 않음을 의미합니다: 게이트를 건너뛰고 프로필로 저장하도록 제안하세요. 모든 토큰이 기본값이고 마커나 헤더가 없으면 게이트가 트리거됩니다. 온보딩 후 references/profiles.md에 따라 명명된 클라이언트 프로필로 저장하도록 제안하세요.
1. 철학
가장 고품질의 움직임은 대개 삭제입니다.
도식에 적용:
- 모든 노드는 별개의 아이디어를 나타냅니다. 항상 함께 움직이는 두 노드는 하나의 노드입니다.
- 모든 연결은 정보를 전달합니다. 레이아웃에서 관계가 명확하면 선을 제거하세요.
- 산호색은 편집적 강조이며, 플래그가 아닙니다. 다이어그램당 1–2개의 초점 노드. 5개 노드에 사용하면 신호가 사라집니다.
- 도식은 모든 것이 추가되었을 때 완성되는 것이 아닙니다. 아무것도 제거할 수 없을 때 완성됩니다.
목표 밀도: 4/10. 기술적으로 완전할 만큼 충분히. 가이드가 필요할 정도로 조밀하지 않게. 9노드 이상이면 아마도 두 개의 다이어그램입니다.
2. 사용 시기
독자가 산문, 표, 글머리 기호 목록보다 시각적 자료에서 더 많은 것을 배울 수 있을 때 45가지 시각적 유형(§3) 중 하나를 사용하세요.
다음에는 사용하지 마세요:
- 빠른 유니코드 다이어그램 → wiretext와 같은 별도의 일반 텍스트 도구. 이 스킬은 제공하지 않습니다.
- 사물 목록 → 표 또는 글머리 기호.
- 속성만 있는 before/after → 표; 토폴로지 변경 → 아키텍처 델타.
- 단일 모양 "다이어그램" → 그냥 문장을 쓰세요.
그리기 전에 물어보세요: 독자가 잘 작성된 문단보다 이것에서 더 많은 것을 배울 수 있을까요? 아니오라면 그리지 마세요.
3. 선택: 의미 패턴, 그다음 시각적 유형
동작, 상태, 시행, 또는 위험이 의미를 전달할 때 먼저 [references/semantic-patterns.md](references/semantic-patterns.md)를 불러와서 하나의 기본 패턴을 선택하세요. 그다음 레이아웃에 가장 가까운 시각적 유형을 선택하세요. 일치하는 패턴이 없으면 유형을 직접 선택하세요.
| 동작 트리거 | 의미 패턴 → 가장 가까운 유형 |
|---|---|
| 팬인, 큐 깊이, 유한 용량, 병목 | 팬인 큐 / 병목 → 데이터 흐름 |
| 여러 단계에 걸친 반복되는 질문/입력/거버넌스/출력 슬롯 | 의미적 슬롯이 있는 단계 프레임워크 → 프로세스 |
| 대화 또는 느슨한 입력이 구조화된 내구성 있는 아티팩트가 됨 | 비구조화된 입력 → 구조화된 아티팩트 → 데이터 흐름 |
| 두 규칙 추적에 통과/실패/건너뜀/도달하지 않음 및 첫 번째 분기가 필요함 | 쌍을 이룬 정책 평가 추적 → 순서도 |
| 신뢰 경계 + 허용/금지된 수신 또는 배포 경로 | 안전한 포장 도로 → 아키텍처 |
| 시행되는 위치별로 그룹화된 제어 | 거버넌스/제어 카탈로그 → 레이어 스택 |
| 방어가 이전 격차를 보상하고 잔여 위험이 전파됨 | 보안 레이어 보상 → 레이어 스택 |
| 계층적, ID 주소 지정 가능한 분해로 블록별 I/O, 제약 조건 및 코드 링크 필요 | 추적 가능한 블록 분해 → 트리 |
| 하나의 주제가 단계, 대기, 재시도, 취소 및 최종 결과를 통해 진행됨 | 라이프사이클 단계 맵 → 상태 머신 |
패턴은 의미적 기본 요소와 더 엄격한 예산을 소유하고, 유형은 레이아웃 문법을 소유합니다. [references/animation.md](references/animation.md)는 모션이 요청되거나 질서 있는 변경을 실질적으로 명확히 할 때만 사용하세요. 정적이 기본값으로 유지됩니다.
시각적 유형 가이드 (45)
| 보여주려는 내용… | 사용 | 참조 |
|---|---|---|
| 하나의 스냅샷에 구성 요소 + 연결; 중첩된 관리 대 트래픽 범위 | 아키텍처 | type-architecture.md |
| 동기화된 Before/After 토폴로지 간 구조적 변경, 변경 내역 포함 | 아키텍처 델타 | 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 |
| 두 변수의 상관 관계 또는 분포; 거품(3변수) 및 beeswarm(1변수, 항목당 점) 변형 | 산점도 | 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](references/style-guide.md)는 색상, 타이포그래피, 토큰 및 기본 팔레트에 대한 단일 정보 소스입니다. 이 파일은 의미적 역할(paper, ink, muted, accent, link, …)을 지정합니다. 브랜드를 적용하려면 style-guide.md를 편집하거나 [references/onboarding.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에 대해 확인하세요.
…
[번역을 위해 잘림]