Back to Details

tailwind

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tailwind CSS (v4+)

Tailwind CSS (v4+)

Overview

概述

Tailwind CSS v4 skill covering CSS-first configuration, design tokens, component patterns, shadcn/ui integration, dark mode, container queries, migration from v3, and custom utilities.
When to use: Configuring Tailwind themes, building utility-first components, implementing dark mode, using container queries, migrating from v3, integrating shadcn/ui, troubleshooting build errors.
When NOT to use: Tailwind v3 legacy projects that will not upgrade, projects using a different styling approach (CSS Modules, styled-components) without plans to adopt Tailwind.
本Tailwind CSS v4技能涵盖CSS优先配置、设计令牌、组件模式、shadcn/ui集成、暗黑模式、容器查询、从v3版本迁移以及自定义工具类等内容。
适用场景： 配置Tailwind主题、构建工具优先的组件、实现暗黑模式、使用容器查询、从v3版本迁移、集成shadcn/ui、排查构建错误。
不适用场景： 不打算升级的Tailwind v3遗留项目，以及未计划采用Tailwind、使用其他样式方案（如CSS Modules、styled-components）的项目。

Quick Reference

快速参考

PatternAPIKey Points
CSS-first config
@theme { --color-brand: oklch(...); }
All config in CSS, no 
tailwind.config.js
Import entry
@import "tailwindcss";
Replaces 
@tailwind base/components/utilities
Custom utilities
@utility name { ... }
Replaces 
@layer utilities
, works with variants
Functional utilities
@utility tab-* { tab-size: --value(--tab-size-*); }
Accept dynamic values via 
--value()
Plugin loading
@plugin "@tailwindcss/typography";
Replaces 
require()
in config
Container queries
@container
parent + 
@md:
child		Built-in, no plugin needed
Named containers
@container/sidebar
+ 
@md/sidebar:
Scope queries to specific containers
Dark mode variant
@custom-variant dark (&:where(.dark, .dark *));
Class-based dark mode override
Theme inline
@theme inline { --color-bg: var(--bg); }
Inlines values at build, single-theme only
Source detection
@source "../node_modules/my-lib";
Explicitly add scan paths
Reference import
@reference "../../app.css";
Use theme in Vue/Svelte scoped styles
Override defaults
--color-*: initial;
inside 
@theme
Reset a category before redefining
Dynamic values
grid-cols-(--my-var)
Use CSS variables in utility values
Text shadows
text-shadow-*
Built-in text shadow utilities
Starting styles
starting:opacity-0
@starting-style
variant for entry animations
Masks
mask-*
CSS mask utilities for image/gradient masking
Field sizing
field-sizing-content
Auto-sizing textareas and inputs
Inset shadows
inset-shadow-*
, 
inset-ring-*
Inner shadow and ring utilities
User validation
user-valid:
, 
user-invalid:
Form validation after user interaction
Pointer queries
pointer-fine:
, 
pointer-coarse:
Target input device precision
Inert
inert:opacity-50
Style inert elements
Logical spacing
pbs-*
, 
pbe-*
, 
mbs-*
, 
mbe-*
Block-direction padding/margin (v4.2)
Logical sizing
inline-*
, 
block-*
, 
min-inline-*
, 
max-block-*
Logical width/height utilities (v4.2)
Logical inset
inset-s-*
, 
inset-e-*
, 
inset-bs-*
, 
inset-be-*
Logical positioning; replaces 
start-*
/
end-*
Logical borders
border-bs-*
, 
border-be-*
Block-direction border utilities (v4.2)
Font features
font-features-['smcp']
OpenType 
font-feature-settings
(v4.2)
New color palettes
mauve
, 
olive
, 
mist
, 
taupe
Additional neutral palettes (v4.2)
Webpack integration
@tailwindcss/webpack
Run Tailwind as a webpack plugin (v4.2)
Color spaceOKLCHDefault in v4, sRGB fallbacks generated
模式API核心要点
CSS优先配置
@theme { --color-brand: oklch(...); }
所有配置均在CSS中完成，无需
tailwind.config.js
导入入口
@import "tailwindcss";
替代
@tailwind base/components/utilities
自定义工具类
@utility name { ... }
替代
@layer utilities
，支持变体
函数式工具类
@utility tab-* { tab-size: --value(--tab-size-*); }
通过
--value()
接收动态值
插件加载
@plugin "@tailwindcss/typography";
替代配置文件中的
require()
容器查询
@container
父元素 + 
@md:
子元素		内置功能，无需额外插件
命名容器
@container/sidebar
+ 
@md/sidebar:
将查询范围限定到特定容器
暗黑模式变体
@custom-variant dark (&:where(.dark, .dark *));
基于类的暗黑模式覆盖方案
内联主题
@theme inline { --color-bg: var(--bg); }
构建时内联值，仅适用于单主题场景
源文件检测
@source "../node_modules/my-lib";
显式添加扫描路径
引用导入
@reference "../../app.css";
在Vue/Svelte作用域样式中使用主题
覆盖默认值
--color-*: initial;
置于
@theme
内部		重新定义前重置分类值
动态值
grid-cols-(--my-var)
在工具类值中使用CSS变量
文本阴影
text-shadow-*
内置文本阴影工具类
初始样式
starting:opacity-0
用于入场动画的
@starting-style
变体
遮罩
mask-*
用于图片/渐变遮罩的CSS工具类
字段自适应
field-sizing-content
文本域与输入框自动调整尺寸
内阴影
inset-shadow-*
, 
inset-ring-*
内阴影与环形边框工具类
用户验证状态
user-valid:
, 
user-invalid:
用户交互后的表单验证状态
指针精度查询
pointer-fine:
, 
pointer-coarse:
针对输入设备精度设置样式
惰性元素样式
inert:opacity-50
为惰性元素设置样式
逻辑间距
pbs-*
, 
pbe-*
, 
mbs-*
, 
mbe-*
块级方向内边距/外边距（v4.2版本新增）
逻辑尺寸
inline-*
, 
block-*
, 
min-inline-*
, 
max-block-*
逻辑宽度/高度工具类（v4.2版本新增）
逻辑定位
inset-s-*
, 
inset-e-*
, 
inset-bs-*
, 
inset-be-*
逻辑定位工具类；替代
start-*
/
end-*
逻辑边框
border-bs-*
, 
border-be-*
块级方向边框工具类（v4.2版本新增）
字体特性
font-features-['smcp']
OpenType 
font-feature-settings
（v4.2版本新增）
新调色板
mauve
, 
olive
, 
mist
, 
taupe
新增中性调色板（v4.2版本新增）
Webpack集成
@tailwindcss/webpack
将Tailwind作为webpack插件运行（v4.2版本新增）
颜色空间OKLCHv4版本默认颜色空间，自动生成sRGB降级方案

Common Mistakes

常见错误

MistakeCorrect Pattern
Using 
tailwind.config.js
in v4		Configure via 
@theme { ... }
in CSS
hsl(var(--background))
double-wrap		Reference directly: 
var(--background)
:root
/
.dark
inside 
@layer base
Define at root level, outside any 
@layer
@apply
with 
@layer components
classes		Use 
@utility
directive for custom utilities
@theme inline
for multi-theme switching		Use 
@theme
without 
inline
for dynamic themes
Raw colors like 
bg-blue-500
everywhere		Semantic tokens (
bg-primary
) that auto-adapt
require()
or 
@import
for plugins		Use 
@plugin "package-name";
tailwindcss-animate
in v4		Use 
tw-animate-css
instead
Missing 
@theme inline
with shadcn/ui		Map all CSS variables in 
@theme inline
block
Using 
theme('colors.brand')
in CSS		Use 
var(--color-brand)
native CSS variables
Using deprecated 
start-*
/
end-*
inset		Use 
inset-s-*
/
inset-e-*
logical utilities
错误做法正确模式
在v4中使用
tailwind.config.js
通过CSS中的
@theme { ... }
进行配置
双重包裹
hsl(var(--background))
直接引用：
var(--background)
在
@layer base
内部使用
:root
/
.dark
在根级别定义，置于所有
@layer
外部
对
@layer components
类使用
@apply
对自定义工具类使用
@utility
指令
为多主题切换使用
@theme inline
动态主题使用不带
inline
的
@theme
随处使用
bg-blue-500
这类原始颜色值		使用可自动适配的语义化令牌（如
bg-primary
）
使用
require()
或
@import
加载插件		使用
@plugin "package-name";
在v4中使用
tailwindcss-animate
改用
tw-animate-css
集成shadcn/ui时缺少
@theme inline
在
@theme inline
块中映射所有CSS变量
在CSS中使用
theme('colors.brand')
使用原生CSS变量
var(--color-brand)
使用已弃用的
start-*
/
end-*
定位工具类		使用
inset-s-*
/
inset-e-*
逻辑定位工具类

Delegation

任务分工

  • Class pattern discovery and usage examples: Use 
    Explore
    agent
  • v3 to v4 migration across multiple files: Use 
    Task
    agent
  • Design token hierarchy and theming architecture: Use 
    Plan
    agent
If the 
motion
skill is available, delegate complex animation patterns (spring physics, gestures, scroll-linked) to it.
  • 类模式探索与使用示例：使用
    Explore
    Agent
  • 多文件从v3到v4迁移：使用
    Task
    Agent
  • 设计令牌层级与主题架构：使用
    Plan
    Agent
若
motion
技能可用，可将复杂动画模式（如弹簧物理效果、手势、滚动关联动画）委托给该技能处理。

References

参考资料

  • Configuration -- CSS-first config, @theme, @theme inline, @utility, @plugin, @source, @reference, @variant directives
  • Design Tokens -- OKLCH token system, brand scales, semantic tokens, shadows, z-index, fluid typography
  • Component Patterns -- Layouts, grids, container queries, 3D transforms, subgrid, CVA variants
  • UI Patterns -- Buttons, forms, navigation, cards, typography with variants, states, accessibility
  • Dark Mode -- Class-based dark mode, multi-theme systems, ThemeProvider, @custom-variant
  • shadcn/ui Integration -- Four-step architecture, components.json, tw-animate-css, Vite setup
  • Migration -- v3 to v4 migration steps, breaking changes, upgrade tool, common gotchas
  • Troubleshooting -- Common errors, build fixes, CSS layer issues, PostCSS problems
  • 配置 -- CSS优先配置、@theme、@theme inline、@utility、@plugin、@source、@reference、@variant 指令
  • 设计令牌 -- OKLCH令牌系统、品牌色阶、语义化令牌、阴影、z-index、流式排版
  • 组件模式 -- 布局、网格、容器查询、3D变换、子网格、CVA变体
  • UI模式 -- 按钮、表单、导航、卡片、带变体的排版、状态、可访问性
  • 暗黑模式 -- 基于类的暗黑模式、多主题系统、ThemeProvider、@custom-variant
  • shadcn/ui集成 -- 四步架构、components.json、tw-animate-css、Vite配置
  • 迁移指南 -- 从v3到v4的迁移步骤、破坏性变更、升级工具、常见陷阱
  • 故障排查 -- 常见错误、构建修复、CSS层级问题、PostCSS问题