简体中文
核心概念
本页说明颜色与尺寸如何由配置决定, 以及严格模式与诊断的作用.
设计思想
CSS 规范的落地长期依赖约定: 不写魔法数字, 颜色与尺寸走统一变量. Tailwind 提供了原子化的写法, 但它的颜色与尺寸是全量开放的, 规范只能靠 code review 约束.
Tunewind 的做法是把规范写成配置, 由构建期执行. 颜色与尺寸在配置中是可以枚举的有限集合, 因此某个类是否可用可以在构建时判定.
规范的边界由此写在配置里, 不再依赖约定维护.
Tunewind 不改变 Tailwind 的语法与用法. 类名结构, 变体, 断点与绝大多数工具类保持原样, 收窄的只有颜色与尺寸的取值.
主题
颜色体系由调色板, 别名与映射三层组成.
- 调色板: 颜色来源. 内置 26 个家族, 每族 11 档; 也可以用对象覆写某一档, 或定义新的家族.
- 别名: 语义命名.
palette的字符串写法,{ primary: "sky" }之后primary与sky指向同一组色阶. - 映射: 可用档位与透明度.
shade与opacity的键名直接成为类名后缀, 未声明的键不可用.
明暗是 palette 与 shade 之上的第二个维度. 值可以是普通值, 也可以是明暗成对的值:
ts
palette: { primary: { light: "sky", dark: "slate" } },
shade: { default: { light: 600, dark: 500 }, subtle: 300 },以主色为例:
ts
theme: {
palette: { primary: { light: "sky", dark: "slate" } },
shade: { default: { light: 600, dark: 500 }, subtle: 300 },
opacity: { default: 100, weak: 80 },
}text-primary在亮色下取600, 暗色下取500.text-primary-subtle在两种模式下都取300.bg-primary/weak在两种模式下都使用80%的透明度.
主题与模式在以上三层之上做覆盖. schemes 中每个主题只声明与 base 不同的部分, 页面类名保持不变. 暗色跟随 prefers-color-scheme, 不需要额外属性.
需要针对某个主题单独指定时, 使用该主题的 prefix, 例如 ocean:text-primary.
white 与 black 始终可用. 未在 palette 中声明的内置家族仍能生成产物, 是否保留由严格模式决定.
尺寸
尺寸体系由单位与范围组成.
- 单位: 长度与后缀.
units的键名作为类名后缀,default不带后缀; 值可以是固定长度, 也可以带自己的范围. - 范围: 可用数字.
minstepmax可以全局声明, 也可以按单位覆盖; 越界的数字不可用.
以默认单位为例:
ts
size: {
max: 64,
units: { default: "4px", r: "1rem" },
}p-4等于4 * 4px.w-8r等于8 * 1rem.w-96超过max, 不可用.
断点在同一套单位之上覆盖长度, 数字与类名不变:
ts
breakpoints: {
xl: { units: { r: "1.25rem" } },
}此时 xl:w-8r 是 8 个 1.25rem.
严格模式
严格模式决定超出配置的写法是否保留, 涉及任意值, 原始色名与放行前缀三个方面. 可以整体关闭, 也可以逐项开放; 收紧到最高时, 只有配置声明的颜色与范围内的尺寸可用.
放行前缀 raw: 仅对任意值与原始色名生效, 尺寸范围与透明度白名单不接受放行. 档位与各开关的含义见严格模式.
诊断
默认不输出信息, 违规的类只表现为产物中缺少对应声明. 启用后, 构建按等级处理被移除的节点:
off: 移除, 不输出.warn: 逐行输出目标与原因, 构建继续.error: 汇总后抛出, 构建中断, 适用于 CI.
输出按首次出现排序并去重, 行数上限可配置. 配置错误与诊断等级无关, 始终直接抛出.
等级与输出的细节见诊断.