xianyan/docs/04_架构与设计规范.md

🏗️ 闲言APP — 架构与设计规范

更新: 2026-04-20 | 作用: 架构决策 + 设计令牌 + iOS 26 页面设计规范

---

一、架构决策记录（ADR）

ADR	决策	选择	理由
001	状态管理	Riverpod 2.5+	编译时安全 + 依赖注入 + 异步支持
002	路由	go_router 14.0+	声明式路由 + 深链接 + ShellRoute
003	数据库	Drift (SQLite)	类型安全 SQL + 响应式查询 + Migration
004	网络层	Dio 5.4+	拦截器 + 请求取消 + FormData
005	UI 风格	iOS 26 Liquid Glass	Cupertino 优先 + 液态玻璃效果
006	底部面板	StupidSimpleGlassSheet	弹簧动画 + 拖拽关闭 + 多级吸附
007	Hero 动画	Heroine	弹簧物理效果替代 Hero
008	空状态动画	Lottie	JSON 动画替代静态 emoji，提升品质感
009	撒花效果	Confetti	点赞/导出等情感化反馈 (仅全局Overlay，列表项禁用)
010	下拉刷新	CustomRefreshIndicator	自定义液态玻璃风格刷新指示器
011	列表动画	AnimateDo	句子流交错入场动画，提升视觉节奏

---

二、设计令牌

2.1 颜色令牌

令牌	日间	夜间	用途
primary	#6C63FF	#8B83FF	主色
secondary	#FF6B6B	#FF8A8A	辅助色
background	#F2F2F7	#000000	背景
bgCard	#FFFFFF	#1C1C1E	卡片背景
bgGrouped	#F2F2F7	#000000	分组背景
textPrimary	#1C1C1E	#FFFFFF	主文字
textSecondary	#8E8E93	#8E8E93	次文字
iconPrimary	#1C1C1E	#FFFFFF	主图标
divider	#C6C6C8	#38383A	分割线

2.2 间距令牌（4的倍数）

令牌	值	用途
space1	4px	微间距
space2	8px	小间距
space3	16px	标准间距
space4	24px	大间距
space5	32px	超大间距

2.3 圆角令牌

令牌	值	用途
radiusSm	4px	小元素
radiusMd	8px	按钮/输入框
radiusLg	12px	卡片
radiusXl	20px	大面板
radiusFull	999px	圆形

2.4 Glass 令牌（iOS 26 Liquid Glass）

层级	thickness	blur	opacity	用途
base	0.02	20	0.6	背景容器
elevated	0.05	30	0.7	卡片/列表项
prominent	0.10	40	0.8	弹窗/面板
alert	0.15	50	0.9	警告/重要弹窗

---

三、iOS 26 页面设计规范

3.1 全局导航 — 液态玻璃 3 TabBar

┌──────────────────────────────────┐
│  🏠 首页  │  💡 灵感  │  ✏️ 编辑  │  ← GlassBottomBar
└──────────────────────────────────┘

• 使用 GlassBottomBar（liquid_glass_widgets）
• 液态玻璃指示器 + 发光效果
• 滚动时自动缩小

3.2 页面设计原则

1. 内容优先：Chrome 退让，内容前进
2. 层级清晰：通过 Glass 深度层级建立视觉层次
3. 触觉丰富：每次交互都有视觉 + 触觉反馈
4. 图文并茂：每个功能入口都有图标/插图
5. 一致性：所有页面遵循统一设计语言

3.3 页面设计速查

页面	导航方式	核心组件	Glass 层级
首页	Tab	句子卡片流 + 每日推荐	base
灵感	Tab	分类标签 + 句子卡片	elevated
编辑器	Tab	画布 + 底部面板	prominent
个人中心	Tab	设置列表 + 主题入口	base
搜索	全屏右滑入	搜索栏 + 结果列表	elevated
来源	全屏右滑入	分类Tab + 来源列表	elevated
会员	GlassSheet	权益 + 订阅方案	prominent
主题设置	全屏右滑入	选项组 + 预览卡片	elevated

3.4 底部面板规范

场景	组件	特性
选项面板	GlassActionSheet	液态玻璃效果
自定义内容	StupidSimpleGlassSheetRoute	弹簧动画 + 拖拽关闭
半屏面板	SheetSnappingConfig([0.4, 0.7, 1.0])	多级吸附

---

四、组件规范

4.1 GlassContainer 使用规范

// 代理层 — 统一入口
GlassContainer(
  depth: GlassDepth.elevated,  // base/elevated/prominent/alert
  borderRadius: 12,            // 使用 radiusLg 令牌
  padding: EdgeInsets.all(16), // 使用 space3 令牌
  child: ...,
)

4.2 禁止事项

• ❌ 硬编码颜色（必须使用 ext 令牌）
• ❌ 硬编码圆角（必须使用 radius 令牌）
• ❌ position: absolute 做整体布局
• ❌ 固定 px 宽度
• ❌ overflow:hidden 用于解决布局问题
• ❌ margin 负值修复结构

4.3 响应式断点

设备	视口	布局
手机	360-640px	单列
平板	768-1024px	双列
桌面	1280-1920px	多列