다이어그램의 의미·축약·검증 - Diagram Design
Diagram Design은 다이어그램을 HTML·SVG로 만드는 스킬과 예제·검증 코드의 저장소다. 이 자료에서 재사용할 판단은 독자가 읽어야 할 관계를 고르고, 제한된 화면에 의미를 보존하며, 표현한 값과 실제 결과를 대조하는 방법이다. 고정된 색상·글꼴·요소 수는 저자의 제작 규칙으로 원천에 남긴다.
원천과 확인 범위
- 원자료: cathrynlavery/diagram-design.
- 확인 버전: ce9344c52cb9be811de187bf2a6d58c712c9c9fe, 해당 commit 시각 2026-09-15 01:23:11 UTC. 지속 갱신 저장소이므로 이를 최초 게시일로 해석하지 않는다.
- 2026-09-15에 핵심 지침, 대표 유형·가져오기·출력·모션 문서, 설계 결정 기록과 관련 검증 코드·테스트를 대조했다.
- 공개 갤러리에서 Architecture, Sankey, Policy trace 샘플을 열었다. Policy trace는 다음 단계 이동과 정적 모드도 확인했다. 갤러리는 갱신될 수 있으며 아래 코드 근거는 고정 commit을 가리킨다.
- 검증 스크립트·테스트는 읽었으며 실행하지 않았다. 모든 유형·브라우저·언어·내보내기 경로를 확인한 결과는 아니다.
먼저 읽어야 할 관계를 정한다
유형 선택은 독자가 답을 얻을 질문에서 시작한다. 같은 시스템도 구성요소의 포함을 보려면 계층이, 호출 순서를 보려면 시퀀스가, 여러 부모와 순환 의존을 보려면 의존 그래프가 필요하다. 주제가 같다는 이유로 같은 그림 문법을 고정하면 필요한 관계가 표현되지 않거나 없는 의미가 덧붙는다.
이 저장소는 배치 문법과 의미 패턴을 나눈다. 정책 평가나 감사 기록처럼 무엇을 설명하는지는 기존 유형에 담을 수 있고, 새로운 공간적 표현 방식이 필요할 때 유형을 늘린다. 이를 모든 도구가 따라야 할 분류 체계로 받아들이기보다, 새 이름을 붙이기 전에 필요한 관계가 이미 표현 가능한지 묻는 근거로 쓴다. 유형 확장 기준, 새 배치 문법의 이유
정량 그림에서도 질문이 다르다. 독립된 항목을 비교하는 막대, 두 시점의 차이를 보여주는 Dumbbell, 분기·합류하는 양을 보여주는 Sankey, 시작값에 증감을 순서대로 더하는 Waterfall은 서로 다른 읽기를 지원한다. Waterfall의 구분 근거
정보량·어휘·출력 크기를 함께 판단한다
출력 규격은 정보량과 독자에게 쓰는 용어를 별도로 정한다. 적은 요소로 기술적인 관계를 설명할 수도 있고, 많은 요소를 쉬운 용어로 설명할 수도 있다. 독자의 전문성을 곧바로 요소 수로 환산하지 않는다.
출력 크기는 읽을 수 있는 정보량에 제약을 준다. 선택한 정보를 담을 수 없으면 개요와 상세를 나누거나 질문의 범위를 좁힌다. 모든 내용을 남긴 채 글자를 줄이는 방식이 항상 충실한 전달은 아니다. 원천의 고정 개수와 독자 분류는 구현 규격이며, 이 노트는 정보량·명명·가독성의 서로 다른 판단을 보존한다. 출력 규격
축약 뒤에도 의미를 복원할 수 있게 한다
가져오기 문서는 원본의 관계를 먼저 추출하고 배치를 다시 정하도록 설계돼 있다. 노드와 연결뿐 아니라 방향, 순서, 조건, 그룹, 다중성처럼 해석을 바꾸는 정보를 보존한다. 원래 좌표와 장식을 버려도 되는지는 그 표현이 의미를 담당했는지 확인한 뒤 판단한다.
반복 요소를 묶거나 상세를 생략할 때는 무엇을 합쳤고 무엇이 빠졌는지 기록한다. 이름을 간단히 바꾸는 것과 서로 다른 역할을 한 요소로 합치는 것은 영향이 다르다. 로그·보안·감시 같은 구성요소도 그림의 질문에 따라 핵심이 될 수 있으므로 고정 삭제 순서를 보편 규칙으로 쓰지 않는다. Mermaid 가져오기, 축약과 생략 기록
추적 가능한 블록 분해는 화면의 간결함과 상세 기록의 한 가지 절충 사례다. 화면에는 안정적인 ID와 이름을 두고, 상세 정보는 그림 내부 메타데이터와 거기서 생성한 별도 목록으로 이어진다. 이 목록을 따로 수작업으로 유지하면 같은 정보가 어긋날 수 있다. 해당 검증기는 ID·부모·순환 같은 구조를 검사하며 그 메타데이터와 실제 선·배치의 일치까지 보장하지 않는다. 블록 메타데이터 계약
수치를 나타내는 도형은 데이터에 맞춘다
Sankey의 폭, Treemap의 면적, Waterfall의 위치와 높이는 숫자의 관계를 표현한다. 정렬·간격·라벨 배치 때문에 이 기하가 달라지면 데이터의 의미도 달라진다.
- Sankey는 공통 축척과 분기·합류의 양이 맞아야 한다.
- Treemap은 작은 셀의 상대 오차도 확인한다. 표기가 없는 작은 셀에도 선언된 비중이 있어야 검증에서 빠지지 않는다. 읽히지 않는 항목은 범례나 구성 내용을 밝힌 묶음으로 전달하거나 다른 유형을 검토한다.
- Waterfall은 시작값과 각 증감이 중간·최종 합계 및 연결선의 누적값과 맞아야 한다. 이 구현은 수치 좌표를 일반적인 4px 배치 격자에서 제외한다.
유형별 반올림 방식은 다르다. 일반화할 판단은 모든 수치 좌표의 격자를 없애라는 것이 아니라, 반올림·간격 조정 뒤에도 표현한 관계가 유지되는지 확인하라는 것이다. 원자료의 신뢰성은 그림 내부의 합계·축척 일치와 별도로 확인한다. Sankey, Treemap, Waterfall
역할별 표현과 정적인 의미를 유지한다
시선을 모으는 강조색과 분류·상태를 구별하는 색은 역할이 다르다. Waterfall은 증감 방향을 채움 차이로 표현하고 강조색은 관심 지점에 쓴다. Treemap의 명암 설명도 밝은 배경과 어두운 배경에서 같은 뜻을 유지해야 한다. 특정 색상값을 복사하기보다 독자가 무엇을 구별하는지 확인한다. Treemap의 테마·범례 기준
모션 문서는 정적인 원본만으로 모든 의미를 읽을 수 있게 두고 움직임을 설명 수단으로 더한다. 인쇄·정적 내보내기·동작 감소·스크립트 미실행 상태에서도 필요한 관계와 결과가 남아야 한다는 계약이다. 임의로 몇 초 기다려 캡처하는 대신 명시적인 정적 상태를 사용한다. 이번에 직접 확인한 것은 Policy trace의 다음 단계 이동과 정적 모드이며, 나머지는 문서에 명시된 계약이다. 모션 계약
검증 코드가 답하는 범위와 실제 관찰을 구분한다
라벨 기하 검증을 추가한 결정 기록에는 기존 검사들을 통과한 예제에서도 글자가 나중에 그려진 노드에 가려졌다는 사례가 있다. 새 검사도 특정 사각형·그리기 순서에 대한 충돌을 찾으며, 일반 SVG 렌더링 전체나 라벨과 연결선의 모든 간격을 검증하지 않는다. 기하 검사 도입 기록, 검증 코드
2026-09-15에 본 Sankey full 샘플에서는 도표가 Build 2,000분·Lint 800분인데 아래 설명문은 1,900분·900분이었다. 고정 버전 HTML의 라벨과 문장에서도 같은 불일치를 확인했다. 이는 그림과 주변 설명을 함께 대조할 이유이며, 현재 CI 결과나 검증기를 실행해 얻은 실패 판정은 아니다. 도표의 라벨, 주변 설명
검증기의 출력으로 말할 수 있는 것은 실제 검사한 계약까지다. 구문, 메타데이터, 기하, 렌더링, 설명의 일치와 원자료의 정확성은 관련돼 있지만 같은 증거로 확정되지 않는다.
에이전트 문서를 줄일 때 보존할 입구
문서 용량을 줄이며 설명에서 유형 이름을 제거했다가 스킬을 발견할 단서를 줄였다는 설계 기록도 있다. 이후 이 프로젝트는 호출 전 보이는 설명에 발견 단서를 남기고 상세 본문을 참조 문서로 옮기도록 정했다. 이 사례는 진입 조건과 참조 경로를 보존하는 근거이며, 이름을 나열하는 것만으로 실제 호출이 보장된다는 실험 결과는 아니다. 문서 감축 결정