Diagram 보기 상세

Diagram은 Markdown에 적힌 연결과 경로를 흐름 그림으로 읽는 projection이다. Glif Desktop은 Sankey, Alluvial, Parallel Sets 세 종류를 제공한다. 그림의 node와 flow는 파생 결과이며, 데이터의 정본은 계속 Markdown이다.

어떤 Diagram을 고를까

Alluvial과 Parallel Sets는 같은 wide table을 읽을 수 있지만 의미가 다르다. 시간이나 funnel 단계라면 Alluvial, 독립적인 범주 조합이라면 Parallel Sets를 고른다. Parallel Sets는 수치 축을 잇는 Parallel Coordinates가 아니다.

준비된 예제

• 콘텐츠 제작 Sankey 표
• 독자 경로 stage-path 표
• H2 문서 흐름
• 순환 오류 예제

파일을 내려받거나 예제 프로젝트에 그대로 둔 뒤 Glif에서 해당 폴더를 Scope로 열 수 있다.

Sankey: 연결량 읽기

최소 문법

| Source | Target | Value |
| :--- | :--- | ---: |
| 아이디어 | 조사 | 72 |
| 아이디어 | 인터뷰 | 28 |
| 조사 | 초안 | 64 |
| 인터뷰 | 초안 | 24 |
| 초안 | 검토 | 70 |
| 검토 | 게시 | 54 |

• Source와 Target은 비어 있지 않은 node 이름이어야 한다.
• Value는 0보다 큰 유한 숫자여야 한다. 쉼표는 허용되지만 단위가 섞인 문자열은 피한다.
• 같은 Source–Target 행은 원문 순서를 보존한 채 합산된다.
• 자기 자신으로 향하는 연결과 방향 cycle은 일부만 그리지 않고 오류로 차단한다.
• 표에는 최대 500행, 결과에는 최대 200 nodes와 800 links를 허용한다.

보기로 전환

1. sankey-content-flow.md를 연다.
2. 문서 헤더의 보기 선택기를 연다.
3. Diagram을 선택한다.
4. 제목 아래 요약에서 node 8개, flow 10개, 표 1을 확인한다.
5. node label과 값이 Markdown의 Source, Target, Value와 일치하는지 대조한다.

영상은 원문 표에서 보기 선택기를 열고 Sankey로 전환하는 실제 앱 조작을 보여 준다. 파란 원은 pointer 위치이고 아래 문장은 검증 단계 설명이다.

H2 문서를 Sankey로 읽기

표가 없어도 H2 section과 직접 bullet로 문서 흐름을 적을 수 있다.

# 문서 전달 흐름

## 조사
- 초안: 48
- 인터뷰: 22

## 초안
- 검토: 56
- 보류: 14

H2가 Source, Target: 양수 형식의 직접 bullet이 edge가 된다. H3 이하, nested list, task list, ordered list와 숫자 없는 문장은 flow로 추측하지 않는다.

표와 H2 문서 후보가 동시에 있으면 Inspector의 원본에서 명시적으로 선택한다. 저장된 원본이 사라졌다면 다른 표에 자동으로 붙지 않고 unresolved 상태로 멈춘다.

Alluvial과 Parallel Sets

stage-path 문법

| 유입 | 기기 | 콘텐츠 | 행동 | 독자 수 |
| :--- | :--- | :--- | :--- | ---: |
| 검색 | 모바일 | 가이드 | 저장 | 32 |
| 뉴스레터 | 태블릿 | 스토리 | 공유 | 20 |
| 커뮤니티 | 데스크톱 | 레퍼런스 | 복사 | 18 |

앞의 2~8개 열은 stage 또는 category이고 마지막 수치 열은 선택적인 Weight다. Weight를 생략하면 각 행의 무게는 1이다. 빈 category, 음수, 0 또는 숫자가 아닌 Weight는 정상 결과로 잘라 그리지 않고 오류로 표시한다.

같은 원문, 다른 해석

1. audience-paths.md를 Diagram으로 연다.
2. 오른쪽 Diagram Inspector에서 Alluvial을 선택한다.
3. 유입 → 기기 → 콘텐츠 → 행동 순서와 독자 수를 확인한다.
4. Parallel Sets로 바꾼다.
5. Markdown table 값과 열 순서가 바뀌지 않았는지 Source에서 확인한다.

실증 캡처에서는 유형 전환 전후 audience-paths.md의 byte가 같았다. 최종 선택 parallel-sets는 .glif/profiles/v1/by-path-sha256/ 아래 문서 profile에 저장됐고, profile JSON에 뉴스레터나 직접 방문 같은 원문 값은 복사되지 않았다.

Diagram Inspector

Inspector는 데이터가 아니라 해석과 표현 설정을 소유한다.

Diagram 유형

Sankey, Alluvial, Parallel Sets 가운데 현재 문서에 사용할 종류를 선택한다. 마지막 선택은 features.diagram.projection.kind에 저장된다.

원본

표 또는 지원되는 H2 document adapter를 고른다. 후보가 하나이고 유효하면 자동으로 선택한다. 후보가 여러 개면 사용자가 정해야 하며, 저장된 binding이 깨졌을 때 임의의 첫 표로 fallback하지 않는다.

데이터 매핑

Sankey에서는 Source, Target, Value 열을 지정한다. Alluvial과 Parallel Sets에서는 stage 열의 순서를 키보드 버튼으로 앞뒤 이동하거나 추가·제거하고 Weight 열을 고른다. mapping을 바꿔도 Markdown과 editor undo history는 바뀌지 않는다.

저장 상태

자동, 수동, 선택 필요, 저장 중, 저장 오류와 unresolved 상태를 구분한다. 저장 오류가 보이면 Source를 수정하기 전에 Scope가 쓰기 가능한지와 .glif 경로를 확인한다.

접근 가능한 데이터 표

canvas만으로 값을 읽기 어려울 수 있으므로 각 Diagram 아래에 접근 가능한 데이터 표가 있다. Sankey는 Source, Target, Value, Markdown line을, stage-path는 record, 각 stage, Weight, Markdown line을 제공한다.

마지막 열의 line 버튼은 해당 Markdown 행으로 돌아간다. screen reader, 키보드 사용자나 그림과 숫자를 직접 대조해야 하는 검토자는 이 표를 기준으로 삼는다.

오류를 숨기지 않는 복구

invalid-cycle.md는 게시 → 초안 연결 때문에 방향 cycle이 생긴다. Diagram은 가능한 일부만 그리는 대신 이 생키에는 순환 흐름이 있습니다라는 원인을 표시한다.

원본에서 수정을 누르면 진단 행으로 돌아간다. 다음 오류도 같은 방식으로 먼저 Source에서 고친다.

한국어와 영어 UI

같은 fixture를 영어 UI에서도 열어 Sankey · 8 nodes · 10 flows · Table 1 접근성 요약을 확인했다.

label은 Markdown 원문이므로 앱 언어를 바꿔도 자동 번역되지 않는다. UI 명칭과 진단만 현재 앱 언어를 따른다.

Desktop과 Hugo 결과의 차이

Desktop은 ECharts 기반 상호작용 그림을 제공한다. 현재 Slide, Hugo와 static 출력은 시각적 Diagram parity를 약속하지 않고 같은 source/profile을 사용한 접근 가능한 원본 데이터 fallback을 낸다.

• Sankey 표 source: caption, header, 유효한 모든 row와 종류·mapping 설명
• H2 document source: renderer-neutral flow/path data summary
• source binding이 unresolved이면 다른 첫 표를 대신 게시하지 않음
• 500행을 넘으면 일부만 잘라 정상 결과처럼 게시하지 않음

따라서 Desktop 그림을 이미지처럼 그대로 Hugo에 내보낸다고 가정하지 않는다. 공개 결과에서는 fallback 고지를 확인하고, 시각적 parity가 꼭 필요하면 검증된 screenshot을 별도 asset으로 사용한다.

성능 경계와 실측

release candidate에서 각 유형 500행 fixture를 5회 준비한 뒤 20회 warm run으로 측정했다. 단위는 p95 밀리초다.

budget은 감지 25ms, parse·검증 50ms, update 100ms, static fallback 100ms다. 원본 측정 JSON에서 fixture 크기와 전체 결과를 확인할 수 있다. 이 수치는 같은 문서 parse를 재사용하는 warm 경로이며, 앱 최초 기동이나 disk I/O를 포함한 cold-open 시간은 아니다.

화면 크기와 접근성 실증

Diagram Inspector는 별도 페이지가 아니라 현재 Diagram과 나란히 쓰는 작업 영역이다. Windows release candidate에서 Inspector 폭을 280px, 360px, 480px로 바꿔 보기 선택기, 세 Diagram 유형, 캔버스와 스크롤 경계를 확인했다. 세 폭 모두 페이지와 Inspector의 가로 오버플로가 0px이었다.

운영체제의 애니메이션 효과 끄기 또는 브라우저의 prefers-reduced-motion: reduce 환경에서도 Diagram은 정적인 결과를 잃지 않는다. 아래 화면은 reduced-motion 조건이 실제로 활성화된 상태에서 같은 Alluvial을 확인한 결과다.

Windows 배율 200%에서는 앱의 실제 CSS 작업 폭이 600×400이 된다. 이때 Glif는 왼쪽 탐색 영역을 접고 본문 304px과 Diagram Inspector 280px을 함께 유지한다. 보기 선택기와 Alluvial 캔버스가 화면 안에 남고 페이지·Inspector 오버플로는 모두 0px이다.

수치와 판정은 280/360/480px·reduced-motion QA JSON과 200% 배율 QA JSON에서 다시 확인할 수 있다.

릴리스 전 확인표

• 세 Diagram 종류의 label과 값이 원문과 일치한다.
• 보기와 mapping 변경 뒤 Markdown byte가 의도치 않게 바뀌지 않는다.
• profile에 원문 row, renderer option이나 canvas payload가 복사되지 않는다.
• 접근 가능한 표와 원본 행 복귀가 작동한다.
• cycle, self-link, invalid number와 501행이 fail-closed한다.
• 한국어와 영어 UI에서 요약과 진단을 읽을 수 있다.
• Hugo/Slide 결과가 visual parity가 아닌 fallback임을 공개한다.
• 280/360/480px, 200% 확대와 reduced-motion 환경을 현재 release candidate에서 확인한다.

ED-26의 기능·오류·저장·성능·native visual qualification을 모두 같은 release candidate와 재현 가능한 fixture에서 확인했다. 이 체크리스트와 evidence manifest가 어긋나면 체크 표시보다 manifest와 재실행 결과를 우선한다.