LanMountainDesktop/docs/03-组件设计规范/README.md

组件设计规范

欢迎来到阑山桌面组件设计规范文档。本章节将帮助你设计出美观、统一、专业的桌面组件。

📐 设计哲学

阑山桌面的设计遵循以下核心原则：

• 🎨 现代简约 - 简洁的视觉语言，去除多余装饰
• 🌈 优雅融合 - 与 Windows 11 Fluent Design 无缝融合
• 🔄 一致体验 - 统一的视觉元素和交互模式
• ♿ 无障碍 - 易读、易用，支持不同用户需求
• 🌓 主题友好 - 完美适配亮色和暗色主题

📚 规范内容

1. 设计系统概述

• 设计原则
• 设计语言
• 设计工作流

2. 视觉规范

• 颜色系统
• 字体排版
• 图标规范
• 阴影与圆角
• 透明与模糊

3. 布局规范

• 安全区域 ⭐
• 间距系统
• 网格系统
• 组件尺寸标准
• 响应式布局

4. 交互规范

• 交互状态
• 动画与过渡
• 反馈机制
• 拖拽与调整

5. 主题系统

• 亮色主题
• 暗色主题
• 自定义主题
• 主题切换

🎯 快速开始

新手开发者

如果你是第一次设计桌面组件，建议按以下顺序学习：

1. ✅ 必读: 布局规范 - 理解安全区域和间距
2. ✅ 必读: 视觉规范 - 掌握颜色和字体
3. 📖 推荐: 设计系统概述 - 理解设计原则
4. 📖 推荐: 主题系统 - 支持主题切换

经验开发者

如果你已有 UI 设计经验，可以：

1. 🔍 快速浏览 设计系统概述
2. 📋 查阅 布局规范 了解安全区域
3. 🎨 参考 视觉规范 使用设计资源
4. 💻 直接开始开发，遇到问题时查阅相关章节

📖 设计规范速查

核心尺寸

项目	值	说明
最小组件宽度	120px	保证可读性
最小组件高度	80px	保证可用性
推荐组件宽度	200-400px	常规信息展示
推荐组件高度	150-300px	常规信息展示
安全边距	16px	内容到边缘的最小距离
圆角半径	8px	卡片和容器圆角

核心颜色（亮色主题）

用途	颜色值	说明
卡片背景	#FFFFFF	组件主背景
主要文本	#1C1C1C	标题、重要信息
次要文本	#616161	描述、辅助信息
强调色	#0078D4	按钮、链接
边框	#E0E0E0	卡片边框

核心字体

用途	字号	字重
大标题	24px	SemiBold (600)
标题	16-18px	SemiBold (600)
正文	14px	Regular (400)
辅助文字	12px	Regular (400)
数字	32-48px	Bold (700)

核心间距

场景	间距值	说明
安全边距	16px	内容到组件边缘
元素间距	8px	相关元素之间
区块间距	16px	不同区块之间
紧密间距	4px	标签、图标间距

🎨 设计资源

Avalonia AXAML 资源

系统提供了完整的设计资源字典：

<ResourceDictionary>
  <!-- 颜色资源 -->
  <SolidColorBrush x:Key="CardBackgroundBrush" Color="#FFFFFF"/>
  <SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="#1C1C1C"/>
  
  <!-- 尺寸资源 -->
  <CornerRadius x:Key="DesignCornerRadiusComponent">8</CornerRadius>
  <Thickness x:Key="DesignPaddingComponent">16</Thickness>
  
  <!-- 字体资源 -->
  <FontFamily x:Key="DesignFontFamilyBase">Microsoft YaHei UI</FontFamily>
</ResourceDictionary>

使用设计资源

<Border Background="{DynamicResource CardBackgroundBrush}"
        CornerRadius="{DynamicResource DesignCornerRadiusComponent}"
        Padding="{DynamicResource DesignPaddingComponent}">
  <TextBlock Text="Hello"
             Foreground="{DynamicResource TextFillColorPrimaryBrush}"
             FontSize="14"/>
</Border>

✅ 设计检查清单

在发布组件前，请确保：

视觉检查

• 遵循 16px 安全边距
• 使用系统颜色资源
• 使用系统字体和字号
• 圆角统一使用 8px
• 投影统一使用标准阴影

主题检查

• 亮色主题下文字清晰可读
• 暗色主题下文字清晰可读
• 使用 DynamicResource 而非硬编码颜色
• 图标和图片适配主题

布局检查

• 最小宽度不小于 120px
• 最小高度不小于 80px
• 内容不会溢出边界
• 长文本正确换行或截断
• 响应式布局适配不同尺寸

交互检查

• 按钮有明确的悬停效果
• 可交互元素有视觉反馈
• 加载状态有明确提示
• 错误状态有清晰说明

性能检查

• 图片使用合适的分辨率
• 动画流畅不卡顿
• 更新频率合理
• 无内存泄漏

🔗 相关资源

内部文档

• 插件开发 - 组件系统
• 插件开发 - 设置系统
• 实战案例 - 天气组件

外部参考

• Fluent Design System
• Windows 11 Design Principles
• Avalonia UI Documentation

💡 设计建议

保持简洁

• 只展示最重要的信息
• 避免信息过载
• 使用清晰的视觉层级

注重细节

• 对齐每一个像素
• 统一间距和尺寸
• 保持视觉一致性

考虑场景

• 组件会在桌面长期显示
• 用户可能会添加多个组件
• 组件应该低调但有用

用户体验

• 信息一目了然
• 交互符合直觉
• 错误处理友好

---

开始设计你的第一个组件: 布局规范 - 安全区域