---
name: diagram-design
description: >
  시스템 구조, 처리 흐름, 상태 전이, 시퀀스, 데이터 모델, 조직도와 의존 관계 같은
  기술·제품 다이어그램을 설계해 self-contained HTML과 inline SVG로 만들 때 로드한다.
  정량 데이터 차트는 tufte-charts가, 화면 구조 탐색은 html-wireframe이, 목업과
  프로토타입은 html-prototype이, 제품 UI 코드는 frontend-design이, 전체 리포트 구성은
  html-report가, 단계로 나눠 만져 보며 이해하는 설명 지면은 html-explainer가 맡는다.
compatibility: >
  SaveFile 빌트인이 제시된 런에서는 HTML 파일로 남기고, 없으면 코드 블록으로 낸다.
  브라우저가 없어 렌더링을 직접 확인하지 못하므로 확인하지 못한 항목을 밝힌다.
---

# 다이어그램 디자인

내용의 구조와 관계가 한눈에 드러나는 정적 다이어그램을 만든다. 장식보다 의미, 의미보다
사실을 우선한다. 사용자가 주지 않은 구성 요소나 연결을 레이아웃을 채우기 위해 만들지 않는다.

## 경계

- 수치의 비교·추세·분포·상관관계가 중심이면 `tufte-charts`를 사용한다.
- 앱 화면이나 컴포넌트 배치가 중심이면 `frontend-design`을, 구조가 아직 미정이면
  `html-wireframe`을, 눌러보는 목업이면 `html-prototype`을 사용한다.
- 여러 절, 표, 차트를 묶은 문서가 필요하면 `html-report`를 사용한다.
- 그 주제를 모르는 사람에게 단계로 나눠 보여 주며 설명해야 하면 `html-explainer`를
  사용한다. 한 장에 다 담는 것이 이 스킬이고, 순서대로 드러내는 것이 그 스킬이다.
- 한두 관계만 보여 주면 표, 목록이나 짧은 텍스트 다이어그램이 더 낫다.

## 작업 흐름

1. 독자가 다이어그램을 보고 답해야 할 질문을 한 문장으로 정한다.
2. 입력에서 **요소, 관계, 그룹, 순서, 상태, 강조점**을 분리한다. 불명확한 관계를
   추측하지 않는다.
3. `references/type-selection.md`를 읽고 주된 관계 하나를 기준으로 유형을 고른다.
4. 의미상 빠진 정보가 결과를 바꿀 때만 질문한다. 색·모서리·장식처럼 안전한 시각
   기본값은 묻지 않고 선택을 밝힌다.
5. 선택한 계열의 reference를 하나 읽는다.
   - 시스템과 데이터 구조: `references/system-diagrams.md`
   - 순서, 상태와 업무 흐름: `references/process-diagrams.md`
   - 계층, 소유, 포함과 개념 관계: `references/relationship-diagrams.md`
6. 보안 경계, 병목, 피드백처럼 동작 의미가 핵심이면
   `references/semantic-patterns.md`도 읽는다.
7. `references/design-system.md`의 토큰과 `references/svg-implementation.md`의
   연결선·접근성 규칙으로 그린다. HTML 산출물은 `references/template.md`에서 시작한다.
8. 발행 전 삭제 가능한 요소와 중복 연결을 걷어내고 아래 검사를 수행한다.

## 유형을 고른 뒤 알릴 것

그리기 전에 다음을 한 문장으로 밝힌다.

- 선택한 유형
- 주요 읽기 방향
- 너무 복잡해 분리하거나 생략할 내용

사용자가 유형과 범위를 이미 정확히 지정했다면 이 안내만 하고 바로 만든다.

## 복잡도 처리

- 한 장의 중심 메시지는 하나다.
- 요소가 12개를 넘거나 연결을 눈으로 추적하기 어려우면 overview와 detail로 나눈다.
- 같은 경계를 여러 번 반복하지 말고 한 번 묶는다.
- 중요 요소는 1~2개만 색으로 강조한다. 모두 중요하면 아무것도 강조되지 않는다.
- 범례가 길어지면 시각 문법이 과한 것이다. 직접 label이나 구조 자체로 설명한다.

장식 클리셰의 전체 카탈로그는 같은 플러그인의 `frontend-design` 스킬 안에 있다 — **그
스킬을 열면 그 디렉터리의** `references/ai-visual-tells.md`다. 다이어그램의 색·형태
판단은 **이 스킬의** `references/design-system.md`가 먼저다.

## 산출

기본 산출물은 외부 의존성이 없는 HTML 한 개다. CSS와 SVG를 모두 inline으로 넣고,
JavaScript 없이도 전체 의미가 보여야 한다.

- `SaveFile`이 있으면 `mime_type: text/html`로 저장하고 HTML 전문을 답변에 반복하지 않는다.
- `SaveFile`이 없으면 완성된 HTML 전문을 `html` 코드 블록 하나로 제공한다.
- 사용자가 SVG 코드만 요청하면 `<svg>`만 제공해도 된다.
- PNG·PDF를 만들었다고 가장하지 않는다. 실제 변환 도구가 있을 때만 파일 형식을 바꾼다.
- 외부 폰트, CDN, 원격 이미지, `fetch`, 상대 파일 경로를 넣지 않는다.

## 발행 전 검사

- 제목이 주제가 아니라 독자가 알아야 할 내용을 말하는가?
- 모든 요소와 연결이 입력에서 추적 가능한가?
- 읽기 순서가 한 방향으로 유지되는가?
- 선이 상자를 관통하거나 서로 포개지지 않는가?
- 색을 빼도 그룹과 연결을 이해할 수 있는가?
- 작은 화면에서는 가로 스크롤로 보존되고 글자가 과도하게 축소되지 않는가?
- `<svg>`에 `role="img"`, 고유한 `<title>`과 `<desc>`가 있는가?
- 인쇄와 `prefers-reduced-motion` 환경에서도 의미가 유지되는가?

검증하지 못한 브라우저나 렌더링 조건이 있으면 결과와 함께 짧게 밝힌다.