docs: brainstorm,brief and prd

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

@@ -0,0 +1,145 @@
+# 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），验证主题切换对不同控件的影响
+
+---
+