[워드프레스] 28. theme.json : 블록 테마 스타일의 중심 theme.json

(워드프레스 해부 ㉘) theme.json

블록 테마에서 색·폰트·간격·레이아웃 폭 같은 걸 정하는 단 하나의 파일이 theme.json이다. CSS를 여기저기 흩뿌리는 대신, 디자인 값을 JSON 한 곳에 모아 디자인 토큰처럼 관리한다.

핵심은 프리셋 → CSS 변수다. theme.json에 색 팔레트를 정의하면, 워드프레스가 자동으로 --wp--preset--color--accent-1 같은 CSS 변수를 만들어 준다. 그럼 블록들이 그 변수를 참조한다. 나도 이 사이트를 이 방식으로 잡았다 — 팔레트 한 곳만 바꾸면 표·코드·링크가 전부 따라오게.

theme.json 사용법의 절반은 위치다. 파일은 테마 루트 — wp-content/themes/테마명/theme.json — 에 둔다. 등록 코드 없이 파일이 거기 있으면 알아서 읽는다. 아래 예제는 전부 이 위치에 놓는 파일 전체 내용이다.

직접 해보기

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "accent-1", "color": "#6D5AE6", "name": "포인트" },
        { "slug": "base",     "color": "#FBFBFA", "name": "배경" }
      ]
    },
    "layout": { "contentSize": "720px", "wideSize": "1200px" }
  }
}

이대로 저장하면 두 가지가 바로 바뀐다. 글 편집기에서 아무 블록이나 잡고 색 메뉴를 열면 색상판에 ‘포인트’와 ‘배경’이라는 이름의 견본이 새로 떠 있고, 본문 폭은 720px로 잡힌다. 이름표가 안 뜨면 십중팔구 JSON 문법 오류다(뒤에서 다룬다).

사용자가 사이트 편집기에서 바꾼 값은 파일이 아니라 DB(전역 스타일)에 저장돼 테마 theme.json을 덮어쓴다. 그래서 편집기 수정과 파일 정의가 병합된다.

✅ 확인 — 페이지 소스의 <style>에서 --wp--preset--color--accent-1: #6D5AE6 같은 CSS 변수가 생성돼 있으면, theme.json의 팔레트가 변수로 변환된 것이다. 이게 블록 테마 스타일의 뼈대다.

브라우저 확인법은 하나로 족하다. F12 → Elements에서 <style id="global-styles-inline-css">를 찾는다. 워드프레스는 theme.json 전체를 이 인라인 스타일로 컴파일해 내보내고, 맨 위 :root에 --wp--preset--* 변수가 죽 나열된다. 내가 적은 값이 여기 없으면 아직 사이트에 도착하지 않은 것이다.

settings와 styles — 역할이 다르다

theme.json은 크게 두 구역으로 나뉜다. settings는 무엇을 쓸 수 있게 할지를 정한다 — 색 팔레트, 글꼴, 간격 프리셋, 그리고 블록이 쓸 수 있는 기능. styles는 실제 값을 어떻게 줄지다 — 본문 배경색, 기본 글꼴 크기, 링크 색을 실제로 지정한다. settings가 ‘재료 목록’이면 styles는 ‘그 재료로 차린 상’이다.

{
  "version": 3,
  "settings": {
    "color": { "palette": [
      { "slug": "accent-1", "color": "#FF8000", "name": "포인트" }
    ] },
    "typography": { "fontSizes": [
      { "slug": "small", "size": "0.9rem", "name": "작게" }
    ] }
  },
  "styles": {
    "color": { "background": "#ffffff" },
    "elements": { "link": { "color": { "text": "var(--wp--preset--color--accent-1)" } } }
  }
}

저장하면 본문 배경이 흰색이 되고, 본문 링크가 전부 포인트색으로 바뀐다. 링크 색을 var(--wp--preset--color--accent-1)로 참조했으니 팔레트에서 색 하나만 바꿔도 링크가 따라온다. fontSizes에 넣은 ‘작게’는 편집기의 글자 크기 선택지에 그대로 등장하고, CSS엔 --wp--preset--font-size--small: 0.9rem으로 떨어진다.

전역 타이포그래피와 간격도 같은 자리에서 잡는다. 이것도 동작하는 최소 파일이다.

{
  "version": 3,
  "settings": { "spacing": { "blockGap": true } },
  "styles": {
    "typography": { "fontSize": "1.05rem", "lineHeight": "1.75" },
    "spacing": { "blockGap": "1.6rem" }
  }
}

저장 후엔 모든 본문 글자가 1.05rem·줄간격 1.75로, 블록 사이 세로 간격이 1.6rem으로 바뀐다. F12로 body를 잡아 Computed 탭을 보면 저 값으로 계산돼 있다. 이 블로그의 본문 줄간격 1.75도 정확히 이 스키마로 지정한 값이다(나는 파일 대신 전역 스타일 쪽에 넣었지만, 쓰는 키는 같다).

누가 이기나 — 스타일 병합 우선순위

‘사이트 편집기에서 바꾼 값이 파일을 덮어쓴다’를 정확히 하면, 스타일은 여러 층이 병합되고 뒤가 이긴다.

우선순위	층	저장 위치
1 (바닥)	워드프레스 코어 기본값	코어
2	테마 theme.json	테마 파일
3	자식 테마 theme.json	자식 테마 파일
4 (최종)	사용자 전역 스타일	DB(wp_global_styles)

그래서 사이트 편집기에서 색을 바꿨는데 theme.json을 고쳐도 안 먹는다면 — 4층(DB)이 2층(파일)을 덮고 있는 것이다. 편집기의 ‘스타일 초기화’로 4층을 비우면 파일 값이 다시 보인다. 이 표 하나면 “왜 내 theme.json이 무시되지?”류의 미스터리가 전부 풀린다.

버전 3과 유동 타이포그래피

theme.json은 버전이 올라가며 기능이 는다. version 3은 워드프레스 6.6부터 쓸 수 있는데, 대표적으로 유동 타이포그래피(fluid typography)가 들어왔다 — 화면 폭에 따라 글자 크기가 매끄럽게 커지고 줄어드는 기능이라, 모바일과 데스크톱에서 각각 크기를 잡을 필요가 줄었다. 새 테마라면 version 3으로 시작하는 게 좋다.

블록마다 따로 값을 줄 수도 있다

styles 안에 blocks를 두면 특정 블록에만 스타일을 준다. 예를 들어 코드 블록엔 옅은 배경과 둥근 모서리를, 인용 블록엔 왼쪽 선을 주는 식이다. 이 블로그의 코드·인용 블록 디자인도 전부 여기서 잡았다.

"styles": {
  "blocks": {
    "core/code":  { "color": { "background": "#f5f5f4" }, "border": { "radius": "10px" } },
    "core/quote": { "border": { "left": { "width": "3px", "color": "#FF8000" } } }
  }
}

위 조각은 전체 파일에서 styles 부분만 잘라 보인 것이다. 완결형으로 하나 더 — 버튼 블록만 손보는 파일 전체는 이렇다.

{
  "version": 3,
  "settings": {
    "color": { "palette": [
      { "slug": "accent-1", "color": "#FF8000", "name": "포인트" }
    ] }
  },
  "styles": {
    "blocks": {
      "core/button": {
        "color": { "background": "var(--wp--preset--color--accent-1)", "text": "#1C1B1F" },
        "border": { "radius": "999px" },
        "typography": { "fontWeight": "700" }
      }
    }
  }
}

저장하면 사이트의 모든 버튼 블록이 주황 배경·알약 모양·굵은 글씨가 된다. 편집기에서 버튼을 새로 추가해 보면 처음부터 이 모양으로 태어난다. 특정 버튼만 다르게 하고 싶으면 그 블록에서 직접 바꾸면 되고, 그 값은 개별 속성이라 theme.json보다 우선한다. 블록 테마 커스터마이징에서 손이 가장 많이 가는 게 버튼·코드·인용 같은 반복 블록인데, 여기서 한 번에 끝내는 게 정석이다.

흔한 함정 — 고쳤는데 아무 일도 없을 때

theme.json의 고약한 점은 틀려도 에러를 안 낸다는 것이다. 화면이 죽지도 경고가 뜨지도 않고, 그냥 아무 일도 일어나지 않는다. 내가 겪은 ‘조용한 실패’는 대부분 셋이다.

정리하면 theme.json은 ‘흩어진 CSS를 한 파일의 디자인 토큰으로 모으는’ 장치다. 이걸 템플릿 파트·사이트 편집기와 함께 쓰면, 코드를 최소한만 만지면서 사이트 전체의 룩을 일관되게 관리할 수 있다.

스타일을 봤으니, 다음은 헤더·푸터를 이루는 템플릿 파트를 편집해 본다.

자주 묻는 질문 (FAQ)

theme.json은 뭘 하나요?

블록 테마의 색·글꼴·간격 등 스타일과 설정의 중심입니다. 여기서 디자인 토큰을 정의하면 사이트 전체에 전파됩니다.

theme.json을 바꾸면 즉시 반영되나요?

대개 그렇지만 캐시나 전역 스타일 설정이 우선할 수 있어 관리자에서 확인이 필요합니다.

theme.json을 고쳤는데 사이트에 반영이 안 됩니다.

세 가지를 순서대로 확인하세요. 먼저 JSON 문법 오류(하나라도 있으면 파일 전체가 조용히 무시됩니다), 다음으로 사이트 편집기에서 저장한 전역 스타일이 파일 값을 덮고 있는지(스타일 초기화로 확인), 마지막으로 페이지 캐시입니다.