Cyrene-For-Android/devdocs/03-design-system.md

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）