ui/docs/prd/user-interface-design-goals.md

User Interface Design Goals

Overall UX Vision

打造简洁、专业、高效的控件库 UI 体验，服务于上位机和 AI 桌面应用的专业用户群体。设计语言基于 Semi Design 样式系统，结合苹果颜色系统的语义化设计，提供现代化的视觉呈现和流畅的交互体验。

核心设计原则：

• 信息密度优先：上位机场景需要在有限空间内展示大量配置项，PropertyGrid 应紧凑但不拥挤
• 即时反馈：所有用户操作（主题切换、属性编辑、引导步骤）应有清晰的视觉反馈
• 最小化学习成本：控件行为应符合 Windows 桌面应用的常见约定（如右键菜单、拖拽、快捷键）
• 暗色模式友好：考虑到长时间使用场景，暗色模式应与浅色模式同等重视，避免高对比度引起的视觉疲劳

Key Interaction Paradigms

1. 属性编辑（PropertyGrid）：

   • 聚焦即编辑：点击属性值区域直接进入编辑状态，无需额外的"编辑"按钮
   • Tab 键导航：支持 Tab 键在属性间快速切换，提升键盘操作效率
   • 即时验证：属性值变化时立即触发验证（依赖 Avalonia 内置机制），错误时显示红色边框和提示图标

2. 主题切换：

   • 全局响应：主题切换命令应在应用级别生效，所有窗口和控件自动同步
   • 平滑过渡：颜色变化应有微妙的过渡动画（100ms），避免突变

3. 新手引导（UserGuide）：

   • 非模态引导：引导流程不应阻塞用户操作，用户可以随时跳过或关闭
   • 渐进式聚焦：使用 Overlay 半透明遮罩突出当前引导目标，其他区域半透明但仍可见
   • 步骤指示：显示当前步骤和总步骤数（如"2/5"），让用户了解进度

4. 响应式布局：

   • PropertyGrid 的 2xN Layout 应在窗口缩放时自动调整标签和编辑器的宽度比例
   • 最小宽度约束：PropertyGrid 最小宽度 300px，低于此宽度应显示水平滚动条

Core Screens and Views

注意：本项目是控件库，不是完整应用，因此"核心屏幕"指的是控件的典型使用场景和示例页面。

1. PropertyGrid 示例页面

   • 展示包含多种属性类型的配置面板
   • 演示属性分组、只读属性、验证错误等状态

2. 主题切换示例页面

   • 提供主题切换按钮或下拉菜单
   • 展示不同主题下的控件外观对比

3. UserGuide 引导示例页面

   • 模拟真实应用的新手引导流程
   • 包含 3-5 个引导步骤，覆盖不同位置和交互

4. 综合 Demo 页面

   • 集成所有 MVP 控件的完整示例
   • 提供侧边栏导航，方便测试各个控件

Accessibility

等级： None（MVP 阶段不作为优先级）

说明：

• MVP 阶段暂不支持 WCAG 标准的无障碍访问特性（如屏幕阅读器支持、高对比度模式）
• 基础的键盘导航（Tab、Enter、Esc）会在控件实现中自然支持
• 颜色设计遵循 4.5:1 的对比度建议（Semi Design 默认已满足），但不进行正式的 WCAG 测试
• Post-MVP 阶段如有需求，可考虑支持 WCAG AA

假设依据： Brief 中未提及无障碍访问需求，上位机和 AI 桌面应用的目标用户群体通常不包括视障人士。

Branding

样式基础： Semi Design 样式库

颜色系统： 苹果颜色系统（语义化颜色）

• Primary Color（主色）： 用于主要操作按钮、选中状态、链接等（具体色值由 UX Expert 在架构阶段定义）
• Success/Warning/Error： 使用语义化的绿色/橙色/红色系统，暗色模式下自动调整为更柔和的色调
• Background/Surface： 多层级背景颜色（bg-primary, bg-secondary, surface-elevated），支持深度感

字体：

• 西文：Segoe UI（Windows）、San Francisco（macOS）、Roboto（Linux）
• 中文：微软雅黑（Windows）、苹方（macOS）、Noto Sans CJK（Linux）
• 代码：Consolas、Menlo、Source Code Pro

图标：

• MVP 阶段暂不引入独立的图标系统
• 必要的图标（如验证错误、引导箭头）使用 Avalonia 的 PathIcon 或 Semi Design 自带图标

品牌个性：

• 专业（Professional）： 工业级的稳定性和可靠性
• 现代（Modern）： 拥抱最新技术栈，不拖泥带水
• 务实（Pragmatic）： 功能优先于花哨特效

Target Device and Platforms

主要平台： Windows 桌面（Windows 10/11）

次要平台： Linux 桌面（Ubuntu 20.04+, Debian 11+）

• 注意：Linux 场景主要是 Linux Pad 设备（如工业平板），不支持多点触控
• Linux 下的字体渲染和主题切换可能与 Windows 有细微差异，优先保证 Windows 体验

可选平台： macOS（不作为 MVP 测试平台，但架构上不排斥）

设备类型： 桌面应用，屏幕分辨率主要为 1920x1080 及以上

• 最小支持分辨率：1366x768（部分工业平板）
• 不支持移动端（手机/平板触摸交互）

输入方式：

• 主要：鼠标 + 键盘
• 次要：触控笔（在 Linux Pad 场景）
• 不支持：多点触控手势

---