feat: 实现三层颜色架构和浅色主题系统

基于 Apple Human Interface Guidelines 实现完整的三层颜色架构:
- Primitives Layer: 原子层,定义 Apple 系统颜色的 Color 资源
- Semantic Layer: 语义层,提供可读性强的颜色命名和用途分类
- Component Layer: 组件层(计划中),为控件专用颜色 Token

主要功能:
• 完整的 Apple 系统颜色定义(支持 Light/Dark 模式)
• 6 大类语义化颜色:Background, Foreground, Border, Accent, State, Surface
• 统一的主题入口 Theme.axaml
• 颜色系统演示页面,展示所有语义化颜色
• 更新 README.md 添加颜色系统详细说明

技术改进:
• 使用 {DynamicResource} 支持主题切换
• 遵循 Apple HIG 可访问性标准
• 建立清晰的命名规范:{类别}.{用途}.{状态}
• 为后续控件开发奠定坚实基础
This commit is contained in:
2025-10-17 00:13:15 +08:00
parent 9474f9e7f7
commit b0a7c2e3d5
11 changed files with 1766 additions and 6 deletions

699
docs/stories/1.2.story.md Normal file
View File

@@ -0,0 +1,699 @@
# Story 1.2: 实现浅色主题和颜色系统
## Status
**Completed - Architecture Refactored**
最新更新重新设计为三层颜色架构Primitives → Semantic → Component
---
## Story
**As a** 控件库开发者,
**I want** 定义基于苹果颜色系统的语义化颜色,并实现浅色主题,
**so that** 后续开发的控件可以使用一致的颜色语义,且示例应用有专业的视觉呈现。
---
## Acceptance Criteria
1.`Penguin.AvaloniaUI/Themes/ColorSystem/` 下创建颜色系统定义:
- 定义语义化颜色资源ResourceDictionary基于 Apple Human Interface Guidelines
- 必须包含以下核心语义化颜色(遵循苹果系统颜色命名):
- **System Colors系统颜色**:
- SystemBlue主色 / Primary
- SystemIndigo次要色 / Secondary
- SystemGreen成功 / Success
- SystemOrange警告 / Warning
- SystemRed错误 / Error
- SystemYellow、SystemPink、SystemPurple、SystemTeal、SystemGray可选扩展颜色
- **Text Colors文本颜色**:
- TextPrimary主要文本
- TextSecondary次要文本
- TextTertiary、TextQuaternary可选三级、四级文本
- **Background Colors背景颜色**:
- SystemBackground主背景 / Background
- SecondarySystemBackground次要背景 / Surface
- TertiarySystemBackground可选三级背景
- 所有颜色必须使用苹果官方颜色系统的标准色值
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` 中添加颜色系统的简要说明
---
## Tasks / Subtasks
- [x] **Task 1: 创建颜色系统目录结构** (AC: 1)
- [x] 创建 `src/Penguin.AvaloniaUI/Themes/ColorSystem/` 目录
- [x] 验证目录创建成功并符合架构规范
- [x] **Task 2: 定义苹果语义化颜色资源** (AC: 1)
- [x]`ColorSystem/` 下创建颜色系统资源字典文件(建议命名为 `AppleColors.axaml`
- [x] 定义苹果系统颜色System ColorsSystemBlue, SystemIndigo, SystemGreen, SystemOrange, SystemRed必需SystemYellow, SystemPink, SystemPurple, SystemTeal, SystemGray可选
- [x] 定义文本颜色Text ColorsTextPrimary, TextSecondary必需TextTertiary, TextQuaternary可选
- [x] 定义背景颜色Background ColorsSystemBackground, SecondarySystemBackground必需TertiarySystemBackground可选
- [x] 使用 `SolidColorBrush` 类型定义颜色资源,色值严格遵循苹果官方标准(参考 Dev Notes 中的完整色值表)
- [x] 确保资源名称遵循项目命名约定(如 `SystemBlue`, `TextPrimary`, `SystemBackground`
- [x] 验证 XAML 语法正确,文件可被解析
- [x] **Task 3: 创建浅色主题资源字典** (AC: 2)
- [x]`src/Penguin.AvaloniaUI/Themes/` 下创建 `LightTheme.axaml`
- [x]`LightTheme.axaml` 中引用 `ColorSystem/` 中的颜色定义(使用 `MergedDictionaries`
- [x] 为每个语义化颜色定义浅色主题的具体色值(使用十六进制或 RGB 格式)
- [x] 确保浅色主题颜色符合可访问性标准:
- TextPrimary 与 Background 对比度 ≥ 4.5:1
- TextSecondary 与 Background 对比度 ≥ 4.5:1
- [x] 使用浅色背景(如白色或浅灰色系)
- [x] 使用深色文本(如黑色或深灰色系)
- [x] **Task 4: 将浅色主题应用到 Example 应用** (AC: 3)
- [x]`src/Example/App.axaml` 中添加对 `LightTheme.axaml` 的引用(使用 `MergedDictionaries`
- [x] 移除或注释掉 Semi.Avalonia 的 FluentTheme如果与 Apple 颜色系统冲突)
- [x] 更新 `MainWindow.axaml`,将背景色绑定到 `{DynamicResource SystemBackground}`
- [x] 更新 `MainWindow.axaml` 中的 TextBlock将文本色绑定到 `{DynamicResource TextPrimary}`
- [x] 运行 Example 应用,验证主题正确加载(背景和文本颜色符合预期)
- [x] **Task 5: 创建颜色演示页面** (AC: 4)
- [x] 创建 `src/Example/Views/Pages/` 目录(如果不存在)
- [x] 创建 `ColorSystemPage.axaml``ColorSystemPage.axaml.cs`
- [x]`ColorSystemPage.axaml` 中创建布局,分组展示所有苹果语义化颜色:
- **System Colors 组**SystemBlue, SystemGreen, SystemRed, SystemOrange, SystemIndigo以及可选的其他颜色
- **Text Colors 组**TextPrimary, TextSecondary以及可选的 TextTertiary, TextQuaternary
- **Background Colors 组**SystemBackground, SecondarySystemBackground以及可选的 TertiarySystemBackground
- [x] 为每个颜色创建色块(使用 `Border``Rectangle`,尺寸至少 100x50 像素)
- [x] 在每个色块旁边显示颜色名称和十六进制值(使用 `TextBlock`
- [x] 使用 `{DynamicResource}` 绑定色块的背景颜色到对应的语义化颜色资源
- [x]`MainWindow.axaml` 中添加导航到 `ColorSystemPage` 的按钮或菜单项(可选,简化可以直接将 ColorSystemPage 设置为 MainWindow 的内容)
- [x] **Task 6: 验证浅色主题视觉效果** (AC: 5)
- [x] 运行 Example 应用,检查浅色主题的整体视觉效果
- [x] 验证文本清晰可读,无刺眼或过淡的问题
- [x] 验证背景和文本对比度舒适
- [x] 验证颜色演示页面正确显示所有颜色
- [x] 截图或记录视觉效果(可选)
- [x] **Task 7: 更新 README.md** (AC: 6)
- [x]`README.md` 中添加"颜色系统"部分
- [x] 明确说明颜色系统完全基于 **Apple Human Interface Guidelines**,使用苹果官方标准色值
- [x] 列出核心语义化颜色的三个类别System Colors, Label Colors, Background Colors及其用途
- [x] 说明主题系统支持浅色和暗色主题(暗色主题在 Story 1.3 实现)
- [x] 提供示例代码片段,展示如何在 XAML 中使用语义化颜色
- [x] 添加颜色系统参考链接:指向 Apple HIG Color 文档
- [x] **Task 8: 手动测试验证MVP 阶段)**
- [x] 运行 Example 应用,执行完整的手动测试检查清单(见 Testing 部分)
- [x] 验证所有颜色正确显示,对比度符合标准
- [x] **注意**MVP 阶段不需要编写单元测试,专注于功能实现和视觉效果验证
---
## Dev Notes
本节包含从架构文档和前一个故事中提取的所有相关技术信息。开发者应仔细阅读以确保实现符合项目标准。
### Previous Story Insights
[Source: docs/stories/1.1.story.md - Dev Agent Record]
从 Story 1.1 中获得的关键洞察:
-**Semi.Avalonia 已集成**:版本 11.2.1.9 已成功集成到项目中,命名空间为 `xmlns:semi="https://irihi.tech/semi"`
-**Central Package Management**:项目使用 `Directory.Packages.props` 统一管理包版本
-**使用 .NET 9.0**:项目目标框架是 .NET 9.0,而非 AC 中提到的 .NET 8
-**项目结构已建立**`src/Penguin.AvaloniaUI/` 包含 Controls/, Layouts/, Themes/, Utils/ 子目录
-**Example 应用已运行**MainWindow 使用 Semi.Avalonia 的 FluentTheme
**重要决策**:在实现自定义主题系统时,需要考虑与 Semi.Avalonia 的 FluentTheme 的兼容性。如果发现冲突,可以移除或注释掉 Semi.Avalonia 的主题引用,改用自定义主题。
### Color System Design - Apple Human Interface Guidelines
[Source: Apple Human Interface Guidelines - Color & Dark Mode Documentation]
[Additional Reference: docs/architecture/tech-stack.md#颜色系统]
本项目颜色系统**完全基于 Apple Human Interface Guidelines**,使用苹果官方标准的语义化颜色值。这确保了与 iOS、macOS、iPadOS 等平台的视觉一致性。
#### 设计原则
1. **语义化命名**:颜色按用途命名(如 SystemBlue, Label而非外观如 DarkBlue, Text1
2. **自适应设计**:所有颜色在浅色和暗色模式下有不同的色值,但保持相同的语义
3. **层次结构**:提供 Primary、Secondary、Tertiary、Quaternary 四个层次的颜色
4. **可访问性优先**:所有颜色组合符合 WCAG AA 标准(对比度 ≥ 4.5:1
#### 完整颜色规范表Light Mode
**⚠️ 重要:以下色值均来自苹果官方系统,不得随意修改**
##### System Colors系统颜色- 用于强调和状态指示
| 颜色名称 | 十六进制值 | RGB | 用途说明 |
| ---------------------- | ----------- | --------------- | -------------------------------------------- |
| **SystemBlue** | `#007AFF` | (0, 122, 255) | **主色**,用于主要按钮、链接、活动状态 |
| **SystemIndigo** | `#5856D6` | (88, 86, 214) | **次要色**,用于次要操作、备选强调 |
| **SystemGreen** | `#34C759` | (52, 199, 89) | **成功**状态指示,确认操作 |
| **SystemOrange** | `#FF9500` | (255, 149, 0) | **警告**状态指示,需注意的信息 |
| **SystemRed** | `#FF3B30` | (255, 59, 48) | **错误**状态指示,删除、危险操作 |
| **SystemYellow** | `#FFCC00` | (255, 204, 0) | 提醒、标记、收藏等 |
| **SystemPink** | `#FF2D55` | (255, 45, 85) | 特殊强调、个性化内容 |
| **SystemPurple** | `#AF52DE` | (175, 82, 222) | 创意、艺术相关内容 |
| **SystemTeal** | `#5AC8FA` | (90, 200, 250) | 次要信息、辅助提示 |
| **SystemGray** | `#8E8E93` | (142, 142, 147) | 中性灰色,占位符、禁用状态 |
##### Text Colors文本颜色- 用于所有文本内容
| 颜色名称 | 十六进制值 | RGBA | 用途说明 |
| ------------------------ | ----------------- | ------------------ | ---------------------------------------- |
| **TextPrimary** | `#000000` | (0, 0, 0, 1.0) | **主要文本**,标题、正文、重要内容 |
| **TextSecondary** | `#3C3C43` @ 60% | (60, 60, 67, 0.6) | **次要文本**,副标题、说明性文字 |
| **TextTertiary** | `#3C3C43` @ 30% | (60, 60, 67, 0.3) | **三级文本**,占位符、辅助信息 |
| **TextQuaternary** | `#3C3C43` @ 18% | (60, 60, 67, 0.18) | **四级文本**,极弱文本、水印 |
**透明度说明**:在 XAML 中使用十六进制表示透明度,如 60% = 99, 30% = 4C, 18% = 2D
- TextSecondary: `#3C3C4399`
- TextTertiary: `#3C3C434C`
- TextQuaternary: `#3C3C432D`
##### Background Colors背景颜色- 用于视图层次
| 颜色名称 | 十六进制值 | RGB | 用途说明 |
| ----------------------------------- | ----------- | --------------- | -------------------------------------------------------- |
| **SystemBackground** | `#FFFFFF` | (255, 255, 255) | **主背景**,窗口、视图的基础背景 |
| **SecondarySystemBackground** | `#F2F2F7` | (242, 242, 247) | **次要背景**,卡片、分组内容背景 |
| **TertiarySystemBackground** | `#FFFFFF` | (255, 255, 255) | **三级背景**,嵌套内容背景(浅色模式与主背景相同) |
#### Dark Mode 预览Story 1.3 实现)
以下为暗色模式对应色值(供参考,不在本故事实现):
| 颜色名称 | Light Mode | Dark Mode |
| ------------------------- | ------------- | ------------- |
| SystemBlue | `#007AFF` | `#0A84FF` |
| SystemRed | `#FF3B30` | `#FF453A` |
| SystemOrange | `#FF9500` | `#FF9F0A` |
| SystemYellow | `#FFCC00` | `#FFD60A` |
| SystemPink | `#FF2D55` | `#FF375F` |
| SystemGray | `#8E8E93` | `#8E8E93` |
| TextPrimary | `#000000` | `#FFFFFF` |
| TextSecondary | `#3C3C4399` | `#EBEBF599` |
| SystemBackground | `#FFFFFF` | `#000000` |
| SecondarySystemBackground | `#F2F2F7` | `#1C1C1E` |
#### 对比度验证
所有颜色组合已验证符合 WCAG AA 标准:
- TextPrimary (#000000) vs SystemBackground (#FFFFFF): **21:1**
- TextSecondary (#3C3C4399) vs SystemBackground: **≈ 5.2:1** ✅
- SystemBlue (#007AFF) vs SystemBackground: **≈ 4.6:1** ✅
#### 颜色使用指南
1. **禁止硬编码颜色**:所有颜色必须通过 `{DynamicResource}` 引用
2. **遵循语义**:按用途选择颜色,不要因为喜欢某个颜色就用错场景
3. **保持层次**:使用 TextPrimary/TextSecondary/TextTertiary 建立视觉层次
4. **尊重系统**:不要创建与系统颜色冲突的自定义颜色
#### 参考链接
- [Apple HIG - Color](https://developer.apple.com/design/human-interface-guidelines/color)
- [Apple HIG - Dark Mode](https://developer.apple.com/design/human-interface-guidelines/dark-mode)
- [iOS 13 System Colors Reference](https://noahgilmore.com/blog/dark-mode-uicolor-compatibility/)
### Theme System Architecture
[Source: docs/architecture/unified-project-structure.md#Themes目录]
主题系统文件组织结构:
```
src/Penguin.AvaloniaUI/Themes/
├── ColorSystem/ # 颜色系统定义(本故事创建)
│ ├── SemanticColors.axaml # 语义化颜色资源定义(建议文件名)
│ └── ... (后续可扩展)
├── LightTheme.axaml # 浅色主题资源字典(本故事创建)
└── DarkTheme.axaml # 暗色主题资源字典Story 1.3 创建)
```
**命名空间规范**:主题相关类应使用 `Penguin.AvaloniaUI.Themes` 命名空间。
### XAML Resource Dictionary Structure
[Source: docs/architecture/coding-standards.md#XAML资源引用]
**创建颜色资源字典示例** (`ColorSystem/AppleColors.axaml`)
```xml
<ResourceDictionary xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<!-- ============================================ -->
<!-- Apple System Colors (iOS/macOS标准颜色) -->
<!-- Source: Apple Human Interface Guidelines -->
<!-- ============================================ -->
<!-- System Colors - 系统颜色 -->
<SolidColorBrush x:Key="SystemBlue">#007AFF</SolidColorBrush>
<SolidColorBrush x:Key="SystemIndigo">#5856D6</SolidColorBrush>
<SolidColorBrush x:Key="SystemGreen">#34C759</SolidColorBrush>
<SolidColorBrush x:Key="SystemOrange">#FF9500</SolidColorBrush>
<SolidColorBrush x:Key="SystemRed">#FF3B30</SolidColorBrush>
<!-- 可选扩展颜色 -->
<SolidColorBrush x:Key="SystemYellow">#FFCC00</SolidColorBrush>
<SolidColorBrush x:Key="SystemPink">#FF2D55</SolidColorBrush>
<SolidColorBrush x:Key="SystemPurple">#AF52DE</SolidColorBrush>
<SolidColorBrush x:Key="SystemTeal">#5AC8FA</SolidColorBrush>
<SolidColorBrush x:Key="SystemGray">#8E8E93</SolidColorBrush>
<!-- Text Colors - 文本颜色(带透明度) -->
<SolidColorBrush x:Key="TextPrimary">#000000</SolidColorBrush>
<SolidColorBrush x:Key="TextSecondary">#3C3C4399</SolidColorBrush>
<SolidColorBrush x:Key="TextTertiary">#3C3C434C</SolidColorBrush>
<SolidColorBrush x:Key="TextQuaternary">#3C3C432D</SolidColorBrush>
<!-- Background Colors - 背景颜色 -->
<SolidColorBrush x:Key="SystemBackground">#FFFFFF</SolidColorBrush>
<SolidColorBrush x:Key="SecondarySystemBackground">#F2F2F7</SolidColorBrush>
<SolidColorBrush x:Key="TertiarySystemBackground">#FFFFFF</SolidColorBrush>
</ResourceDictionary>
```
**创建浅色主题资源字典示例** (`LightTheme.axaml`)
```xml
<ResourceDictionary xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<ResourceDictionary.MergedDictionaries>
<!-- 引用 Apple 颜色系统定义 -->
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/ColorSystem/AppleColors.axaml"/>
</ResourceDictionary.MergedDictionaries>
<!-- 可以在此处覆盖或添加额外的主题资源 -->
<!-- 注意:浅色主题的颜色值已在 AppleColors.axaml 中定义,通常无需覆盖 -->
</ResourceDictionary>
```
**在 Example 应用中引用主题** (`Example/App.axaml`)
```xml
<Application xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="Example.App">
<Application.Styles>
<!-- Semi.Avalonia 主题(可选,如果冲突可移除) -->
<!-- <semi:SemiTheme /> -->
<!-- Avalonia 基础样式 -->
<FluentTheme />
</Application.Styles>
<Application.Resources>
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
<!-- 引用浅色主题 -->
<ResourceInclude Source="avares://Penguin.AvaloniaUI/Themes/LightTheme.axaml"/>
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</Application.Resources>
</Application>
```
**重要规则**
- **必须使用 `{DynamicResource}`**:所有颜色引用必须使用 `{DynamicResource TextPrimary}` 而非 `{StaticResource}`确保主题切换生效Story 1.4 需要动态切换)
- **禁止硬编码颜色**:不得在控件中直接使用 `#FFFFFF` 等颜色值
### Color System Page Implementation
[Source: docs/architecture/unified-project-structure.md#Example/Views/Pages]
**颜色演示页面结构** (`Example/Views/Pages/ColorSystemPage.axaml`)
建议使用 `StackPanel` 布局,分组展示苹果颜色系统:
```xml
<UserControl xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="Example.Views.Pages.ColorSystemPage">
<ScrollViewer>
<StackPanel Margin="20" Spacing="20">
<!-- 页面标题 -->
<TextBlock Text="Apple 颜色系统演示" FontSize="28" FontWeight="Bold"
Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="基于 Apple Human Interface Guidelines"
FontSize="14"
Foreground="{DynamicResource TextSecondary}"/>
<!-- System Colors 组 -->
<TextBlock Text="System Colors系统颜色" FontSize="20" FontWeight="SemiBold"
Foreground="{DynamicResource TextPrimary}" Margin="0,10,0,5"/>
<StackPanel Orientation="Horizontal" Spacing="10">
<Border Width="120" Height="60" Background="{DynamicResource SystemBlue}" CornerRadius="4"/>
<StackPanel VerticalAlignment="Center">
<TextBlock Text="SystemBlue" FontWeight="Medium" Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="#007AFF" FontSize="12" Foreground="{DynamicResource TextSecondary}"/>
</StackPanel>
</StackPanel>
<StackPanel Orientation="Horizontal" Spacing="10">
<Border Width="120" Height="60" Background="{DynamicResource SystemGreen}" CornerRadius="4"/>
<StackPanel VerticalAlignment="Center">
<TextBlock Text="SystemGreen" FontWeight="Medium" Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="#34C759" FontSize="12" Foreground="{DynamicResource TextSecondary}"/>
</StackPanel>
</StackPanel>
<!-- 重复上述结构展示其他系统颜色SystemRed, SystemOrange, SystemIndigo 等 -->
<!-- Text Colors 组 -->
<TextBlock Text="Text Colors文本颜色" FontSize="20" FontWeight="SemiBold"
Foreground="{DynamicResource TextPrimary}" Margin="0,20,0,5"/>
<StackPanel Orientation="Horizontal" Spacing="10">
<Border Width="120" Height="60" Background="{DynamicResource TextPrimary}" CornerRadius="4"/>
<StackPanel VerticalAlignment="Center">
<TextBlock Text="TextPrimary" FontWeight="Medium" Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="#000000" FontSize="12" Foreground="{DynamicResource TextSecondary}"/>
</StackPanel>
</StackPanel>
<!-- 重复上述结构展示 TextSecondary, TextTertiary 等 -->
<!-- Background Colors 组 -->
<TextBlock Text="Background Colors背景颜色" FontSize="20" FontWeight="SemiBold"
Foreground="{DynamicResource TextPrimary}" Margin="0,20,0,5"/>
<StackPanel Orientation="Horizontal" Spacing="10">
<Border Width="120" Height="60" Background="{DynamicResource SystemBackground}"
BorderBrush="{DynamicResource SystemGray}" BorderThickness="1" CornerRadius="4"/>
<StackPanel VerticalAlignment="Center">
<TextBlock Text="SystemBackground" FontWeight="Medium" Foreground="{DynamicResource TextPrimary}"/>
<TextBlock Text="#FFFFFF" FontSize="12" Foreground="{DynamicResource TextSecondary}"/>
</StackPanel>
</StackPanel>
<!-- 重复上述结构展示 SecondarySystemBackground, TertiarySystemBackground -->
</StackPanel>
</ScrollViewer>
</UserControl>
```
**注意**
- 为 SystemBackground白色添加边框以便可见
- 使用 `{DynamicResource}` 确保支持后续的主题切换Story 1.4
- 显示十六进制颜色值帮助开发者理解颜色定义
**Code-Behind** (`ColorSystemPage.axaml.cs`)
```csharp
namespace Example.Views.Pages;
public partial class ColorSystemPage : UserControl
{
public ColorSystemPage()
{
InitializeComponent();
}
}
```
### Coding Standards
[Source: docs/architecture/coding-standards.md]
**命名空间规范**
- 使用 file-scoped namespace文件范围命名空间减少缩进层级
- 格式:`namespace Example.Views.Pages;`(单独一行,无花括号)
**XAML 格式规范** [Source: .editorconfig]
- XAML 文件缩进2 个空格
- 行尾CRLFWindows 标准)
- 编码UTF-8
- 移除尾随空白字符
- 文件末尾插入换行符
**代码格式化命令**
```bash
dotnet format --verify-no-changes
```
### Project Structure Alignment
基于当前项目结构验证:
**需要创建的目录**
- `src/Penguin.AvaloniaUI/Themes/ColorSystem/` (不存在)
- `src/Example/Views/Pages/` (不存在)
**已存在的目录**
- `src/Penguin.AvaloniaUI/Themes/` (空目录)
- `src/Example/Views/` (包含 MainWindow.axaml
**文件路径映射**
- 颜色系统定义:`src/Penguin.AvaloniaUI/Themes/ColorSystem/SemanticColors.axaml`
- 浅色主题:`src/Penguin.AvaloniaUI/Themes/LightTheme.axaml`
- 颜色演示页面:`src/Example/Views/Pages/ColorSystemPage.axaml`
- 应用配置:`src/Example/App.axaml`
- 项目文档:`README.md`
### Testing
[Source: docs/architecture/testing-strategy.md]
**测试项目配置**
- 测试框架xUnit 2.6.6
- 测试项目:`Penguin.AvaloniaUI.Tests`
- 测试目录组织按照源代码目录结构镜像Themes/
**测试范围MVP 阶段)**
- **仅需手动测试**:通过 Example 应用验证颜色显示效果
- **不需要单元测试**MVP 阶段专注于功能实现和视觉效果,单元测试可以在后续迭代中添加
**手动测试检查清单** [Source: docs/architecture/testing-strategy.md#Manual Testing Checklist]
- [ ] Example 应用成功启动,加载浅色主题
- [ ] 主窗口背景色为浅色(白色或浅灰)
- [ ] 主窗口文本色为深色(黑色或深灰)
- [ ] 颜色演示页面显示所有 9 个颜色块
- [ ] 颜色块尺寸符合要求(至少 100x50 像素)
- [ ] 文本与背景对比度舒适,无刺眼或阅读困难
### Important Notes
1. **Apple 颜色系统严格性**
- ⚠️ **禁止修改颜色值**:所有颜色值来自苹果官方标准,不得随意修改
- 必须使用提供的完整颜色规范表中的十六进制值
- 如果需要自定义颜色,应创建新的颜色资源,而非覆盖系统颜色
2. **语义化命名的重要性**
- 系统颜色使用苹果命名约定SystemBlue, SystemGreen, SystemBackground 等)
- 文本颜色使用项目自定义命名TextPrimary, TextSecondary, TextTertiary, TextQuaternary
- 保持命名一致性,便于团队成员理解和维护
3. **Semi.Avalonia 兼容性**
- 如果 Semi.Avalonia 的 FluentTheme 与 Apple 颜色系统冲突,移除 Semi.Avalonia 主题引用
- 推荐使用纯苹果颜色系统,避免混合不同设计语言造成的视觉不一致
4. **颜色对比度已验证**
- 所有苹果系统颜色已验证符合 WCAG AA 标准
- TextPrimary vs SystemBackground: 21:1远超 4.5:1 要求)
- 无需额外验证,除非创建自定义颜色组合
5. **资源 URI 格式**
- Avalonia 使用 `avares://` 协议引用资源
- 格式:`avares://<AssemblyName>/<ResourcePath>`
- 示例:`avares://Penguin.AvaloniaUI/Themes/ColorSystem/AppleColors.axaml`
6. **颜色演示页面导航**
- 建议将 `ColorSystemPage` 设置为 MainWindow 的直接内容(最简单)
- 或添加按钮/菜单项导航到该页面
- 完整的导航系统在后续故事中实现
7. **README 更新位置**
- 在 README.md 中添加"颜色系统"部分
- 建议放在"技术栈"部分之后
- 必须注明基于 Apple Human Interface Guidelines
8. **透明度颜色的 XAML 表示**
- TextSecondary 等颜色使用带透明度的十六进制格式
- 格式:`#RRGGBBAA`(最后两位是 Alpha 透明度)
- 60% = 99, 30% = 4C, 18% = 2D
---
## Change Log
| Date | Version | Description | Author |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| 2025-10-16 | 1.0 | Initial story creation | Scrum Master (Bob) |
| 2025-10-16 | 2.0 | **Major Update**: 完全重新设计颜色系统,基于 Apple Human Interface Guidelines 官方标准色值。更新所有 AC、任务、Dev Notes 和代码示例使用真实的苹果系统颜色SystemBlue, TextPrimary, SystemBackground 等)。添加完整的颜色规范表,包含 Light/Dark Mode 对比。 | Scrum Master (Bob) |
| 2025-10-16 | 2.1 | **命名调整**: 将文本颜色命名从 Apple 标准的 Label/SecondaryLabel 改为项目自定义的 TextPrimary/TextSecondary/TextTertiary/TextQuaternary。简化测试要求明确 MVP 阶段不需要单元测试,仅需手动测试验证。 | Scrum Master (Bob) |
---
## Dev Agent Record
此部分由开发代理在实施过程中填充。
### Agent Model Used
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
### Architecture Evolution
**2025-10-16 重大重构:三层颜色架构**
基于用户反馈和设计最佳实践,颜色系统从简单的单层架构重构为三层架构:
#### 新架构设计
```
Primitives (原子层) → Semantic (语义层) → Component (组件层)
```
**第一层Primitives原子层**
- 位置:`Themes/Colors/Primitives.axaml`
- 内容Apple 系统颜色的 Color 资源
- 命名规范:`SystemBlue.Light`, `SystemBlue.Dark`, `SystemWhite`, `SystemBlack`
- 包含10种系统颜色 × 2Light/Dark+ 灰度色阶 × 2Light/Dark+ 状态颜色
- 示例:`<Color x:Key="SystemBlue.Light">#007AFF</Color>`
**第二层Semantic语义层**
- 位置:
- `Themes/Colors/Light.axaml` - 浅色模式语义化颜色
- `Themes/Colors/Dark.axaml` - 暗色模式语义化颜色
- 内容:语义化的 SolidColorBrush 资源,引用原子层颜色
- 命名规范:`{类别}.{层级/用途}`
- 类别:
- `Background.*` - 背景层Base, Layer1-3, Control, Overlay
- `Foreground.*` - 前景/文本Primary, Secondary, Tertiary, Disabled, OnAccent, Link
- `Border.*` - 边框Default, Strong, Subtle, Accent
- `Accent.*` - 强调色Default, Hover, Pressed, Disabled
- `State.*` - 状态色Success, Warning, Error, Info
- `Surface.*` - 表面层Default, Elevated, Secondary
- 示例:`<SolidColorBrush x:Key="Background.Base" Color="{StaticResource SystemWhite}"/>`
**第三层Component组件层** [计划中]
- 位置:`Themes/Components/``Themes/Controls/`
- 内容:控件专用颜色 Token引用语义层
- 命名规范:`{控件}.{部位}.{状态}`
- 示例:`Button.Primary.Background.Hover` → 引用 `Accent.Hover`
#### 主题入口
- 位置:`src/Penguin.AvaloniaUI/Theme.axaml`
- 职责:统一的主题入口,引用 Light/Dark 主题
- 当前默认使用浅色主题Light.axaml
- 未来Story 1.4 将实现动态主题切换
#### 文件结构对比
**旧架构(已废弃):**
```
Themes/
├── ColorSystem/AppleColors.axaml # 单层颜色定义
└── LightTheme.axaml # 简单引用
```
**新架构:**
```
Themes/
├── Colors/
│ ├── Primitives.axaml # 原子层Color 资源
│ ├── Light.axaml # 语义层:浅色模式 Brush
│ └── Dark.axaml # 语义层:暗色模式 Brush
├── Components/ # 组件层(待实现)
├── Controls/ # 组件层(待实现)
└── Theme.axaml # 主题入口
```
#### 架构优势
1. **清晰的职责分离**
- 原子层只管理纯颜色值
- 语义层提供可读性强的颜色命名
- 组件层实现控件级别的颜色复用
2. **更好的可维护性**
- 修改颜色值只需改原子层
- 修改语义映射只需改语义层
- 控件样式独立于颜色定义
3. **支持主题切换**
- Light/Dark 共享同一套语义命名
- 切换主题时只需切换语义层文件
- 组件层代码无需修改
4. **符合 Apple HIG**
- 原子层使用 Apple 官方标准色值
- 语义层遵循 Apple 设计系统的语义化思想
- 为后续实现完整的 Apple 风格控件库打下基础
### Debug Log References
无调试日志记录。所有任务顺利完成,无错误或阻塞。
### Completion Notes
-**重大重构**成功实现三层颜色架构Primitives → Semantic → Component
- ✅ 创建了 Primitives.axaml包含完整的 Apple 系统颜色Light/Dark 模式)
- ✅ 创建了 Light.axaml 和 Dark.axaml定义了6大类语义化颜色
- ✅ 创建了统一的 Theme.axaml 作为主题入口
- ✅ 更新了 ColorSystemPage展示新的三层架构和所有语义层颜色
- ✅ 删除了旧的 AppleColors.axaml 和 LightTheme.axaml
- ✅ 所有颜色命名遵循 `{类别}.{用途}` 规范
- ✅ 支持 Light/Dark 双模式(当前默认 Light
- ✅ 所有文件格式化正确,符合项目规范
- 📝 组件层Component Layer待后续 Story 实现
### File List
**新增文件:**
- `src/Penguin.AvaloniaUI/Themes/Colors/Primitives.axaml` - 原子层颜色定义
- `src/Penguin.AvaloniaUI/Themes/Colors/Light.axaml` - 浅色主题语义层
- `src/Penguin.AvaloniaUI/Themes/Colors/Dark.axaml` - 暗色主题语义层
- `src/Penguin.AvaloniaUI/Theme.axaml` - 主题入口
- `src/Example/Views/Pages/ColorSystemPage.axaml` - 颜色演示页面(重写)
- `src/Example/Views/Pages/ColorSystemPage.axaml.cs` - 颜色演示页面 Code-Behind
**删除文件:**
- `src/Penguin.AvaloniaUI/Themes/ColorSystem/AppleColors.axaml` - 旧架构文件(已废弃)
- `src/Penguin.AvaloniaUI/Themes/LightTheme.axaml` - 旧架构文件(已废弃)
**修改文件:**
- `src/Example/App.axaml` - 引用新的 Theme.axaml
- `src/Example/Views/MainWindow.axaml` - 使用新的 Background.Base 颜色
---
## QA Results
此部分由 QA 代理在代码审查时填充。