输入关键词,开始搜索

↑↓ 选择↵ 打开esc 关闭
沉浸

皮肤与配色接口

皮肤与配色接口

皮肤是独立的包:核心只带经典皮肤和它的配色 A–I、K,其他皮肤放在站点根目录的 skins/ 下,在 src/data/config/identity.ts 里按名字启用。每个皮肤至少自带一套配色,访客在一个皮肤下只能选它自己的配色;没有单独的配色包。用法见界面皮肤和配色方案。

这一篇写给做皮肤、做配色的人,列出核心承诺保持稳定的东西:目录和清单的格式,以及皮肤可以依赖的 token、挂钩、属性和变量。皮肤只依赖这里列出的东西,核心升级时就不会坏。皮肤写在站点里,不用改主题代码。

接口版本

当前版本是 1,记在主题的 src/appearance/contract.json。皮肤的清单 skin.json 里要写 "contract": 1,和核心对不上时构建直接失败,免得一个按旧约定写的皮肤悄悄坏掉。

本篇列出的任何一项改名或删除,核心都会升版本;只是新增挂钩、新增可选字段,不升版本。

目录约定

目录名就是皮肤名。目录里只放数据、样式和说明,不放脚本:构建时核心只读这些文件,不执行任何代码。

skins/<皮肤名>/  skin.json              清单:显示名、默认配色、自带的配色  skin.css               样式入口,可以再 @import 同目录下拆开的文件  schemes/<配色 ID>.css   自带的配色,至少一套,每套一个文件,文件名就是配色 ID  README.md              给使用者看的说明(可选)

vergil-skins 里的皮肤都是按这个约定写的,可以照着改。用 vg skin add 装下来的皮肤目录里还会多一个 .vg-source.json,记着从哪里装的,主题不读它。

skin.json

JSON
{    "contract": 1,    "labels": { "zh-CN": "海岛", "en": "Island" },    "recommendedScheme": "warm-cream",    "schemes": [        {            "id": "warm-cream",            "short": "L",            "labels": { "zh-CN": "暖奶油", "en": "Warm Cream" },            "swatch": "#a9521f"        }    ]}
字段 必填 说明
contract 是 接口版本,当前是 1
labels 否 面板上显示的名字,按界面语言取,没有当前语言就用 en,再没有就用皮肤名
recommendedScheme 否 默认配色:访客切到这个皮肤、或者还没选过配色时用哪套。只能是这个皮肤自带的,不写就是 schemes 里的第一套
schemes 是 自带的配色,至少一套。访客在这个皮肤下只能选这些,每一项的字段见下表

自带配色的每一项:

字段 必填 说明
id 是 配色 ID,会写进 <html data-theme>,也是 schemes/ 下的文件名
short 是 面板色点下面显示的 1~2 个字母或数字,同一个皮肤里不能重复
labels 否 显示名,规则同上,鼠标悬停在色点上时显示
swatch 是 色点的颜色
icon 否 选中这套配色后,右上角调色盘图标的颜色。不写就等于 swatch。色点颜色在页面底色上看不清时用它,比如报纸荧绿的荧光绿在纸白底上太淡,图标改用 var(--text-main)

校验规则

  • 皮肤名、配色 ID 只能用小写字母、数字和短横,以字母开头,最长 32 个字符。它们会写进目录路径、CSS 选择器和 HTML 属性,所以卡得比较严
  • swatch、icon 只接受十六进制色值(#a9521f)或一个 CSS 变量(var(--text-main))
  • 每个皮肤至少带一套配色,recommendedScheme 只能是自己带的
  • 配色 ID 在所有皮肤之间都不能重复,包括和内置的 A–I、K 重复:配色的样式是全局加载的,靠 ID 区分
  • 目录如果是软链接,必须指在 skins/ 里面
  • identity.ts 里写了名字但目录不存在:跳过这个包,构建时警告,站点照常构建
  • 目录存在但清单写错、缺文件、版本对不上:构建失败,报错会指出是哪个文件、哪个字段

提交到 vergil-skins 的皮肤还要满足几条更严的要求,保证任意几个皮肤一起启用不会互相影响:显示名要有中文和英文,配色 ID 全仓库不重复,样式都挂在自己的皮肤或配色下,@keyframes 以皮肤名开头,不从外部加载资源。仓库里的 pnpm check 会逐条检查,详见它的 CONTRIBUTING。

皮肤能依赖的东西

所有规则都挂在 html[data-skin="<皮肤名>"] 下面,别的皮肤不受影响。不要去匹配组件内部的 Tailwind 类名,那些类名随时可能因为重构而变。

设计 token

在皮肤的根选择器里重新定义它们,全站跟着变,这一层改动面最大、成本最低:

  • 圆角 --radius-xs ~ --radius-2xl、阴影 --shadow-xs ~ --shadow-xl、动效 --ease-out、--duration-*,取值见设计 Token
  • 内容指令的圆角和描边:--md-radius、--md-radius-sm、--md-radius-lg、--md-border

挂钩类

组件上的 ui-* 类本身没有样式,只是给皮肤一个稳定的抓手:

挂钩 在哪
ui-topbar 顶部导航栏的外壳,里面的 <nav> 是内容条
ui-btn Button 组件渲染出来的按钮或链接
ui-btn-primary 主按钮,比如开屏页和文档封面上的「开始使用」
ui-label 侧栏各小组件的小标题(最近更新、热力图、标签等)
ui-title 列表页的页面标题(文章、项目、文档、专栏、工具)
ui-tag / ui-tag-sep 文章卡片和文章末尾的标签、分类链接,以及标签之间的逗号
ui-pagination / ui-icon-btn 分页条和它两侧的翻页圆钮
ui-fab 右下角的悬浮圆钮(回到顶部、目录)
ui-modal / ui-input 搜索弹窗和里面的输入框
ui-tooltip 热力图的提示浮层
ui-panel 左侧栏的各个小组件(头像卡、站内导航、站点信息等)和右侧栏的介绍卡片
card-interactive 可点击的卡片,比如文章列表里的每一篇

内容指令的类名(.md-tabs-nav、.md-directive-folding 这些)本身就是公开的,也可以直接匹配。

固定的 id、类名和属性

选择器 是什么
html[data-skin]、html[data-theme]、html.dark 当前皮肤、当前配色、暗色模式
[aria-current] 导航里的当前项:顶部导航、移动端菜单、左栏站内导航、文档目录、分页
#top-nav-header、.mobile-menu-glass 顶栏和移动端菜单
#main-sidebar、#docs-sidebar、.right-sidebar-container 左侧栏、文档目录侧栏、右侧栏
#main-stage、#main-content、#floating-toolbar 正文区域、正文内容、正文顶上吸顶的工具条
#reading-progress 文章页顶部的阅读进度条
.hero、.splash-gradient、[data-splash-mode] 首页的介绍区、开屏图底部的渐变、是否处于开屏状态
.prose 文章正文,里面是 Markdown 渲染出来的标准元素
.heatmap-cell[data-level] 热力图的格子,data-level 从 0 到 4
.astro-code Shiki 渲染的代码块

首页 Hero 的行动按钮目前还没有挂钩,海岛和粗野皮肤按 .hero a.bg-accent 匹配,以后补上挂钩会升接口版本。

配色变量

配色就是一组 CSS 变量,写在 html[data-theme="<配色 ID>"] 和 html[data-theme="<配色 ID>"].dark 两个块里。暗色不会自动推导,要单独写一份。

必填,每个皮肤都会读:

变量 用途
--text-main、--text-secondary、--text-muted 正文、次要文字、最淡的文字
--bg-main、--bg-card、--bg-muted、--bg-hover 页面底色、卡片、浅底、悬停底
--border-main、--border-light 重描边、轻描边
--accent-color、--accent-hover 强调色和它的悬停色

可选:

变量 谁读 用途
--accent-text 所有皮肤 压在强调色上的文字。不写时亮色是白色,暗色是页面底色
--bg-panel 海岛 有值时把正文栏放进一块这个颜色的圆角面板
--bg-dot 海岛 波点底纹的颜色
--bg-pop 粗野 大块平涂的颜色(主按钮、页面标题的高亮、悬停底、进度条、悬浮按钮),不写就用强调色
--pop-text 粗野 压在平涂色上的字色,不写就用 --accent-text

配色只会和带它的皮肤一起出现,所以配色文件里可以放只给这个皮肤的特调,比如重写热力图格子的颜色,vergil-skins 里的几套配色都这么做了。

皮肤里的颜色一律从这些变量里取,需要派生色就用 color-mix() 混出来,别写死色值,否则换一套配色或者切到暗色就对不上了。确实需要固定颜色的地方要写清楚理由,比如海岛皮肤的代码块固定用暖深棕底,因为 Shiki 的配色只分亮暗两套,没法跟着配色变。

未知标题
00:00
00:00
播放列表