UX Baseline Check 是 agentic-design-system 中的一项技能，定位为 ADS 状态与组件契约的负责人。它的作用范围是：根据所请求的行为和产品契约来选择状态，而不是罗列所有可以想象的状态。例如一处很小的文案或间距修改，只需检查其受影响的行为，不必凭空引入加载、表单、权限或额外屏幕。该清单属于同一次工作或评审过程的一部分，而非单独的仪式。
组件契约先于复制
在引入新的可复用组件或复制现有组件之前，应从既有代码、类型或 stories 中恢复或定义其契约。当这些来源已经能回答以下问题时，不要求单独编写文档：结构与内容槽位；属性与有意义的变体；适用的数据、交互、校验、加载、错误与成功状态；目标断点下的响应式行为；键盘、指针、触摸与语义行为；它所复用的既有组件与 token。每个实例都应遵循同一契约。缺少该契约的组件尚不具备被广泛复制的条件。
状态清单
在任何页面或组件被视为“完成”之前，需验证每个适用状态是否存在：
-
数据状态 空状态——尚无数据。应提供有帮助的提示信息与明确的行动号召，而不是空白屏幕。 加载状态——保留内容几何结构并暴露真实的待处理工作；不要为了展示加载器而延迟已缓存或快速返回的数据。 已加载——即正常路径。 错误——API 失败、网络问题。提供用户友好的信息与重试操作。 部分——部分数据加载成功、部分失败。不要隐藏已正常工作的部分。 长内容——200 个条目会怎样？2000 字符的名称会怎样？需要实际测试。
-
交互状态 悬停——适当的指针反馈；不要让触摸或键盘使用依赖悬停。 聚焦——键盘导航可用，焦点环可见。 激活/按下——按钮对点击有视觉响应。 禁用——使用原生语义并保持可读状态；必要时在附近持久文案中说明原因，而不是依赖需要聚焦禁用控件才能看到的工具提示。 选中——多选、当前标签页、活动筛选器都应视觉上可区分。
-
表单状态 校验——及时的字段级指引，失焦或提交时机应与任务相匹配；不要过早拒绝未完成的输入。 必填字段——清晰标记。 成功反馈——用户知道其操作已生效（toast、内联提示、重定向）。 破坏性恢复——对可逆操作优先提供撤销；对真正不可逆或后果重大的操作进行确认，并保留产品的权限模型。 自动填充——浏览器自动填充时不会破坏布局。
-
响应式 使用受支持的目标断点；以下为示例宽度，并非四次强制截图： 移动端（375px）——可用，而不仅仅是可见。触摸目标 ≥48px，间距 ≥8px。 平板（768px）——布局应适配，而不仅仅是缩小。 桌面（1280px）——主要目标，看起来应是有意设计的。 宽屏（1800px+）——内容不应被荒谬地拉伸。使用最大宽度或居中。
-
无障碍 键盘导航——可用 Tab 到达所有交互元素。 屏幕阅读器——语义化 HTML，图标带 aria-label，图片带 alt 文本。 颜色对比度——测量最终合成颜色是否满足适用的文本/控件要求；不要假设不透明度百分比能证明对比度。 不依赖颜色单一指示——不要仅靠红/绿表示状态。
-
边界情况 首次用户——引导页或空状态提供指引。 权限被拒——用户能看到无法访问的原因，而不是一个损坏的页面。 数据过期——数据可能过时时提供时间戳或刷新指示。 并发编辑——两人同时编辑同一内容时会发生什么？
相邻操作一致性
对于被改动的只读、禁用、离线、权限受限或破坏性状态，需在受影响的断点检查附近每一个主要、次要、工具栏和内联操作。标签、强调、启用状态、原生语义与辅助文本必须与该状态一致。在保留未受影响状态中有效操作的前提下，移除、禁用、重新标记或解释矛盾之处。修复后需再次验证；仅修复被点名的控件是不够的。
在 ADS 流程中的使用
在实现前识别适用状态，并在给出设计结论前实际演练这些状态。小的表单改动仍需要相关的表单与无障碍检查；静态页面不需要虚构异步状态。必需的缺失状态应保持未决，并阻止声称该功能已完成。将不可获得的证据或有意推迟的产品决策与通过状态分开记录。对于有意义的交互改动，使用真实浏览器，包括在适用时使用目标移动端/WebKit 环境。仅凭源字符串和截图无法确立状态转换。