설명 장치는 장면이 바뀌어야 이해될 때 쓴다

이 글은 표준 개념 글이 아니라, 이 사이트에서 글을 쓸 때 쓰는 설명 장치를 고르는 기준이다. 다루는 대상은 MDX 컴포넌트 다섯이다. 학습 기록이나 명단 같은 표준 개념 자체는 이 글의 범위가 아니다. 그 설명은 학습 기록은 한 줄이 한 건이다에 있다.

장치를 고르는 문제는 취향이 아니다. 잘못 고르면 독자가 개념 대신 화면을 읽는다. 그래서 먼저 무엇을 한 건으로 볼지 정한다.

정의

단위: 한 개념을 설명하기 위해 화면에 놓는 장치 하나다.

범위: 글 본문 안에서 개념을 보이는 데 쓰는 MDX 컴포넌트를 다룬다.

제외 대상: 홈 화면, 목록, 검색처럼 글 밖의 화면은 다루지 않는다.

실패 조건: 장치를 걷어내도 문장만으로 개념이 그대로 전달되는 상태다. 그때 그 장치는 장식이다.

다섯 장치가 서는 자리

장치는 두 갈래로 나뉜다. 정지 컴포넌트는 개념의 구조를 한 번에 보인다. 장면 장치는 독자의 동작에 따라 화면을 바꾼다. 아래 도해에서 각 장치를 짚으면 그 자리가 나온다.

정지 컴포넌트가 기본값이고, 장면 장치는 화면이 바뀌어야 할 때만 쓴다

도해의 지점을 짚거나 Tab으로 옮겨 보십시오

DefBox

단위, 범위, 제외 대상, 실패 조건을 못 박는다. 개념 글의 기본값이며, 이 글도 위에서 이것부터 썼다.

LayerMap

표준과 프로파일처럼 층위가 다른 말이 한 글에 섞일 때, 어느 층에 속하는지 나열한다.

FlowStrip

원천 시스템에서 소비 시스템으로 데이터가 이동하는 방향 자체가 논지일 때 쓴다.

ScrollExplain

한 자료가 단계마다 달라지는 과정을 보인다. 순서가 정해져 있어서 독자를 그 순서로 지나가게 한다.

PointExplain

짚을 지점이 몇 개로 정해져 있고 순서가 없을 때 쓴다. 독자가 궁금한 자리부터 고른다.

두 장면 장치의 차이는 순서다. 과정에는 순서가 있으므로 독자를 밀어야 하고, 구조에는 순서가 없으므로 독자가 고르게 두어야 한다. 순서가 없는 것을 스크롤로 밀면 독자는 자기가 지나온 자리를 다시 볼 방법을 잃는다.

장면 장치를 쓰는 기준

정지 컴포넌트로 설명이 끝나면 거기서 멈춘다. 장면 장치는 아래 두 조건을 같이 만족할 때만 쓴다.

개념이 상태의 변화다. 앞 상태와 뒤 상태가 다르고, 그 차이가 개념의 핵심이다.
그 변화를 문장으로 옮기면 독자가 앞 문단으로 되돌아가서 대조해야 한다.

두 번째 조건이 중요하다. 되돌아가지 않아도 되는 설명이라면 장치는 읽는 속도만 늦춘다.

예시 — 순서가 있는 과정

아래 장면은 말로 적힌 메모가 저장소에 남길 기록 한 건으로 바뀌는 과정이다. 앞의 세 줄과 뒤의 한 줄이 다르다는 것이 개념이므로, 두 상태를 같은 자리에 겹쳐 놓아야 차이가 보인다.

세 사람이 다르게 말한 오후가, 다시 물어볼 수 있는 한 줄이 된다

주간 회의 메모 / 아직 기록이 아님

저장소에 남는 줄

기획
학습했다
LMS
진도 80%
운영
완료 처리함

한 건의 기록누가, 무엇을 했는지, 무엇에, 언제. 이 네 가지가 닫혀야 한 건이다.

누가: —김준수
한 일: —완료함
대상: —4과

김준수가 4과를 완료했다

나중에 묻는 말: 4과를 끝낸 사람. 진도 80%인 사람은 이 줄로 답할 수 없다.

아직 뭐를 한 건으로 셀지 정하지 않았다. 세 줄이 다른 것을 센다. 오른쪽 그림은 아직 장식이다.

같은 오후, 세 가지 말

줄을 지우지 않는다. 그어 두고, 한 건의 테두리만 올린다. 진도 퍼센트는 테두리 밖이다.

다시 남길 수 있는 일만 한 건

메모는 위로 접혀 출처가 된다. 누가, 한 일, 대상 칸이 열린다. 그림이 옆으로 미끄러진다. 칸은 비어 있다.

칸만 열렸다

빈 칸에 김준수, 완료함, 4과가 올라온다. 칸 바탕이 잠깐 짙어진다. 진도 80%는 안 들어간다.

세 칸이 채워진다

한 줄이 남는다. 그림은 그 옆까지 내려온다. 이제 이 줄로만 묻는다.

이제 한 건이다

에서는 학습 활동 한 건을 Actor, Verb, Object 같은 칸으로 표현한다. 이 칸의 개념 설명은 학습 기록은 한 줄이 한 건이다에 있다. 여기서는 그 개념이 아니라 장치를 보이려고 같은 자료를 다시 썼다.

아닌 것

설명 장치는 구현 기록이 아니다. 장치를 어떻게 만들었는지는 이 사이트의 주제가 아니다. 장치가 개념을 어떻게 바꾸어 보이는지가 주제다. 만드는 과정은 저장소의 커밋과 스킬 문서에 남긴다.

설명 장치는 분량을 채우는 수단도 아니다. 한 글에 장면 장치를 둘 이상 넣으면 글마다 리듬이 같아진다. 그러면 독자는 어느 글에서 무엇을 봤는지 구분하지 못한다. 이 글은 장치 자체가 주제여서 둘을 같이 놓았다.

장치는 접근성을 대신하지도 않는다. 짚는 도해는 포인터가 없는 기기에서도 Tab으로 전부 열려야 하고, 스크롤 장면은 모션을 줄인 독자에게 화면을 붙잡지 않고 위에서 아래로 펼쳐져야 한다. 이 조건을 만족하지 못하면 그 장치는 쓰지 않는다.

화면 기능이 장치를 막을 때

장치가 화면의 기본 기능을 잡아먹는 경우가 있다. 홈 오른쪽 그림 안에 소개, 글, 작업, 편지 네 링크를 넣으려 했을 때가 그랬다.

그림 위에 링크를 겹치면 눌린다. 다만 그림과 링크가 한 장이 아니다. 한 장으로 만들려고 링크를 캡처해서 그림에 붙이면 모양만 남는다. 그 글자는 눌리지 않고, 검색과 탭 이동도 그 글자를 읽지 못한다.

크롬이 열어 둔 시험이 그 틈을 메운다. 진짜 링크를 그림 칸의 자식으로 두고, 그 자식을 그림으로 그리면서도 누르기는 원래 링크가 받게 한다. 이 사이트는 넓은 화면의 크롬에서만 그렇게 하고, 사파리와 좁은 화면은 왼쪽 목록을 그대로 둔다. 시험은 크롬 148부터 154까지이고 2026년 10월 20일에 끝난다.

여기서 남는 기준은 하나다. 한 장으로 만들어야 할 이유가 없으면 겹쳐 둔다. 텍스처나 셰이더처럼 픽셀을 나눠야 하는 일이 아니라면, 장치를 위해 링크를 포기하지 않는다.

다음에 열 것

이 글의 범위는 장치를 고르는 기준까지다. 아직 다루지 않은 내용은 아래와 같다.

장치가 필요 없는 글의 기본 형태: 정지 컴포넌트만으로 개념 글을 끝내는 순서다.
도해의 어휘: 상자, 화살표, 강조를 어떤 규칙으로 그릴지는 따로 정리한다.

장치의 구현 규칙은 ai-stack의 scroll-explain 스킬에 있다. 화면 글의 영어 컴포넌트 이름과 크롬 시험의 속성 이름은 아래 출처에 있다.