# 设计稿还原全局规范

> 跨平台通用的设计稿还原规范（Flutter / Vue / React / 小程序）
> 版本: v1.0.0 | 更新: 2026-01-20

---

## 🔴 核心原则

**全局样式优先检查**：在还原任何 UI 元素前，必须通过搜索检查项目是否已定义该样式，禁止直接硬编码样式值。

---

## 🔍 样式检查方法（通用流程）

### 步骤 1: 测量设计稿

从 Sketch/Figma 中测量出具体数值，例如：
- 圆角: 16px
- 按钮高度: 56px
- 颜色: #1C2B45
- 阴影: (6,6,12)

### 步骤 2: 全局搜索该值

**不要假设文件路径**，直接在项目根目录搜索该值：

#### 方法 1: 命令行搜索（推荐）

```bash
# 搜索数值（适用圆角、尺寸、间距）
grep -r "16" . --include="*.dart" --include="*.ts" --include="*.scss" --include="*.css"

# 搜索颜色
grep -ri "1C2B45\|1c2b45" .

# 搜索关键词（如 radius, shadow, color）
grep -ri "radius.*16\|16.*radius" .
```

#### 方法 2: IDE 全局搜索

1. VSCode/Android Studio: `Cmd/Ctrl + Shift + F`
2. 搜索内容: `16` 或 `1C2B45` 或 `radius`
3. 包含文件: `*.dart, *.ts, *.vue, *.scss`
4. 排除目录: `node_modules, build, .git`

### 步骤 3: 识别样式定义

搜索结果中寻找以下模式：

#### 常量定义模式

```dart
// Flutter
static const double borderRadius = 16;
static const double cardRadius = 16;
static const radius16 = 16.0;

// TypeScript/JavaScript  
export const RADIUS_LG = 16;
const borderRadius = '16px';

// SCSS
$radius-lg: 16px;
--radius-card: 16px;
```

#### 语义化命名模式

常见命名规则：
- `lg`, `large`, `big` → 大尺寸
- `md`, `medium`, `base` → 中等尺寸
- `sm`, `small` → 小尺寸
- `primary`, `main`, `brand` → 主要色
- `secondary`, `accent` → 次要色
- `text-*`, `bg-*`, `border-*` → 语义化颜色

### 步骤 4: 判断是否使用

判断标准：
- ✅ 该值在多个文件中重复出现 → 应该有全局定义
- ✅ 找到常量定义 → 使用该常量
- ❌ 只找到硬编码 → 考虑提取为常量
- ❌ 完全找不到 → 可能是新增样式，需确认是否需建立规范

---

## 📐 常见样式类型检查指南

### 1. 圆角 (Border Radius)

#### 搜索关键词
```bash
# 搜索具体数值
grep -ri "radius.*16\|16.*radius\|borderRadius.*16" .

# 搜索变量名
grep -ri "radius\|rounded\|corner" . --include="*.dart" --include="*.ts"
```

#### 可能的定义位置
- 常量类：`*Radius*`, `*Corner*`, `*Rounded*`
- CSS 变量：`--radius-*`, `--rounded-*`, `--border-radius-*`
- 配置对象：`theme.radius`, `config.borderRadius`

#### 常见命名模式
```dart
// Flutter
AppRadius.lg / DesignRadius.large / borderRadiusLarge / RADIUS_16

// CSS/SCSS
--radius-lg / $radius-large / @border-radius-lg

// JS/TS
borderRadius.lg / RADIUS.LARGE / theme.radius.large
```

### 2. 尺寸 (Size/Height/Width)

#### 搜索关键词
```bash
# 按钮高度
grep -ri "height.*56\|buttonHeight\|btnHeight" .

# 图标尺寸
grep -ri "iconSize\|icon.*size\|size.*icon" .

# 间距
grep -ri "spacing\|margin\|padding\|gap" .
```

#### 可能的定义位置
- 尺寸常量：`*Size*`, `*Height*`, `*Width*`, `*Spacing*`
- 组件配置：`ButtonConfig`, `IconConfig`
- Design Token：`spacing.*`, `size.*`

#### 常见命名模式
```dart
// 按钮
buttonHeightLarge / BTN_HEIGHT_LG / button.height.large

// 间距
spacingMedium / SPACING_16 / spacing.md / space-4

// 图标
iconSizeMedium / ICON_SIZE_24 / icon.size.md
```

### 3. 颜色 (Color)

#### 搜索关键词
```bash
# 搜索色值（HEX）
grep -ri "1C2B45\|#1C2B45" .

# 搜索色值（RGB）
grep -ri "0xFF1C2B45\|rgba(28,\s*43,\s*69" .

# 搜索颜色名
grep -ri "primary\|secondary\|brand\|accent" . --include="*color*"
```

#### 可能的定义位置
- 颜色类：`*Color*`, `*Palette*`, `*Theme*`
- CSS 变量：`--color-*`, `--bg-*`, `--text-*`
- 设计系统：`colors.*`, `palette.*`

#### 语义化颜色命名
```
功能色: primary, secondary, accent, brand
状态色: success, warning, error, info, disabled
文本色: text-primary, text-secondary, text-disabled, text-hint
背景色: bg-primary, bg-secondary, surface, background
边框色: border, border-light, border-dark, divider
```

### 4. 阴影 (Shadow/Elevation)

#### 搜索关键词
```bash
# 搜索阴影参数
grep -ri "boxShadow\|elevation\|shadow" .

# 搜索具体参数值
grep -ri "offset.*6.*6\|blur.*12" .
```

#### 可能的定义位置
- 阴影类：`*Shadow*`, `*Elevation*`
- CSS Mixin：`@mixin shadow`, `@mixin elevation`
- 预设对象：`shadows.*`, `elevations.*`

#### 常见命名模式
```dart
// 层级命名
shadow1 / shadow2 / elevation1 / elevation2

// 语义命名
shadowCard / shadowButton / shadowModal / shadowNone

// 尺寸命名
shadowSm / shadowMd / shadowLg / shadowXl
```

### 5. 字体 (Typography)

#### 搜索关键词
```bash
# 字号
grep -ri "fontSize.*14\|font.*14\|14px" .

# 字重
grep -ri "fontWeight\|font-weight\|w400\|w700" .

# 字体系列
grep -ri "fontFamily\|font-family" .
```

#### 可能的定义位置
- 字体类：`*Typography*`, `*TextStyle*`, `*Font*`
- CSS 变量：`--font-size-*`, `--font-weight-*`
- 主题配置：`theme.typography`, `textStyles.*`

#### 常见命名模式
```
// 层级命名
h1, h2, h3, h4, h5, h6

// 语义命名
headline, title, subtitle, body, caption, overline

// 尺寸命名
text-xs, text-sm, text-base, text-lg, text-xl
```

### 6. 渐变 (Gradient)

#### 搜索关键词
```bash
# 线性渐变
grep -ri "linearGradient\|linear-gradient\|LinearGradient" .

# 径向渐变
grep -ri "radialGradient\|radial-gradient" .

# 渐变色值
grep -ri "gradient.*start\|gradient.*end" .
```

#### 可能的定义位置
- 渐变对象：`*Gradient*`, `gradients.*`
- CSS 变量/Mixin：`--gradient-*`, `@mixin gradient`

### 7. 动画/过渡 (Animation/Transition)

#### 搜索关键词
```bash
# 动画时长
grep -ri "duration\|transition.*duration\|animationDuration" .

# 缓动函数
grep -ri "easing\|cubic-bezier\|ease-in\|ease-out" .
```

#### 可能的定义位置
- 动画配置：`*Animation*`, `*Transition*`, `*Duration*`
- CSS 变量：`--duration-*`, `--easing-*`

### 8. 层级 (Z-Index)

#### 搜索关键词
```bash
grep -ri "zIndex\|z-index" .
```

#### 常见命名
```
zIndexModal / zIndexDropdown / zIndexTooltip / zIndexOverlay
--z-modal / --z-dropdown / z-1000, z-2000
```

---

## 🚀 使用项目样式规范

### 通用使用流程

```
1. 从设计稿测量 → 2. 全局搜索 → 3. 找到定义 → 4. 使用常量/变量
```

### Flutter 示例

```dart
// ❌ 错误：直接硬编码
Container(
  decoration: BoxDecoration(
    borderRadius: BorderRadius.circular(16),
    color: Color(0xFF1C2B45),
  ),
  height: 56,
)

// ✅ 正确：先搜索项目，找到并使用常量
// 1. 搜索: grep -r "16" lib/ | grep -i radius
// 2. 发现: AppRadius.lg = 16 (在 lib/theme/app_radius.dart)
// 3. 使用常量:
import 'package:app/theme/app_radius.dart';
import 'package:app/theme/app_colors.dart';
import 'package:app/theme/app_sizes.dart';

Container(
  decoration: BoxDecoration(
    borderRadius: BorderRadius.circular(AppRadius.lg),
    color: AppColors.textPrimary,
  ),
  height: AppSizes.buttonHeightCTA,
)
```

### Vue / React 示例

```vue
<template>
  <div class="card">
    <button class="btn-cta">提交</button>
  </div>
</template>

<style scoped lang="scss">
// ❌ 错误：直接硬编码
.card {
  border-radius: 16px;
  box-shadow: 0 6px 12px rgba(0,0,0,0.1);
  height: 56px;
}

// ✅ 正确：先搜索项目 CSS 变量或 SCSS 变量
// 1. 搜索: grep -r "--radius\|$radius" src/
// 2. 发现: --radius-card: 16px (在 src/styles/variables.css)
// 3. 使用变量:
.card {
  border-radius: var(--radius-card);
  box-shadow: var(--shadow-card);
  height: var(--button-height-lg);
}
</style>
```

### 小程序示例

```javascript
// ❌ 错误：直接硬编码
<view style="border-radius: 16px; height: 56px;">

// ✅ 正确：先搜索配置文件
// 1. 搜索: grep -r "16" config/
// 2. 发现: RADIUS_LG = 16 (在 config/design.js)
// 3. 使用配置:
import { RADIUS_LG, BUTTON_HEIGHT_LG } from '@/config/design'

<view style="border-radius: {{RADIUS_LG}}rpx; height: {{BUTTON_HEIGHT_LG}}rpx;">
```


---

## ⚠️ 强制要求

### 禁止假设文件路径

```dart
// ❌ 禁止：假设样式定义在固定路径
import 'package:app/core/themes/design_constants.dart';  // 不确定是否存在

// ✅ 正确：先搜索确认
// 1. 搜索: grep -r "DesignRadius\|AppRadius\|RADIUS" lib/
// 2. 找到实际路径: lib/constants/app_theme.dart
// 3. 导入正确路径
import 'package:app/constants/app_theme.dart';
```

### 禁止跳过搜索直接硬编码

```dart
// ❌ 禁止流程
测量设计稿: 16px → 直接写: BorderRadius.circular(16)

// ✅ 正确流程
测量设计稿: 16px 
  ↓
搜索项目: grep -r "16" lib/ | grep -i "radius"
  ↓
找到定义: AppRadius.medium = 16  (或找不到)
  ↓
使用常量: BorderRadius.circular(AppRadius.medium)
(或提出是否需要新建常量)
```

### 必须搜索整个项目

不要只搜索特定目录，项目可能有不同的组织结构：

```bash
# ❌ 禁止：只搜索固定目录
grep -r "radius" lib/core/themes/

# ✅ 正确：搜索整个项目
grep -r "radius" . --include="*.dart"

# 常用搜索范围
lib/           # Flutter 主代码
src/           # Vue/React 主代码  
app/           # 某些项目的主代码
config/        # 配置文件
constants/     # 常量定义
theme/         # 主题定义
styles/        # 样式文件
utils/         # 工具函数
```

### 处理搜索无结果的情况

如果搜索不到该值的常量定义：

1. **扩大搜索范围** - 搜索相近值（如 16 → 搜索 15-18）
2. **搜索语义名称** - 搜索 `large`, `medium`, `card` 等
3. **检查是否有统一管理** - 搜索 `theme`, `config`, `constants`
4. **询问是否需要提取** - 该值在设计稿中多处出现，应提取为常量吗？
5. **说明原因后硬编码** - 如确实是特殊场景，添加注释说明

```dart
// ✅ 可接受的硬编码（特殊场景+注释）
BorderRadius.circular(13)  // 特殊圆角值，仅此处使用，已与设计确认
```


---

## 📋 设计稿还原检查清单

### ⭐ 核心检查（必须完成）

- [ ] 已从设计稿测量出具体数值（圆角/尺寸/颜色等）
- [ ] 已在项目中全局搜索该数值
- [ ] 已查看搜索结果，确认是否有常量定义
- [ ] 已决定使用常量或合理硬编码（特殊场景）

### 📝 详细检查清单

#### 圆角检查
- [ ] 已搜索: `grep -ri "radius.*[测量值]\|[测量值].*radius" .`
- [ ] 确认使用: `AppRadius.*` / `--radius-*` / `theme.radius.*`

#### 尺寸检查
- [ ] 已搜索: `grep -ri "height.*[测量值]\|width.*[测量值]" .`
- [ ] 确认使用: 按钮/图标/间距相关常量

#### 颜色检查
- [ ] 已搜索色值: `grep -ri "[色值HEX]" .`
- [ ] 已搜索语义名: `grep -ri "primary\|secondary\|brand" .`
- [ ] 确认使用: 颜色常量而非硬编码色值

#### 阴影检查
- [ ] 已搜索: `grep -ri "shadow\|elevation" .`
- [ ] 确认使用: 预设阴影而非手写参数

#### 字体检查
- [ ] 已搜索字号: `grep -ri "fontSize.*[测量值]" .`
- [ ] 已搜索字重: `grep -ri "fontWeight\|w[400|700]" .`
- [ ] 确认使用: 字体相关常量

### 🚫 反面检查（确保避免）

- [ ] 未跳过搜索直接硬编码
- [ ] 未假设文件路径（而是搜索确认）
- [ ] 未只搜索固定目录（而是搜索全项目）
- [ ] 未忽略搜索到的现有常量定义

---

## 🔍 实用搜索技巧

### 高效搜索命令

```bash
# 1. 按数值搜索（精确）
grep -r "16" . --include="*.dart" --include="*.ts" --include="*.scss"

# 2. 按数值范围搜索（模糊）
grep -rE "1[4-8]" . --include="*.dart"  # 搜索 14-18

# 3. 按关键词+数值搜索（组合）
grep -ri "radius.*16\|16.*radius" .

# 4. 按文件类型搜索
grep -r "radius" . --include="*{theme,constant,config,style}*"

# 5. 排除目录搜索（提高速度）
grep -r "radius" . --exclude-dir={node_modules,build,.git,dist}

# 6. 查看上下文（了解用法）
grep -r "AppRadius" . -A 3 -B 3  # 显示前后3行
```

### VSCode 搜索技巧

1. **正则搜索**: 勾选 `.*` 图标，搜索 `radius.*(16|1[4-8])`
2. **文件包含**: `*.dart, *.ts, *.vue, *.scss`
3. **文件排除**: `**/node_modules, **/build, **/.git`
4. **全词匹配**: 搜索 `\bradius\b` 而非 `radius`
5. **大小写敏感**: 根据项目命名规范调整

### 搜索结果分析

```
搜索结果示例:
lib/theme/app_radius.dart:10: static const double lg = 16;
lib/screens/home.dart:45: borderRadius: BorderRadius.circular(16),
lib/components/card.dart:23: final radius = 16.0;

分析:
✅ 第1条: 这是常量定义，应该使用它
❌ 第2-3条: 这是硬编码，应该改用第1条的常量
```

---

## 💡 项目无全局样式时的处理

如果搜索整个项目都找不到样式规范定义：

### 方案1: 创建全局样式文件（推荐）

```dart
// 1. 创建文件（根据项目结构选择合适位置）
// Flutter: lib/config/design_constants.dart
// Vue: src/config/design-tokens.ts

// 2. 提取常量
abstract class DesignConstants {
  // 从设计稿测量的常用值
  static const double radiusCard = 16;
  static const double buttonHeightLarge = 56;
  static const Color primaryColor = Color(0xFF1C2B45);
}

// 3. 逐步迁移硬编码
```

### 方案2: 暂时硬编码+注释

```dart
// 项目暂无设计系统，待后续统一重构
BorderRadius.circular(16)  // TODO: 提取为 DesignConstants.radiusCard
```

### 方案3: 咨询团队

在团队协作项目中，应先与团队确认：
- 是否计划建立设计系统？
- 样式规范是否有文档说明？
- 是否应该提取常量还是保持硬编码？

---

**维护团队**: MTA工作室  
**适用范围**: Flutter / Vue / React / 小程序 / 任何 UI 还原场景  
**核心理念**: 通过全局搜索发现项目现有规范，避免硬编码和假设