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

---