Tailwind CSS v4
이 스킬은 https://tailwindcss.com/docs 에 문서화된 Tailwind CSS v4.x를 다룹니다. v4는 JavaScript가 아닌 CSS로 구성되며, 많은 v3 클래스 이름과 기본값이 변경되었습니다. 이 스킬은 습관과 다른 점, 즉 CSS-first 설정, 예상치 못한 기본값, 이름이 변경된 유틸리티 및 문서에서 권장하는 패턴을 다룹니다. 참조 파일의 각 주장은 출처 페이지로 끝납니다.
탐색 방법
- 아래 규칙을 읽으세요. v4에서 깨지는 가장 빈번한 v3 습관을 잡아냅니다.
- 마지막 표에서 작업과 일치하는 참조 파일 하나를 여세요.
- 프로젝트에
tailwind.config.js,@tailwind지시문 또는 v3 클래스 이름이 있거나, v3 습관이 있을 수 있는 코드를 검토할 때는 먼저references/upgrade-from-v3.md를 읽으세요. 기본 마이그레이션 경로는 새 브랜치에서npx @tailwindcss/upgrade를 실행한 후, diff를 검토하고 브라우저에서 테스트하는 것입니다. https://tailwindcss.com/docs/upgrade-guide#using-the-upgrade-tool
빠른 시작 (CSS-first, Vite)
npm install tailwindcss @tailwindcss/vite
// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({ plugins: [tailwindcss()] })
/* app.css */
@import "tailwindcss";
@theme {
--color-midnight: #121063;
--font-display: "Oswald", sans-serif;
}
@custom-variant dark (&:where(.dark, .dark *));
- 전체 설정은 패키지, 플러그인 및 하나의
@import "tailwindcss";입니다. 설치 단계에서는tailwind.config.js및content배열을 사용하지 않습니다. https://tailwindcss.com/docs/installation/using-vite - Tailwind는 소스 파일을 자체적으로 스캔합니다.
.gitignore,node_modules, CSS 파일 및 잠금 파일에 있는 파일은 건너뜁니다. https://tailwindcss.com/docs/detecting-classes-in-source-files#which-files-are-scanned - Next.js, Angular 및 기타 Vite가 아닌 번들러는 대신 PostCSS 플러그인을 사용합니다:
npm install tailwindcss @tailwindcss/postcss postcss, 그런 다음plugins: { "@tailwindcss/postcss": {} }. https://tailwindcss.com/docs/installation/using-postcss - 글꼴 URL
@import(Google Fonts 등)는@import "tailwindcss"위, 먼저 와야 하며, 그런 다음 패밀리가@theme에 선언됩니다. https://tailwindcss.com/docs/font-family#customizing-your-theme @theme변수는 유틸리티를 만듭니다:--color-midnight는bg-midnight,text-midnight,fill-midnight을 제공하고,--font-display는font-display를 제공합니다. https://tailwindcss.com/docs/theme#what-are-theme-variables
가장 중요한 규칙
설정 및 구성
- PostCSS 플러그인은
@tailwindcss/postcss이며tailwindcss가 아닙니다.autoprefixer또는postcss-import를 추가하지 마세요: 가져오기 및 공급업체 접두사는 내장되어 있습니다. https://tailwindcss.com/docs/upgrade-guide#using-postcss - Vite 구성에서 프레임워크 가이드는
plugins에서 프레임워크 플러그인(React Router, SvelteKit, SolidJS, Qwik)보다 먼저tailwindcss()를 먼저 나열합니다. 문서에는 순서 요구 사항이 명시되어 있지 않습니다. https://tailwindcss.com/docs/installation/framework-guides/react-router https://tailwindcss.com/docs/installation/framework-guides/sveltekit @theme을 사용하여 CSS에서 사용자 정의합니다. JS 구성은 더 이상 감지되지 않으며corePlugins,safelist또는separator없이@config "../../tailwind.config.js";를 통해서만 로드됩니다. https://tailwindcss.com/docs/upgrade-guide#using-a-javascript-config-file@source inline("{hover:,}bg-red-{50,{100..900..100},950}");로 safelist합니다. https://tailwindcss.com/docs/detecting-classes-in-source-files#safelisting-specific-utilitiesnode_modules내부에 Tailwind로 빌드된 라이브러리는 스캔되지 않습니다:@source "../node_modules/@acmecorp/ui-lib";(스타일시트 기준 상대 경로)를 추가합니다. https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources- 클래스 이름을 동적으로 생성하지 마세요(
`bg-${color}-600`). 값을 완전한 클래스 문자열에 매핑합니다. https://tailwindcss.com/docs/detecting-classes-in-source-files#dynamic-class-names - Vue, Svelte 또는 Astro
<style>블록 및 CSS 모듈은 별도로 컴파일됩니다. 거기서@apply를 사용하기 전에@reference "../app.css";를 추가하거나 대신var(--color-blue-500)을 사용합니다. https://tailwindcss.com/docs/compatibility#explicit-context-sharing https://tailwindcss.com/docs/compatibility#vue-svelte-and-astro - Tailwind v4는 Sass, Less 또는 Stylus와 같은 CSS 전처리기와 함께 사용하도록 설계되지 않았으므로 Vue, Svelte 또는 Astro에서 스타일시트 또는
<style>블록에 사용할 수 없습니다. https://tailwindcss.com/docs/compatibility#sass-less-and-stylus - v4는 Safari 16.4+, Chrome 111+, Firefox 128+가 필요합니다. 이전 브라우저의 경우 v3.4를 유지하세요. https://tailwindcss.com/docs/upgrade-guide#browser-requirements
테마 및 사용자 정의 CSS
- 테마 변수가 다른 변수를 참조할 때는
@theme inline { --font-sans: var(--font-inter); }를 작성합니다. 그렇지 않으면--font-sans가 정의된 위치에서 값이 확인됩니다. https://tailwindcss.com/docs/theme#referencing-other-variables --color-*: initial;로 기본 네임스페이스를 제거하고,--*: initial;로 전체 테마를 제거합니다. https://tailwindcss.com/docs/theme#overriding-the-default-theme@utility name { ... }로 사용자 정의 유틸리티를 선언합니다(@layer utilities가 아님). 그러면 변형이 작동합니다. https://tailwindcss.com/docs/upgrade-guide#adding-custom-utilities- 사용자 정의 CSS 및 JS에서 테마 값을 CSS 변수(
var(--color-red-500))로 읽습니다.theme(colors.red.500)또는resolveConfig를 사용하지 마십시오. https://tailwindcss.com/docs/upgrade-guide#theme-values-in-javascript - 모든 중단점에 동일한 단위를 사용합니다(기본값처럼 rem). 그렇지 않으면 중단점이 서로를 덮어씁니다. https://tailwindcss.com/docs/responsive-design#customizing-your-theme
클래스 구문
- CSS 변수 약어는 괄호를 사용합니다:
bg-(--brand-color),bg-[--brand-color]가 아닙니다. https://tailwindcss.com/docs/upgrade-guide#variables-in-arbitrary-values text-(--my-var)는 모호하므로(글꼴 크기 또는 색상), 유형 힌트를 추가합니다:text-(length:--my-var)또는text-(color:--my-var).font-(family-name:--f),border-(length:--w),bg-(image:--img)및shadow-(color:--c)에도 동일한 힌트가 있습니다. https://tailwindcss.com/docs/adding-custom-styles#resolving-ambiguities https://tailwindcss.com/docs/font-family https://tailwindcss.com/docs/border-width https://tailwindcss.com/docs/background-image https://tailwindcss.com/docs/box-shadow- important 한정자는 끝에 옵니다:
bg-red-500!. https://tailwindcss.com/docs/upgrade-guide#the-important-modifier - 쌓인 변형은 왼쪽에서 오른쪽으로 적용됩니다:
*:first:pt-0,first:*:pt-0이 아닙니다. https://tailwindcss.com/docs/upgrade-guide#variant-stacking-order - 접두사가 없는 클래스는 모든 크기를 대상으로 합니다.
sm:은 모바일을 의미하지 않습니다:text-center sm:text-left로 작성합니다. https://tailwindcss.com/docs/responsive-design#targeting-mobile-screens hover:는 호버가 가능한 장치에만 적용됩니다(@media (hover: hover)). hover를 개선 사항으로 취급합니다. https://tailwindcss.com/docs/upgrade-guide#hover-styles-on-mobile
변경된 기본값
- 테두리 및 나누기 색상의 기본값은
currentColor입니다: 항상border로 색상을 설정합니다. https://tailwindcss.com/docs/upgrade-guide#default-border-color ring은 1pxcurrentColor입니다. v3 모양을 보려면ring-3 ring-blue-500을 작성합니다. https://tailwindcss.com/docs/upgrade-guide#default-ring-width-and-coloroutline-hidden으로 포커스 아웃라인을 숨깁니다(forced-colors 모드에서는 유지됨): v3focus:outline-none은focus:outline-hidden이 됩니다.outline-none은 이제 아웃라인을 완전히 제거합니다. https://tailwindcss.com/docs/upgrade-guide#renamed-outline-utility- 스케일이 변경되었습니다: v3의
shadow-sm,rounded-sm,blur-sm은 이제-xs이고, v3의 기본shadow,rounded,blur는 이제-sm입니다. https://tailwindcss.com/docs/upgrade-guide#updated-shadow-radius-and-blur-scales - 그라데이션은
bg-linear-to-r이며,bg-radial및bg-conic-<angle>도 있습니다. https://tailwindcss.com/docs/background-image#adding-a-linear-gradient container는 중앙 정렬이나 패딩을 제공하지 않습니다:container mx-auto px-4를 작성합니다. https://tailwindcss.com/docs/max-width#using-breakpoints-container- 그리드, 래핑 레이아웃 또는 사용자 정의 순서의 하위 요소에는
space-x-*및space-y-*대신gap을 사용합니다. https://tailwindcss.com/docs/margin#limitations - 버튼에는
cursor: default가 있습니다. https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor - 플레이스홀더는 현재 텍스트 색상을 50% 불투명도로 사용합니다. https://tailwindcss.com/docs/upgrade-guide#new-default-placeholder-color
- display 클래스는 더 이상
hidden속성을 재정의하지 않습니다: 요소를 표시하려면hidden을 제거합니다. https://tailwindcss.com/docs/upgrade-guide#hidden-attribute-takes-priority
클래스를 사용한 다크 모드
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
// 페이지가 렌더링되기 전에 <head>에 인라인으로 추가
document.documentElement.classList.toggle(
"dark",
localStorage.theme === "dark" ||
(!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),
);
localStorage.theme = "dark" 또는 "light"로 설정하고, localStorage.removeItem("theme")로 시스템 설정을 따르도록 합니다. https://tailwindcss.com/docs/dark-mode#with-system-theme-support
참조 파일
| 파일 | 읽어야 할 때 |
|---|---|
| references/installation-and-frameworks.md | Tailwind 설치, Vite, PostCSS 또는 CLI 선택, 프레임워크별 단계, CSS 모듈, 편집기 도구 |
| references/upgrade-from-v3.md | v3 프로젝트 마이그레이션, v3 클래스 이름 또는 구성이 있는 코드 검토 |
| references/utilities-and-variants.md | 클래스 작성: 임의 값, 충돌, 상태 변형, group 및 peer, 반응형, 컨테이너 쿼리, 다크 모드 |
| references/theme-and-colors.md | 색상, 글꼴, 중단점, 간격, 애니메이션, 테마 네임스페이스 추가 또는 재정의 |
| references/custom-styles.md | 기본 스타일, Preflight, 컴포넌트 클래스, @utility, 함수형 유틸리티, @custom-variant, @variant |
| references/directives-and-source-detection.md | @apply, @reference, --alpha(), --spacing(), @config, @plugin, @source, 가져오기 옵션(prefix, important, source) |
| references/layout-flexbox-grid.md | display, position, inset, z-index, columns, flex, grid, 정렬 및 -safe 정렬 |
| references/spacing-and-sizing.md | padding, margin, space, width, height, size, container scale, viewport 단위, 논리적 크기 |
| references/typography.md | 글꼴, 글꼴 크기 및 줄 높이, 자간, 텍스트 줄 바꿈, 오버플로우 줄 바꿈, 장식, content |
| references/backgrounds-and-borders.md | 그라데이션, 배경 이미지, 크기 및 위치, 반경, 테두리 너비 및 색상, 아웃라인 |
| references/effects-and-filters.md | 그림자, 링, 텍스트 그림자, 불투명도, 혼합 모드, 마스크, 필터 및 배경 필터 |
| references/transitions-transforms-tables.md | 전환, 불연속 전환, 애니메이션, 회전, 크기 조절, 이동, 3D, 확대/축소, 테이블 |
| references/interactivity-and-svg.md | 색상 구성표, 필드 크기 조정, 스크롤바, 스크롤 스냅, 커서, will-change, SVG 채우기 및 획, forced colors |