테마, 스타일 토큰과 복구
Glif에서 Markdown은 내용과 구조의 원본이고, 테마는 그 원본을 화면에 표현하는 규칙이다. 색상 모드나 style token을 바꿔도 heading, link, 표와 task list의 Markdown은 그대로 남는다. 이 분리를 지키면 하나의 문서를 여러 화면·projection·출력에 다시 사용할 수 있다.
이 장에서는 다음을 실제 예제로 수행한다.
- 같은 문서를 다크와 라이트 모드로 비교한다.
- 번들
Minimal과Paper테마를 전환한다. - 라이트 강조색 token을 초안으로 바꾼다.
- 변경 되돌리기와 번들
Minimal로 복구한다. - 고급 검색으로 많은 semantic token을 좁힌다.
- 로그 설정의 공개 범위와 내부 정책을 구분한다.
색상 모드와 테마의 차이
| 개념 | 바꾸는 것 | 바꾸지 않는 것 |
|---|---|---|
| 색상 모드 | 현재 테마의 라이트·다크 palette 선택 | theme contract와 Markdown |
| 테마 | surface, text, border, accent, typography와 layout token 묶음 | Markdown 의미와 문서 link |
| style token | 테마 안의 개별 표현 값 | source heading·paragraph·table 구조 |
| Hugo site theme | publish된 웹사이트의 template·style | 데스크톱 앱 theme |
앱 테마와 게시 사이트 테마를 같은 것으로 취급하지 않는다. 앱에서 Paper를 선택했다고 Hugo 출력도 자동으로 Paper가 되는 것은 아니다.
1. 같은 원문으로 색상 모드 비교하기
10_contrast-check.md를 열고 오른쪽 위 색상 모드 전환을 선택한다. 현재 다크면 라이트로, 라이트면 다크로 이동한다. 현재 quick toggle은 수동 라이트·다크 전환 경로다.
다음 요소를 두 모드에서 각각 확인한다.
- H1, H2, H3의 크기·굵기·간격이 본문과 구분되는가?
- 일반 link, inline code와 굵은 강조를 색 이외의 형태로 구분할 수 있는가?
- blockquote, code fence, table border와 task 상태가 배경에서 사라지지 않는가?
- 선택, hover, focus와 disabled 상태가 서로 다른가?
시스템 선호를 따르는 system 값은 theme contract에 존재하지만, 이 실증이 검증한 공개 shortcut은 라이트·다크 수동 전환이다. 별도의 system 선택 UI가 확인되기 전까지 가이드에서 그 경로를 현재 기능처럼 약속하지 않는다.
2. 스타일 설정 열기
- 설정 열기를 선택한다.
- 왼쪽 스타일을 선택한다.
- 위쪽 theme library에서 현재 테마를 확인한다.
- 기본, 고급, CSS 오버라이드 중 작업 목적에 맞는 tab을 선택한다.
Theme library action
| action | 사용 시점 | 주의할 점 |
|---|---|---|
| 변경 되돌리기 | 저장하지 않은 초안을 버릴 때 | 현재 저장된 테마 상태를 다시 불러온다 |
| 테마 저장 | 현재 테마를 적용·저장할 때 | 번들 ID는 사용자 파일로 덮어쓰지 않는다 |
| 다른 이름으로 저장 | 번들을 기반으로 사용자 테마를 만들 때 | 고유한 theme ID를 사용한다 |
| 파일에서 테마 추가 | 검토한 JSON theme을 library에 넣을 때 | 출처와 schema 호환성을 확인한다 |
| 외부 파일로 내보내기 | 백업하거나 다른 환경에서 검토할 때 | 사용자 경로·비밀값을 포함하지 않는다 |
번들 테마는 삭제할 수 없다. 사용자 테마가 손상되거나 과도한 값을 가졌을 때 돌아갈 수 있는 복구 기준을 남기기 위해서다.
3. Minimal과 Paper 비교하기
theme library dropdown에서 Paper를 선택한다. 선택 즉시 현재 앱 표현이 Paper contract로 바뀐다.
Minimal과 Paper는 이름만 다른 preset이 아니라 서로 다른 번들 contract다. 같은 문서를 열어 다음을 비교한다.
| 비교 대상 | 확인 질문 |
|---|---|
| surface | app base, elevated, overlay가 구분되는가? |
| text | 기본·보조·약한 text가 읽히면서 계층이 생기는가? |
| accent | link, 선택, focus에서 과도하거나 부족하지 않은가? |
| border | panel, table, control 경계가 배경과 구분되는가? |
| typography | 본문과 heading rhythm이 긴 읽기에 적합한가? |
비교를 마쳤으면 dropdown에서 Minimal을 다시 선택한다. 내부 ID는 default지만 UI label은 Minimal이다. 가이드와 지원 안내에서는 사용자에게 보이는 Minimal을 사용하고, 진단에서만 내부 ID를 구분한다.
4. 기본 token 편집하기
기본 → 외형은 영향이 큰 라이트·다크 값을 한 표에서 보여 준다.
- 표면: base, elevated, overlay
- 강조색
- 기본·보조·약한 text
- 기본 border
한 번에 많은 값을 바꾸지 않는다. 이 실습에서는 라이트 강조색 하나만 #2d64dd에서 #7c3aed로 바꾼다.
- 외형 표의 강조색 → 라이트 swatch를 선택한다.
- color popup의 값을
#7c3aed로 입력한다. - 설정과 뒤의 실제 문서에서 link·선택·focus가 어떻게 달라지는지 확인한다.
- 저장하지 않을 실험이면 변경 되돌리기를 선택한다.
- 강조색이 원래
#2d64dd로 돌아왔는지 확인한다.
이번 실증에서는 #2d64dd → #7c3aed → #2d64dd가 실제 관측됐다. 초안 변경과 되돌리기 과정에서도 예제 Markdown 네 파일의 SHA-256은 변하지 않았다.
5. 타이포그래피와 레이아웃
기본 → 타이포그래피와 레이아웃은 다음 공용 역할을 조절한다.
- body, heading, mono font family
- 기본 문서 content width
- 문서 body font size와 line height
- editor body role, 크기, line height와 weight
문서 읽기 타이포와 editor 입력 타이포는 목적이 다르므로 같은 값이라고 가정하지 않는다. content width를 넓힐 때는 긴 문장 한 줄의 길이, 표·code overflow, 200% 확대를 함께 확인한다. 사용자 font를 추가했다면 폰트 새로고침으로 registry를 다시 읽고, 파일을 점검해야 할 때만 폰트 폴더 열기를 사용한다.
6. 고급 token 검색
고급은 foundation, app, document, metrics, zones, chrome, editor semantic을 세분화한다. 모든 section을 펼치기보다 검색에 label이나 token path 일부를 입력한다.
| 검색 예 | 기대 결과 |
|---|---|
document |
문서 semantic과 관련 metric |
editor |
editor body·surface·syntax 역할 |
border |
border width와 semantic border field |
spacing |
foundation spacing과 관련 layout field |
검색은 section title, field label과 token path를 대상으로 한다. 결과가 없다고 token이 삭제된 것은 아니다. 쿼리를 비우고 schema의 전체 section을 다시 확인한다.
기본·고급·CSS 오버라이드 선택 기준
| tab | 선택 기준 |
|---|---|
| 기본 | 전체 분위기와 읽기 품질에 큰 값부터 빠르게 조정 |
| 고급 | schema가 정의한 semantic과 foundation token을 정확히 조정 |
| CSS 오버라이드 | 공통 theme contract 밖에 남겨야 할 예외만 작성 |
가능하면 기본·고급 token을 우선한다. CSS override는 강력하지만 schema validation과 구조화된 편집의 이점을 잃기 쉬우므로 이유와 제거 조건을 남긴다.
전체 조작 영상
다음 12.8초 영상은 실제 Glif에서 같은 Markdown의 색상 모드를 전환하고, 설정 셸에서 스타일로 이동하고, 강조 token을 편집·되돌린 뒤 Paper → Minimal 복구, 고급 검색과 keyboard focus까지 이어서 수행한다.
로그 설정과 내부 정책의 경계
로그는 테마 기능이 아니지만 설정·문제 해결의 안전 경계와 연결된다.
OP-15는 log sink와 출력 정책을 정하는 내부 품질 계약이다. 일반 사용자 기능 카드나 설정 단계로 공개하지 않는다.OP-16은 문제 재현을 위한 log level·flush 설정 계약이다.- 현재 검증한 앱에서 log control은 개발 환경에만 노출됐다. packaged release에 같은 UI가 있다는 주장은 아직 하지 않는다.
- 어떤 환경에서도 token, password, 문서 본문과 불필요한 개인 경로를 로그에 남기지 않는 redaction 원칙은 유지한다.
packaged release에서 OP-16을 공개하려면 설정 위치, level 의미, flush 완료 상태, reset, redaction과 지원 전달 절차를 별도 실증해야 한다. 그 전에는 “설정 → 시스템에서 항상 로그 수준을 바꿀 수 있다”고 안내하지 않는다.
예상과 다를 때
| 증상 | 먼저 확인할 것 | 조치 |
|---|---|---|
| 색상 모드가 예상과 반대다 | 현재 mode와 system preference | quick toggle로 현재 상태를 확인하고 한 번만 전환한다 |
| Paper를 선택해도 문서가 그대로다 | 앱 theme과 Hugo site theme 혼동 | 데스크톱 앱 화면에서 비교하고 publish theme은 Site에서 따로 확인한다 |
| token을 바꿨는데 유지되지 않는다 | 초안인지 저장했는지 | 실제 화면을 확인한 뒤 테마 저장 또는 다른 이름으로 저장을 선택한다 |
| 번들 테마를 덮어쓸 수 없다 | default, paper 예약 ID |
사용자 ID로 다른 이름으로 저장한다 |
| 화면 대비가 무너졌다 | 한 번에 여러 token을 바꿨는지 | 변경 되돌리기 후 한 token씩 다시 조정한다 |
| 고급 검색 결과가 없다 | 번역 label과 token path | document, border 같은 짧은 path 조각으로 다시 찾는다 |
| CSS가 token을 이긴다 | CSS override 존재 여부 | override를 다시 불러와 충돌 rule을 제거하거나 이유를 기록한다 |
| 로그 설정이 보이지 않는다 | packaged build인지 | 개발 전용 UI를 공개 기능으로 간주하지 말고 지원 절차를 따른다 |
원본 보존과 검증 범위
이 장에서 실증한 canonical 기능 ID는 OP-11, OP-11A, OP-12이며 설정 셸 흐름은 WS-16, keyboard focus는 WS-20과 함께 확인했다. OP-16은 공개 계약의 경계만 문서화했으며 packaged UI 실증은 남아 있다. OP-15는 내부-only라 공개 기능 coverage에서 제외한다.
캡처는 Glif 0.1.0, Windows, 한국어, 1200×800 앱 client area에서 수행했다.
- 확인함: 수동 라이트·다크 전환, Minimal·Paper 선택, Minimal 복구, accent token 초안·되돌리기, 고급 검색, keyboard focus, Markdown 원본 보존
- 아직 주장하지 않음: 실제 OS high contrast, 실제 OS 200% 확대, 사람의 screen reader 청취, packaged
OP-16control,OP-15내부 log sink 구현 세부
완료 확인
- 색상 모드와 테마의 차이를 설명할 수 있다.
- 같은 Markdown을 다크·라이트에서 비교했다.
- Minimal과 Paper를 전환하고 Minimal로 복구했다.
- 강조색 하나를 초안으로 바꾸고 되돌렸다.
- 기본, 고급, CSS override의 선택 기준을 이해했다.
- 고급 검색으로 필요한 semantic token만 찾았다.
- 앱 theme이 Hugo site theme을 자동 변경하지 않음을 확인했다.
-
OP-15내부 정책과OP-16공개 문제 해결 계약을 구분했다.