zzzUI

用设计 token 定制 zzzUI 主题

zzzUI 是基于 shadcn、仅暗色的组件库,外观由少数几个设计 token 决定:一个斜切角度、三档描边粗细、一种强调色和一组动效时长。自定义主题时,只需在自己样式表的 :root 中覆盖这些值,所有组件都会随之改变,无需修改其他代码。

设计 token 定义在哪里

安装任意一个 zzzUI 组件时,地基会写入项目的主样式表:每个设计 token 以 --zero- 开头命名,在 :root 上声明一次,Tailwind 的主题再引用它,因此 bg-zero-accent 读取的是 --zero-accent。要修改某个设计 token,在地基之后再写一条 :root 规则,重新设置同名变量即可。注意要覆盖 --zero- 开头的变量,而不是 --color-zero- 开头的:工具类读取的是前者。

主要设计 token

属性类型默认值说明
--zero-slantangle14deg所有斜切:斜切块的边缘,以及填充条与标记的倾斜。
--zero-stroke-thin / --zero-stroke / --zero-stroke-thicklength2px / 3px / 4px描边粗细。
--zero-accent (-hi, -lo)colour#cde31c唯一的亮色,以及它的悬停色与按下色。
--zero-focuscolour#f2e74b围绕当前焦点元素的焦点框。
--zero-dur-fast / -base / -slowtime140ms / 240ms / 420ms悬停、松开与显现的时长。
--zero-rarity-common … -legendarycolour五档稀有度的颜色(见 Rarity)。

修改斜切角度

每一处切角都由 --zero-slant 和元素高度计算得出,每一道描边都是形状精确向内收缩的结果。因此换一个角度,按钮、标签页、输入框和徽章会一起重新斜切,描边粗细依旧均匀。文字使用字体自带的斜体,不随该设计 token 变化;若希望切角与文字协调,角度应保持在默认值附近(8 到 18 度之间)。

globals.css
: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,清晰可读;红色不在预设之列,因为它表示危险。

layout.tsx
<html lang="en" data-zero-accent="cyan" suppressHydrationWarning>  <head>    <AccentScript />  {/* applies a remembered choice before paint */}  </head>  …</html>

自定义强调色

强调色是主按钮和选中标签页的填充色,上面是墨黑文字,因此应选一种足够亮、能让文字保持清晰的颜色(zzzUI 默认的 lime 与墨黑的对比度为 13.8 : 1)。它要与焦点框的黄色明显区分,否则主按钮获得焦点时,焦点框会融进填充色而难以分辨;也要避开表示危险的红色。悬停色和按下色由它混合得出:

globals.css
: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 都会把装饰性动效(高光、故障效果、等待中的循环动画)的时长降为零。

globals.css
:root {  /* everything a little quicker */  --zero-dur-fast: 110ms;  --zero-dur-base: 190ms;  --zero-dur-slow: 330ms;}

延伸阅读

Rarity 介绍各档稀有度的颜色及其使用位置;Icons 说明图标如何沿用同一个斜切角度。要查看设计 token 在完整界面中的效果,请浏览代码块。