feat: 읽기 품질 — 제목 크기, 접히는 실험 조건, 넘어가는 표, 먼저 오는 적용 범위

제목이 컸다. 데스크톱 52~56px 은 짧은 영문 제목에는 맞지만 한국어 기술 제목에서는
넉 줄이 되고, 모바일 38~44px 은 제목만으로 첫 화면을 채워 맥락이 두 번째 화면으로
밀린다. 데스크톱 44~48px, 모바일 30~34px 로 내리고 눌려 있던 줄간(1.05~1.14)을
1.18~1.26 으로 편다.

Case 의 실험 조건은 재현하려는 사람에게 필요하고 처음 읽는 사람에게는 본론을 막는
벽이다. 버전과 데이터셋을 여러 줄로 적으면 좁은 화면에서 이 덩어리만으로 한 화면을
채운다. 접어 두되 손잡이가 무엇이 들었는지 말하게 한다.

표와 코드가 옆으로 넘어간다는 것을 말하지 않았다. 좁은 화면에서는 잘린 채 끝난
것처럼 보여서, 읽는 사람은 오른쪽 칸이 있다는 것 자체를 몰랐다. 넘어가는 쪽에만
그림자가 서게 하고(자바스크립트 없이 `local`/`scroll` 배경을 겹친다), 좁은 화면에서는
첫 칸을 붙여 둔다 — 옆으로 넘기는 동안 그 행이 무엇에 대한 줄인지 사라지면 표를 읽을
수 없다.

적용 기준의 「적용할 때」·「예외와 주의」를 판단 기준 위로 올렸다. 아래에 있으면 읽는
사람은 기준 여럿을 다 읽은 뒤에야 "이건 내 경우가 아니었다"를 알게 된다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
This commit is contained in:
DongHyeonka
2026-09-15 20:18:13 +09:00
co-authored by Claude Opus 5
parent 0b0c5cb42d
commit d3bf3925cf
3 changed files with 233 additions and 53 deletions
@@ -200,23 +200,33 @@ function CaseDocument({
</div>
</section>
<dl className="case-meta">
<div>
<dt>검증 환경</dt>
<dd><ProseText text={model.environment} /></dd>
</div>
<div>
<dt>검증 데이터</dt>
<dd><ProseText text={model.reproduction.replace(/^Dataset:\s*/, "")} /></dd>
</div>
<div>
<dt>기록</dt>
<dd>
게시 {publishedLabel(model, resolvePublishedLabel)} · 마지막 검증{" "}
{displayDate(model.lastVerifiedOn)}
</dd>
</div>
</dl>
{/*
실험 조건은 재현하려는 사람에게 필요하고, 처음 읽는 사람에게는 본론을 막는 벽이다.
버전과 데이터셋을 여러 줄로 적어 두면 좁은 화면에서 이 덩어리만으로 한 화면을 채워,
「문제·결론」 바로 다음에 와야 할 본문이 두 번째 화면으로 밀린다.
접어 둔다. 무엇이 들었는지는 손잡이가 말하므로 펴 보지 않아도 있다는 것은 안다.
*/}
<details className="case-meta-details">
<summary>실험 조건 · 검증 환경과 데이터</summary>
<dl className="case-meta">
<div>
<dt>검증 환경</dt>
<dd><ProseText text={model.environment} /></dd>
</div>
<div>
<dt>검증 데이터</dt>
<dd><ProseText text={model.reproduction.replace(/^Dataset:\s*/, "")} /></dd>
</div>
<div>
<dt>기록</dt>
<dd>
게시 {publishedLabel(model, resolvePublishedLabel)} · 마지막 검증{" "}
{displayDate(model.lastVerifiedOn)}
</dd>
</div>
</dl>
</details>
</header>
<ContextNavigator model={model} />
@@ -428,6 +438,40 @@ function ReferenceDocument({
<h2 id="purpose-title">이 기준을 쓰는 이유</h2>
<ProseText text={model.purpose} />
</section>
{/*
이 기준이 어디에 걸리고 어디에 안 걸리는지를 먼저 말한다.
「적용할 때」와 「예외와 주의」는 오래 판단 기준 아래에 있었다. 그러면 읽는 사람은 기준
여럿을 다 읽은 뒤에야 "이건 내 경우가 아니었다"를 알게 된다 — 긴 문단을 다 읽히고 나서
해당 없음을 알리는 셈이다. 두 목록을 위로 올려 나란히 둔다.
*/}
{model.applyWhen.length > 0 || model.exceptions.length > 0 ? (
<section className="reference-applicability" aria-labelledby="applicability-title">
<h2 id="applicability-title">언제 쓰는 기준인가</h2>
<div>
{model.applyWhen.length > 0 ? (
<div>
<h3>이럴 때 씁니다</h3>
<ul>
{[...model.applyWhen]
.sort((left, right) => left.order - right.order)
.map((item) => <li key={item.id}><ProseText text={item.text} /></li>)}
</ul>
</div>
) : null}
{model.exceptions.length > 0 ? (
<div>
<h3>이럴 때는 다릅니다</h3>
<ul>
{[...model.exceptions]
.sort((left, right) => left.order - right.order)
.map((item) => <li key={item.id}><ProseText text={item.text} /></li>)}
</ul>
</div>
) : null}
</div>
</section>
) : null}
<article className="public-document-body reference-body">
<section aria-labelledby="rules-title">
<h2 id="rules-title">판단 기준</h2>
@@ -445,22 +489,6 @@ function ReferenceDocument({
))}
</ol>
</section>
<section aria-labelledby="apply-title">
<h2 id="apply-title">적용할 때</h2>
<ul>
{[...model.applyWhen]
.sort((left, right) => left.order - right.order)
.map((item) => <li key={item.id}><ProseText text={item.text} /></li>)}
</ul>
</section>
<section aria-labelledby="exceptions-title">
<h2 id="exceptions-title">예외와 주의</h2>
<ul>
{[...model.exceptions]
.sort((left, right) => left.order - right.order)
.map((item) => <li key={item.id}><ProseText text={item.text} /></li>)}
</ul>
</section>
<section aria-labelledby="examples-title">
<h2 id="examples-title">예시</h2>
<ul>
@@ -383,7 +383,7 @@ a {
.home-identity h1 {
margin: 0 0 24px;
font-size: clamp(48px, 5vw, 56px);
font-size: clamp(38px, 4.4vw, 48px);
font-weight: 680;
letter-spacing: -0.055em;
line-height: 1.02;
@@ -804,10 +804,10 @@ a {
.case-header h1 {
max-width: 930px;
margin: 0;
font-size: clamp(42px, 5vw, 52px);
font-size: clamp(36px, 4.4vw, 46px);
font-weight: 660;
letter-spacing: -0.052em;
line-height: 1.14;
letter-spacing: -0.038em;
line-height: 1.18;
}
.case-summary {
@@ -1529,7 +1529,7 @@ dialog::backdrop {
.fatal-state h1 {
max-width: 700px;
margin: 17px 0 22px;
font-size: clamp(38px, 5vw, 52px);
font-size: clamp(34px, 4.4vw, 44px);
font-weight: 650;
letter-spacing: -0.048em;
line-height: 1.2;
@@ -1720,8 +1720,8 @@ dialog::backdrop {
.home-identity h1 {
margin-top: 15px;
margin-bottom: 19px;
font-size: 38px;
line-height: 1.08;
font-size: 32px;
line-height: 1.24;
}
.identity-statement {
@@ -1882,9 +1882,9 @@ dialog::backdrop {
}
.case-header h1 {
font-size: 34px;
letter-spacing: -0.045em;
line-height: 1.2;
font-size: 31px;
letter-spacing: -0.032em;
line-height: 1.26;
}
.case-summary {
@@ -2130,7 +2130,7 @@ dialog::backdrop {
.release-page-header { max-width: 940px; }
.release-page-header nav { display: flex; gap: 9px; margin-bottom: 30px; color: var(--faint); font-size: 12px; }
.release-page-header nav a:hover { color: var(--signal); }
.release-page-header h1 { margin: 14px 0 17px; font-size: clamp(42px, 5vw, 52px); font-weight: 660; letter-spacing: -0.052em; line-height: 1.13; }
.release-page-header h1 { margin: 14px 0 17px; font-size: clamp(36px, 4.4vw, 46px); font-weight: 660; letter-spacing: -0.038em; line-height: 1.18; }
.release-page-header > p:not(.section-kicker) { max-width: 780px; margin: 0; color: var(--ink-soft); font-size: 19px; line-height: 1.72; }
.release-page-header > time { display: block; margin-top: 28px; color: var(--faint); font-family: "IBM Plex Mono", monospace; font-size: 10px; }
.release-document { margin-top: 72px; border-top: 1px solid var(--line-strong); }
@@ -2147,7 +2147,7 @@ dialog::backdrop {
.profile-page { padding-top: 98px; padding-bottom: 120px; }
.profile-header { max-width: 850px; padding-bottom: 88px; }
.profile-header h1 { margin: 15px 0 20px; font-size: clamp(48px, 5vw, 56px); font-weight: 670; letter-spacing: -0.055em; line-height: 1.05; }
.profile-header h1 { margin: 15px 0 20px; font-size: clamp(38px, 4.4vw, 48px); font-weight: 670; letter-spacing: -0.04em; line-height: 1.18; }
.profile-header > p:last-child { max-width: 760px; margin: 0; color: var(--ink-soft); font-size: clamp(22px, 2.4vw, 28px); line-height: 1.55; letter-spacing: -0.025em; }
.profile-principles,
.profile-projects { display: grid; grid-template-columns: 0.7fr 1.3fr; gap: 80px; padding: 65px 0 70px; border-top: 1px solid var(--line-strong); }
@@ -2193,7 +2193,7 @@ dialog::backdrop {
.release-index-list li > a > span:last-child { display: none; }
.release-index-list h2 { font-size: 20px; }
.release-page { padding-top: 57px; padding-bottom: 90px; }
.release-page-header h1 { font-size: 38px; }
.release-page-header h1 { font-size: 32px; line-height: 1.24; }
.release-page-header > p:not(.section-kicker) { font-size: 17px; }
.release-document { margin-top: 55px; }
.release-document > section { grid-template-columns: 27px minmax(0, 1fr); gap: 11px; padding: 39px 0 43px; }
@@ -2201,7 +2201,7 @@ dialog::backdrop {
.release-document li { font-size: 15px; }
.profile-page { padding-top: 66px; padding-bottom: 90px; }
.profile-header { padding-bottom: 62px; }
.profile-header h1 { font-size: 44px; }
.profile-header h1 { font-size: 33px; line-height: 1.22; }
.profile-header > p:last-child { font-size: 21px; }
.profile-principles,
.profile-projects { display: block; padding: 48px 0 55px; }
@@ -2233,7 +2233,7 @@ dialog::backdrop {
.project-page-header { max-width: 980px; }
.project-breadcrumb { display: flex; gap: 9px; margin: 0 0 27px; color: var(--faint); font-size: 12px; }
.project-breadcrumb a:hover { color: var(--signal); }
.project-page-header h1 { margin: 0; font-size: clamp(42px, 5vw, 52px); font-weight: 660; letter-spacing: -0.052em; line-height: 1.13; }
.project-page-header h1 { margin: 0; font-size: clamp(36px, 4.4vw, 46px); font-weight: 660; letter-spacing: -0.038em; line-height: 1.18; }
.project-page-header > p:not(.project-breadcrumb) { max-width: 800px; margin: 17px 0 0; color: var(--ink-soft); font-size: 18px; line-height: 1.72; }
.project-navigation { display: flex; gap: 28px; margin-top: 46px; border-bottom: 1px solid var(--line-strong); }
.project-navigation a { position: relative; display: inline-flex; min-height: 48px; align-items: center; color: var(--muted); font-size: 13px; font-weight: 560; }
@@ -2293,7 +2293,7 @@ dialog::backdrop {
.project-index-list dl { display: block; }
.project-index-list dl div + div { margin-top: 7px; }
.project-page { padding-top: 57px; padding-bottom: 90px; }
.project-page-header h1 { font-size: 38px; }
.project-page-header h1 { font-size: 32px; line-height: 1.24; }
.project-page-header > p:not(.project-breadcrumb) { font-size: 16px; }
.project-navigation { gap: 18px; overflow-x: auto; }
.project-navigation a { flex: 0 0 auto; min-height: 48px; }
@@ -2343,7 +2343,7 @@ dialog::backdrop {
.public-page-header h1,
.public-document-header h1 {
margin: 15px 0 18px;
font-size: clamp(42px, 5vw, 52px);
font-size: clamp(36px, 4.4vw, 46px);
font-weight: 660;
letter-spacing: -0.052em;
line-height: 1.13;
@@ -2601,7 +2601,7 @@ dialog::backdrop {
.public-index-page,
.public-document-page { padding-top: 60px; padding-bottom: 90px; }
.public-page-header h1,
.public-document-header h1 { font-size: 38px; }
.public-document-header h1 { font-size: 32px; line-height: 1.24; }
.public-page-header > p:last-child,
.public-document-header > p { font-size: 17px; }
.public-filter-form { grid-template-columns: 1fr; margin-top: 40px; }
@@ -3677,3 +3677,149 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
gap: 2px;
}
}
/* 실험 조건 — 재현하려는 사람에게 필요하고, 처음 읽는 사람에게는 벽이다 */
.case-meta-details {
margin-top: 34px;
padding-top: 20px;
border-top: 1px solid var(--line);
}
.case-meta-details > summary {
color: var(--muted);
cursor: pointer;
font-size: 13px;
font-weight: 620;
list-style: none;
}
.case-meta-details > summary::-webkit-details-marker {
display: none;
}
.case-meta-details > summary::after {
content: " ▸";
color: var(--line-strong);
}
.case-meta-details[open] > summary::after {
content: " ▾";
}
.case-meta-details > summary:hover {
color: var(--signal);
}
.case-meta-details .case-meta {
margin-top: 18px;
}
/* 표와 코드가 옆으로 넘어간다는 것을 보이게 한다 */
/*
넘어가는 쪽에만 그림자가 선다. `local` 배경은 내용과 함께 스크롤되고 `scroll` 배경은 칸에
붙어 있으므로, 둘을 겹치면 "왼쪽/오른쪽에 더 있다"를 자바스크립트 없이 말할 수 있다.
넘어간다는 사실을 말하지 않던 동안 좁은 화면의 표는 잘린 채로 끝난 것처럼 보였다 — 읽는
사람은 오른쪽 칸이 있다는 것 자체를 몰랐다.
*/
.data-table-wrap,
.code-block pre {
background-repeat: no-repeat;
background-position:
left center,
right center,
left center,
right center;
background-size:
30px 100%,
30px 100%,
12px 100%,
12px 100%;
background-attachment: local, local, scroll, scroll;
}
.data-table-wrap {
background-image:
linear-gradient(to right, var(--paper), rgb(252 252 251 / 0%)),
linear-gradient(to left, var(--paper), rgb(252 252 251 / 0%)),
radial-gradient(farthest-side at 0 50%, rgb(0 0 0 / 13%), transparent),
radial-gradient(farthest-side at 100% 50%, rgb(0 0 0 / 13%), transparent);
}
.code-block pre {
background-image:
linear-gradient(to right, var(--code-canvas), rgb(21 24 29 / 0%)),
linear-gradient(to left, var(--code-canvas), rgb(21 24 29 / 0%)),
radial-gradient(farthest-side at 0 50%, rgb(0 0 0 / 45%), transparent),
radial-gradient(farthest-side at 100% 50%, rgb(0 0 0 / 45%), transparent);
}
/*
좁은 화면에서는 첫 칸을 붙여 둔다. 옆으로 넘기는 동안 그 행이 무엇에 대한 줄인지 사라지면
표를 읽을 수 없다.
*/
@media (max-width: 899px) {
.data-table-wrap tbody th[scope="row"] {
position: sticky;
left: 0;
background: var(--paper);
}
.data-table-wrap thead th:first-child {
position: sticky;
left: 0;
background: #f0f0ed;
}
}
/* 적용 기준 — 언제 쓰는 기준인가를 먼저 말한다 */
.reference-applicability {
margin-top: 40px;
padding-block: 26px 30px;
border-top: 1px solid var(--line-strong);
border-bottom: 1px solid var(--line);
}
.reference-applicability > h2 {
margin: 0;
font-size: 13px;
font-weight: 650;
letter-spacing: 0.06em;
text-transform: uppercase;
color: var(--muted);
}
.reference-applicability > div {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
gap: 22px 44px;
margin-top: 20px;
}
.reference-applicability h3 {
margin: 0;
font-size: 15px;
font-weight: 640;
color: var(--ink);
}
.reference-applicability ul {
margin: 11px 0 0;
padding: 0;
list-style: none;
}
.reference-applicability ul li {
padding-block: 5px;
color: var(--ink-soft);
font-size: 15px;
line-height: 1.62;
}
.reference-applicability ul li::before {
content: "— ";
color: var(--line-strong);
}
@@ -372,8 +372,14 @@ describe("shared Public record renderer", () => {
expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent(
"컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
);
expect(screen.getByText("수정 중인 데이터셋")).toBeVisible();
expect(screen.getByText(/게시 2026\.08\.14 · 마지막 검증 2030\.01\.02/)).toBeVisible();
/*
실험 조건은 접혀 있다 — 재현하려는 사람에게 필요하고, 처음 읽는 사람에게는 본론을 막는
벽이다. 접혀 있어도 문서에는 있어야 하므로 존재는 확인하고, 손잡이가 무엇이 들었는지
말하는지까지 본다.
*/
expect(screen.getByText("실험 조건 · 검증 환경과 데이터")).toBeVisible();
expect(screen.getByText("수정 중인 데이터셋")).toBeInTheDocument();
expect(screen.getByText(/게시 2026\.08\.14 · 마지막 검증 2030\.01\.02/)).toBeInTheDocument();
expect(screen.getAllByRole("navigation", { name: "문서 목차" })).toHaveLength(
1,
);