표현 범위와 검증 범위

요약

ThinkFlow는 thinkflow 원본 하나로 구조, 순서, 상태, 스키마, API, 클래스, 칸 격자, 추적, 값에 묶인 차트와 열여섯 차트 종류를 한 모형으로 그린다. 개발자가 만드는 모든 시각물을 지원하지는 않는다. 이 문서는 지원하는 표현을 문법, 예제, 확인 근거와 이어 주고, 전용 문법이 없거나 일부러 제외한 표현을 구분한다. 문법 전체의 항목 목록은 그림 문법의 생성 표가 정본이다. 이 문서의 표는 "예제가 이 기능을 적었다"와 "확인한 시험이 있다"를 말할 뿐 모든 조합이 맞다고 주장하지 않는다.

동기

문법을 읽는 시험만으로는 글자 잘림, 조작 오류, 본문에 넣었을 때의 크기와 테마 연결을 판단할 수 없고, 예제 수만으로는 기능이 빠졌는지 알 수 없다. 기능마다 어느 예제가 쓰는지, 무엇을 확인했는지, 무엇을 확인하지 않았는지를 한 곳에서 대조할 수 있어야 한다.

기능을 판단하는 기준

목적은 기술 블로그와 문서에서 아키텍처·순서·요청 흐름·상태·자료구조·표·다양한 그래프와 데이터를 일관된 시각 언어로 설명하는 것이다. 이 표현들은 핵심 범위이며 기능 수만으로 줄이지 않는다. 같은 카드·선·아이콘·탭·조작은 공통 디자인을 상속한다. 기능 수나 예제 수를 늘리는 것을 목표로 삼지 않는다. 새 표현은 설명할 문서 사례와 기존 부품으로 부족한 의미를 먼저 확인한다. 기본값으로 표현할 수 있는 그림에는 불필요한 옵션·보기·장면 선언을 요구하지 않고 같은 의미에 같은 문법을 사용한다.

애니메이션과 트래픽 효과는 필수 표현이다. 장면별 재생·반복, 동시 이동, 값 변화와 강조를 유지하고 공통 문법·시간표·부품으로 구현한다. 정적인 구조와 움직이는 설명은 같은 카드와 관계를 사용하며 화면마다 별도 효과를 구현하지 않는다. 움직임 줄이기 설정은 같은 의미를 마지막 상태로 전달한다.

사용하지 않는 옵션과 효과가 없는 별칭은 정리 대상으로 검토한다. 사용처가 예제뿐이라는 이유만으로 기능을 미사용 코드로 판정하지 않는다. 구조·순서·상태·스키마·클래스·메모리·성능 분석처럼 문서 용도가 다르면 같은 모양의 상자로 대체할 수 있는지도 의미를 먼저 대조한다.

예시

기능이 예제에 있는지 찾기

1. 아래 표에서 기능의 줄을 찾는다.
2. 예제 열의 원본(examples/*.thinkflow)을 연다. 카탈로그(npm run catalog가 .local/examples/index.html로 만든다)는 모든 예제의 첫 장면 정지 이미지 미리보기와 재생 화면, SVG, 원본 링크를 한 쪽에 모으고 iframe을 쓰지 않는다. thinkflow gallery가 쓰는 목록 쪽은 재생기를 iframe으로 모으므로 둘은 다른 출력이다.
3. 예제가 그 기능을 줄 번호와 함께 쓰는지는 scripts/lib/catalog-coverage.mjs가 원본 낱말을 읽어 알려 준다.

지원 범위를 넘는 요청

1. 간트 차트나 UML 연관 클래스처럼 전용 문법이 없는 표현을 아래 목록에서 확인한다.
2. 카드와 선으로 일부 의미를 설명할 수 있어도 해당 표준이나 차트를 지원한다고 표시하지 않는다.

상세 설계

지원하는 표현

모든 예제는 첫 줄이 thinkflow이다. mode는 줄이 없는 장면은 정지(static), 줄이 있는 장면은 한 번(once)이 기본이라, 필요할 때만(loop, 줄이 있는 정지 장면) 적는다. 첫 장면은 정지이고 움직임은 둘째 장면 이후에 둔다. 보기는 기본 보기로 충분하면 적지 않고, 방향(down)이나 라벨이 필요하거나 카드를 나눠야 할 때만 적는다. 차트는 종류마다 예제를 하나씩 두며, 개발 그림은 구조와 처리 과정이 다른 경우 별도 예제로 둔다. 메모리는 페이지 배치·주소 변환·페이지 부재, SQL은 행 결합을 구분한다. 같은 표현의 모양만 바꾼 변형 예제는 두지 않는다.

예제가 쓰지 않는 문법

문법 표에 있어도 예제가 쓰지 않아 이 문서가 예제로 연결하지 못하는 항목이다. 지원을 부정하는 것이 아니라 예제 근거가 없다는 뜻이다.

전용 표현이 없는 범위

다음은 기존 카드와 선으로 일부 의미를 그릴 수 있어도 전용 문법과 검증이 없는 범위다. 전용 지원 여부는 src/source/grammar.js의 카드, 보기, 차트 종류 목록을 기준으로 판단한다. 임의의 모든 조합을 시험했다는 뜻으로 목록을 사용하지 않는다. 이 목록은 지금 지원하지 않는다는 표시이고 구현해야 할 수용 기준이 아니다. 지원 범위에 넣으려면 먼저 승인한 제외와 보류와 대조해 따로 결정한다.

승인한 제외와 보류

설계 검토에서 정한 제외와 보류다. 제외는 지원한다고 쓰거나 우회 문법을 두지 않는다. 보류는 지원하지 않는다는 결정이 아니라 검증이 끝나지 않았다는 뜻이고, 지금은 지원한다고 쓰지 않는다.

색 수는 팔레트 개정 1의 일곱이고 고정된 최대가 아니다. 앞 네 색(파랑, 노랑, 빨강, 초록)은 공식 solid 2024 기능 아이콘에서 읽은 값이라 바뀌지 않고, 뒤 색은 후보를 실제 크기의 라이트·다크 화면으로 검수한 뒤 기록한 순서 끝에만 더한다. 개정 2가 생기기 전에는 원본에서 개정을 고르는 문법이 없다.

Things와의 연결 기준

기준은 Things 공식 페이지와 기능 페이지의 실제 렌더링이다. 예전 Refero 화면은 정규화한 측정값과 재구성 예제라 보조 참고일 뿐 기준이 아니다. 중립 면, 흰 카드, 절제된 파랑, 글자 위계를 역할이 같은 요소끼리 비교한다. 재생 조작은 시간 흐름을 장면 탭으로 고르는 구조라 Things의 대응 요소가 없고, 도구 막대 아이콘은 ThinkFlow의 확장이다(재생). ThinkFlow의 데이터 의미색과 글꼴 측정 규칙을 Things의 원본 구현이라고 부르지 않는다.

화면 값은 design-tokens의 tokens가 소유한다. ThinkFlow에서 가져온 JSON이나 생성 CSS·JS를 손으로 고치지 않는다. 그림 글꼴은 측정과 SVG 배포를 위해 포함한 글꼴을 쓰므로, 운영체제 글꼴을 쓰는 Things와 글꼴 파일이 같지는 않다. 다크 테마는 ThinkFlow의 확장이며 공식 밝은 페이지와 같은 화면이라고 판정하지 않는다. 다크의 보조 참고는 라이트·다크가 함께 있는 2018년 Things 3.7 화면 쌍이고, 현재 네이티브 버전의 다크라는 근거는 아니다. 2017년 사이트 영상 스틸도 같은 이유로 역할 비교용 보조 참고일 뿐 현재 네이티브 버전과 같다는 근거가 아니며, 두 이미지의 색을 현재 네이티브 색으로 읽지 않는다.

화면으로 확인한 범위는 예제와 검증 범위의 표가 정하고, 그 밖의 폭과 장면, 실제 기기와 Safari, Firefox는 확인하지 않았다(검증 요구사항, 미완료). 가로 넘침 없는 결과와 실제 글자가 읽히는 결과를 구분한다. 복잡한 그래프와 순서 그림은 보통 보기에서 모든 판이 같은 비율로 줄어 가로로 잘리지 않고 들어오지만 그만큼 글자가 작아지므로 글자가 읽힌다고 적지 않고, 전체 화면은 묶음 전체를 영역에 맞춘 뒤 수동 확대로 읽는다(재생). 화면 비교는 도형 경계, 텍스트 겹침, 카드 여백, 의미색, 조작의 위치를 확인하며 자동 검사 통과만으로 디자인 승인을 대신하지 않는다.

요소별 대응과 소유권

요소 하나를 추가·수정할 때 실제 Things 화면 옆에 놓고 판정한다. 같은 색·모서리 수치나 자동 테스트 통과만으로 일체감을 통과시키지 않는다. 대응 요소의 실제 캡처, 양쪽 크기·획·모서리·글꼴·간격, 주변 문맥, 선택·비선택·재생 상태, 모바일 읽기 결과를 함께 남긴다. 원본에 없는 도표·관계 기호는 확장으로 표시하고 조화 여부를 별도로 판정한다.

기준은 Things 공식 웹 페이지이고, 색의 기준점은 공식 사이트의 solid 2024 기능 아이콘이다. 웹 페이지에 보이는 요소는 computed style을 1280px Chrome에서 확인한다. 공식 2017년 사이트 영상 스틸과 2018년 Things 3.7 화면 쌍은 역할 위계의 보조 참고이고 역할이 같은 요소끼리 비교한다. 사이트 기능 아이콘의 면색은 사이트의 값이지 네이티브 앱 모든 역할의 같은 색이라는 근거가 아니다. 숨긴 접근성 제목은 화면 글자 크기 비교에서 제외한다. 아래의 확장은 Things에 동일한 도형이 있다는 뜻이 아니고, 표의 판정은 같은 모양이라는 증명이 아니라 어느 정본 경로가 맡는지의 대응이다.

스타일 책임은 테마의 값, 배치의 크기, 렌더러의 기하, 공통 CSS의 상태로 나눈다. 도형 종류마다 같은 경계 값을 다시 쓰지 않는다. 클래스 구획도 표의 col-line을 사용한다. 원본에 명시한 의미색은 공통 기본값보다 우선한다. 페이지가 시스템 글꼴을 써도 그림 측정과 출력 글꼴은 바꾸지 않는다.

지원 범위를 넓힐 때

지원하는 표현의 회귀 검사와 표현 확장의 완료 판정은 별개다. 전용 표현이 없는 범위의 표현은 구현과 검증이 갖춰지기 전까지 지원하지 않는다. 지원하지 않는 문법을 거부하는 테스트는 오류 계약의 근거이며 해당 표현을 지원한다는 근거가 아니다.

새 표현을 지원 범위에 넣기로 따로 결정하면 원본 선언, 의미와 오류 검사, 배치와 렌더링, 정적 출력과 재생, 실제 브라우저 검수를 모두 연결한다. 표준의 일부만 구현하면 지원하는 부분을 명시한다. 임의의 모든 조합이나 모든 개발 분야를 검증했다고 쓰지 않는다.

아래는 지금 요구하는 구현 목록이 아니라 아직 범위에 없는 바람의 예다. 완전한 C4 계층이나 객체 편집처럼 이 표에 없는 바람도 새 수용 기준이 되지 않으며, 필요하면 결정 기록으로 먼저 정한다.

요구사항

시험은 각 파일이 맡은 계약의 범위만 보인다. 이 표는 시험이 있는 계약을 대응시킬 뿐 전체 품질을 확인했다는 근거가 아니다. npm test는 브라우저를 열지 않는다. 그림 안의 글자 겹침, 의미색, 라이트와 다크의 모양, 재생 중 표시는 자동으로 확인하지 않고 화면으로 본다. 이 문서와 다른 문서의 표는 시험이 맡은 계약을 적을 뿐이고, 시험이나 CI를 실제로 돌린 결과는 GitHub Actions 기록과 이슈가 맡는다.

시험 번호

시험 이름은 번호로 시작한다(V1, S7, K-arch). 번호는 계약 묶음을 가리키고, 묶음의 규칙은 오른쪽 문서가 정한다. 결함을 막는 시험은 이슈 번호(#171)를 이름에 단다. 문서의 요구사항 표는 이 번호로 시험을 가리킨다.

공통 부품(카드, 필드, 선, 화살촉, 라벨, 아이콘, 탭, 도구 막대)의 모양과 상태는 부품이 하나씩 소유하므로 그 시험도 부품마다 한 곳에 한 번만 둔다. 부품 시험은 둘로 나뉜다. test/components.test.js는 부품의 기하와 구조(잰 크기와 그린 모양이 같다, 글이 이스케이프된다, 같은 도형이 같은 모양이다)를 보고, 코드가 실제로 쓰는 진입점(measure/card.js, measure/texts.js, draw/texts.js, draw/arrow.js, icons/, html/player-script.js의 figureFrame)과 공개 진입점(buildFigure, toSvg, toHtml)을 부른다. test/component-state.test.js는 출력 어댑터 사이의 일치를 본다. 켜짐과 평소의 모습을 움직이는 SVG와 HTML이 같은 정의(--fx-*)로 읽는지, 차트 방향선의 화살촉이 역할마다 정의 하나인지를 공개 진입점의 출력에서만 읽는다. 시험만을 위한 내보내기나 훅은 없다. 종류별 시험이 같은 색, 두께, 모양을 다시 확인하지 않고, 조합 시험은 데이터 전달과 연결만 본다. 이 시험들은 부품이 약속한 기하와 구조, 출력이 읽는 정의를 읽을 뿐이고, 토큰 값이 자기 자신과 같은지나 소스 글을 읽지 않으며, 계산된 색이 화면에서 어떻게 보이는지는 보지 않는다. 부품 시험으로 아직 덮지 못한 것: 카드 내용(show) 줄의 면과 색(줄의 글 자리는 test/text.test.js가 측정과 그린 자리의 일치로 본다), 격자 칸과 큐 칸의 모양, 글꼴 조각에 백틱 글자가 실리는지(보이는 글자가 글꼴에 있는지는 화면에서 본다).

브라우저에서만 보이는 계약

공개 진입점으로 읽을 수 없는 계약이다. 시험이 없다고 통과로 쓰지 않고, 실제 Chrome에서 보는 검수의 몫이다. 표의 "시험이 대신 보는 것"과 "보지 않는 것"은 시험의 범위일 뿐이고, 어떤 항목을 Chrome에서 어디까지 확인했는지는 예제와 검증 범위가 정한다. 거기 적히지 않은 항목은 검증 요구사항, 미완료다.

예제와 검증 범위

예제 30개는 test/examples.test.js가 현재 문법으로 strict 빌드하고, 첫 화면 그림 docs/assets/how-it-works.thinkflow은 CI의 check --strict가 읽는다. 첫 화면 그림 쇼케이스(docs/assets/showcase/의 일곱 쌍)도 CI의 원본 검사와 생성 그림 대조가 읽는다. npm run figures는 예제와 첫 화면 그림, 쇼케이스, 문서 그림을 함께 갱신한다. 실제 Chrome에서 확인한 범위는 아래와 같고, 그 밖은 검증 요구사항, 미완료다. 이전 모양의 화면 검수는 이번 개편(공통 장면 기본값, 한 낱말 색, 공통 도구 막대, Things 색 역할)의 근거가 아니다. 시험과 빌드를 돌린 결과와 날짜, 개수는 이슈가 맡고 이 표에 적지 않는다.

자동 시험은 브라우저 엔진도, 실제 휴대폰이나 기기의 Safari도 시험하지 않는다. 접근성 기준 전체를 충족한다고도 적지 않는다.

알려진 결함과 제한은 이 문서의 승인한 제외와 보류와 차트에 있다. 예제의 트래픽은 설명용 시뮬레이션이고, 수치는 모두 기능을 설명하려고 만든 예시 데이터다. 실제 부하나 실행 추적을 수집하는 기능은 없다.

미해결 질문

• E1: 명시한 그룹 방향·포함 관계를 유지하면서 큰 중첩 구성도를 좁은 화면에서 읽히게 할 방법. 모바일 배치 기준을 따르며, 원본 의미 변경과 보기 전환을 구분한다.
• E2: 전용 표현이 없는 범위의 항목 가운데 지원 범위에 넣을 것이 있는지. 넣는다면 어떤 문법·의미 검사·렌더러·실행 사례로 지원할지. 기존 상자·선으로 그릴 수 있다는 이유로 지원으로 승격하지 않는다.

추가한 memory-address, memory-fault, sql-join과 개편한 memory는 위 기존 일괄 검수의 범위에 포함하지 않는다. 격자 외곽 변경의 영향 범위는 이 네 예제와 stack, pointer이며, Safari와 실제 모바일 기기 검수는 미완료다.