Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

docs(web): 设计准则写明行内图标、控件命名与四档高度

longmeidao8794be5fe8ad
diff --git a/.claude/skills/peach-web-ui/SKILL.md b/.claude/skills/peach-web-ui/SKILL.md
index 1b8090911..6a3554a2d 100644
--- a/.claude/skills/peach-web-ui/SKILL.md
+++ b/.claude/skills/peach-web-ui/SKILL.md
@@ -5,7 +5,7 @@ description: 在新增、修改、预览或复核 Peach 页面、控件、提示
# Peach Web UI 复用门槛
-最后复核:2026-10-21
+最后复核:2026-10-22
证据来源:现有 UI 契约、`docs/TESTING.md`、本机重复文案与异步轮询回归记录、jakubkrehel/skills 与 emilkowalski/skills 摘录、`docs/reference-snapshots/open-claude-ui.md`、用户真实小样本预览与明确确认后测试的约定。
## 开工顺序
@@ -48,6 +48,7 @@ description: 在新增、修改、预览或复核 Peach 页面、控件、提示
- 优先扩展 `frontend/src/ui-kit/`,不要为同一语义复制一次性 class 和模板。
- 数据表统一用 TanStack Table 驱动 BoardUI `Table`,具备全集排序、分页、跨页选择与批量操作;工具栏、分页和批量栏按关注列表复用 `data-table.tsx`、`table-controls.tsx`、`DataTableFrame` 与 `SelectionDock`,默认每页 20 条,同页只保留当前表格的选择。
- 管理页单面板分区的标题放在面板内,不在框外重复;多卡片分组可用框外标题。同级分区标题用 `text-title-2-medium`,加载态与内容态共用 500 字重、20px 字号和 26px 行高。
+- 控件高度只取 `--control-h-inline`/`-compact`/`--control-h`/`-large` 四档,同一行的同类控件同档;与文字同行的图标用 `--icon-inline`,单独图标按控件档取固定值;下拉不点开也要看得出在选什么(上方标签、触发键前缀或格子选择器的弹层标题三选一)。判据与坏例见 `docs/DESIGN_GUIDELINES.md` 第 2、10、11 节。
- 颜色、字号、圆角、浮层层级只用 `:root` 已有 token;新 token 必须证明现有词汇无法表达。
- 字重只有 400/500/600 三档,标题按既定层级选择 medium 或 semibold;圆角只用 `--badge-radius`/`--control-radius`/`--surface-radius`/`--floating-radius`/`--pill-radius` 加 `50%` 与 `0`,带边框容器里的头尾条用 `calc(… - 1px)` 保持同心。两者的字面值由 `tests/test_web_ui.py` 拒绝,归属判据见 `:root` 注释。
- 单色优先:`--tungsten` 只给焦点环、链接、进度/数据与 Toggle 开态。主动作用 `--ink` 底 `--ground` 字且每屏最多一个。标题悬停下划线不变蓝,计数徽章中性灰。其它选择器引用 `--tungsten` 由 `tests/test_web_ui.py` 拒绝;实测见 `vercel-geist-semantics-measured.md`「选中态与开关色」「Button 全变体与状态」。
diff --git a/docs/DESIGN_GUIDELINES.md b/docs/DESIGN_GUIDELINES.md
index dab2d47f7..b2844ef1f 100644
--- a/docs/DESIGN_GUIDELINES.md
+++ b/docs/DESIGN_GUIDELINES.md
@@ -19,6 +19,8 @@ Open Claude UI 提供本文件的补充参考。采用范围与源码缺口见 [
- 时间、数量、进度等持续变化的读数使用等宽数字,单位与精度稳定;标签、姓名与正文继续使用对应文本样式。
- 按内容选择换行和截断:标题与说明保留语义阅读,路径、文件名、URL 等资源标识使用已有中间省略;需要复核的完整值有明确查看或复制入口。
- 长字符串在真正承载它的内容区安全换行,flex/grid 子项允许收缩。按钮、徽标和短标签不能因容器挤压变成单字竖排。
+- 与文字同行的图标(带文字按钮的前置图标、署名、标签、导航、站标)用 `--icon-inline`(`1.2em`),跟所在文字字号缩放。依据是实测:14px 正文里汉字墨迹约 13px,雪碧图笔画约占 24 画框的 75%,`1.2em` 的画框让两者等高。`cap` 只量拉丁大写(14px 时约 10px),中文界面不用它定图标尺寸。
+- 单独的图标(纯图标按钮、封面上的播放与快进、状态圆点、头像、色球)不跟文字走,按所在控件的尺寸档取固定值。
- 图标与文字按当前字体的实际基线核验;数字缩放、固定负偏移与可变字体轴只在取得实际字体和像素证据时调整。保持项目已有中文字体回退与手机输入字号判据。
## 3. 按组件可用宽度适配
@@ -72,11 +74,40 @@ Open Claude UI 提供本文件的补充参考。采用范围与源码缺口见 [
- 减少动态效果同时覆盖 CSS 与 JavaScript 动画;持续脉冲、Canvas 和逐字模糊不承担唯一状态信息。隐藏和卸载停止本区域动画,失败或缺少转场 API 时仍能完成操作。
- 文本与表格以清楚阅读为先。环境光、成功弹跳、提示音等只有明确产品用途和用户设置时才采用;媒体音量与提示音分别管理。
+## 10. 控件写明在选什么
+
+- 看值就知道在选什么的控件不写名字:图标键、名称框、每一项都自带说明的下拉(「每页 20 部」「最近 30 天」)。排序下拉的「时长」「评分」单看说不清,按下一条加前缀。
+- 单独一个表单字段:名字放在控件上方(`FolderField`、`SettingsRow`、`FieldLabel`)。
+- 工具栏或重复块里一行并排、单看值说不清的下拉:名字写进触发键,作为值前的浅色前缀(BoardUI `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 能否进出?关闭后焦点去了哪里? |
| 滚动与手势 | 新内容是否抢走阅读位置?拖动取消能否恢复?隐藏控件是否仍可聚焦? |