Files
feresaria/docs/development/visual-direction.md
T

25 KiB
Raw Blame History

Ferese Graphite 视觉方案

  • 文档版本:1.5
  • 整理日期:2026-10-28
  • 视觉基线:1e34ec4、9908dde、3264659、6671960;本版补充全部设置分类与窗口缩放的性能检查。
  • 适用范围:Ferese 设置、Shell 共享控件、锁屏与原生 Rime 候选界面的主题协同。

1. 视觉目标

以中性表面、细边界和清晰排版建立界面层次,让配置内容和操作状态成为视觉重点。

  1. 中性底色:使用石墨灰与纸白两种外观,通过相邻表面的明度差区分区域。
  2. 少量强调色:将颜色集中在选中、键盘焦点、开关与状态提示上。
  3. 统一节奏:统一页边距、分组间距、图标尺寸和导航行高。
  4. 文字分层:用字号、字重和次级文字颜色区分标题、说明与辅助信息。
  5. 克制装饰:降低光晕、玻璃染色和阴影的存在感,保留必要的层次提示。
  6. 状态清晰:分别表达悬停、按下、选中、键盘焦点和禁用状态。
  7. 紧凑但舒展:减少重复说明、强制换行和无用途的空白;将空间留给设置行、卡片之间的适度间距。

2. 参考视频分析

参考文件:ir9g5tra15711hQD.mp4,时长约 9.78 秒,2168 × 2160,60 fps。

视频展示的是界面重设计过程。可提取其配色、布局和排版原则;剪辑中的变化速度不能用于确定真实交互的延迟、缓动曲线或动画时长。

视频阶段 可观察的变化 在 Ferese 中的落地
0–3 秒 调整导航、卡片与标题间距,统一对齐关系 建立主要间距尺度,统一导航行高和页面边距
3–5 秒 紫色光晕和高饱和背景逐渐收敛为中性表面 新增 Graphite 深浅主题,降低染色与阴影强度
5–7 秒 换用细线图标、缩小品牌标识、简化选中态 使用小型轮廓图标、中性选中底色与细指示条
7–9.78 秒 通过排版与内容形成层级,颜色集中在有意义的信息上 保留 MiSans,统一标题字重、说明文字和状态色使用方式

3. 主题与配色

主题族 ID 为 graphite。深色预设 ID 为 graphite,浅色预设 ID 为 graphite-light;通常选择主题族后,通过外观模式切换深浅。

3.1 基础色板

下表是预设源值。实际绘制颜色经过共享主题解析与对比度校正,组件应消费解析后的主题令牌,避免各自复制一份色值。

角色 深色 浅色
基础表面 / 侧栏 #101113 #F7F8FA
抬升表面 #1B1D21 #FFFFFF
应用背景 #141518 #F1F3F5
主要文字 #E7E9ED #23262C
次级文字 #9A9FA9 #626A76
强调色 #8EABD8 #3F6DAA
边界基色,含透明度 #FFFFFF16 #00000018

边界与控件底色会结合当前背景和文字颜色派生。普通分区采用细边界与轻微明度差;高对比度模式加强边界与文字校正。

3.2 材质参数

参数 深色 浅色
材质不透明度 0.96 0.98
模糊半径 8 4
染色强度 0.06 0.02
阴影不透明度 0.12 0.08

这些数值由主题和组件共同解释。设置应用的正文表面保持清楚稳定;Shell 等支持材质的组件使用对应材质令牌。

导航选中背景采用中性色。用户明确选择的渐变主题,继续通过现有主题机制作用于相关控件和窗口焦点。

4. 字体与图标

4.1 字体层级

界面使用 MiSans;Rime 候选优先使用 MiSans / MiSans TC。

角色 逻辑字号 字重 / 用法
页面标题 16 px Medium,比分组标题大 2 px
分组标题,含侧栏和详细页 14 px Bold
总览卡片标题 14 px Regular
侧栏导航、普通字段名称 13 px Regular
字段补充说明与辅助提示 10.5 px Regular、次级色,与 13 px 字段名称明确区分
卡片说明、代码编辑器 11 px Regular
保存状态 11 px Regular、次级色

字段名称与短说明在同一段内自然排版,仅在可用宽度不足时换行;说明使用次级色区分,不另起固定的一行。页面标题下不重复展示泛化副标题。卡片高度跟随实际内容,适应中英文;细则与控件文字均使用标准字重。

4.2 图标

  • 品牌标识:24 px。
  • 页面与导航轮廓图标:19 px。
  • 小型操作图标、卡片箭头:16 px。
  • 普通图标使用主要或次级文字色,选中导航图标使用强调色。
  • 图标与同行文字垂直居中;卡片箭头固定在行的末端。

5. 间距与形状

本文的 px 均指逻辑像素,截图中的物理像素会随显示缩放变化。

以 4 px 为主要间距基准;文本行间距、细边界和字形光学校正允许采用更细的数值。

项目 规格
页面上 / 下边距 16 / 12 px
页面左右边距 20 px
总览及详细页分组间距 20 px
分组标题与设置容器间距 10 px
同组卡片间距 16 px
卡片内部边距 16 px
卡片图标与文字间距 12 px
卡片标题与说明间距 4 px
设置行内边距 上下 12 px、左右 14 px
设置行标签与控件间距 12 px
同组设置行间距 4 px
侧栏宽度 208 px
折叠侧栏抽屉宽度 244 px
侧栏内边距 上下 24 px、左右 12 px
导航按钮高度 36 px
导航按钮左右内边距 8 px
导航行内元素间距 8 px
选中指示条 2 × 14 px
普通输入框圆角上限 7 px
设置按钮圆角上限 5 px
按钮组圆角上限 6 px
按钮组内边距 5 px
选项按钮内边距 上下 6 px、左右 10 px;页内标签为 8 / 14 px
导航滚动条 宽 4 px,与选项间隔 8 px,单独占位
分区容器圆角上限 10 px
常规边界 1 px
键盘焦点轮廓 2 px

圆角上限受现有主题圆角设置约束,方角等用户偏好继续生效。

6. 设置总览与自适应布局

Appearance 作为全部设置的入口,内容按实际功能分组:

分组 入口
快速访问 常规、全部配置
桌面 主题、壁纸、面板与 Shell、托盘图标
交互 窗口、键盘与鼠标、辅助功能
系统 显示器、连接、通知、日历、锁屏、登录启动项

总览使用等宽卡片,文字区域占用弹性空间,箭头在卡片末端对齐。

  • 总览可用内容宽度 ≥ 680 逻辑像素:双列。
  • 总览可用内容宽度 < 680 逻辑像素:单列。
  • 窗口宽度 < 960 逻辑像素:侧栏收起,通过按钮打开导航抽屉。
  • 页面内容框最大宽度为 1280 px,包含左右各 20 px 的留白;更宽窗口居中显示内容框。
  • 卡片高度由内容决定,说明换行后保持完整显示。
  • 超出视口的内容通过滚动访问,保存状态与撤销、重新加载操作位于页脚。

卡片列数依据正文可用宽度计算,侧栏折叠依据窗口宽度计算,二者使用独立阈值。

6.1 详细页分组

设置进入详细页后,继续按功能组织,分组标题采用 14 px 粗体,设置名称与细则采用标准字重。分组随实际字段出现,避免空组。

详细页 主要分组
常规 界面
日历 日期显示、日本祝日、自定义节假日
窗口 工作区与布局、间距与圆角、焦点与窗口效果
键盘与鼠标 键盘布局、按键重复、鼠标、触控板
主题 配色与强调色、表面与透明度、字体与排版;自动外观按需展开
辅助功能 视觉辅助、动画
通知 通知行为、通知时长
锁屏 时钟与日期、锁屏背景、显示器电源,按支持的配置出现
托盘图标 应用托盘、应用图标、面板状态图标
快捷键 快捷键指南、自定义快捷键

显示器、连接和面板编辑器延续各自已有的功能分区;登录启动项按应用组织。窗口效果预览放入对应分组,高度收至 84 px,避免独占页首的大块空间。

6.2 留白与窗口操作

  • 双击页面顶部、底部、左右边缘及超宽窗口外侧的留白,切换最大化与还原;标题区域和侧栏未被控件占用的区域同样支持。
  • 在上述区域移动指针超过拖动阈值后开始拖窗,单击不立即拖动。
  • 设置内容与控件遵循自身交互,双击字段标签不会触发最大化。
  • 窄窗口导航抽屉通过点击右侧空白或按 Esc 关闭;移除独立的“关闭导航”按钮。

7. 组件状态与对齐

状态 视觉表达
普通 中性表面、细边界、正常文字对比度
悬停 轻微改变底色明度,保持几何位置稳定
按下 比悬停更明确的明度或色彩反馈
选中 中性选中底色,配合小面积强调色;导航显示左侧指示条
键盘焦点 明确的 2 px 焦点轮廓,与选中态分别表达
禁用 使用次级文字与图标颜色,保持状态可辨认
高对比度 加强边界,并校正文字颜色以保持可读性

7.1 导航垂直居中

导航需要同时满足两层对齐:

  1. 图标、文字与指示条在内容行内部垂直居中。
  2. 整个内容行在 36 px 按钮及悬停区域内垂直居中。

原生自定义按钮会从上内边距放置子内容,因此仅设置行内居中,会使整行仍处于按钮上方。实现中增加填满按钮高度的居中容器,确保普通、悬停、选中和焦点状态使用同一条中心线。

7.2 Rime 候选界面

  • 候选横向排列,使用 MiSans 字体。
  • 编号、中英文候选字按实际字形边界进行垂直居中。
  • 背景、边界与选中态通过共享主题保持一致。
  • 保留数字键选字以及数字行 -、= / + 翻页的既有行为。

7.3 导航、按钮组与本地化

  • 导航滚动条嵌入独立通道,绘制区域和点击区域均不覆盖导航项。直接打开靠下的页面、切换页面及打开抽屉时,将当前选项完整滚入视口。
  • 按钮组与内部按钮使用保留少量圆角的矩形。组背景采用轻微表面差,扩大内边距,避免形成明显的厚重外框。
  • 标准设置名称、说明、枚举、面板项目、连接操作和提示通过统一语言目录显示。配置键、动作标识、应用名、SSID 和用户内容保留原值。

7.4 时间入口与通知标记

  • 时间右侧紧邻通知标记,二者保持紧凑间距。标记为 3 × 13 px、圆角 1.5 px 的竖条;点击区域固定宽 11 px。
  • 有通知时竖条为白色,无通知时透明,状态变化不改变布局宽度。点击仍可打开通知历史。
  • 移除独立控制中心、Wi-Fi 和夜光快捷图标。旧面板配置在显示时合并时间相关入口,保留其余项目的 ID、可见性和自定义内容。
  • 点击时间打开组合组件:上方日历,下方控制中心。控制中心保留外观、网络、蓝牙、音量、亮度与电源管理,移除夜光和勿扰开关。
  • 音量区显示当前输出设备、百分比、音量滑块与明确标注的静音开关;设备暂不可用时显示简短状态。
  • 电源区按设备能力显示节能、均衡、性能模式,以及重启、关机、挂起操作。重启、关机、挂起先打开确认弹窗;取消保持当前会话。
  • 常规组合弹层宽 360 px,高度随内容变化并受可用空间限制;内容过长时可滚动。Morph 样式同步提供组合内容。

7.5 活动窗口区

  • 活动窗口区位于面板右侧、系统托盘区左边,与工作区显示空间独立。排列所有已打开窗口,每个窗口一个应用图标,关闭窗口即移除;不保留已关闭应用的固定图标。
  • 点击图标切换到对应窗口,支持同一应用的多个窗口和跨工作区切换。以启动顺序保持稳定位置,突出当前焦点窗口。
  • 图标 18 px,按钮宽 30 px,间隔 2 px;悬停显示窗口标题,标题为空时使用应用标识。窗口过多时在分配宽度内横向滚动,默认最大宽 360 px。
  • 面板编辑器可添加、隐藏、移动“活动窗口”项目;旧预设在合并时间入口时补齐该项目,新配置中主动移除后不会自动恢复。

7.6 日历与祝日函数

  • 每周从周日开始;星期标题随 Ferese 语言变化,中文为“日、一、二、三、四、五、六”,英文为 Sun 至 Sat。
  • 日本祝日和自定义节假日的日期使用红色粗体,悬停可查看名称;当前日期底色与节假日文字样式分别表达。
  • 默认显示相邻月份的日期,在“日历 → 日期显示”中可关闭。开关不改变本月日期的列对齐。
  • “日历 → 日本祝日”右侧仅提供代码图标作为函数编辑入口。点击展开 280 px 高的多行编辑器;未应用代码在收起、再次打开后继续保留。
  • 编辑器提供“应用函数”和“恢复内置函数”。恢复只替换编辑内容,仍需应用;语法或日期结果错误时保留草稿和诊断,当前日历继续使用已保存函数。
  • 内置源为 japanese-holidays.rhai,入口 japanese_holidays(year) 返回 YYYY-MM-DD → 名称 映射。辅助函数为 date(year, month, day)、weekday(date)(周日为 0)、add_days(date, n)、days_in_year(year) 和 floor(value)。
  • 规则包含历史制度调整、振替休日、夹在祝日间的休日、即位等特例,以及 2020 / 2021 年奥运调整。适用范围为 1955–2099 年;已与内阁府公布的 1955–2027 年全部 1067 条日期和名称核对一致。未公布年份按规则推算,春秋分日以官报公布为准。
  • 解释器离线运行,禁用导入与动态求值,并限制代码长度、运算量、调用深度和容器大小。编译结果和年度结果缓存,函数校验在后台执行。
  • 自定义节假日支持 YYYY-MM-DD 单次日期和 MM-DD 每年重复;同一天可同时显示日本祝日与个人节假日名称。

来源:内阁府祝日资料、国立天文台春秋分日说明、Rhai 运算限制。官方快照作为回归校验资料,日历运行时使用可编辑函数。

7.7 内容载入与绘制

  • 主题预览由原生矩形、圆角和线条绘制,保留浅深配对、当前外观指示和选中标记;布局阶段不再生成与窗口尺寸相关的 SVG。主题与快捷键列表继续按可见行挂载。
  • “全部配置”在首次进入或搜索时异步查询 schema,同一请求在完成前只执行一次。成功结果以不可变快照缓存;失败可重试;查询返回时使用最新配置并保留搜索内容。
  • 显示器、连接、托盘应用与壁纸继续使用各自的后台读取或缩略图任务。新增页面应先显示内容结构和载入状态,将耗时采集放到后台,避免在视图构建、布局或绘制回调里执行子进程和文件解析。
  • 显示器查询合并进行中请求,成功或失败返回后 1 秒内的自动访问复用结果,保留原有 2 秒轮询。托盘应用查询使用 2 秒短时缓存和 3 秒总超时;失败保留上次成功列表。手动刷新绕过缓存有效期,但不会叠加进行中请求。
  • 面板预览在配置解析时保留规范化数据,仅在面板字段编辑后更新,避免每帧重复反序列化。启动时的主题快照在初始化中复用;手动重新载入配置使用后台任务,结果不会覆盖请求之后的新编辑。
  • 窗口布局示意图使用缓存矢量几何,保留原有渐变、曲线、颜色、描边和比例;布局参数或主题改变时更新缓存。最大化与还原保持同一示意图尺寸时复用几何。
  • 设置控件保留稳定 ID,使异步数据刷新、可见行挂载和页面切换保持键盘焦点与未提交输入。

8. 动效原则

保留现有动画与“减少动画”配置。动效服务于状态变化与空间关系,悬停和按下反馈保持简洁。

参考视频没有提供可验证的交互时长或缓动参数,因此本轮视觉方案没有新增动画时长或缓动曲线。窗口操作按 6.2 节执行。

9. 配置示例

theme {
    family "graphite"
    mode "dark"
    typography {
        font-family "MiSans"
    }
}

将 mode 改为 "light" 可使用同一主题族的浅色外观。现有其他主题仍可从“外观与设置 → 主题”切换。

status {
    calendar {
        show-adjacent-days #true
        custom-holidays "12-24" "个人假日"
    }
}

祝日函数通过设置编辑,保存在 status.calendar.japanese_holiday_function;未覆盖时使用内置函数。

10. 验收与实现索引

验收要点

  • 深浅外观均能区分背景、分区、文字和操作状态。
  • 鼠标悬停与按下不会导致文字或图标跳动。
  • 选中态与键盘焦点分别清楚可辨。
  • 导航文字、图标和指示条相对完整按钮区域居中。
  • 窄窗口单列、宽窗口双列,所有设置入口均可到达。
  • 中文与英文换行后,卡片内容完整且互不重叠。
  • 页面标题比分组标题大 2 px;分组为粗体,设置名称和细则为标准字体。
  • 详细页按功能分组,短说明自然流动,不保留重复副标题和大型装饰留白。
  • 双击边缘留白能最大化和还原,设置控件不会误触发;导航抽屉保留外侧点击和 Esc 关闭。
  • 原生 Rime 候选保留横向排列、选字、翻页与主题跟随。

已完成的验证

本版密度与交互修订:

验证项 结果
设置测试 128 项通过,10 项可选检查默认跳过
滚动渲染专项 额外运行 1 项通过,覆盖 WGPU / tiny-skia 与两种主题配置
配置测试 51 项单元测试及 11 项集成测试通过
共享主题 / 面板 / Shell 34 / 69 / 253 项通过
布局检查 覆盖 480–1800 px 窗口宽度
原生预览 已检查深浅外观及 631 px 窄窗口
导航居中 全部 16 项;包含独立滚动条通道检查
Rime 原生输入、候选、翻页、主题变化与进程恢复通过
边缘双击 原生预览内 1272 px 最大化与 631 px 还原双向切换通过,配置内容不变
导航抽屉 已移除关闭按钮,外侧点击和 Esc 关闭均检查通过
时间控制面板 原生预览显示真实音频输出、音量与静音控件、电源模式;关机确认后取消,会话保持运行
活动窗口区 位于右侧托盘左边;三个窗口点击、相邻图标切换、跨工作区激活、关闭移除与重新打开均通过
祝日函数 原生编辑并应用函数可改变日历;无限循环被拒绝且保存配置不变,恢复内置函数后配置校验通过
通知标记 独立预览中创建并移除测试通知,检查白色与透明状态,点击区域宽度保持不变
原生主题预览 检查配对颜色、透明外角和选中标记图层顺序;保留比例与键盘导航
后台 schema 将查询人为延迟 2 秒,窗口提前显示载入状态;结果完成后显示选项,查询只执行一次;覆盖失败重试与最新配置接续

滚动渲染专项记录沿用前版 9908dde;边缘双击与窄窗口抽屉本轮再次检查通过。本版原生检查使用独立嵌套预览,保留原预览中的应用;没有重新执行关机、挂起或切换实际桌面会话。主机显示器、默认应用关联和 GNOME 输入源配置与开始时一致。

性能采样

2026-10-28 在本机同一隔离嵌套会话对比 3264659 与本次修订,均为调试构建。原生设置窗口为 1272 × 760 逻辑像素、2 倍缩放;每个程序首次进入主题页一次,再切换三次。原生指标为页面切换至首个重绘回调的时间,不等同于显示器扫描呈现延迟。

指标 原实现 优化后
原生主题页首次重绘 243.3 ms 15.1 ms
原生主题页后续切换中位数 14.0 ms 10.8 ms
WGPU 主题滚动绘制与读回 P95 163.9 ms 3.75 ms

滚动采样使用相同的 1000 × 780 逻辑视口、1.25 倍缩放及 48 帧往返滚动,跳过最初 8 帧。软件回退的主题绘制 P95 仍约 304 ms,本轮未进一步调整其共有绘制成本。把 schema 查询人为延迟 2 秒时,约 765 ms 已显示载入界面,随后补齐选项;请求仅执行一次。

性能、原生界面与后台载入记录位于 .artifacts/settings-performance-20261028/,与此前验收资料分开保存。另保留主题键盘选取、配置写入与恢复检查,以及配对颜色、透明外角和选中标记的像素回归。

全部分类与最大化 / 还原

随后以 6671960 为基线,检查全部 18 个页面(包含动效、快捷键子页)。同一配置、WGPU、2 倍缩放,每页测量首次构建、稳定帧、10 次往返尺寸变化及 4 次切换,共 324 帧;尺寸为 1272 × 760 与 631 × 568 逻辑像素。连接、托盘和三屏数据使用固定模型,异步硬件查询另由请求合并测试和原生预览检查覆盖。

指标(中位数,调试构建) 基线 优化后
窗口页尺寸变化:绘制与 GPU 读回 28.52 ms 8.35 ms
窗口页尺寸变化:构建、布局、绘制与读回总计 49.64 ms 29.32 ms
面板页稳定帧:构建与布局 2.20 ms 1.66 ms
面板页重复切换:构建与布局 2.15 ms 1.47 ms

其余分类重复切换的构建与布局中位数约 0.69–1.63 ms,没有发现同类 SVG 渲染尖峰。完整尺寸变化仍需重新排版文字,各页约 6–21 ms;首次进程的字体和渲染器初始化成本仍存在。这些读回指标用于实现对照,不代表物理屏幕的呈现延迟,也不表示每个页面都获得同等加速。

54 张相同尺寸的页面图像对照中,52 张逐像素一致;窗口页的两张宽窗口图仅有矢量替换差异,平均每通道误差约 0.071 / 255。独立示意图对照的平均每通道误差约 0.023 / 255,涵盖描边缩放和 SVG 渐变坐标的保持。请求合并、失败重试、预览缓存失效和后台重新载入期间的新输入保护均有回归检查。

独立嵌套会话中,18 页各切换两次,切换到首个重绘回调为 3.0–19.8 ms,两轮中位数分别为 7.9 / 7.4 ms。窗口页原生最大化 / 还原各测 12 次:新尺寸内容提交的中位数为基线 37.1 ms、优化后 35.2 ms,包含 IPC 轮询误差,未显示明显的原生提交延迟改善。视觉动画结束约 413 ms,保持原有动效;它与客户端绘制耗时分别记录,不以缩短动效替代渲染优化。

手动重新载入另用隔离配置和仅测试进程使用的读取拦截器人为延迟 2 秒:基线的读取线程就是界面主线程,新版的读取发生在工作线程。约 0.88 秒时,新版已经切换并显示主题页,基线仍等待读取。两版测试实例随后关闭,拦截器不用于保留的开发预览。预览运行程序的 SHA-256 与本次构建一致,检查前后配置的 SHA-256 一致。

本轮记录位于 .artifacts/settings-audit-20261028/,包含逐帧数据、前后图像、原生分类与窗口尺寸检查;这些资料只保留在本机。

实现位置

内容 文件
主题色与材质预设 crates/ferese-config/src/presets.rs
主题族注册 crates/ferese-config/src/families.rs
共享按钮、导航、输入框状态 crates/ferese-theme/src/controls.rs
页面结构与导航居中 shell/ferese-settings/src/pages.rs
详细页字段分组 shell/ferese-settings/src/schema.rs
行内说明与标题字重 shell/ferese-settings/src/form_controls.rs
日历设置与代码编辑器 shell/ferese-settings/src/calendar_controls.rs
日历日期和星期显示 crates/ferese-theme/src/calendar.rs
原生主题预览绘制 crates/ferese-theme/src/gallery/preview.rs
按需 schema 载入与缓存 shell/ferese-settings/src/all_options.rs
数据刷新合并与有效期 shell/ferese-settings/src/refresh.rs
规范化面板预览缓存 shell/ferese-settings/src/store.rs
窗口示意图缓存绘制 shell/ferese-settings/src/window_preview.rs
全部分类与尺寸性能采样 shell/ferese-settings/src/performance_tests.rs
祝日函数执行与校验 crates/ferese-config/src/calendar_rules.rs
时间弹层与控制中心 shell/ferese-shell/src/status_ui/
活动窗口与焦点切换 shell/ferese-shell/src/window_tray.rs
总览卡片与双列布局 shell/ferese-settings/src/all_options.rs
分区表面与图标 shell/ferese-settings/src/visuals.rs
布局及对齐回归检查 shell/ferese-settings/src/scroll_tests.rs

前版记录保存在 .artifacts/visual-reference-20261028/ 与 .artifacts/settings-density-20261028/;本版日历、函数编辑器和通知标记的记录保存在 .artifacts/time-hub-20261028/。这些本机验收资料不随仓库分发。