Peach: Local-first video metadata scraper and media manager.
Peach 设计准则
本文件用于设计和审阅页面、控件、媒体查看器与任务反馈。组件选择与 token 见 组件契约,执行与验收见 Web UI 技能,BoardUI 的采用范围见 BoardUI 适配。这些准则指导后续实现,不表示所有页面已逐项验收。
Open Claude UI 提供本文件的补充参考。采用范围与源码缺口见 阅读与取舍;它对 Claude 官方实现的描述属于第三方自述,Peach 只采用可以解释自身需求的原则。实际参数服从项目已有 token、组件契约与本机验收。
1. 用内容建立层级
- 先用留白、标题、对齐和已有表面色区分区域。闭合边框用于独立对象、输入控件或浮层的边界;一个容器里的正文、工具栏和次级分组通常用留白或单向分隔线。
- 「单一外框」是减少重复装饰的默认判断。独立可编辑字段、可访问焦点环和数据表格的必要边界仍按组件契约保留。
- 保留独立任务、创作者与指标卡已有的对象边界。采用参考原则前先指出具体阅读或操作问题,并用同一数据比较;减少卡片数量本身不构成改进依据。
- 直接摆在页面上的卡靠填充底和页面区分,不另加描边;描边只留给底色与所在表面分不开的卡(灰卡里的白卡、卡内代码块)。
- 卡内分隔线按用途分两种:切开正文、清单、页脚等区域的线两端顶到卡边;同一列表的行间线左端与行内文字对齐、右端顶到卡边。
- 常态、悬停、选中、焦点与忙态保持控件几何稳定。边框参与布局时预留相同宽度;焦点使用已有 outline/ring,不靠增加边框厚度改变尺寸。
- 浅色与暗色分别检查正文、次级文字、分隔线和浮层。表面微对比必须保留可辨识的控件与焦点;颜色、字重、圆角和阴影均复用 Peach 的语义 token。
坏例:作品详情的外壳、简介、操作条与每段说明各套一个闭合卡片。好例:详情保留外壳,简介自然排版,操作条用留白或一条分隔线,独立字段保留自己的输入边界。
2. 让排版适应内容
- 时间、数量、进度等持续变化的读数使用等宽数字,单位与精度稳定;标签、姓名与正文继续使用对应文本样式。
- 按内容选择换行和截断:标题与说明保留语义阅读,路径、文件名、URL 等资源标识使用已有中间省略;需要复核的完整值有明确查看或复制入口。
- 长字符串在真正承载它的内容区安全换行,flex/grid 子项允许收缩。按钮、徽标和短标签不能因容器挤压变成单字竖排。
- 与文字同行的图标(带文字按钮的前置图标、署名、标签、导航、站标)用
--icon-inline(1.2em),跟所在文字字号缩放。依据是实测:14px 正文里汉字墨迹约 13px,雪碧图笔画约占 24 画框的 75%,1.2em的画框让两者等高。cap只量拉丁大写(14px 时约 10px),中文界面不用它定图标尺寸。 - 单独的图标(纯图标按钮、封面上的播放与快进、状态圆点、头像、色球)不跟文字走,按所在控件的尺寸档取固定值。侧栏导航收起成图标列时仍用
--icon-inline,展开与收起之间图标大小不变。 - 指向站外的链接(来源页、官网、资料站、说明文档、另一台 Peach 的写入端)一律新标签页打开,
rel="noopener noreferrer",用<a>或链接按钮,不用按钮加window.open,保证能中键打开和复制地址。带文字的外链在文字后跟外链字形(React 侧RiExternalLinkLine,HTML 字符串用icon('external-link', 'ui-externalmark'),尺寸都是--icon-inline),设置页现成的写法是ExternalLink;只有站标或品牌图标的链接不加。Peach 换端口、完成首次设置后回到自身入口仍在当前页跳转,外部播放器协议链接也不开新页。外链字形只表示「离开 Peach」,站内跳转不用它。 - 图标与文字按当前字体的实际基线核验;数字缩放、固定负偏移与可变字体轴只在取得实际字体和像素证据时调整。保持项目已有中文字体回退与手机输入字号判据。
3. 按组件可用宽度适配
- 页面布局由视口决定;可嵌入侧栏、详情或弹层的复用组件由自身容器宽度决定。断点取内容放得下的边界,不照抄外部产品的屏幕宽度。
- 工具栏收紧时,依次减少辅助信息、缩短可理解的标签、把次要动作收入现有菜单;主动作、当前选择和恢复入口保持可达。
- 只在图标含义清楚且有可访问名称时隐藏文字。互斥选项保留当前项的可见名称;无法清楚压缩的一排使用局部横滚或换行。
- 验收同一组件在宽页面中的窄容器,以及桌面、手机、长中文、长资源名和放大文字。分栏装不下各栏必要内容时转为单栏或现有覆盖层。
4. 输入与焦点优先
- 输入法合成期间,Enter、方向键和 Escape 优先服务候选词;搜索、提交与建议菜单不得误接管。使用合成事件与原生
isComposing;确有兼容需求时补keyCode === 229检查,并用中文、日文输入验证。 - Escape 按当前交互层处理:先退出输入候选、建议菜单或拖动,再处理外层弹窗。拦截外层关闭不能妨碍输入法完成自身操作。
- 一组互斥选项使用对应的 Tabs/radio 契约;方向键导航后选项在自身滚动区可见,Tab 能离开组。菜单跳过不可用项,空列表与动态删项有明确焦点去向。
- 模态层复用原生 dialog 或 React Aria 的焦点管理;进入给出有意义的焦点,关闭归还仍存在的触发器。触发器消失时归还到当前区域的合理入口。
- 悬停出现的次要动作在键盘聚焦和触屏下也能访问;隐藏或折叠的内容不残留 Tab 停靠点。
5. 保持用户的阅读位置
- 内容追加、后台刷新和局部状态变化不抢夺滚动位置。只在用户已跟随最新内容时继续跟随;主动滚轮、触摸或键盘浏览立即解除跟随。
- 需要自动跟随的任务日志提供「跳至最新」入口。冷却时间与底部容差用于过滤程序滚动,不能在计时结束后强制把正在阅读的人拉回底部。
- 边缘渐隐只提示该方向仍有内容;没有溢出或已滚到边缘时撤去对应渐隐。保留首尾文字、焦点环和操作的可见空间,内容或容器尺寸变化时重算。
- 多段透明度曲线是渐隐的可选视觉方案,强度和距离须在 Peach 的主题与媒体背景上核验;滚动状态和卸载清理继续由现有 Scroller/覆盖式滚动条承担。
6. 手势可中断,也可恢复
- 点击与拖动使用明确位移阈值区分。开始拖动后显示被拖对象和真实落点;完成拖动时不再触发该对象的点击动作。
- 指针捕获、
pointercancel、失去捕获、Escape 和卸载都有清理路径。取消回到开始状态;重排同时提供键盘或触屏可用的替代入口。 - 拖动中的几何直接跟随指针,松手后的吸附才使用已有动效。中断动效从当前可见状态接续,避免重启整段位移。
- 可调整分栏的最小尺寸、折叠和展开入口由真实内容决定。跨 iframe 拖动要验证事件连续性;透明但不接收事件的覆盖层不能作为事件屏蔽证据。
- 乐观显示只用于可以准确恢复的偏好或顺序;持久化失败时恢复一致状态并保留原因。账本写入与不可逆动作的结果由服务端决定。
7. 媒体查看保持空间与成本连续
- 放大以鼠标所指位置或手势中心为锚点,让正在查看的细节保持在附近。缩放上限、原大小和适应窗口的定义继续使用现有灯箱契约。
- 坐标计算使用一致的图像与视口空间,区分原始适应尺寸和变换后的显示尺寸;拖动以起始位置加位移计算,避免累计同一位移。
- 缩略图到大图的共享元素过渡仅在来源、目标和媒体身份明确时使用,计算实际图像显示范围、裁切和圆角。来源已卸载、API 不可用或减少动态效果时直接打开、关闭,并恢复焦点。
- 灯箱、轮播与播放复用 Swiper、MediaCarousel、舞台与共用播放器。预载范围按来源成本和本机缓存决定,隐藏媒体不因预载而播放,关闭和切换按现有生命周期停止媒体。
8. 反馈来自真实状态
- 操作区域先显示对象、范围和当前状态,细节按需展开。待执行、运行、等待来源、成功、失败、取消和部分完成保持各自语义;授权提示只在真实权限边界需要时出现。
- Spinner、Loading Dots、Skeleton、Progress、Toast 与持久错误按组件契约选择。已知总量显示真实读数,估算明确标明;动画计时与模拟响应不能产生成功结论。
- 失败保留输入、对象和原因,并给出当前可行的恢复动作。自动重试只用于已有策略允许的操作,界面显示服务端实际等待状态;刷新或打开面板不额外启动重试。
- 折叠详情不改变任务的运行状态。流式输出可以保持区域结构稳定,用户仍能收起不必持续阅读的日志;不因为任务运行就强制展开所有内容。
- 增量内容只更新受影响区域,异步结果绑定当前请求与对象,保留阅读位置和选择;不为每个新增片段重建整个内容区。
9. 动效服务于操作
- 用动效解释位置、选中关系和层级变化;高频控件尽快反馈。复用已有 Motion 与 CSS token,参数通过真实距离、反向操作和连续输入核验。
- 减少动态效果同时覆盖 CSS 与 JavaScript 动画;持续脉冲、Canvas 和逐字模糊不承担唯一状态信息。隐藏和卸载停止本区域动画,失败或缺少转场 API 时仍能完成操作。
- 文本与表格以清楚阅读为先。环境光、成功弹跳、提示音等只有明确产品用途和用户设置时才采用;媒体音量与提示音分别管理。
10. 控件写明在选什么
- 看值就知道在选什么的控件不写名字:图标键、名称框、每一项都自带说明的下拉(「每页 20 部」「最近 30 天」)。排序下拉的「时长」「评分」单看说不清,按下一条加前缀。
- 单独一个表单字段:名字放在控件上方(
FolderField、SettingsRow、FieldLabel)。 - 工具栏或重复块里一行并排、单看值说不清的下拉:名字写进触发键,作为值前的浅色前缀(
frontend/src/react/components/select.tsx的Select的prefix,自制触发键同样用text-text-tertiary前缀)。这样重复的块不必每块多一行标签。 - 弹层顶部的标题只给格子型选择器(图标、色球):格子里没有文字,需要标题说明在选什么。列表下拉外面已经写了名字,弹层里不再写一遍。
坏例:媒体库标题行的下拉只显示「自动补全」,点开才看到「选择处理方式」;「移到媒体库」上方有标签,弹层又写「移到哪个媒体库」。好例:处理方式 自动补全 ▾、来源色 ● 翠绿,「移到媒体库」只保留上方标签。
11. 控件高度分四档
不是全站一种高度,而是同类、挨在一起的控件同一档。四档在 :root 定义,BoardUI 尺寸与之对应:
| token | 高度 | BoardUI | 用在哪里 |
|---|---|---|---|
--control-h-inline |
28px | Chip、分段器与页签的内芯 | 正文和卡片里的标签、标签删除、标题旁的小工具、评分点击区;不单独成一行工具栏 |
--control-h-compact |
32px | size="small"、Select sm |
表格行操作、分页、卡片悬浮动作、卡内次级操作、筛选条 |
--control-h |
36px | 默认尺寸、Select md |
表单字段和同组按钮、保存配置、页面与分区操作、表格工具栏、分段器与页签外框、侧栏和设置导航 |
--control-h-large |
40px | 顶栏 .ib |
顶栏搜索与图标键、播放器控制条、首页厂牌胶囊 |
同一行混用时:
- 有输入框或下拉的行,按钮和图标键跟它们同档;表单行默认 36px。图标键与同行的文字按钮同档。
- 分段器、按钮组、页签组按外框对齐:外框取这一行的档,内芯取下一档(36 配 28)。
- 同一个动作在同一页只用一档;卡内的次级操作和行操作取紧凑档。
- 标签、角标、评分、头像不参与这一行的对齐;行内档不和紧凑及以上的档放在同一条工具栏里。拿不准时向上取一档。
坏例:媒体库卡里一排 36px 的下拉下面跟着 32px 的「添加文件夹」;设置页凭据卡的「保存配置」是 32px,别处都是 36px。验收时在浏览器里按行收集可见控件的高度,同一行出现两档以上的同类控件就是问题。
验收问题
| 检查位置 | 必须能回答的问题 |
|---|---|
| 区域与控件 | 边界是否表达独立语义?状态切换是否改变尺寸?焦点与暗色文字是否可辨?不点开能否看出每个下拉在选什么?同一行的同类控件是否同一档高度? |
| 容器与文本 | 宽页面中的窄面板能否使用?长中文、长路径和放大文字是否仍可阅读? |
| 输入与键盘 | 输入法确认会不会提交或关窗?Tab 能否进出?关闭后焦点去了哪里? |
| 滚动与手势 | 新内容是否抢走阅读位置?拖动取消能否恢复?隐藏控件是否仍可聚焦? |
| 媒体 | 放大是否保留细节位置?缺图与转场失败是否可恢复?预载是否触发额外播放或无界回源? |
| 状态与动效 | 终态来自哪份结果?失败保留什么?快速反向操作、减少动态效果与卸载是否完整? |
按实际改动从表中选取行为或布局验收,使用项目统一测试入口。只修改本准则时检查文档、来源锁与上下文门槛;页面采用某条原则时再验证对应的真实行为与视觉。