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.mdindex 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.mdindex 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 能否进出?关闭后焦点去了哪里? || 滚动与手势 | 新内容是否抢走阅读位置?拖动取消能否恢复?隐藏控件是否仍可聚焦? |