界面皮肤
界面皮肤
皮肤决定界面的形状和质感:圆角有多大、按钮长什么样、卡片靠投影还是描边、页面底下铺不铺底纹。每个皮肤还带着自己的几套配色:经典皮肤用内置的十套配色方案,其他皮肤用各自带的配色。暗色模式在哪个皮肤下都照常生效。
切换皮肤
访客可以自己切换:点右上角的主题图标,面板最上面一行是皮肤,下面是当前皮肤的配色。切换皮肤时,配色会换成新皮肤的默认配色,之后可以在这个皮肤自己的配色里再挑。选择会记在浏览器里,换页、下次再来都保持。
站长在配置里定的是默认皮肤,也就是访客没选过时看到的那一个。打开 src/data/config/identity.ts,改 skin 这一项。比如装好海岛皮肤以后,想让访客默认看到它:
export const siteInfo = { title: 'Vergil', locale: 'zh-CN', skin: 'island', skins: ['island'], // ...};skin 只能填已经启用的皮肤(见下一节),填了没启用的会退回 classic,构建时打一条警告,站点不会因此报错。
安装和启用
主题本身只带经典皮肤 classic。其他皮肤都是独立的包,集中放在 vergil-skins 仓库,官方皮肤和大家贡献的皮肤都在那里。用法像 zsh 的插件:
- 安装:把皮肤目录放进站点根目录的
skins/下,目录名就是皮肤名,比如skins/island/ - 启用:在
identity.ts的skins里写上名字
写了名字但目录不存在,构建时会跳过这个皮肤并提示该放到哪里。想停用一个皮肤,从 skins 里删掉名字就行,目录留着也没关系:没启用的皮肤,样式不会打进构建,面板上也不会出现。访客之前选过的皮肤被停用后,会自动退回默认皮肤和它的默认配色。
用 vergil-cli 的话,vg skin add <名字> 从 vergil-skins 安装并启用,别处的皮肤写 owner/repo、owner/repo/目录 或本地目录;vg skin use <名字> 设成默认皮肤,vg skin update 从原来的地方重新拉取,vg skin remove <名字> 停用并删除。装下来的皮肤是一份文件快照,跟着站点仓库一起提交,部署时不用再装一遍。
现有皮肤
| 值 | 怎么装 | 样子 |
|---|---|---|
classic |
内置 | 经典皮肤,主题原本的样子:小圆角、轻投影、贴边的毛玻璃顶栏 |
island |
vg skin add island |
治愈系海岛风:大圆角和胶囊按钮,页面铺一层波点底,顶栏变成悬浮的胶囊。列表页标题是燕尾飘带,选项卡和分页换成实心胶囊,标签变成浅色小签,代码块统一用暖深棕底,搜索弹窗的边缘带一点手工感的起伏。只有主按钮底下压一道实色台阶,按下去会陷进去,其余按钮和卡片都只用很轻的投影或描边 |
brutalism |
vg skin add brutalism |
粗野皮肤,报纸风的新粗野主义:全部直角,纸面上只用 1px 黑色细框。容器(侧栏小组件、折叠、提示框)只描边,可点击的东西(卡片、按钮、代码块、悬浮按钮)再加一道不模糊的 4px 硬投影,悬停往左上抬,按下去沉进投影里。小标签、标签、按钮和表头用等宽大写,侧栏小标题是墨色实底的小方签,导航和目录的当前项是墨色实块,列表页标题是黑字加一道荧光笔似的高亮,分隔线是报纸上的双线,选项卡切换时会弹一下 |
每个皮肤能选的配色不一样:
| 皮肤 | 能选的配色 | 默认配色 |
|---|---|---|
classic |
内置的 A–I、K,共十套 | C 暖墨橙红 |
island |
暖奶油 warm-cream(面板上显示 L)、奶油珊瑚 cream-coral(J) |
暖奶油 |
brutalism |
报纸荧绿 newsprint(M),纸白底、黑字黑框,荧光绿只做大块平涂 |
报纸荧绿 |
粗野皮肤只带一套配色,所以在它下面没有配色可换,这是正常的。
皮肤不管字体,字体仍然由字体配置决定。想让海岛更接近原型,可以把西文字体换成 Nunito 这类圆体;粗野皮肤的等宽字取的是字体配置里的等宽字体。
写一个皮肤
皮肤就是 skins/ 下的一个目录,里面只有一份清单、样式和说明,不需要改核心的任何代码:
skins/my-skin/ skin.json 显示名、默认配色、自带的配色 skin.css 样式入口 schemes/ 自带的配色,至少一套,每套一个 CSS 文件 README.md 说明(可选)最简单的 skin.json 带一套配色:
{ "contract": 1, "labels": { "zh-CN": "我的皮肤", "en": "My Skin" }, "schemes": [ { "id": "my-scheme", "short": "N", "labels": { "zh-CN": "我的配色", "en": "My Scheme" }, "swatch": "#a9521f" } ]}对应的配色写在 schemes/my-scheme.css 里,写法见配色方案。带了好几套时,recommendedScheme 指定默认用哪套,不写就是第一套。
skin.css 里的规则都挂在 html[data-skin="my-skin"] 下面,这样别的皮肤完全不受影响。写好以后在 identity.ts 的 skins 里加上 'my-skin',面板上就会出现它。
皮肤能动的东西分三层,完整的清单和清单字段见皮肤与配色接口:
- 设计 token:在皮肤的根选择器里重新定义
--radius-*、--shadow-*、--ease-out,全站所有rounded-lg、shadow-md这类工具类都会跟着变,这一层改动面最大、成本最低 ui-*挂钩类:组件上专门留给皮肤的抓手,比如顶栏ui-topbar、按钮ui-btn、侧栏小组件ui-panel。导航里的当前项都带aria-current,要改选中态就按这个属性匹配- 内容指令:指令的类名(
.md-tabs-nav、.md-directive-folding这些)本身就是公开的,大部分指令的圆角和描边读的是--md-radius*、--md-border这组变量,改掉它们就能一次统一
配色也可以给皮肤递信息。海岛皮肤会读 --bg-panel 和 --bg-dot:前者把正文栏放进一块这个颜色的圆角面板,后者是波点底纹的颜色,它自带的两套配色都提供了。粗野皮肤会读 --bg-pop 和 --pop-text,作为大块平涂的颜色和压在上面的字色,报纸荧绿提供了荧光绿和黑字,没提供时退回强调色。
皮肤只匹配 token、挂钩类、指令类名和接口文档里列出的 id,不要去匹配组件内部的 Tailwind 类名,那些类名随时可能因为重构而变。颜色一律从 --text-main、--bg-card、--accent-color 这些配色变量里取,需要派生色就用 color-mix() 混出来,别写死色值,否则换一套配色或者切到暗色就对不上了。
贡献皮肤
写好的皮肤欢迎提 PR 到 vergil-skins,在 skins/ 下加一个目录就行。仓库的 CI 会检查清单、配色 ID 有没有重复、样式是不是都挂在自己的皮肤下,再把全部皮肤装进最新的主题跑一次构建。写法和规则见它的 CONTRIBUTING。