디자인 시스템
화면 토큰, 컴포넌트, 집필 규칙, HTML 패턴, 금지 목록. 주소 뒤에 해시를 붙이면 그 섹션이 열립니다.
찾는 법
탭을 바꿔도 섹션은 문서 안에 남습니다. #rule-5, #pattern-math처럼 열면 해당 탭이 열리고 그 제목으로 이동합니다. 기계가 읽을 목록은 #design-system-map JSON입니다.
| 앵커 | 내용 |
|---|---|
| #ds-tokens | 색, 서체, 굵기 500, 본문 폭 |
| #ds-components | 제목, 에피그래프, 수식, 코드, 콜아웃 실물 |
| #specimen-epigraph | 장 앞 인용. blockquote.epigraph |
| #rule-5 | 수식은 KaTeX. 한국어 잇기는 식 밖 |
| #rule-10 | 짧은 연결어미 뒤에는 쉼표를 두지 않음 |
| #pattern-math | 수식 카드 마크업 |
| #ds-forbidden | 쓰지 않는 패턴 |
| #ds-debug | ?debug로만 보이는 편집 장치, 언어 폴더, 메타 |
색
기본 시트는 흰색이고 본문 잉크는 #111입니다. Aa에서 세피아, 그레이, 다크로 바꿉니다.
--bg-sheet 종이--text-ink 본문 #111--text-secondary 보조--text-muted 캡션--accent-primary 링크. 밑줄 없음본문·표·목록의 링크는 --accent-primary이고, 기본·방문·호버 모두 밑줄이 없습니다. 목차와 이전/다음은 각자 글자색을 유지합니다.
--bg-code 코드 #F6F8FA서체와 굵기
본문만 명조입니다. 제목, 헤더, 목차는 고딕입니다. 굵기는 장 제목부터 코드 키워드까지 500 한 가지입니다. 장 제목과 절 제목의 위계는 크기로 냅니다. 소제목은 본문과 같은 크기이고, 고딕과 굵기 500으로 구분합니다.
| 역할 | 크기 | 굵기 | 서체 |
|---|---|---|---|
| 장 제목 | 1.86rem | 500 | 고딕 |
| 절 제목 | 1.18rem | 500 | 고딕 |
| 소제목 | 본문과 같음 | 500 | 고딕 |
| 본문 | 18px | 400 | 명조 |
| 강조, 표 머리 | 본문 | 500 | 본문과 같음 |
명조 스택은 AppleMyungjo, KoPub Batang, Nanum Myeongjo, Batang, Source Serif 4, Noto Serif KR입니다. 고딕은 Pretendard와 Inter입니다. 그레이스케일 안티앨리어싱은 쓰지 않습니다. 줄간격 기본은 넉넉함 1.85입니다.
폭과 목차
본문 폭은 42rem이고, 1280px부터 52rem, 1600px부터 64rem입니다. 목차는 왼쪽 끝 오버레이 336px이며 기본은 숨김입니다. 핀으로 본문을 밀지 않습니다. 저널 여백 뷰는 없습니다.
제목
부제는 본문 서체, 굵기 400입니다. 절 제목은 아래처럼 본문보다 조금만 큽니다.
1. 절 제목 견본
본문 문장입니다. 이어지는 문단은 첫 줄을 한 글자 들여 씁니다.
둘째 문단은 들여쓰기됩니다. 용어 박스는 쓰지 않고, 처음 나올 때 영어를 괄호로 답니다. 예: 동기화기(Synchronizer).
에피그래프
장이나 부의 첫 질문입니다. 본문 명조이고, 출처는 cite입니다.
"체결부터 결제까지 기간이 길어질수록 위험도 함께 커진다. 한쪽이 지급불능이나 채무불이행에 빠질 가능성이 높아지고 미결제 거래는 불어난다. 그사이 증권 가격이 약정 가격에서 크게 벗어날 여지도 넓어진다." — 지급결제제도위원회·국제증권감독자기구, 「증권결제시스템에 대한 권고」 권고 3 해설, 2001년 11월
수식
그러나 기관 쌍에서는
코드
언어 표식은 한 가지 칩이고, 복사는 아이콘입니다. 두 언어는 위아래로 이어 붙입니다. 보기 전환 탭은 없습니다.
await db.insert(row);
signatory obligor, beneficiary
콜아웃
상단 라벨은 두지 않습니다. 말할 내용은 이 문장처럼 문단의 첫 줄입니다.
편집 방향
초반에는 문제의식과 절제된 지적 유머로 들어오고, 뒤로 갈수록 수식, 알고리즘, Daml 패턴, 노드 운영, 규제까지 밀도를 올립니다. 역사 일화는 챕터의 15~20% 이내입니다. 제목과 본문의 80% 이상은 Daml 규칙, Canton 구성요소, 상태 전이, 실물 계약입니다.
| 파트 | 축 |
|---|---|
| Part 1 | 시장 미시구조, O(n²) 대사, 결제 완결성 |
| Part 2 | 실물 계약, Daml 구문, TypeScript 대조, Isabelle/HOL |
| Part 3 | 블라인드 머클 뷰, 7단계 합의, 격자 준동형 해시 |
| Part 4 | PostgreSQL, 인덱서, HOCON, 복구와 프루닝 |
| Part 5 | Splice, CIP, 한국 STO, 글로벌 규제 |
| Part 6 | 계약 주방 요리책, Daml 3.7 디자인 패턴 26개 레시피 |
규칙 1. 메커니즘 중심 표제
제목만 읽어도 기술 요소가 보여야 합니다. 예: 원장 API(Ledger API), 서명자(Signatory), 2단계 커밋(Two-Phase Commit, 2PC).
규칙 2. 첫 등장에 영어 병기
외래 용어, 역할, 기관명은 문서에서 처음 나올 때 영어를 괄호에 답니다. 이후에는 한국어나 약어만 써도 됩니다. 예: 활성 계약 세트(Active Contract Set, ACS), 예탁결제원(Korea Securities Depository, KSD).
규칙 3. 실물 계약, TypeScript, Daml
Daml 문법을 암기 목록으로 두지 않습니다. 실물 계약 조항, TypeScript로 구현할 때의 구멍, Daml이 그 구멍을 어떻게 막는지의 순서로 잇습니다.
규칙 4. 출처와 경로를 본문에 두지 않음
독자용 HTML에는 내부 파일 경로, 줄 번호, 저장소를 열어 봤다는 말을 쓰지 않습니다. 경로 없는 Daml 모듈명과 교육용 패턴 코드는 괜찮습니다.
규칙 5. 수식은 조판
핵심 주장은 수식 카드나 상태 전이로 못 박습니다. 이항계수는 \binom, 분수는 \dfrac입니다. 두 식을 잇는 한국어는 .math-bridge에 두고 식 안에 넣지 않습니다. 식별자는 카드 아래 캡션입니다.
규칙 6. 스팟 삽화
1960~70년대 미국 인디 스팟과 벨 연구소 매뉴얼 두들입니다. 여백 75% 이상, 딥펜 먹선, 회색 망점, 그림 안 글자는 없습니다. 캡션은 이미지 아래, 영문 프롬프트는 접이식입니다.
규칙 10. 연결어미 뒤 쉼표
영어 For A, B를 ~려면, ~한다로 옮기면 번역투 쉼표가 됩니다. 짧은 조건·이유 절 뒤에는 쉼표를 두지 않습니다. 쉼표는 나열, 호격, 삽입, 수식 범위가 헷갈릴 때 씁니다.
금지 틀은 ~려면, ~면, ~므로, ~서, ~지만, ~고, ~며, 바로 뒤에 본절이 오는 짧은 문장입니다. 절이 길거나 주어가 바뀌어 숨이 필요하면 쉼표를 남기거나 문장을 나눕니다. 이웃한 두 문장이 같은 연결어미로 시작하면 둘째 문장의 뼈대를 바꿉니다.
사실, 수치, 고유명사, 합니다체, 첫 영어 병기는 유지합니다. 해요체로 낮추거나 영어 괄호를 지우지 않습니다.
나쁨: 계약의 효과가 강제력을 가지려면, 들어가는 일은 자발적이어야 한다. 의도대로 수행된다고 보장하려면, 정형 검증이 가능해야 한다. 좋음: 계약의 효과가 강제력을 가지려면 그 계약에 들어서는 일이 자발적이어야 한다. 의도한 수행을 보장하는 길은 정형 검증이다.
챕터 6단계
| 단계 | 비중 | 역할 |
|---|---|---|
| 1. 헤더 | 5% | 장 제목, 부제, 선택적 메타. eyebrow 없음 |
| 2. 도입 | 15% | 실물 균열과 스팟 삽화 |
| 3. 정식화 | 20% | 수식 카드 |
| 4. 메커니즘 | 35% | 실물 계약, TypeScript, Daml |
| 5. 제도 | 15% | statute. 위아래 선. 출처는 문장 안 |
| 6. 정리 | 10% | recap과 텍스트 이전/다음 |
챕터 헤더
<h1 class="chapter-title">…</h1> <p class="chapter-subtitle">…</p> <div class="chapter-meta-bar">…</div>
본문
term-figure와 margin-note는 쓰지 않습니다. 정의는 문장으로 흡수합니다.
문장은 규칙 10을 따릅니다. 짧은 연결어미 뒤 쉼표는 빼고, 같은 틀이 두 문장에 반복되면 둘째 문장만 바꿉니다.
나쁨: ~려면, ~한다. ~려면, ~한다. 좋음: ~려면 ~한다. 둘째 문장은 다른 뼈대로 잇는다.
에피그래프
<blockquote class="epigraph"> "…" <cite>— …</cite> </blockquote>
제1부 시작글의 첫 질문과 같은 자리입니다. 규정 문단(statute)이나 수식 카드와 섞지 않습니다.
수식 카드
<figure class="math-figure">
<div class="math-card">
<div class="math-formula" data-tex="|E|=\binom{n}{2}=\dfrac{n(n-1)}{2}=\Theta(n^{2})">…</div>
<p class="math-bridge">그러나 …에서는</p>
<div class="math-note">…해설…</div>
</div>
<figcaption class="math-card-caption">INVARIANT 1.1 · …</figcaption>
</figure>
수식이 있는 페이지는 assets/vendor/katex/의 CSS와 JS를 book.js보다 먼저 불러옵니다.
삽화
<figure class="spot-figure"> <div class="spot-image-frame"><img alt="…" /></div> <figcaption class="spot-caption">…</figcaption> <details class="prompt-drawer">…</details> </figure>
프롬프트 서랍은 주소에 ?debug가 있을 때만 문서에 남습니다. 꺼져 있으면 book.js가 그 요소를 지웁니다.
규정 statute
법·감독 문단. 위아래 선 사이의 본문입니다. 작은 캡션은 두지 않고, 출처는 문장 안에 있습니다.
장 요약 recap
장이 남기는 명제. 제목은 절 제목과 같은 크기이고, 항목 이름은 문장 첫머리입니다.
콜아웃
<div class="callout architect"> <p>첫 문장이 요지.</p> </div>
이전 / 다음
<nav class="chapter-pager"> <a class="pager-link">…</a> <a class="pager-link next">…</a> </nav>
포털 목록은 .part-grid 안의 .part-card를 헤어라인 리스트로만 둡니다.
쓰지 않음
| 금지 | 대신 |
|---|---|
.chapter-eyebrow, .track-badge, 러닝헤드 | 장 제목과 부제만 |
| 박스 왼쪽 컬러 바 | 헤어라인과 옅은 배경 |
박스 안 상단 INVARIANT, HISTORY, callout-title | 아래 캡션, 또는 문단 첫 문장 |
.pager-card | .pager-link |
data-layout="journal" | 단일 컬럼 |
수식을 C(n, 2), n/2 평문으로만 | KaTeX data-tex |
| 코드 보기 전환 탭, 노트북 제목 줄 | 위아래 연속. .lang-tag 하나, 복사 아이콘 |
| 굵기 600 이상 | 강조는 500. 위계는 크기 |
| 링크 밑줄 | 색만. text-decoration: none |
HTML 본문 내 마크다운 기호(**강조**) 직접 노출 | 시맨틱 태그 <strong>강조</strong> 사용 (원시 별표 노출 절대 금지) |
| 어색한 기계적 직역어 | 표준 비즈니스·소프트웨어 공학 용어 '구문 전개(디슈거링, Desugaring)' 사용 |
짧은 ~려면, ~면, ~므로, ~서, ~지만, | 쉼표 없이 잇는다. 길면 문장을 나눈다. 규칙 10 |
이웃 문장이 같은 -려면 -면으로 시작 | 둘째 문장의 뼈대를 바꾼다 |
편집 화면 ?debug
독자 화면과 편집 화면을 주소 한 칸으로 나눕니다. 아무 장 주소 뒤에 ?debug를 붙이면 그 브라우저 탭에서 켜지고, ?debug=0을 붙이면 꺼집니다. 상태는 sessionStorage에 남아, 같은 탭에서 장을 옮겨도 유지됩니다.
| 켜면 보이는 것 | 꺼져 있을 때 |
|---|---|
삽화 프롬프트 .prompt-drawer | DOM에서 제거. 검색 문장에 생성 프롬프트가 섞이지 않게 한다 |
| 목차 제목 「도서 안내 및 편집 전략」 | 제목만 숨김. 표지(HOME) 항목은 남는다 |
| 집필 가이드, 디자인 시스템 목차 링크 | 목차와 장 이동 메뉴에서 빠진다 |
| 본문의 집필 가이드·디자인 시스템 링크 | 그 앵커를 지운다. 표지의 이전 링크가 여기에 해당한다 |
이 페이지의 목차 링크도 그때만 나옵니다. 직접 열 주소는 /design-system.html입니다. 한글만 두고 ko와 en 밖에 있습니다.
언어 폴더
book-site/ ├── index.html 언어 입구 ├── design-system.html 한글 디자인 시스템. ko/en 밖 ├── assets/ css, js, images, vendor. 두 언어가 같이 씀 ├── ko/ 한글 본문 │ ├── index.html │ └── chapters/ ├── en/ 영문 자리. 번역 전까지 ko와 같은 한글 │ ├── index.html │ └── chapters/ ├── companion-notes/ 집필 노트. 독자 페이지가 아님 └── WRITING_STRATEGY_AND_STYLE_GUIDE.md
장 HTML의 공용 자산은 ../../assets/입니다. 표지는 ../assets/입니다. 삽화 파일은 복사하지 않습니다. 목차의 디자인 시스템 주소는 언어 루트에서 한 칸 위인 ../design-system.html입니다.
en은 ko를 복사한 자리입니다. 본문이 아직 한글이므로 lang은 ko이고, 폴더만 data-locale="en"으로 구분합니다. 한 장을 영어로 바꾸면 그 페이지의 lang을 en으로 바꿉니다.
헤더의 KO · EN은 같은 장의 언어 주소로 옮기고, 그 선택을 localStorage에 남깁니다. 입구 index.html만 저장된 선택이 있으면 그 언어로, 없으면 브라우저 언어로 ko 또는 en 표지에 보냅니다. 장 주소로 들어온 경우에는 언어를 바꾸지 않습니다. 이 페이지는 짝이 없으므로 선택기는 그 언어의 표지로 갑니다.
메타
각 장 <head>의 설명은 그 페이지 부제입니다. canonical, og:title, og:description, og:locale(ko_KR)을 같이 둡니다. 표지는 og:type이 website이고, 장은 article입니다.
en 페이지는 robots가 noindex이고, canonical은 같은 글의 /ko/ 주소입니다. 영문이 그 장에서 실제로 바뀌기 전에는 hreflang을 넣지 않습니다. 번역이 끝나면 그 페이지에서 noindex를 빼고, canonical을 자기 /en/ 주소로 돌린 뒤 양쪽 hreflang을 넣습니다.
집필 가이드와 이 디자인 시스템도 noindex입니다.