이 문서는 업그레이드용 테스트 세트를 어떤 파일 단위로 정리했는지 남겨두는 메모다.
나중에 theme를 다시 바꿀 때도 같은 기준으로 회귀 확인을 할 수 있도록, 기능과 위치를 함께 적는다.

이번에 손본 영역

  • config/_default/params.cta.toml
    CTA의 중앙 설정 원본이다. defaults / policy / preset을 분리해서 관리한다.

  • themes/(0000-0000-0000-0001)/layouts/shortcodes/cta.html
    복사/붙여넣기 가능한 예시와 기본 정책을 주석으로 남긴 shortcode 진입점이다.

  • themes/(0000-0000-0000-0001)/layouts/partials/cta/render.html
    site params / page params / shortcode 인자를 병합해 최종 CTA를 렌더링한다.

  • themes/(0000-0000-0000-0001)/assets/css/core/theme-vars.css
    CTA 전용 토큰을 추가해 컴포넌트의 간격/반경/그림자를 중앙 제어할 수 있게 했다.

  • themes/(0000-0000-0000-0001)/assets/css/extended/cta.css
    CTA의 실제 UI 규칙. 색상은 직접 지정하지 않고 중앙 토큰을 상속한다.

  • content/ko/theme-upgrade-lab/cta-shortcodes.md
    kind, preset, 링크, block shortcode, 비활성 상태, 접근성, 빈 값 폴백을 확인하는 테스트 페이지다.

  • layouts/shortcodes/design-probe.html
    theme-vars.css의 leaf 값을 재귀적으로 추적하고, config 원문값 / CSS 변수 / HTML 샘플을 같이 보여 주는 진단용 shortcode로 재구성했다.

  • layouts/partials/theme/design-probe-tree.html
    map 구조를 따라 내려가면서 leaf와 nested group을 분리 렌더링하는 탐색용 partial을 추가했다.

  • layouts/partials/theme/design-probe-table.html
    각 토큰 행에 시각 샘플 열을 붙여, 값이 실제 스타일에 어떻게 반영되는지 보이도록 바꿨다.

  • layouts/partials/theme/design-token-preview.html
    색상, 폰트, 라운드, 그림자, 길이, motion, layer 타입을 각각 다른 샘플로 보여 주는 시각화 레이어다.

  • layouts/partials/theme/design-token-kind.html / design-token-cssvar.html
    경로를 기준으로 토큰 시각화 타입과 CSS 변수명을 추적하는 보조 partial을 분리했다.

  • content/ko/theme-upgrade-lab/design-tokens.md
    검증 중심 페이지. 토큰 트리와 셸 샘플을 통해 config → CSS → HTML 연결을 확인한다.

  • content/ko/theme-upgrade-lab/layout-spacing.md
    page/content/nav 폭, padding, gap, responsive helper를 확인하는 페이지를 추가했다.

  • content/ko/theme-upgrade-lab/typography-language.md
    언어별 폰트 스택, 크기 스케일, mono/code 렌더링을 확인하는 페이지를 추가했다.

  • content/ko/theme-upgrade-lab/surfaces-controls.md
    버튼, input, chip, card, shadow, radius 등 실제 컴포넌트 톤을 확인하는 페이지를 추가했다.

  • content/ko/theme-upgrade-lab/colors-effects.md
    light/dark 색상과 효과 토큰을 빠르게 점검하는 페이지를 추가했다.

  • content/ko/theme-upgrade-lab/_index.md
    검증 순서와 페이지 링크를 새 구조에 맞게 재정렬했다.

현재 트리에서의 위치

content/ko/theme-upgrade-lab/
├── _index.md
├── colors-effects.md
├── design-tokens.md
├── edge-cases.md
├── layout-spacing.md
├── markdown-shortcodes.md
├── surfaces-controls.md
├── taxonomy-navigation.md
├── typography-language.md
└── verification-notes.md

themes/(0000-0000-0000-0001)/layouts/shortcodes/
└── design-probe.html

themes/(0000-0000-0000-0001)/layouts/partials/theme/
├── design-token-cssvar.html
├── design-token-kind.html
├── design-token-preview.html
├── design-probe-table.html
└── design-probe-tree.html

해석 기준

  • theme-vars.css의 값은 가능한 한 그대로 노출한다.
  • design-probe는 config 값과 partial fallback 값을 분리해서 보여 준다.
  • 실제 확인은 “값이 보인다”보다 “같은 토큰이 같은 컴포넌트에서 같은 톤으로 보인다”를 기준으로 한다.
  • 색상 축은 light/dark 양쪽을 같이 본다.
  • 컴포넌트는 중앙 토큰을 직접 참조해야 하며, 페이지별 하드코딩은 남기지 않는다.

보수 시 우선순위

  1. design-probe를 먼저 확인한다.
  2. 그 다음 design-tokens와 layout-spacing, typography-language, surfaces-controls, colors-effects를 본다.
  3. 마지막으로 목록/탐색/경계값 페이지에서 실제 화면 차이를 본다.

이 메모는 코드가 아니라 검증 기준서의 요약판으로 쓰면 된다.

render 호환성 수정

  • 재귀 트리에서 map 판별 시 kindIs를 사용하던 부분을 reflect.IsMap으로 교체했다.
  • Hugo 템플릿 파서에서 사전 정의되지 않은 함수로 인해 빌드가 중단되는 문제를 제거했다.