🎛️ Tailwind 9장: 테마 커스터마이징

2026년 3월 5일 수정됨

📋 개요

@theme 디렉티브와 디자인 토큰 — 브랜드 컬러, 폰트, 커스텀 스케일을 Tailwind 시스템에 통합하기

📋 목차

📌 이 문서를 읽기 전에
🤔 왜 알아야 하는가
🏗️ 비유로 먼저 이해하기
⚙️ @theme 디렉티브로 테마 정의
🎨 커스텀 색상 추가
✍️ 커스텀 폰트 추가
📐 커스텀 Breakpoint 추가
💻 실전: 영수네 커뮤니티 디자인 시스템 구축
🏁 이번에 배운 내용 총정리
📝 마무리 퀴즈
🐣 영철이의 퇴근 일기
🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분

🎯 이 문서를 다 읽으면 할 수 있는 것

@theme 디렉티브로 커스텀 색상, 폰트, 간격을 Tailwind 에 통합할 수 있다
브랜드 컬러를 bg-brand-500, text-brand-600 처럼 사용할 수 있다
디자인 토큰과 Tailwind 클래스 시스템을 연결하는 구조를 설계할 수 있다

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

🎨 영숙 (디자이너): "영철 님, 우리 서비스 브랜드 색상이 #4F46E5 (인디고) 인데, 이걸 Tailwind 에 추가할 수 있나요? 매번 bg-[#4F46E5] 쓰기 너무 불편해요."
🐣 영철: "커스텀 색상이요? 설정 파일 어딘가에서..."
🦁 영호 (리드): "CSS 파일에 @theme 블록 추가하면 돼요. 그러면 bg-brand-500 같은 클래스로 쓸 수 있어요."
🎨 영숙: "그럼 나중에 브랜드 색상 바뀌어도 한 곳만 수정하면 되겠네요!"
🦁 영호: "바로 그게 디자인 토큰의 핵심이에요."

🤔 왜 알아야 하는가

Tailwind 기본 팔레트는 범용적이야. 하지만 실제 프로젝트에는 브랜드 고유의 색상, 폰트, 간격 규칙이 있어.

영수네 커뮤니티가 성장하면서:

브랜드 컬러 (#4F46E5) 를 50개 파일에 bg-[#4F46E5] 로 하드코딩
나중에 브랜드 컬러가 #7C3AED 로 변경 → 50개 파일 수동 수정
하나라도 놓치면 화면이 얼룩덜룩

이걸 방지하는 것이 바로 디자인 토큰 + @theme 통합이야.

🏗️ 비유로 먼저 이해하기

@theme = 중앙 통제소

군대의 중앙 통제소에서 "오늘부터 군복 색깔은 카키 대신 올리브야" 라고 명령하면 모든 부대가 동시에 바뀌어. @theme 에서 --color-brand-500: #4F46E5 를 --color-brand-500: #7C3AED 로 바꾸면, bg-brand-500 을 쓰는 모든 곳이 동시에 변경돼.

💡 한 줄로 기억하기
@theme 는 Tailwind 가 이해하는 CSS 변수 저장소. 여기서 변수를 바꾸면 해당 토큰을 쓰는 클래스 전체가 바뀐다.

⚙️ @theme 디렉티브로 테마 정의

🎯 이 섹션을 읽고 나면:

@theme 가 CSS 변수(Custom Properties)와 어떻게 연결되는지 원리를 이해할 수 있다

Tailwind v4 (CSS 기반) 와 v3 (JS 설정 파일) 방식의 차이와 선택 기준을 알 수 있다

커스텀 토큰이 bg-brand-500 같은 클래스로 어떻게 변환되는지 머릿속에 그릴 수 있다

영숙이 Figma 디자인 파일을 넘기며 이렇게 말했어: "영철 님, 이번 주 중으로 우리 브랜드 색상 #4F46E5 가 들어간 버튼이랑 배지 컴포넌트 완성해줄 수 있어요?"

영철이가 처음에 한 것: 컴포넌트마다 bg-[#4F46E5] 를 직접 타이핑. 그런데 이틀 후 영수 님이 "경쟁사 조사 결과 보라색 계열로 바꾸자고 하네요. 색상 #7C3AED 로 업데이트해주세요." 라고 슬랙을 날렸어.

영철이: "...34개 파일에서 #4F46E5 를 찾아서 바꿔야 한다고요?"

🦁 영호: "그래서 디자인 토큰을 @theme 에 한 곳에 모아야 하는 거예요. @theme 는 Tailwind 가 CSS 변수를 클래스로 변환해주는 중앙 창고 에요. 창고에서 바꾸면 전체가 바뀌어요."

Tailwind v4 방식 (CSS 기반 — 권장)

Tailwind v4 는 자바스크립트 설정 파일 없이, CSS 파일 안의 @theme 블록에서 모든 테마를 정의해. 브라우저가 이해하는 CSS 변수를 직접 써서 런타임에도 접근할 수 있는 게 장점이야.

/* app/globals.css */
@import "tailwindcss";
 
/* 🦁 영호: "@theme 안의 변수들이 bg-brand-500, font-sans 같은 유틸리티 클래스로 자동 변환돼요. */
/*           네이밍 규칙은 --{카테고리}-{이름}: 값 형태예요." */
@theme {
  /* 색상 토큰: --color-{이름} → bg-{이름}, text-{이름}, border-{이름} 클래스 생성 */
  --color-brand-50:  oklch(0.97 0.02 270);  /* 가장 밝은 색 */
  --color-brand-100: oklch(0.93 0.05 270);
  --color-brand-200: oklch(0.86 0.10 270);
  --color-brand-300: oklch(0.78 0.15 270);
  --color-brand-400: oklch(0.68 0.20 270);
  --color-brand-500: oklch(0.58 0.24 270);  /* 🎨 영숙이 요청한 메인 브랜드 색 */
  --color-brand-600: oklch(0.50 0.22 270);  /* hover 시 사용 */
  --color-brand-700: oklch(0.42 0.20 270);
  --color-brand-800: oklch(0.34 0.17 270);
  --color-brand-900: oklch(0.27 0.13 270);  /* 가장 어두운 색 */
 
  /* 폰트 토큰: --font-{이름} → font-{이름} 클래스 생성 */
  --font-sans: 'Pretendard', 'Noto Sans KR', sans-serif;
  --font-display: 'Noto Serif KR', Georgia, serif;
 
  /* 커스텀 breakpoint: --breakpoint-{이름} → {이름}: 반응형 prefix 생성 */
  --breakpoint-xs: 480px;   /* xs:flex 처럼 사용 가능 */
  --breakpoint-3xl: 1920px; /* 초대형 모니터 대응 */
 
  /* 커스텀 spacing: --spacing-{이름} → pt-{이름}, mt-{이름} 등 생성 */
  --spacing-18: 4.5rem;    /* 72px — 8의 배수가 아닌 커스텀 값 */
  --spacing-22: 5.5rem;    /* 88px */
}

이제 @theme 에 정의한 토큰들이 Tailwind 유틸리티 클래스로 그대로 사용 가능해:

<!-- bg-brand-500, text-brand-600 이제 사용 가능! -->
<div class="bg-brand-500 text-white hover:bg-brand-600">브랜드 버튼</div>
<p class="font-display text-2xl">브랜드 폰트 제목</p>
<div class="pt-18">커스텀 간격 72px</div>
<div class="xs:flex hidden">480px 이상에서만 flex</div>

나중에 브랜드 컬러가 바뀌어도? @theme 의 --color-brand-500 한 줄만 수정하면 프로젝트 전체에 반영돼.

Tailwind v3 방식 (tailwind.config.js)

Next.js 프로젝트가 아직 v3 를 사용한다면 JS 설정 파일에서 테마를 확장해. extend 키를 통해 기존 팔레트를 유지하면서 커스텀 토큰을 추가하는 방식이야.

🦁 영호: "중요한 포인트가 있어요. theme.extend 에 넣으면 기존 Tailwind 색상을 유지하면서 추가돼요. 하지만 theme 에 바로 colors 를 넣으면 기존 팔레트가 전부 날아가요. extend 를 빼먹으면 text-gray-500 같은 기본 클래스도 없어져요."

// tailwind.config.js
const { fontFamily } = require('tailwindcss/defaultTheme');
 
module.exports = {
  theme: {
    extend: {
      // ✅ extend 안에 넣어야 기존 팔레트 유지!
      colors: {
        brand: {
          50:  '#eef2ff',
          100: '#e0e7ff',
          200: '#c7d2fe',
          300: '#a5b4fc',
          400: '#818cf8',
          500: '#6366f1',  // 메인 브랜드 색
          600: '#4f46e5',
          700: '#4338ca',
          800: '#3730a3',
          900: '#312e81',
          950: '#1e1b4b',
        },
      },
      fontFamily: {
        // 기존 sans 폰트 스택 앞에 Pretendard 추가 (fallback 유지)
        sans: ['Pretendard', ...fontFamily.sans],
        display: ['Noto Serif KR', 'Georgia', 'serif'],
      },
      screens: {
        xs: '480px',     // 추가 breakpoint
        '3xl': '1920px', // 초대형 화면
      },
    },
  },
};

항목	v4 (`@theme` in CSS)	v3 (`tailwind.config.js`)
설정 위치	CSS 파일 안	JS 설정 파일
런타임 접근	✅ CSS 변수로 JS에서도 접근 가능	❌ 빌드 타임에만 클래스 생성
색상 포맷	oklch, hsl, rgb 모두	주로 hex, hsl
권장	✅ 신규 프로젝트	기존 v3 프로젝트 유지 보수

🎨 커스텀 색상 추가

브랜드 컬러 전체 스케일 추가

/* globals.css — @theme 방식 */
@theme {
  /* oklch: 최신 색상 형식, 더 정확한 색상 표현 */
  --color-brand-50:  #f5f3ff;
  --color-brand-100: #ede9fe;
  --color-brand-200: #ddd6fe;
  --color-brand-300: #c4b5fd;
  --color-brand-400: #a78bfa;
  --color-brand-500: #8b5cf6;
  --color-brand-600: #7c3aed;
  --color-brand-700: #6d28d9;
  --color-brand-800: #5b21b6;
  --color-brand-900: #4c1d95;
  --color-brand-950: #2e1065;
 
  /* 시맨틱 색상 (역할 기반 이름) */
  --color-success-500: #22c55e;
  --color-warning-500: #f59e0b;
  --color-danger-500:  #ef4444;
  --color-info-500:    #3b82f6;
}

// 사용 예
function AlertBanner({ type, message }: Props) {
  const styles = {
    success: 'bg-success-50 border-success-200 text-success-700',
    warning: 'bg-warning-50 border-warning-200 text-warning-700',
    danger:  'bg-danger-50  border-danger-200  text-danger-700',
    info:    'bg-info-50    border-info-200    text-info-700',
  };
 
  return (
    <div className={`rounded-lg border p-4 ${styles[type]}`}>
      {message}
    </div>
  );
}

✍️ 커스텀 폰트 추가

한국어 폰트 (Pretendard) 적용

/* globals.css */
 
/* 1. 폰트 import (Google Fonts 또는 CDN) */
@import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard/dist/web/variable/pretendardvariable.css');
 
@import "tailwindcss";
 
@theme {
  /* 2. @theme 에 폰트 등록 */
  --font-sans: 'Pretendard Variable', 'Pretendard', -apple-system,
               BlinkMacSystemFont, system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;
}

// 3. body 에 기본 폰트 적용
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      {/* font-sans: --font-sans 에 등록한 Pretendard 가 적용됨 */}
      <body className="font-sans antialiased">
        {children}
      </body>
    </html>
  );
}

Next.js next/font 와 통합 (권장)

// app/layout.tsx
import { Inter, Noto_Sans_KR } from 'next/font/google';
 
const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
});
 
const notoSansKr = Noto_Sans_KR({
  subsets: ['latin'],
  weight: ['400', '500', '700'],
  variable: '--font-noto-sans-kr',
});
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko" className={`${inter.variable} ${notoSansKr.variable}`}>
      <body className="font-sans">
        {children}
      </body>
    </html>
  );
}

/* globals.css */
@theme {
  --font-sans: var(--font-noto-sans-kr), var(--font-inter), sans-serif;
}

📐 커스텀 Breakpoint 추가

@theme {
  /* 영수네 커뮤니티의 커스텀 breakpoint */
  --breakpoint-xs: 30rem;     /* 480px — 큰 스마트폰 */
  --breakpoint-3xl: 120rem;   /* 1920px — 4K 모니터 */
 
  /* 기존 breakpoint 재정의 (신중히!) */
  /* --breakpoint-md: 48rem; */  /* 기본 768px 유지 */
}

<!-- 커스텀 breakpoint 사용 -->
<div class="grid grid-cols-1 xs:grid-cols-2 md:grid-cols-3 3xl:grid-cols-4">

💻 실전: 영수네 커뮤니티 디자인 시스템 구축

/* app/globals.css — 영수네 커뮤니티 전체 디자인 시스템 */
@import "tailwindcss";
 
@theme {
  /* ===== 브랜드 색상 ===== */
  --color-brand-50:  #f5f3ff;
  --color-brand-100: #ede9fe;
  --color-brand-200: #ddd6fe;
  --color-brand-300: #c4b5fd;
  --color-brand-400: #a78bfa;
  --color-brand-500: #8b5cf6;
  --color-brand-600: #7c3aed;  /* 주요 버튼, 링크 */
  --color-brand-700: #6d28d9;
  --color-brand-800: #5b21b6;
  --color-brand-900: #4c1d95;
 
  /* ===== 시맨틱 색상 ===== */
  --color-success: #16a34a;
  --color-warning: #d97706;
  --color-danger:  #dc2626;
  --color-info:    #2563eb;
 
  /* ===== 폰트 ===== */
  --font-sans: 'Pretendard Variable', -apple-system, sans-serif;
 
  /* ===== 커스텀 Breakpoint ===== */
  --breakpoint-xs: 30rem;
 
  /* ===== 커스텀 Spacing ===== */
  --spacing-18: 4.5rem;
 
  /* ===== 커스텀 Border Radius ===== */
  --radius-2xl: 1rem;
  --radius-3xl: 1.5rem;
 
  /* ===== 커스텀 Box Shadow ===== */
  --shadow-card: 0 2px 8px -2px rgb(0 0 0 / 0.1), 0 4px 12px -4px rgb(0 0 0 / 0.1);
}

// 디자인 토큰 기반 버튼 컴포넌트
type ButtonVariant = 'primary' | 'secondary' | 'danger';
 
const variantClass: Record<ButtonVariant, string> = {
  primary:   'bg-brand-600 text-white hover:bg-brand-700 focus-visible:ring-brand-500',
  secondary: 'bg-brand-50 text-brand-700 hover:bg-brand-100 focus-visible:ring-brand-300',
  danger:    'bg-red-600 text-white hover:bg-red-700 focus-visible:ring-red-500',
};
 
function Button({ variant = 'primary', children, ...props }: Props) {
  return (
    <button
      className={`
        rounded-xl px-6 py-3 font-semibold text-sm
        transition-all duration-200 ease-out
        focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2
        active:scale-95
        disabled:cursor-not-allowed disabled:opacity-50
        ${variantClass[variant]}
      `}
      {...props}
    >
      {children}
    </button>
  );
}

🏁 이번에 배운 내용 총정리

개념	방법	결과
커스텀 색상	`@theme { --color-brand-500: ... }`	`bg-brand-500` 사용 가능
커스텀 폰트	`@theme { --font-sans: ... }`	`font-sans` 에 적용
커스텀 Breakpoint	`@theme { --breakpoint-xs: 30rem }`	`xs:` 접두사 사용 가능
시맨틱 색상	`--color-success`, `--color-danger`	역할 기반 이름
디자인 토큰	`@theme` 한 곳에서 관리	전역 변경 용이

📝 마무리 퀴즈

Q1. 영숙이 브랜드 색상을 #8B5CF6 으로 정했다. 이를 Tailwind 에서 bg-brand-500, text-brand-600 처럼 사용하려면 어디에 무엇을 추가해야 하는가?

✅ 정답: CSS 파일의 @theme 블록에 --color-brand-500: #8b5cf6; 과 전체 스케일(50~950)을 정의한다.

💡 상세 해설:

@theme 에서 --color-{name}-{scale}: 형식으로 정의하면 Tailwind 가 자동으로 bg-{name}-{scale}, text-{name}-{scale}, border-{name}-{scale} 등 모든 색상 유틸리티를 생성해.
단 하나의 값(500)만 추가해도 사용은 되지만, 보통 전체 스케일을 정의해야 밝음/어두움 변형을 자유롭게 쓸 수 있어.
📌 핵심 기억법: "@theme { --color-name-scale: value; } → Tailwind 가 나머지 클래스를 자동 생성."

Q2. tailwind.config.js 에서 theme.colors 와 theme.extend.colors 의 차이는?

✅ 정답: theme.colors 는 기존 Tailwind 색상 팔레트 전체를 교체하고, theme.extend.colors 는 기존 팔레트를 유지하면서 새 색상을 추가한다.

💡 상세 해설:

theme.colors: { brand: {...} } 를 설정하면 기존의 blue, gray, red 등 모든 내장 색상이 사라지고 brand 만 남아.
theme.extend.colors: { brand: {...} } 는 기존 색상은 그대로 유지하면서 brand 색상을 추가해. 실무에서는 거의 항상 extend 를 사용해야 해.
📌 핵심 기억법: "교체 = theme.colors, 추가 = theme.extend.colors. 실무는 항상 extend."

Q3. 영수네 커뮤니티가 성장해서 480px (xs) breakpoint 가 필요해졌다. Tailwind v4 에서 추가하는 방법은?

✅ 정답: globals.css 의 @theme 블록에 --breakpoint-xs: 30rem; 을 추가한다. (480px ÷ 16 = 30rem)

💡 상세 해설:

Tailwind v4 에서 breakpoint 는 --breakpoint-{name}: {value} 형식으로 @theme 에 추가해.
30rem = 480px (1rem = 16px 기준).
추가 후 xs:grid-cols-2 처럼 xs: 접두사를 사용할 수 있어.
Tailwind v3 에서는 tailwind.config.js 의 theme.extend.screens: { xs: '480px' } 로 추가해.
📌 핵심 기억법: "v4 = @theme CSS, v3 = tailwind.config.js. 단위는 rem(16 나누기)."

🐣 영철이의 퇴근 일기

오늘 @theme 블록 하나로 영수네 커뮤니티 전체 디자인 시스템 기초를 잡았다. 영숙 님이 피그마에서 브랜드 색상 팔레트 뽑아줬고, 그걸 CSS 변수로 등록했더니 bg-brand-600 같은 클래스가 생겨났다.

영호 님이 "디자인 토큰은 디자이너와 개발자 사이의 공통 언어예요. brand-600 이라고 하면 둘 다 같은 색을 떠올려야 해요" 라고 하셨는데, 그게 정말 맞는 말 같다.

💡 오늘의 교훈: "디자인 토큰 하나를 잘 정의하면, 그걸 참조하는 수백 줄의 코드가 한 번에 바뀐다. 이게 유지보수의 본질이다."

오늘 일 마치고 영호 님이랑 편의점 맥주 한 잔 했다. 가끔 이렇게 편하게 얘기하면서 배우는 게 공식 문서보다 더 많이 남는 것 같다. 좋은 팀 만났다는 생각이 새삼 든다. 🍺

🎛️ Tailwind 9장: 테마 커스터마이징

📋 목차

📌 이 문서를 읽기 전에

🤔 왜 알아야 하는가

🏗️ 비유로 먼저 이해하기

⚙️ @theme 디렉티브로 테마 정의

Tailwind v4 방식 (CSS 기반 — 권장)

Tailwind v3 방식 (tailwind.config.js)

🎨 커스텀 색상 추가

브랜드 컬러 전체 스케일 추가

✍️ 커스텀 폰트 추가

한국어 폰트 (Pretendard) 적용

Next.js next/font 와 통합 (권장)

📐 커스텀 Breakpoint 추가

💻 실전: 영수네 커뮤니티 디자인 시스템 구축

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

🐣 영철이의 퇴근 일기

🔗 더 알아보기