AnisAbdellatif/d2

D2 다이어그램

D2는 선언형 언어입니다: 모양과 그 사이의 연결을 설명하면 레이아웃 엔진이 모든 것을 어디에 배치할지 결정합니다. 수동으로 좌표를 지정할 필요가 전혀 없습니다. 이것이 D2 다이어그램이 짧고, diff 가능하며, 나중에 편집하기 쉬운 이유이며, 대부분의 오류가 설계가 아닌 구문 및 레이아웃 엔진의 특성에서 비롯되는 이유이기도 합니다.

이 스킬은 실제 컴파일러로 검증된 D2 v0.9.x에 대한 완전한 실무 지식입니다. references/ 및 assets/templates/의 모든 예제는 컴파일됩니다.

워크플로우

1. 도구를 확인하세요. d2 --version (또는 scripts/d2check.sh --version)을 실행하세요. d2가 없으면 사용자에게 알리고 brew install d2 또는 curl -fsSL https://d2lang.com/install.sh | sh -s --를 제공하세요. 자동으로 설치하지 마세요.
2. 다이어그램 유형을 선택하고 일치하는 참조(아래 표)를 읽으세요. 적합한 템플릿이 있으면 assets/templates/의 템플릿으로 시작하세요.
3. 사용자가 원하는 위치(기본값: diagrams/<name>.d2)에 .d2 파일을 작성하세요.
4. scripts/d2check.sh <file.d2> [outdir] [pdf|pptx|gif]로 컴파일 및 렌더링하세요 (형식 지정, 컴파일, SVG 렌더링, PNG 미리보기를 outdir/preview/에 배치 및 추가 형식). d2 validate만으로는 안 됩니다: 구문만 구문 분석합니다. 잘못된 모양 이름, 범위를 벗어난 스타일, 지원되지 않는 레이아웃 기능 및 누락된 가져오기는 모두 validate를 통과하고 컴파일 시 실패합니다.
5. 그림을 보세요. preview/에서 PNG를 열고(.png 파일에 대해 Read 도구 사용) 중복 레이블, 엉킨 가장자리, 잘못된 흐름 방향, 한쪽으로 치우친 레이아웃 등을 평가하세요. 수정하고 다시 렌더링하세요. 컴파일되지만 읽을 수 없는 다이어그램은 완료된 것이 아닙니다.
6. 전달 .d2 소스와 렌더링된 파일을 제공하고 사용한 레이아웃 엔진, 테마 및 방향을 알려주어 사용자가 변경할 수 있도록 하세요.

빠른 일회용(파일 없음)의 경우: echo 'a -> b' | d2 - out.svg.

한 화면에 담은 구문

direction: right                    # up | down | right | left (루트 레벨, TALA만 컨테이너별 허용)

# 모양: 키, 선택적 레이블, 선택적 속성
web: Web App {shape: rectangle}     # 키 `web`, 레이블 "Web App"
db: Postgres {shape: cylinder}
user: Customer {shape: person}

# 연결: -> <- <-> --  (항상 KEY를 참조하고, 레이블을 참조하지 마세요)
user -> web: 사용
web -> db: SQL {style.stroke-dash: 3}
web -> cache: 읽음              # 선언되지 않은 키는 즉시 생성됩니다.

# 컨테이너: 점 또는 중첩 맵
backend: {
  api -> worker: 대기열에 추가
  worker -> _.db: 기록         # _ = 부모 스코프
}
web -> backend.api: HTTPS

# 스타일링은 속성 안에 있습니다.
db.style.fill: "#e6f2ff"         # #로 시작하는 모든 것은 따옴표로 묶으세요
(web -> db)[0].style.stroke: red # 인덱스로 연결 스타일 지정

# 재사용: 클래스, 변수, 글로브
classes: {
  store: {shape: cylinder; style.fill: "#e6f2ff"}
}
cache.class: store
vars: {env: prod}
note: ${env}에서 실행 중
*.style.border-radius: 8

세미콜론은 한 줄에서 항목을 구분합니다. #는 주석을 시작하고, """ ... """는 블록 주석입니다. 키는 대소문자를 구분하지 않으며 중복 선언은 병합됩니다(API, api 및 Api: Gateway는 "Gateway" 레이블이 있는 하나의 모양입니다).

인용: 오류의 가장 큰 원인

따옴표가 없는 문자열은 편리하지만 여러 문자에 의미가 있습니다. 다음 중 하나라도 포함되면 전체 레이블을 따옴표("..." 또는 '...')로 묶으세요. 그렇지 않으면 컴파일러가 오류를 내거나, 더 나쁘게는 레이블을 자동으로 잘라냅니다:

문자	따옴표 없이 발생하는 현상	수정 예시
# (어디든)	나머지 줄이 주석이 됨: a: C# language는 "C"만 렌더링	a: "C# language"
시작 부분의 [	배열로 구문 분석됨: a: [JSON/HTTPS]는 "a"만 렌더링	a: "[JSON/HTTPS]"
키 안의 .	컨테이너 생성: svc v1.2는 svc v1 > 2가 됨	"svc v1.2"
키 안의 & 또는 [ ]	구문 오류 (&는 글로브 필터 마커)	"R&D", "svc[0]"
{가 아닌 다른 문자 뒤의 $	"substitutions must begin on {"	작은따옴표: 'costs $5'
레이블 시작 부분의 { } `	`	맵 또는 블록 문자열 열림
모양 키로서의 예약어 (label, link, class, top, style, shape, icon, near, direction, vars ...)	"reserved keywords are prohibited in edges"	"link" -> b, 또는 다른 키 선택
가장자리 레이블 안의 -> 또는 :	실제로는 문제 없음 (a -> b: Time: 10s 동작)	인용 불필요
전각 콜론 ： 같은 비ASCII 구두점	콜론으로 인식되지 않음	ASCII : ; . 사용

16진수 색상은 따옴표로 묶어야 합니다("#fff") . #가 주석을 시작하기 때문입니다. 작은따옴표는 ${...} 치환도 비활성화합니다.

레이블의 새 줄: 따옴표가 있거나 없는 레이블의 \n, 또는 서식 있는 텍스트를 위한 블록 문자열 |md ... |.

함정 (디버깅 전에 읽으세요)

• 기본 레이아웃 엔진인 Dagre는 컨테이너와 그 하위 항목 간의 연결을 그릴 수 없습니다 (a -> a.b). 컨테이너 크기(width/height)를 조정할 수 없으며 near: <object>를 사용할 수 없습니다. 컴파일 시 오류가 발생합니다. 다이어그램을 다시 작성하는 대신 --layout=elk(또는 vars.d2-config.layout-engine: elk)로 전환하세요.
• 예약어는 대소문자를 구분하지 않고 일치합니다. Shape, Label, Class, Style, Link, Icon...으로 명명된 모양 또는 UML 클래스는 키워드와 충돌합니다 (reserved field shape does not accept composite). 이름을 바꾸세요.
• 레이블이 아닌 키를 연결하세요. be: Backend 후에 Backend -> x는 Backend라는 새로운 모양을 만듭니다. be -> x를 사용하세요.
• 중복 연결은 병합되지 않습니다. a -> b를 두 번 쓰면 두 개의 화살표가 그려집니다. (a -> b)[0], (a -> b)[1]로 주소를 지정하세요.
• d2-legend는 변수이지 모양이 아닙니다: vars: { d2-legend: { ... } } 안에 넣으세요. 최상위 d2-legend: ""는 "d2-legend"라는 이름의 평범한 모양일 뿐입니다.
• 시퀀스 다이어그램: 선언 순서가 화면상의 순서이며, 액터는 먼저 선언되어야 하고, 그룹 내에서는 최상위에 존재하는 액터만 참조할 수 있습니다.
• SQL 테이블 및 UML 클래스: 행을 연결하세요 (orders.user_id -> users.id), 그리고 ELK 또는 TALA를 사용하여 가장자리가 정확한 행에 닿도록 하세요.
• 화살촉 모양은 화살표가 있는 끝에서만 렌더링됩니다: A -> B와 함께 source-arrowhead.shape: diamond는 A에 아무것도 그리지 않습니다 (그리고 --는 전혀 모양을 그리지 않습니다). 모양이 대상에 있도록 가장자리를 뒤집거나 <->를 사용하세요.
• d2 fmt는 예약어 레이블을 다시 작성합니다 (lnk: Link는 lnk: link가 됨), 그리고 scripts/d2check.sh는 파일에서 fmt를 실행합니다. 이러한 레이블은 따옴표로 묶으세요 (lnk: "Link").
• 블록 문자열 |md ... |는 다음 |에서 끝납니다. 내부에 리터럴 파이프가 필요한 경우 더 긴 구분 기호를 사용하세요: |md ... | 또는 ||md ... ||.
• 숫자 스타일 범위가 적용됩니다: stroke-width 0-15, opacity 0-1, font-size 8-100. text-transform은 none|uppercase|lowercase|capitalize를 사용합니다 (웹사이트는 title을 표시하지만 컴파일러는 거부합니다). 3d는 rectangle, square 및 hexagon에서만 작동합니다.
• 요청하지 않으면 animated: true 또는 dark-theme-id를 추가하지 마세요. 애니메이션은 런타임 데이터 흐름을 의미하며, 다크 테마는 OS가 다크 모드인 시청자를 위해 색상을 자동으로 반전시킵니다.
• 모양의 채우기 색상은 테마를 재정의합니다. 테마와 몇 가지 classes를 선호하고, 색상에 의미가 있을 때만 명시적 색상을 사용하세요 (그리고 범례를 추가하세요).
• PNG/PDF/PPTX/GIF는 v0.9+에서 브라우저 없이 렌더링됩니다. 이전 버전(<0.8)에서는 Playwright/Chromium이 필요하며, 처음 사용할 때 다운로드됩니다. d2 --version을 확인하세요.
• TALA는 v0.9에 포함되어 있지만 (--layout=tala) 비결정적입니다: 작은 레이블 변경으로 레이아웃이 뒤섞일 수 있습니다. 재현성이 중요하다면 data.tala-seeds로 고정하세요.
• 멀티보드 파일 (layers/scenarios/steps)은 SVG와 PNG를 디렉토리로 내보냅니다 (x/index.svg, x/layers/a.svg). 동일한 이름으로 PNG를 렌더링하면 SVG 디렉토리가 대체됩니다. 형식을 별도의 폴더에 유지하세요 (스크립트가 수행). 드릴다운 전달의 경우 PDF를 사용하고(보드당 한 페이지, 클릭 가능한 link: layers.x), "뒤로" 모양을 수동으로 그리지 마세요: 내보내기 도구가 자동으로 이동 경로 표시줄을 추가합니다. references/composition.md를 참조하세요.
• 출력 파일이 존재한다고 성공을 의미하지는 않습니다. D2는 오류 발생 시 부분 렌더링을 작성할 수 있습니다. 종료 코드를 확인하세요 (스크립트가 수행).

레이아웃, 방향, 테마 선택

• 레이아웃 엔진: dagre (기본값, 빠름, 곡선 가장자리) -> elk (직각 라우팅, 아키텍처, SQL 테이블, 컨테이너 간 가장자리에 최적) -> tala (대칭, 컨테이너별 direction, near: object, 고정 top/left). 컨테이너나 테이블이 있는 경우 기본적으로 ELK를 사용하세요.
• 방향: 파이프라인, 요청 흐름 및 와이드 스크린에는 right; 계층 구조 및 조직도에는 down. 전체 보드에 대해 하나를 선택하세요.
• 테마: theme-id: 0 기본값; 4 Cool classics 및 3 Flagship Terrastruct는 현대적으로 보임; 1 neutral grey는 문서에 적합; 8은 색맹 안전; 300/301 터미널; 303 C4; 200/201 다크. 전체 표는 references/cli-and-rendering.md에 있습니다.
• 렌더링 설정을 파일에 넣어 함께 전달되도록 하세요:

vars: {
  d2-config: {
    layout-engine: elk
    theme-id: 4
    pad: 40
  }
}

(CLI 플래그 및 D2_* 환경 변수가 이 블록을 재정의합니다.)

디자인 지침

• 보드당 3~12개 모양. 그 이상이면 layers (확대), scenarios (변형) 또는 steps (점진적 표시)로 분할하거나 컨테이너를 사용하여 그룹화하세요.
• 키로 이름 짓고, 사람을 위해 레이블을 사용하세요: 짧고 안정적인 키 (pg, auth), 읽기 쉬운 레이블 (pg: PostgreSQL).
• 가장자리 레이블은 동사 또는 프로토콜입니다 (읽음, 게시, HTTPS). 문장이 아니고 대상의 이름이 아닙니다.
• 의미에 맞는 모양을 사용하세요: cylinder 저장소, queue, person, cloud 외부, diamond 결정, hexagon 서비스, document/page, package, step. 모든 것을 사각형으로 남겨두지 마세요.
• 색상은 의미를 인코딩하거나 아무것도 인코딩하지 않습니다. 최대 ~5개 카테고리, classes를 통해 적용, 레이블이 전달하지 않는 정보를 색상이 전달할 때만 d2-legend를 사용하세요.
• 보드당 하나의 추상화 수준.
• D2는 화이트보드 규모(최대 수백 개 모양)의 소프트웨어 및 시스템 문서화를 위한 것입니다. 의도적으로 Gantt 차트, 마인드 맵, 벤 다이어그램, Sankey, 원형/막대 차트 또는 지리적 지도가 없으며, 객체가 두 컨테이너에 동시에 존재할 수 없습니다. 이 사실을 알리고 D2를 억지로 사용하기보다 다른 도구를 제안하세요.

참조 맵

작업에 필요한 것만 읽으세요.

작업	읽을 자료
구문 관련 모든 의문: 키, 레이블, 연결, 컨테이너, 문자열, 이스케이프, 주석, 예약어	references/language.md
모양, 모든 스타일 키와 범위, 화살촉, 텍스트/마크다운/LaTeX/코드, 아이콘, near 위치 지정, 크기, 테마	references/shapes-and-styling.md
시퀀스 다이어그램, SQL 테이블 (ERD), UML 클래스, 그리드, 범례, 툴팁/링크, C4	references/diagram-types.md
클래스, 변수, 글로브 및 필터, 재정의 및 null, 가져오기, suspend 모델	references/reuse-and-globs.md
레이어, 시나리오, 단계, 보드 연결, 대규모 다이어그램 가져오기, 멀티보드 내보내기	references/composition.md
CLI 플래그, 레이아웃 엔진, 테마 표, 내보내기 형식, d2-config, 문서/CI에 포함, D2.js	references/cli-and-rendering.md
다이어그램 계열별 기성 패턴 (아키텍처, 순서도, 상태, ERD, C4, 조직도...)	references/recipes.md + assets/templates/*.d2
Mermaid / PlantUML / Graphviz에서 변환	references/recipes.md (변환 섹션)
오류 메시지 또는 잘못 렌더링되는 다이어그램	references/troubleshooting.md

컴파일 실패 시

scripts/d2check.sh file.d2를 실행하세요. 오류는 file:LINE:COL: message 형식으로 표시됩니다. references/troubleshooting.md에서 메시지를 찾아보세요. 일반적인 원인은 인용 문제(위 참조), 레이아웃 엔진 제한(ELK로 전환), 알 수 없는 모양 또는 범위를 벗어난 스타일, 블록 문자열 들여쓰기입니다. 한 번에 하나의 오류를 수정하고 다시 실행하세요: 이후 오류는 종종 첫 번째 오류의 결과입니다.