Tailwind CSS on kenji.blog

Hugo 테마 커스터마이징: Tailwind CSS 도입 방법

Sun, 13 Sep 2026 03:00:00 +0900

들어가며: 정적 사이트 생성기 Hugo와 Tailwind CSS의 강력한 시너지

현대 웹 프론트엔드 개발에서 성능과 개발자 경험(DX: Developer Experience)의 양립은 모든 프로젝트에서 가장 중요한 과제 중 하나입니다. 정적 사이트 생성기(SSG) 중에서도 세계 최고 수준의 빌드 속도를 자랑하는 Hugo와, 유틸리티 퍼스트라는 혁신적인 패러다임을 도입한 Tailwind CSS를 결합하는 것은 이 과제에 대한 하나의 궁극적인 해답이라고 할 수 있습니다.

Hugo는 Go 언어로 작성되어 있어, 수천 페이지의 사이트라도 단 몇 초 혹은 밀리초 단위로 빌드를 완료하는 경이로운 성능을 가지고 있습니다. 한편, Tailwind CSS는 사전에 정의된 무수히 많은 유틸리티 클래스(flex, text-center, mt-4 등)를 HTML에 직접 작성함으로써, CSS 파일과 HTML 파일 사이를 오가는 컨텍스트 스위칭을 없애고 디자인 이터레이션을 가속화합니다.

본 기사에서는 Hugo 테마에 Tailwind CSS를 도입하고, 나아가 PostCSS를 이용한 고도화된 에셋 파이프라인(Hugo Pipes)을 구축하는 절차를 아키텍처의 근간부터 수학적인 성능 최적화 관점에 이르기까지 철저하고 상세하게 해설합니다.

1. 유틸리티 퍼스트 CSS와 컴포넌트 지향의 변천

Tailwind CSS의 도입 절차에 들어가기 전에, 왜 우리가 Tailwind CSS를 사용해야 하는지, 그 배경에 있는 CSS 설계 사상의 역사와 진화에 대해 깊이 이해해 두는 것은 매우 유익합니다.

기존 CSS 설계(BEM이나 OOCSS)의 한계

과거의 웹 개발에서는 시맨틱한 클래스명을 부여하는 것이 베스트 프랙티스로 여겨졌습니다. 예를 들어, 카드 컴포넌트를 작성할 경우 다음과 같이 HTML과 CSS를 분리했습니다.

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">제목</h2>
 <p class="card__description">설명문이 이곳에 들어갑니다.</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* 이후 상세한 스타일이 계속됨 */

이러한 BEM(Block Element Modifier) 기반 설계는 프로젝트 규모가 작을 때는 기능하지만, 다음과 같은 문제를 일으키기 쉽습니다.

이름 짓기의 고갈과 피로: 비슷한 컴포넌트를 만들 때마다 새로운 클래스명을 고민해야 합니다(예: card-news, card-featured 등).
CSS의 비대화: 새로운 기능을 추가할 때마다 CSS의 줄 수가 계속 늘어나고, 한 번 작성된 CSS는 “어디서 사용되는지 모른다"는 두려움 때문에 삭제되는 일이 적어 데드 코드가 축적됩니다.
컨텍스트 스위칭: HTML의 구조와 CSS의 스타일을 별도의 파일로 관리하기 때문에 에디터 상에서 탭을 오가는 횟수가 기하급수적으로 증가합니다.

Tailwind CSS에 의한 패러다임 시프트

Tailwind CSS는 이러한 문제들을 ‘유틸리티 클래스의 조합’이라는 접근법으로 해결합니다. 위의 카드 컴포넌트는 Tailwind CSS를 사용하면 다음과 같이 됩니다.

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">제목</h2>
 <p class="mt-2 text-gray-600">설명문이 이곳에 들어갑니다.</p>
 </div>
</div>

클래스명 자체가 스타일의 구체적인 값(p-6는 padding: 1.5rem; 등)을 나타내고 있기 때문에, HTML을 보는 것만으로도 최종적인 렌더링 결과를 예측할 수 있습니다. 게다가 Tailwind의 JIT(Just-In-Time) 컴파일러에 의해 실제로 사용된 클래스만이 프로덕션용 CSS 파일로 추출되기 때문에 CSS의 파일 크기는 극한까지 작아집니다.

2. Hugo Pipes와 PostCSS의 아키텍처

Hugo에 Tailwind CSS를 통합하기 위해서는 Hugo Pipes라고 불리는 에셋 처리 파이프라인을 이해할 필요가 있습니다. Hugo Pipes는 Sass/SCSS 컴파일, JavaScript 번들링 및 Minify, 그리고 이번에 사용하는 PostCSS 실행 등 에셋과 관련된 모든 처리를 Hugo 내부에서 완결시키는 강력한 기능입니다.

PostCSS는 JavaScript 플러그인을 사용하여 CSS를 변환하기 위한 도구입니다. Tailwind CSS 자체도 실은 PostCSS의 플러그인으로서 동작하고 있습니다.

PostCSS에 의한 AST(추상 구문 트리) 변환 메커니즘

PostCSS가 어떻게 CSS를 처리하고 있는지를 이해하는 것은 트러블슈팅을 할 때 크게 도움이 됩니다. 다음의 Mermaid 다이어그램은 PostCSS가 CSS 파일을 읽어 들이고, 플러그인을 통해 변환하여 최종적인 CSS를 출력하기까지의 파이프라인을 보여줍니다.

flowchart TD
A["원본 CSS (styles.css)"] -->|Parser| B["AST (추상 구문 트리)"]
B --> C["Plugin 1: Tailwind CSS"]
C --> D["Plugin 2: Autoprefixer"]
D --> E["Plugin N: cssnano"]
E -->|Stringifier| F["컴파일 및 최적화된 CSS"]

Parser (파서): 입력된 원본 CSS 문자열을 분석하여, 프로그램으로 조작 가능한 데이터 구조인 AST(추상 구문 트리)로 변환합니다.
Plugins (플러그인들):
- Tailwind CSS: 템플릿 파일(HTML이나 Markdown)을 스캔하여, 사용되고 있는 유틸리티 클래스를 AST 상에 노드로 추가합니다. 또한 @tailwind 지시어를 전개합니다.
- Autoprefixer: Can I Use 데이터베이스를 참조하여, 필요에 따라 벤더 프리픽스(-webkit-, -moz- 등)를 AST의 속성에 추가합니다.
Stringifier (스트링기파이어): 변환이 완료된 AST를 다시 브라우저가 해석 가능한 CSS 문자열로 변환하여 출력합니다.

3. 환경 구축과 전제 조건

그러면 실제 도입 절차로 들어가 보겠습니다. 먼저 필요한 소프트웨어가 설치되어 있는지 확인합니다.

필수 요건

Hugo Extended Version: 일반적인 Hugo가 아닌, Sass/SCSS 처리 기능이나 네이티브 PostCSS 연동 기능이 포함된 Extended 버전이 필수입니다. 터미널에서 다음 명령어를 실행하여 버전 정보에 extended라는 문자열이 포함되어 있는지 확인해 주세요.
1 2 3

hugo version # 예상되는 출력 예시: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js와 npm: Tailwind CSS나 PostCSS 등의 의존성 패키지는 Node.js 상에서 동작합니다. Node.js(LTS 버전 권장)가 설치되어 있는지 확인합니다.
1 2

node -v npm -v

npm 패키지 설치

프로젝트 루트 디렉토리(Hugo 설정 파일 hugo.toml이 있는 위치)에서 npm을 초기화하고, 필요한 패키지를 설치합니다.

1
2
3
4
5


# package.json 생성
npm init -y

# 개발 의존성 패키지로 Tailwind CSS, PostCSS, Autoprefixer 설치
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] postcss-cli가 설치되어 있지 않으면, Hugo 내부에서 PostCSS를 호출할 때 에러가 발생할 수 있습니다. Hugo Pipes는 내부적으로 postcss-cli를 사용하므로 반드시 설치해 두어야 합니다.

4. 설정 파일 구축 (PostCSS & Tailwind CSS)

패키지 설치가 완료되면, 프로젝트의 동작을 제어할 2개의 중요한 설정 파일을 작성합니다. 프로젝트 루트 디렉토리에 배치해 주세요.

tailwind.config.js 작성

터미널에서 다음 명령어를 실행하면 기본 설정 파일이 생성됩니다.

1

npx tailwindcss init

생성된 tailwind.config.js를 에디터로 열고, content 속성을 설정합니다. 이 부분은 매우 중요합니다. Tailwind는 여기서 지정된 경로의 파일을 분석하여 사용되고 있는 클래스를 추출합니다. Hugo의 프로젝트 구조에 맞춰 레이아웃 파일이나 콘텐츠 파일을 정확하게 지정합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // Hugo의 디렉토리 구조에 맞춰 스캔 대상을 지정
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // 테마를 사용하는 경우에는 테마의 디렉토리도 포함해야 합니다
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // 커스텀 색상이나 폰트 확장을 이곳에서 진행합니다
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // 필요에 따라 공식 플러그인 추가 (예: Typography 플러그인)
 // require('@tailwindcss/typography'),
 ],
}

postcss.config.js 작성

다음으로, PostCSS가 어떤 플러그인을 어떤 순서로 실행할지를 정의하는 postcss.config.js를 프로젝트 루트에 작성합니다.

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

이 설정을 통해 Hugo가 PostCSS를 호출할 때, 먼저 Tailwind CSS 처리가 수행되고 그 다음에 Autoprefixer에 의한 벤더 프리픽스 부여가 진행됩니다.

5. Hugo에서의 CSS 에셋 파이프라인 구축

설정이 완료되면 드디어 Hugo 테마 측에 Tailwind CSS를 통합합니다.

5-1. 엔트리 포인트가 되는 CSS 파일 작성

assets/css/ 디렉토리(존재하지 않는다면 만들어주세요)에 엔트리 포인트가 될 CSS 파일을 작성합니다. 여기서는 main.css로 하겠습니다.

파일 경로: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* Tailwind의 기본 스타일(리셋 CSS 등) 불러오기 */
@tailwind base;

/* 컴포넌트 클래스 불러오기 */
@tailwind components;

/* 유틸리티 클래스 불러오기 */
@tailwind utilities;

/* 독자적인 커스텀 CSS가 필요한 경우 여기에 추가할 수 있지만,
 가능한 한 tailwind.config.js의 extend로 대응하는 것을 권장합니다 */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. 레이아웃 파일(head.html) 편집

다음으로, Hugo의 템플릿에서 위에서 만든 CSS 파일을 불러와 PostCSS로 처리하는 파이프라인을 작성합니다. 일반적으로 <head> 태그 내부를 정의하고 있는 부분 템플릿(예: layouts/partials/head.html)을 편집합니다.

파일 경로: layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- assets/css/main.css 가져오기 -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- PostCSS의 옵션 정의 -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- 프로덕션 환경(Production)을 위한 에셋 최적화 파이프라인 -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify (압축) -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint (캐시 버스팅을 위한 해시 부여) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. SRI(Subresource Integrity)를 포함하여 태그 출력 -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- 개발 환경(Development)에서는 압축하지 않고 그대로 출력 (빌드 속도 우선) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

파이프라인 해설 및 Mermaid 다이어그램

위의 Go 템플릿 코드가 어떻게 CSS 파일을 처리해 나가는지, 일련의 파이프라인 처리를 다이어그램으로 설명합니다.

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Hugo 메모리 공간"]
B -->|resources.PostCSS| C["PostCSS + Tailwind JIT 처리"]
C --> D{"hugo.IsProduction ?"}
D -- "Yes (프로덕션 환경)" --> E["minify (공백·줄바꿈 삭제)"]
E --> F["fingerprint (해시 계산)"]
F --> G["public/css/main.[hash].css (SRI 포함)"]
D -- "No (개발 환경)" --> H["public/css/main.css"]

resources.Get: assets 디렉토리 내의 지정된 파일을 찾아 메모리 상의 리소스 객체로 로드합니다.
resources.PostCSS: 프로젝트 루트의 postcss.config.js를 참조하여, CSS 소스 코드에 Tailwind CSS와 Autoprefixer 처리를 적용합니다. 개발 환경(hugo server)에서는 JIT 모드가 작동하여, 파일 변경 시 필요한 클래스만을 빠르게 생성합니다.
minify: 프로덕션 환경 빌드 시(hugo --environment production 등)에 불필요한 공백이나 주석을 삭제하여 파일 크기를 최소화합니다.
fingerprint: 파일의 내용에 기반하여 SHA 해시를 계산하고 파일명에 부여합니다(예: main.ab12cd...css). 이를 통해 브라우저의 강력한 캐시를 활용하면서 CSS 업데이트 시에는 확실하게 새로운 파일을 불러오게 하는 ‘캐시 버스팅’을 실현합니다.
integrity: Fingerprint로 계산된 해시값을 사용하여 CDN 등에서의 위변조를 방지하는 SRI 속성을 출력합니다.

6. CSS 최적화에서의 수학적 성능 분석

Tailwind CSS를 도입하는 가장 큰 장점 중 하나는 전송되는 CSS 파일 크기의 극소화입니다. 이것이 웹 성능(특히 First Contentful Paint: FCP)에 어떤 영향을 미치는지 수학적인 모델을 사용하여 정량적으로 분석해 보겠습니다.

CSS 파일 크기 감소 모델

기존 CSS 프레임워크(Bootstrap 등)에서는 사용하지 않는 스타일까지 포함하여 전체가 로드되기 때문에 파일 크기 $S_{original}$이 커지기 쉽습니다(약 150KB〜200KB). Tailwind CSS의 JIT 컴파일러에 의한 불필요한 클래스 제거(Purge) 적용 후의 크기를 $S_{purged}$라고 하면, 감소율 $R_{purge}$를 사용하여 다음과 같이 나타낼 수 있습니다.

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

일반적인 프로젝트에서 $R_{purge}$는 $0.9$(90% 감소) 가까이에 도달하며, $S_{purged}$는 불과 10KB〜20KB 정도 내에 머뭅니다.

게다가 전송 시에는 서버 측에서 Brotli나 Gzip에 의한 압축이 이루어집니다. 압축률을 $R_{compress}$(통상적으로 약 0.7〜0.8)라고 하면 네트워크를 흐르는 최종 페이로드 크기 $S_{final}$은 다음 공식으로 계산됩니다.

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

중요 렌더링 경로(Critical Rendering Path)와 네트워크 지연

브라우저가 화면에 첫 콘텐츠를 그릴 때까지의 시간(FCP)은 HTML 다운로드 시간, CSS 다운로드 시간, 그리고 렌더링 시간의 합계로 근사할 수 있습니다.

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

여기서,

$RTT$: Round Trip Time (서버와의 왕복 통신 지연 시간)
$BW$: 네트워크 대역폭 (Bandwidth)

모바일 환경 등 $BW$가 좁고 $RTT$가 큰(지연이 긴) 환경에서, $S_{final}$을 수 킬로바이트 단위까지 깎아낼 수 있는 Tailwind CSS의 접근 방식은 $\frac{S_{final}}{BW}$ 항을 극한까지 0에 가깝게 만들어, 경이로운 점수(Google PageSpeed Insights 등)를 내는 원동력이 됩니다.

7. 개발 서버 실행과 핫 리로드 확인

모든 설정이 완료되었다면 Hugo 개발 서버를 실행하고, Tailwind CSS가 올바르게 작동하는지 확인합니다.

1

hugo server -D

브라우저에서 http://localhost:1313/에 접속하여 사이트가 표시되는지 확인합니다. Markdown 콘텐츠 파일이나 Hugo 템플릿(layouts/ 이하 파일)을 열어 클래스를 추가해 보세요.

1
2
3
4
5


<!-- 테스트용 Tailwind 클래스 적용 예시 -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo is Awesome!</h1>
 <p class="mt-4 text-lg font-medium">핫 리로드가 즉각적으로 반영되는 것을 확인해 보세요.</p>
</div>

파일을 저장하는 순간, Hugo의 강력한 파일 감시자와 Tailwind의 JIT 컴파일러가 연동하여 밀리초 단위로 CSS가 재구축되고, 브라우저가 자동으로 새로고침되는(핫 리로드) 쾌감을 맛볼 수 있을 것입니다.

트러블슈팅: 스타일이 반영되지 않을 경우

만약 변경 사항이 반영되지 않는다면 다음 사항들을 체크해 보세요.

tailwind.config.js의 content 경로 설정 스캔 대상 파일 경로가 잘못되어 있으면 Tailwind는 해당 파일 내에서 사용 중인 클래스를 감지하지 못하여 CSS에 출력하지 않습니다. 특히 테마를 사용하는 경우 테마 디렉토리의 경로가 누락되지 않았는지 확인하세요.
PostCSS 에러 터미널의 Hugo 서버 로그에 Error: failed to transform resource: PostCSS not found 같은 에러가 출력된다면, npm install이 제대로 실행되지 않았거나 postcss-cli가 부족할 가능성이 있습니다.
Hugo 캐시 삭제 드물게 Hugo의 캐시 문제로 오래된 CSS가 남는 경우가 있습니다. 서버를 끄고 hugo server --ignoreCache로 다시 실행하거나, OS의 임시 디렉토리(/tmp/hugo_cache/ 등)를 삭제해 보세요.

8. 프로덕션 환경용 빌드와 더욱 고도화된 설정

사이트를 프로덕션 서버(Netlify, Vercel, GitHub Pages, Cloudflare Pages 등)에 배포할 때는, 환경 변수를 설정하여 프로덕션용 최적화 파이프라인을 실행해야 합니다.

1
2


# 프로덕션 빌드 명령어 예시
NODE_ENV=production hugo --minify --environment production

--environment production 플래그를 붙임으로써 head.html 안의 {{ if hugo.IsProduction }} 블록이 실행되며, CSS의 Minify화와 Fingerprint 부여가 수행됩니다.

Typography 플러그인을 활용한 Markdown 스타일링

Hugo 같은 블로그나 문서 사이트에서는 Markdown에서 생성된 순수 HTML 요소(<h1>, <p>, <ul> 등)에 직접 클래스를 추가할 수 없습니다. 이러한 경우에 매우 유용한 것이 Tailwind 공식 Typography 플러그인입니다.

플러그인 설치

1

npm install -D @tailwindcss/typography

tailwind.config.js에 추가

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

템플릿에 적용 글 본문을 출력하는 컨테이너 요소에 prose 클래스(및 취향에 맞게 색상이나 크기의 변형)를 부여하는 것만으로 아름다운 기본 스타일이 적용됩니다.
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

이것으로 손수 복잡한 CSS 선택자(.article-content h2 { ... })를 작성할 필요가 전혀 없어지며, 컴포넌트의 모듈성이 완벽하게 유지됩니다.

9. 요약: 유지 보수성이 뛰어난 프론트엔드 생태계 완성

수고하셨습니다. 이것으로 Hugo의 초고속 정적 사이트 생성 엔진과 Tailwind CSS의 모던한 스타일링 기능, 그리고 PostCSS의 확장성을 갖춘 완벽한 웹 개발 에셋 파이프라인이 완성되었습니다.

이 아키텍처의 뛰어난 점은 **“설정은 처음 한 번으로 끝난다”**는 것입니다. 한 번 파이프라인을 구축해 두면, 개발자는 CSS 파일을 열 필요 없이 직관적인 유틸리티 클래스를 HTML이나 Markdown 템플릿에 작성하는 것만으로 복잡한 UI를 놀라운 속도로 조립해 나갈 수 있습니다.

또한 출력되는 CSS 크기가 항상 최소화되기 때문에 Core Web Vitals 점수 향상으로도 직결되며 SEO 관점에서도 매우 유리하게 작용합니다.

Hugo와 Tailwind CSS의 조합은 개인 기술 블로그부터 대규모 기업 사이트까지 모든 프로젝트에서 ‘최고의 선택지’ 중 하나로 계속 남을 것입니다. 부디 이 강력한 툴체인을 활용하여 쾌적한 웹 개발 라이프를 즐기시길 바랍니다!

블로그의 다크 모드 지원을 위한 CSS 설계의 포인트

Sat, 12 Sep 2026 12:00:00 +0900

현대 웹 개발에서 다크 모드(Dark Mode) 지원은 단순한 ‘있으면 좋은 기능(Nice to have)‘에서 사용자 경험(UX)을 향상시키기 위한 ‘필수 요건(Must have)‘으로 변화하고 있습니다. 특히 블로그나 문서 사이트처럼 장시간 텍스트 읽기를 전제로 하는 미디어에서는 사용자의 눈의 피로를 덜어주고 기기의 배터리 소모를 줄이는 효과가 있기 때문에, 다크 모드 지원의 중요성은 매우 높다고 할 수 있습니다.

본 기사에서는 블로그의 다크 모드 지원에 있어 피할 수 없는 기술적인 과제와 유지보수성이 높은 CSS 설계의 핵심을 프런트엔드 엔지니어의 관점에서 매우 깊이 파고들어 해설합니다. CSS Custom Properties(CSS 변수)의 활용, FOUC(Flash of Unstyled Content)를 방지하기 위한 고급 JavaScript 제어와 SSR 연동, 접근성(WCAG 2.1 AAA)을 보장하기 위한 색채 설계(RGB, HSL, 그리고 최신 OKLCH), 나아가 Tailwind CSS를 활용한 실전 코드 예시까지 다크 모드 구현의 모든 것을 망라합니다.

1. CSS Custom Properties(CSS 변수)를 이용한 테마 설계의 기초

다크 모드를 구현하는 데 있어 현재 가장 표준적이고 강력한 방법이 CSS Custom Properties(CSS 변수) 를 이용한 접근법입니다. Sass 같은 CSS 전처리기의 변수($color)가 컴파일 시점에 정적으로 해결되는 반면, CSS 변수는 브라우저의 런타임에서 동적으로 해결 및 덮어쓰기 됩니다. 이를 통해 JavaScript에서 클래스를 전환하는 것만으로 페이지 전체의 색조를 순식간에 변경하는 것이 가능해집니다.

1.1 기본적인 컬러 테마 정의

먼저, :root 가상 클래스를 사용하여 라이트 모드(기본값)의 컬러 팔레트를 정의합니다. 그리고 [data-theme='dark']와 같은 속성(또는 .dark 클래스)이 부여되었을 때, 해당 변수들을 덮어쓰는 설계 패턴이 정석입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* 라이트 모드(기본값)의 변수 정의 */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* 다크 모드 시의 변수 덮어쓰기 */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* 실제 적용 */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

이렇게 레이아웃이나 타이포그래피 지정과 색상(테마) 지정을 완전히 분리함으로써 CSS의 유지보수성은 비약적으로 향상됩니다.

1.2 @media (prefers-color-scheme: dark) 의 활용

OS 레벨에서 다크 모드가 설정된 경우, 웹사이트 첫 방문 시부터 자동으로 다크 테마를 적용하는 것이 UX 관점에서 바람직합니다. 이를 실현하는 것이 @media (prefers-color-scheme: dark) 라는 미디어 쿼리입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* OS의 환경 설정이 다크 모드인 경우의 폴백 */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

이 표기법에서는 사용자가 명시적으로 라이트 모드를 선택(data-theme='light')하지 않는 한, OS의 다크 모드 설정을 존중하여 변수를 덮어씁니다.

2. 색 공간의 이해와 접근성(WCAG 2.1 AAA)

다크 모드의 색채 설계에서 단순히 ‘배경을 검게, 글자를 하얗게’ 하는 것만으로는 불충분합니다. 대비가 너무 강하면 헐레이션이 일어나 오히려 읽기 힘들어지고, 대비가 너무 낮으면 시인성이 떨어집니다. Web Content Accessibility Guidelines (WCAG)에서는 시인성을 확보하기 위한 대비율(명암비)이 엄격하게 정의되어 있습니다.

2.1 WCAG 대비율 계산식

WCAG에서의 대비율(Contrast Ratio) $CR$ 은 배경색과 전경색의 상대 휘도(Relative Luminance)를 이용하여 다음과 같이 정의됩니다.

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

여기서 $L_{lighter}$는 밝은 쪽 색의 상대 휘도, $L_{darker}$는 어두운 쪽 색의 상대 휘도입니다(값의 범위는 0.0부터 1.0까지). WCAG 2.1의 레벨 AAA를 달성하기 위해서는 일반 텍스트에서 7:1 이상, 큰 텍스트에서 4.5:1 이상의 대비율이 요구됩니다.

상대 휘도 $L$ 은 sRGB 색 공간의 RGB 값으로부터 아래의 복잡한 수식으로 계산됩니다.

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

각 성분($R, G, B$)은 원래의 8비트 값($R_{sRGB}$)을 255로 나눈 정규화 값을 사용하여 감마 보정을 풀기 위한 다음 변환을 수행합니다.

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

이 계산을 수동으로 하는 것은 어렵지만, 색채 설계 도구를 활용하면 대비율이 7:1 ($CR \ge 7.0$)을 만족하는 색을 기계적으로 선정할 수 있습니다.

2.2 HSL vs RGB vs OKLCH

컬러 팔레트를 만들 때, 예전에는 RGB나 HSL이 주류였습니다. 하지만 이것들에는 ‘지각적 균일성’이라는 관점에서 큰 결함이 있습니다.

RGB: 기계적인 빛의 삼원색이며, 사람이 직관적으로 ‘밝게 한다’, ‘어둡게 한다’와 같은 조정을 하기가 어렵습니다.
HSL: 색상(Hue), 채도(Saturation), 명도(Lightness)를 사용하지만, HSL의 ‘명도(L)‘는 사람 눈의 지각적인 밝기와 일치하지 않습니다. 예를 들어 HSL에서 명도 50%인 순수한 노란색과 순수한 파란색은 수치상으로는 같은 밝기지만, 사람의 눈에는 노란색이 압도적으로 밝게 보입니다.
OKLCH: 최근 CSS Color Module Level 4에서 도입된 최신 색 공간입니다. Lightness(지각적 명도), Chroma(채도), Hue(색상)로 구성되어 있으며, **인간의 시각 특성과 완전히 일치(지각적 균일)**합니다.

OKLCH를 사용하면 색상(Hue)을 변경해도 동일한 지각적 명도(Lightness)를 유지할 수 있기 때문에 다크 모드용 컬러 팔레트 생성이 극도로 예측 가능하고 안전해집니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* OKLCH를 사용한 CSS 변수의 정의 예 */
:root {
 /* 라이트 모드의 기본 명도를 높게, 채도를 억제하여 */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* 다크 모드에서는 명도를 반전시키는 것만으로, 지각적 대비를 유지하기 쉬움 */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* 다크 모드용으로 조금 밝게 하여 시인성을 확보 */
}

이와 같이 OKLCH를 도입함으로써 여러 테마 간에 일관된 대비율(WCAG AAA 수준)을 보장하는 로직을 심플하게 구축할 수 있습니다.

3. FOUC(Flash of Unstyled Content) 방지와 SSR 하이드레이션

다크 모드 지원에서 개발자를 가장 괴롭히는 것이 FOUC(Flash of Unstyled Content) 라고 불리는 화면 깜빡임 문제입니다.

3.1 클라이언트 사이드 JS를 통한 테마 전환의 함정

React나 Vue 같은 SPA(혹은 SSG를 통한 정적 사이트)에서 사용자의 설정을 localStorage 에 저장하고, JavaScript로 불러와 테마를 전환하는 방식이 일반적입니다. 하지만 이 처리를 React의 useEffect 등에서 수행하면 다음과 같은 문제가 발생합니다.

브라우저가 라이트 모드의 HTML/CSS를 렌더링한다.
JS 번들이 로드되고 실행된다.
localStorage 에서 dark 설정을 읽어온다.
HTML에 dark 클래스가 부여되고 화면이 갑자기 어두워진다 (깜빡임).

3.2 완벽한 FOUC 방지책: Cookie와 SSR의 활용

FOUC를 완전히 방지하고 하이드레이션 오류를 막기 위한 모범 사례는 사용자의 테마 설정을 document.cookie 에 저장하고, 서버 사이드 렌더링(SSR) 단계에서 적절한 클래스를 부여한 HTML을 반환 하는 것입니다.

아래 시퀀스 다이어그램은 Cookie를 이용한 테마 초기화의 이상적인 흐름을 보여줍니다.

sequenceDiagram
participant User as "사용자"
participant Browser as "브라우저 OS"
participant Server as "서버 SSR"
participant DOM as "클라이언트 DOM"
User->>Browser: "페이지 요청"
Browser->>Server: "Cookie를 포함한 GET 요청 (theme=dark)"
Server-->>Browser: "<html data-theme='dark'>가 포함된 HTML 반환"
Browser->>DOM: "초기 HTML 렌더링 (FOUC 없음)"
DOM->>DOM: "하이드레이션 스크립트 실행"
alt "Cookie 없음 (첫 방문)"
DOM->>Browser: "OS prefers-color-scheme 확인"
Browser-->>DOM: "matchMedia 결과 (예: dark)"
DOM->>DOM: "인라인 차단 스크립트를 통한 data-theme='dark' 설정"
end

3.3 인라인 스크립트를 통한 방어선(Cookie를 사용할 수 없는 정적 사이트의 경우)

SSG(정적 사이트 생성)만 지원되어 SSR이 불가능한 블로그(Hugo나 Gatsby, Astro의 정적 익스포트 등)의 경우, <head> 태그 내부에 렌더링을 차단하며 실행되는 인라인 JavaScript를 배치하고 DOM이 렌더링 되기 직전에 클래스를 부여하는 방식이 필수적입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- <head> 안의 마지막에 배치한다 -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

이 작은 스크립트는 브라우저의 렌더링을 차단하고 즉시 실행되기 때문에 화면이 렌더링 되는 시점에는 이미 data-theme 속성이 설정되어 있어 화면 깜빡임(FOUC)을 완벽하게 방지할 수 있습니다.

4. Tailwind CSS 와 순수 SCSS/CSS에서의 구현 접근법

다크 모드를 실제 프로젝트에 통합할 때, 각 도구별 접근 방식을 이해해 둘 필요가 있습니다.

4.1 Tailwind CSS 에서의 다크 모드

Tailwind CSS 는 기본적으로 dark: 변형(variant)을 제공하고 있어 매우 쉽게 다크 모드를 구현할 수 있습니다. 설정 파일(tailwind.config.js)에서 darkMode 속성을 설정합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (OS 설정 의존) 또는 'class' (수동 전환 가능)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* CSS 변수를 이용하여 Tailwind의 컬러 팔레트를 확장 */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

HTML 측에서는 아래와 같이 클래스를 부여하기만 하면 됩니다.

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hello World</h1>
 <p class="mt-2">Tailwind makes dark mode incredibly easy.</p>
</div>

하지만 모든 요소에 dark:bg-xxx 라고 작성하는 것은 컴포넌트가 비대해지는 원인이 되기도 합니다. 대규모 블로그나 앱에서는 CSS 변수를 기반으로 하고 Tailwind에서는 그 CSS 변수를 참조하는 하이브리드 설계(시맨틱 컬러 설계)가 권장됩니다.

아래는 CSS 변수의 상속과 적용 계층을 보여주는 클래스 다이어그램입니다.

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "유틸리티 클래스 적용"

4.2 Raw SCSS/CSS 에서의 구현(Mixin 활용)

Tailwind를 사용하지 않고 자체적으로 SCSS를 작성하는 프로젝트에서는 @mixin 을 활용하여 다크 모드의 스타일을 캡슐화합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* SCSS Mixin 정의 */
@mixin dark-mode {
 /* [data-theme='dark'] 속성, 또는 OS 설정 양쪽을 모두 지원 */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* 사용 예 */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

이 방법은 직관적이지만 컴파일 후의 CSS 파일 크기가 비대해지기 쉽기(미디어 쿼리가 각 선택자마다 복제됨) 때문에, 역시 CSS 변수(Custom Properties)를 중심으로 한 설계로의 전환이 현재의 트렌드입니다.

5. 이미지(Image)와 SVG의 다크 모드 최적화

텍스트와 배경의 색채 설계가 완료되었더라도, 콘텐츠로 배치된 이미지나 아이콘(SVG)이 라이트 모드 그대로라면 다크 모드 시에 너무 눈부시게 떠 보이게 됩니다. 이들에 대한 최적화도 필수적입니다.

5.1 이미지의 밝기를 낮추는 CSS 필터

사진 등의 비트맵 이미지는 다크 모드 시에 그대로 표시하면 너무 눈부실 수 있습니다. CSS의 filter 속성을 사용하여 이미지의 명도(brightness)와 대비(contrast)를 약간 낮춤으로써 다크 테마의 UI에 자연스럽게 녹아들게 할 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* 밝기를 낮추고, 약간 대비를 올림 */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* 호버 시에는 원래 밝기로 되돌림 (사용자가 자세히 보고 싶은 경우) */
 filter: brightness(1) contrast(1);
}

5.2 `<picture>` 태그를 통한 이미지 분기 처리

로고 이미지나 설명용 도해(배경이 흰색으로 고정된 JPEG 등)는 필터 처리만으로는 대응할 수 없습니다. 이 경우 HTML의 <picture> 요소와 미디어 쿼리를 사용하여 다크 모드용의 다른 이미지 파일을 분기 처리하여 보여주는 것이 정답입니다.

1
2
3
4
5
6


<picture>
 <!-- 다크 모드 OS 설정의 사용자에게는 이곳을 표시 -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- 기본(라이트 모드) -->
 <img src="/img/logo-light.png" alt="사이트 로고">
</picture>

※단, 이 방법은 localStorage 등을 통한 수동 토글과는 연동되지 않기(OS 설정에만 의존) 때문에, 수동 전환을 구현한 경우에는 JS로 이미지의 src를 동적으로 변경하거나 CSS 클래스로 display: none을 전환할 필요가 있습니다.

5.3 SVG 아이콘의 `currentColor` 대응

아이콘 등에 사용하는 인라인 SVG는 칠하기 색상을 부모 요소의 텍스트 컬러와 연동시키는 가장 스마트한 방법입니다. SVG의 fill 이나 stroke 속성에 currentColor 를 지정합니다.

1
2
3
4


<!-- CSS의 color 속성 값(var(--text-primary) 등)이 자동으로 적용된다 -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

이를 통해 다크 모드로 전환되어 부모 요소의 글자색이 흰색 계통이 되면, SVG 아이콘도 자동으로 흰색 계통으로 변합니다.

6. 요약: 지속 가능한 다크 모드 설계를 향해

블로그나 웹 애플리케이션에서 고품질의 다크 모드를 구현하기 위해서는 아래의 포인트를 망라한 CSS 설계가 필수적입니다.

CSS Custom Properties 활용하기: 색상 지정의 하드코딩을 피하고, 시맨틱한 변수명(예: --bg-primary)으로 추상화한다.
OKLCH 색 공간 채택하기: WCAG 2.1 AAA를 만족하는 접근성 높은 대비율(7:1 이상)을 지각적으로 균일한 색 공간에서 논리적으로 설계한다.
FOUC 대책 철저히 하기: SSR과 Cookie의 연동, 혹은 <head> 내의 렌더링 차단 인라인 스크립트를 통해 초기 로드 시의 화면 깜빡임을 완전히 배제한다.
미디어와 자산의 최적화: filter: brightness() 나 currentColor, <picture> 태그를 구사하여 텍스트 이외의 요소도 다크 테마와 조화시킨다.

단순한 ‘색상 반전’을 넘어서는 이러한 세심한 배려야말로 사용자에게 오랫동안 사랑받고 눈이 피로하지 않은 훌륭한 독서 경험(리딩 익스피리언스)을 제공하는 모던 블로그의 조건이라 할 수 있겠습니다. 앞으로 다크 모드를 도입할 개발자 분들은 꼭 이 글의 설계 패턴을 참고해 보시기 바랍니다.