Skip to content

核心概念 ​

本页说明颜色与尺寸如何由配置决定, 以及严格模式与诊断的作用.

设计思想 ​

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 不带后缀; 值可以是固定长度, 也可以带自己的范围.
  • 范围: 可用数字. min step max 可以全局声明, 也可以按单位覆盖; 越界的数字不可用.

以默认单位为例:

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.

输出按首次出现排序并去重, 行数上限可配置. 配置错误与诊断等级无关, 始终直接抛出.

等级与输出的细节见诊断.