1. 개요

기능명

Blog Layout Quality System

목적

Allen’s Blog를 개인 연구 지도형 블로그로 운영하기 위해 레이아웃, 검색, 사이드바, 포스트 구조, 도구 페이지, 운영 문서를 하나의 품질 기준으로 관리한다.

문제

기존 페이지별 인라인 스타일과 전역 CSS가 서로 덮어써 화면마다 색상, 간격, 버튼 형태가 달라졌다.
검색창, 사이드바, 카테고리 칩, 글 목록 카드가 동일한 상호작용 규칙을 공유하지 않았다.
운영 문서와 실제 구현이 계속 어긋나면 이후 글 작성, 도구 확장, SEO 개선 작업의 회귀 가능성이 높다.

기대 효과

사용자는 포스트, 시리즈, 도구, 소개 페이지를 같은 제품처럼 인식한다.
운영자는 새 글과 새 도구를 추가할 때 동일한 품질 기준을 적용한다.
빌드, 접근성, 검색, 레이아웃 회귀를 배포 전에 확인할 수 있다.

핵심 사용자

1차 사용자: 블로그 방문자, 검색 유입 독자, 모바일 독자
2차 사용자: 블로그 운영자 Allen Kang
운영 사용자: 향후 Codex 또는 자동화 에이전트

2. 범위

In Scope

민트/파스텔 기반 전역 테마 정리
포스트, 글 목록, 시리즈, 도구, 소개 페이지의 레이아웃 규칙 통일
검색 폼과 검색 결과의 접근성, 표시 상태, 카테고리 라벨 개선
모바일 사이드바와 포커스 상태의 기본 품질 기준 정의
Google Analytics, Search Console, 콘텐츠 갱신 루틴을 문서 기준으로 연결
PRD, HLD, LLD, TDD, ADR, 검토 보고서 작성

Out of Scope

Jekyll에서 다른 프레임워크로 마이그레이션
전체 콘텐츠의 학술적 재집필
새 도메인 구매, DNS 변경, Search Console 실제 등록 대행
GA4 콘솔 내부 설정 변경
결제, 로그인, 회원 기능

3. 성공 기준

비즈니스 성공 기준

주요 페이지 5종(/, /posts/, /series/, /tools/, /about/)이 동일한 테마와 레이아웃 규칙을 사용한다.
Search Console과 GA4 운영 루틴이 문서화되어 월 1회 반복 가능하다.

사용자 성공 기준

사용자는 모바일 390px 폭에서 글 제목, 카테고리, 검색, 본문 시작 영역을 가로 스크롤 없이 읽을 수 있다.
사용자는 검색 결과에서 제목, 카테고리, 날짜, 요약을 구분할 수 있다.
사용자는 사이드바가 열린 상태와 닫힌 상태를 버튼 라벨과 시각 상태로 구분할 수 있다.

기술 성공 기준

bundle exec jekyll build가 성공한다.
변경된 JavaScript 파일은 node --check를 통과한다.
주요 텍스트/배경 조합은 WCAG AA 대비 기준을 만족한다.
커밋 후 GitHub Pages 원격 브랜치에 푸시된다.

4. 기능 요구사항

ID	우선순위	요구사항	입력 조건	기대 결과	수용 조건	관련 테스트
R-001	P0	전역 테마는 mint paper, ink text, teal action 중심으로 통일한다.	방문자가 주요 페이지를 연다.	페이지마다 색상 체계가 동일하다.	보라색이 주요 hover 전환으로 사용되지 않고, 주요 액션은 teal 계열이다.	T-001, T-009
R-002	P0	포스트 레이아웃은 제목, 메타, 학습 목표, 목차, 본문 간격을 동일한 폭 규칙으로 배치한다.	포스트 상세 페이지 접근	본문 카드와 목차가 같은 기준선에 정렬된다.	포스트 본문이 `--atlas-article-max` 폭 안에 있고 가로 스크롤이 없다.	T-002, T-010
R-003	P0	검색 폼은 검색어 지우기 버튼 1개와 검색 실행 버튼 1개만 표시하고 결과를 다시 열 수 있어야 한다.	검색어 입력 또는 URL `q` 파라미터 존재	결과 영역이 사이드바 안에 표시된다.	검색창 포커스 시 현재 검색어와 일치하는 결과만 다시 보이며, clear affordance가 중복 표시되지 않는다.	T-003, T-011
R-004	P0	카테고리 키는 사용자에게 한국어 라벨로 표시한다.	검색 결과 또는 포스트 메타 렌더링	`mathematics_philosophy_history` 대신 `수학철학·수학사`가 보인다.	정의된 카테고리 4종은 모두 한국어 라벨로 표시된다.	T-004
R-005	P0	모바일 사이드바는 모달 드로어처럼 작동한다.	768px 이하 화면에서 사이드바 버튼 클릭	열림/닫힘 상태, 배경 잠금, 포커스 가능 상태가 일치한다.	`aria-expanded`, `aria-hidden`, 본문 inert 상태가 열림 상태와 일치한다.	T-005, T-012
R-006	P1	소개 페이지는 민트 고래 로고와 평범한 앱형 소개 구조를 사용한다.	`/about/` 접근	과장된 섹션명 없이 블로그 목적과 주요 링크가 보인다.	로고가 렌더링되고, 주요 링크 3개 이상이 접근 가능한 이름을 가진다.	T-006
R-007	P1	도구 페이지는 개별 랜딩 페이지와 계산기 묶음을 구분한다.	`/tools/` 접근	개별 계산 안내와 계산기 탭이 순서대로 보인다.	단위 변환기, 운동 에너지, 가속도, DSR 페이지 링크가 존재한다.	T-007
R-008	P1	포스트 운영 정보는 작성일과 갱신일을 구분한다.	`date_modified` 또는 `last_modified_at`가 있는 글	작성일과 갱신일이 함께 표시된다.	작성일과 갱신일이 다르면 두 값이 모두 렌더링된다.	T-008
R-009	P1	운영 문서는 Search Console, GA4 이벤트, 발행 전후 루틴을 포함한다.	운영자가 문서를 연다.	반복 가능한 체크리스트가 보인다.	`BLOG_OPERATIONS.md`에 월간, 발행 전, 발행 후, 분기별 점검 항목이 있다.	T-013
R-010	P2	디자인 시스템 문서는 실제 구현 토큰과 동기화되어야 한다.	디자인 토큰 변경	문서와 CSS 토큰이 같은 방향을 설명한다.	`DESIGN.md`와 `theme-atlas.css`의 핵심 색상 차이가 검토 보고서에 기록된다.	T-014
R-011	P0	이미지와 lazy loading은 전역 CSS 때문에 숨겨지지 않아야 한다.	이미지가 포함된 포스트 또는 프로젝트 접근	이미지가 로드 전후 모두 레이아웃을 깨지 않고 보인다.	로드 후 `img`의 opacity가 1이고 lazy 이미지의 `src/srcset`이 실제 URL로 갱신된다.	T-015
R-012	P0	사이드바 내비게이션은 하위 페이지에서도 현재 섹션을 드러내야 한다.	`/posts/`, `/series/`, `/tools/*` 접근	해당 상위 nav item이 active 상태가 된다.	active nav item에 `aria-current`가 있다.	T-016

5. 비기능 요구사항

ID	우선순위	요구사항	수용 조건	관련 테스트
R-NF-001	P0	GitHub Pages와 Jekyll 정적 빌드 호환성을 유지한다.	로컬 Jekyll 빌드가 성공하고 `_config.yml` 플러그인이 GitHub Pages에서 허용 가능한 범위다.	T-NF-001
R-NF-002	P0	핵심 UI 텍스트와 컨트롤은 WCAG AA 대비를 만족한다.	주요 색상 조합 대비가 4.5:1 이상이다.	T-NF-002
R-NF-003	P0	키보드 접근과 보이는 포커스 상태를 유지한다.	버튼, 링크, 입력, 탭에 `:focus-visible` 스타일이 적용된다.	T-NF-003
R-NF-004	P1	레이아웃 변경은 페이지별 대규모 재작성보다 전역 override 계층으로 관리한다.	새 규칙이 `theme-atlas.css` 중심으로 위치한다.	T-NF-004
R-NF-005	P1	GA4 이벤트에는 개인정보와 검색어 원문을 보내지 않는다.	검색 이벤트는 `query_length`만 사용한다.	T-NF-005
R-NF-006	P2	정적 자산은 이미지 렌더링 실패 시 레이아웃을 깨지 않아야 한다.	로고 컨테이너에 배경색/크기 fallback이 있다.	T-NF-006

6. 사용자 시나리오

정상 흐름

방문자는 모바일에서 글 목록을 연다.
글 제목, 날짜, 카테고리, 요약, 읽기 링크를 확인한다.
사이드바 버튼을 눌러 검색을 연다.
검색어를 입력하고 결과를 확인한다.
검색 결과에서 관련 포스트로 이동한다.

예외 흐름

검색 데이터 로딩이 실패한다.
사용자는 검색 결과 영역에서 오류 메시지를 확인한다.
사이드바를 닫아 본문으로 돌아간다.

7. 예외/에러 처리 요구사항

ID	발생 조건	시스템 동작	사용자 응답	로깅	관련 테스트
R-ERR-001	`/search.json` 로딩 실패	검색 결과 영역에 오류 메시지 표시	다른 탐색 경로를 사용할 수 있다.	`console.error` 1회	T-ERR-001
R-ERR-002	검색 결과 없음	결과 없음 메시지와 다른 검색어 안내 표시	검색어를 바꿀 수 있다.	없음	T-ERR-002
R-ERR-003	계산기 입력값이 비어 있거나 잘못됨	오류 영역에 안내 표시	값을 수정 후 재시도한다.	없음	T-ERR-003
R-ERR-004	로고 이미지 로딩 실패	배경색과 크기는 유지	레이아웃이 깨지지 않는다.	없음	T-ERR-004

8. 데이터/인터페이스 요구사항

입력 데이터

Jekyll front matter: title, date, date_modified, last_modified_at, categories, series, learning_outcomes, references
검색 데이터: /search.json
UI 상태: URL q 파라미터, localStorage.sidebarCollapsed

출력 데이터

정적 HTML, CSS, JavaScript
sitemap.xml, feed.xml, SEO 메타태그
GA4 이벤트: tool_calculate, tool_tab_change, search_submit, post_category_filter, outbound_link_click

외부 연동

GitHub Pages
Google Analytics 4
Google Search Console
Utterances 댓글

9. 제약사항

GitHub Pages 정적 사이트 제약을 유지한다.
서버 사이드 검색, 데이터베이스, 로그인 기능은 사용하지 않는다.
사용자의 실제 GA4, Search Console 콘솔 설정은 로컬 코드만으로 검증할 수 없다.
일부 검증은 브라우저 수동 확인 또는 Playwright E2E가 필요하다.

10. 가정/확인 필요 사항

[가정] 기본 배포 브랜치는 main이다.
[가정] 블로그의 핵심 시각 방향은 민트/파스텔 계열이다.
[확인 필요] Search Console 소유권 등록과 사이트맵 제출 완료 여부.
[확인 필요] GA4 DebugView에서 이벤트가 실제 수집되는지.
[확인 필요] 운영자가 앞으로 보라색 accent를 완전히 제거할지, 제한된 보조 색으로 유지할지.

11. 정보 공백 및 사용자 확인 요청 항목

12. 요구사항 추적 매트릭스

요구사항	테스트	LLD 모듈	구현 상태
R-001	T-001, T-009	M-001	구현됨
R-002	T-002, T-010	M-002, M-005	구현됨
R-003	T-003, T-011	M-003	구현됨
R-004	T-004	M-003, M-007	구현됨
R-005	T-005, T-012	M-004	구현됨
R-006	T-006	M-006	구현됨
R-007	T-007	M-008	구현됨
R-008	T-008	M-005, M-007	구현됨
R-009	T-013	M-009	구현됨
R-010	T-014	M-001, M-009	확인 필요
R-011	T-015	M-012	구현됨
R-012	T-016	M-004, M-013	구현됨
R-NF-001	T-NF-001	M-010	구현됨
R-NF-002	T-NF-002	M-001	구현됨
R-NF-003	T-NF-003	M-001, M-004	구현됨
R-NF-004	T-NF-004	M-001, M-002	구현됨
R-NF-005	T-NF-005	M-011	부분 구현
R-NF-006	T-NF-006	M-006	구현됨
R-ERR-001	T-ERR-001	M-003	구현됨
R-ERR-002	T-ERR-002	M-003	구현됨
R-ERR-003	T-ERR-003	M-008	구현됨
R-ERR-004	T-ERR-004	M-006	구현됨

13. 승인 기록

날짜	작성자	상태	비고
2026-05-05	Codex	Draft	커밋 `40d60a8` 이후 품질 문서 v1 작성