# Airhub Flutter 样式规范 🎨

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

---

## 1. 设计令牌（Design Tokens）

**文件**：`lib/theme/design_tokens.dart`

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

---

## 2. 双层主题色体系

### 2.1 科技主题（App 公共页面）
**适用**：首页、蓝牙搜索、WiFi 配网、登录

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

// 按钮阴影
AppShadows.shadowPrimaryButton
```

### 2.2 产品专属主题
**当前产品**：卡皮巴拉（Capybara）毛绒机芯

```dart
// 按钮渐变
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。

```dart
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 次级按钮

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

```dart
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. 页面头部规范

### 标准结构
```dart
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` 暖沙色）。

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

---

## 7. Toast 通知

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

```dart
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` | 毛玻璃对话框 |