rtc_prd/flutter_style_guide.md

Airhub Flutter 样式规范 🎨

最后更新：2026-02-07 本文档是 design_system.md 的 Flutter 实现版本。 所有 Flutter 页面开发必须遵守本规范。

---

1. 设计令牌（Design Tokens）

文件：lib/theme/design_tokens.dart

所有颜色、字体、间距、圆角均应从此文件引用，禁止在页面中硬编码。

---

2. 双层主题色体系

2.1 科技主题（App 公共页面）

适用：首页、蓝牙搜索、WiFi 配网、登录

// 按钮渐变
AppColors.btnPrimaryGradient  // cyan→blue→indigo→purple

// 按钮阴影
AppShadows.shadowPrimaryButton

2.2 产品专属主题

当前产品：卡皮巴拉（Capybara）毛绒机芯

// 按钮渐变
AppColors.btnCapybaraGradient  // #ECCFA8→#C99672
// 或
AppColors.btnPlushGradient     // 同色 LinearGradient 对象

// 按钮阴影
AppShadows.shadowPlushButton

未来扩展：每新增一个产品线，在 app_colors.dart / design_tokens.dart 中新增对应的渐变和阴影定义。产品页面的所有主按钮颜色跟随产品卡片颜色。

2.3 混用禁令

• 公共页面 → 只用科技渐变
• 卡皮巴拉页面 → 只用毛绒渐变
• 严禁混搭

---

3. 按钮规范

3.1 主按钮（GradientButton）

组件：lib/widgets/gradient_button.dart

所有主操作按钮必须使用 GradientButton，禁止手写 Container + GestureDetector。

GradientButton(
  text: '按钮文字',
  height: 48,                    // 常规按钮
  // height: 56,                 // 登录/配网等重要操作
  gradient: AppColors.btnPlushGradient,  // 或不传使用默认科技渐变
  onPressed: () {},
)

属性	规范值
高度	48px（常规）/ 56px（登录/配网）
圆角	height / 2（胶囊形）
字体	DM Sans, 17px, w600, 白色
光泽	顶部 white 15% → transparent 渐变
点击	InkWell 涟漪，splashColor white 20%
禁用	opacity 0.7

3.2 次级按钮

用于与主按钮并排的取消/次要操作。

Container(
  height: 48,  // 与主按钮等高
  decoration: BoxDecoration(
    border: Border.all(color: Color(0xFFE5E7EB)),
    borderRadius: BorderRadius.circular(24),
    color: Colors.white.withOpacity(0.8),
  ),
)

属性	规范值
高度	与相邻主按钮等高
圆角	24px
边框	1px #E5E7EB
背景	white 80%
字体	16px, w600, #4B5563

3.3 对话框按钮

• 单按钮：GradientButton, height 48, 全宽
• 双按钮：左次级 + 右 GradientButton, height 44, Expanded

---

4. 页面头部规范

标准结构

Container(
  padding: EdgeInsets.symmetric(horizontal: 4, vertical: 8),
  child: Stack(
    alignment: Alignment.center,
    children: [
      // 左：返回按钮
      Align(
        alignment: Alignment.centerLeft,
        child: Container(
          width: 40,
          height: 40,
          decoration: BoxDecoration(
            color: Colors.white.withOpacity(0.6),  // AppColors.iconBtnBg
            borderRadius: BorderRadius.circular(12), // AppRadius.button
            // 无边框
          ),
          child: Icon(
            Icons.arrow_back_ios_new,
            size: 18,
            color: Color(0xFF4B5563),
          ),
        ),
      ),
      // 中：标题
      Text('页面标题', style: AppTextStyles.title),
      // 右：可选按钮或 SizedBox(width: 40) 占位
    ],
  ),
)

属性	规范值
返回按钮	40×40, 圆角 12, 背景 white 60%, 无边框
图标	Icons.arrow_back_ios_new, size 18, color #4B5563
标题	Outfit, 17px, w600, #1F2937, 居中
背景	transparent
页面背景	AnimatedGradientBackground

---

5. 字体规范

用途	字体	字号	字重
Logo	Press Start 2P	—	—
页面标题	Outfit	17	w600
按钮文字	DM Sans	17	w600
正文	DM Sans	14-16	w400-w500
小标签	DM Sans	12-13	w500

全局默认字体通过 app_theme.dart 设为 DM Sans。

---

6. 页面背景规范

所有页面使用 AnimatedGradientBackground 作为背景，禁止使用纯白或固定色背景（除故事相关页面使用 #FDF9F3 暖沙色）。

Scaffold(
  backgroundColor: Colors.transparent,
  body: Stack(
    children: [
      const AnimatedGradientBackground(),
      // 页面内容
    ],
  ),
)

---

7. Toast 通知

使用 AppToast.show() 替代 ScaffoldMessenger.showSnackBar()。

AppToast.show(context, '操作成功');
AppToast.show(context, '出错了', isError: true);

---

8. 文件索引

文件	说明
lib/theme/design_tokens.dart	颜色、字体、间距、圆角、阴影
lib/theme/app_colors.dart	渐变定义（btnPrimaryGradient, btnPlushGradient）
lib/theme/app_theme.dart	MaterialApp 全局主题
lib/widgets/gradient_button.dart	统一主按钮组件
lib/widgets/ios_toast.dart	iOS 风格 toast 通知
lib/widgets/animated_gradient_background.dart	流动渐变背景
lib/widgets/glass_dialog.dart	毛玻璃对话框