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

Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §3~§6
parent: [`README.md`](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`<br/>`Role: JWT 검증 + 비즈니스 API`<br/>`Stack: Spring Boot 3.4 / Java 21`<br/>`+ Spring Security 6.x`<br/>`Endpoint: localhost:8080`<br/>`Capacity: 1 instance`<br/>`Owner: 본인` (7줄) | `**Spring Boot RS**`<br/>`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)`<br/>`   payload: ~50KB (initial SPA bundle)`<br/>`   p99: ~80ms (cold) / ~10ms (cache)` (3줄) | `① GET /` (1줄) |
| `⑥ proxy_pass http://localhost:8080`<br/>`   Authorization header forward`<br/>`   (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종류 이상 섞지 말 것.