llm-wiki/.agents/plugins/wiki-superpowers/rules/diagram-standards/elements.md

Diagram Elements — Budget + Component / Edge Labels + Visual Hierarchy

Root SSOT: rules/diagram-standards.md §3~§6 parent: README.md

§3. Element Budget — 요소 수 상한 (HARD LIMITS)

요소	권장	상한	초과 시
Vertex (박스)	5~7개	10개	분할 또는 비핵심 제거
Edge (화살표)	4~6개	8개	시퀀스 다이어그램으로 분리
Callout (주석 박스)	0~1개	1개	본문 텍스트로 옮김
Boundary group	1~2개	3개	중첩 단계 축소
Legend 항목	3~4개	6개	표준 컨벤션 사용 (legend 생략)
색상	2~3 가지 (회색/흑백 + 강조 1)	4 가지	색 분류 축소

상한을 초과하면 다이어그램이 잘못된 단위에 있다. 분할 또는 추상화 레벨 올리기.

§4. Component Label — 박스 안 텍스트 ≤ 2줄

┌─────────────────────────┐
│  <Name>                 │  ← 1줄: 시스템 이름 (Bold)
│  <Context 1줄>          │  ← 1줄: 역할 OR 기술. 둘 중 핵심만.
└─────────────────────────┘

예시

Bad (v2 이전 스타일)	Good
Spring Boot Resource Server Role: JWT 검증 + 비즈니스 API Stack: Spring Boot 3.4 / Java 21 + Spring Security 6.x Endpoint: localhost:8080 Capacity: 1 instance Owner: 본인 (7줄)	**Spring Boot RS** Spring Boot 3.4 · :8080 (2줄)

다이어그램에 안 들어가는 정보는 본문에

• 컴포넌트 상세 (역할, 책임, owner, capacity) → project-note 의 §"컴포넌트 책임 분담" 표
• 의존성 매트릭스 → 별도 §"외부 의존성" 표
• 운영 SLO → 별도 §"비기능 요구사항"

§5. Edge Label — 화살표 라벨 ≤ 5단어

<step?> <verb/protocol> <object>

예시

Bad (v2 이전 스타일)	Good
① HTTPS GET / (HTML/JS) payload: ~50KB (initial SPA bundle) p99: ~80ms (cold) / ~10ms (cache) (3줄)	① GET / (1줄)
⑥ proxy_pass http://localhost:8080 Authorization header forward (timeout: 30s, keepalive: 60s)	proxy_pass :8080

스케일 어노테이션 (QPS, latency, payload size) — 다이어그램의 질문이 그것 일 때만

• 일반 아키텍처 다이어그램: 화살표는 prototype + endpoint 만
• 성능 다이어그램: QPS / latency 가 핵심 → 그 때만 라벨에

번호 (①②③) 는 순서가 중요할 때만. 정적 토폴로지 다이어그램은 번호 불필요.

§6. Visual Hierarchy Through Restraint — 색은 강조용

색 사용 비율

• 80% 회색/흑백 — 본문 박스의 기본 fill / stroke
• 15% 강조색 1개 — 다이어그램의 critical path 또는 primary system
• 5% 위험 / 경고색 (빨강) — error path, SPoF, 보안 위협 — 있을 때만

표준 팔레트 (Minimal)

용도	Fill	Stroke	비고
일반 컴포넌트 (기본)	#FFFFFF	#57606A (회색)	80% 의 박스가 여기
Critical path / 주인공	#FFFFFF 또는 옅은 강조색	굵은 강조색 (#1F6FEB 파랑 또는 #FB923C 주황)	다이어그램에서 가장 중요한 1~2개 박스만
Data store (DB)	#FFFFFF	#57606A + cylinder shape	모양으로 구분
External (점선)	#F6F8FA	#D0D7DE (회색 점선)	외부 시스템·3rd party
Warning / Error path	#FEF2F2 (옅은 빨강)	#DC2626 (빨강)	있을 때만, 1~2 요소 한정

금지: 모든 박스에 색 칠하기. 색이 의미를 잃음 (color salad).

Stroke 굵기

• 일반: 1~1.5px
• Critical path / Primary: 2~3px (강조용)
• Boundary: 1.5~2px

화살표 종류

종류	의미
실선 + 화살촉	동기 호출 (HTTP, RPC, JDBC)
점선 + 화살촉	비동기 / fire-and-forget (Kafka publish, async event)
굵은 실선 (2~3px, 강조색)	Critical path / hot path
빨간 점선	Error path

화살표 종류는 다이어그램 내 일관성 이 핵심. 4종류 이상 섞지 말 것.