한눈에 보기: 워드프레스 CSS는 테마의 품질과 사용자 경험을 결정합니다. theme.json 전역 토큰으로 색·간격·타이포를 관리하고, Flex·Grid로 반응형 레이아웃을 설계하세요. 블록 에디터의 .wp-block-* 클래스·alignwide/alignfull를 정확히 대응하면 에디터와 프론트의 일관성이 높아집니다. 마지막으로 크리티컬 CSS·CLS 방지 등 성능 루틴을 적용하면 디자인과 속도를 동시에 잡을 수 있습니다.

목차
1. 전역 스타일 전략: theme.json과 전역 토큰
2. 반응형 레이아웃: Flex·Grid 활용
3. 블록 에디터 스타일링: Gutenberg와 .wp-block-*
4. 타이포그래피 시스템
5. 이미지·미디어 요소 다루기
6. 헤더·내비·푸터 스타일링
7. 성능 최적화 CSS
8. 커스텀 CSS 관리 방법
9. 흔한 깨짐 디버깅
10. FAQ
11. 이 글의 범위와 문의 안내
12. 출처
관련글 추천

1. 전역 스타일 전략: theme.json과 전역 토큰

theme.json은 테마의 전역 디자인 시스템을 선언하는 파일입니다. 색상·간격·타이포그래피 등을 정의하면, 워드프레스가 --wp--preset--* CSS 변수를 생성해 에디터와 프론트에서 일관되게 사용합니다. “추가 CSS”로 개별 스타일을 쌓는 방식보다 유지보수와 협업에 유리합니다.

예를 들어 기본 색·폰트·콘텐츠 폭을 다음처럼 정의할 수 있습니다. 변수는 var(--wp--preset--color--primary)처럼 참조합니다.

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "name": "Primary", "color": "#0ea5e9" },
        { "slug": "neutral", "name": "Neutral", "color": "#0f172a" }
      ]
    },
    "spacing": { "units": ["px","rem","%"], "blocksGap": "1.2rem" },
    "typography": {
      "fontSizes": [
        { "slug": "base", "size": "1rem" },
        { "slug": "lg", "size": "1.125rem" },
        { "slug": "xl", "size": "1.25rem" }
      ],
      "lineHeight": "1.6"
    },
    "layout": { "contentSize": "720px", "wideSize": "1100px" }
  }
}

전역 토큰을 쓰면 다크모드나 브랜드 리뉴얼에도 대응이 쉬워집니다. HTML 필수 가이드의 시맨틱 구조와 함께 사용하면 구조·스타일의 경계가 명확해집니다.

핵심 요약: theme.json으로 전역 토큰을 정의하고, CSS는 토큰을 소비하는 역할에 집중하세요.

2. 반응형 레이아웃: Flex·Grid 활용

반응형의 기본은 모바일 퍼스트입니다. 작은 화면에서 단일 컬럼, 넓어질수록 컬럼을 늘리는 전략이 유지보수에 유리합니다. CSS Grid는 영역 배치를, Flex는 축 정렬과 분배를 담당하도록 역할을 나누세요.

아래는 카드 목록의 대표적인 모바일 퍼스트 Grid 예시입니다. 단일 컬럼 → 40rem 이상에서 2컬럼 → 64rem 이상에서 3컬럼으로 확장합니다.

.cards {
  display: grid;
  grid-template-columns: 1fr;
  gap: 1rem;
}
@media (min-width: 40rem) {
  .cards { grid-template-columns: repeat(2, 1fr); }
}
@media (min-width: 64rem) {
  .cards { grid-template-columns: repeat(3, 1fr); }
}

헤더·내비처럼 가로 배치가 핵심인 경우엔 Flex가 단순합니다.

.nav {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: .75rem;
}

핵심 요약: “Grid = 영역 배치”, “Flex = 정렬/분배”로 역할을 분리하면 레이아웃이 단순해집니다.

3. 블록 에디터 스타일링: Gutenberg와 .wp-block-*

블록 에디터는 블록마다 .wp-block-* 클래스를 붙입니다. 테마는 이를 대상으로 최소한의 여백·타이포를 보정해 에디터와 프론트의 일관성을 확보해야 합니다. 또한 alignwide, alignfull 클래스를 수용할 레이아웃 컨테이너가 필요합니다.

아래는 콘텐츠 컨테이너 폭과 와이드/풀 정렬을 처리하는 기본 패턴입니다.

.container { max-width: 720px; margin-inline: auto; padding-inline: 1rem; }
.alignwide  { max-width: 1100px; margin-inline: auto; }
.alignfull  { width: 100vw; margin-left: calc(50% - 50vw); margin-right: calc(50% - 50vw); }

대표 블록에 대한 최소 스타일도 준비해 두세요.

.wp-block-image figcaption { color: var(--wp--preset--color--neutral); opacity: .75; }
.wp-block-quote { border-inline-start: 4px solid var(--wp--preset--color--primary); padding-inline: 1rem; }

핵심 요약: 컨테이너 폭 + alignwide/alignfull 처리가 에디터·프론트 일치의 핵심입니다.

4. 타이포그래피 시스템

가독성은 줄 길이·행간·대비로 결정됩니다. 본문은 16px(1rem) 기준에 line-height: 1.6 전후를 제안합니다. 제목 크기는 clamp()로 반응형 스케일을 구성하면 브레이크포인트가 줄어듭니다.

:root에 타입 토큰을 두고 요소에 적용하면 전체 일관성이 높아집니다.

:root{
  --font-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans", sans-serif;
  --fs-base: 1rem;
  --fs-lg: clamp(1.125rem, 1rem + 1vw, 1.375rem);
  --fs-xl: clamp(1.375rem, 1rem + 2vw, 1.75rem);
}
body{ font-family: var(--font-sans); font-size: var(--fs-base); line-height: 1.6; }
h1{ font-size: clamp(2rem, 1.5rem + 3vw, 3rem); line-height: 1.2; }
h2{ font-size: var(--fs-xl); line-height: 1.3; }

코드·인용·리드 문장 등 패턴도 사전에 정의하면 재사용성이 좋아집니다.

핵심 요약: 타입 스케일은 clamp()와 토큰으로 구성해 일관성과 유연성을 동시에 확보하세요.

5. 이미지·미디어 요소 다루기

마크업은 <figure>·<figcaption>을 기본으로, CSS는 비율과 오버플로를 제어합니다. 이미지에는 width/height 또는 aspect-ratio를 지정해 CLS를 방지하세요.

캡션과 반응형 이미지를 위한 최소 스타일입니다.

.wp-block-image img{ display:block; height:auto; max-width:100%; }
.wp-block-image figcaption{ text-align:center; font-size:.875rem; opacity:.8; }
.media-cover{ aspect-ratio: 16/9; object-fit: cover; width: 100%; }

동영상·임베드엔 고정 비율 래퍼를 제공하면 레이아웃 이동이 줄어듭니다.

핵심 요약: 의미는 figure/figcaption, 안정성은 aspect-ratio/폭 제어로 확보합니다.

6. 헤더·내비·푸터 스타일링

헤더는 스크롤 시 흔들림 없이 고정되어야 합니다. position: sticky;는 브라우저 호환과 접근성이 좋습니다. 내비게이션은 키보드 포커스 링이 명확해야 하며, 포커스 트랩을 만들지 않도록 주의합니다.

아래는 스티키 헤더와 기본 내비 예시입니다.

.site-header{ position: sticky; top: 0; background: #fff; z-index: 50; }
.nav a{ padding:.5rem .75rem; border-radius:.375rem; }
.nav a:focus-visible{ outline: 2px solid var(--wp--preset--color--primary); outline-offset: 2px; }
  • 접근성: 스킵 링크 제공, 포커스 시각화, 실제 버튼/링크 요소 사용
  • 메뉴 깊이:
    • 2단계까지만 노출
    • 모바일은 아코디언 패턴 권장

핵심 요약: 스티키·포커스·깊이 제한의 3요소로 내비를 단순하게 유지하세요.

7. 성능 최적화 CSS

렌더링을 지연시키는 CSS는 최소화해야 합니다. Above-the-fold에 필요한 크리티컬 CSS만 인라인(테마 전역)하고, 나머지는 파일로 로드하세요. 폰트는 font-display: swap;으로 FOUT 전략을 택합니다.

CLS(누적 레이아웃 이동)는 이미지 치수·웹폰트 교체·광고/임베드 높이 미정에서 주로 발생합니다. 필수 영역에 플레이스홀더 높이를 명시하세요.

  • 크리티컬 CSS: Above-the-fold 최소화, 나머지는 지연
  • CLS 방지:
    • 이미지 width/height 또는 aspect-ratio 지정
    • 웹폰트 swap, 임베드 고정 높이
  • 번들링: 미니파이·중복 제거로 페이로드 축소

핵심 요약: 크리티컬 최소화 + CLS 방지가 체감 성능을 좌우합니다.

8. 커스텀 CSS 관리 방법

스타일 관리 장소가 분산되면 누락과 충돌이 잦습니다. 규모·팀 구성에 따라 “추가 CSS”·차일드 테마·빌드 파이프라인 중 한 가지를 기준선으로 정하세요.

  • 추가 CSS: 소규모 사이트, 긴급 패치에 적합. 장기 유지에는 비권장
  • 차일드 테마: 부모 업데이트에 안전. style.css로 커스터마이징
  • 빌드 파이프라인:
    • SCSS/PostCSS로 토큰·유틸리티 관리
    • 미니파이·자동 접두사·코드 분할

핵심 요약: 운영 기준선(차일드 or 빌드)을 정하고 “추가 CSS”는 보조로만 쓰세요.

9. 흔한 깨짐 디버깅

특이성 충돌과 상속 오해가 가장 흔한 원인입니다. 개발자 도구에서 “적용된 규칙” 순서를 확인하고, 과한 !important를 줄이세요. 전역 리셋은 이점이 있지만, 블록 스타일과 충돌하지 않도록 최소화가 필요합니다.

특이성 제어를 위해 :where()를 활용하면 낮은 특이성으로 유틸리티를 선언할 수 있습니다.

:where(.prose) h2{ margin-top: 1.5rem; }

에디터와 프론트가 다르게 보이면 editor-style을 등록하고 동일한 CSS/토큰을 공유하세요. PHP와 워드프레스 글의 wp_enqueue_style() 예시를 참고하면 로딩 순서를 통제할 수 있습니다.

핵심 요약: 특이성·상속·로딩 순서 3가지를 점검하면 대부분의 깨짐이 해결됩니다.

10. FAQ

Q. “추가 CSS”만으로 사이트 운영해도 되나요?
소규모·단기 프로젝트에 한해 가능합니다. 장기 운영은 차일드 테마 또는 빌드 파이프라인을 권장합니다. theme.json으로 전역 토큰을 먼저 정의하세요.

Q. alignfull/alignwide가 적용되지 않습니다.
콘텐츠 래퍼의 폭 제어가 없거나 강제 폭 제한이 있을 수 있습니다. .alignfull의 100vw와 음수 마진, .alignwide의 확장 폭을 수용하는 컨테이너 규칙을 추가하세요(3번 섹션 코드 참고).

Q. CLS를 줄이려면 어디부터 손보나요?
이미지의 width/height(또는 aspect-ratio), 웹폰트 font-display: swap;, 임베드/광고 고정 높이부터 적용하세요.

Q. 에디터 미리보기와 실제 화면이 달라요.
에디터용 스타일을 등록하고, 동일한 토큰/변수를 공유해야 합니다. 블록별 최소 스타일을 에디터에도 로드하세요.

Q. 웹폰트는 어떻게 최적화하나요?
Woff2 사용, 서브셋 생성, font-display: swap;, 필요 시 preload를 고려하세요. 무거운 가변 폰트는 스타일 수를 줄여 페이로드를 통제합니다.

핵심 요약: 전역 토큰·컨테이너 폭·CLS 3가지만 해결해도 댓글 질문의 대부분이 사라집니다.

11. 이 글의 범위와 문의 안내

이 글은 워드프레스 CSS 전략과 실무 패턴에 초점을 둡니다. 특정 사이트의 개별 오류나 테마/플러그인 충돌 등 1:1 디버깅은 범위에 포함되지 않습니다. 이상이 발생하면 다음 순서로 점검해 주세요: 기본 테마 전환 → 플러그인 단계적 비활성화 → 개발자 도구로 특이성/로딩 순서 확인.

심화 학습은 캐싱·성능 최적화, JavaScript 기본 & ES6, React로 Gutenberg 블록 개발하기에서 이어집니다.

핵심 요약: 본문과 연결 글만으로 자가 해결이 가능하도록 구성했습니다. 개별 디버깅은 본 글의 범위를 벗어납니다.

12. 출처