# 03 — 设计系统规范 (Material Design 3)

> **设计语言**：Material Design 3 (Material You)  
> **组件库**：`androidx.compose.material3`  
> **最低 API**：26（不支持 Monet 的设备回退为手动主题色）

---

## 1. 色彩系统

### 1.1 动态配色 (Dynamic Color)

```
首选：androidx.compose.material3.dynamicColor
    → 系统壁纸提取 Primary / Secondary / Tertiary
    → 支持 Android 12+ (API 31+)
    → API 26-30 回退为预设主题色

备选：用户在设置中手动选择 Seed Color
    → 通过 MaterialTheme.colorScheme 的 lightColorScheme/darkColorScheme 生成
```

### 1.2 预设主题色

| 主题名 | Seed Color | 氛围 |
|--------|-----------|------|
| 默认（昔涟紫） | `#9C6BFF` (Lavender) | 温柔、亲切 |
| 樱花粉 | `#FFB4C8` (Sakura) | 甜美 |
| 海洋蓝 | `#6BA4FF` (Ocean) | 清爽 |
| 森林绿 | `#6BCF7C` (Forest) | 自然 |
| 日落橙 | `#FF9E6B` (Sunset) | 温暖 |

### 1.3 暗黑模式

| 属性 | Light | Dark |
|------|-------|------|
| Surface | `#FFFBFF` | `#1C1B1F` |
| Background | `#FFFBFF` | `#1C1B1F` |
| Primary | Dynamic | Dynamic (暗黑自适应) |
| OnSurface | `#1C1B1F` | `#E6E1E5` |
| SurfaceVariant | `#E7E0EC` | `#49454F` |
| 遮罩颜色 | `rgba(0,0,0,0.5)` | `rgba(0,0,0,0.7)` |

### 1.4 悬浮窗专用色

```
覆盖层背景遮罩：
    Light: rgba(0, 0, 0, 0.5)   // 50% 不透明度
    Dark:  rgba(0, 0, 0, 0.7)   // 70% 不透明度

对话卡片背景：
    Light: MaterialTheme.colorScheme.surface
    Dark:  MaterialTheme.colorScheme.surface

卡片圆角：28dp (顶部) / 0dp (底部)
卡片阴影 (Light)：8dp elevation
卡片阴影 (Dark)：无阴影，用 1dp outline 代替
```

## 2. 字体系统 (Typography)

| 角色 | 字号 | 字重 | 行高 | 用途 |
|------|------|------|------|------|
| displayLarge | 57sp | 400 | 64sp | 欢迎页标题 |
| headlineMedium | 28sp | 400 | 36sp | 设置页标题 |
| titleLarge | 22sp | 400 | 28sp | 对话框标题 |
| titleMedium | 16sp | 500 | 24sp | 列表标题 |
| bodyLarge | 16sp | 400 | 24sp | 对话气泡文字 |
| bodyMedium | 14sp | 400 | 20sp | 辅助文字、时间戳 |
| labelLarge | 14sp | 500 | 20sp | 按钮文字 |
| labelMedium | 12sp | 500 | 16sp | Tab 标签 |
| labelSmall | 11sp | 500 | 16sp | 状态标签 |

字体家族：`system-ui`（默认），不支持自定义字体以保证加载速度和系统一致性。

## 3. 形状系统 (Shapes)

| 角色 | 圆角 | 用途 |
|------|------|------|
| extraSmall | 4dp | 小标签、芯片 |
| small | 8dp | 输入框、按钮 |
| medium | 12dp | 卡片、对话框 |
| large | 16dp | 大卡片 |
| extraLarge | 28dp | 底部弹出卡片、Sheet |

## 4. 组件规范

### 4.1 对话气泡

```
昔涟消息 (左侧)：
┌─────────────────────────────┐
│ 🤖 昔涟               10:32 │
│ ┌─────────────────────────┐ │
│ │ 开拓者，今天心情怎么样？   │ │  ← 圆角: 12dp (top-start 4dp)
│ └─────────────────────────┘ │    背景: PrimaryContainer
│                             │    文字: OnPrimaryContainer
└─────────────────────────────┘

用户消息 (右侧)：
┌─────────────────────────────┐
│                    你 10:33 │
│     ┌─────────────────────┐ │
│     │ 还不错！你呢？        │ │  ← 圆角: 12dp (top-end 4dp)
│     └─────────────────────┘ │    背景: Primary
│                             │    文字: OnPrimary
└─────────────────────────────┘
```

### 4.2 消息类型样式

| 类型 | 样式 | 示例 |
|------|------|------|
| `chat` | 普通气泡 | 对话内容 |
| `action` | 居中斜体、灰色 | *昔涟正在查看客厅灯光状态* |
| `thinking` | 折叠面板、虚线边框 | 可展开/折叠 |
| `system_info` | Toast 样式 | 服务状态告知 |
| `tool_progress` | 进度条 + 图标 | IoT 操作进行中 |

### 4.3 语音输入按钮 (悬浮窗核心组件)

```
┌─────────────────────────────────┐
│                                 │
│         🎤 波形动画              │  (LISTENING 状态)
│         "我在听..."              │
│                                 │
│  ┌───────────────────────────┐  │
│  │ 输入文字或直接说话...      │  │  (IDLE 状态，点击切换语音)
│  └───────────────────────────┘  │
│                                 │
│  ┌────┐                    ┌──┐ │
│  │ 🎤 │  (按住说话)        │⌨️│ │  (WAITING 状态)
│  └────┘                    └──┘ │
└─────────────────────────────────┘
```

### 4.4 昔涟状态指示器

```
在线 (绿色点 + "昔涟")：
● 昔涟

思考中 (黄色脉冲 + "思考中...")：
◉ 思考中...

离线 (灰色 + "离线")：
○ 昔涟 · 离线

说话中 (蓝色波纹 + "正在说话...")：
〰 正在说话...
```

### 4.5 IoT 设备卡片

```
┌──────────────────────────┐
│ 💡 客厅灯          ● ON  │
│ ┌──────────────────────┐ │
│ │ 亮度  ████████░░  80% │ │
│ │ 色温  ████░░░░░░ 4000K│ │
│ └──────────────────────┘ │
│         [💡 开关]         │
└──────────────────────────┘
```

## 5. 动效规范

| 动效 | 时长 | 曲线 | 说明 |
|------|------|------|------|
| 覆盖层出现 | 300ms | `FastOutSlowInEasing` | 底部滑入 |
| 覆盖层消失 | 250ms | `FastOutLinearInEasing` | 底部滑落 |
| 气泡出现 | 200ms | `LinearOutSlowInEasing` | 淡入 + 微上移 |
| 涟漪效果 | 400ms | `LinearEasing` | 标准 MD3 ripple |
| 页面切换 | 300ms | `FastOutSlowInEasing` | 淡入淡出 |
| 波形动画 | 循环 | — | 录制时音频可视化 |
| 状态指示脉冲 | 2s 循环 | — | 思考中 / 说话中的呼吸灯效果 |

## 6. 图标系统

| 来源 | 用途 |
|------|------|
| `Icons.Filled` | 导航栏、主要操作按钮 |
| `Icons.Outlined` | 列表项、辅助操作 |
| `Icons.Rounded` | 芯片、标签 |
| 自定义 Lottie | 昔涟头像动画、情感表达 |
| 自定义 Vector | 品牌 LOGO、IoT 设备图标 |

## 7. 悬浮窗 vs 全屏 布局差异

| 元素 | 全屏 Activity | 悬浮窗 Overlay |
|------|-------------|---------------|
| TopAppBar | 显示（标题 + 操作） | 不显示 |
| BottomNav | 显示（三 Tab） | 不显示 |
| 对话区域 | 全屏滚动 | 自适应高度，最大 70% 屏幕 |
| 背景 | Surface 纯色 | 半透明遮罩 + 卡片 |
| 圆角 | 无 | 顶部 28dp |
| 导航返回 | 系统返回键 | 关闭覆盖层 |
| IoT 面板 | 完整功能 | 仅限查询，无控制 |
| 设置入口 | 完整 | 无（需打开 APP） |

## 8. 无障碍规范

- 所有可交互元素提供 `contentDescription`
- 语音按钮提供大点击区域（最小 48dp × 48dp）
- 支持 TalkBack 导航
- 字体缩放：支持系统字体大小设置（最大 200%）
- 色彩对比度：满足 WCAG AA 标准（正文 ≥ 4.5:1，大文字 ≥ 3:1）