theme.json 이 하는 일 — 블록 에디터로 팔레트를 넘기는 통로

토큰을 CSS 에 심어도 블록 에디터는 그것을 모릅니다. 편집자가 문단을 선택하고 색을 고르면 테마와 아무 관계 없는 색상환이 열립니다. 이 간극을 메우는 파일이 theme.json 입니다.

이름 때문에 스타일 설정 파일처럼 보이지만, 디자인 시스템 관점에서 이 파일의 정체는 통로입니다. 우리가 정한 팔레트 · 글자 크기 · 간격 척도를 편집 화면으로 넘겨주는 통로입니다.

팔레트를 넘기면 일어나는 일

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand",   "name": "브랜드",   "color": "#0e7c66" },
        { "slug": "ink",     "name": "본문",     "color": "#1f2933" },
        { "slug": "surface", "name": "배경",     "color": "#ffffff" }
      ]
    }
  }
}

이 파일 하나로 세 가지가 동시에 생깁니다. 편집 화면의 색 선택기에 이 세 색이 스와치로 뜨고, 프론트에는 .has-brand-color 같은 클래스가 자동으로 생기며, 워드프레스가 --wp--preset--color--brand 형태의 CSS 변수를 스스로 내보냅니다.

값이 두 곳에 살지 않게 하는 법

여기서 함정이 하나 있습니다. 같은 색이 CSS 토큰 파일과 theme.json 두 곳에 적히면, 언젠가 한쪽만 고쳐집니다. 그리고 그 어긋남은 편집자가 만든 화면에서만 드러나기 때문에 발견이 늦습니다.

해결은 한쪽을 다른 쪽에 종속시키는 것입니다. 워드프레스가 프리셋 변수를 스스로 내보내므로, theme.json 을 값의 출처로 삼고 우리 토큰이 그것을 참조하게 하면 출처가 하나로 남습니다.

:root {
  --brand: var(--wp--preset--color--brand);
  --ink: var(--wp--preset--color--ink);
}

반대 방향도 가능하지만, 편집 화면의 스와치는 미리보기를 위해 실제 색 값을 필요로 하므로 위 방향이 대체로 덜 번거롭습니다. 어느 쪽을 고르든 규칙은 같습니다 — 값은 한 곳에만 산다.

theme.json 이 닿지 않는 곳

이 파일의 영향 범위를 정확히 알아 두는 편이 좋습니다. 블록으로 만들어진 콘텐츠 영역에는 강하게 작용하지만, 코드로 짠 페이지 템플릿 · 헤더 · 푸터에는 관여하지 않습니다. 그쪽은 여전히 우리 CSS 토큰이 담당합니다.

그래서 실무의 구성은 대개 두 층입니다 — 사이트의 뼈대는 코드와 토큰이 그리고, 편집자가 채우는 본문 영역은 theme.json 이 울타리를 칩니다. 두 층이 같은 값을 보고 있으면 화면은 한 벌로 읽힙니다.

간격과 글자 크기도 같은 방식으로 넘길 수 있습니다(settings.spacing.spacingSizes · settings.typography.fontSizes). 3회차에서 정한 척도를 여기에 그대로 옮기면 편집자의 간격 선택도 척도 안으로 들어옵니다.

블록 에디터와 테마의 관계를 더 보려면 테마 · 플러그인 아카이브가 있고, 테마 구조 정비를 함께 맡기고 싶다면 최적화 지원 사업에 포함됩니다.

다음 회차

팔레트를 넘겼습니다. 그런데 편집자의 색 선택기에는 우리 스와치 옆에 여전히 자유 색상환이 있습니다. 다음 회차에서 그것을 닫습니다 — 자유도를 줄여 일관성을 얻는 설정입니다.