Tailwind CSS에서 마이그레이션

Tailwind CSS v4와 Master CSS는 모두 클래스 이름과 CSS 지시문으로 CSS를 생성하지만 그대로 교체할 수는 없습니다. 스타일 구현을 바꾸는 작업으로 다루세요. Tailwind와 함께 Master CSS를 설치하고 라우트나 컴포넌트 그룹을 하나씩 변환합니다. 해당 영역이 빌드되고 의도한 디자인과 일치한 뒤 Tailwind를 제거합니다.

이 가이드는 Tailwind CSS v4의 CSS 우선 워크플로인 @import "tailwindcss", @theme, @utility, @variant, @custom-variant, @source, @apply를 다룹니다. Tailwind 동작은 공식 함수와 지시문, 테마 변수, 소스에서 클래스 감지, 상태와 변형을 확인하세요.

#마이그레이션 전략

에이전트와 작업할 때는 정적 HTML 또는 JSX 컴포넌트 하나, 스타일시트 진입점, 원래 Tailwind 버전을 공식 master-css 스킬에 제공합니다. 모양과 상호작용을 보존하고 남긴 CSS와 Tailwind 의존성을 보고하도록 요청하세요. 스킬은 검토된 절차이며 프로젝트 전체 자동 변환기는 아닙니다.

클래스 이름을 바꾸기 전에 원본에 설치된 Tailwind 도구 체인으로 빌드합니다. 컴파일한 CSS가 실제 값, 변형, 변수 의존성을 제공합니다. 테마나 플러그인 설정이 없는 조각은 해당 문맥을 먼저 파악한 뒤 충실한 변환인지 판단하세요. mastercss_suggest_classes는 독립 선언 블록에만 쓰고 복잡한 선택자와 미해결 동적 표현식은 네이티브 CSS에 둡니다. Master 클래스를 넘기기 전에 tailwind-merge 등 Tailwind 전용 클래스 처리를 확인합니다.

같은 리셋, 글꼴, 테마, 브라우저 상태에서 두 버전을 비교하세요. Tailwind v4의 hover:에는 (hover: hover) 미디어 조건도 필요하므로 의사 클래스만 복사하면 동작이 달라집니다. mastercss_css_compare는 Master 출력끼리 비교합니다. 원본 컴포넌트와 변환 결과의 비교에는 브라우저를 사용하세요.

공존, 기준 캡처, 제거 검사는 공통 마이그레이션 절차를 사용합니다. 첫 작업에서 다음 Tailwind 전용 계약을 확인하세요.

전역 검색·치환은 피하세요. 두 시스템은 리셋, 스케일, ring 모델, 지시문 계약이 다릅니다. 같은 키워드도 다른 작업을 의미할 수 있습니다.

Tailwind 유틸리티 목록은 Master CSS 믹스인 이름이 아닙니다. 적용 구문을 바꾸기 전에 네이티브 선언을 쓰거나 믹스인을 정의하세요.

텍스트 설명

1. Tailwind 입력. @apply px-4 py-2가 현재 규칙에 Tailwind 유틸리티 선언을 펼칩니다.
2. Master CSS 입력. @apply --control이 미리 정의한 @mixin --control 하나를 펼칩니다.
3. 값 보존. padding-inline: 1rem과 padding-block: .5rem을 명시적으로 정의한 뒤 믹스인을 적용합니다.

#Tailwind와 함께 Master CSS 설치

Tailwind 진입점은 계속 Tailwind 컴파일러가 처리합니다. 일반 CSS로 컴파일한 뒤 Master CSS 진입점과 함께 읽습니다. 두 시스템은 @theme, @utility, @apply라는 이름을 서로 다른 계약으로 사용하므로 처리되지 않은 Tailwind 정의를 Master CSS 컴파일러로 넘기지 마세요.

@import "./legacy-tailwind.generated.css";@import "@master/css";

이 진입점을 컴파일하기 전에 기존 Tailwind 빌드가 legacy-tailwind.generated.css를 생성하도록 유지합니다. 두 시스템이 같은 클래스 이름을 정의할 수 있으므로 공존 중에는 캐스케이드 레이어, 리셋, 중복 이름을 비교하세요.

대부분의 통합에는 여기서 Master CSS 소스 지시문이 필요하지 않습니다. 통합이나 CLI 스캐너가 일반 앱 파일을 찾으므로 기본 범위 밖에 있는 변환 마크업에만 @source를 추가합니다.

그런 다음 프로젝트 프레임워크나 빌드 도구의 설치를 따릅니다. React는 번들러 가이드를, Laravel과 Blazor는 서버 렌더링 앱의 호스트별 절을 사용합니다.

아직 Tailwind를 제거하지 마세요. 첫 목표는 앱의 모양을 유지하면서 Master CSS가 새 마크업이나 변환한 마크업의 규칙을 생성하는 상태입니다.

#렌더링 모드 선택

정적 렌더링부터 시작하세요. 대부분의 Tailwind 프로젝트는 소스에 완전한 클래스 문자열을 이미 보유합니다. 클래스를 전환하거나 요소별 CSS 변수를 바꾸는 데 브라우저 런타임은 필요하지 않습니다.

빌드 후 앱이 실제로 새 클래스 이름을 만들 때만 런타임이나 점진적 렌더링을 사용합니다. 모드를 고르기 전에 조각 조립을 완전한 클래스 맵으로 바꾸고 기존 빌드가 의존하는 소스 경계를 확인하세요.

#CSS 우선 테마 값 변환

Tailwind v4 @theme 변수는 유틸리티 클래스와 변형을 만들고, Master CSS @theme 변수는 네임스페이스의 디자인 토큰을 정의합니다. 형태는 비슷하지만 생성 클래스 구문은 다릅니다.

@import "tailwindcss";@theme {  --color-brand: oklch(0.62 0.2 265);  --spacing-card: 1.5rem;  --radius-card: 1rem;  --breakpoint-dashboard: 72rem;}

@import "@master/css";@theme {  --color-brand: oklch(0.62 0.2 265);  --spacing-card: 1.5rem;  --radius-card: 1rem;}@custom-media --dashboard (width >= 72rem);

<article class="grid r-card grid-cols(3)@dashboard bg-brand p-card">  ...</article>

Master CSS는 네임스페이스에 따라 토큰 이름을 해석합니다. --color-brand는 bg-brand, fg-brand, 테두리 색 유틸리티에, --spacing-card는 p-card, gap-card, m-card 같은 간격 유틸리티에 사용할 수 있습니다.

@theme inline은 생성 선언에서 토큰 값을 한 번 대입하고, @theme static은 사용처가 없어도 토큰과 의존성을 유지합니다. 두 수정자를 함께 쓸 수 있습니다. 테마 블록에는 사용자 정의 속성 선언만 둡니다. 키프레임은 네이티브 CSS에 두고 사용 기반 출력을 원하면 해당 파일에 @prune native;를 넣습니다.

수동 테마 전환용 .light, .dark 선택자는 @theme 밖에 둡니다. 마크업이 @apply(--manual-light)나 @apply(--manual-dark) 접미사를 사용한다면 선택자 믹스인을 별도로 정의합니다.

@import "@master/css";@mixin --manual-light { &:where(.light, .light *) { @contents; } }@mixin --manual-dark { &:where(.dark, .dark *) { @contents; } }@theme {  --color-panel:#fff;  --color-text-body:#111827;}.light {  --color-panel: #fff;  --color-text-body: #111827;}.dark {  --color-panel: #111827;  --color-text-body: #f9fafb;}

<section class="fg-text-body bg-panel">  ...</section>

Tailwind와 Master CSS의 기본 테마는 다릅니다. 사용자 정의 제품 토큰을 먼저 변환한 뒤 기본 팔레트와 스케일 대체를 의도적으로 검토하세요.

#유틸리티 변환

명시적인 Master CSS 선언으로 시작한 뒤 로컬 어휘가 분명한 곳을 줄입니다.

다음은 프리셋 값을 쓰는 Master CSS 레이아웃입니다. 지정되지 않은 Tailwind 레이아웃을 픽셀 단위로 재현한 변환은 아닙니다.

<section class="grid gap-lg w-full max-w-5xl mx-auto px-md py-2xl grid-cols(3)@md">  <article class="p-lg r-lg bg-surface-base shadow-sm">    <h2 class="m(0) font-2xl font-regular fg-text-neutral">Account</h2>    <p class="mt-xs fg-text-muted">Review profile settings.</p>  </article></section>

짧은 Master CSS 별칭이 없는 Tailwind 클래스는 CSS 속성을 직접 사용합니다.

<div class="(scroll-margin-top:4rem) (text-wrap:balance)">  ...</div>

#변형과 상태 변환

Tailwind는 유틸리티 앞에 변형을 쓰고 Master CSS는 선언 뒤에 선택자와 조건을 붙입니다.

<button type="button" class="inline-flex items-center (min-height:2.5rem) px-md r-md bg-blue-60 fg-white bg-blue-70:hover@media(hover:hover) (opacity:.5):disabled">  Save</button>

Tailwind 기본 md는 48rem부터, Master CSS 프리셋 md는 64rem부터입니다. 위 반응형 행은 명명된 조건으로 Tailwind 임계값을 유지합니다.

@custom-media --tailwind-md (width >= 48rem);

Tailwind의 max-md:는 @custom-media --max-tailwind-md not (--tailwind-md);와 @max-tailwind-md 접미사로 유지합니다. Master 프리셋 @max-md는 자체 64rem 임계값의 여집합입니다. 재사용 미디어 쿼리는 @custom-media, 다른 래퍼는 @contents를 포함한 믹스인을 쓰며 선택자 상태는 접미사나 중첩 선택자로 유지합니다.

@import "@master/css";@custom-media --compact (width < 48rem);

<button type="button" class="bg-blue-70:hover@media(hover:hover) fg-white:hover@media(hover:hover) px-sm@compact">  Save</button>

Tailwind의 group-*, peer-* 패턴에는 가능하면 네이티브 선택자를 사용합니다. Master CSS는 자손, 자식, 형제, 속성, :has()를 대상으로 할 수 있지만 Tailwind의 group·peer 변형 이름을 구현하지 않습니다.

<article class="bg-blue-5:hover_h2@media(hover:hover) fg-blue-60:hover_h2@media(hover:hover)">  <h2 class="fg-text-neutral">Project</h2></article>

#유틸리티 조합을 네이티브 CSS로 교체

Tailwind 조합을 네이티브 선언과 선택자로 다시 쓰고 토큰 참조와 상태를 보존합니다. Master 유틸리티는 마크업에서 직접 사용하세요. Master CSS @apply는 명명된 @mixin 하나를 펼치며 유틸리티 클래스 목록을 받지 않습니다. @compose는 지원하지 않습니다.

.btn {  @apply inline-flex items-center gap-2 rounded-md bg-blue-600 px-4 py-2 text-white shadow-sm;}

@import "@master/css";.btn {  display: inline-flex;  border-radius: var(--radius-md);  gap: var(--spacing-xs);  padding-block: var(--spacing-xs);  padding-inline: var(--spacing-md);  background-color: var(--color-blue-60);  box-shadow: var(--shadow-sm);  color: oklch(100% 0 none);  align-items: center;}

이 예는 Master 프리셋 팔레트와 그림자를 사용하므로 Tailwind 기본값과 정확히 같은 모양은 아닙니다. 충실한 변환을 원하면 프로젝트가 디자인을 명시적으로 변경할 때까지 원래 해석된 색과 그림자 값을 유지하세요.

CSS 안에서 선언 그룹을 재사용해야 한다면 믹스인 이름을 부여합니다. 이것이 Master CSS의 @apply 의미입니다.

@mixin --control {  padding-inline: 1rem;  padding-block: .5rem;}.btn {  @apply --control;}

컴포넌트 전용 스타일은 네이티브 선언으로 규칙 전체를 표현할 수 있습니다.

.form-panel {  border-radius: var(--radius-lg);  padding: var(--spacing-lg);  background-color: oklch(100% 0 none);  box-shadow: var(--shadow-sm);  border: 1px solid color-mix(in oklab, currentColor 12%, transparent);}

Vite, Next.js, Webpack 통합에서는 CSS Modules와 프레임워크 스타일 블록에 프로젝트 토큰, 믹스인, 사용자 정의 미디어를 자동으로 제공합니다. 추가 정의 파일이나 독립 컴파일에만 @reference를 사용하세요.

.button {  display: inline-flex;  border-radius: var(--radius-md);  padding-inline: var(--spacing-md);  background-color: var(--color-blue-60);  color: oklch(100% 0 none);  align-items: center;  height: 2.5rem;}

따옴표 문자열, 복잡한 content 값, 특수 선택자는 일반 CSS 선언이나 중첩 CSS로 유지합니다.

#사용자 정의 유틸리티와 컴포넌트 이동

Tailwind @utility는 변형과 함께 쓰는 사용자 정의 유틸리티를 만듭니다. Master CSS에서는 클래스 레시피에 @utility, 선언 재사용에 @mixin, 제품 역할에 @layer components를 사용합니다.

@utility content-auto {  content-visibility: auto;  contain-intrinsic-size: auto 32rem;}

@import "@master/css";@utility content-auto {  content-visibility: auto;  contain-intrinsic-size: auto 32rem;}

<section class="content-auto">  ...</section>

이름이 저수준 기본 기능이 아니라 제품 UI 역할을 설명하면 @layer components를 사용합니다.

@layer components {  .btn {    display: inline-flex;    border-radius: var(--radius-md);    gap: var(--spacing-xs);    padding-block: var(--spacing-xs);    padding-inline: var(--spacing-md);    font-size: var(--font-size-sm);    font-weight: var(--font-weight-medium);    align-items: center;    justify-content: center;    background-color: var(--color-blue-60);    color: oklch(100% 0 none);    &:disabled {      opacity: .5;      pointer-events: none;    }    @media (--md) {      padding-inline: var(--spacing-lg);    }  }}

<button class="btn">  Submit</button>

유틸리티 조합으로 읽기 어려워지는 복잡한 외부 재정의는 네이티브 CSS에 유지합니다.

#동적 클래스 처리

Tailwind와 Master CSS 정적 렌더링은 페이지 실행 전에 찾을 수 있는 클래스 이름에 의존합니다. 완전한 문자열이 가장 안전한 마이그레이션 대상입니다.

const className = '(background:' + tone + ')'

const toneClasses = {  neutral: 'bg-surface-base fg-text-neutral',  success: 'bg-green-80 fg-white',  danger: 'bg-red-70 fg-white'}

값만 동적이면 클래스는 고정하고 런타임 값은 CSS 변수로 전달합니다.

function Progress({ value }: { value: number }) {  const percent = Number.isFinite(value) ? Math.max(0, Math.min(100, value)) : 0  return (    <div role="progressbar" aria-label="Progress" aria-valuemin={0} aria-valuemax={100} aria-valuenow={percent}      className="overflow-hidden (height:1rem) pill bg-surface-inset">      <div        className="h-full (width:var(--progress)) bg-text-muted (transition-property:width) (transition-duration:var(--duration-fast))@motion-safe (transition-timing-function:var(--easing-smooth))"        style={{ '--progress': `${percent}%` } as React.CSSProperties}      />    </div>  )}

Master CSS로 전환하면 대부분의 Tailwind @source 경계를 삭제할 수 있습니다. 공유 워크스페이스 패키지나 외부 콘텐츠처럼 통합이나 CLI가 원래 스캔하지 않는 소스에만 Master CSS @source를 유지하거나 추가합니다.

@import "@master/css";@source "../content/**/*.mdx";@source "../packages/ui/**/*.{ts,tsx}";@source not "../packages/ui/**/*.stories.tsx";

스캔 소스에 없는 유한한 클래스에는 @safelist를, 잘못 감지한 항목에는 @blocklist를 사용합니다.

@import "@master/css";@safelist "bg-blue-60 bg-red-60@dark";@blocklist "debug-*";

Tailwind @source inline()은 인라인 문자열과 중괄호 확장으로 클래스를 생성할 수 있습니다. Master CSS의 @safelist에는 프로젝트에 필요한 클래스를 명시적으로 나열합니다.

#마이그레이션 검증

각 작업을 코드와 UI 양쪽에서 검토합니다.

• 프로젝트 포매터, 린터, 타입 검사, 테스트, 프로덕션 빌드를 실행합니다.
• 코드 린트로 Master CSS 클래스 문자열을 검증하고 충돌을 찾습니다.
• 라이트·다크 테마, 반응형 중단점, 호버·포커스, 필요하다면 인쇄 상태에서 이전 Tailwind 버전과 비교합니다.
• Tailwind Preflight, 기본 테마 값, ring 유틸리티, container, 공식 플러그인, group·peer 변형에 의존한 라우트를 확인합니다.
• 변환된 페이지가 Tailwind 클래스나 플러그인 출력에 의존하지 않을 때까지 Tailwind를 읽습니다.

작업별 검사가 통과하면 더 이상 사용하지 않는 Tailwind 유틸리티만 제거합니다. 제품에 필요한 동안 두 시스템을 계속 함께 사용할 수 있습니다.

#Tailwind 제거

변환한 경로가 빌드되고 의도한 디자인과 시각적으로 일치한 뒤에만 Tailwind를 제거합니다.

1. 앱 진입점에서 생성 Tailwind CSS import를 제거하고 별도의 Tailwind 빌드 입력을 폐기합니다.
2. 대체된 Tailwind 전용 @theme, @utility, @custom-variant, @variant, @apply, @source inline(), @plugin 사용을 제거합니다.
3. 어떤 스타일시트도 Tailwind를 가져오지 않을 때 패키지와 PostCSS 또는 Vite 통합 코드를 제거합니다.
4. 프로젝트 전체 검증을 실행합니다.
5. 브라우저에서 주요 페이지를 다시 확인합니다.

서드파티 플러그인이나 외부 스타일시트가 유용한 CSS를 제공한다면 제품 전용 대안이 생길 때까지 일반 CSS로 유지합니다.

#관련 참고 자료

• 설치: 프로젝트에 Master CSS 추가.
• 렌더링 모드: 정적, 런타임, 점진적 렌더링 선택.
• 스타일 선언: 클래스 구문.
• 테마 토큰: @theme 토큰, 변수와 모드: 모드, 조건: 쿼리 구문.
• CSS 지시문: @source, @safelist, @blocklist, @apply.
• 클래스 이름 스캔: 정적 소스 스캔 동작.
• 전역 스타일: 마크업 유틸리티, 테마 토큰, 사용자 정의 유틸리티, 컴포넌트 클래스 선택.
• 코드 린트: 마이그레이션 중 Master CSS 클래스 검증.

#Master CSS에 직접 대응하지 않는 Tailwind CSS 기능