Tailwind CSS @theme 사용법: 변수와 디자인 토큰 구분하기

• Tailwind 클래스를 쓰다 보면 기준이 흩어지는 순간
• Design Token은 예쁜 변수명이 아니라 반복 기준이다
• Tailwind v4에서 Theme Variables가 하는 일
• @theme와 :root는 언제 나눠야 할까
• 디자인 토큰을 너무 많이 만들면 생기는 문제
• 작은 프로젝트에서 시작하는 토큰 정리 순서
• 정리: 토큰은 클래스를 줄이는 도구가 아니라 수정 기준을 남기는 도구다

Tailwind 클래스를 쓰다 보면 기준이 흩어지는 순간

Tailwind를 처음 사용할 때는 기본 유틸리티만으로도 화면이 빠르게 잡힙니다. 버튼은 글자는 카드는 간격은 처럼 바로 붙이면 됩니다. 한두 개의 화면을 만드는 단계에서는 이 방식이 가장 단순합니다.

문제는 비슷한 UI가 여러 화면에 퍼진 뒤에 드러납니다. 상품 카드에서는 을 쓰고, 관리자 카드에서는 을 쓰고, 모달에서는 를 쓰기 시작합니다. 버튼도 어떤 곳은 어떤 곳은 또 다른 곳은 으로 갈라집니다. 각각은 틀린 코드가 아니지만, 나중에 브랜드 색상을 바꾸거나 카드 스타일을 통일하려고 하면 기준이 어디에 있었는지 찾기 어려워집니다.

이 지점에서 Design Token이 필요해집니다. 토큰은 클래스를 짧게 줄이는 장치가 아니라, 프로젝트 안에서 반복되는 시각적 결정을 이름으로 남기는 기준입니다. Tailwind v4에서는 이 기준을 CSS 안의 로 정의할 수 있습니다.

처음에는 문제가 없어 보이는 코드

<button class="rounded-xl bg-blue-600 px-4 py-2 text-sm font-semibold text-white shadow-sm hover:bg-blue-700"> 저장하기
</button> <article class="rounded-xl border border-gray-200 bg-white p-5 shadow-sm"> <h3 class="text-lg font-bold text-gray-900">상품명</h3> <p class="mt-2 text-sm text-gray-600">상품 설명이 들어갑니다.</p>
</article>

이 코드는 그대로 써도 화면은 나옵니다. 다만 이 브랜드의 대표 색상인지, 해당 버튼에서만 잠깐 고른 색인지 코드만 보고 구분하기 어렵습니다. 도 마찬가지입니다. 카드의 표준 radius인지, 해당 컴포넌트에서만 쓰는 임시 값인지 판단하려면 다른 파일까지 뒤져야 합니다.

Design Token은 예쁜 변수명이 아니라 반복 기준이다

Design Token을 처음 보면같은 이름을 붙이는 작업처럼 보입니다. 하지만 이름만 바꾼다고 토큰이 되는 것은 아닙니다. 토큰의 역할은 “이 프로젝트에서 이 값은 어떤 의미로 반복되는가”를 코드에 남기는 것입니다.

예를 들어 라는 색상이 있다고 해보겠습니다. 이 색상은 단순한 파란색일 수도 있고, 브랜드 대표 색상일 수도 있고, 저장 버튼의 배경색일 수도 있습니다. 셋은 비슷해 보이지만 수정 기준이 다릅니다. 색상 자체가 바뀌는 문제인지, 브랜드 톤이 바뀌는 문제인지, 버튼 컴포넌트의 상태 스타일이 바뀌는 문제인지 분리해서 봐야 합니다.

구분	예시	역할
원시 값		색상 자체
의미 값	,	프로젝트에서 쓰이는 목적
컴포넌트 기준	,	특정 UI 요소의 표준 스타일

작은 프로젝트에서는 이 셋을 모두 엄격하게 나누지 않아도 됩니다. 오히려 처음부터 원시 토큰, 의미 토큰, 컴포넌트 토큰을 모두 만들면 이름만 늘고 실제 작업 속도는 떨어집니다. 먼저 반복되는 값을 찾는 쪽이 낫습니다. 버튼 색상, 카드 radius, 공통 shadow, 대표 font family처럼 여러 화면에서 다시 등장하는 값이 첫 번째 후보입니다.

토큰으로 볼 만한 값

@import "tailwindcss"; @theme { --color-brand-50: #eff6ff; --color-brand-600: #2563eb; --color-brand-700: #1d4ed8; --radius-card: 1rem; --shadow-card: 0 1px 3px rgb(15 23 42 / 0.08);
}

여기서 은 단순한 파란색이 아니라 브랜드 강조색으로 쓰겠다는 결정입니다. 는 카드마다 을 반복해서 붙이는 대신, 카드의 모서리 기준을 따로 남긴 값입니다. 카드 디자인을 조금 더 각지게 바꾸거나 그림자 톤을 낮춰야 할 때, 수정할 위치가 자연스럽게 좁혀집니다.

Tailwind v4에서 Theme Variables가 하는 일

Tailwind v4에서 안에 정의하는 값은 Theme Variables입니다. 모양만 보면 CSS 변수와 비슷합니다. 실제로 CSS 변수처럼 참조할 수도 있습니다. 하지만 Tailwind 입장에서 는 일반 변수보다 더 큰 역할을 합니다.

에 을 정의하면 Tailwind는 이 값을 색상 namespace에 속한 theme variable로 봅니다. 그래서같은 유틸리티를 사용할 수 있게 됩니다. 를 정의하면 처럼 쓸 수 있고를 정의하면 가 됩니다.

로 유틸리티 기준 만들기

@import "tailwindcss"; @theme { --color-brand-600: #2563eb; --color-brand-700: #1d4ed8; --radius-card: 1rem; --shadow-card: 0 1px 3px rgb(15 23 42 / 0.08);
}

<button class="rounded-lg bg-brand-600 px-4 py-2 text-sm font-semibold text-white hover:bg-brand-700"> 저장하기
</button> <article class="rounded-card border border-gray-200 bg-white p-5 shadow-card"> <h3 class="text-lg font-bold text-gray-900">상품명</h3> <p class="mt-2 text-sm text-gray-600">상품 설명이 들어갑니다.</p>
</article>

이렇게 바꾸면 클래스 개수가 크게 줄어드는 것은 아닙니다. 대신 클래스가 가리키는 기준이 달라집니다. 은 “파란색 하나를 골랐다”가 아니라 “이 프로젝트의 브랜드 강조색을 사용한다”는 의미를 갖습니다. 도 단순한 radius 값보다 카드 UI의 표준 모서리 값이라는 흔적을 남깁니다.

namespace를 맞춰야 클래스가 생긴다

Tailwind theme variables는 이름 앞부분의 namespace가 중요합니다. 는 색상 유틸리티와 연결되고는 font family 유틸리티는 글자 크기 유틸리티은 간격과 크기 계열 유틸리티는 border radius 유틸리티와 연결됩니다.

예를 들어 처럼 자유롭게 이름을 지으면 일반 CSS 변수처럼 볼 수는 있어도 Tailwind 색상 유틸리티와 기대한 방식으로 연결되지 않습니다. Tailwind에서 같은 클래스를 만들고 싶다면 처럼 namespace를 맞춰야 합니다.

@theme { --color-brand-600: #2563eb; --font-display: "Pretendard", sans-serif; --text-page-title: 2rem; --radius-card: 1rem; --shadow-panel: 0 8px 24px rgb(15 23 42 / 0.08);
}

위 값들은 각각처럼 사용할 수 있는 기준이 됩니다. 원하는 이름을 아무렇게나 붙이는 것이 아니라, Tailwind가 이해하는 namespace 안에서 프로젝트 전용 이름을 설계하는 방식입니다.

와 :root는 언제 나눠야 할까

와 는 둘 다 CSS 변수처럼 보이기 때문에 헷갈리기 쉽습니다. 기준은 “Tailwind 유틸리티로 사용할 값인가”입니다. 유틸리티 클래스로 쓰고 싶은 값은 에 둡니다. CSS 안에서만 계산하거나 특정 컴포넌트 내부에서만 쓰는 값은 나 선택자 내부 변수로 둬도 충분합니다.

구분	사용하는 경우	예시
	Tailwind 유틸리티 클래스로 쓰고 싶은 값	,
	CSS 안에서만 재사용할 일반 변수	,
컴포넌트 선택자 내부	해당 컴포넌트에서만 필요한 임시 계산값	,

예를 들어 는 레이아웃 계산에는 필요하지만 같은 Tailwind 클래스로 계속 쓸 값이 아닐 수 있습니다. 이런 값까지 전부 에 올리면 theme가 실제 디자인 토큰과 임시 레이아웃 변수로 뒤섞입니다.

@import "tailwindcss"; @theme { --color-brand-600: #2563eb; --radius-card: 1rem; --shadow-card: 0 1px 3px rgb(15 23 42 / 0.08);
} :root { --header-height: 64px; --page-inline-padding: 20px;
} .admin-layout { min-height: calc(100vh - var(--header-height)); padding-inline: var(--page-inline-padding);
}

이 구조에서는 Tailwind 유틸리티로 반복해서 쓰는 디자인 기준은 에 있고, 레이아웃 계산에 필요한 일반 변수는 에 있습니다. 나중에 파일을 다시 볼 때도 “이 값은 클래스 API로 쓰는 값인지, CSS 계산용 값인지” 구분할 수 있습니다.

디자인 토큰을 너무 많이 만들면 생기는 문제

디자인 토큰을 알게 되면 모든 값을 이름 붙이고 싶어질 수 있습니다. 하지만 Tailwind에서는 기본 스케일 자체가 이미 촘촘합니다.같은 값은 많은 프로젝트에서 그대로 써도 무리가 없습니다.

처음부터 spacing 전체를처럼 나누면 오히려 판단해야 할 이름이 늘어납니다. 토큰이 많다고 시스템이 좋아지는 것은 아닙니다. 실제 화면에서 반복되고, 바뀔 가능성이 있고, 프로젝트 안에서 의미가 공유되는 값이 토큰 후보입니다.

토큰화가 애매한 경우

@theme { --spacing-card-small: 0.875rem; --spacing-card-normal: 1rem; --spacing-card-large: 1.125rem; --spacing-card-extra: 1.25rem;
}

이런 값은 이름은 많지만 기준이 선명하지 않습니다.가 실제 화면에서 어떤 차이를 만드는지 설명하기 어렵다면, 기본 spacing scale을 쓰는 쪽이 더 단순합니다. 반대로 섹션 상하 여백처럼 페이지 전체 리듬을 결정하는 값이라면 토큰으로 분리할 이유가 생깁니다.

토큰화할 이유가 선명한 경우

@theme { --spacing-section-y: 5rem; --radius-card: 1rem; --shadow-card: 0 1px 3px rgb(15 23 42 / 0.08); --color-brand-600: #2563eb;
}

이 값들은 화면 전체의 인상에 영향을 줍니다. 브랜드 색상, 카드 모서리, 카드 그림자, 섹션 간격처럼 여러 컴포넌트에서 반복되는 값은 나중에 디자인 톤을 바꿀 때 수정 기준이 됩니다.

작은 프로젝트에서 시작하는 토큰 정리 순서

작은 프로젝트라면 처음부터 완성된 디자인 시스템을 만들 필요는 없습니다. Tailwind의 기본값을 버리고 모든 것을 커스텀하려고 하면, 오히려 Tailwind를 쓰는 장점이 줄어듭니다. 시작 순서는 좁게 잡는 것이 좋습니다.

브랜드 색상부터 분리하기

가장 먼저 분리할 만한 값은 브랜드 색상입니다. 색상은 버튼, 링크, 배지, 활성 상태, 포커스 링 등 여러 곳에 반복됩니다.처럼 실제 색상 이름으로 남겨도 되지만, 프로젝트의 대표 강조색이라면 로 바꾸는 순간 수정 기준이 더 선명해집니다.

@theme { --color-brand-50: #eff6ff; --color-brand-100: #dbeafe; --color-brand-600: #2563eb; --color-brand-700: #1d4ed8;
}

카드와 버튼 기준값 분리하기

카드와 버튼은 대부분의 화면에서 반복됩니다. 특히 관리자 화면이나 쇼핑몰 UI처럼 카드가 여러 개 쌓이는 구조에서는 radius와 shadow가 조금만 달라도 화면이 산만해집니다. 이때처럼 기준을 만들면 컴포넌트가 늘어나도 시각적 리듬이 덜 흔들립니다.

<section class="grid gap-4 md:grid-cols-3"> <article class="rounded-card border border-gray-200 bg-white p-5 shadow-card"> <span class="text-sm font-medium text-brand-600">NEW</span> <h3 class="mt-2 text-lg font-bold text-gray-900">카드 제목</h3> <p class="mt-2 text-sm text-gray-600">반복되는 카드 설명입니다.</p> </article>
</section>

spacing은 무리해서 전부 바꾸지 않기

간격은 토큰화 욕심이 가장 많이 생기는 영역입니다. 하지만 Tailwind의 기본 spacing scale은 유틸리티 중심 작업에 맞게 이미 준비되어 있습니다. 모든을 커스텀 이름으로 바꾸기보다, 섹션 간격이나 레이아웃 최대 폭처럼 반복 기준이 확실한 값부터 분리하는 쪽이 현실적입니다.

공유할 값은 별도 theme 파일로 분리하기

프로젝트가 커져서 웹, 관리자, 랜딩 페이지가 같은 브랜드 기준을 써야 한다면 theme 파일을 분리할 수 있습니다. 이때 를 한 파일에 모아두고 각 진입 CSS에서 import하면 여러 화면이 같은 토큰을 바라보게 됩니다.

@import "tailwindcss";
@import "./theme/brand.css";

처음부터 패키지 구조까지 만들 필요는 없습니다. 다만 브랜드 색상과 카드 기준처럼 여러 화면이 같이 쓰는 값이 생겼다면, 하나의 CSS 파일로 분리해두는 것만으로도 수정 위치가 명확해집니다.

정리: 토큰은 클래스를 줄이는 도구가 아니라 수정 기준을 남기는 도구다

Tailwind의 Theme Variables를 단순히 “CSS 변수처럼 쓰는 기능”으로만 보면 와 차이가 흐려집니다. Tailwind v4의 는 디자인 토큰을 정의하면서, 동시에 어떤 유틸리티 클래스가 프로젝트에 존재할지 정하는 기준입니다.

Design Token은 이름을 많이 만드는 작업이 아닙니다. 버튼 색상, 카드 모서리, 공통 shadow, 대표 폰트처럼 여러 화면에서 반복되고 나중에 바뀔 가능성이 있는 값을 먼저 분리하는 것이 출발점입니다. 반대로 한 컴포넌트 안에서만 쓰는 임시 계산값이나 레이아웃 보조값은 나 컴포넌트 내부 변수로 두는 쪽이 더 단순합니다.

다음에 Tailwind로 UI를 만들 때는 클래스를 줄일 수 있는지보다이 값이 프로젝트의 기준으로 남을 만한지 먼저 확인해야 합니다.같은 이름은 짧아서 쓰는 것이 아니라, 나중에 같은 화면을 다시 고칠 때 기준점으로 돌아오기 위해 남겨두는 이름입니다.

토큰이 실제 유틸리티 클래스와 어떻게 연결되는지 복습하려면 Tailwind CSS 기본 클래스 사용법 글을 함께 참고하면 좋습니다.

참고 자료

Tailwind CSS v4의 theme variables, namespace와의 차이, theme variable 공유 방식은 Tailwind CSS 공식 문서의 Theme variables 설명을 기준으로 정리했습니다.