Publii UI 开发指南:从 CSS 设计令牌到共享组件的设计系统落地实践

原创2026-10-15 15:55:361,685 阅读
文章标签:开发工具前端

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/ 目录。

工作规则:七条铁律

  1. 先复用共享组件,再考虑新增视图局部控件或 class;
  2. 用 props 表达组件语义,禁止把空格分隔的 class 名当作"变体 API";
  3. 组件中使用语义化 CSS 令牌,禁止在 appearance 文件之外消费私有 --palette-* 变量;
  4. 每个应用外观的 light/dark 两套 scheme 中,语义令牌名必须保持一致,字面值由各 scheme 各自拥有;
  5. 一次性光学修正与结构尺寸保持局部化,不为每个数字创建全局令牌;
  6. 组件不得直接修改 data-theme、data-app-appearance、data-color-scheme、data-workspace-accent 这四个属性;
  7. 提交渲染器 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)。

新增颜色令牌前必须执行的检查清单:

  1. 先确认是否已有语义角色可描述该用途;
  2. 仅当角色是共享的、随应用外观变化的、或属于既定的可复用基础时,才新增全局角色;
  3. 在 light 与 dark 两套 scheme 块中都定义该角色;
  4. 组件消费语义角色,调色板变量保持私有;
  5. 若新角色改变视觉契约,更新 DESIGN.md;
  6. 运行 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 上设置 invalid prop,组件会同时设置 is-invalid class 与 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 文件,必须定义:

  1. 在 data-app-appearance 下定义的共享视觉语言令牌(排版、间距、圆角、过渡等 20 项,审计脚本以 appearanceVisualTokens 数组逐一核对);
  2. 完整的 light 语义与私有调色板契约;
  3. 独立调优的同一份 dark 契约;
  4. 每个已注册的非默认 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 的对比度目标。

如何新增一个应用外观

  1. 在 app/src/css/appearances/ 创建外观文件(文件名即注册值);
  2. 在 app-appearance.js 注册该外观及其支持的 accents;
  3. 在 App.vue 与 prepare-editor-css.js 中,让该文件在 css-variables.css 之后加载;
  4. 运行 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 from your theme library"(当库持有同版或更旧版本时提供)选中同一个 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 代码。

登录后查看全文
Publii