chuan/ui

Files

chuan c4a9b8d8d4 feat: 实现暗色主题和完善颜色系统架构

- 完成三层颜色架构实现（Primitives → Semantic → Component）
- 新增暗色主题支持，包含完整的 Apple HIG Dark Mode 色值
- 重构颜色系统为六类别架构（Background, Foreground, Border, Accent, State, Surface）
- 完善颜色演示页面，按类别分组展示所有颜色
- 更新主题切换说明，支持手动切换浅色/暗色主题
- 新增 BMad 方法文档和架构说明
- 完善 README 和技术栈文档

2025-10-17 18:16:14 +08:00

50 KiB

Raw Blame History

Penguin.AvaloniaUI Product Requirements Document (PRD)

Project Name: Penguin.AvaloniaUI Version: 1.0 Date: 2025-10-15 Status: Ready for Architecture PRD Completeness: 88%

Goals and Background Context

Goals

在 1 个月内完成 MVP，验证 PropertyGrid 和 UserGuide 的核心功能
建立基于 Semi Design 和苹果颜色系统的多主题框架，支持至少 2 种主题（浅色、暗色）和运行时切换
实现支持国际化扩展的架构，MVP 阶段默认使用一种语言，预留语言切换扩展点
完成 PropertyGrid 控件，支持常用属性类型（string, int, double, bool, enum, DateTime），实现自动 UI 生成、属性分组和基础验证
完成 UserGuide 系列控件，包括新手引导流程和增强 Tooltip，提升用户体验
确保架构设计考虑未来 AOT 编译支持，MVP 阶段允许使用反射
在开发过程中产出 5+ 个可复用的基础控件和工具类（TwoColumnLayout、Overlay、RichTooltip、ThemeManager 等）
为后续控件开发（LoggingControl、TextEditor 等）打下坚实基础

Background Context

当前 Avalonia 生态主要聚焦于基础控件库（Button、TextBox 等），但真正加速开发的是业务场景集成控件（PropertyGrid、LoggingControl、UserGuide），这些在上位机和 AI 桌面应用场景中尤为关键。开发者被迫在每个项目中重复实现相似的复合控件，平均花费 30-50% 的时间在这些重复工作上。此外，许多现有库为了兼容旧版本（.NET Framework、Avalonia 0.x），牺牲了现代特性，AOT 支持不完善。

本项目旨在填补这一空白，采用自顶向下开发策略：先定义业务控件需求，再从中分解必要的基础控件。我们专注于上位机和 AI 桌面应用场景，基于 .NET 8+、Avalonia 11.x、ReactiveUI 和 Semi Design 样式系统，打造一套现代化、高度场景化的业务控件库。与传统控件库追求极致通用性不同，我们允许合理的取舍，优先满足目标场景的核心需求，确保开发效率和技术栈的前瞻性。

Change Log

Date	Version	Description	Author
2025-10-15	1.0	Initial PRD creation	PM Agent

Requirements

Functional Requirements

FR1: 系统应提供基于苹果颜色系统的三层架构颜色定义（Primitives → Semantic → Component），包含完整的 Apple 官方色值，支持 2 种预设主题（浅色、深色）和语义化颜色使用

FR2: 系统应提供 ThemeManager API，允许运行时动态切换主题，且主题切换应流畅无闪烁，所有控件自动响应主题变化

FR3: 系统架构应支持国际化扩展，MVP 阶段默认使用一种语言（中文或英文），预留语言切换扩展点，为后续多语言支持打下基础

FR4: PropertyGrid 应能够从数据模型自动生成属性编辑 UI，支持以下基础属性类型：string, int, double, bool, enum, DateTime

FR5: PropertyGrid 应支持属性分组功能，允许开发者将相关属性组织在一起，提升配置界面的可读性

FR6: PropertyGrid 应支持只读属性标记，只读属性应显示但禁止编辑

FR7: PropertyGrid 应使用 2xN Layout 布局（左侧标签，右侧编辑器），确保界面整齐对齐

FR8: PropertyGrid 可选支持 IPAddress 和 FilePath 属性类型，满足上位机场景的常见配置需求（MVP 阶段可根据开发进度决定是否实现）

FR9: UserGuide 应提供步骤式引导流程控件，支持配置引导步骤（目标控件、提示文本、相对位置），支持上一步、下一步、跳过操作

FR10: UserGuide 应提供增强 Tooltip 控件，支持基础富文本显示（粗体、斜体、换行）

FR11: UserGuide 应提供 Overlay 遮罩控件，用于聚焦引导目标，半透明背景突出当前步骤

FR12: 所有控件应基于 ReactiveUI 实现数据绑定和交互逻辑，支持 Command、Reactive、Event 混合使用

Non-Functional Requirements

NFR1: 所有控件必须支持 .NET 8+ 和 Avalonia 11.x 或更高版本，不向后兼容旧版本

NFR2: 系统架构设计应考虑未来 AOT 编译支持，MVP 阶段允许使用反射（PropertyGrid 可基于反射实现，后续可通过 Source Generator 优化）

NFR3: UI 渲染性能应达到 60fps（16ms 每帧），控件交互应流畅无卡顿

NFR4: 主题切换应在 100ms 内完成，用户感知无延迟

NFR5: PropertyGrid 对于包含 50 个属性的模型，UI 生成时间应小于 200ms

NFR6: 控件应支持 Windows（主要）、Linux（次要）、macOS（可选）平台，优先保证 Windows 体验

NFR7: 代码应遵循 C# 编码规范，使用清晰的命名和注释，便于后续维护

NFR8: 控件应具备良好的可扩展性，支持开发者通过模板（Template）和样式（Style）自定义外观，这是控件库的基本要求

NFR9: MVP 阶段应提供基础文档（README 和使用示例），核心控件（PropertyGrid、UserGuide）应有完整的代码示例

NFR10: 项目应使用 Git 进行版本控制，关键里程碑应有清晰的提交记录和标签

NFR11: 应提供 ReactiveUI 在 Avalonia 控件开发中的快速入门文档和代码示例，降低团队学习成本

User Interface Design Goals

Overall UX Vision

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

核心设计原则：

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

Key Interaction Paradigms

属性编辑（PropertyGrid）：
- 聚焦即编辑：点击属性值区域直接进入编辑状态，无需额外的"编辑"按钮
- Tab 键导航：支持 Tab 键在属性间快速切换，提升键盘操作效率
- 即时验证：属性值变化时立即触发验证（依赖 Avalonia 内置机制），错误时显示红色边框和提示图标
主题切换：
- 全局响应：主题切换命令应在应用级别生效，所有窗口和控件自动同步
- 平滑过渡：颜色变化应有微妙的过渡动画（100ms），避免突变
新手引导（UserGuide）：
- 非模态引导：引导流程不应阻塞用户操作，用户可以随时跳过或关闭
- 渐进式聚焦：使用 Overlay 半透明遮罩突出当前引导目标，其他区域半透明但仍可见
- 步骤指示：显示当前步骤和总步骤数（如"2/5"），让用户了解进度
响应式布局：
- PropertyGrid 的 2xN Layout 应在窗口缩放时自动调整标签和编辑器的宽度比例
- 最小宽度约束：PropertyGrid 最小宽度 300px，低于此宽度应显示水平滚动条

Core Screens and Views

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

PropertyGrid 示例页面
- 展示包含多种属性类型的配置面板
- 演示属性分组、只读属性、验证错误等状态
主题切换示例页面
- 提供主题切换按钮或下拉菜单
- 展示不同主题下的控件外观对比
UserGuide 引导示例页面
- 模拟真实应用的新手引导流程
- 包含 3-5 个引导步骤，覆盖不同位置和交互
综合 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 场景）
不支持：多点触控手势

Technical Assumptions

Repository Structure: Monorepo

决策： 采用 Monorepo 结构，所有代码在单一 Git 仓库中管理

目录结构：

D:\32_avalonia.ui/
├── src/
│   ├── Penguin.AvaloniaUI/              # 核心控件库项目
│   ├── Penguin.AvaloniaUI.SourceGenerators/  # Source Generator（可选，Post-MVP）
│   ├── Example/                         # 示例应用项目
│   └── Penguin.AvaloniaUI.Tests/        # 单元测试项目
├── docs/                                # 文档
└── .bmad-core/                          # BMAD 框架配置

Rationale:

Monorepo 简化了控件库和示例应用的协同开发，便于快速迭代和测试
依赖管理更简单，所有项目共享同一个 NuGet 依赖版本
MVP 阶段项目数量少（3-4 个），Monorepo 不会带来复杂度负担
未来如果需要拆分（如 Source Generator 独立发布），迁移成本也可控

Service Architecture

架构类型： 单体库（Monolithic Library）

说明：

Penguin.AvaloniaUI 是一个单一的 .NET 类库项目，所有控件作为命名空间组织在同一个程序集中
不采用微服务或独立的控件包（如每个控件一个 NuGet 包），避免过度设计和版本管理复杂度
控件之间可以有依赖关系（如 UserGuide 依赖 Overlay），但应尽量保持松耦合
使用命名空间隔离不同功能模块：
- Penguin.AvaloniaUI.Controls - 业务场景控件
- Penguin.AvaloniaUI.Layouts - 布局控件
- Penguin.AvaloniaUI.Themes - 主题和样式
- Penguin.AvaloniaUI.Utils - 工具类

架构约束：

所有控件必须继承自 Avalonia 的标准控件基类（TemplatedControl、UserControl 等）
样式和模板通过 Avalonia 的资源字典（ResourceDictionary）组织
主题切换通过 Application.Current.Resources 动态加载不同的资源字典实现

Testing Requirements

测试策略： 单元测试 + 手动集成测试

单元测试范围：

核心业务逻辑：PropertyGrid 的属性解析、UserGuide 的步骤流转逻辑
工具类：ThemeManager、LocalizationManager（如果实现）等
数据绑定和验证：PropertyGrid 的数据模型和 ReactiveUI 集成

不包括的测试：

UI 渲染测试（Avalonia 的渲染层不易测试，依赖手动验证）
跨平台兼容性测试（MVP 阶段只在 Windows 上测试）
性能基准测试（除非发现明显的性能问题）

手动测试：

使用 Example 项目作为主要测试载体
每个控件应在 Example 中有独立的演示页面
测试场景包括：主题切换、属性编辑、引导流程、异常处理

测试框架：

xUnit 作为单元测试框架
FluentAssertions 用于断言（可选）
不引入 UI 自动化测试框架（如 Appium）

Rationale:

MVP 阶段时间紧张，优先保证核心逻辑的正确性，UI 渲染依赖手动测试
上位机和 AI 桌面应用通常不需要极高的测试覆盖率（不像 Web 应用需要应对大规模用户）
Example 项目本身就是"活文档"，可以作为回归测试的基准

Additional Technical Assumptions and Requests

1. 核心技术栈：

.NET 版本： .NET 8.0 或更高（LTS 版本）
Avalonia 版本： 11.x（最新稳定版），锁定到次要版本（如 11.0.x）
ReactiveUI 版本： 最新稳定版（19.x 或更高）
Semi.Avalonia 版本： 最新稳定版（需要在项目初期快速评估其可用性）

2. AOT 支持策略（软约束）：

架构设计应考虑未来 AOT 支持，但 MVP 阶段允许使用反射
PropertyGrid 如果使用反射实现，应设计清晰的抽象层，便于后续迁移到 Source Generator
避免使用 Reflection.Emit 和动态类型（dynamic）
尽量使用编译时类型安全的 API

3. 国际化架构预留：

控件内置文本（如 PropertyGrid 的"名称"、"值"列头，UserGuide 的"下一步"按钮）应通过资源系统管理，而非硬编码
MVP 阶段可以使用单一语言（中文或英文），但代码结构应支持后续扩展为多语言
推荐方案：使用 Avalonia 的本地化机制（IResourceProvider）或自定义 LocalizationManager

4. 依赖管理原则：

最小化第三方依赖：除了 Avalonia、ReactiveUI、Semi.Avalonia 外，尽量不引入其他 NuGet 包
锁定主要依赖版本：Avalonia 和 ReactiveUI 的主版本号应固定，避免自动升级导致 Breaking Changes
Semi.Avalonia 的可选性：如果评估后发现 Semi.Avalonia 不可用或过于复杂，允许放弃使用，改为自定义样式系统（风险缓解措施）

5. 开发工具和环境：

IDE： Visual Studio 2022 或 Rider
版本控制： Git，托管在本地或私有仓库
持续集成（可选）： MVP 阶段不强制要求 CI/CD，手动构建和测试即可
代码格式化： 使用 .editorconfig 统一代码风格

6. 性能优化原则：

过早优化是万恶之源：MVP 阶段优先功能完整性，性能问题在出现时再优化
已知的性能需求：PropertyGrid 对 50 个属性的生成时间 < 200ms，主题切换 < 100ms（见 NFR）
虚拟化和懒加载：如果 PropertyGrid 需要支持数百个属性，考虑使用 VirtualizingStackPanel（Post-MVP）

7. 文档和注释规范：

所有公开 API（public class、public method）必须有 XML 文档注释
复杂的业务逻辑应有内联注释解释设计意图
README 应包括：快速开始、控件列表、使用示例、常见问题

8. 颜色系统和字体配置：

苹果颜色系统的具体实现细节（颜色值、命名规范）将在架构和开发阶段由 UX Expert 确定，PRD 只明确方向
字体配置的具体 fallback 策略将在实现时补充，PRD 只定义目标字体族

Epic List

Epic 1: Foundation & Theme Infrastructure

建立项目基础设施（项目结构、依赖配置、CI 准备），实现基于苹果颜色系统的主题框架，支持浅色和深色主题的运行时切换，交付可验证主题切换的示例应用

Epic 2: PropertyGrid - Auto-Generated Configuration UI

实现 PropertyGrid 控件的核心功能，支持 6 种基础属性类型的自动 UI 生成、属性分组、只读属性和基础验证，交付可在上位机和 AI 应用中使用的配置界面解决方案

Epic 3: UserGuide - Onboarding & User Assistance

实现 UserGuide 控件系列，包括步骤式引导流程、增强 Tooltip 和 Overlay 遮罩，交付完整的新手引导和应用内帮助系统

Epic 1 Details: Foundation & Theme Infrastructure

Epic Goal

建立 Penguin.AvaloniaUI 控件库项目的完整基础设施，实现基于苹果颜色系统的主题框架。该 Epic 交付一个可运行的示例应用，演示浅色和暗色主题的流畅切换，为后续控件开发提供样式和颜色基础。通过该 Epic，验证技术栈选择（Avalonia、ReactiveUI、Semi.Avalonia）的可行性。

Story 1.1: 项目基础设施搭建并初始化示例应用

As a 控件库开发者， I want 建立完整的项目结构和依赖配置，并创建一个可运行的示例应用， so that 我可以在稳定的基础设施上开始控件开发，并有一个测试载体来验证功能。

Acceptance Criteria

创建 Monorepo 目录结构，包含以下项目：
- src/Penguin.AvaloniaUI/（核心控件库，.NET 8 类库）
- src/Example/（示例应用，Avalonia 桌面应用）
- src/Penguin.AvaloniaUI.Tests/（单元测试项目，xUnit）
配置 Penguin.AvaloniaUI 项目的核心依赖：
- Avalonia 11.x（最新稳定版）
- Avalonia.ReactiveUI
- Semi.Avalonia（如果评估后可用）
配置 Example 项目引用 Penguin.AvaloniaUI 项目
Example 应用能够成功启动，显示一个基础窗口，包含：
- 标题："Penguin.AvaloniaUI Demo"
- 一个 TextBlock 显示 "Hello World"
- 窗口大小：800x600
项目能够在 Windows 平台成功编译和运行
创建基础的 .gitignore 和 README.md
快速评估 Semi.Avalonia 的可用性：
- 如果 Semi.Avalonia 可用，在 Example 中应用其基础样式
- 如果不可用或过于复杂，记录决策并准备自定义样式系统

Story 1.2: 实现浅色主题和三层颜色架构

As a 控件库开发者， I want 实现基于苹果颜色系统的三层架构颜色系统（Primitives → Semantic → Component），并完成浅色主题， so that 后续开发的控件可以使用一致的颜色语义，且示例应用有专业的视觉呈现。

Acceptance Criteria

在 Penguin.AvaloniaUI/Themes/Colors/ 下实现三层颜色架构：
- Primitives.axaml（原子层）：定义 Apple 官方系统颜色的 Color 资源
- Light.axaml（语义层）：定义浅色主题的语义化颜色（Background., Foreground., Border., Accent., State., Surface.）
- Theme.axaml（主题入口）：统一的主题加载入口，默认加载 Light.axaml
实现完整的语义化颜色体系（6 大类）：
- Background：Base, Layer1, Layer2, Layer3, Control, Overlay
- Foreground：Primary, Secondary, Tertiary, Disabled, OnAccent, Link
- Border：Default, Strong, Subtle, Accent
- Accent：Default, Hover, Pressed, Disabled
- State：Success, Warning, Error, Danger, Info
- Surface：Default, Elevated, Secondary
将浅色主题应用到 Example 应用：
- 在 App.axaml 中引用 Theme.axaml
- 示例窗口的背景色使用 {DynamicResource Background.Base}
- TextBlock 的文本色使用 {DynamicResource Foreground.Primary}
在 Example 中添加一个演示页面，展示所有语义化颜色：
- 显示每个颜色的名称和色块（使用 Border 或 Rectangle）
- 色块大小：至少 100x50 像素
- 按类别分组展示 6 大类颜色
浅色主题下，示例应用视觉呈现专业、清晰，无明显的配色问题
在 README.md 中添加三层颜色架构的说明，突出其架构优势

Story 1.3: 实现暗色主题

As a 控件库开发者， I want 基于颜色系统创建暗色主题， so that 控件库可以支持暗色模式，满足长时间使用场景的需求。

Acceptance Criteria

在 Penguin.AvaloniaUI/Themes/ 下创建 DarkTheme.axaml（暗色主题资源字典）：
- 为每个语义化颜色定义暗色主题的具体色值
- 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）
- 暗色主题的背景色应较深（避免纯黑 #000000，推荐深灰色系）
暗色主题的颜色定义应与浅色主题在语义上对应：
- Primary 在两种主题下都表示"强调色"，但色值可以不同
- Background 在浅色主题下是浅色，在暗色主题下是深色
修改 Example 应用，支持手动切换到暗色主题：
- 在 App.axaml 中暂时保留浅色主题为默认
- 提供注释说明如何切换到暗色主题（修改 App.axaml 中的资源引用）
在暗色主题下，颜色演示页面能够正确显示所有暗色主题的颜色
暗色主题视觉呈现舒适，无过度刺眼或过暗的问题
两种主题下的颜色演示页面应使用相同的 XAML 代码（通过语义化颜色资源绑定）

Story 1.4: 实现运行时主题切换

As a 示例应用的用户， I want 通过 UI 按钮动态切换浅色和暗色主题， so that 我可以快速验证控件库在不同主题下的视觉效果，无需修改代码和重启应用。

Acceptance Criteria

在 Penguin.AvaloniaUI/Themes/ 下创建 ThemeManager.cs 类：
- 提供 ApplyTheme(ThemeType theme) 方法，支持动态加载主题资源
- ThemeType 枚举包含 Light 和 Dark
- 主题切换通过替换 Application.Current.Resources 中的资源字典实现
提供一个 ReactiveUI Command：SwitchThemeCommand
- 接受 ThemeType 参数
- 调用 ThemeManager.ApplyTheme() 切换主题
在 Example 应用的主窗口添加主题切换按钮：
- 两个按钮："浅色主题" 和 "暗色主题"（或一个 ToggleButton）
- 按钮绑定到 SwitchThemeCommand
- 按钮样式使用当前主题的颜色系统
主题切换应流畅无闪烁：
- 切换时间 < 100ms（符合 NFR4）
- 所有使用语义化颜色的控件应自动更新外观
主题切换后，颜色演示页面应立即反映新主题的颜色
主题状态应持久化（可选，MVP 可以每次启动默认浅色主题）
在 Example 中添加一个简单的测试页面，包含多种控件（Button、TextBox、CheckBox），验证主题切换对不同控件的影响

Epic 2 Details: PropertyGrid - Auto-Generated Configuration UI

Epic Goal

实现 PropertyGrid 控件，这是控件库的核心价值所在。该控件能够从数据模型自动生成属性编辑 UI，支持 string, int, double, bool, enum, DateTime 六种基础类型，以及属性分组、只读属性等功能。Epic 完成后，上位机和 AI 应用开发者可以快速构建配置界面，无需手写大量 XAML。该 Epic 在开发过程中会产出必要的布局控件（如 TwoColumnLayout）和工具类。

Story 2.1: 实现 2xN Layout 布局控件

As a 控件库开发者， I want 创建一个专用的 2xN Layout 布局控件（左侧标签，右侧编辑器）， so that PropertyGrid 可以使用统一的布局来呈现属性列表，且这个布局控件可以复用到其他需要"标签-值"配对的场景。

Acceptance Criteria

在 Penguin.AvaloniaUI/Layouts/ 下创建 TwoColumnLayout.cs 控件类：
- 继承自 Panel 或使用 Grid 作为基础
- 支持添加多行，每行包含左侧标签（Label）和右侧内容（Content）
提供简单的 API 来添加行：
- 可以通过 Items 集合添加行
- 每个 Item 包含 Label（string）和 Content（Control）
布局行为：
- 左列（标签列）宽度固定或自适应最长标签的宽度
- 右列（内容列）占据剩余空间
- 行与行之间有合适的垂直间距（如 8px）
- 标签垂直对齐到内容控件的中心或顶部
响应主题系统：
- 标签文本颜色使用 TextSecondary
- 背景色透明或使用 Surface
在 Example 中创建测试页面，演示 TwoColumnLayout 的使用：
- 至少 5 行测试数据
- 包含不同类型的右侧内容（TextBox, CheckBox, ComboBox）
布局在窗口缩放时应正确响应，不出现重叠或错位

Story 2.2: 实现基础属性编辑器控件

As a 控件库开发者， I want 为 PropertyGrid 支持的 6 种属性类型创建或选择合适的编辑器控件， so that PropertyGrid 可以根据属性类型自动选择正确的编辑器。

Acceptance Criteria

为以下属性类型选择或创建编辑器控件：
- string: 使用 Avalonia 的 TextBox
- int/double: 使用 Avalonia 的 NumericUpDown（如果 Semi 或 Avalonia 提供）或自定义数字输入框
- bool: 使用 Avalonia 的 CheckBox
- enum: 使用 Avalonia 的 ComboBox，Items 为枚举值列表
- DateTime: 使用 Avalonia 的 DatePicker 和 TimePicker（或组合控件）
所有编辑器控件应响应主题系统，使用语义化颜色
编辑器控件应支持基础的数据绑定：
- 双向绑定（TwoWay Binding）
- 支持 INotifyPropertyChanged 机制
在 Example 中创建测试页面，演示所有 6 种编辑器：
- 每种编辑器独立展示
- 显示当前绑定的值（使用 TextBlock）
- 修改编辑器后，绑定的值应自动更新
编辑器控件应具备基础的验证提示能力：
- 依赖 Avalonia 的内置验证机制（如 DataValidationErrors）
- 验证失败时显示红色边框或错误图标

Story 2.3: 实现 PropertyGrid 核心逻辑和数据模型

As a 控件库开发者， I want 定义 PropertyGrid 的数据模型和核心逻辑，支持从对象反射属性信息， so that PropertyGrid 可以自动生成属性列表，为后续的 UI 呈现做好准备。

Acceptance Criteria

在 Penguin.AvaloniaUI/Controls/PropertyGrid/ 下创建以下类：
- PropertyGrid.cs: PropertyGrid 主控件类
- PropertyItem.cs: 表示单个属性的数据模型，包含：
  - Name（属性名称）
  - Value（属性值）
  - Type（属性类型）
  - IsReadOnly（是否只读）
  - Category（分组类别，可选）
  - Description（描述，可选）
PropertyGrid 提供 SelectedObject 属性（依赖属性）：
- 接受任意对象
- 当 SelectedObject 变化时，自动通过反射解析对象的属性
反射逻辑：
- 获取对象的所有 public 属性
- 过滤掉不应显示的属性（如索引器、只写属性）
- 支持通过 Attribute 控制属性的显示（可选，如 [Browsable(false)]）
将反射得到的属性转换为 PropertyItem 集合：
- 存储在 PropertyGrid 的内部集合中
- 支持属性变化通知（使用 ReactiveUI 或 INotifyPropertyChanged）
创建单元测试，验证反射逻辑：
- 测试包含 6 种基础类型的测试对象
- 验证属性数量、名称、类型正确解析
- 验证只读属性标记正确识别
在 Example 中创建测试页面，验证数据模型：
- 定义一个包含 6 种类型属性的测试类
- 将测试对象赋值给 PropertyGrid.SelectedObject
- 使用调试输出或 ListBox 显示解析出的 PropertyItem 列表（暂时不渲染为编辑器）

Story 2.4: 实现 PropertyGrid UI 呈现和属性编辑

As a PropertyGrid 的用户（开发者）， I want PropertyGrid 能够自动将属性列表渲染为可编辑的 UI， so that 我可以直接使用 PropertyGrid 控件，无需手动编写属性编辑界面。

Acceptance Criteria

PropertyGrid 使用 TwoColumnLayout 呈现属性列表：
- 左列显示属性名称（PropertyItem.Name）
- 右列根据属性类型显示对应的编辑器控件
属性类型到编辑器的映射逻辑：
- string → TextBox
- int/double → NumericUpDown
- bool → CheckBox
- enum → ComboBox（自动填充枚举值）
- DateTime → DatePicker/TimePicker
编辑器控件与属性值双向绑定：
- 修改编辑器时，PropertyItem.Value 自动更新
- PropertyItem.Value 变化时，编辑器自动刷新（如果 SelectedObject 外部修改）
只读属性的处理：
- 如果 PropertyItem.IsReadOnly = true，编辑器应禁用（IsEnabled = false）或显示为只读文本
在 Example 中创建完整的 PropertyGrid 演示页面：
- 定义一个包含所有 6 种类型的配置类（如 DemoSettings）
- 使用 PropertyGrid 绑定到 DemoSettings 实例
- 在页面底部显示当前配置对象的 JSON 或字符串表示，验证属性编辑生效
PropertyGrid 应响应主题切换，所有编辑器控件使用主题颜色
PropertyGrid 的默认宽度应至少 400px，高度自适应内容（或支持滚动）

Story 2.5: 实现属性分组功能

As a PropertyGrid 的用户（开发者）， I want PropertyGrid 支持将属性按类别分组显示， so that 当属性数量较多时，配置界面更清晰易读。

Acceptance Criteria

PropertyItem 支持 Category 属性（字符串）：
- 如果未指定 Category，默认分组为 "General" 或不分组
支持通过 Attribute 在数据模型上标记分组：
- 例如使用 [Category("Network")] 标记属性
- 反射逻辑自动读取 Category Attribute
PropertyGrid 按 Category 对 PropertyItem 进行分组：
- 相同 Category 的属性显示在一起
- 分组之间有视觉分隔（如分隔线或分组标题）
分组标题的呈现：
- 使用稍大的字体或加粗显示分组名称
- 分组标题使用 TextPrimary 颜色
- 分组标题上方有一定的间距（如 16px）
支持可选的分组折叠功能（可选，MVP 可以暂时不实现折叠）：
- 如果时间允许，分组可以展开/折叠
- 默认所有分组展开
在 Example 中扩展演示页面：
- DemoSettings 类的属性使用 [Category] 标记，分为至少 2 个分组（如 "General"、"Advanced"）
- PropertyGrid 正确显示分组
- 验证分组标题和属性的视觉层次清晰

Story 2.6: PropertyGrid 集成测试和优化

As a 控件库开发者， I want 对 PropertyGrid 进行全面测试和性能优化， so that 确保 PropertyGrid 在真实场景下稳定可用，并满足性能要求（50 属性 < 200ms）。

Acceptance Criteria

创建综合测试类，包含 50 个属性，覆盖所有支持的类型和分组
在 Example 中使用该测试类验证 PropertyGrid：
- PropertyGrid 正确渲染所有 50 个属性
- UI 生成时间 < 200ms（符合 NFR5）
- 所有编辑器可正常交互，值绑定正确
测试边缘情况：
- SelectedObject 为 null 时，PropertyGrid 显示空状态或提示信息
- 对象属性在运行时变化时，PropertyGrid 能够正确响应（如果支持动态刷新）
- 只读属性不能编辑
主题切换测试：
- 在浅色和暗色主题下，PropertyGrid 的视觉呈现正确
- 主题切换时，PropertyGrid 无闪烁或错位
性能优化（如果需要）：
- 如果初始加载超过 200ms，使用虚拟化或延迟加载优化
- 如果属性数量超过 100，考虑使用 VirtualizingStackPanel
修复 Example 测试中发现的所有 Bug
在 README 中添加 PropertyGrid 的使用文档：
- 基础用法示例（XAML 和代码）
- 支持的属性类型列表
- 如何使用 Category Attribute
- 已知限制（如暂不支持嵌套对象）

Epic 3 Details: UserGuide - Onboarding & User Assistance

Epic Goal

实现 UserGuide 控件系列，为 AI 桌面应用提供完整的新手引导和应用内帮助系统。该 Epic 交付三个核心控件：Overlay（半透明遮罩）、增强 Tooltip（支持基础富文本）、UserGuide 引导流程控件（步骤式引导）。完成后，开发者可以快速为应用添加专业的用户引导功能，提升用户体验。

Story 3.1: 实现 Overlay 遮罩控件

As a 控件库开发者， I want 创建一个 Overlay 遮罩控件，能够在当前窗口上方显示半透明遮罩层， so that UserGuide 可以使用它来聚焦引导目标，同时遮挡其他区域，引导用户注意力。

Acceptance Criteria

在 Penguin.AvaloniaUI/Controls/UserGuide/ 下创建 Overlay.cs 控件类：
- 继承自 ContentControl 或 Panel
- 能够覆盖整个父容器（通常是 Window）
Overlay 支持以下属性：
- IsVisible: 控制遮罩显示/隐藏
- BackgroundOpacity: 遮罩的不透明度（默认 0.5，范围 0-1）
- BackgroundColor: 遮罩颜色（默认黑色）
- TargetControl: 可选的目标控件，遮罩在该控件区域挖空（透明）以突出显示
遮罩的视觉效果：
- 默认显示为半透明黑色覆盖层
- 如果指定了 TargetControl，该控件区域应保持清晰可见（通过 Clip 或透明矩形实现）
Overlay 应响应主题系统：
- 浅色主题下使用半透明黑色（默认）
- 暗色主题下使用半透明白色或深灰色（避免过暗）
在 Example 中创建测试页面：
- 页面包含几个按钮或控件
- 添加一个"显示遮罩"按钮，点击后显示 Overlay
- 测试不指定 TargetControl（全屏遮罩）和指定 TargetControl（挖空特定控件）两种模式
遮罩显示时，应阻止用户点击被遮罩区域的控件（除了 TargetControl）
Overlay 支持动画效果（可选）：
- 显示和隐藏时有淡入淡出动画（200ms）

As a 应用开发者， I want 使用增强的 Tooltip 控件，支持基础富文本格式（粗体、斜体、换行）， so that 我可以在引导提示中强调关键信息，提升提示的可读性和吸引力。

Acceptance Criteria

在 Penguin.AvaloniaUI/Controls/UserGuide/ 下创建 RichTooltip.cs 控件类：
- 继承或扩展 Avalonia 的 ToolTip
- 支持 Content 为 TextBlock 或自定义内容
支持基础富文本格式：
- 粗体: 使用 <Bold> 标签或支持 Markdown 的 **text** 语法（选其一）
- 斜体: 使用 <Italic> 标签或 Markdown 的 *text* 语法
- 换行: 使用 \n 或自动换行
- 不支持链接、图片等复杂格式（符合 YAGNI 原则）
RichTooltip 应响应主题系统：
- 背景色使用 Surface 或 Background
- 文本颜色使用 TextPrimary
- 边框颜色使用 Primary 或 Secondary
提供简单的 API 设置内容：
- 接受纯文本（自动解析格式标记）
- 或接受 TextBlock（手动设置格式）
在 Example 中创建测试页面：
- 几个按钮，鼠标悬停时显示 RichTooltip
- 测试粗体、斜体、换行的组合效果
- 示例文本："注意: 这是一个重要的功能提示。\n请仔细阅读。"
RichTooltip 的显示位置应智能调整：
- 默认显示在目标控件下方
- 如果空间不足，自动调整到上方或左右侧
RichTooltip 的最大宽度应限制（如 300px），超出自动换行

Story 3.3: 实现 UserGuide 引导流程数据模型和步骤管理

As a 控件库开发者， I want 定义 UserGuide 的数据模型和步骤管理逻辑， so that 开发者可以配置多步引导流程，UserGuide 控件可以管理步骤的流转。

Acceptance Criteria

在 Penguin.AvaloniaUI/Controls/UserGuide/ 下创建以下类：
- UserGuide.cs: UserGuide 主控件类
- GuideStep.cs: 表示单个引导步骤的数据模型，包含：
  - TargetControl: 引导目标控件（Control 类型）
  - Title: 步骤标题（string）
  - Content: 步骤内容/提示文本（string，支持基础富文本）
  - Position: 提示框相对于目标控件的位置（枚举：Bottom、Top、Left、Right）
  - Order: 步骤顺序（int）
UserGuide 提供 Steps 属性（集合）：
- 接受 GuideStep 列表
- 支持在 XAML 或代码中配置
UserGuide 提供步骤管理功能：
- CurrentStepIndex: 当前步骤索引（int）
- NextStepCommand: 前进到下一步
- PreviousStepCommand: 返回上一步
- SkipCommand: 跳过引导
- FinishCommand: 完成引导
步骤流转逻辑：
- 初始状态：CurrentStepIndex = 0（第一步）
- NextStep: CurrentStepIndex + 1，如果是最后一步则触发 Finish
- PreviousStep: CurrentStepIndex - 1，如果是第一步则禁用
- Skip/Finish: 隐藏 UserGuide，触发完成事件
创建单元测试，验证步骤管理逻辑：
- 测试 NextStep、PreviousStep 的边界条件
- 测试步骤按 Order 排序
在 Example 中创建测试页面：
- 定义包含 3-5 个 GuideStep 的引导流程
- 使用调试输出或 TextBlock 显示当前步骤信息（暂时不渲染 UI）
- 提供按钮手动触发 NextStep、PreviousStep，验证逻辑正确

Story 3.4: 实现 UserGuide UI 呈现和引导交互

As a 应用用户， I want 看到清晰的引导提示框，并通过"上一步"、"下一步"、"跳过"按钮控制引导流程， so that 我可以快速了解应用的核心功能，而不会感到困惑。

Acceptance Criteria

UserGuide 开始引导时：
- 显示 Overlay 遮罩，遮挡除当前目标控件外的其他区域
- 在目标控件附近显示引导提示框（根据 GuideStep.Position）
引导提示框的内容：
- 显示步骤标题（GuideStep.Title），使用稍大的字体或加粗
- 显示步骤内容（GuideStep.Content），支持基础富文本（调用 RichTooltip 逻辑）
- 显示步骤进度（如 "2/5"）
引导提示框的按钮：
- "上一步"按钮（如果不是第一步）
- "下一步"按钮（如果不是最后一步）或"完成"按钮（如果是最后一步）
- "跳过"按钮（所有步骤都显示）
- 按钮绑定到 UserGuide 的 Command
引导提示框应响应主题系统：
- 背景色使用 Surface 并带有阴影效果
- 按钮使用 Primary 颜色（"下一步"/"完成"）和 Secondary 颜色（"上一步"/"跳过"）
步骤切换动画（可选）：
- 切换步骤时，提示框有淡入淡出或平移动画（200ms）
在 Example 中创建完整的 UserGuide 演示：
- 定义一个包含 5 个步骤的引导流程
- 目标控件为页面上的不同按钮或区域
- 测试步骤：用户可以顺畅地前进、后退、跳过、完成引导
UserGuide 完成后，应触发事件或回调：
- 开发者可以监听完成事件，执行后续逻辑（如标记"引导已完成"）

Story 3.5: UserGuide 边缘情况处理和集成测试

As a 控件库开发者， I want 处理 UserGuide 的边缘情况并进行全面测试， so that 确保 UserGuide 在各种场景下稳定可用，用户体验流畅。

Acceptance Criteria

处理边缘情况：
- 目标控件不可见或已销毁: UserGuide 应自动跳过该步骤或显示错误提示
- 窗口缩放: 引导提示框应随窗口调整位置，不出现错位
- 多窗口场景: UserGuide 应只在启动它的窗口内生效
- 用户点击 Overlay 遮罩: 默认不响应（不关闭引导），或提供配置选项
主题切换测试：
- 在引导进行中切换主题，UserGuide 应正确响应，无视觉错误
性能测试：
- 引导流程包含 10 个步骤时，步骤切换应流畅（< 100ms）
- Overlay 和提示框的动画不应卡顿
用户体验测试：
- 引导流程的视觉呈现清晰，提示框不会遮挡目标控件
- 按钮的位置和文本易于理解
- 进度指示清晰（如 "3/5"）
在 Example 中创建综合测试页面：
- 模拟真实应用的引导场景（如"首次使用教程"）
- 包含至少 5 个步骤，覆盖不同位置（Top、Bottom、Left、Right）
- 测试跳过、返回、完成等所有操作
修复测试中发现的所有 Bug
在 README 中添加 UserGuide 的使用文档：
- 基础用法示例（XAML 和代码）
- 如何定义 GuideStep
- 如何监听完成事件
- 最佳实践建议（如引导步骤不宜过多、提示文本应简洁）

Story 3.6: MVP 整体集成测试和文档完善

As a 控件库的用户（开发者）， I want 在 Example 应用中看到所有 MVP 功能的完整演示，并有清晰的文档指导， so that 我可以快速学习如何使用控件库，并在自己的项目中集成。

Acceptance Criteria

在 Example 中创建"综合 Demo"页面：
- 集成 PropertyGrid、UserGuide、主题切换功能
- 模拟一个真实的应用场景（如"AI 模型配置工具"）
- 页面包含：
  - 主题切换按钮
  - PropertyGrid 显示配置对象
  - "开始引导"按钮，触发 UserGuide
  - UserGuide 引导用户了解主题切换、PropertyGrid 使用等功能
验证所有 MVP Success Criteria（来自 Brief）：
- ✅ 颜色系统和主题框架可用：至少 2 种主题，运行时流畅切换
- ✅ 国际化框架架构预留：代码结构支持后续扩展
- ✅ PropertyGrid 可在测试项目中使用：支持常用类型，基础数据绑定
- ✅ UserGuide 可在测试项目中使用：引导流程完整，Tooltip 增强功能可用
- ✅ 架构支持未来 AOT：MVP 阶段允许反射
- ✅ 产出 5+ 个可复用的基础控件/工具：TwoColumnLayout、Overlay、RichTooltip、ThemeManager 等
测试跨功能集成：
- 在 PropertyGrid 编辑时触发主题切换，验证无冲突
- 在 UserGuide 进行中修改 PropertyGrid，验证无异常
性能基准测试：
- PropertyGrid 50 属性生成 < 200ms（NFR5）
- 主题切换 < 100ms（NFR4）
- UI 渲染 60fps（NFR3）
完善 README.md：
- 项目概述和目标
- 快速开始指南（如何运行 Example）
- 控件列表和功能概述
- 核心控件的使用示例（PropertyGrid、UserGuide）
- 已知限制和后续计划（Post-MVP）
创建 CHANGELOG.md：
- 记录 MVP v1.0 的功能清单
- 标记已完成的 Epic 和 Story
项目代码质量检查：
- 所有公开 API 有 XML 文档注释
- 代码符合 C# 编码规范
- 删除未使用的代码和注释
- 确保 Git 提交记录清晰

Checklist Results Report

Executive Summary

Overall PRD Completeness: 88% MVP Scope Appropriateness: Just Right Readiness for Architecture Phase: Ready

Most Critical Gaps:

用户流程图缺失（可在架构阶段补充，MEDIUM 优先级）
数据实体未正式定义（PropertyItem、GuideStep 在 Stories 中有描述，HIGH 优先级建议补充专门章节）
性能测量工具未明确（架构阶段确定，MEDIUM 优先级）

Category Statuses

Category	Status	Critical Issues
1. Problem Definition & Context	PASS	无
2. MVP Scope Definition	PASS	无
3. User Experience Requirements	PARTIAL	缺少用户流程图（MEDIUM）
4. Functional Requirements	PASS	无
5. Non-Functional Requirements	PASS	无
6. Epic & Story Structure	PASS	无
7. Technical Guidance	PASS	无
8. Cross-Functional Requirements	PARTIAL	数据实体未正式定义（HIGH）
9. Clarity & Communication	PASS	无

Overall Status: 7/9 PASS, 2/9 PARTIAL

Key Findings

Strengths:

Epic 和 Story 结构完整，16 个 Stories 都有详细的 Acceptance Criteria
技术栈和架构方向明确，风险已识别并有缓解措施
MVP 范围经过 YAGNI 和多方利益相关者验证，合理且可行
需求经过深度分析（YAGNI + Stakeholder Round Table），削减了约 1 周工作量

Areas for Improvement:

HIGH 优先级： 建议在 Requirements 部分添加"Data Models"章节，正式定义 PropertyItem、GuideStep 等核心数据结构
MEDIUM 优先级： 在架构阶段补充 2-3 个关键用户流程图（可与 UX Expert 协作）
MEDIUM 优先级： 明确性能测量工具和方法（如何测量 60fps、100ms、200ms）

Recommendations

For Architecture Phase:

优先完成 Semi.Avalonia 可用性评估（Story 1.1 的前置任务）
与 UX Expert 协作定义苹果颜色系统的具体色值
确定国际化方案（Avalonia 内置 vs 自定义）
选择性能测量工具

Timeline Realism:

4 周完成 3 个 Epic、16 个 Stories：可行
Epic 1: 1 周，Epic 2: 1.5-2 周，Epic 3: 1-1.5 周
符合 1-2 人业余时间开发（每周 10-20 小时）

Next Steps

UX Expert Prompt

你好！我是 Penguin.AvaloniaUI 控件库的产品经理。我们刚刚完成了 MVP 的 PRD，现在需要你的 UX 专业知识来完善用户体验设计。

**项目背景：**
- 目标：为上位机和 AI 桌面应用开发者提供业务场景控件库（PropertyGrid、UserGuide 等）
- 技术栈：Avalonia UI、.NET 8+、ReactiveUI、Semi Design 样式系统
- MVP 时间线：1 个月（4 周）
- MVP 范围：主题框架 + PropertyGrid + UserGuide

**你的任务：**
1. **审查 UI Design Goals 部分**（本文档中的"User Interface Design Goals"）
   - 验证设计原则是否符合上位机和 AI 应用的用户习惯
   - 确认"信息密度优先"和"暗色模式友好"的设计方向

2. **补充关键用户流程图**（可选，MEDIUM 优先级）
   - "开发者配置 PropertyGrid"的完整流程
   - "用户使用 UserGuide 引导"的完整流程
   - "主题切换"的触发路径

3. **设计苹果颜色系统的具体色值**
   - 为浅色和暗色主题定义 Primary, Secondary, Success, Warning, Error, Background, Surface 等颜色的具体 HEX 值
   - 确保色彩对比度符合 4.5:1 要求
   - 参考：Apple Human Interface Guidelines (https://developer.apple.com/design/human-interface-guidelines/color)

4. **评估 Semi.Avalonia 的可用性**（与 Architect 协作）
   - 检查 Semi Design 样式是否满足"紧凑布局"需求
   - 确认 Semi 的颜色系统能否与苹果颜色系统集成
   - 如果不可用，提出 Plan B（自定义样式系统）

**交付物：**
- 苹果颜色系统色值规范文档（Markdown 或 Figma）
- （可选）2-3 个关键用户流程图
- Semi.Avalonia 可用性评估报告

**时间预估：** 2-3 天

请先阅读 docs/brief.md 和本 PRD，了解项目的完整背景，然后开始你的工作。如有疑问，随时联系我！

Architect Prompt

你好！我是 Penguin.AvaloniaUI 控件库的产品经理。我们刚刚完成了 MVP 的 PRD，现在需要你设计技术架构，为开发阶段提供清晰的实现蓝图。

**项目背景：**
- 目标：为上位机和 AI 桌面应用开发者提供业务场景控件库（PropertyGrid、UserGuide 等）
- 技术栈：Avalonia UI、.NET 8+、ReactiveUI、Semi Design 样式系统
- MVP 时间线：1 个月（4 周）
- MVP 范围：主题框架 + PropertyGrid + UserGuide

**你的任务：**
1. **审查 Technical Assumptions 部分**（本文档中的"Technical Assumptions"）
   - 确认技术栈选择的合理性（Monorepo、单体库、ReactiveUI）
   - 验证依赖管理策略（Semi.Avalonia、AOT 支持策略）

2. **设计核心架构**
   - 项目结构和命名空间组织（Controls、Layouts、Themes、Utils）
   - 主题系统的技术实现方案（ResourceDictionary 动态加载）
   - PropertyGrid 的反射实现方案（平衡性能和可维护性）
   - UserGuide 的 Overlay 和步骤管理架构

3. **明确技术决策**
   - **国际化方案选择**：Avalonia 内置 IResourceProvider vs 自定义 LocalizationManager
   - **PropertyGrid 反射策略**：直接反射 vs Fluent API 配置
   - **Semi.Avalonia 集成方案**：完全依赖 vs 部分使用 vs 自定义样式
   - **性能测量工具**：如何测量 60fps、100ms、200ms 等性能指标

4. **识别技术风险并提出缓解措施**
   - Semi.Avalonia 可用性风险（与 UX Expert 协作评估）
   - PropertyGrid 反射性能风险（50 属性 < 200ms）
   - ReactiveUI 学习曲线风险

5. **设计架构文档结构**
   - 高层架构图（项目结构、依赖关系）
   - 核心控件的类图（PropertyGrid、UserGuide）
   - 主题系统的序列图（主题切换流程）
   - 关键数据模型定义（PropertyItem、GuideStep）

**关键约束：**
- MVP 阶段允许使用反射（AOT 支持是"架构考虑"，不是硬性要求）
- 如果 Semi.Avalonia 不可用，允许放弃并自定义样式系统
- 测试策略：单元测试 + 手动测试（不需要 UI 自动化测试）

**交付物：**
- 架构设计文档（docs/architecture.md）
- 技术决策记录（ADR）
- （可选）核心控件的技术规格书

**时间预估：** 3-5 天

请先阅读 docs/brief.md 和本 PRD，了解项目的完整背景和产品需求。优先完成 Semi.Avalonia 的评估（Story 1.1 的前置任务），因为这会影响 Epic 1 的实现方案。如有疑问，随时联系我！

End of PRD

50 KiB Raw Blame History Unescape Escape

Penguin.AvaloniaUI Product Requirements Document (PRD)

Goals and Background Context

Goals

Background Context

Change Log

Requirements

Functional Requirements

Non-Functional Requirements

User Interface Design Goals

Overall UX Vision

Key Interaction Paradigms

Core Screens and Views

Accessibility

Branding

Target Device and Platforms

Technical Assumptions

Repository Structure: Monorepo

Service Architecture

Testing Requirements

Additional Technical Assumptions and Requests

Epic List

Epic 1: Foundation & Theme Infrastructure

Epic 2: PropertyGrid - Auto-Generated Configuration UI

Epic 3: UserGuide - Onboarding & User Assistance

Epic 1 Details: Foundation & Theme Infrastructure

Epic Goal

Story 1.1: 项目基础设施搭建并初始化示例应用

Acceptance Criteria

Story 1.2: 实现浅色主题和三层颜色架构

Acceptance Criteria

Story 1.3: 实现暗色主题

Acceptance Criteria

Story 1.4: 实现运行时主题切换

Acceptance Criteria

Epic 2 Details: PropertyGrid - Auto-Generated Configuration UI

Epic Goal

Story 2.1: 实现 2xN Layout 布局控件

Acceptance Criteria

Story 2.2: 实现基础属性编辑器控件

Acceptance Criteria

Story 2.3: 实现 PropertyGrid 核心逻辑和数据模型

Acceptance Criteria

Story 2.4: 实现 PropertyGrid UI 呈现和属性编辑

Acceptance Criteria

Story 2.5: 实现属性分组功能

Acceptance Criteria

Story 2.6: PropertyGrid 集成测试和优化

Acceptance Criteria

Epic 3 Details: UserGuide - Onboarding & User Assistance

Epic Goal

Story 3.1: 实现 Overlay 遮罩控件

Acceptance Criteria

Story 3.2: 实现增强 Tooltip 控件（支持基础富文本）

Acceptance Criteria

Story 3.3: 实现 UserGuide 引导流程数据模型和步骤管理

Acceptance Criteria

Story 3.4: 实现 UserGuide UI 呈现和引导交互

Acceptance Criteria

Story 3.5: UserGuide 边缘情况处理和集成测试

Acceptance Criteria

Story 3.6: MVP 整体集成测试和文档完善

Acceptance Criteria

Checklist Results Report

Executive Summary

Category Statuses

Key Findings

Recommendations

Next Steps

UX Expert Prompt

Architect Prompt

50 KiB

Raw Blame History