Publii UI 开发指南:从 CSS 设计令牌到共享组件的设计系统落地实践
Publii UI 开发指南:从 CSS 设计令牌到共享组件的设计系统落地实践
导读
本文是 Publii(开源桌面静态站点 CMS)UI 开发指南(UI-DEVELOPMENT.md)的中文深度解读,围绕"如何在 Vue 模板与应用自有 CSS 中落地设计契约"这一核心主题展开。文章以仓库中的设计规范 DESIGN.md 为视觉契约源头,系统讲解语义化 CSS 令牌(颜色、间距、排版、形状、深度、动效、层级)、appAppearance 与 workspaceAccent 的运行时机制、basic-elements 共享组件的 props 契约,以及遗留 API 的迁移路径与自动化审计流程。读完本文,你将掌握在 Publii 渲染器中编写符合设计系统约束的组件样式、正确消费语义令牌、迁移旧式 props,并通过 npm run audit:design-system 通过契约检查的完整实战方法。
文档定位:实现级配套指南,而非新的设计规范
UI-DEVELOPMENT.md 是 DESIGN.md 的"实现配套"文档:DESIGN.md 定义视觉契约与已接受的设计决策,本指南则解释如何将该契约应用到 Vue 模板和应用自有 CSS 中。二者的分工关系清晰:
- 当本指南与某个组件发生分歧时,以组件中经过校验(validated)的 props 作为可执行 API,并应在同一变更中更新本指南;
- 任何视觉契约的变更都必须同步更新
DESIGN.md。
当前规范化范围覆盖主应用渲染器(renderer)与编辑器 chrome 共享的视觉角色;编辑器自有布局、块编辑器内部实现、vendor 样式、生成站点主题(site themes)与外部插件样式属于独立作用域,不在本次组件规范化范围内。
真相来源(Sources of truth)
原文档给出了一张"真相来源"对照表,这是理解 Publii 设计系统代码组织的钥匙,在仓库中均可一一对应:
| 关注点 | 来源 |
|---|---|
| 视觉规则与已接受的设计决策 | DESIGN.md |
| 技术性 CSS 基础(appearance 无关) | app/src/css/css-variables.css |
| 完整应用外观(appAppearance) | app/src/css/appearances/ |
| 共享组件实现与 prop 校验器 | app/src/components/basic-elements/ |
| 全局注册的组件名 | app/src/main.js |
| 应用外观运行时 | app/src/helpers/app-appearance.js |
| 自动化契约检查 | build/scripts/audit-design-system.js |
| 已批准的本地颜色例外 | build/scripts/design-system-baseline.json |
其中 css-variables.css 存放的是与外观无关的技术基础:静态中性色 --black/--white、全局堆叠层级(--layer-panel: 9999 到 --layer-alert: 100006 共 10 个命名层级)、工作区布局尺寸(如 --topbar-height: 2.2rem、--options-sidebar-width: 44rem、--app-sidebar-width: 28rem)、共享按钮尺寸,以及由应用设置写入的运行时桥接变量 --ui-zoom-level。从源码结构看,该文件刻意与外观解耦,完整调色板全部下沉到 appearances/ 目录。
工作规则:七条铁律
- 先复用共享组件,再考虑新增视图局部控件或 class;
- 用 props 表达组件语义,禁止把空格分隔的 class 名当作"变体 API";
- 组件中使用语义化 CSS 令牌,禁止在 appearance 文件之外消费私有
--palette-*变量; - 每个应用外观的 light/dark 两套 scheme 中,语义令牌名必须保持一致,字面值由各 scheme 各自拥有;
- 一次性光学修正与结构尺寸保持局部化,不为每个数字创建全局令牌;
- 组件不得直接修改
data-theme、data-app-appearance、data-color-scheme、data-workspace-accent这四个属性; - 提交渲染器 UI 改动前,必须运行 design-system audit。
第 6 条在审计脚本中有硬性保障:audit-design-system.js 会扫描所有非 app-appearance.js 文件,一旦发现 setAttribute('data-theme') 等直接写入外观属性的代码,即报错 Appearance attributes must be applied through app-appearance.js。这正是"运行时唯一所有者"原则的自动化落地。
使用 CSS 语义令牌
应用自有令牌由 App.vue 全局加载——在 app/src/components/App.vue 中可以看到两条关键 import:先 @import '../css/css-variables.css',再 @import '../css/appearances/publii.css'。加载顺序即"基础优先、外观覆盖"的层级关系。编辑器 iframe 内使用的独立样式表由 build/scripts/prepare-editor-css.js 生成,其 editor.css 与 editor-options.css 两个产物同样按 css-variables.css → appearances/publii.css → 编辑器专属 CSS 的顺序拼接。
颜色:按"角色"而非"当前颜色"选令牌
.panel {
background: var(--bg-secondary);
border: 1px solid var(--color-border-default);
color: var(--text-primary-color);
}
.panel-note {
color: var(--text-light-color);
}
.panel-link {
color: var(--link-primary-color);
}
.panel-error {
color: var(--color-danger);
}
常用令牌族对照:
| 需求 | 令牌族 |
|---|---|
| 页面与面板表面 | --bg-*、--color-surface-* |
| 文本与标题 | --text-*、--headings-color、--label-color |
| 边框 | --color-border-*、--border-light-color |
| 链接 | --link-* |
| 图标 | --icon-*-color、--color-icon-* |
| 表单控件 | --input-* |
| 按钮 | --button-* |
| 状态 | --color-danger、--color-success、--color-warning |
| 集合(Collections) | --collection-* |
| 侧边栏、标签页、弹窗 | 各自命名的组件角色令牌 |
透明度处理:从既有语义色用相对 OKLCH 语法派生 alpha 色,禁止为透明度组合引入独立的 *-rgb 通道令牌:
background: oklch(from var(--color-primary) l c h / 17%);
box-shadow: 0 2px 6px oklch(from var(--black) l c h / 15%);
publii.css 中的阴影、侧边栏悬停覆盖层正是这一模式的实例,例如 light 方案下 --sidebar-link-bg-hover: oklch(from var(--white) l c h / 14%),保证侧边栏的半透明覆盖层在任何 workspace accent 下都能保持层级关系,而不嵌入具体色值。
私有调色板边界:--palette-brand-* 与 --palette-neutral-* 是私有输入,只能用 OKLCH 编写(审计脚本通过 oklchLiteralPattern 强制校验),仅供语义角色引用。组件中直接引用这些私有变量会被审计判为违规(Private palette token used outside its owner)。从 publii.css 可见,语义角色全部通过 var(--palette-...) 间接引用,例如 --color-primary: var(--palette-brand-55)。
新增颜色令牌前必须执行的检查清单:
- 先确认是否已有语义角色可描述该用途;
- 仅当角色是共享的、随应用外观变化的、或属于既定的可复用基础时,才新增全局角色;
- 在 light 与 dark 两套 scheme 块中都定义该角色;
- 组件消费语义角色,调色板变量保持私有;
- 若新角色改变视觉契约,更新
DESIGN.md; - 运行
npm run audit:design-system。
特别注意:不能通过随意提高 design-system-baseline.json 中的颜色字面量基线来"让审计通过"——该文件记录的是已接受的存量债务,不是可供新 UI 使用的颜色清单。审计脚本会把新增的颜色字面量(hex/rgba/hsla/oklch)与基线逐文件、逐色号比对,任何新增都会报 New owned color literal。
间距:共享间距刻度
当精确值存在时,margin、padding、gap 必须使用共享刻度:
| 令牌 | 值 |
|---|---|
--space-1 |
0.25rem |
--space-2 |
0.5rem |
--space-3 |
0.75rem |
--space-4 |
1rem |
--space-6 |
1.5rem |
--space-8 |
2rem |
--space-12 |
3rem |
--space-16 |
4rem |
.toolbar {
display: flex;
gap: var(--space-4);
margin-bottom: var(--space-8);
padding: var(--space-6) var(--space-8);
}
--space-unit(0.25rem)可用于比例计算。1.3rem 这类数值只有在"是有意光学修正、改变它会破坏当前布局"时才允许局部保留。高度、宽度、偏移、图标尺寸等结构测量值,即使数值恰好落在间距刻度上,也不会因此升级为间距令牌。审计脚本的 spacingLiteralPattern 专门扫描 margin/padding/gap 声明中的 0.25/0.5/0.75/1/1.5/2/3/4rem 字面量,发现即报 Canonical spacing literal must use the shared scale。
排版
共享 UI 排版令牌示例:
.metadata {
font-family: var(--font-family-sans);
font-size: var(--font-size-ui-sm);
font-weight: var(--font-weight-regular);
line-height: var(--line-height-base);
}
可用的 UI 字号为 --font-size-ui-xs(1.2rem)、--font-size-ui-sm(1.3rem)、--font-size-ui-md(1.4rem)、--font-size-ui-lg(1.6rem)、--font-size-ui-xl(2.4rem);可用字重为 --font-weight-light(300)、--font-weight-regular(400)、--font-weight-medium(500)、--font-weight-semibold(600)、--font-weight-bold(700);行高基础为 --line-height-base: 1.5。这些具体数值均能在 publii.css 的共享视觉语言块中找到。
--font-family-serif 与 --font-family-mono 仅在内容角色确实需要时使用。持久化的编辑器字体偏好必须使用 sans-serif/serif 这类 CSS 通用值——因为编辑器文档可能不加载应用令牌表,跨文档的字体偏好不能依赖应用自定义属性。
形状、深度、动效与层级
- 圆角:普通矩形控件与容器统一使用
--radius-base(当前外观为 6px);圆形与完全圆润的控件可保留组件自有圆角。 - 输入框焦点环:字段用
--input-shadow-focus绘制焦点环、--input-shadow-invalid绘制非法环,两者共用同一内嵌形状,且非法环在聚焦时保持可见。在text-input、dropdown、file-select上设置invalidprop,组件会同时设置is-invalidclass 与aria-invalid;普通字段可直接写aria-invalid="true"或置于is-invalid包装内,由全局forms.css规则统一样式。 - 阴影:
--shadow-sm、--shadow-md、--shadow-list-hover对应文档化的抬升角色;--shadow-md-up专用于向上展开的ButtonDropdown变体,它在每个色彩方案中保留中等阴影的同时反转垂直偏移(见publii.css中--shadow-md-up的负向-2px/-10px定义)。无共享角色的独特效果应保持局部,不要扩充全局阴影令牌。 - 过渡:标准 UI 过渡使用
--transition-default(all .2s ease-out)。 - 层级:视口级表面使用命名
--layer-*令牌;数值z-index仅允许用于组件自有堆叠上下文内部的局部兄弟排序。ActionMenu中.action-menu.is-open { z-index: 20 }正是这种"局部数值"的合法用例。
应用外观(appAppearance)与工作区强调色(workspaceAccent)
四组术语不可混用
| 名称 | 含义 |
|---|---|
siteTheme |
生成网站(generated website)使用的主题 |
appAppearance |
Publii 应用的命名视觉预设 |
colorScheme |
解析后的应用 light 或 dark 方案 |
system |
解析为色彩方案的用户偏好 |
运行时外观属性必须通过 app/src/helpers/app-appearance.js 的 applyAppAppearance 应用。data-theme 保留为兼容性属性,新组件不得把它当作应用外观的所有者。从源码可见,applyAppAppearance 依次设置四个属性:data-theme(按 legacyTheme === 'dark' 解析为 dark/default)、data-app-appearance、data-color-scheme、data-workspace-accent,并对未注册的 appearance 与 accent 做归一化回退(未知值一律回落 default)。
每个 appAppearance 的完整契约
每个 appAppearance 在 appearances/ 目录下有一个文件名与注册值一致的 CSS 文件,必须定义:
- 在
data-app-appearance下定义的共享视觉语言令牌(排版、间距、圆角、过渡等 20 项,审计脚本以appearanceVisualTokens数组逐一核对); - 完整的
light语义与私有调色板契约; - 独立调优的同一份
dark契约; - 每个已注册的非默认
workspaceAccent的预览令牌与完整的 light/dark 私有品牌调色板覆盖。
以 publii.css 为例,其结构完全对应上述四项:共享视觉语言块 → light scheme 块(含 11 个 --palette-brand-* 与 15 个 --palette-neutral-* 私有色板、全部语义角色)→ dark scheme 块(独立调优的色板)→ 12 个 accent 各自的预览令牌与 light/dark 品牌色覆盖。审计会强制 light/dark 语义令牌集合完全一致(light-only appearance token/dark-only appearance token 报错),并强制 accent 覆盖只能修改品牌令牌(accent overrides a non-brand token 报错)。
workspaceAccent:按站点生效的品牌色覆盖
workspaceAccent 是按站点(per-site)的偏好。它只改变当前应用外观内部的私有品牌调色板,不改变中性色、状态色、排版、间距或组件契约,也永远不影响生成网站。默认 accent 使用外观的基础品牌调色板;缺失、废弃或不支持的持久化值归一化为 default。
Publii 的注册表依次注册前七个彩色 accent:default、indigo、violet、magenta、crimson、rose、orange,随后是更偏灰调的 emerald、petrol、navy、graphite、midnight 集合——与 app-appearance.js 中的 workspaceAccents 数组完全一致。设置 UI 必须保持注册表顺序,而不是维护第二份列表。
对比度门槛:每个新增的非默认 accent 必须通过自动化 WCAG AA 对比度检查,覆盖两套色彩方案下的语义控件与链接,包括正常态与 hover 态、dark 方案下的同步控件,以及可见的焦点指示。审计脚本内置了 12 组对比度检查对(如 light 下 --white 对 --palette-brand-55 的控件对比度 ≥ 4.5:1、dark 下 --palette-brand-50 对 --palette-neutral-60 的焦点指示对比度 ≥ 3:1),对比度计算基于 OKLCH 到线性 sRGB 的转换与相对亮度公式,逐 accent 强制执行。原始的默认蓝色是有文档记录的视觉兼容性例外,不得作为新 accent 的对比度目标。
如何新增一个应用外观
- 在
app/src/css/appearances/创建外观文件(文件名即注册值); - 在
app-appearance.js注册该外观及其支持的 accents; - 在
App.vue与prepare-editor-css.js中,让该文件在css-variables.css之后加载; - 运行 design-system audit。
组件不得要求外观专属的 class 或选择器覆盖——外观对组件完全透明。
共享组件体系
app/src/main.js 中通过 Vue.component(...) 全局注册的 basic-elements(p-button、btn-dropdown、action-menu、text-input、field、image-upload、progress-bar、progress-orb、overlay、icon、app-illustration、collection、collection-cell、collection-row、tabs 等)在 Vue 模板中全局可用,无需再次 import。下表汇总各组件的规范化视觉契约(组件文件中的 prop 校验器才是完整可接受值清单):
| 组件 | 当前视觉契约 |
|---|---|
p-button |
intent、appearance、size、width、layout;独立的状态布尔值 |
btn-dropdown |
intent="default|primary"、button-icon、preview-icon、is-reversed、disabled |
action-menu |
items 数组:{ label, value, icon, intent="default|danger", disabled, visible, onClick } 或 { separator: true };label;icon;size="default|small";align="left|right";disabled |
text-input |
原生 type;视觉 size="default|small";keyboard-blocked 与 invalid 布尔值 |
field |
spacing="normal|small";独立的 label 布局布尔值 |
image-upload |
size="default|small" |
progress-bar |
intent="default|success|danger|warning" |
progress-orb |
phase="idle|rendering|connecting|uploading|success|warning|error";数值 progress;独立 indeterminate 布尔值;message;size="default|small";appearance="default|flat" |
overlay |
appearance="default|drop-zone" |
icon |
命名 size;non-interactive 布尔值;需要时受控的自定义 class |
app-illustration |
白名单 name;可选 scale 与 translate-y;每个插图一个内联的、令牌驱动的 SVG symbol |
collection |
数值 columns |
collection-cell |
variant="titles|assignment|publish-dates|modification-dates|authors|actions|menu|identifier";对齐与尺寸 props 仅在异于默认时转为内联样式 |
collection-row |
语义行状态:main-author、expanded(展开行保留编辑行高亮) |
tabs |
orientation="vertical|horizontal";独立 scrollable 布尔值 |
空状态插图
每个插图在 app/src/assets/svg/svg-map-empty-states.svg 中只添加一次,base 名称需与 app-illustration 接受的名称一致。绘制值使用既有语义角色(如 --bg-secondary、--color-surface-*、--color-border-*、--color-text-faint、--color-primary)。因为所选 symbol 是内联渲染的,这些自定义属性会随当前应用外观与 workspace accent 自动更新。不要添加 -default/-dark symbol 对、硬编码主题选择器或主题切换监听器到组件中。
窗口命令
即时窗口管理命令不得放进 Application Settings。通用 New Window 命令保留在应用菜单;站点选择器拥有特定网站的上下文操作 Open in new window——它位于行的 action-menu 中,同时支持对网站名执行 Cmd-click(macOS)、Ctrl-click 或中键点击。两条路由都必须复用白名单内的 preload IPC 命令,由主进程校验可选网站标识、强制窗口归属并创建 BrowserWindow。
按钮(p-button):关注点正交分解
按钮的五个关注点完全独立:
| 关注点 | Prop | 可接受值 |
|---|---|---|
| 语义 | intent |
default、primary、danger、success |
| 表现 | appearance |
default、secondary、outline、popup-cancel、clean、clean-inverse、clean-muted、light |
| 尺寸 | size |
default、small、medium |
| 宽度 | width |
auto、quarter、half、full |
| 布局 | layout |
inline、bottom |
| 图标处理 | icon、icon-size、icon-only、icon-tone |
icon-size:xs、s(默认);icon-tone:default、primary |
| 状态 | 布尔值 | active、back、disabled、disabled-with-events、loading、square |
p-button 渲染原生 <button type="button">(见 Button.vue 模板首行),因此可用 Tab 聚焦、Enter/Space 激活。disabled 映射到原生 disabled 属性;disabled-with-events 保持控件可交互并暴露 aria-disabled;loading 暴露 aria-busy。键盘焦点通过 :focus-visible 显示共享 --input-border-focus 环(2px outline),指针点击不残留焦点或悬停样式。禁用态表面使用 --button-disabled-bg(light 下为 --palette-neutral-10,dark 保留其既有禁用背景),该角色与 popup-cancel 的悬停样式互相独立。
btn-dropdown 是拆分按钮:主操作与菜单开关是两个独立原生按钮,打开的下拉列表是 role="menu" 的原生 menuitem 按钮集合。任意部分按 Arrow Down 打开列表,Arrow Up/Down 在项目间移动,Home/End 跳转首尾,Escape 关闭并归还焦点到开关,Tab 关闭并继续移动焦点;键盘选中某项后焦点回到主操作,指针交互保持旧行为且不显示焦点环。
不要重建旧的空格分隔 type API,正确写法如下:
<!-- 正确 -->
<p-button
:onClick="createBackup"
intent="primary"
icon="plus"
:disabled="operationInProgress"
:loading="operationInProgress">
{{ $t('file.createBackup') }}
</p-button>
clean 是内联操作的文字按钮,使用链接角色;clean-muted 是置于主操作之下、用于 Cancel/OK 等关闭动作的低强调文字按钮,使用对话框取消角色 --popup-btn-cancel-color / --popup-btn-cancel-hover-color,因此不会与主操作或强调色竞争;popup-cancel 保留给对话框页脚,其表面与顶部边框(border-top: 1px solid var(--input-border-color))在那里才属于它。icon prop 自动启用前置图标布局,无需额外传 icon class 或状态;disabled 控制可用性,loading 控制预加载器;动态状态应放入相应布尔 prop,而不是条件变体字符串。
操作菜单(action-menu)
action-menu 是行级与卡片级操作的溢出控件:渲染一个仅图标的原生按钮,打开 role="menu" 的原生 menuitem 按钮列表,遵循与 btn-dropdown 相同的键盘模型(Arrow Down/Up 打开并在项目间移动、Home/End 首尾、Escape 关闭并归还焦点、Tab 关闭并继续、指针交互不显示焦点环)。打开的菜单在以下情况关闭:另一个菜单打开、文档 body 被点击、任何滚动发生或窗口尺寸变化。列表相对视口定位,因此滚动容器不会裁剪它,且在靠近视口底部时自动翻转到触发器上方。不要把触发器放在带 transform 或 will-change: transform 的祖先内——那会把该祖先变成列表的包含块(containing block)。这些行为都能在 ActionMenu.vue 的 open/close/updatePlacement 方法中找到源码依据。
用数据而非标记描述每个动作:
<action-menu
size="small"
:items="[
{ label: $t('menu.renameMenu'), value: 'rename', icon: 'edit', onClick: startRename },
{ separator: true },
{ label: $t('menu.deleteMenu'), value: 'delete', icon: 'trash', intent: 'danger', onClick: deleteMenu }
]" />
intent="danger" 是唯一的项目变体。disabled 与 visible(布尔值或函数)控制可用性。组件调用项目的 onClick 并同时以选中的 value 发射 select 事件。密集行内用 size="small";触发器位于容器左边缘时用 align="left"。触发器标签默认使用共享的 "Other options" 字符串,菜单归属具名对象时通过 label 传入。
提示对话框(confirm)
共享 confirm 对话框接受可选的纯文本 title,使用 popup-common.css 渲染为 h1。正文保持在 message 中,并提供 dialogLabel 以管理键盘与焦点行为。省略 title 保留既有纯消息布局。
可选的 link 对象(label、路由 to、可选 onClick)在消息下方添加导航链接:其回调先于导航执行,使调用方可以保留未保存的草稿;跟随链接会关闭对话框而不确认主操作。
对话框还接受可选 validate 回调配合 hasInput:回调接收当前值并返回 true 或错误消息;对话框在字段下方显示消息、保持打开,并在值一旦变化时清除消息。用它取代"关掉对话框再用 toast 报错"的做法:
this.$bus.$emit('confirm-display', {
hasInput: true,
message: this.$t('menu.provideNameForNewMenu'),
okLabel: this.$t('menu.createNewMenu'),
validate: name => this.validateMenuName(name),
okClick: name => this.addNewMenu(name)
});
表单值契约
dropdown、radio-buttons、switcher 以 v-model/value 作为唯一的值契约:
<dropdown
v-model="selectedProvider"
:items="providers" />
<radio-buttons
v-model="importType"
name="import-type"
:items="importTypes" />
<switcher v-model="enabled" />
不要在这三个组件上使用已退役的 selected 或 checked 初始化别名。switcher 是可键盘操作的 role="switch" 控件:可聚焦、暴露 aria-checked、Space/Enter 切换、disabled 时忽略输入、键盘聚焦显示共享 --input-border-focus 环。
checkbox 有意不同:它是受控的列表选择原语,仍使用 checked、value、on-click:
<checkbox
:value="item.id"
:checked="isChecked(item.id)"
:onClick="toggleItem" />
customCssClasses 仅在 schema 驱动的主题或插件设置需要扩展点时可用,不得作为创建组件变体的常规方式。
站点主题字段(themes-dropdown)
Site Settings 通过 themes-dropdown 选择网站主题,该组件读取 siteThemesState store getter。getter 将主题库(location: 'app')与当前网站的站点副本合并,并报告当前主题在库或 Publii 市场中是否有更新版本。下拉框始终是值控件:空值保留当前主题(占位选项会点名该主题)、use-<directory> 切换到既有站点副本、install-use-<directory> 将库中主题复制进站点或从库更新当前副本。选项描述状态而非动作,每个主题只出现一次。值通过常规设置保存由后端 changeTheme() 应用,字段在变更待定时显示提示。
命令放在字段旁:"Update to v.X" 按钮只选中更新选项;action-menu 的 "Reinstall install-use-<directory> 值,下拉框仅在待定期间把它列入 "Reinstall" 下。字段的 action-menu 还负责:把主题文件安装进库(共享 ThemeUpload mixin;组件可定义 themeUploadedHint(data) 向成功 toast 追加下一步)、打开主题库、打开市场、移除未使用的站点副本。移除是破坏性操作,必须先经共享 confirm 对话框确认,再调用专用 app-site-theme-remove IPC(只删除未使用副本、绝不删除当前主题)并返回刷新后的主题列表;设置表单本身不被保存。市场更新用 msg msg-small msg-icon msg-info 块及其下载/安装链接报告;通知流的 free 标志决定链接是直接下载还是打开市场账户下载页。不要把动作动词加回选项列表。
同步指示器(progress-orb)
progress-orb 是同步弹窗的阶段感知活动指示器(实现见 ProgressOrb.vue):
- 通过校验过的
phase每次只显示一个阶段; - 数值
progress在圆环中保持真实进度可见(基于 r=60 圆的周长 377px 计算strokeDashoffset); - 独立
indeterminate布尔值把圆环切换为旋转弧; message在圆盘下方打印阶段文本,与progress-bar消息角色相同;- 绘制部分是
aria-hidden,消息是它唯一的文本。
它使用空状态插图的绘制材料:圆盘用 --bg-secondary、--color-surface-subtle、--color-border-muted,而光晕、阴影、圆环、图标与粒子从 --color-primary 与状态角色通过相对 OKLCH 与 color-mix() 派生——因此指示器无需覆盖即可跟随 workspace accent 与色彩方案。其动效仅用 CSS 的 transform 与 opacity,并在 prefers-reduced-motion 下停止(样式块末尾的 reduced-motion 媒体查询覆盖了 glow、disc、ring、trace、particles 与消息 shimmer)。调用方拥有周围布局:通过 class 传外边距,不要重排其内部。
appearance="flat" 只保留圆环与传入图标,用于预览准备、缩略图重新生成等紧凑布局;两者都用 progress-status.css 承载 orb、标题、百分比与状态文本。flat 的 idle 态保持中性。重新生成从页面头部启动,小型 Cancel 操作位于状态面板右侧、百分比之下;运行开始时焦点从头部操作移到 Cancel,结束时归还。取消的运行保留已处理计数与静态中性 orb,"Regenerate again" 开启新运行。
同步弹窗把自身状态映射到阶段:同步开始前 idle、站点生成中 rendering、首个上传进度到达前 connecting、之后 uploading,随后 success;带问题完成的同步为 warning;连接或渲染失败为 error。最小化弹窗因悬浮于侧边栏之上而保留 progress-bar。
集合(Collections)
父级提供列数,单元格提供经校验的视觉角色,行暴露语义状态:
<collection :columns="4">
<collection-row
v-for="item in items"
:key="item.id"
slot="content"
:main-author="item.id === 1">
<collection-cell variant="titles">
{{ item.name }}
</collection-cell>
</collection-row>
</collection>
对主作者,:main-author="true" 使 CollectionRow 应用其内部 is-main-author class。消费者表达语义状态,共享组件拥有 CSS class。
遗留 API 迁移参考
新代码不得引入遗留形式——自动化审计会拒绝已退役的组件 props(legacyComponentProps 映射中列出了 p-button type、collection itemsCount、dropdown selected 等 16 组禁用项)。完整迁移对照:
| 遗留 API | 当前 API |
|---|---|
p-button type="primary" |
intent="primary" |
p-button type="green|success" |
intent="success" |
p-button type="danger|error|delete" |
intent="danger" |
p-button type="secondary" |
appearance="secondary" |
p-button type="outline" |
appearance="outline" |
p-button type="cancel-popup" |
appearance="popup-cancel" |
p-button type="clean" |
appearance="clean" |
p-button type="clean-invert" |
appearance="clean-inverse" |
p-button type="light" |
appearance="light" |
p-button type="small|medium" |
size="small|medium" |
按钮 type 中的 quarter-width/half-width/full-width |
width="quarter|half|full" |
按钮 type 中的 bottom |
layout="bottom" |
按钮 type 中的 preloader |
:loading="condition" |
按钮 type 中的 disabled、disabled-with-events、active、back |
相应布尔 prop |
按钮 type 中的 no-border-radius |
square 布尔 prop |
按钮 type 中的 icon |
由 icon prop 派生 |
按钮 type 中的 only-icon |
icon-only 布尔 prop |
按钮 type 中的 only-icon-color |
icon-only + icon-tone="primary" |
btn-dropdown buttonColor="green" |
intent="primary" |
btn-dropdown type="is-reversed" |
is-reversed 布尔 prop |
text-input properties="is-small" |
size="small" |
text-input properties="keyboard-blocked" |
keyboard-blocked 布尔 prop |
text-input/dropdown/file-select 上的 ariaInvalid 或 :class="{ 'is-invalid': … }" |
invalid 布尔 prop(同时设置 class 与 aria-invalid) |
image-upload type="small" |
size="small" |
icon properties="not-clickable" |
non-interactive 布尔 prop |
collection itemsCount |
columns |
collection formIsOpened |
已移除;无替换 |
collection-cell type |
variant |
collection-row cssClasses |
命名语义状态 prop,目前为 main-author |
dropdown selected |
v-model / value |
radio-buttons selected |
v-model / value |
switcher checked |
v-model / value |
tabs isHorizontal |
orientation="horizontal" |
tabs isScrollable |
scrollable 布尔 prop |
overlay hasBorder + isBlue |
appearance="drop-zone" |
progress-bar color="blue|green|red|orange" |
intent="default|success|danger|warning" |
progress-bar stopped |
已移除(无视觉行为) |
fields-group type="danger" |
已移除未使用变体;需要状态传达时使用显式状态组件 |
separator type 是有意的临时例外:它的值可能来自持久化的主题与插件设置 schema。不要把这个字符串 API 复制到其他组件;其规范化需要跨所有持有者的带版本 schema 迁移。
作用域边界
- 应用设计令牌属于 Publii 渲染器;生成站点主题必须使用自己的主题契约;
- 外部插件选项样式不受应用令牌文件自动约束;
- 编辑器自有 CSS(
app/src/css/editor/)、块编辑器内部、文章编辑器内部与 vendor CSS 仍处于组件规范化阶段之外; - 共享编辑器 chrome 可以消费应用语义令牌,但编辑器内容的排版与布局仍独立所有;
- 保持 Electron 渲染器的安全边界不变:UI 工作不得启用 Node integration,也不得绕过 preload 桥接(这正是
app-preload.js存在的意义)。
扩展体系
当新行为与既有原语具有相同语义角色时,优先扩展现有原语。只有代表可复用 UI 契约时才在 app/src/components/basic-elements/ 新增组件;屏幕专属组合留在其所属视图。
一个共享组件必须满足:
- 在适用时,为语义、表现、尺寸、布局与状态暴露分离的、带类型的 props;
- 校验每个字符串枚举(可参考
Button.vue中每个枚举 prop 的validator写法); - 拥有其内部 CSS class,而不是要求消费者拼装 class;
- 使用语义令牌,且无需视图级主题覆盖即可支持两套色彩方案;
- 对值控件保持
v-model约定; - 仅当意图全局可用时注册到
app/src/main.js; - 新增或变更公开视觉契约时更新本指南。
不要为了"可能有用"添加兼容性 prop——除非外部或持久化数据阻止原子迁移;每个兼容性例外都必须记录所有者和移除条件。
验证与提交前检查
在仓库根目录依次运行:
npm run audit:design-system
npm test
npm run prod
按改动规模按比例使用:
- 每次渲染器样式或共享组件改动:
npm run audit:design-system; - 合并前:
npm test(它包含 design-system audit 与后端测试,package.json中test脚本以npm run audit:design-system && mocha ...开头); - 修改共享令牌、原语、应用外观行为或 webpack 可见的样式 import 后:
npm run prod(生产渲染器构建是最终的结构性验证); - 影响共享视觉角色或组件时:在 light 与 dark 两套方案下做运行时 QA。
提交 pull request 前确认:
- UI 在适当处复用了既有共享组件;
- 新组件行为由类型化 props 而非 class 字符串表达;
- 组件 CSS 使用语义角色而非调色板值或新字面量;
- light 与 dark 定义了相同的共享语义角色集合;
- 间距与排版在精确值适用处使用规范令牌;
- 公开契约变更时已更新
DESIGN.md与本指南; - design-system audit 通过。
小结
Publii 的设计系统是一条完整闭环:DESIGN.md 定义视觉契约 → css-variables.css 提供 appearance 无关的技术基础 → appearances/publii.css 提供每个外观的完整语义与私有调色板 → basic-elements 组件以类型化 props 消费语义令牌 → app-appearance.js 独占运行时外观属性 → audit-design-system.js 以十余类检查(未解析令牌、遗留令牌、私有调色板越界、light/dark 对等性、accent 对比度、颜色字面量基线、间距与排版字面量、遗留 props)守住契约。对开发者而言,把"按角色选令牌、用 props 表达语义、私有调色板不进组件、外观属性单一所有者、提交前跑审计"这五条原则内化为日常习惯,就能在 Publii 的渲染器中写出既符合设计契约、又经得起自动化验证的 UI 代码。