docs: rename UI design guide and clarify switches

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

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` 的首次为空、无结果、失败和只读变体。