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:
co-authored by
Claude Opus 5
parent
0b0c5cb42d
commit
d3bf3925cf
+61
-33
@@ -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,
|
||||
);
|
||||
|
||||
Reference in New Issue
Block a user