用设计 token 定制 zzzUI 主题
zzzUI 是基于 shadcn、仅暗色的组件库,外观由少数几个设计 token 决定:一个斜切角度、三档描边粗细、一种强调色和一组动效时长。自定义主题时,只需在自己样式表的 :root 中覆盖这些值,所有组件都会随之改变,无需修改其他代码。
设计 token 定义在哪里
安装任意一个 zzzUI 组件时,地基会写入项目的主样式表:每个设计 token 以 --zero- 开头命名,在 :root 上声明一次,Tailwind 的主题再引用它,因此 bg-zero-accent 读取的是 --zero-accent。要修改某个设计 token,在地基之后再写一条 :root 规则,重新设置同名变量即可。注意要覆盖 --zero- 开头的变量,而不是 --color-zero- 开头的:工具类读取的是前者。
主要设计 token
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| --zero-slant | angle | 14deg | 所有斜切:斜切块的边缘,以及填充条与标记的倾斜。 |
| --zero-stroke-thin / --zero-stroke / --zero-stroke-thick | length | 2px / 3px / 4px | 描边粗细。 |
| --zero-accent (-hi, -lo) | colour | #cde31c | 唯一的亮色,以及它的悬停色与按下色。 |
| --zero-focus | colour | #f2e74b | 围绕当前焦点元素的焦点框。 |
| --zero-dur-fast / -base / -slow | time | 140ms / 240ms / 420ms | 悬停、松开与显现的时长。 |
| --zero-rarity-common … -legendary | colour | 五档稀有度的颜色(见 Rarity)。 |
修改斜切角度
每一处切角都由 --zero-slant 和元素高度计算得出,每一道描边都是形状精确向内收缩的结果。因此换一个角度,按钮、标签页、输入框和徽章会一起重新斜切,描边粗细依旧均匀。文字使用字体自带的斜体,不随该设计 token 变化;若希望切角与文字协调,角度应保持在默认值附近(8 到 18 度之间)。
:root { --zero-slant: 8deg; /* a gentler cut than the default 14deg */}切换强调色预设
更换强调色最快的方式是使用预设:在 <html> 上把 data-zero-accent 设为十二个预设之一(lime、cyan、magenta、amber、mint、sky、violet、mono、yellow、leaf、iris、orchid);设在其他元素上,则只改变该元素内部的颜色。Accent switch 和 Accent picker 让访客自行选择,并保存所选结果,Accent picker 还支持自定义颜色。每个预设上的墨黑文字对比度都达到 7 : 1,清晰可读;红色不在预设之列,因为它表示危险。
<html lang="en" data-zero-accent="cyan" suppressHydrationWarning> <head> <AccentScript /> {/* applies a remembered choice before paint */} </head> …</html>自定义强调色
强调色是主按钮和选中标签页的填充色,上面是墨黑文字,因此应选一种足够亮、能让文字保持清晰的颜色(zzzUI 默认的 lime 与墨黑的对比度为 13.8 : 1)。它要与焦点框的黄色明显区分,否则主按钮获得焦点时,焦点框会融进填充色而难以分辨;也要避开表示危险的红色。悬停色和按下色由它混合得出:
:root { --zero-accent: #2ee6d6; --zero-accent-hi: color-mix(in oklab, #2ee6d6, white 22%); /* hover */ --zero-accent-lo: color-mix(in oklab, #2ee6d6, black 18%); /* pressed */}调整动效快慢
时长同样是设计 token,整体缩放这些值,即可改变整套组件的手感:按下反馈、弹出层、标签页滑动、Gauge 的残影。开启「减少动态效果」时,无论这里如何设置,zzzUI 都会把装饰性动效(高光、故障效果、等待中的循环动画)的时长降为零。
:root { /* everything a little quicker */ --zero-dur-fast: 110ms; --zero-dur-base: 190ms; --zero-dur-slow: 330ms;}