feat: 문서 종류를 독자의 말로 바꾸고 미해결을 눈에 띄게 한다

이 저장소의 종류 이름은 글을 담아 둔 방식의 이름이었다 — Case, Reference,
Open Question. 독자는 그 말을 배우고 나서야 목록을 읽을 수 있었고, 정작
뜻풀이는 홈 바닥(2,000px 아래)에 있었다. 이름이 하는 일을 말하게 한다:

  Case → 직접 해보니        Reference → 다음에 쓸 기준
  Question → 아직 모르는 것  Concept → 어떻게 동작하나
  Decision → 이렇게 하기로

이름이 스스로 설명하므로 홈 바닥의 뜻풀이 섹션은 종류별 입구로 바꾼다.
그 목록에 손으로 적어 둔 `OpenQuestion` 은 사이트 어디에도 없는 여섯 번째
표기였다. 탐색 필터·Case/개념 breadcrumb·종류별 화면 제목도 각자 이름을
적고 있었다 — 전부 공용 표를 쓰게 한다.

목록의 종류 표시는 다섯이 같은 회색 11px 이라 스캔되지 않았다. 색을 다섯
칠하는 대신 지식의 상태 셋(확인함·정리함·미해결)으로 가르고 미해결만
강조한다. 이 기록에서 가장 정직한 신호인데 가장 안 보였다.

mono 글꼴과 대문자 변환도 걷어낸다 — 이름이 한국어 문구가 되었고, mono 는
한글을 갖지 않아 낱말 사이만 벌어진다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
This commit is contained in:
DongHyeonka
2026-09-01 15:19:47 +09:00
co-authored by Claude Opus 5
parent 2b042829cf
commit a6413d0301
11 changed files with 101 additions and 46 deletions
@@ -2,6 +2,14 @@ import { Link, useNavigate } from "react-router-dom";
import type { RecordKind } from "../../../application/ports/public-content-queries.ts";
import { usePublicContent } from "../use-public-content.tsx";
import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
/*
탐색이 거를 수 있는 종류. 이름은 공용 표에서 가져온다 — 예전에는 이 목록만 「개념」이라
적어 두어 배지·머리말과 어긋났고, 같은 문서가 화면마다 다른 이름으로 보였다.
결정은 프로젝트 안에서만 읽히므로 여기 없다.
*/
const EXPLORE_KINDS = ["CASE", "REFERENCE", "QUESTION", "CONCEPT"] as const;
export function ExploreFilterForm({
action,
@@ -94,7 +102,7 @@ export function ExploreFilterForm({
onSubmit={submit}
>
{showType ? (
<label><span>유형</span><select name="type" defaultValue={kind ?? ""}><option value="">전체</option><option value="CASE">Case</option><option value="REFERENCE">Reference</option><option value="QUESTION">Open Question</option><option value="CONCEPT">개념</option></select></label>
<label><span>유형</span><select name="type" defaultValue={kind ?? ""}><option value="">전체</option>{EXPLORE_KINDS.map((entry) => <option key={entry} value={entry}>{DOCUMENT_KIND_LABELS[entry]}</option>)}</select></label>
) : null}
<label><span>주제</span><select name="topic" defaultValue={selectedTopic ?? ""}><option value="">전체</option>{topics.map((item) => <option value={item.slug} key={item.slug}>{item.name}</option>)}</select></label>
<label><span>프로젝트</span><select name="project" defaultValue={selectedProject ?? ""}><option value="">전체</option>{projects.map((item) => <option value={item.slug} key={item.slug}>{item.title}</option>)}</select></label>
@@ -1,7 +1,10 @@
import { Link } from "react-router-dom";
import type { PublicRecord } from "../../../application/ports/public-content-queries.ts";
import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
import {
DOCUMENT_KIND_LABELS,
DOCUMENT_KIND_STATES,
} from "../../shared/document-kind-labels.ts";
import { cardSummary } from "../../../domain/content-format/card-summary.ts";
export function PublicRecordList({
@@ -20,7 +23,14 @@ export function PublicRecordList({
{records.map((record) => (
<li key={record.path}>
<Link to={record.path}>
<span className="record-kind">{DOCUMENT_KIND_LABELS[record.kind]}</span>
{/*
다섯 종류가 같은 회색 11px 로 나오면 목록이 스캔되지 않는다. 색을 다섯 개 칠하는
대신 지식의 상태 셋으로만 가른다 — 그중 「아직 모르는 것」만 강조한다. 이 기록에서
가장 정직한 신호인데 지금까지 가장 안 보였다.
*/}
<span className="record-kind" data-state={DOCUMENT_KIND_STATES[record.kind]}>
{DOCUMENT_KIND_LABELS[record.kind]}
</span>
<div>
<strong>{record.title}</strong>
<p>{cardSummary(record.summary)}</p>
@@ -7,12 +7,13 @@ import {
import { ExploreFilterForm } from "../components/explore-filter-form.tsx";
import { PublicRecordList } from "../components/public-record-list.tsx";
import { usePublicContent } from "../use-public-content.tsx";
import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
const kinds = {
cases: { kind: "CASE", title: "Case", description: "문제를 재현하고 관찰한 값에서 설계 결론까지 따라갑니다." },
references: { kind: "REFERENCE", title: "Reference", description: "다시 확인할 수 있는 기술 기준과 적용 범위를 정리합니다." },
questions: { kind: "QUESTION", title: "Open Question", description: "확인한 사실과 미지수, 다음 검증을 공개적으로 추적합니다." },
concepts: { kind: "CONCEPT", title: "개념", description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다." },
cases: { kind: "CASE", title: DOCUMENT_KIND_LABELS.CASE, description: "문제를 재현하고 관찰한 값에서 설계 결론까지 따라갑니다." },
references: { kind: "REFERENCE", title: DOCUMENT_KIND_LABELS.REFERENCE, description: "다시 확인할 수 있는 기술 기준과 적용 범위를 정리합니다." },
questions: { kind: "QUESTION", title: DOCUMENT_KIND_LABELS.QUESTION, description: "확인한 사실과 미지수, 다음 검증을 공개적으로 추적합니다." },
concepts: { kind: "CONCEPT", title: DOCUMENT_KIND_LABELS.CONCEPT, description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다." },
} as const;
function optionalString(value: unknown): string | undefined {
@@ -11,28 +11,32 @@ import {
LatestIndex,
type LatestEntry,
} from "../components/latest-index.tsx";
import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
/*
종류별 입구. 예전에는 여기가 "이 낱말은 이런 뜻입니다" 하는 범례였고, 그 낱말을 쓰는 목록은
2,000px 위에 있었다 — 배우기 한참 전에 먼저 쓰는 셈이었다. 이름 자체가 하는 일을 말하도록
바꾼 뒤로는 뜻풀이가 필요 없으므로, 설명 대신 그 종류에서 무엇을 얻는지를 적는다.
라벨은 공용 표에서 가져온다. 여기 손으로 적어 두었을 때 `OpenQuestion` 이라는, 사이트
어디에도 없는 여섯 번째 표기가 생겨 있었다.
*/
const exploreEntries = [
{
label: "Case",
description: "문제를 따라가며 검증 과정을 읽습니다",
kind: "CASE",
description: "무엇을 해보고 무엇을 확인했는지",
path: "/explore/cases",
},
{
label: "Reference",
description: "다시 찾을 수 있는 기술 기준을 확인합니다",
kind: "REFERENCE",
description: "다음에 같은 판단을 할 때 볼 것",
path: "/explore/references",
},
{
label: "OpenQuestion",
description: "아직 끝나지 않은 판단과 다음 검증을 봅니다",
kind: "QUESTION",
description: "아직 답하지 못한 것과 다음 검증",
path: "/explore/questions",
},
{
label: "Project",
description: "여러 기록을 하나의 시스템 맥락에서 연결합니다",
path: "/projects",
},
] as const;
function optionalString(value: unknown): string | undefined {
@@ -177,15 +181,15 @@ export function HomePage() {
<div className="section-heading-row explore-heading">
<div>
<p className="section-kicker">Explore</p>
<h2 id="explore-title">어떤 맥락으로 읽을까요?</h2>
<h2 id="explore-title">종류별로 읽기</h2>
</div>
</div>
<ul className="explore-list">
{exploreEntries.map((entry) => (
<li key={entry.label}>
<li key={entry.kind}>
<Link to={entry.path}>
<span>{entry.description}</span>
<strong>{entry.label}</strong>
<strong>{DOCUMENT_KIND_LABELS[entry.kind]}</strong>
<span aria-hidden="true">↗</span>
</Link>
</li>
@@ -5,17 +5,34 @@ type RecordKind = components["schemas"]["RecordKind"];
/**
* 문서 종류를 사람에게 보여 주는 이름.
*
* <p>이 표는 화면마다 하나씩 복사되어 있었고, 그래서 갈라졌다. 같은 `QUESTION` 이 공개 화면에서는
* "Open Question", 작업본 목록과 게시 기록에서는 "Question", 편집기 상태 줄에서는 "QUESTION" 으로
* 나왔다 — 여섯 벌 중 네 가지 표기였다. 쓰는 사람은 같은 문서를 화면마다 다른 이름으로 만난다.
* <p>이름은 문서의 정체가 아니라 독자에게 하는 일로 적는다. `Reference` 는 이 저장소가 문서를
* 담아 둔 방식의 이름이지 읽는 사람의 말이 아니다 — 종류 이름이 스스로 설명하면 "어떤 맥락으로
* 읽을까요?" 같은 범례가 따로 필요 없다.
*
* <p>표가 화면마다 복사되어 있던 시절에는 같은 `QUESTION` 이 화면마다 네 가지 이름으로 나왔다.
*
* <p>한 곳에 두면 다음에 종류가 늘어날 때도 한 번만 고친다. 종류를 더하면 이 표가 비어 있는 것을
* 타입이 잡는다 — `Record<RecordKind, string>` 이므로 빠진 종류가 있으면 컴파일되지 않는다.
*/
export const DOCUMENT_KIND_LABELS: Record<RecordKind, string> = {
CASE: "Case",
REFERENCE: "Reference",
QUESTION: "Open Question",
CONCEPT: "개념",
PROJECT_DECISION: "Decision",
CASE: "직접 해보니",
REFERENCE: "다음에 쓸 기준",
QUESTION: "아직 모르는 것",
CONCEPT: "어떻게 동작하나",
PROJECT_DECISION: "이렇게 하기로",
};
/**
* 독자가 실제로 구분해야 하는 것은 지식의 상태다. 다섯 종류를 셋으로 접는다 — 확인한 것,
* 정리한 것, 아직 모르는 것. 목록에서 미해결만 눈에 띄게 하는 것이 이 표의 쓰임이다.
*
* <p>미해결이 이 기록의 가장 정직한 신호인데 다섯 종류가 같은 회색 11px 로 나오면 그것이
* 가장 안 보인다.
*/
export const DOCUMENT_KIND_STATES: Record<RecordKind, "CONFIRMED" | "SETTLED" | "OPEN"> = {
CASE: "CONFIRMED",
CONCEPT: "CONFIRMED",
REFERENCE: "SETTLED",
PROJECT_DECISION: "SETTLED",
QUESTION: "OPEN",
};
@@ -160,7 +160,7 @@ function CaseDocument({
>
<header className="shell case-header">
<nav className="case-breadcrumb" aria-label="문서 경로">
<Link to="/explore/cases">Case</Link>
<Link to="/explore/cases">{DOCUMENT_KIND_LABELS.CASE}</Link>
<span aria-hidden="true">/</span>
<TargetLink target={model.topic} />
{model.project ? (
@@ -255,7 +255,7 @@ function ConceptDocument({
>
<header className="shell case-header">
<nav className="case-breadcrumb" aria-label="문서 경로">
<Link to="/explore/concepts">개념</Link>
<Link to="/explore/concepts">{DOCUMENT_KIND_LABELS.CONCEPT}</Link>
<span aria-hidden="true">/</span>
<TargetLink target={model.topic} />
{model.project ? (
@@ -2391,7 +2391,17 @@ dialog::backdrop {
padding: 26px 0 27px;
}
.public-record-list a:hover strong { color: var(--signal); }
.record-kind { padding-top: 3px; color: var(--faint); font-family: "IBM Plex Mono", monospace; font-size: 11px; text-transform: uppercase; }
/*
종류 표시. 이름이 이제 한국어 문구이므로 대문자 변환을 쓰지 않는다 — 한글에는 대소문자가
없고, mono 글꼴은 한글을 갖지 않아 낱말 사이만 벌어진다.
*/
.record-kind { padding-top: 3px; color: var(--faint); font-size: 12px; letter-spacing: -0.01em; }
/*
다섯 종류를 색 다섯으로 칠하지 않는다. 독자가 구분해야 하는 것은 지식의 상태 셋이고, 그중
아직 답하지 못한 것만 눈에 띄면 된다.
*/
.record-kind[data-state="OPEN"] { color: var(--warning, #b8791f); font-weight: 650; }
.record-kind[data-state="SETTLED"] { color: var(--muted); }
.public-record-list strong { display: block; font-size: 18px; font-weight: 630; letter-spacing: -0.02em; }
.public-record-list p { max-width: 700px; margin: 7px 0 6px; color: var(--muted); font-size: 14px; line-height: 1.62; }