# 视觉规范

本文档详细说明组件视觉设计规范，包括颜色系统、字体排版、图标规范、阴影与圆角等。

## 🎨 颜色系统

### 设计原则

- **语义化** - 颜色传达明确的含义
- **主题适配** - 完美支持亮色和暗色主题
- **对比度** - 确保文字清晰可读
- **一致性** - 在整个系统中保持统一

### 亮色主题（Light Theme）

#### 背景色

| 名称 | 颜色值 | 用途 | AXAML 资源 |
|-----|--------|------|-----------|
| **主背景** | `#F3F3F3` | 桌面背景 | `DesktopBackgroundBrush` |
| **卡片背景** | `#FFFFFF` | 组件背景 | `CardBackgroundBrush` |
| **次级背景** | `#F9F9F9` | 悬停背景 | `CardBackgroundSecondaryBrush` |
| **输入框背景** | `#FFFFFF` | 输入框 | `TextBoxBackgroundBrush` |

#### 文本色

| 名称 | 颜色值 | 对比度 | 用途 | AXAML 资源 |
|-----|--------|--------|------|-----------|
| **主要文本** | `#1C1C1C` | 16.1:1 | 标题、重要信息 | `TextFillColorPrimaryBrush` |
| **次要文本** | `#616161` | 5.7:1 | 正文、描述 | `TextFillColorSecondaryBrush` |
| **辅助文本** | `#8E8E8E` | 3.5:1 | 提示、说明 | `TextFillColorTertiaryBrush` |
| **禁用文本** | `#C7C7C7` | 1.9:1 | 禁用状态 | `TextFillColorDisabledBrush` |

#### 强调色

| 名称 | 颜色值 | 用途 | AXAML 资源 |
|-----|--------|------|-----------|
| **主色** | `#0078D4` | 按钮、链接、选中状态 | `AccentBrush` |
| **主色悬停** | `#106EBE` | 按钮悬停 | `AccentHoverBrush` |
| **主色按下** | `#005A9E` | 按钮按下 | `AccentPressedBrush` |

#### 语义色

| 名称 | 颜色值 | 用途 | AXAML 资源 |
|-----|--------|------|-----------|
| **成功** | `#107C10` | 成功提示 | `SuccessBrush` |
| **警告** | `#FF8C00` | 警告提示 | `WarningBrush` |
| **错误** | `#E81123` | 错误提示 | `ErrorBrush` |
| **信息** | `#0078D4` | 信息提示 | `InfoBrush` |

#### 边框与分割线

| 名称 | 颜色值 | 用途 | AXAML 资源 |
|-----|--------|------|-----------|
| **边框** | `#E0E0E0` | 卡片边框 | `CardBorderBrush` |
| **分割线** | `#EBEBEB` | 分隔线 | `DividerBrush` |
| **输入框边框** | `#E0E0E0` | 输入框边框 | `TextBoxBorderBrush` |

### 暗色主题（Dark Theme）

#### 背景色

| 名称 | 颜色值 | 用途 | AXAML 资源 |
|-----|--------|------|-----------|
| **主背景** | `#202020` | 桌面背景 | `DesktopBackgroundBrush` |
| **卡片背景** | `#2C2C2C` | 组件背景 | `CardBackgroundBrush` |
| **次级背景** | `#343434` | 悬停背景 | `CardBackgroundSecondaryBrush` |
| **输入框背景** | `#2C2C2C` | 输入框 | `TextBoxBackgroundBrush` |

#### 文本色

| 名称 | 颜色值 | 对比度 | 用途 | AXAML 资源 |
|-----|--------|--------|------|-----------|
| **主要文本** | `#FFFFFF` | 15.3:1 | 标题、重要信息 | `TextFillColorPrimaryBrush` |
| **次要文本** | `#C8C8C8` | 8.5:1 | 正文、描述 | `TextFillColorSecondaryBrush` |
| **辅助文本** | `#8E8E8E` | 4.2:1 | 提示、说明 | `TextFillColorTertiaryBrush` |
| **禁用文本** | `#5E5E5E` | 2.3:1 | 禁用状态 | `TextFillColorDisabledBrush` |

#### 强调色

| 名称 | 颜色值 | 用途 | AXAML 资源 |
|-----|--------|------|-----------|
| **主色** | `#60CDFF` | 按钮、链接、选中状态 | `AccentBrush` |
| **主色悬停** | `#3DB8FF` | 按钮悬停 | `AccentHoverBrush` |
| **主色按下** | `#1AA7FF` | 按钮按下 | `AccentPressedBrush` |

#### 语义色

| 名称 | 颜色值 | 用途 | AXAML 资源 |
|-----|--------|------|-----------|
| **成功** | `#6CCB5F` | 成功提示 | `SuccessBrush` |
| **警告** | `#FCE100` | 警告提示 | `WarningBrush` |
| **错误** | `#FF99A4` | 错误提示 | `ErrorBrush` |
| **信息** | `#60CDFF` | 信息提示 | `InfoBrush` |

#### 边框与分割线

| 名称 | 颜色值 | 用途 | AXAML 资源 |
|-----|--------|------|-----------|
| **边框** | `#3F3F3F` | 卡片边框 | `CardBorderBrush` |
| **分割线** | `#3A3A3A` | 分隔线 | `DividerBrush` |
| **输入框边框** | `#3F3F3F` | 输入框边框 | `TextBoxBorderBrush` |

### 颜色使用示例

```xml
<!-- ✅ 正确：使用动态资源 -->
<Border Background="{DynamicResource CardBackgroundBrush}"
        BorderBrush="{DynamicResource CardBorderBrush}"
        BorderThickness="1">
  <StackPanel>
    <TextBlock Text="标题"
               Foreground="{DynamicResource TextFillColorPrimaryBrush}"/>
    <TextBlock Text="描述"
               Foreground="{DynamicResource TextFillColorSecondaryBrush}"/>
    <Button Content="操作"
            Background="{DynamicResource AccentBrush}"/>
  </StackPanel>
</Border>

<!-- ❌ 错误：硬编码颜色 -->
<Border Background="#FFFFFF"
        BorderBrush="#E0E0E0">
  <TextBlock Text="标题" Foreground="#1C1C1C"/>
  <!-- 不会响应主题切换 -->
</Border>
```

### 颜色对比度要求

**WCAG 2.1 标准**:

| 文本类型 | AA 级 | AAA 级 | 推荐 |
|---------|-------|--------|------|
| **正文文本**（< 18pt） | ≥ 4.5:1 | ≥ 7:1 | ≥ 4.5:1 |
| **大号文本**（≥ 18pt） | ≥ 3:1 | ≥ 4.5:1 | ≥ 3:1 |
| **UI 组件** | ≥ 3:1 | - | ≥ 3:1 |

**检查工具**:
- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
- [WhoCanUse](https://whocanuse.com/)

## 🔤 字体排版

### 字体家族

| 平台 | 主字体 | 备用字体 |
|-----|--------|---------|
| **中文 Windows** | Microsoft YaHei UI | 微软雅黑 |
| **英文 Windows** | Segoe UI | Arial |
| **数字专用** | Segoe UI | Roboto |

### AXAML 字体定义

```xml
<ResourceDictionary>
  <!-- 字体家族 -->
  <FontFamily x:Key="DesignFontFamilyBase">Microsoft YaHei UI</FontFamily>
  <FontFamily x:Key="DesignFontFamilyNumber">Segoe UI</FontFamily>
  
  <!-- 字体大小 -->
  <x:Double x:Key="DesignFontSizeXS">10</x:Double>
  <x:Double x:Key="DesignFontSizeS">12</x:Double>
  <x:Double x:Key="DesignFontSizeM">14</x:Double>
  <x:Double x:Key="DesignFontSizeL">16</x:Double>
  <x:Double x:Key="DesignFontSizeXL">18</x:Double>
  <x:Double x:Key="DesignFontSizeXXL">24</x:Double>
  <x:Double x:Key="DesignFontSizeHuge">32</x:Double>
  <x:Double x:Key="DesignFontSizeGiant">48</x:Double>
</ResourceDictionary>
```

### 字体规范

#### 标题（Headings）

| 级别 | 字号 | 行高 | 字重 | 用途 | AXAML |
|-----|------|------|------|------|-------|
| **H1** | 32px | 40px | Bold (700) | 页面标题 | `FontSize="32" FontWeight="Bold"` |
| **H2** | 24px | 32px | SemiBold (600) | 区块标题 | `FontSize="24" FontWeight="SemiBold"` |
| **H3** | 18px | 24px | SemiBold (600) | 小节标题 | `FontSize="18" FontWeight="SemiBold"` |
| **H4** | 16px | 22px | SemiBold (600) | 卡片标题 | `FontSize="16" FontWeight="SemiBold"` |

#### 正文（Body）

| 类型 | 字号 | 行高 | 字重 | 用途 | AXAML |
|-----|------|------|------|------|-------|
| **大号正文** | 16px | 24px | Regular (400) | 重要内容 | `FontSize="16"` |
| **标准正文** | 14px | 20px | Regular (400) | 常规内容 | `FontSize="14"` |
| **小号正文** | 12px | 18px | Regular (400) | 辅助说明 | `FontSize="12"` |
| **极小文字** | 10px | 16px | Regular (400) | 次要信息 | `FontSize="10"` |

#### 数字（Numbers）

| 类型 | 字号 | 字重 | 用途 | AXAML |
|-----|------|------|------|-------|
| **超大数字** | 48px | Bold (700) | 核心数据（温度） | `FontSize="48" FontWeight="Bold"` |
| **大数字** | 32px | Bold (700) | 重要数据（时间） | `FontSize="32" FontWeight="Bold"` |
| **中数字** | 24px | SemiBold (600) | 统计数据 | `FontSize="24" FontWeight="SemiBold"` |
| **小数字** | 14px | Regular (400) | 辅助数据 | `FontSize="14"` |

### 字体样式

```xml
<!-- 标题样式 -->
<TextBlock Text="天气预报"
           FontSize="18"
           FontWeight="SemiBold"
           Foreground="{DynamicResource TextFillColorPrimaryBrush}"/>

<!-- 正文样式 -->
<TextBlock Text="今天天气晴朗，适合出行"
           FontSize="14"
           FontWeight="Regular"
           Foreground="{DynamicResource TextFillColorSecondaryBrush}"/>

<!-- 数字样式 -->
<TextBlock Text="25°C"
           FontSize="32"
           FontWeight="Bold"
           FontFamily="Segoe UI"
           Foreground="{DynamicResource TextFillColorPrimaryBrush}"/>

<!-- 辅助文字 -->
<TextBlock Text="更新时间: 14:30"
           FontSize="12"
           FontWeight="Regular"
           Foreground="{DynamicResource TextFillColorTertiaryBrush}"/>
```

### 行高与间距

**行高（Line Height）**:
```
推荐行高 = 字号 × 1.4 - 1.6

示例:
14px 字号 → 20px 行高 (1.43)
16px 字号 → 24px 行高 (1.5)
18px 字号 → 28px 行高 (1.56)
```

**字间距（Letter Spacing）**:
```
中文: 0 (默认)
英文: 0 - 0.5px
数字: 0 - 1px (可选)
```

### 文本处理

#### 单行文本截断

```xml
<TextBlock Text="这是一段很长的文字，需要截断显示..."
           TextTrimming="CharacterEllipsis"
           MaxLines="1"/>
```

#### 多行文本

```xml
<TextBlock Text="这是一段很长的文字，会自动换行显示在多行中"
           TextWrapping="Wrap"
           MaxLines="3"
           TextTrimming="CharacterEllipsis"/>
```

#### 文本对齐

```xml
<!-- 左对齐（默认） -->
<TextBlock Text="左对齐" TextAlignment="Left"/>

<!-- 居中对齐 -->
<TextBlock Text="居中对齐" TextAlignment="Center"/>

<!-- 右对齐 -->
<TextBlock Text="右对齐" TextAlignment="Right"/>

<!-- 两端对齐 -->
<TextBlock Text="两端对齐" TextAlignment="Justify"/>
```

## 🎭 图标规范

### 图标来源

**推荐图标库**:
- [Fluent UI System Icons](https://github.com/microsoft/fluentui-system-icons)
- [Segoe Fluent Icons](https://learn.microsoft.com/windows/apps/design/style/segoe-fluent-icons-font)
- [Emoji](https://emojipedia.org/)

### 图标尺寸

| 尺寸 | 用途 | 示例 |
|-----|------|------|
| **12px** | 行内图标 | 文字旁边的小图标 |
| **16px** | 标准图标 | 按钮图标、列表图标 |
| **20px** | 中等图标 | 工具栏图标 |
| **24px** | 大图标 | 标题图标 |
| **32px** | 特大图标 | 功能入口 |
| **48px** | 巨大图标 | 天气图标、状态图标 |

### 图标使用

#### 使用 Fluent Icons 字体

```xml
<TextBlock Text="&#xE8FB;"
           FontFamily="Segoe Fluent Icons"
           FontSize="16"
           Foreground="{DynamicResource TextFillColorPrimaryBrush}"/>
```

#### 使用 Emoji

```xml
<TextBlock Text="☀️"
           FontSize="48"/>
```

#### 使用图片图标

```xml
<Image Source="avares://MyPlugin/Assets/icon.png"
       Width="24"
       Height="24"/>
```

#### 使用 SVG 图标

```xml
<Path Data="M12 2L2 7l10 5 10-5-10-5z..."
      Fill="{DynamicResource TextFillColorPrimaryBrush}"
      Width="24"
      Height="24"/>
```

### 图标颜色

```xml
<!-- 主色图标 -->
<TextBlock Text="📍"
           FontSize="16"
           Foreground="{DynamicResource TextFillColorPrimaryBrush}"/>

<!-- 次色图标 -->
<TextBlock Text="⚙️"
           FontSize="16"
           Foreground="{DynamicResource TextFillColorSecondaryBrush}"/>

<!-- 强调色图标 -->
<TextBlock Text="🔄"
           FontSize="16"
           Foreground="{DynamicResource AccentBrush}"/>
```

### 图标与文字搭配

```xml
<StackPanel Orientation="Horizontal" Spacing="4">
  <!-- 图标 -->
  <TextBlock Text="📍"
             FontSize="14"
             VerticalAlignment="Center"/>
  <!-- 文字 -->
  <TextBlock Text="北京"
             FontSize="14"
             VerticalAlignment="Center"/>
</StackPanel>
```

## 🌑 阴影与圆角

### 阴影系统

#### 阴影层级

| 层级 | 模糊 | 偏移 | 扩散 | 透明度 | 用途 |
|-----|------|------|------|--------|------|
| **Level 1** | 4px | 0,2px | 0 | 10% | 卡片 |
| **Level 2** | 8px | 0,4px | 0 | 15% | 悬浮卡片 |
| **Level 3** | 16px | 0,8px | 0 | 20% | 弹出层 |
| **Level 4** | 24px | 0,12px | 0 | 25% | 模态对话框 |

#### AXAML 阴影定义

```xml
<ResourceDictionary>
  <!-- 阴影资源 -->
  <BoxShadows x:Key="DesignShadowLevel1">0 2 8 0 #1A000000</BoxShadows>
  <BoxShadows x:Key="DesignShadowLevel2">0 4 16 0 #26000000</BoxShadows>
  <BoxShadows x:Key="DesignShadowLevel3">0 8 24 0 #33000000</BoxShadows>
  <BoxShadows x:Key="DesignShadowLevel4">0 12 32 0 #40000000</BoxShadows>
</ResourceDictionary>
```

#### 使用阴影

```xml
<!-- 标准卡片阴影 -->
<Border Background="{DynamicResource CardBackgroundBrush}"
        CornerRadius="8"
        BoxShadow="{StaticResource DesignShadowLevel1}">
  <!-- 内容 -->
</Border>

<!-- 悬浮时的阴影 -->
<Border.Styles>
  <Style Selector="Border:pointerover">
    <Setter Property="BoxShadow" Value="{StaticResource DesignShadowLevel2}"/>
  </Style>
</Border.Styles>
```

### 圆角系统

#### 圆角尺寸

| 尺寸 | 值 | 用途 |
|-----|---|------|
| **小圆角** | 4px | 按钮、标签 |
| **标准圆角** | 8px | 卡片、容器 |
| **大圆角** | 12px | 大卡片 |
| **圆形** | 50% | 头像、图标 |

#### AXAML 圆角定义

```xml
<ResourceDictionary>
  <CornerRadius x:Key="DesignCornerRadiusSmall">4</CornerRadius>
  <CornerRadius x:Key="DesignCornerRadiusComponent">8</CornerRadius>
  <CornerRadius x:Key="DesignCornerRadiusLarge">12</CornerRadius>
</ResourceDictionary>
```

#### 使用圆角

```xml
<!-- 标准组件圆角 -->
<Border CornerRadius="8">
  <!-- 内容 -->
</Border>

<!-- 使用资源 -->
<Border CornerRadius="{StaticResource DesignCornerRadiusComponent}">
  <!-- 内容 -->
</Border>

<!-- 圆形 -->
<Border Width="40" Height="40"
        CornerRadius="20">
  <!-- 圆形内容 -->
</Border>
```

### 边框

#### 边框粗细

| 粗细 | 用途 |
|-----|------|
| **1px** | 标准边框、分割线 |
| **2px** | 强调边框、选中状态 |
| **3px** | 聚焦边框 |

#### 使用边框

```xml
<!-- 标准边框 -->
<Border BorderBrush="{DynamicResource CardBorderBrush}"
        BorderThickness="1"
        CornerRadius="8">
  <!-- 内容 -->
</Border>

<!-- 选中状态 -->
<Border BorderBrush="{DynamicResource AccentBrush}"
        BorderThickness="2"
        CornerRadius="8">
  <!-- 内容 -->
</Border>

<!-- 不同方向的边框 -->
<Border BorderBrush="{DynamicResource DividerBrush}"
        BorderThickness="0,0,0,1">
  <!-- 只有底边框 -->
</Border>
```

## 🌈 透明与模糊

### 透明度

| 级别 | 透明度 | 用途 |
|-----|--------|------|
| **不透明** | 100% | 标准内容 |
| **半透明** | 80-90% | 悬浮层 |
| **透明** | 60-70% | 背景层 |
| **极透明** | 40-50% | 装饰元素 |

### Acrylic 亚克力效果

```xml
<Border>
  <Border.Background>
    <ExperimentalAcrylicMaterial
      BackgroundSource="Digger"
      TintColor="#F3F3F3"
      TintOpacity="0.8"
      MaterialOpacity="0.9"/>
  </Border.Background>
</Border>
```

## ✅ 视觉检查清单

发布前请检查：

### 颜色
- [ ] 使用 `DynamicResource` 而非硬编码
- [ ] 亮色主题显示正常
- [ ] 暗色主题显示正常
- [ ] 文本对比度 ≥ 4.5:1
- [ ] 语义色使用正确

### 字体
- [ ] 使用系统字体
- [ ] 字号符合规范
- [ ] 行高适中
- [ ] 长文本正确处理
- [ ] 字重使用合理

### 图标
- [ ] 图标尺寸统一
- [ ] 图标清晰可见
- [ ] 图标适配主题
- [ ] 与文字对齐

### 阴影与圆角
- [ ] 圆角统一 8px
- [ ] 阴影层级正确
- [ ] 边框颜色合适
- [ ] 边框粗细统一

## 📖 相关文档

- [布局规范](03-布局规范.md) - 安全区域和间距
- [交互规范](04-交互规范.md) - 交互状态和动画
- [主题系统](05-主题系统.md) - 主题切换实现
- [组件系统](../01-插件开发/02-核心概念/02-组件系统.md) - 组件开发

---

**记住**: 使用 DynamicResource，确保对比度，统一视觉元素。