From 9bbaa2c53b6d58ce9fe9eefc80fdc52da918cce3 Mon Sep 17 00:00:00 2001 From: lofyer Date: Tue, 11 Aug 2026 20:07:58 +0800 Subject: [PATCH] docs: rename UI design guide and clarify switches --- AGENTS.md | 7 +++++++ DESIGN.md => UI-DESIGN.md | 14 ++++++++++++++ 2 files changed, 21 insertions(+) rename DESIGN.md => UI-DESIGN.md (95%) diff --git a/AGENTS.md b/AGENTS.md index 14d8755..ddb458c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,10 +60,17 @@ Keep Electron security boundaries intact: ## UI Consistency +- Treat `UI-DESIGN.md` as the canonical UI design system. Read and follow it + before changing renderer layout, shared controls, interaction feedback, + themes, responsive behavior, or accessibility semantics. - Reuse the shared `PageTabs` and `SegmentedControl` primitives instead of creating page-specific tab or toggle styles. A semantic tab set may use the shared segmented visual variant, but it must retain `tablist`, `tab`, `tabpanel`, `aria-selected`, roving focus, and arrow-key behavior. +- Use the shared sliding Switch pattern for persistent binary states and expose + `role="switch"` even when it is implemented with a checkbox input. Keep + Checkbox visuals and semantics for multi-select, assignment, and explicit + confirmation. Do not create page-specific Switch styling. - Use the bundled `Inter Variable` and `Noto Sans SC Variable` UI fonts through the shared typography tokens. Do not add remote font requests or page-local font stacks. Keep redistributed font licenses in packaged resources and diff --git a/DESIGN.md b/UI-DESIGN.md similarity index 95% rename from DESIGN.md rename to UI-DESIGN.md index 3cc3a6e..3059e00 100644 --- a/DESIGN.md +++ b/UI-DESIGN.md @@ -317,6 +317,19 @@ - 就地错误必须与对应字段或操作建立程序化关联；全局错误使用 `alert` 和 assertive 实时区域，成功与信息使用 `status` 和 polite 实时区域。 - 一个事件只能选择一种主要反馈位置，不得同时显示页内横幅和全局通知。失败时不得因通知切换而清空用户输入、筛选或未提交草稿。 +### 6.12 Switch 与 Checkbox + +Switch 用于在两个持久状态之间立即切换，例如启用能力、开启索引、允许群消息或显示平台入口。Checkbox 用于独立多选、范围分配或执行前确认，例如选择多个 Runtime、选择知识库、清除已保存密钥。两者不得只因底层都使用 `input[type="checkbox"]` 而混用视觉或语义。 + +- 二元启停必须使用共享滑动开关视觉，当前实现复用 `toggle-row`，不得显示为原生方形 Checkbox。 +- Switch 底层可以使用 `input[type="checkbox"]`，但必须声明 `role="switch"`，通过原生 `checked` 状态暴露开关状态，并具有持久、明确的可访问名称。 +- Checkbox 保留原生 Checkbox 语义和方形勾选视觉，不得添加 `role="switch"`。多项分配、列表选择、确认声明和“保存时清除密钥”等一次性选择均属于 Checkbox。 +- 不创建页面专属 Switch 样式。需要紧凑布局时仍复用同一轨道、滑块、焦点环、禁用状态和动效，只调整共享组件支持的布局变体。 +- Switch 支持 Tab 聚焦和 Space 切换，键盘焦点至少显示 `2px` 高对比焦点环。可见标签应描述被控制的能力，不能只显示“开 / 关”。 +- 异步切换期间禁用重复操作并保留原状态。失败时恢复或保留最后确认状态，通过应用通知或就地可恢复错误说明原因。 +- 涉及联网、上传、电脑控制或其他外部影响的 Switch，附近必须持续说明数据去向、权限范围或风险，不能只靠设置名称表达影响。 +- 自动化测试应按 `switch` 角色查询二元开关，按 `checkbox` 角色查询多选或确认项，防止视觉迁移后语义回退。 + ## 7. 交互状态 所有可交互组件必须实现： @@ -567,6 +580,7 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证 - [ ] 使用 `SegmentedControl` 统一少量互斥视图和状态切换。 - [ ] 需要分段外观的同级面板使用 `PageTabs` 的共享 `segmented` 变体，不复制控件样式。 - [ ] 建立统一筛选工具栏，移除以页签样式伪装的筛选。 +- [ ] 二元启停统一使用共享 Switch 视觉与 `role="switch"`，多选、范围分配和确认项保留 Checkbox。 - [ ] 将短期成功、信息和非局部异步错误接入应用通知视口，移除页面专属通知横幅。 - [ ] 实现 `ScopeBadge` 并覆盖全局、项目、失效和可切换状态。 - [ ] 实现 `EmptyState` 的首次为空、无结果、失败和只读变体。