Bark 界面规范

这份文档约束 Yumu 的每一个前端：macOS（SwiftUI）、Windows（WinUI 3）、将来的 Linux（GTK4），以及任何预览页或新壳。目标只有一句话：换一台电脑打开 Yumu，除了字体和窗口边框，看到的是同一个产品。

平台只决定三件事：字体、窗口边框与系统控件的手感、系统级弹窗（文件选择器、权限）。其余一切——布局、层级、颜色、间距、动效、文案、交互顺序——由本文与 bark/tokens/ 决定，任何端不得自行发挥。

可交互的效果演示见 bark/preview/：index.html 是三个布局方向的选版页，spec.html 是令牌与组件演示。用 python3 -m http.server --directory bark/preview 起个静态服务再打开，直接双击文件加载不到共用脚本。

0. 已定的方向

三个布局方案（见 bark/preview/）里选定了素木，并吸收森林的两点：侧栏带像素图标，标签栏用下划线式（带数量角标）。没有封面大图，因为大多数实例不是整合包、没有美术资源；头部的分量靠「大图标 + 大标题 + 右侧数据带 + 一排按钮」撑起来。macOS 应用已按此实现，apps/macos 就是这份规范的参照物。

1. 四条原则

原则	一句话	判断标准
一眼看懂	任何页面 3 秒内知道自己在哪、能做什么	每页只有一个主操作按钮，用强调色；其余全是次级
一步到位	用户想做的事，默认值已经填好，直接点	新建实例不改任何项就能创建；拖入整合包不问任何问题
高级藏起来	高级功能全部存在，但默认看不见	高级项在「更多」菜单、折叠区或设置页里，永不出现在主路径
动起来才算完成	每个状态变化都有过渡，没有闪变	列表增删、页面切换、进度、成功反馈都走 Bark 动效令牌

冲突时按这个顺序取舍：一眼看懂 > 一步到位 > 高级藏起来 > 动效。

2. 窗口结构

所有端用同一个两栏结构，第三栏按需出现。

┌─────────────┬────────────────────────────────────────────┐
│  侧栏        │  内容区                                     │
│  实例列表    │  标题区（图标、名称、副标题、次级操作）         │
│             │  分段切换（概览 · 模组 · 资源 · 日志）         │
│             │  页面内容                                   │
│  ─────────  │                                            │
│  导入进度    │                                            │
│  账号栏      │  底栏：状态（左）  主操作「开始游戏」（右）      │
└─────────────┴────────────────────────────────────────────┘

侧栏宽 240（最小 200，最大 320），背景 background.sidebar。只放实例列表、导入进度、账号栏。工具栏上放三个入口：浏览整合包、导入、新建。
内容区 背景 background.canvas，内边距 space.xxl（32）。
第三栏 / 抽屉 只在查看日志或崩溃报告时出现，从右侧滑入，宽 360。
导航只有一层：选实例 → 看详情。没有面包屑，没有返回键。
多实例同时运行是常态，界面必须随时能回答「现在哪些在跑」：
- 标题栏右侧出现「N 个实例运行中」胶囊，点开列出每个运行中的实例、已运行时间、「查看」与「结束」。
- 侧栏顶部出现「正在运行」分组，行内呼吸绿点 + 计时，悬停显示「结束」；没有侧栏的布局在首页顶部放「正在运行」条，导航图标加数字角标。
- 运行中实例的详情页，主按钮变成「结束游戏」次级样式；其他实例的「开始游戏」不受影响。
- 游戏退出后分组与胶囊即时消失（standard），崩溃则在该实例页留下通知卡。
窗口最小 900 × 600。窄于 900 时侧栏可折叠成图标列，不出现横向滚动。
所有端的窗口内容不画自己的边框，窗口边框交给系统。

3. 页面清单

每一页按同一个模板写：目的、主操作、次操作、空状态、加载、进度、错误。缺一项就是没设计完。

3.1 实例列表（侧栏）

行：图标（原版 cube / 模组 puzzle）、名称、副标题（版本），右侧状态位：运行中绿点、安装中小进度环。
选中行用 accent.tint 背景，不用高亮描边。
右键菜单：开始游戏、打开文件夹、复制、重命名、删除实例（危险色，底部）。
空状态：侧栏本身留空，由内容区的空状态引导（见 3.3）。
「这台 Mac 上已有」分区：实例列表下方，text.secondary 灰色行，列出本机其他启动器里有、Yumu 里还没有的东西（核心 discover.scan）：
- 版本行：图标、版本 id、副标题「加载器版本 · 游戏版本」，行尾一个「添加」次级按钮，点一下就按检测到的加载器与版本建实例，不弹表单。已经有同版本同加载器的实例时该行消失。
- 存档行：世界名、上次游玩，行尾「导入到选中的实例」；没有选中实例时按钮禁用并 tooltip「先选中一个实例」。
- 这个分区取代了任何「扫描 / 导入已有存档」按钮：发现是被动展示，不需要用户主动去找。
侧栏不放工具栏按钮。新建实例、导入整合包、浏览整合包都在侧栏底部账号栏右侧的「+」菜单里。

3.2 实例详情

头部一行：96 × 96 像素图标（预设地形，可换），名称 32 pt 粗体 + 收藏星，副标题「加载器版本 · 游戏版本 · 上次游玩」，状态行（准备就绪 / 准备中 / 安装进度 / 运行中 · 计时 / 上次运行崩溃）；右侧是 2 × 2 数据带：游玩时长、上次游玩、存档数、模组数。
操作行：主按钮「开始游戏」（运行中时文案变「再开一个」，同一实例可以开多个），运行中时旁边出现次级「结束游戏」（多个进程时是菜单），然后「打开文件夹」与「···」。
下划线标签栏：概览、模组（数量）、资源、存档（数量）、日志、设置。
内容最大宽 980，居中；全部是圆角分组卡，列表行之间细线。
「开始游戏」是整个窗口唯一的强调色填充按钮。
高级项（Java 路径、内存、JVM 参数、分辨率、加载器版本、启动前命令）全部在「···」→「实例设置…」Sheet 里，默认折叠，见第 4 节。

3.3 空状态（没有实例）

居中：淡色大图标、标题「还没有实例」、一句话、三个按钮：新建实例（主）、浏览整合包、导入整合包。
最下方 text.tertiary 小字「拖入 .mrpack 即可导入」。
空状态是功能入口，不是装饰。所有列表的空状态都要给出下一步动作。

3.4 新建实例（Sheet，宽 440）

默认：名称留空（占位显示版本号）、版本选最新正式版、加载器选原版。不改任何项按回车就能创建。
版本下拉默认只列正式版；快照、旧版在下拉底部「显示全部版本」展开。
加载器用分段控件：原版 · Fabric · Quilt · Forge · NeoForge。不可用的组合直接禁用并给出 tooltip，不弹错误。
「高级选项」折叠区在表单底部：加载器版本、Java、内存、JVM 参数。默认折叠，记住用户上次是否展开。
底部右对齐：取消、创建（主）。

3.5 整合包浏览器（Sheet，宽 720 × 540）

顶部搜索框自动聚焦；下方卡片网格，每卡：图标、名称、作者、下载量、一句简介、「安装」按钮。
安装即新建实例，不再弹第二个表单。版本选择在卡片「···」里。
底部一行说明「安装会新建一个实例，整合包需要的东西全部自动装好。」

3.6 模组页 / 资源页

上半：已安装列表，每行有启用开关、名称、版本、「移除」在右键或悬停时出现。
下半：搜索框 + 结果列表，每行「安装」按钮，已安装的显示「已安装」标签。
原版实例的模组页显示提示文字加「新建一个 Fabric 实例」按钮，不显示空列表。
必需依赖自动装，不询问；可选依赖不装，不询问。

3.7 账号栏（侧栏底部）

头像（皮肤头部 32 × 32 或占位）、玩家名、类型小字。点击弹出切换列表与「添加账号…」。
微软登录：一个 Sheet，大号设备码、「已复制」、「再次打开页面」。等待时用进度环与「等待你在浏览器里完成登录…」。

3.8 设置（窗口菜单或 ⌘, / Ctrl+,）

分组：通用、下载、Java、外观、关于。每组一个表单，不用标签页。
外观（个性化）：主题（跟随系统 / 浅 / 深，三张缩略图选）、强调色（跟随系统 + 五个预设色点）、密度（舒适 / 紧凑）、侧栏是否显示封面、动效（跟随系统 / 完整 / 减弱）、语言（跟随系统 / 三语）。
实例级个性化放在实例设置里：图标与封面（预设像素地形或自定义图片）、收藏置顶。
下载源、镜像、代理、并发数属于「下载」组——这是高级项该在的地方。

3.9 存档

实例页「存档」标签：每个世界一张卡（封面缩略、名称、模式 · 大小 · 上次游玩、进入按钮），末尾一张虚线「新建世界」卡。
点存档卡等于「开始游戏并直接进入这个世界」；实例设置里也可以固定一个默认世界。
顶部次操作：导入世界、备份全部。备份不弹进度窗，走侧栏底部进度位。

3.10 日志与崩溃

实例页「日志」标签：下拉选运行记录（含崩溃报告）、搜索、复制、打开日志目录；日志用等宽字体深色区块，INFO / WARN / ERROR 三色。
崩溃后概览与日志顶部都出现一条通知卡：分类标题（内存不足 / 模组冲突 / Java 版本不匹配 / 未知）、一句原因、一个主按钮（「把内存调到 4 GB」）和「查看日志」。

3.11 欢迎页（首次启动）

第一次打开只显示这一页：标题「欢迎使用 Yumu」、一句话、三步卡片（登录账号 → 导入或新建 → 开始游戏），已完成的步骤打勾。
第二步提供「导入本机存档」：列出官方启动器与其他启动器里发现的版本与存档，勾选导入。
底部：新建实例（主）、浏览整合包、「以后再说」文字按钮。任何一个动作都会离开欢迎页，不再出现。

3.12 关于（设置里的一组）

应用图标、名称、版本号（含 Heartwood 版本与架构）、「检查更新」。
自动更新开关、更新通道。
链接：源代码、使用指南、报告问题、支持开发、第三方许可、隐私说明、日志目录。
一段致谢与商标声明。

3.13 导入进度与崩溃报告

导入进度固定在侧栏底部、账号栏之上，细进度条 + 百分比，不弹窗，不阻塞。
成功：emphasized 一次弹性缩放新实例行，并给一条 Toast「整合包已导入」。
崩溃：核心在 game.exited 事件里给出 crash: {kind, detail[], mods[], reportPath}，kind 七选一：OUT_OF_MEMORY、JAVA_VERSION、NATIVES、MOD_DEPENDENCY、MOD_CONFLICT、GRAPHICS、UNKNOWN。详情底栏状态区显示翻译后的分类句（crash.<KIND>）加一个建议按钮，按 kind 固定对应：
- OUT_OF_MEMORY → 「把内存调到 N GB」（当前值 + 2，上限 16），点一下直接改 instance.update。
- JAVA_VERSION、NATIVES → 「让 Yumu 自动选 Java」，直接把 Java 设回自动。
- MOD_DEPENDENCY、MOD_CONFLICT → 「查看模组」切到模组页；mods 非空时在句子后面附「涉及：A、B」。
- GRAPHICS、UNKNOWN → 「打开日志」，打开 logPath 所在文件夹。
- 原始 detail 行放在「详情」展开区，等宽字体，不默认展开。下次点「开始游戏」时清除。

4. 渐进披露：高级功能怎么藏

三层，从外到里：

层	在哪	放什么	例子
直接可见	页面上	90% 用户每次都用的	开始游戏、新建、导入、搜索模组
一次点击	「···」菜单、右键、折叠区	偶尔用、懂的人才用	打开文件夹、复制实例、加载器版本、JVM 参数
设置页	偏好设置	装好后几乎不再碰	下载源、代理、Java 列表、强调色

规则：

默认值必须能直接用。没有一个高级项是「不填就跑不起来」的。
折叠区记住展开状态（每个表单单独记），但新用户第一次看到的一定是折叠的。
不做「专家模式」总开关。那是把设计责任推给用户。
高级项展开后依然用同一套控件与间距，不换成「技术风」。
任何高级项都带一句说明文字（text.secondary，type.callout），说明不写术语，写后果：「内存越大加载越快，但不要超过物理内存的一半。」
破坏性操作永远在菜单最底部、用危险色、二次确认，确认按钮写明动作（「删除实例」不写「确定」）。

5. 组件

组件尺寸用令牌表达，三端的实现必须对上这张表。所有尺寸单位是逻辑像素（pt / dip）。

5.1 按钮

层级	填充	文字	高度	圆角	用途
主	`accent.default`	`text.onAccent`	28 / 大 36	`radius.md`	每页一个
次	`surface.elevated` + `border.subtle`	`text.primary`	28	`radius.md`	其他操作
文字	无	`accent.default`	28	`radius.md`	行内、低优先
危险	`status.dangerTint`	`status.danger`	28	`radius.md`	删除、移除

状态：悬停加 surface.hover 叠层；按下缩放 0.97（quick）；禁用 40% 不透明度且不响应悬停；聚焦画 2px accent 外环，偏移 2。

5.2 列表行

高 36（紧凑 28），左右内边距 space.md，行间无分隔线，用 space.xs 间隔。选中 accent.tint 底 + radius.sm。悬停 surface.hover。

5.3 卡片

surface.default 底，radius.lg，内边距 space.lg，无边框，elevation.raised 只在悬停时出现（quick）。

5.4 分段控件

高 28，surface.sunken 轨道，选中块 surface.elevated + elevation.raised，选中块位移用 standard。

5.5 输入框与搜索框

高 28，surface.sunken 底，radius.sm，无边框；聚焦时底变 surface.default 并画 2px accent 外环。搜索框左侧放大镜图标，右侧有内容时出现清除按钮。

5.6 进度

线性进度条高 4，accent 填充，轨道 surface.sunken，圆角全。
不确定进度用进度环，20 或 14。
进度永远带文字：百分比或「已下载 / 总量」，数字用等宽数字避免跳动。

5.7 状态点与标签

状态点 8 × 8 圆：运行 success，安装 accent，警告 warning，错误 danger。运行中的点以 2 秒周期轻微呼吸（0.6 ↔ 1 不透明度）。标签高 18，type.caption，surface.sunken 底，radius.sm，内边距 2 × 6。

5.8 开关

44 × 24，开为 accent，滑块位移 standard。

5.9 Sheet 与对话框

从窗口顶部中央下落，emphasized 进入、standard 退出，背后画 30% 遮罩并模糊。宽度固定：表单 440、浏览器 720、确认 360。Esc 关闭，回车触发主按钮。

5.10 Toast

右下角，surface.elevated + elevation.overlay，radius.lg，图标 + 一句话 + 可选动作，3 秒后自动消失。同时最多一条，后来的顶掉前面的。

5.11 拖放覆盖层

拖入窗口任何位置：整窗覆盖 ultraThinMaterial，中央虚线框 2px accent，图标 48 + 文字「拖入 .mrpack 即可导入」。quick 淡入淡出。

5.12 右键菜单与「···」菜单

系统原生菜单。条目顺序：常用操作 → 分隔线 → 次要操作 → 分隔线 → 破坏性操作。

6. 视觉令牌

全部在 bark/tokens/*.json，这里只说规则，不抄数值。

颜色 color.json：语义命名，深浅成对。强调色默认跟随系统强调色，无系统强调色（Linux）或用户固定时用令牌里的苔绿。中性色带一点暖，这是「原木」的来源。
字体 type.json：只定义六级刻度与字重，字体由平台决定（SF Pro / Segoe UI Variable / Cantarell 或 Inter）。中文字体跟随系统。不在任何地方硬编码字号。
间距 space.json：4 的倍数。相关元素 sm，分组内 md/lg，分组间 xl，区块间 xxl。
圆角 radius.json：按钮与输入 md，卡片与图标块 lg，Sheet 与覆盖层 xl，标签与小元素 sm。嵌套时内层圆角 = 外层圆角 − 内边距。
层级 elevation.json：平面靠背景色区分，阴影只给悬浮物（卡片悬停、Sheet、菜单、Toast）。深色模式阴影更重，并靠 surface.elevated 的亮度差区分层级。
图标：线性图标，1.5 描边，默认 16，标题区 32，空状态 56。macOS 用 SF Symbols，Windows 用 Fluent，Linux 用 Lucide，但语义一一对应（见第 11 节映射表）。

7. 动效

7.1 令牌

名称	时长	曲线	Web 近似	用途
`instant`	0	—	—	减弱动态效果时的替代
`quick`	150 ms	ease-out	`cubic-bezier(0, 0, 0.2, 1)`	悬停、按下、开关、淡入淡出
`standard`	≈ 300 ms	spring(response 0.35, damping 0.85)	`300ms cubic-bezier(0.2, 0.8, 0.2, 1)`	列表增删、面板切换、选中块位移
`emphasized`	≈ 450 ms	spring(response 0.5, damping 0.8)	`450ms cubic-bezier(0.34, 1.3, 0.64, 1)`	导入完成、创建成功、Sheet 进入

7.2 场景对照

场景	动效	怎么动
悬停 / 离开	`quick`	背景叠层淡入
按下	`quick`	缩放 0.97
开关、复选	`quick`	滑块位移 + 颜色
选中列表行	`standard`	选中背景从旧行滑到新行（同一元素位移，不是两次淡入淡出）
切换详情	`standard`	旧内容淡出并上移 8，新内容淡入并从下 8 归位；标题区不动
分段切换	`standard`	选中块位移，内容交叉淡入淡出
列表新增	`standard`	从 0.96 缩放 + 淡入，其他行位移让位
列表删除	`standard`	淡出 + 缩放 0.96，其他行合拢
列表首次出现	`standard` + 错峰	每项间隔 20 ms，最多 6 项错峰，之后同步
Sheet 进入	`emphasized`	从上方 −16 下落 + 0.96 缩放 + 淡入，遮罩 `quick`
Sheet 退出	`standard`	反向，不过冲
进度更新	`standard`	进度条宽度插值，数字直接变
成功反馈	`emphasized`	目标元素 1 → 1.04 → 1 一次
错误反馈	`quick`	变色 + 文字出现。不抖动，不弹窗
拖放覆盖	`quick`	淡入淡出
Toast	`standard` 进 / `quick` 出	从右下 +16 滑入
运行中状态点	2 s 循环	不透明度 0.6 ↔ 1，减弱动态时静止

7.3 规则

一次只动一个主体。 内容切换时标题区、侧栏、底栏不动。
动效表达因果。 从哪来、到哪去要和用户的动作对应：从右下角按钮触发的 Toast 出现在右下角。
持续性反馈不阻塞。 进度在原位显示，用户随时能干别的。
时长不随数量变。 100 个实例的列表和 3 个实例的列表动画一样长。
减弱动态效果（系统设置）：所有位移、缩放、spring 退化为 instant，只保留淡入淡出，呼吸点静止。
不叠加动效：一个元素同一时刻只有一个动画，新动画打断旧动画而不是排队。
60 fps 是底线。动画只改 transform 与 opacity，不动 layout；列表超过 50 项时错峰关闭。

8. 文案

短句，动词开头：「新建实例」「导入整合包」。不写「点击此处」。
说发生了什么和下一步，不说「错误」「失败」：「无法连接 modrinth.com，请检查网络」。
按钮写动作结果：「删除实例」「安装」「开始游戏」。不写「确定」「是」「OK」。
不用感叹号，不用「成功」二字。成功用动效与一句陈述：「整合包已导入」。
技术词只在高级区出现，且带一句后果说明。
三语（en、zh-Hans、ja）同时交付，源在 bark/i18n/，界面不写死任何一句话。
标题区名称 display，页面标题 title，分组标题 headline，正文 body，说明 callout，时间戳与标签 caption。

9. 状态与反馈

状态	怎么做	不这么做
加载 < 300 ms	什么都不显示	闪一下进度环
加载 ≥ 300 ms	原位进度环 + 一句话（「正在获取版本列表…」）	整页遮罩
列表加载	骨架行 3 条，`standard` 淡入真实内容	空白再突然出现
有进度	线性进度条 + 数字，原位	模态进度窗
成功	`emphasized` 一次 + Toast 或原位文字	弹窗说「成功」
可恢复错误	原位红字说明 + 一个修复按钮	弹窗
不可恢复错误	系统 alert，标题「出了点问题」，正文翻译后的 `kind` + `args`	显示原始错误串
离线	搜索框下一行提示，已安装内容照常可用	禁用整页

10. 可访问性与输入

全键盘可达：Tab 顺序与视觉顺序一致，回车触发主按钮，Esc 关闭 Sheet，⌘N / Ctrl+N 新建，⌘, / Ctrl+, 设置，Delete 删除（走确认）。
焦点环 2px accent，只在键盘导航时显示。
文字对比度 ≥ 4.5 : 1，text.tertiary 只用于非必要信息。
最小点击区域 28 × 28；图标按钮加 tooltip。
跟随系统字体缩放，布局用自适应布局不用固定高度（除行高）。
所有图标按钮有无障碍标签；进度条报百分比；状态点有文字替代。
不依赖颜色传递唯一信息：运行中有绿点也有「运行中」文字。

11. 平台映射

概念	macOS SwiftUI	Windows WinUI 3	Linux GTK4	Web 预览
两栏结构	`NavigationSplitView`	`NavigationView` (Left, compact 折叠)	`AdwNavigationSplitView`	CSS Grid
侧栏材质	`.sidebar`	Mica Alt	`.sidebar-pane`	`background.sidebar`
主按钮	`.borderedProminent`	`AccentButtonStyle`	`.suggested-action`	`.btn-primary`
危险按钮	`role: .destructive`	自定义 Brush	`.destructive-action`	`.btn-danger`
分段控件	`Picker(.segmented)`	`SelectorBar`	`AdwViewSwitcher`	`.segmented`
Sheet	`.sheet`	`ContentDialog`	`AdwDialog`	`.sheet`
确认	`.confirmationDialog`	`ContentDialog`	`AdwAlertDialog`	`.sheet.confirm`
右键菜单	`.contextMenu`	`MenuFlyout`	`GtkPopoverMenu`	自绘
Toast	自绘	`InfoBar` / `TeachingTip`	`AdwToast`	自绘
拖放	`.dropDestination`	`AllowDrop`	`GtkDropTarget`	`dragover`
减弱动态	`accessibilityDisplayShouldReduceMotion`	`UISettings.AnimationsEnabled`	`gtk-enable-animations`	`prefers-reduced-motion`
强调色	`.tint` 跟随系统	`SystemAccentColor`	令牌苔绿	令牌苔绿
字体	SF Pro	Segoe UI Variable	Cantarell / Inter	系统字体栈
图标	SF Symbols	Fluent System Icons	Lucide	内联 SVG

图标语义表（三套图标库各自对应）：实例 cube / 模组实例 puzzle / 开始 play / 新建 plus / 导入 arrow-down-to-box / 整合包 package / 文件夹 folder / 搜索 magnifier / 设置 gear / 账号 person / 更多 ellipsis / 删除 trash / 运行中 circle.fill。

12. 提 PR 前自查

这页只有一个强调色按钮吗。
不改任何默认值能完成任务吗。
高级项在「···」、折叠区或设置里吗，带后果说明吗。
空状态、加载、进度、错误四种状态都画了吗，都有下一步动作吗。
每个状态变化都用了 Bark 动效令牌吗，减弱动态时正常吗。
尺寸、颜色、间距全部来自令牌吗，没有魔法数字吗。
三语文案都在 bark/i18n/ 里吗。
键盘走一遍能完成吗，Esc 和回车对吗。
深色模式看过了吗。
和另一端摆在一起，除了字体和窗口边框还有区别吗。

13. 禁止事项

不出现第二个强调色填充按钮。
不弹模态进度窗。
不用「确定」「OK」「是/否」做按钮文字。
不抖动、不闪烁、不弹跳超过一次。
不在主路径放任何需要解释的术语（JVM、classpath、natives）。
不写死颜色、字号、间距、时长。
不在界面里拼接自然语言，所有文案走翻译键。
不用边框分隔区域，用背景层级。
不做「专家模式」开关。
不给某个端加另一端没有的功能。

源文件 bark/guidelines.md 更新于 2026-10-08