Peach: Local-first video metadata scraper and media manager.
界面组件契约
本文件维护组件选择与交互约束;执行流程见 界面技能,层级与布局原则见 设计准则。按当前任务读取对应章节。
适用组件体系
React 与 BoardUI 的组件、颜色和尺寸采用 BoardUI 适配 与 ADR-0031,保留既定蓝色主动作和原始组件约束。遗留 Geist 的 --ink、--ground、--tungsten 和 DOM class 只约束使用这些词汇的既有控件,不覆盖 BoardUI token。
下表的 Switch、Toggle 和 DOM helper 名称需结合体系理解:BoardUI Switch 是布尔输入,遗留 Switch 是 radio 分段器。修改既有控件复用其实现,不能为满足旧命名规则重写另一体系。涉及数值、媒体比例与取景时,以当前实现及对应测试为准。
组件选择
| 需求 | 使用 | 不要使用 |
|---|---|---|
| 字段、卡片、分区旁的持久反馈 | Note | Toast、空状态 |
| 页面/系统级问题与恢复动作 | Banner | Note |
| 短暂操作回执 | Toast | 持久 Note |
| 写操作前的确认 | confirmModal() |
原生 confirm()、Toast |
| 一个主动作加 1–4 个近亲做法 | Split Button(主动作在左,第一项菜单项与它同名同事) | 把变体摊平成并排按钮、把破坏性动作当主动作 |
| 一行内的重排 | wireDragReorder() 拖动 |
上下移动按钮 |
| 已知总量的进行状态 | Progress | 装饰性蓝条 |
| 用户触发动作等待结果 | Spinner | 旋转原操作图标、Loading Dots |
| 后台任务仍在推进 | Loading Dots | Spinner、假百分比 |
| 整页或大区块首次等待内容结构 | Skeleton | Spinner、Loading Dots |
| 2–3 个互斥视图 | 遗留 Switch(radio)或现有分段组件 | Toggle |
| 布尔开关 | 遗留 Toggle 或 BoardUI Switch | radio 分段器 |
| 无布局高度变化的菜单 | Menu/Listbox;开合走 presentMenu/dismissMenu,动效只在 Board 层那一份 |
Collapse 动画、自己再写一份 150ms |
| 带搜索语义的输入 | Search Input(搜索图标前缀;搜索中原位换 Spinner) | 无图标裸输入 |
| 全屏命令/设置覆盖层 | 有锁定证据的 Dialog motion | 把同一动画套给普通菜单 |
| 展开正文或分组 | Collapse | 自造 easing |
| 一组输入/候选及其底部动作 | Fieldset | 自造卡片 Footer |
| 固定高度区域中的溢出内容 | Scroller | 页面级滚动或嵌套滚动区 |
| 没有数据或结果 | Empty State(图标、标题、说明同组) | 裸灰字或把说明拆到组件外 |
| 图标含义与补充说明 | Tooltip | 让浮层撑宽页面 |
组件与视觉
- React 页面优先扩展现有 BoardUI 组合件;遗留 DOM 页面复用
frontend/src/ui-kit/,不为同一语义复制一次性 class 与模板。 - 需要全集排序、分页、跨页选择与批量操作的数据表复用 TanStack Table、BoardUI Table、
DataTableFrame与SelectionDock;少量静态关系沿用现有简单表格,不强加分页与选择。默认页大小与选择范围以实际页面契约为准。 - 管理页单面板分区的标题放在面板内,不在框外重复;多卡片分组可用框外标题。同级分区标题用
text-title-2-medium,加载态与内容态共用 500 字重、20px 字号和 26px 行高。 - 控件高度只取
--control-h-inline/-compact/--control-h/-large四档,同一行的同类控件同档;与文字同行的图标用--icon-inline,单独图标按控件档取固定值;下拉不点开也要看得出在选什么(上方标签、触发键前缀或格子选择器的弹层标题三选一)。判据与坏例见docs/DESIGN_GUIDELINES.md第 2、10、11 节。 - React 使用 BoardUI 语义 token,遗留样式使用对应
:roottoken;新增 token 须说明现有词汇无法表达的语义。 - 无图头像、首字母与默认人像复用 BoardUI 无图头像规范,同时核对承载面的深浅主题、悬停和选中态;不能把数据未取得当作动作禁用而降低前景对比度。表格、表单与浮卡使用完整字阶和对应间距,复用快照须包含 Peach 已登记的暗色例外。
- 字重只有 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注释。 - 遗留 Geist 层单色优先:
--tungsten只给焦点环、链接、进度/数据与 Toggle 开态。主动作用--ink底--ground字且每屏最多一个。标题悬停下划线不变蓝,计数徽章中性灰。其它选择器引用--tungsten由tests/test_web_ui.py拒绝;实测见vercel-geist-semantics-measured.md「选中态与开关色」「Button 全变体与状态」。 - 选中态只有填充:一律
--hover底--ink字,不加边框、不加inset一圈线、不加字重(Geist Switch/Tabs 的类名里三样都没有)。填充既然专属选中,同一排横向互斥选项的未选中项悬停就只提文字色到--ink;没有选中态的按钮和没有并排邻居的孤立开关悬停照旧抬填充。侧栏导航(.edge/.dnav)分工相反:实测 Geist 左栏是悬停抬填充、当前项握着文字与图标色,别把横排那条推广过去。清单见同一份快照的「选中态与它的悬停」和「侧栏导航是例外」。 - 按钮悬停只抬填充:次级到
color-mix(in srgb,var(--ink) 8%,var(--ground))(Geist gray-200 那一档,全站同一个值),主动作到color-mix(in srgb,var(--ink) 88%,var(--ground)),边框与文字色都不动。主动作那条悬停规则要自己写上color:var(--ground),否则同组更宽的通用 hover 里那句color:var(--ink)无人竞争,浅色实底上落成白字白底。禁用走--surface底、--border-15边、--muted字,不用opacity;按下不加scale。三条都有 Geist Button 源规则佐证。 outline:0/outline:none只允许出现在同一规则给出替代焦点样式的地方(box-shadow或子元素 outline),或输入框由带:focus-within的容器接管焦点时;reduced motion 由全局@media (prefers-reduced-motion:reduce)统一关闭,不逐处补。- 危险动作的悬停态一律
--drop实底加白字。只描红边、红字的话,静止态和悬停态在暗色底上几乎一样亮,按下去之前看不出这是不可逆动作;带文字的销毁按钮全站一个写法,纯图标删除键不适用。Geist 的 error Button 同样是实心红填充,只是它静止态就红。实测见vercel-geist-controls-measured.md。 - 按钮的前置图标只在图标指向对象(来源站点、当前选中项、平台)或形态方向(触发器右侧的
chevron-down)时出现;文字已经把动词说完的不加,+ 添加、↻ 刷新、✓ 保存这枚多余字形会把同一行主次动作的视觉重量拉平。图标键必须给aria-label,名称点出动作和对象、不描述图标形状。判据与 Geist Button 文档正文见docs/reference-snapshots/vercel-geist-button-icons.md;官方 Geist 图标 SVG 没有可直取的入口,同一份快照记了原因。 - 同一行里的输入框和按钮共用
--control-h,不各写一个像素数:两个控件差 3px 就不是一行了,而差值往往来自窄屏那条防放大规则只抬其中一个。 - 一枚字形只代表一个意思,同一个意思也只有一枚字形。取字形先问它指的是哪个名词或哪个方向:文件类型取
file-*,本地取hard-drive、订阅源取rss,往下接一页取chevron-down,原地换一批取shuffle,refresh-cw只归「去问一遍来源有没有更新」;筛不出结果和一次比对没有发现是两个空态,不能共用一枚。图标语义结合控件的可访问名称与实际操作复核。没有使用者的 symbol 从scripts/vendor_web_dependencies.mjs的名单和雪碧图里一起删,用户点名留的备用件在名单旁说明用途。 - 没有直接证据不得新增动效。菜单开合的证据是 boardui
menu-styles.ts(docs/BOARD_UI.md),已落在 board.css 的共用规则里;旧版 Geist 层仍无动画。 - 界面优先显示读数、当前状态与可执行动作,省略无助于决策的实现细节。费用、估算限制、隐私上传同意与不可逆操作的范围必须保留;单位跟随数字,必要口径放适当帮助入口。
等待与回执
- Progress 必须有真实
value/max、可见单位与aria-valuemin/max/now;分隔线放在完整指标(含进度条)之后。 - Spinner 只反馈用户直接触发的动作,触发器统一调用
setActionBusy():写入aria-busy=true与aria-disabled=true、视觉变灰、拦截重复触发,同时保持可聚焦;请求等待期不得再用原生disabled,它只留给缺输入、无权限等动作确实不可执行的状态。未知时长的后台抓取使用 Loading Dots。整页或大区块首次取数使用 Skeleton 预留最终结构。Spinner/Loading Dots 保留可见状态文字;Skeleton 只保留给辅助技术的状态名,不另画「正在读取」文案。三者都尊重 reduced motion。 - 用户写操作只在服务端终态成功后调用共享
actionReceipt()发一条过去时 Toast;可由安全逆操作完整恢复的状态提供 8 秒「撤销」,永久删除、凭据、保存到账本等不伪造撤销。仅打开面板/菜单/Dialog 不算操作完成,不发 Toast;失败除短 Toast 外仍在原位置保留原因与重试入口。 - 同一次页面进入只呈现一段等待态;深链启动与页面取数复用同一个 Skeleton,禁止 Spinner 再切换成 Loading Dots 或 Skeleton。
- 页面顶边的换页进度条(
navigation-progress.ts)顶替单页换页时不再出现的浏览器加载条,属于壳,不算页面的等待态:壳在取某一页首屏、或屏上组件在等第一份数据时亮,200ms 内画完不出现,出现后至少停 400ms。它只是不定进度,不报百分比,也不替代 Skeleton。 - Skeleton 只覆盖真正等待的内容区;静态标题、导航和能同步得到的筛选控件立即显示。骨架必须复用最终容器的宽度、列数与对齐方式:卡片网格横向铺满,居中面板仍居中,不得用一列通用占位替代不同页面结构。
- 骨架里的占位不接指针、没有任何悬停反馈(
09-skeleton.css一处关掉);要等数据才能执行的键用原生disabled加data-skeleton-action,呈全站共用的禁用面(--surface底、--border-15环、--muted字、not-allowed),不用 opacity,也不伪装成可点的最终档。 - 分页末尾、空页和「没有更多内容」是中性终止状态,用可关闭 Note;只有需要恢复或处理的故障才能进入红色 error Note。
- 上一次跑完的结果不常态显示。它是那一刻的快照,进页面就铺开会被读成现在的状态,而页面上没有任何东西说它是旧的;只有仍在进行的任务才自动接管页面。
- Empty State 的标题和说明必须同处组件内;全页空态与上方工具条统一留 16px,不得再套一层空卡片。
表单与浮层
- 遗留 Switch 分段器共享 radio
name、初始一个checked并支持键盘;布尔状态使用对应体系的布尔控件,BoardUI Switch 不采用 radio 契约。 - 菜单每项包含与入口相同的图标和文字,菜单内部滚动、
overscroll-behavior:contain,不得把浏览器页面撑出滚动条。锚定菜单一律走wireAnchoredMenu:高度压到触发钮那一侧真正剩下的空间(上沿是--topH顶栏下缘),装不下就在菜单内滚,不横跨触发钮;页面滚动关掉菜单,菜单自身的滚动不关。 - 只读查询(搜索、筛选)不配提交按钮:回车即执行,忙态落在表单自己身上(
form[aria-busy]加前缀原位换 Spinner)。有副作用的提交必须有按钮,且回车同样要能提交。表单里除这个输入框外还有别的字段时浏览器不做隐式提交,回车要自己接管requestSubmit()并跳过isComposing。判据与实测见docs/reference-snapshots/vercel-forms-submit-affordance.md。 - 确认弹层一律走
confirmModal():原生<dialog>承载,标题是陈述句,正文先说后果并点名 涉及的两个值,主按钮是与标题同一动词的「动词+名词」,取消键就写「取消」,成功 Toast 与主 按钮的动词一一对应。写入交给onConfirm,忙态落在主按钮上,失败时弹层不关、原因留在正文 下方等重试。形状与文案判据见docs/reference-snapshots/vercel-geist-modal-measured.md。 - 下拉框的用途用框内左侧 16px 前缀图标标明,不在同一行挂一个文字标签:Geist 的文字 Label 是块级、排在控件上方,行内并排那种写法它没有,而工具行没有上方空间。无障碍名称改由
aria-label承担。 - 弹层标题栏与滚动正文分层:标题分隔线属于卡片全宽,滚动条只属于正文。
- Fieldset 的正文统一 20px 内边距;标题条与底部操作条同为
--fieldset-bar-h(52px)、竖直居中、左 20px 右 16px。标题放在框体里,不用原生<legend>:它会在上边框上开缺口,同组卡片内容高度不同时缺口位置也跟着不齐。同组卡片必须同高,变化内容只放一个纵向 Scroller。
媒体与页面状态
- 关注来源标签先服从来源记录的类型:只有明确标为
general的标签才能进入卡片、顶部筛选和在线标签页,artist/character/copyright/metadata与未知类型不得靠词形猜成general。通用词清理是第二道门槛,只处理已经确认的general;详情可显示全部来源标签,并按真实类型着色。 - 播放器控制条的窄屏折叠按播放器自身宽度判定(
ResizeObserver观察player.el()),不用媒体查询:同一个视口下影院模式和普通视图的播放器宽度差一大截,用视口判据会在影院模式下白折叠、在普通视图下继续超框。门槛与提示外观见youtube-player-controls-user-screenshot.md。 - 任何先请求再重绘整页的入口都必须绑定导航代际;只比较
location.pathname不能防住「离开后快速返回同一路径」的旧响应。