核心概念
将工具类作为设计令牌的API使用
Tailwind 是一个用于构建自定义设计的框架,不同的设计需要不同的排版、颜色、阴影、断点等。
这些底层设计决策通常被称为_设计令牌_,在 Tailwind 项目中,你会将这些值存储在_主题变量_中。
主题变量是使用 @theme
指令定义的特殊 CSS 变量,它们会影响项目中存在哪些工具类。
例如,你可以通过定义像 --color-mint-500
这样的主题变量来为项目添加新颜色:
@import "tailwindcss";@theme { --color-mint-500: oklch(0.72 0.11 178);}
现在你就可以在 HTML 中使用 bg-mint-500
、text-mint-500
或 fill-mint-500
等工具类:
<div class="bg-mint-500"> <!-- ... --></div>
Tailwind 还会为你的主题变量生成常规的 CSS 变量,这样你就可以在任意值或内联样式中引用你的设计令牌:
<div style="background-color: var(--color-mint-500)"> <!-- ... --></div>
了解更多关于主题变量如何映射到不同工具类的信息,请参阅主题变量命名空间文档。
@theme
而不是 :root
?主题变量不仅仅是 CSS 变量 —— 它们还会指示 Tailwind 创建新的实用类,供你在 HTML 中使用。
由于它们的功能比普通 CSS 变量更多,Tailwind 使用特殊语法来确保主题变量的定义始终是显式的。主题变量还要求必须在顶层定义,不能嵌套在其他选择器或媒体查询下,使用特殊语法可以强制执行这一规则。
在 Tailwind 项目中,当你需要定义一个不打算与实用类关联的变量时,使用 :root
定义常规 CSS 变量仍然很有用。当你希望设计标记直接映射到实用类时使用 @theme
,而对于不应该有对应实用类的常规 CSS 变量,则使用 :root
来定义。
Tailwind 中的一些工具类如 flex
和 object-cover
是静态的,在不同项目中始终保持不变。但许多其他工具类由主题变量驱动,它们的存在完全取决于您定义的主题变量。
例如,在 --font-*
命名空间下定义的主题变量决定了项目中所有 font-family
工具类的存在:
@theme { --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif; --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; /* ... */}
font-sans
、font-serif
和 font-mono
工具类默认存在,仅仅是因为 Tailwind 的默认主题定义了 --font-sans
、--font-serif
和 --font-mono
主题变量。
如果定义了另一个主题变量如 --font-poppins
,相应的 font-poppins
工具类就会变得可用:
@import "tailwindcss";@theme { --font-poppins: Poppins, sans-serif;}
<h1 class="font-poppins">这个标题将使用 Poppins 字体。</h1>
您可以在这些命名空间内自由命名主题变量,HTML 中就会自动生成对应的同名工具类供您使用。
某些主题变量用于定义变体而非工具类。例如,--breakpoint-*
命名空间中的主题变量决定了项目中存在哪些响应式断点变体:
@import "tailwindcss";@theme { --breakpoint-3xl: 120rem;}
现在你可以使用 3xl:*
变体,仅在视口宽度达到 120rem 或更宽时触发某个工具类:
<div class="3xl:grid-cols-6 grid grid-cols-2 md:grid-cols-4"> <!-- ... --></div>
要了解更多关于主题变量如何映射到不同工具类和变体的信息,请参阅主题变量命名空间文档。
主题变量定义在_命名空间_中,每个命名空间对应一个或多个工具类或变体 API。
在这些命名空间中定义新的主题变量将使对应的新工具类和变体在你的项目中可用:
命名空间 | 工具类 |
---|---|
--color-* | 颜色工具类,如 bg-red-500 、text-sky-300 等 |
--font-* | 字体家族工具类,如 font-sans |
--text-* | 字体大小工具类,如 text-xl |
--font-weight-* | 字体粗细工具类,如 font-bold |
--tracking-* | 字母间距工具类,如 tracking-wide |
--leading-* | 行高工具类,如 leading-tight |
--breakpoint-* | 响应式断点变体,如 sm:* |
--container-* | 容器查询变体如 @sm:* 和尺寸工具类如 max-w-md |
--spacing-* | 间距和尺寸工具类,如 px-4 、max-h-16 等 |
--radius-* | 边框圆角工具类,如 rounded-sm |
--shadow-* | 盒子阴影工具类,如 shadow-md |
--inset-shadow-* | 内嵌盒子阴影工具类,如 inset-shadow-xs |
--drop-shadow-* | 投影滤镜工具类,如 drop-shadow-md |
--blur-* | 模糊滤镜工具类,如 blur-md |
--perspective-* | 透视工具类,如 perspective-near |
--aspect-* | 宽高比工具类,如 aspect-video |
--ease-* | 过渡时序函数工具类,如 ease-out |
--animate-* | 动画工具类,如 animate-spin |
要查看所有默认主题变量的列表,请参阅默认主题变量参考。
当你在 CSS 文件顶部导入 tailwindcss
时,它会包含一组默认主题变量帮助你快速开始开发。
以下是实际导入 tailwindcss
时包含的内容:
@layer theme, base, components, utilities;@import "./theme.css" layer(theme);@import "./preflight.css" layer(base);@import "./utilities.css" layer(utilities);
其中 theme.css
文件包含了默认的调色板、字体比例、阴影、字体等配置:
@theme { --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif; --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; --color-red-50: oklch(0.971 0.013 17.38); --color-red-100: oklch(0.936 0.032 17.717); --color-red-200: oklch(0.885 0.062 18.334); /* ... */ --shadow-2xs: 0 1px rgb(0 0 0 / 0.05); --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.05); --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1); /* ... */}
这就是为什么像 bg-red-200
、font-serif
和 shadow-sm
这样的工具类可以直接使用 —— 它们是由默认主题驱动的,而不是像 flex-col
或 pointer-events-none
那样硬编码在框架中。
要查看所有默认主题变量的列表,请参阅默认主题变量参考。
默认主题变量非常通用,适合构建各种不同的设计,但它们仍然只是一个起点。通常你会自定义调色板、字体和阴影等内容,以构建你心目中的精确设计。
使用 @theme
来定义新的主题变量并扩展默认主题:
@import "tailwindcss";@theme { --font-script: Great Vibes, cursive;}
这会创建一个新的 font-script
工具类,你可以像使用默认的 font-sans
或 font-mono
工具类一样在 HTML 中使用它:
<p class="font-script">这将使用 Great Vibes 字体家族。</p>
了解更多关于主题变量如何映射到不同工具类和变体的信息,请参阅主题变量命名空间文档。
通过在 @theme
中重新定义变量来覆盖默认主题变量的值:
@import "tailwindcss";@theme { --breakpoint-sm: 30rem;}
现在 sm:*
变体将在 30rem 视口尺寸时触发,而不是默认的 40rem:
<div class="grid grid-cols-1 sm:grid-cols-3"> <!-- ... --></div>
要完全覆盖默认主题中的整个命名空间,可以使用特殊的星号语法将该命名空间设置为 initial
:
@import "tailwindcss";@theme { --color-*: initial; --color-white: #fff; --color-purple: #3f3cbb; --color-midnight: #121063; --color-tahiti: #3ab7bf; --color-bermuda: #78dcca;}
这样做时,所有使用该命名空间的默认工具类(如 bg-red-500
)都会被移除,只有你的自定义值(如 bg-midnight
)会保留。
了解更多关于主题变量如何映射到不同工具类和变体的信息,请参阅主题变量命名空间文档。
要完全禁用默认主题并仅使用自定义值,请将全局主题变量命名空间设置为 initial
:
@import "tailwindcss";@theme { --*: initial; --spacing: 4px; --font-body: Inter, sans-serif; --color-lagoon: oklch(0.72 0.11 221.19); --color-coral: oklch(0.74 0.17 40.24); --color-driftwood: oklch(0.79 0.06 74.59); --color-tide: oklch(0.49 0.08 205.88); --color-dusk: oklch(0.82 0.15 72.09);}
现在所有由主题变量驱动的默认工具类都将不可用,您只能使用与自定义主题变量匹配的工具类,如 font-body
和 text-dusk
。
在 @theme
中为您的 --animate-*
主题变量定义 @keyframes
规则,以便将它们包含在生成的 CSS 中:
@import "tailwindcss";@theme { --animate-fade-in-scale: fade-in-scale 0.3s ease-out; @keyframes fade-in-scale { 0% { opacity: 0; transform: scale(0.95); } 100% { opacity: 1; transform: scale(1); } }}
如果您希望自定义的 @keyframes
规则即使在不添加 --animate-*
主题变量时也能始终包含在内,请改为在 @theme
外部定义它们。
在定义引用其他变量的主题变量时,请使用 inline
选项:
@import "tailwindcss";@theme inline { --font-sans: var(--font-inter);}
使用 inline
选项后,工具类将直接使用主题变量的 值 而非引用实际的主题变量:
.font-sans { font-family: var(--font-inter);}
如果不使用 inline
,由于 CSS 中变量解析的方式,你的工具类可能会解析出意外的值。
例如,以下文本将回退到 sans-serif
字体,而不会如预期般使用 Inter
:
<div id="parent" style="--font-sans: var(--font-inter, sans-serif);"> <div id="child" style="--font-inter: Inter; font-family: var(--font-sans);"> 这段文字将使用 sans-serif 字体,而非 Inter。 </div></div>
这是因为 var(--font-sans)
会在 --font-sans
定义的位置 (在 #parent
上) 解析,而此时 --font-inter
还没有值,因为它是在更深的树结构中 (在 #child
上) 才定义的。
默认情况下,最终 CSS 输出中只会生成被使用的 CSS 变量。如果你想始终生成所有 CSS 变量,可以使用 static
主题选项:
@import "tailwindcss";@theme static { --color-primary: var(--color-red-500); --color-secondary: var(--color-blue-500);}
由于主题变量是在 CSS 中定义的,跨项目共享它们只需将其放入一个独立的 CSS 文件中,然后在每个项目中导入即可:
@theme { --*: initial; --spacing: 4px; --font-body: Inter, sans-serif; --color-lagoon: oklch(0.72 0.11 221.19); --color-coral: oklch(0.74 0.17 40.24); --color-driftwood: oklch(0.79 0.06 74.59); --color-tide: oklch(0.49 0.08 205.88); --color-dusk: oklch(0.82 0.15 72.09);}
然后你可以使用 @import
在其他项目中引入你的主题变量:
@import "tailwindcss";@import "../brand/theme.css";
在 monorepo 设置中,你可以将这类共享主题变量放在独立的包中,甚至可以发布到 NPM,然后像导入其他第三方 CSS 文件一样导入它们。
当你编译 CSS 时,所有的主题变量都会被转换为常规的 CSS 变量:
:root { --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif; --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; --color-red-50: oklch(0.971 0.013 17.38); --color-red-100: oklch(0.936 0.032 17.717); --color-red-200: oklch(0.885 0.062 18.334); /* ... */ --shadow-2xs: 0 1px rgb(0 0 0 / 0.05); --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.05); --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1); /* ... */}
这使得你可以在自定义 CSS 或内联样式中轻松引用所有的设计令牌。
在编写需要使用相同设计值的自定义 CSS 时,可以通过主题变量来访问你的设计标记:
@import "tailwindcss";@layer components { .typography { p { font-size: var(--text-base); color: var(--color-gray-700); } h1 { font-size: var(--text-2xl--line-height); font-weight: var(--font-weight-semibold); color: var(--color-gray-950); } h2 { font-size: var(--text-xl); font-weight: var(--font-weight-semibold); color: var(--color-gray-950); } }}
这在样式化不受你控制的 HTML 时特别有用,比如来自数据库或 API 并渲染为 HTML 的 Markdown 内容。
在任意值中使用主题变量会很有帮助,特别是与 calc()
函数结合使用时。
<div class="relative rounded-xl"> <div class="absolute inset-px rounded-[calc(var(--radius-xl)-1px)]"> <!-- ... --> </div> <!-- ... --></div>
在上面的例子中,我们在嵌套的内嵌元素上从 --radius-xl
值中减去 1px,以确保它具有同心圆角边框。
大多数情况下,当您需要在 JavaScript 中引用主题变量时,可以直接使用 CSS 变量,就像使用其他 CSS 值一样。
例如,流行的 React 动画库 Motion 允许您使用 CSS 变量值进行动画处理:
<motion.div animate={{ backgroundColor: "var(--color-blue-500)" }} />
如果您需要在 JavaScript 中获取已解析的 CSS 变量值,可以使用 getComputedStyle
获取文档根元素上的主题变量值:
let styles = getComputedStyle(document.documentElement);let shadow = styles.getPropertyValue("--shadow-xl");
以下是将 Tailwind CSS 导入项目时默认包含的完整主题变量列表,供参考:
@theme { --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif; --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; --color-red-50: oklch(0.971 0.013 17.38); --color-red-100: oklch(0.936 0.032 17.717); --color-red-200: oklch(0.885 0.062 18.334); --color-red-300: oklch(0.808 0.114 19.571); --color-red-400: oklch(0.704 0.191 22.216); --color-red-500: oklch(0.637 0.237 25.331); --color-red-600: oklch(0.577 0.245 27.325); --color-red-700: oklch(0.505 0.213 27.518); --color-red-800: oklch(0.444 0.177 26.899); --color-red-900: oklch(0.396 0.141 25.723); --color-red-950: oklch(0.258 0.092 26.042); --color-orange-50: oklch(0.98 0.016 73.684); --color-orange-100: oklch(0.954 0.038 75.164); --color-orange-200: oklch(0.901 0.076 70.697); --color-orange-300: oklch(0.837 0.128 66.29); --color-orange-400: oklch(0.75 0.183 55.934); --color-orange-500: oklch(0.705 0.213 47.604); --color-orange-600: oklch(0.646 0.222 41.116); --color-orange-700: oklch(0.553 0.195 38.402); --color-orange-800: oklch(0.47 0.157 37.304); --color-orange-900: oklch(0.408 0.123 38.172); --color-orange-950: oklch(0.266 0.079 36.259); --color-amber-50: oklch(0.987 0.022 95.277); --color-amber-100: oklch(0.962 0.059 95.617); --color-amber-200: oklch(0.924 0.12 95.746); --color-amber-300: oklch(0.879 0.169 91.605); --color-amber-400: oklch(0.828 0.189 84.429); --color-amber-500: oklch(0.769 0.188 70.08); --color-amber-600: oklch(0.666 0.179 58.318); --color-amber-700: oklch(0.555 0.163 48.998); --color-amber-800: oklch(0.473 0.137 46.201); --color-amber-900: oklch(0.414 0.112 45.904); --color-amber-950: oklch(0.279 0.077 45.635); --color-yellow-50: oklch(0.987 0.026 102.212); --color-yellow-100: oklch(0.973 0.071 103.193); --color-yellow-200: oklch(0.945 0.129 101.54); --color-yellow-300: oklch(0.905 0.182 98.111); --color-yellow-400: oklch(0.852 0.199 91.936); --color-yellow-500: oklch(0.795 0.184 86.047); --color-yellow-600: oklch(0.681 0.162 75.834); --color-yellow-700: oklch(0.554 0.135 66.442); --color-yellow-800: oklch(0.476 0.114 61.907); --color-yellow-900: oklch(0.421 0.095 57.708); --color-yellow-950: oklch(0.286 0.066 53.813); --color-lime-50: oklch(0.986 0.031 120.757); --color-lime-100: oklch(0.967 0.067 122.328); --color-lime-200: oklch(0.938 0.127 124.321); --color-lime-300: oklch(0.897 0.196 126.665); --color-lime-400: oklch(0.841 0.238 128.85); --color-lime-500: oklch(0.768 0.233 130.85); --color-lime-600: oklch(0.648 0.2 131.684); --color-lime-700: oklch(0.532 0.157 131.589); --color-lime-800: oklch(0.453 0.124 130.933); --color-lime-900: oklch(0.405 0.101 131.063); --color-lime-950: oklch(0.274 0.072 132.109); --color-green-50: oklch(0.982 0.018 155.826); --color-green-100: oklch(0.962 0.044 156.743); --color-green-200: oklch(0.925 0.084 155.995); --color-green-300: oklch(0.871 0.15 154.449); --color-green-400: oklch(0.792 0.209 151.711); --color-green-500: oklch(0.723 0.219 149.579); --color-green-600: oklch(0.627 0.194 149.214); --color-green-700: oklch(0.527 0.154 150.069); --color-green-800: oklch(0.448 0.119 151.328); --color-green-900: oklch(0.393 0.095 152.535); --color-green-950: oklch(0.266 0.065 152.934); --color-emerald-50: oklch(0.979 0.021 166.113); --color-emerald-100: oklch(0.95 0.052 163.051); --color-emerald-200: oklch(0.905 0.093 164.15); --color-emerald-300: oklch(0.845 0.143 164.978); --color-emerald-400: oklch(0.765 0.177 163.223); --color-emerald-500: oklch(0.696 0.17 162.48); --color-emerald-600: oklch(0.596 0.145 163.225); --color-emerald-700: oklch(0.508 0.118 165.612); --color-emerald-800: oklch(0.432 0.095 166.913); --color-emerald-900: oklch(0.378 0.077 168.94); --color-emerald-950: oklch(0.262 0.051 172.552); --color-teal-50: oklch(0.984 0.014 180.72); --color-teal-100: oklch(0.953 0.051 180.801); --color-teal-200: oklch(0.91 0.096 180.426); --color-teal-300: oklch(0.855 0.138 181.071); --color-teal-400: oklch(0.777 0.152 181.912); --color-teal-500: oklch(0.704 0.14 182.503); --color-teal-600: oklch(0.6 0.118 184.704); --color-teal-700: oklch(0.511 0.096 186.391); --color-teal-800: oklch(0.437 0.078 188.216); --color-teal-900: oklch(0.386 0.063 188.416); --color-teal-950: oklch(0.277 0.046 192.524); --color-cyan-50: oklch(0.984 0.019 200.873); --color-cyan-100: oklch(0.956 0.045 203.388); --color-cyan-200: oklch(0.917 0.08 205.041); --color-cyan-300: oklch(0.865 0.127 207.078); --color-cyan-400: oklch(0.789 0.154 211.53); --color-cyan-500: oklch(0.715 0.143 215.221); --color-cyan-600: oklch(0.609 0.126 221.723); --color-cyan-700: oklch(0.52 0.105 223.128); --color-cyan-800: oklch(0.45 0.085 224.283); --color-cyan-900: oklch(0.398 0.07 227.392); --color-cyan-950: oklch(0.302 0.056 229.695); --color-sky-50: oklch(0.977 0.013 236.62); --color-s sky-100: oklch(0.951 0.026 236.824); --color-sky-200: oklch(0.901 0.058 230.902); --color-sky-300: oklch(0.828 0.111 230.318); --color-sky-400: oklch(0.746 0.16 232.661); --color-sky-500: oklch(0.685 0.169 237.323); --color-sky-600: oklch(0.588 0.158 241.966); --color-sky-700: oklch(0.5 0.134 242.749); --color-sky-800: oklch(0.443 0.11 240.79); --color-sky-900: oklch(0.391 0.09 240.876); --color-sky-950: oklch(0.293 0.066 243.157); --color-blue-50: oklch(0.97 0.014 254.604); --color-blue-100: oklch(0.932 0.032 255.585); --color-blue-200: oklch(0.882 0.059 254.128); --color-blue-300: oklch(0.809 0.105 251.813); --color-blue-400: oklch(0.707 0.165 254.624); --color-blue-500: oklch(0.623 0.214 259.815); --color-blue-600: oklch(0.546 0.245 262.881); --color-blue-700: oklch(0.488 0.243 264.376); --color-blue-800: oklch(0.424 0.199 265.638); --color-blue-900: oklch(0.379 0.146 265.522); --color-blue-950: oklch(0.282 0.091 267.935); --color-indigo-50: oklch(0.962 0.018 272.314); --color-indigo-100: oklch(0.93 0.034 272.788); --color-indigo-200: oklch(0.87 0.065 274.039); --color-indigo-300: oklch(0.785 0.115 274.713); --color-indigo-400: oklch(0.673 0.182 276.935); --color-indigo-500: oklch(0.585 0.233 277.117); --color-indigo-600: oklch(0.511 0.262 276.966); --color-indigo-700: oklch(0.457 0.24 277.023); --color-indigo-800: oklch(0.398 0.195 277.366); --color-indigo-900: oklch(0.359 0.144 278.697); --color-indigo-950: oklch(0.257 0.09 281.288); --color-violet-50: oklch(0.969 0.016 293.756); --color-violet-100: oklch(0.943 0.029 294.588); --color-violet-200: oklch(0.894 0.057 293.283); --color-violet-300: oklch(0.811 0.111 293.571); --color-violet-400: oklch(0.702 0.183 293.541); --color-violet-500: oklch(0.606 0.25 292.717); --color-violet-600: oklch(0.541 0.281 293.009); --color-violet-700: oklch(0.491 0.27 292.581); --color-violet-800: oklch(0.432 0.232 292.759); --color-violet-900: oklch(0.38 0.189 293.745); --color-violet-950: oklch(0.283 0.141 291.089); --color-purple-50: oklch(0.977 0.014 308.299); --color-purple-100: oklch(0.946 0.033 307.174); --color-purple-200: oklch(0.902 0.063 306.703); --color-purple-300: oklch(0.827 0.119 306.383); --color-purple-4 00: oklch(0.714 0.203 305.504); --color-purple-500: oklch(0.627 0.265 303.9); --color-purple-600: oklch(0.558 0.288 302.321); --color-purple-700: oklch(0.496 0.265 301.924); --color-purple-800: oklch(0.438 0.218 303.724); --color-purple-900: oklch(0.381 0.176 304.987); --color-purple-950: oklch(0.291 0.149 302.717); --color-fuchsia-50: oklch(0.977 0.017 320.058); --color-fuchsia-100: oklch(0.952 0.037 318.852); --color-fuchsia-200: oklch(0.903 0.076 319.62); --color-fuchsia-300: oklch(0.833 0.145 321.434); --color-fuchsia-400: oklch(0.74 0.238 322.16); --color-fuchsia-500: oklch(0.667 0.295 322.15); --color-fuchsia-600: oklch(0.591 0.293 322.896); --color-fuchsia-700: oklch(0.518 0.253 323.949); --color-fuchsia-800: oklch(0.452 0.211 324.591); --color-fuchsia-900: oklch(0.401 0.17 325.612); --color-fuchsia-950: oklch(0.293 0.136 325.661);