IT 단어 학습 목업
🟡 개발 중 · UI/UX 프로토타입 단계
IT 단어를 모바일에서 공부하기 좋게 보여주는 학습 웹앱의 목업이다.
단어는 content/ 의 Markdown 이 원본이다. 원래 Obsidian vault 에 있던 것을 2026년 8월에 여기로 들여왔다.
지금 단계의 목표는 기능 완성이 아니라 디자인과 화면 흐름을 눈으로 확인하고 승인받는 것이다.
실행
cd apps/development/it-roadmap
python3 -m http.server 8000
# http://localhost:8000 을 브라우저에서 연다
index.html 을 더블클릭해서 file:// 로 열어도 동작한다. 외부 프레임워크도 빌드 단계도 없다.
모바일 화면을 기준으로 만들었으므로, 데스크톱 브라우저라면 개발자 도구의 기기 모드에서
iPhone 크기(390 x 844)로 보는 것을 권한다.
무엇이 되는가
- 홈에서 "지금 뭘 하면 되는지" 한 화면에 제시
- 단어장 12권 / 단어 329개
- 검색, 상태 필터, 이전/다음 단어 이동
- 단어 상세에서 progressive disclosure 로 깊이 조절
- 떠올리기 — 뜻을 가리고 스스로 회상한 뒤 확인하고 자가 평가
- 퀴즈 3종, 문항 수 예고, "모르겠어요", 대조형 오답 해설, 결과 요약
- 통과하면 멀어지고 틀리면 처음으로 돌아오는 간격 반복 (1 / 3 / 7 / 16 / 35일)
- 진도 화면(통과/공부한/복습 필요/전체, 연속 학습일, 단어장별 진행률, 기록)
- 밝은 화면 / 어두운 화면, 시스템 설정 따름 + 수동 전환
- 상태는
localStorage 에 남아서 껐다 켜도 이어진다
로그인도 서버도 데이터베이스도 없다. 목업 단계에서는 필요하지 않다.
학습 루프
읽기 ──→ 떠올리기 ──→ 퀴즈 ──→ (통과) ──→ N일 뒤 복습으로 자동 복귀
│ │
└── 아직 ────┴── 오답 ──→ 복습 목록 (상자 초기화)
읽기와 퀴즈 사이에 떠올리기가 있다. 객관식은 보기 네 개를 주는 순간
재인(recognition)이지 회상(recall)이 아니라서, 읽자마자 퀴즈로 가면
"보니까 알겠다"는 착각이 남는다. Anki·클래스카드·Quizlet Learn 셋 다
그 사이에 한 단계를 둔다.
데이터
원본은 이 repo 안의 content/ 다. 바깥에 의존하는 것이 없다.
python3 tools/build.py # content/*.md -> data/vocabulary.js
python3 tools/build.py --dry-run # 무엇이 잡히는지만 확인
content/ 는 그대로 Obsidian vault 로 열 수 있다. 그 폴더를 vault 로 지정하면
지금까지처럼 Obsidian 에서 쓰면서, 동기화 대신 git 이 이력을 갖는다.
단어를 고치는 순서는 항상 같다 — content/ 의 .md 를 고치고, tools/build.py 를 돌린다.
data/vocabulary.js 를 직접 고치지 않는다. 다음 빌드에 덮어써진다.
빌드가 뽑아내는 것:
| 원본 | 앱에서 쓰이는 곳 |
|---|
# 용어 (원어) | 표제어, 원어 표기 |
## 📝 정의 첫 문단 | 한 줄 뜻 (항상 보이는 자리) |
### 비유 | 정의 아래 따로 세우는 한 줄 |
## 🖼️ 그림으로 보기 | 대표 그림 (접히지 않는다) |
## ⚠️ 해결하는 문제 | "왜 필요한가" |
## ⚙️ 작동 원리 | "어떻게 작동하나" |
## 🚫 흔한 오해 | "흔히 잘못 아는 것" |
## ❓ 이해했는지 | 화면 맨 아래 확인 질문 (접히지 않는다) |
## 🔗 관련 용어 의 [[링크]] | 관련 개념, 퀴즈 출제 근거 |
| 폴더 이름 | 단어장 분류 (BOOKS 에서 이름·소개를 붙인다) |
## 🖼️ 그림으로 보기 가 없는 노트는 본문 안의 첫 도해를 대표 그림으로 끌어올린다.
접이식 안에 두면 펼쳐야만 보이는데, 그러면 그림을 맨 앞에 세운 이유가 없어진다.
vault 에서 들여올 때 한 일
tools/import_vault.py 가 한 번 돌았다 (2026-08-16). 다시 돌릴 일은 없지만 기록으로 남긴다.
노트 244편
mermaid 324개 -> 도해로 132개, 버림 192개
껍데기만 남은 섹션 57개 제거
이름이 겹치는 노트 13개 제거 (가장 큰 것만 남김)
mermaid 를 버린 이유는 graph 가 가로로 넓어져 390px 에서 못 읽기 때문이다.
mermaid.js 를 넣어도(1MB) 그 폭 문제는 그대로다. 세로 한 폭에서 읽히는 도해로
옮길 수 있는 것만 옮겼다. 버린 것은 git 이 기억한다.
조사한 것과 거기서 가져온 것
디자인을 상상해서 만들지 않았다. 아래를 먼저 확인하고 각각에서 하나씩 가져왔다.
Apple Human Interface Guidelines (탭 바)
탭은 3~5개를 쓰고, 화면을 옮겨 다녀도 탭 바는 계속 보여야 한다.
다만 모달성 화면에서는 감춰도 된다.
→ 목적지를 4개로 고정했다. 그리고 읽기 화면과 퀴즈 진행 화면에서만 탭 바를 감춘다.
그 두 화면은 하나의 일에 집중하는 자리이기 때문이다.
Material Design 3 (내비게이션 바)
하단 내비게이션은 3~5개, 최상위 목적지 전용이다.
→ 하위 내비게이션을 탭 바에 밀어 넣지 않았다. 단어장 안의 필터는 화면 안의 칩으로 뒀다.
Anki (학습 상태 모델)
카드를 New / Learning / Review 로 나누고, 덱 화면에서 오늘 할 양을 숫자로 먼저 보여준다.
→ 상태를 5개로 정리했다. 안 봄 / 읽는 중 / 학습 완료 / 퀴즈 통과 / 복습 필요.
이 다섯 개가 앱 전체에서 같은 이름, 같은 색, 같은 아이콘으로 쓰인다.
그리고 홈에서 "오늘 뭘 할지"를 목록이 아니라 행동 하나로 제시한다.
Quizlet Learn (적응형 출제)
틀린 항목을 더 자주 물어보는 방식으로 학습을 개인화한다.
→ 퀴즈에서 틀리면 그 자리에서 복습 대기열로 넘어간다. 별도 조작이 필요 없다.
홈과 탭 바의 배지가 그 숫자를 계속 보여준다.
Readwise Reader (긴 글 읽기)
긴 글을 읽을 때는 액션이 많은 하단 바를 감추고 읽기 진행률만 남긴다.
→ 단어 상세에서 탭 바를 감추고, 화면 최상단에 2px 짜리 읽기 진행선을 뒀다.
하단에는 지금 필요한 액션 하나와 이전/다음만 남겼다.
Nielsen Norman Group (progressive disclosure)
처음에는 자주 쓰는 것만 보이고, 나머지는 요청할 때 연다.
단계는 2단계까지만 만든다. 3단계 이상이면 사용성이 떨어진다.
버튼 이름은 열었을 때 뭐가 나오는지 알 수 있어야 한다.
→ 항상 보이는 것은 표제어와 한 줄 뜻과 짧은 본문까지다.
그 아래는 "왜 필요한가", "어떻게 작동하나" 처럼 내용을 말하는 이름으로 접어뒀다.
"더보기" 같은 이름은 쓰지 않았고, 3단계는 만들지 않았다.
Notion / NotebookLM 계열의 인상
UI 가 콘텐츠보다 눈에 띄지 않는다.
→ 브랜드 색을 따로 두지 않았다. 가장 진한 잉크색이 곧 주요 버튼 색이다.
색은 학습 상태를 말할 때만 쓴다.
2차 검수에서 추가로 조사한 것
Anki (자가 평가와 예고)
답을 확인한 뒤 Again / Hard / Good / Easy 로 스스로 매긴다.
덱 화면은 시작 전에 New / Learning / Due 개수를 먼저 보여준다.
→ 떠올리기 단계를 만들고 자가 평가를 두 갈래(아직 / 떠올랐다)로 뒀다.
네 갈래는 고르는 데 시간이 걸리고, 목업에서 그 차이를 쓸 데가 없다.
퀴즈 범위마다 실제 문항 수를 미리 적는다.
클래스카드 (국내 단어장)
암기 → 리콜 → 스펠 3단 사다리로 난이도를 올린다.
→ 읽기와 퀴즈 사이의 빈 칸이 여기서 보였다. 리콜에 해당하는 단계를 넣었다.
스펠(직접 입력)은 넣지 않았다 — 영어 학습이라면 철자가 목적이지만,
여기서 확인하려는 건 개념 이해라서 "Load Balancer"를 정확히 타이핑하는 능력은
측정 대상이 아니다. 모바일에서 영문 타이핑은 오답의 대부분이 오타가 된다.
Readwise (오늘 볼 N개)
복습을 끝이 없는 목록이 아니라 끝이 있는 하루치 의식으로 만든다.
→ 떠올리기는 한 번에 최대 12개, 한 단어당 두 번까지만 보여주고 끊는다.
떠올릴 때까지 붙잡아두면 그만두는 것 말고는 빠져나갈 길이 없다.
Duolingo (노력 예고)
진행 막대로 "얼마나 걸릴지"를 시작 전에 알려준다.
→ 문항 수 예고만 가져왔다. 하트·리그·XP·연속 보상은 가져오지 않았다.
게임 앱처럼 보이지 않게 하는 것이 이 제품의 전제다.
여기서 뽑은 디자인 원칙 6가지
- 3초 안에 다음 할 일이 보인다. 홈은 통계판이 아니라 "다음 단어 하나 + 시작 버튼"이다.
- 한 화면에 다 넣지 않는다. 항상 보이는 것과 눌러서 여는 것을 나눈다. 2단계까지만.
- 학습 루프가 버튼에 드러난다. 상세 화면의 주 버튼이 상태에 따라 바뀐다.
학습 완료 -> 퀴즈로 확인하기 -> 복습 목록에 넣기. 읽고 끝나지 않게 한다.
- 색만으로 뜻을 전달하지 않는다. 상태는 색 + 아이콘 + 글자를 항상 같이 쓴다.
- UI 가 콘텐츠보다 튀지 않는다. 그라디언트, 유리 효과, 큰 그림자, 큰 아이콘을 쓰지 않는다.
- 게임처럼 만들지 않는다. 연속 학습일은 보여주되 불꽃도 레벨도 트로피도 없다.
학습 관리 도구의 인상을 유지한다.
정보 구조
홈 지금 뭘 하면 되는가
├── 오늘의 단어 + 시작 버튼
├── 복습 대기 알림 (있을 때만)
├── 공부 중인 단어장
└── 최근에 본 단어
단어장 무엇을 공부할 수 있는가
└── 단어 목록 검색 / 상태 필터
└── 단어 상세 집중해서 읽는 자리 (탭 바 숨김)
├── 표제어 + 한 줄 뜻 항상 보임
├── 접이식 섹션 최대 5개 첫 칸은 열려 있고, 나머지는 안에 든 것의 이름이 보임
├── 관련 개념 연결된 용어 이름이 접힌 채로 보임
└── 하단 고정 액션 상태에 따라 라벨이 바뀜
떠올리기 읽은 게 남았는가 (탭 바 숨김)
├── 용어만 보여주고 뜻은 가림
├── 뜻 확인하기 -> 아직 / 떠올랐다
└── 마무리: 떠올린 단어, 다시 읽을 단어, 퀴즈로 가는 길
퀴즈 정말 이해했는가
├── 범위 고르기 (복습 / 학습 완료 / 단어장별) — 범위마다 문항 수를 미리 표시
├── 문제 -> 답 선택 또는 "모르겠어요" -> 피드백과 해설 -> 다음
│ 틀리면 내가 고른 게 사실 무엇이었는지 같이 보여준다
└── 결과: 점수, 복습으로 넘긴 단어, 통과한 단어
진도 어디까지 왔는가
├── 통과 / 공부한 / 복습 필요 / 전체
├── 최근 7일과 연속 학습일
├── 단어장별 진행률 (막대와 범례가 같은 것을 센다)
├── 학습 기록
└── 이어서 할 일
퀴즈를 어떻게 냈는가
암기가 아니라 이해를 확인하는 게 목적이라 세 종류를 섞는다.
- 설명에서 용어 찾기 뜻을 읽고 이름을 떠올릴 수 있는가
- 용어의 뜻 고르기 이름을 보고 뜻을 고를 수 있는가
- 같이 쓰이는 개념 노트의
관련 용어 를 정답으로 쓴다
내용을 몰라도 맞힐 수 있는 길을 막는 데 신경을 썼다.
- 오답은 같은 단어장 안에서 뽑는다. 전혀 다른 분야에서 뽑으면 소거법으로 풀린다.
- 지문에서 정답 용어를 지운다. 노트마다 제목은 영문인데 본문은 한글 이름을 쓰는 경우가 있어서
(
# Load Balancer 인데 본문은 "로드 밸런서는"), 용어명 필드가 아니라 문장의 앞머리를 찾아 지운다.
- 보기 길이를 맞춘다. 정답만 유난히 길면 읽지 않고도 고를 수 있다.
길이가 비슷한 오답을 고르고, 길이와 상관없이 항상 첫 문장에서 끊는다.
한도(110자)를 넘을 때만 자르면, 두 문장이 합쳐서 95자인 뜻풀이만 혼자 길어진다.
실측: 가장 긴 보기가 정답인 비율 16% (무작위면 25%).
- 보기에는 마크다운을 렌더하지 않는다. 굵은 글씨가 한 보기에만 남으면 그것도 힌트가 된다.
- 빈칸 뒤 조사를 원문 그대로 두지 않는다. "____은" 이면 받침 있는 말,
"____는" 이면 없는 말로 답이 좁혀진다. CDN(씨디엔)만 "은"을 받는 식이라 실제로 찍힌다.
시험지 표기(
____은(는))로 눕혀서 단서를 없앴다.
- 질문에는 조사 병기를 만들지 않는다. "X 와(과)" 는 조사를 못 골라 병기한 흔적이라
한국어 서비스에서 바로 티가 난다. 영문 약어 뒤 조사는 한글 읽기의 받침을 알아야
정해지는데 그 정보가 노트에 없다. 조사가 필요 없는 문장으로 바꿨다.
- "모르겠어요"를 둔다. 네 개 중 하나를 찍어 맞으면 아는 것으로 기록되고
그 단어는 한 달 뒤에나 다시 나온다. 모른다고 말할 수 있어야 복습 목록이 실력과 맞는다.
결과는 오답과 같지만 말투는 다르게 한다.
파일 구조
index.html 앱 셸
css/tokens.css 디자인 토큰. 여기만 고치면 인상이 바뀐다
css/app.css 컴포넌트와 화면
js/ui.js 이스케이프, 아이콘, 마크다운 렌더러
js/store.js 학습 상태와 localStorage
js/quiz.js 문제 생성
js/app.js 라우터, 탭 바, 화면 전환
js/screens.js 홈, 단어장, 목록, 상세, 진도
js/reading.js 용어 풀이(점선 밑줄) · 그림 단계 보기 · 배우 아이콘 부착
js/art.js 그림 어휘 — 배우 아이콘 26종과 장면 서랍
js/recall.js 떠올리기 (회상 단계)
js/quiz-screens.js 퀴즈 흐름
data/index.js 목록·검색에 필요한 것만 (시작할 때 읽는다)
data/terms/<권>.js 단어 본문 (그 권을 열 때만 읽는다)
data/scenes/<권>.js 장면 컷 만화 SVG (본문과 함께 온다)
content/ 단어 원본 Markdown (Obsidian vault 로 열 수 있다)
scenes/<권>.json 장면 각본. 사람이 쓰는 쪽 — 원문 밖에 있다
tools/build.py content/*.md -> data/index.js + data/terms/*.js
tools/build_scenes.py scenes/*.json -> data/scenes/*.js
tools/scenes/parts.py 장면 부품 라이브러리 (배우·사물·표시를 한 손으로 그린다)
tools/scenes/render.py 각본 -> SVG 조립기. 배치 규칙이 여기 한 곳에만 있다
tools/scenes/lint_scenes.py 각본이 컷 문법을 지켰는지 전수 검사
tools/import_vault.py vault 이전 도구 (한 번 쓰고 기록으로 남김)
tools/check_template.py 노트가 템플릿을 지켰는지 검사 (읽기만 한다)
docs/TERM-TEMPLATE.md 새 단어를 쓸 때 따르는 형식
mockups/term.html 원문과 화면을 나란히 보는 목업
DESIGN.md 디자인 시스템
디자인 시스템은 DESIGN.md 에 있다.
새 단어를 추가할 때
형식은 docs/TERM-TEMPLATE.md 에 있다.
기존 노트에서 반복되는 구조를 추리고, 세 자리를 새로 넣었다.
| 새로 넣은 자리 | 막는 구멍 |
|---|
🖼️ 그림으로 보기 | 읽어야만 알 수 있다 — 대개 안 읽는다 |
🚫 흔한 오해 | 틀린 그림을 그대로 갖고 나간다 |
❓ 이해했는지 | 이해한 줄 알고 넘어간다 |
### 예 | 닮은 것만 알고 겪은 장면과 안 이어진다 |
🧱 구성 | 무엇으로 되어 있는지 모른 채 이름만 외운다 |
### 이름 | 이름과 뜻을 따로 외운다 — 대개 이름이 곧 하는 일이다 |
### 직접 | 읽기만 하고 자기 화면에서 본 적이 없다 |
🧒 열 살에게 | 알아본 것을 아는 것으로 착각한다 |
재는 것은 하나다
읽고 나면 IT 를 전혀 모르는 사람(열 살 아이)에게 제 입으로 설명할 수 있어야 한다.
이해의 기준을 "알아본다" 가 아니라 "가르칠 수 있다" 로 잡았다. 그래서 마지막
자리가 🧒 열 살에게 다 — 모범 답을 바로 보여주지 않고, 소리 내어 해 본 다음에
열게 한다. 모범 답은 IT 낱말 0개로 쓰고, 검사기가 금지어 목록과 영문 두 글자
이상으로 그걸 잰다. 사람 눈으로 "쉽게 썼나" 를 재면 329편에서 기준이 흔들린다.
이해의 네 기둥은 접지 않는다
읽는 사람이 단어 하나에 던지는 물음은 넷이고, 넷 다 첫 화면에 답이 있다.
| 물음 | 답하는 자리 |
|---|
| 무엇인가 | 📝 정의 — 한 줄 뜻 · 비유 · 예 |
| 어떻게 되나 | 🖼️ 그림으로 보기 |
| 왜 필요한가 | ⚠️ 해결하는 문제 |
| 무엇으로 되어 있나 | 🧱 구성 (부품이 있는 단어만) |
접힌 것은 대체로 안 열린다 — 열어야 보이는 기둥은 없는 기둥이다.
그래서 넷은 펼친 채로 두고, 나머지(작동 원리 · 비교 · 사례 · 오해 · 주의)는
전부 닫힌 채로 시작한다. 거기 남는 것은 다 대등한 심화라 하나만 열어두면
그 칸만 특별해 보인다. 그림으로 들어와서 확인 질문으로 나간다.
확인 질문에는 → 답이 있는 자리 가 붙어서, 누르면 답이 든 칸이 열리고 그리로 데려간다.
읽는 동안 두 가지가 더 일어난다
낯선 용어에 점선 밑줄이 그어진다. 정의 한 줄과 그림 안에서, 단어장에
이미 있는 용어에만. 탭하면 그 줄 바로 아래 한 줄 뜻이 펼쳐진다 —
글은 그림의 해당 부분 옆에 있을 때 배워진다. 사전을 따로 두지 않았다.
단어장 색인 329편의 제목·별칭·한 줄 뜻이 그대로 사전이다. 한 번 열어 본
용어는 어디서든 점선이 옅어지고, 그 줄어드는 진한 점선이 곧 진도다.
한 줄 뜻 밑에 장면 컷 만화가 선다. 문제 → 동작 → 결과 세 컷(왕복이 본질인
개념은 네 컷)으로, 글을 읽기 전에 그림만 보고 무슨 일을 하는 단어인지 잡게 한다.
회색 점선은 이동이고 파랑은 옮겨지는 사물이라, 파랑만 눈으로 따라가도 줄거리가
나온다. 각본은 scenes/ 에 있고 SVG 는 부품 라이브러리가 조립한다 — 자유
드로잉이 없어야 329편이 같은 세계에 산다. 원문 Markdown 은 그림 때문에 한 글자도
바뀌지 않는다.
흐름 그림의 배우 이름에는 그림이 붙고, 탭할 때마다 한 마디씩 밝아진다. 자동 재생은 없고, 지나온
마디는 사라지지 않는다. 속도를 학습자가 정할 때 더 깊이 배우고, 저절로
움직이는 그림은 기억에서 먼저 사라져 정지 그림보다 못하기 때문이다.
진행 막대도 숫자도 없다 — 그림 자체가 단추이고 밝아진 줄 수가 곧 진행이다.
python3 tools/check_template.py content/네트워크/DNS.md
python3 tools/check_template.py --strict content/ # 경고까지 실패로 세어 본다
open mockups/term.html # 원문과 화면을 나란히 본다
단어 329개가 모두 이 템플릿을 지킨다. 검사기가 329편 전부를 통과시키고,
앱이 그 형식을 그대로 그린다. 새로 쓰는 단어도 같은 형식을 따른다.
검사기는 실패(✕) 와 경고(△) 두 단계로 말한다 — 실패는 고쳐야 하고,
경고는 "이게 맞나" 를 묻는 것이다.
확인한 것
헤드리스 크로미움으로 실제 화면을 띄워 측정했다. 코드를 읽고 판단한 게 아니라
브라우저가 실제로 그린 결과를 잰 값이다.
기능
- 단어 227개 화면을 전수 순회: 그림 · 정리 · 확인 질문이 227편 전부에 그려진다
- 도해 596장이 그림으로 렌더된다. 안 그려지고 원문 펜스로 떨어진 것 0건
<script> 태그, on* 속성, 원문 펜스 누출 0건- 관련 용어 링크 전수 대조: 가리키는 노트가 없는 링크 0건
- 퀴즈 320문항: 보기 4개, 정답 정확히 1개, 같은 단어가 두 칸 차지하는 문항 0건
- 문항 수 예고 = 실제 문항 수 (단어장 6개 × 5회 반복 검증)
- 간격 반복: 1 → 3 → 7 → 16 → 35일, 오답이면 다시 1일부터
- 막대 세그먼트 합 = 상태별 개수 합 (단어장 6개 전부)
화면 — 320 / 390 / 430px, 밝은 화면과 어두운 화면
- 44px 히트 영역:
elementFromPoint 로 위아래 끝을 실제로 눌러 확인
- 가로 오버플로 0건 (표·코드는 자기 안에서만 스크롤)
- inline 요소에 블록 전용 속성 0건
- 대비 WCAG AA:
color-mix 합성 결과까지 계산해서 전 화면 통과
지키는 것
content/ 의 Markdown 이 원본이다. 빌드는 읽기만 하고 data/ 에만 쓴다- 코드 블록의 내용은 고쳐 쓰지 않는다. 재조판은 코드가 아닌 것에만 한다
다음 단계 후보
디자인을 승인한 뒤에 이야기할 것들이다. 지금은 넣지 않았다.
- 단어 목록 가상 스크롤 (227개에서 아직은 필요 없다)
- 복습 주기를 실제 간격 반복(SM-2 등)으로 계산
- 상세 화면의 Mermaid 다이어그램 렌더 (지금은 어댑터에서 걷어낸다)
- 파일 변경 감지해서 데이터 자동 갱신
- 여러 기기에서 학습 상태 공유
