# 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 场景）
- 不支持：多点触控手势

---