Skip to content

颜色 ​

颜色由 theme.palette, theme.shade 与 theme.opacity 三部分决定: 前者决定有哪些颜色, 后两者决定可用档位与透明度.

配置 ​

ts
theme: {
  palette: {
    primary: { light: "sky", dark: "slate" },
    ink: "slate",
  },
  shade: {
    default: { light: 600, dark: 500 },
    subtle: 300,
    strong: 800,
  },
  opacity: {
    default: 100,
    weak: 80,
  },
}

palette ​

内置调色板与 Tailwind 一致, 共 26 个家族, 每族 11 档.

palette 有两种写法: 字符串表示引用内置家族, 对象表示自定义色阶.

字符串形式是内置家族的别名, { primary: "sky" } 之后 primary 与 sky 指向同一组色阶.

对象形式是自定义色阶, 键为档位数字, 值为任意 CSS 颜色, 至少定义一档. 同名家族写成对象即为覆写, 未写出的档位沿用内置值.

shade ​

键名即类名后缀, 取值必须是内置档位 50 到 950 之一. default 作为键名时不带后缀, 因此 text-primary 取 default 对应的档位.

明暗 ​

palette 与 shade 的值可以是普通值, 也可以是明暗成对的值:

ts
primary: { light: "sky", dark: "slate" }
default: { light: 600, dark: 500 }

默认模式是亮色. 需要暗色时显式写 dark; 未写的一侧沿用 base 的对应值.

opacity 不参与明暗成对写法, 它是一份亮暗共用的映射.

opacity ​

键名即颜色修饰符, 取值是 0 到 100 的数字. default 在这里没有特殊含义, 与其他键等价.

规则 ​

颜色名来自 palette, 档位与透明度来自 shade 与 opacity, 三者组合成完整类名. 未列出的键不可用, Tailwind 原有的数字档位与默认修饰符随之消失.

未在 palette 中声明的内置家族不会被自动移除, 是否保留取决于严格模式中的 family 检查; 任意颜色值, 例如 text-[#fff], 由同一处的 arbitrary 检查控制.

亮色值声明在 @theme 中, 暗色值在 @media (prefers-color-scheme: dark) 下覆盖. 暗色跟随系统偏好.

white 与 black 只有单体, 不存在 text-white-subtle 这类档位写法, 带透明度时仍需声明对应的 opacity 键. transparent, current, inherit 三个关键字始终可用.

用法 ​

以上配置对应以下写法, 右列为等价的 Tailwind 写法:

类名结果等价写法
text-primary取 default, 即 600text-sky-600
text-primary-subtle取 300text-sky-300
border-ink-strong取 800border-slate-800
bg-primary/weak透明度为 80%bg-sky-600/80
text-white内置常量, 不受配置影响text-white

输出 ​

颜色以变量形式提供, 需要写自定义样式时可以直接引用:

css
.card {
  color: var(--color-primary-subtle);
  border-color: var(--color-ink-strong);
  background: color-mix(in oklab, var(--color-primary) var(--opacity-weak), transparent);
}

命名规则为 --color-<名>, --color-<名>-<键>, --opacity-<键>. 自定义样式不需要写暗色分支, var(--color-primary) 会自动取当前模式的值.

报错 ​

自定义色阶缺少被引用的档位时, 构建会报出家族与档位:

text
color family "primary" has no shade 400

色阶为空, 或键名不符合 [A-Za-z0-9_]+ 时同样会直接报错.

明暗成对的值两侧都缺失时也会报错:

text
mode value must define light or dark

相关 ​