아래 순서로 확인하면 대부분의 렌더링 문제를 빨리 찾을 수 있다.

1. 구조 확인

  • config/_default/hugo.toml 과 config/_default/params.toml 이 루트에 남아 있는가
  • config/_default/languages/ 아래에 언어 파일이 정리되어 있는가
  • 홈이 정상적으로 열리는가
  • 소개/블로그/카테고리/태그/연락처가 서로 연결되는가
  • 언어별 하위 경로가 유지되는가

2. 토큰 확인

  • 색상, 배경, 테두리, 그림자가 theme-vars를 읽는가
  • 폰트가 언어별로 바뀌는가
  • 버튼과 CTA의 톤이 일관적인가
  • 공지/알림의 패딩, 간격, 이미지 크기가 모바일/태블릿/데스크톱에서 다르게 보이는가
  • 공지 이미지가 16:9 고정 비율로 유지되는가

3. 문법 확인

  • 헤딩, 표, 코드, 인용, 목록이 깨지지 않는가
  • collapse 내부에서 markdownify가 유지되는가
  • ltr/rtl 블록이 다른 요소를 밀어내지 않는가

4. 미디어 확인

  • figure 캡션이 길어도 화면이 무너지지 않는가
  • page bundle 리소스가 상대경로로 읽히는가
  • 인라인 이미지가 baseline을 깨지 않는가
  • 공지 이미지가 카드 폭을 넘지 않고, 모바일에서 과도하게 커지지 않는가

5. 배포 전 승인 기준

기준 확인 결과
링크 실제 존재하는 경로만 연결
구조 root config 와 theme data 분리 완료
디자인 값은 중앙 토큰에서 관리
언어 ko 우선 검증 후 다른 언어도 같은 규칙
유지보수 다음 변경 때도 로그를 이어 쓸 수 있음

이 체크리스트는 기능 테스트가 아니라, “프런트엔드가 의도한 대로 읽히는가"를 보는 검증표다.

6. 공지 / CTA 모듈 확인

  • themes/(0000-0000-0000-0001)/data/40-communication/announcement/_index.toml 이 실제 원본으로 읽히는가
  • themes/(0000-0000-0000-0001)/data/40-communication/announcement/<lang>.toml 에 제목/본문/이미지/CTA 가 들어 있는가
  • config/_default/params/_index.toml 은 경로 안내용 주석 파일로만 남아 있는가
  • announcement 는 enabled = false 상태에서 기본 비노출이 유지되는가
  • enabled = true 와 itemLimit = 0 조합에서 활성 공지가 모두 렌더링되는가
  • 전역 배너가 모든 page kind 에서 빠지지 않고 노출되는가
  • nested section / path scope 가 실제로 매칭되는가
  • dismiss 상태가 storageKey 에 저장되고, 다시 접속했을 때 동일하게 유지되는가
  • 서로 다른 공지의 dismiss 상태가 서로 간섭하지 않는가
  • modal 공지와 banner 공지가 같이 있을 때도 한 쪽이 다른 쪽을 가리지 않는가
  • 닫기 와 24시간 동안 숨기기 버튼이 둘 다 표시되는가
  • 닫기 는 sessionStorage 로, 숨기기 는 localStorage TTL 로 동작하는가
  • 버튼 위치가 데스크톱에서 footer 우측 정렬로 자연스럽게 보이는가

7. 정리 기준

  • 렌더링은 되는데 디자인만 어긋나면 theme-vars 를 먼저 고친다.
  • 문구가 틀리면 data/40-communication/announcement/_index.toml 과 data/40-communication/announcement/<lang>.toml 을 먼저 본다.
  • 특정 섹션에서만 안 보이면 scope.path / scope.pathPrefixes / scope.sections 를 먼저 본다.
  • 전체가 안 보이면 master enabled 와 theme data 경로를 먼저 본다.

8. 공지/알림 전용 검증

  • base 파일과 언어별 오버라이드 파일이 분리되어 있는가
  • announcementProfile = "showcase" 를 넣은 페이지에서 모달형과 인라인 카드형이 동시에 확인되는가
  • 이미지, 상세보기 CTA, 캡션이 언어별 문구로 교체되는가
  • enabled = false 샘플을 유지한 채 운영자가 바로 켜서 테스트할 수 있는가
  • taxonomy / term 전용 예시를 켰을 때 categories / tags 페이지에만 노출되는가
  • 모바일에서 공지 타이틀이 줄바꿈되더라도 레이아웃이 흔들리지 않는가
  • snoozeHours 를 바꿨을 때 숨김 TTL 이 그 값대로 적용되는가

9. 배포 직전 체크

  • 공통 디자인 토큰은 theme-vars 에만 남아 있는가
  • 텍스트 번역은 theme i18n 에서만 읽는가
  • 공지/알림의 실제 값은 data/40-communication/announcement/_index.toml 계열에만 있는가
  • 공지 동작 JS 는 외부 파일로 분리되어 있는가
  • 운영자 문서(이 update-log)가 최신 경로를 설명하고 있는가

10. 공지/알림 재검증 항목

이번 패스 이후에는 아래 순서로 다시 확인해야 한다.

  • 닫기 버튼을 눌렀을 때 즉시 숨겨지는가
  • 24시간 동안 숨기기 버튼이 실제 TTL 로 저장되는가
  • 같은 공지의 상태가 서로 다른 공지에 전염되지 않는가
  • priority 가 낮은 항목이 먼저 렌더링되는가
  • itemLimit 이 0/미설정일 때 전체 노출로 동작하는가
  • itemLimit 이 양수일 때 상위 N개로 잘리는가
  • announcement/<lang>.toml 이 문구만 덮어쓰는지 구조까지 바꾸지 않는가
  • dialog 형 공지에서도 클릭이 정상 동작하는가
  • 모바일에서 닫기 / 숨기기 버튼이 눌리지 않는 상태로 겹치지 않는가

이번 검증은 스타일보다 기능 우선이다.
화면이 예뻐 보여도 닫기와 숨기기가 깨지면 아직 완료된 상태가 아니다.

11. JS 검증 추가 항목

  • config/_default/params.toml 의 [params.js] 가 실제로 모듈을 켜고 끌 수 있는가
  • themes/(0000-0000-0000-0001)/assets/js/04-composition-layer/cross-cutting-composition/announcement-boot.js 가 dismiss 된 공지를 첫 페인트 전에 숨기는가
  • themes/(0000-0000-0000-0001)/assets/js/04-composition-layer/cross-cutting-composition/navigation.js 가 메뉴 스크롤 저장, 앵커 스크롤, top 버튼 노출을 모두 처리하는가
  • themes/(0000-0000-0000-0001)/assets/js/04-composition-layer/cross-cutting-composition/code-copy.js 가 code block 에 버튼을 실제로 붙이는가
  • themes/(0000-0000-0000-0001)/assets/js/04-composition-layer/cross-cutting-composition/announcement.js 가 session / persistent / snooze 상태를 기존 구조와 호환되게 저장하는가
  • node --check 로 모든 신규 JS 모듈의 문법이 통과하는가