ui/docs/prd/epic-1-details-foundation-theme-infrastructure.md

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

1. 创建 Monorepo 目录结构，包含以下项目：

   • src/Penguin.AvaloniaUI/（核心控件库，.NET 8 类库）
   • src/Example/（示例应用，Avalonia 桌面应用）
   • src/Penguin.AvaloniaUI.Tests/（单元测试项目，xUnit）

2. 配置 Penguin.AvaloniaUI 项目的核心依赖：

   • Avalonia 11.x（最新稳定版）
   • Avalonia.ReactiveUI
   • Semi.Avalonia（如果评估后可用）

3. 配置 Example 项目引用 Penguin.AvaloniaUI 项目

4. Example 应用能够成功启动，显示一个基础窗口，包含：

   • 标题："Penguin.AvaloniaUI Demo"
   • 一个 TextBlock 显示 "Hello World"
   • 窗口大小：800x600

5. 项目能够在 Windows 平台成功编译和运行

6. 创建基础的 .gitignore 和 README.md

7. 快速评估 Semi.Avalonia 的可用性：

   • 如果 Semi.Avalonia 可用，在 Example 中应用其基础样式
   • 如果不可用或过于复杂，记录决策并准备自定义样式系统

---

Story 1.2: 实现浅色主题和颜色系统

As a 控件库开发者， I want 定义基于苹果颜色系统的语义化颜色，并实现浅色主题， so that 后续开发的控件可以使用一致的颜色语义，且示例应用有专业的视觉呈现。

Acceptance Criteria

1. 在 Penguin.AvaloniaUI/Themes/ColorSystem/ 下创建颜色系统定义：

   • 定义语义化颜色资源（ResourceDictionary），包含至少以下颜色：
     • Primary（主色）
     • Secondary（次要色）
     • Success（成功）
     • Warning（警告）
     • Error（错误）
     • Background（背景）
     • Surface（表面）
     • TextPrimary（主要文本）
     • TextSecondary（次要文本）

2. 在 Penguin.AvaloniaUI/Themes/ 下创建 LightTheme.axaml（浅色主题资源字典）：

   • 为每个语义化颜色定义浅色主题的具体色值
   • 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）

3. 将浅色主题应用到 Example 应用：

   • 在 App.axaml 中引用 LightTheme.axaml
   • 示例窗口的背景色使用 Background 颜色
   • TextBlock 的文本色使用 TextPrimary 颜色

4. 在 Example 中添加一个演示页面，展示所有语义化颜色：

   • 显示每个颜色的名称和色块（使用 Border 或 Rectangle）
   • 色块大小：至少 100x50 像素

5. 浅色主题下，示例应用视觉呈现专业、清晰，无明显的配色问题

6. 在 README.md 中添加颜色系统的简要说明

---

Story 1.3: 实现暗色主题

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

Acceptance Criteria

1. 在 Penguin.AvaloniaUI/Themes/ 下创建 DarkTheme.axaml（暗色主题资源字典）：

   • 为每个语义化颜色定义暗色主题的具体色值
   • 确保颜色对比度足够（文本与背景对比度 ≥ 4.5:1）
   • 暗色主题的背景色应较深（避免纯黑 #000000，推荐深灰色系）

2. 暗色主题的颜色定义应与浅色主题在语义上对应：

   • Primary 在两种主题下都表示"强调色"，但色值可以不同
   • Background 在浅色主题下是浅色，在暗色主题下是深色

3. 修改 Example 应用，支持手动切换到暗色主题：

   • 在 App.axaml 中暂时保留浅色主题为默认
   • 提供注释说明如何切换到暗色主题（修改 App.axaml 中的资源引用）

4. 在暗色主题下，颜色演示页面能够正确显示所有暗色主题的颜色

5. 暗色主题视觉呈现舒适，无过度刺眼或过暗的问题

6. 两种主题下的颜色演示页面应使用相同的 XAML 代码（通过语义化颜色资源绑定）

---

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

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

Acceptance Criteria

1. 在 Penguin.AvaloniaUI/Themes/ 下创建 ThemeManager.cs 类：

   • 提供 ApplyTheme(ThemeType theme) 方法，支持动态加载主题资源
   • ThemeType 枚举包含 Light 和 Dark
   • 主题切换通过替换 Application.Current.Resources 中的资源字典实现

2. 提供一个 ReactiveUI Command：SwitchThemeCommand

   • 接受 ThemeType 参数
   • 调用 ThemeManager.ApplyTheme() 切换主题

3. 在 Example 应用的主窗口添加主题切换按钮：

   • 两个按钮："浅色主题" 和 "暗色主题"（或一个 ToggleButton）
   • 按钮绑定到 SwitchThemeCommand
   • 按钮样式使用当前主题的颜色系统

4. 主题切换应流畅无闪烁：

   • 切换时间 < 100ms（符合 NFR4）
   • 所有使用语义化颜色的控件应自动更新外观

5. 主题切换后，颜色演示页面应立即反映新主题的颜色

6. 主题状态应持久化（可选，MVP 可以每次启动默认浅色主题）

7. 在 Example 中添加一个简单的测试页面，包含多种控件（Button、TextBox、CheckBox），验证主题切换对不同控件的影响

---