mta-mcp 1.0.0

package/standards/patterns/design-system-restoration.md

@@ -0,0 +1,570 @@
+# 设计稿还原全局规范
+
+> 跨平台通用的设计稿还原规范（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 还原场景  
+**核心理念**: 通过全局搜索发现项目现有规范，避免硬编码和假设