LanMountainDesktop/docs/03-组件设计规范/02-视觉规范.md

视觉规范

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

🎨 颜色系统

设计原则

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

亮色主题（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

颜色使用示例

<!-- ✅ 正确：使用动态资源 -->
<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
• WhoCanUse

🔤 字体排版

字体家族

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

AXAML 字体定义

<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"

字体样式

<!-- 标题样式 -->
<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 (可选)

文本处理

单行文本截断

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

多行文本

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

文本对齐

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

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

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

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

🎭 图标规范

图标来源

推荐图标库:

• Fluent UI System Icons
• Segoe Fluent Icons
• Emoji

图标尺寸

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

图标使用

使用 Fluent Icons 字体

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

使用 Emoji

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

使用图片图标

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

使用 SVG 图标

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

图标颜色

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

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

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

图标与文字搭配

<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 阴影定义

<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>

使用阴影

<!-- 标准卡片阴影 -->
<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 圆角定义

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

使用圆角

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

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

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

边框

边框粗细

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

使用边框

<!-- 标准边框 -->
<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 亚克力效果

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

✅ 视觉检查清单

发布前请检查：

颜色

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

字体

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

图标

• 图标尺寸统一
• 图标清晰可见
• 图标适配主题
• 与文字对齐

阴影与圆角

• 圆角统一 8px
• 阴影层级正确
• 边框颜色合适
• 边框粗细统一

📖 相关文档

• 布局规范 - 安全区域和间距
• 交互规范 - 交互状态和动画
• 主题系统 - 主题切换实现
• 组件系统 - 组件开发

---

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