ux

UX — 设计价值与执行清单

LobeHub 产品应给人的感受，以及实现这些体验的具体规则。在构建或评审任何面向用户的流程时，请使用本文档。

本文档是索引：下方的设计价值和交互原则构成概念层；执行清单则位于各模块的参考文件中（见清单模块）。每条清单项都会标注其服务的设计价值。

内容分布：DESIGN.md 与本技能

两份文档，各司其职——不要重复内容，而要交叉引用。

• DESIGN.md — 设计系统：产品的视觉与表达方式。可主题化的令牌（颜色、排版、层级、圆角）、组件清单，以及语气与内容（措辞、语气）。需要令牌值、组件或文案语气时，请查阅此文档。
• 本 ux 技能 — 交互行为：流程应如何随时间变化。空状态／加载状态／错误状态、大规模列表、选择可见性、选择器、数字格式、草稿安全、操作流程与推进节奏、按钮层级、实体生命周期、能力边界、渐进式披露。

经验法则：静态外观与措辞 → DESIGN.md；动态行为 → 本技能。 关于组件／样式选择，请参阅 react；关于命令式模态框接线，请参阅 modal。

设计价值

LobeHub 遵循四项产品设计价值——Natural・Meaningful・Certainty・Growth。 设计前请先阅读： references/design-values.md（定义与冲突优先级）。

交互原则

当一个流程存在多种合理的交互模式时，请先遵循这些原则，再查看执行清单。

保持界面承诺・Meaningful・Natural

每种界面都承载着一项任务承诺：聊天界面让用户持续进行工作对话，文档页面支持专注阅读／编辑，设置页面支持配置，依此类推。默认交互应延续这一承诺，而不是意外地将用户带入另一种模式。对于查阅和辅助工作，优先采用上下文内界面（portal／面板／抽屉）；只有在需要专注处理已确认的内容或明确切换模式时，才使用整页导航。

一致性关乎语义，而非机械统一・Certainty・Meaningful

一致性意味着相同的用户意图在同一界面中会有相同的行为，并不意味着同一组件在所有地方都必须执行相同操作。当一个组件跨界面复用时，应由父级界面提供交互策略，让行为遵循用户意图，而不是实现上的便利。

布局传达角色・Natural・Certainty

元素的位置是界面语言的一部分。身份与位置（面包屑、标题、对象标签）应与状态和操作（保存状态、共享、面板开关、更多菜单）清晰区分。如果这些角色混在一起，用户就得自行判断某个元素是在描述当前对象，还是在对其执行操作。

组合规范界面组件，不要重新实现・Certainty・Natural

如果当前代码库中已有某类界面的规范组件——侧边栏行 → NavItem，可折叠分组 → Accordion / GroupedAccordion，激活状态的界面 → Block variant='filled'——就应组合使用，不要用原始的 <div>／<button>／<input> 加上特制的 createStaticStyles 代码块重新搭建外观。手工实现的平行版本会重新定义内边距、悬停／激活状态、对齐方式和悬停时显示的行为，也会在每个细节上与同类组件产生偏差——即使每处差异都很小，整体仍会显得“不够精致”。在构建列表／导航／主从面板前，先查找同类界面使用的基础组件（搜索 NavItem、Accordion）并组合使用；只有遇到真正全新的行类型时，才退而使用原始元素。完整模式请参阅**阅读 §1.10**；react 的组件优先级规则说明了具体做法。

页面上下文中的审核消息・确定性

区分常规说明与会阻止操作的状态；不要为不同用途堆叠同等醒目的警告横幅。限制说明必须指出当前条件和下一步操作，并使用精确的产品实体（例如，区分模型与其提供方）。检查整个页面，而不只是已更改的组件。

检查清单模块

按交互类型分组——即用户正在执行的操作类型。跳转到与你正在构建的界面相匹配的模块；一个界面通常涉及多个模块（可编辑列表属于 Read + Edit + Act）——逐一检查适用的模块。

• Read — 查看数据和列表：空状态 / 加载状态 / 错误状态、大规模列表、选择项可见性、选择器完整性、数字格式、默认视图。
• Edit — 输入和修改内容：保护进行中的草稿，绝不丢失输入内容。
• Act — 操作、流程和按钮：推动流程前进、一个主按钮、实体生命周期完整性。
• Feedback — 加载视觉效果和能力防护措施。
• Grow — 可发现性和渐进式披露。

快速检查清单

使用此清单找出适用的检查项，然后阅读链接模块，了解完整要求和示例。实现细节和案例历史应保留在相应模块中，不要在此重复。

Read — 查看数据和列表（read.md）

• 区分首次使用时的空状态、无搜索结果、加载状态和失败状态；在持久显示的界面框架下方提供有用的正文状态。
• 在空状态、未找到、聚合值为零或静态备用条目掩盖错误之前，先处理获取错误。
• 通过分页、虚拟化和批量操作（按需采用），支持从 1 行到 10k 行的列表。
• 搜索、筛选、排序、计数和批量操作范围应覆盖整个数据集，而不只是已加载的页面。
• 选中项所在行出现后，将其滚动到可视区域；已在可视区域内的选中项不要移动。
• 选择器应包含所有有效目标，包括默认选项和收件箱选项。
• 使用共享的数字格式化器，并处理 K/M/B/T 单位进位；绝不显示 ≥ 1000 的系数。
• 根据进入意图和已解析的数据选择初始视图；保留手动选择，并确保可以访问集合级操作。
• 实时信息流应提示更新、允许手动刷新、保留阅读位置，并区分刷新失败。
• 确保条件轮询可靠启动；未知或失败的实时状态绝不能使项目符合破坏性批量操作的条件。
• 为大型导航界面提供搜索、筛选或跳转功能。
• 注册表卡片应一致地显示拥有 / 已安装状态和信任状态；贡献入口应跳转到应用内提交流程。
• 复用规范的列表行和分组组件；参见 Read §1.10 和 react 技能。
• 在持久显示的编辑框下方保持已填充列表可见；对不断增长的编辑器设定上限或将其折叠。
• 状态标签应准确描述每个成员。
• 将嵌入文档折叠为带标题的行，并展开为使用从属排版的全文。
• 没有图片的实体应回退到共享的类型图标，绝不使用名称首字母头像或 UI 标签。

Edit — 输入和修改内容（edit.md）

• 在重新加载、保存失败和切换项目时保留并恢复草稿；破坏性退出前应发出警告或先保存。
• 保持占位符稳定，并确保占位符之外的有意义内容仍可检索。

Act — 操作、流程和按钮（act.md）

• 成功操作会进入结果页；终端页面会提供可执行的后续操作或退出方式。
• 会改变后续步骤的结果应予以保留；临时确认信息则使用 toast 提示。
• 同时提供批量操作和单项操作入口。
• 在需要时显示确认信息、锁定进度和操作结果。耗时的原子操作应关闭确认界面，并在发起操作的界面上显示进度。
• 长时间运行或成本较高的操作应支持运行时取消，并在失败后重试。
• 显示乐观更新和任务控制失败；绝不静默回滚。
• 编辑后保持列表视图与详情视图同步。
• 将操作和状态固定在可滚动内容之外；验证内容溢出的状态。
• 每个界面只设置一个视觉上最突出的主要操作。
• 根据各实体的来源提供相应的生命周期操作；在每种移除方式中遵守固定／保留／锁定设置。
• 显示当前操作的身份，并提供切换账户或重新认证的途径。
• 对不可恢复或影响范围较大的破坏性操作，要求用户执行明确的手势，并报告部分失败。
• 新生成的密钥仅展示一次并提供复制功能，随后进行遮蔽；仅供校验的密钥应进行哈希处理，服务器需要以明文使用的协议凭据应加密；按需在实体自身的行中生成凭据，而非在创建时生成。
• 用户记忆／个人资料存储应支持更正、保留但不使用、导出，以及撤销或软删除。

反馈 — 加载与系统响应 (feedback.md)

• 加载形式符合 feedback §4.1 中的场景表。
• 骨架屏结构应匹配经测量的渲染布局，包括平台和路由变体。
• 加载和加载更多失败时，应提供清晰的恢复途径；失败项应保留，而非自动消失。
• 依赖数据的获取门控应在数据已确定、数据不存在或发生错误时解除；错误／未找到分支应保持可访问。
• 等待中的写入操作失败后，应解除控件的忙碌状态；自动保存应显示保存中、已保存和失败状态，并提供重试。
• 使用本地化、易于理解的错误信息；将内部 ID 保留在结构化检查字段中，对于可确定的失败，应首先说明解决方法。
• 能力警告应随状态变化，并等待配置解析完成；区分模型选项与平台限制。

成长 — 可发现性与渐进式披露 (grow.md)

• 在适当时展示高级功能，同时避免让新手使用路径显得繁杂。
• 键盘提示应对应实际可用的快捷键，并在运行中的 UI 中验证。
• 配置界面应链接到该功能的数据或管理区域。
• 超过两步的流程应显示进度，并允许跳过非必要步骤，同时提供退出方式。

相关技能

• ux-audit — 以 Designing Interfaces 为基准，对单个界面进行可重复的审查；运行此技能以找出差距，并将改进纳入这些检查清单。
• modal — 用于确认／进度／完成流程的命令式 createModal 状态机接线。
• DESIGN.md（语气与内容）— 确认／完成／空状态／错误状态的措辞。
• react — 组件优先级、Button 用法和样式。