CSS to Tailwind 변환 가이드: 유틸리티 클래스 매핑과 마이그레이션 전략

커스텀 CSS에서 Tailwind CSS로 마이그레이션하는 것은 현대 프론트엔드 개발에서 가장 흔한 리팩토링 작업 중 하나입니다. 레거시 스타일시트를 변환하든, Figma 디자인을 HTML로 옮기든, 서드파티 컴포넌트를 통합하든, CSS 속성과 Tailwind 유틸리티 클래스의 매핑 관계를 아는 것이 시간을 크게 절약합니다.

CSS를 Tailwind로 즉시 변환 →

Tailwind CSS 동작 원리

Tailwind는 유틸리티 우선(Utility-First) CSS 프레임워크입니다. .card나 .hero-section 같은 의미론적 클래스명 대신, 단일 목적의 유틸리티 클래스를 HTML에 직접 조합합니다:

<!-- 전통적인 CSS 방식 -->
<div class="card">...</div>

<!-- Tailwind 방식 -->
<div class="rounded-lg shadow-md p-6 bg-white border border-gray-200">...</div>

각 유틸리티 클래스는 하나(또는 소수의) CSS 선언에 매핑됩니다. Tailwind 빌드 프로세스가 코드를 스캔하여 실제로 사용된 CSS만 생성합니다.

CSS와 Tailwind 핵심 매핑

스페이싱 (margin, padding)

Tailwind는 기본적으로 1 = 4px(0.25rem)인 숫자 스케일 사용:

CSS	Tailwind
`margin: 0`	`m-0`
`margin: 1rem`	`m-4`
`margin: 2rem`	`m-8`
`margin-top: 1.5rem`	`mt-6`
`margin-left: auto`	`ml-auto`
`padding: 0.5rem`	`p-2`
`padding: 1.25rem`	`p-5`
`padding-left: 2rem`	`pl-8`
`padding-top: 0; padding-bottom: 0`	`py-0`
`padding-left: 1rem; padding-right: 1rem`	`px-4`

약어 패턴: m = margin, p = padding, t/r/b/l = 상/우/하/좌, x = 가로, y = 세로.

사이즈 (width, height)

CSS	Tailwind
`width: 100%`	`w-full`
`width: 50%`	`w-1/2`
`width: 100vw`	`w-screen`
`width: auto`	`w-auto`
`max-width: 64rem`	`max-w-4xl`
`height: 100vh`	`h-screen`
`min-height: 100vh`	`min-h-screen`

타이포그래피

CSS	Tailwind
`font-size: 0.875rem`	`text-sm`
`font-size: 1rem`	`text-base`
`font-size: 1.25rem`	`text-xl`
`font-size: 2.25rem`	`text-4xl`
`font-weight: 400`	`font-normal`
`font-weight: 600`	`font-semibold`
`font-weight: 700`	`font-bold`
`line-height: 1.5`	`leading-normal`
`text-align: center`	`text-center`
`text-transform: uppercase`	`uppercase`
`color: #6b7280`	`text-gray-500`

Flexbox

CSS	Tailwind
`flex-direction: row`	`flex-row`
`flex-direction: column`	`flex-col`
`justify-content: center`	`justify-center`
`justify-content: space-between`	`justify-between`
`align-items: center`	`items-center`
`flex-wrap: wrap`	`flex-wrap`
`gap: 1rem`	`gap-4`
`flex: 1`	`flex-1`

Grid

CSS	Tailwind
`grid-template-columns: repeat(3, 1fr)`	`grid-cols-3`
`grid-column: span 2`	`col-span-2`
`gap: 1.5rem`	`gap-6`

보더와 그림자

CSS	Tailwind
`border: 1px solid`	`border`
`border-radius: 0.25rem`	`rounded`
`border-radius: 0.5rem`	`rounded-lg`
`border-radius: 9999px`	`rounded-full`
`box-shadow: 0 4px 6px rgba(0,0,0,0.1)`	`shadow-md`

임의 값

디자인이 Tailwind 기본 스케일에 없는 값을 사용할 때 대괄호 임의 값 문법 사용:

<!-- Tailwind 임의 값 -->
<div class="w-[327px] pt-[22px] text-[#1a2b3c]">

임의 값은 모든 Tailwind 유틸리티에서 동작합니다: h-[calc(100vh-4rem)], grid-cols-[1fr_2fr_1fr].

반응형 디자인

Tailwind는 모바일 우선 브레이크포인트 접두사 사용:

브레이크포인트	CSS 등가	접두사
모바일 (기본)	모든 너비	(없음)
SM	`@media (min-width: 640px)`	`sm:`
MD	`@media (min-width: 768px)`	`md:`
LG	`@media (min-width: 1024px)`	`lg:`

<!-- Tailwind 반응형 클래스 -->
<h1 class="text-2xl md:text-4xl lg:text-5xl">히어로</h1>

실제 변환 예시

전형적인 카드 컴포넌트:

/* 변환 전: 커스텀 CSS */
.card {
  background-color: #ffffff;
  border-radius: 0.75rem;
  padding: 1.5rem;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.07);
  border: 1px solid #f3f4f6;
}

.card-title {
  font-size: 1.125rem;
  font-weight: 600;
  color: #111827;
  margin-bottom: 0.5rem;
}

<!-- 변환 후: Tailwind -->
<div class="bg-white rounded-xl p-6 shadow-md border border-gray-100">
  <h3 class="text-lg font-semibold text-gray-900 mb-2">제목</h3>
  <p class="text-sm text-gray-500 leading-relaxed">본문 텍스트.</p>
</div>

Tailwind v4 변경 사항

Tailwind v4는 2025년 초에 출시되어 설정 방식이 변경되었습니다.

`tailwind.config.js` 불필요

v4에서는 JavaScript 파일에서 CSS로 설정이 이동했습니다:

/* v4: 메인 CSS 파일 */
@import "tailwindcss";

@theme {
  --color-brand: #1a73e8;
  --spacing-18: 4.5rem;
}

세 가지 @tailwind 지시어(base, components, utilities)가 단일 @import "tailwindcss"로 대체됩니다.

v4 클래스명 변경

v3 클래스	v4 등가	변경 내용
`shadow`	`shadow-sm`	기본 그림자가 더 미묘해짐
`ring`	`ring-3`	기본 링 너비가 1px로 감소

공식 업그레이드 도구

npx @tailwindcss/upgrade

tailwind.config.js를 @theme 블록으로 변환하고 더 이상 사용되지 않는 클래스를 이름 변경합니다. 이후 남은 커스텀 CSS에는 CSS to Tailwind 변환기를 사용하세요.

온라인 CSS to Tailwind 변환기

일회성 변환에는 ZeroTool의 CSS to Tailwind 변환기가 CSS 속성 블록을 실시간으로 Tailwind 등가물로 변환합니다. 왼쪽에 CSS를 붙여 넣으면 오른쪽에 Tailwind 클래스가 출력됩니다——빌드 단계, 설치 불필요.

CSS to Tailwind 변환기 사용해보기 →