Tailwind CSS v4

Quick Start

프로젝트의 메인 CSS 파일(예: global.css)에 아래 코드를 순서대로 복사하여 붙여넣으세요.

/* global.css */

/* 1. 파일 최상단에서 전체 Layer 순서를 정의합니다. */
@layer tw-theme, theme, reset, components, utilities, tw-utilities;

/* 2. Tailwind와 Vapor UI 스타일을 불러옵니다. */
@import 'tailwindcss/theme.css' layer(tw-theme);
@import 'tailwindcss/utilities.css' layer(tw-utilities);

@import '@vapor-ui/core/styles.css';
@import '@vapor-ui/core/tailwind.css';

이 설정만으로 Vapor UI와 Tailwind CSS를 함께 사용하기 위한 모든 준비가 완료됩니다.

Styling with Vapor Utility Classes

@vapor-ui/core/tailwind.css를 추가하면 Vapor UI의 디자인 토큰을 활용하는 다양한 유틸리티 클래스를 사용할 수 있습니다. 모든 클래스는 v- 접두사를 가집니다.

테마 토큰 클래스

Vapor UI의 디자인 토큰은 @theme 규칙을 통해 Tailwind CSS의 네이티브 테마 시스템에 통합됩니다. 각 토큰은 color, spacing, radius 등과 같은 네임스페이스로 그룹화되어 있습니다.

사용법은 각 네임스페이스에 속한 토큰 이름에 v- 접두사를 붙여 Tailwind의 표준 유틸리티 클래스와 조합하면 됩니다.

color 네임스페이스
- 토큰 예시: `--color-v-blue-500, --color-v-red-300, --color-v-gray-900, ...
- 사용 예시: bg-v-blue-500, text-v-red-300, border-v-gray-900, ...
spacing 네임스페이스
- 토큰 예시: --spacing-v-100, --spacing-v-200, --spacing-v-400, ...
- 사용 예시: p-v-100, m-v-200, gap-v-400, w-v-400, ...`
radius 네임스페이스
- 토큰 예시: --radius-v-200, --radius-v-400, ...
- 사용 예시: rounded-v-200, rounded-t-v-400, ...
font-weight 네임스페이스
- 토큰 예시: --font-weight-v-400, --font-weight-v-700, ...
- 사용 예시: font-v-400, font-v-700, ...

각 네임스페이스와 조합할 수 있는 전체 유틸리티 클래스 목록(예: bg-, p-, w-, h-, border- 등)은 Tailwind CSS 공식 문서 에서 확인하실 수 있습니다.

시맨틱 유틸리티 클래스

'주요 배경색', '위험 상태 텍스트' 등 의미에 기반한 고유한 유틸리티 클래스도 제공합니다. 이 클래스들은 Vapor UI에만 존재하므로 아래 리스트를 통해 확인할 수 있습니다.

배경색 (Background Colors)

bg-v-primary, bg-v-secondary, bg-v-success, bg-v-warning, bg-v-danger, bg-v-hint, bg-v-contrast, bg-v-normal, bg-v-normal-lighter, bg-v-normal-darker

글자색 (Text Colors) text-v-primary, text-v-primary-darker, text-v-secondary, text-v-secondary-darker, text-v-success, text-v-success-darker, text-v-warning, text-v-warning-darker, text-v-danger, text-v-danger-darker, text-v-hint, text-v-hint-darker, text-v-contrast, text-v-contrast-darker, text-v-accent, text-v-normal, text-v-normal-lighter, text-v-logo

테두리색 (Border Colors) border-v-primary, border-v-secondary, border-v-normal, border-v-success, border-v-warning, border-v-danger, border-v-hint, border-v-contrast

Core Concepts

CSS Layer와 우선순위

Vapor UI와 Tailwind CSS의 통합은 CSS의 @layer 규칙을 기반으로 동작합니다. 'Quick Start'에서 설정한 코드는 다음과 같은 스타일 우선순위 계층을 만듭니다.

우선순위 (낮음 → 높음):

tw-theme: Tailwind의 기본 테마 변수
theme: Vapor UI의 커스텀 테마 변수
reset: Vapor UI의 브라우저 스타일 초기화
components: Vapor UI 컴포넌트의 기본 스타일
utilities: Vapor UI의 보조 유틸리티 클래스
tw-utilities: Tailwind의 유틸리티 클래스 (가장 높은 우선순위)

이 구조의 핵심은 Tailwind 유틸리티(tw-utilities)가 항상 가장 높은 우선순위를 갖는 것입니다. 덕분에 개발자는 className="bg-blue-500 text-white"와 같은 Tailwind 클래스를 사용하여 Vapor UI 컴포넌트의 기본 스타일을 언제든지 쉽게 재정의할 수 있습니다.

CSS Reset 정책

스타일 초기화(Reset)는 라이브러리 간 충돌이 발생하기 쉬운 부분이므로, Vapor UI의 정책을 이해하는 것이 중요합니다.

권장: Vapor UI의 자체 Reset 사용

Vapor UI는 @layer reset을 통해 자체적으로 필요한 최소한의 브라우저 스타일 초기화를 수행합니다. 따라서 Tailwind CSS의 preflight.css를 별도로 불러오는 것을 권장하지 않습니다.
두 개의 Reset을 함께 사용하면 예상치 못한 스타일 충돌이 발생하거나, 일관성이 깨질 수 있습니다.

예외: preflight.css를 반드시 사용해야 하는 경우

만약 프로젝트의 특정 요구사항으로 인해 Tailwind의 preflight.css를 반드시 사용해야 한다면, @layer 순서를 직접 제어하여 preflight가 Vapor UI의 reset보다 낮은 우선순위를 갖도록 설정해야 합니다.

예를 들어, 다음과 같이 순서를 조정할 수 있습니다.

/* globals.css (예시) */

@layer tw-theme, theme, tw-base, reset, components, utilities, tw-utilities;

@import 'tailwindcss/theme.css' layer(tw-theme);
@import 'tailwindcss/utilities.css' layer(tw-utilities);
@import 'tailwindcss/preflight.css' layer(tw-base); /* 추가 */

@import '@vapor-ui/core/styles.css';
@import '@vapor-ui/core/tailwind.css';

참고

Tailwind Preflight