mta-mcp 2.17.0 → 3.0.0

package/standards/syntax-mapping.md

@@ -0,0 +1,256 @@
+# 跨框架样式语法映射表
+
+> 设计稿参数到各框架代码的转换参考
+
+## 📋 概述
+
+本文档提供设计稿参数到不同框架（Flutter、Vue/CSS、React Native、小程序）的语法映射，用于设计稿还原时的快速查阅。
+
+---
+
+## 📐 尺寸与布局
+
+### 宽高
+
+| 设计稿 | Flutter | Vue/CSS | React Native | 小程序 |
+|--------|---------|---------|--------------|--------|
+| width: 100px | `width: 100` | `width: 100px` | `width: 100` | `width: 200rpx` |
+| height: 50px | `height: 50` | `height: 50px` | `height: 50` | `height: 100rpx` |
+| 100% 宽度 | `double.infinity` | `width: 100%` | `width: '100%'` | `width: 100%` |
+
+### 内边距 (Padding)
+
+| 设计稿 | Flutter | Vue/CSS | React Native | 小程序 |
+|--------|---------|---------|--------------|--------|
+| 全部 16px | `padding: EdgeInsets.all(16)` | `padding: 16px` | `padding: 16` | `padding: 32rpx` |
+| 水平 16px | `padding: EdgeInsets.symmetric(horizontal: 16)` | `padding: 0 16px` | `paddingHorizontal: 16` | `padding: 0 32rpx` |
+| 垂直 12px | `padding: EdgeInsets.symmetric(vertical: 12)` | `padding: 12px 0` | `paddingVertical: 12` | `padding: 24rpx 0` |
+| 上20 右16 下12 左16 | `padding: EdgeInsets.fromLTRB(16, 20, 16, 12)` | `padding: 20px 16px 12px 16px` | `paddingTop: 20, ...` | `padding: 40rpx 32rpx 24rpx` |
+
+### 外边距 (Margin)
+
+| 设计稿 | Flutter | Vue/CSS | React Native | 小程序 |
+|--------|---------|---------|--------------|--------|
+| 底部 16px | `margin: EdgeInsets.only(bottom: 16)` | `margin-bottom: 16px` | `marginBottom: 16` | `margin-bottom: 32rpx` |
+| 水平居中 | `Container(alignment: Alignment.center)` | `margin: 0 auto` | `alignSelf: 'center'` | `margin: 0 auto` |
+
+---
+
+## 🎨 颜色
+
+### 纯色
+
+| 设计稿 | Flutter | Vue/CSS | React Native |
+|--------|---------|---------|--------------|
+| #1C2B45 | `Color(0xFF1C2B45)` | `#1C2B45` | `'#1C2B45'` |
+| #1C2B45 50%透明 | `Color(0x801C2B45)` | `rgba(28,43,69,0.5)` | `'rgba(28,43,69,0.5)'` |
+
+### 透明度换算
+
+| 透明度 | 十六进制 | 用法示例 |
+|--------|---------|---------|
+| 100% | FF | `0xFF1C2B45` |
+| 90% | E6 | `0xE61C2B45` |
+| 80% | CC | `0xCC1C2B45` |
+| 70% | B3 | `0xB31C2B45` |
+| 60% | 99 | `0x991C2B45` |
+| 50% | 80 | `0x801C2B45` |
+| 40% | 66 | `0x661C2B45` |
+| 30% | 4D | `0x4D1C2B45` |
+| 20% | 33 | `0x331C2B45` |
+| 15% | 26 | `0x261C2B45` |
+| 12% | 1F | `0x1F1C2B45` |
+| 10% | 1A | `0x1A1C2B45` |
+| 5% | 0D | `0x0D1C2B45` |
+| 0% | 00 | `0x001C2B45` |
+
+### 渐变色
+
+**设计稿**: 从 #E01020 到 #B8101A，左上到右下
+
+```dart
+// Flutter
+LinearGradient(
+  begin: Alignment.topLeft,
+  end: Alignment.bottomRight,
+  colors: [Color(0xFFE01020), Color(0xFFB8101A)],
+)
+```
+
+```css
+/* CSS */
+background: linear-gradient(135deg, #E01020 0%, #B8101A 100%);
+```
+
+```javascript
+// React Native (需要 react-native-linear-gradient)
+<LinearGradient
+  colors={['#E01020', '#B8101A']}
+  start={{x: 0, y: 0}}
+  end={{x: 1, y: 1}}
+/>
+```
+
+```css
+/* 小程序 */
+background: linear-gradient(135deg, #E01020, #B8101A);
+```
+
+---
+
+## 📦 圆角
+
+| 设计稿 | Flutter | Vue/CSS | React Native |
+|--------|---------|---------|--------------|
+| 全部 12px | `borderRadius: BorderRadius.circular(12)` | `border-radius: 12px` | `borderRadius: 12` |
+| 只有顶部 12px | `borderRadius: BorderRadius.vertical(top: Radius.circular(12))` | `border-radius: 12px 12px 0 0` | `borderTopLeftRadius: 12, borderTopRightRadius: 12` |
+| 各角不同 [8,12,16,20] | `borderRadius: BorderRadius.only(topLeft: Radius.circular(8), ...)` | `border-radius: 8px 12px 16px 20px` | 逐角设置 |
+
+---
+
+## 🌑 阴影
+
+### 单一阴影
+
+**设计稿**: x=8, y=8, blur=20, color=#1C2B45 15%
+
+```dart
+// Flutter
+BoxShadow(
+  color: Color(0x261C2B45),  // 15% = 0x26
+  blurRadius: 20,
+  offset: Offset(8, 8),
+  spreadRadius: 0,
+)
+```
+
+```css
+/* CSS */
+box-shadow: 8px 8px 20px 0px rgba(28, 43, 69, 0.15);
+```
+
+```javascript
+// React Native
+shadowColor: '#1C2B45',
+shadowOffset: { width: 8, height: 8 },
+shadowOpacity: 0.15,
+shadowRadius: 20,
+elevation: 8,  // Android
+```
+
+### 新拟态双阴影
+
+**设计稿**: 右下深色 + 左上浅色
+
+```dart
+// Flutter
+boxShadow: [
+  // 右下阴影（深色）
+  BoxShadow(
+    color: Color(0x261C2B45),  // 15%
+    blurRadius: 20,
+    offset: Offset(8, 8),
+  ),
+  // 左上高光（浅色）
+  BoxShadow(
+    color: Color(0xE6FFFFFF),  // 90%
+    blurRadius: 20,
+    offset: Offset(-8, -8),
+  ),
+]
+```
+
+```css
+/* CSS */
+box-shadow: 
+  8px 8px 20px rgba(28, 43, 69, 0.15),
+  -8px -8px 20px rgba(255, 255, 255, 0.9);
+```
+
+---
+
+## ✏️ 字体
+
+### 基础属性
+
+| 设计稿 | Flutter | Vue/CSS | React Native |
+|--------|---------|---------|--------------|
+| 字号 16px | `fontSize: 16` | `font-size: 16px` | `fontSize: 16` |
+| 字重 SemiBold(600) | `fontWeight: FontWeight.w600` | `font-weight: 600` | `fontWeight: '600'` |
+| 字重 Bold(700) | `fontWeight: FontWeight.bold` | `font-weight: bold` | `fontWeight: 'bold'` |
+| 行高 24px (字号16) | `height: 1.5` (比例!) | `line-height: 24px` | `lineHeight: 24` |
+| 字间距 0.5px | `letterSpacing: 0.5` | `letter-spacing: 0.5px` | `letterSpacing: 0.5` |
+
+### 字重映射
+
+| 名称 | 数值 | Flutter | CSS |
+|------|------|---------|-----|
+| Thin | 100 | `FontWeight.w100` | `font-weight: 100` |
+| ExtraLight | 200 | `FontWeight.w200` | `font-weight: 200` |
+| Light | 300 | `FontWeight.w300` | `font-weight: 300` |
+| Regular | 400 | `FontWeight.w400` / `FontWeight.normal` | `font-weight: 400` |
+| Medium | 500 | `FontWeight.w500` | `font-weight: 500` |
+| SemiBold | 600 | `FontWeight.w600` | `font-weight: 600` |
+| Bold | 700 | `FontWeight.w700` / `FontWeight.bold` | `font-weight: 700` |
+| ExtraBold | 800 | `FontWeight.w800` | `font-weight: 800` |
+| Black | 900 | `FontWeight.w900` | `font-weight: 900` |
+
+### ⚠️ Flutter 行高注意
+
+Flutter 的 `TextStyle.height` 是**比例值**，不是像素值！
+
+```dart
+// 设计稿：字号 16px，行高 24px
+TextStyle(
+  fontSize: 16,
+  height: 1.5,  // 24 / 16 = 1.5
+)
+```
+
+---
+
+## 🔲 边框
+
+| 设计稿 | Flutter | Vue/CSS | React Native |
+|--------|---------|---------|--------------|
+| 1px #E5E5E5 实线 | `border: Border.all(color: Color(0xFFE5E5E5), width: 1)` | `border: 1px solid #E5E5E5` | `borderWidth: 1, borderColor: '#E5E5E5'` |
+| 只有底边框 | `border: Border(bottom: BorderSide(...))` | `border-bottom: 1px solid #E5E5E5` | `borderBottomWidth: 1, ...` |
+
+---
+
+## 📱 单位换算
+
+### 小程序 rpx
+
+小程序设计稿通常基于 750px 宽度：
+
+```
+rpx = px * 2
+
+设计稿 16px → 小程序 32rpx
+设计稿 100px → 小程序 200rpx
+```
+
+### React Native
+
+React Native 使用逻辑像素（dp/pt），通常与设计稿 1:1：
+
+```javascript
+// 设计稿 16px
+style={{ fontSize: 16 }}
+```
+
+如需适配，使用 `PixelRatio` 或响应式方案。
+
+---
+
+## 📚 相关规范
+
+- [设计稿还原规范](./workflows/design-restoration.md)
+- [Sketch MCP 最佳实践](./mcp-tools/sketch-mcp.md)
+
+---
+
+**维护者**: MTA工作室  
+**创建日期**: 2026-01-20  
+**适用版本**: 通用

package/standards/workflows/design-restoration.md

@@ -0,0 +1,401 @@
+# 设计稿还原规范 (Design Restoration Standard)
+
+> 通用规范 - 适用于所有视觉化开发场景（跨平台/前端/全栈）
+
+## 📋 概述
+
+本规范定义了从设计工具（Sketch、Figma、Adobe XD 等）还原 UI 到代码的标准流程和注意事项，确保在不同框架（Flutter、Vue、React、小程序等）中都能准确还原设计稿。
+
+**适用场景**：
+- 使用 Sketch MCP、Figma MCP 等工具测量设计稿
+- 根据设计图片手动还原 UI
+- 跨平台/多框架项目的样式统一
+
+---
+
+## 🎯 核心原则
+
+### 1. 测量优先级
+
+按以下优先级获取设计参数：
+
+1. **MCP 工具直接读取** - 最准确，但需注意 API 陷阱
+2. **设计工具检查器** - 设计师侧边栏的属性面板
+3. **标注插件导出** - 如 Sketch Measure、Zeplin
+4. **肉眼估算** - 最后手段，需反复对比验证
+
+### 2. 验证闭环
+
+```
+测量 → 编码 → 截图对比 → 微调 → 确认
+```
+
+每个元素都必须完成这个闭环。
+
+### 3. 原子化记录
+
+将设计参数按类别记录，便于复用和维护。
+
+---
+
+## 📐 测量要素清单
+
+### 必须测量的参数
+
+| 类别 | 参数 | 说明 |
+|------|------|------|
+| **尺寸** | width, height | 精确到像素 |
+| **位置** | x, y, margin, padding | 相对于父容器 |
+| **颜色** | 填充色、边框色、阴影色 | ⚠️ 注意渐变 |
+| **圆角** | borderRadius | 四角可能不同 |
+| **字体** | family, size, weight, height | 行高很重要 |
+| **阴影** | color, blur, offset, spread | 多重阴影 |
+| **边框** | color, width, style | 虚线/实线 |
+
+### ⚠️ 常见陷阱
+
+#### 1. 渐变色读取错误
+
+**问题**：API 返回渐变的"代表色"而非实际渐变定义
+
+```javascript
+// ❌ 错误方式
+layer.style.fills[0].color  // 返回错误的单色
+
+// ✅ 正确方式
+if (fill.fillType === 'Gradient') {
+  fill.gradient.stops.map(s => s.color)  // 获取所有色标
+}
+```
+
+#### 2. 透明度丢失
+
+**问题**：颜色值可能不包含透明度信息
+
+```javascript
+// 确保读取完整的 RGBA
+color: "#1C2B4580"  // 包含透明度
+// 而不是
+color: "#1C2B45"    // 丢失透明度
+```
+
+#### 3. 字体权重映射
+
+设计稿中的字重名称需要映射为数值：
+
+| 设计稿名称 | PostScript 后缀 | 数值 | Flutter | CSS |
+|-----------|----------------|------|---------|-----|
+| Thin | -Thin | 100 | FontWeight.w100 | font-weight: 100 |
+| Ultralight | -Ultralight | 200 | FontWeight.w200 | font-weight: 200 |
+| Light | -Light | 300 | FontWeight.w300 | font-weight: 300 |
+| Regular | -Regular | 400 | FontWeight.w400 | font-weight: 400 |
+| Medium | -Medium | 500 | FontWeight.w500 | font-weight: 500 |
+| SemiBold | -Semibold | 600 | FontWeight.w600 | font-weight: 600 |
+| Bold | -Bold | 700 | FontWeight.w700 | font-weight: 700 |
+| Heavy/ExtraBold | -Heavy | 800 | FontWeight.w800 | font-weight: 800 |
+| Black | -Black | 900 | FontWeight.w900 | font-weight: 900 |
+
+> ⚠️ **重要**：Sketch API 的 `fontWeight` 属性返回的数值（如 8）不可靠！必须通过 `sketchObject.font().fontName()` 获取真实的 PostScript 字体名称（如 `PingFangSC-Semibold`），然后根据后缀映射。
+
+#### 4. 图标必须从设计稿导出
+
+**绝对禁止**：AI 自己生成图标 SVG
+
+**正确做法**：使用设计工具 API 导出设计稿中的图标
+
+```javascript
+// Sketch 导出示例
+const buffer = sketch.export(iconLayer, {
+  formats: 'svg',
+  output: false,
+  scales: '1'
+});
+const svgString = buffer.toString('utf-8');
+```
+
+**原因**：
+- 设计师精心调整过图标的线条粗细、比例、细节
+- AI 生成的图标风格可能与设计稿不一致
+- 图标是品牌视觉的重要组成部分
+
+#### 5. 列表间距必须逐个测量
+
+**问题**：同一列表中的元素间距可能不完全一致
+
+**正确做法**：测量每对相邻元素的间距，取多数值或与设计师确认
+
+```javascript
+// 间距计算公式
+spacing = nextElement.y - (currentElement.y + currentElement.height)
+```
+
+#### 6. 行高计算差异
+
+不同框架对行高的处理不同：
+
+```
+设计稿行高: 24px, 字号: 16px
+
+Flutter: height = 24 / 16 = 1.5 (比例值)
+CSS: line-height: 24px 或 line-height: 1.5
+小程序: line-height: 24px
+```
+
+---
+
+## 🎨 颜色规范
+
+### 颜色提取完整流程
+
+```javascript
+function extractColor(fill) {
+  if (!fill || !fill.enabled) return null;
+  
+  switch (fill.fillType) {
+    case 'Color':
+      return { type: 'solid', color: fill.color };
+    
+    case 'Gradient':
+      return {
+        type: 'gradient',
+        gradientType: fill.gradient.gradientType,  // Linear/Radial/Angular
+        direction: {
+          from: fill.gradient.from,  // { x: 0, y: 0 }
+          to: fill.gradient.to       // { x: 1, y: 1 }
+        },
+        stops: fill.gradient.stops.map(s => ({
+          position: s.position,  // 0 ~ 1
+          color: s.color
+        }))
+      };
+    
+    case 'Pattern':
+      return { type: 'pattern', image: fill.pattern?.image };
+    
+    default:
+      return null;
+  }
+}
+```
+
+### 渐变方向映射
+
+| 设计稿方向 | Flutter | CSS |
+|-----------|---------|-----|
+| 左上→右下 | Alignment.topLeft → bottomRight | to bottom right |
+| 上→下 | Alignment.topCenter → bottomCenter | to bottom |
+| 左→右 | Alignment.centerLeft → centerRight | to right |
+
+### 颜色透明度表示
+
+```dart
+// Flutter - 使用 0x 前缀
+Color(0x801C2B45)  // 50% 透明度
+
+// CSS - 使用 rgba 或 8位十六进制
+rgba(28, 43, 69, 0.5)
+#1C2B4580
+
+// 小程序 - 同 CSS
+```
+
+---
+
+## 📦 框架语法映射
+
+### 容器/盒模型
+
+| 属性 | Flutter | Vue/CSS | React Native | 小程序 |
+|------|---------|---------|--------------|--------|
+| 宽度 | `width: 100` | `width: 100px` | `width: 100` | `width: 100rpx` |
+| 高度 | `height: 100` | `height: 100px` | `height: 100` | `height: 100rpx` |
+| 内边距 | `padding: EdgeInsets.all(16)` | `padding: 16px` | `padding: 16` | `padding: 32rpx` |
+| 外边距 | `margin: EdgeInsets.only(top: 8)` | `margin-top: 8px` | `marginTop: 8` | `margin-top: 16rpx` |
+| 圆角 | `borderRadius: BorderRadius.circular(12)` | `border-radius: 12px` | `borderRadius: 12` | `border-radius: 24rpx` |
+
+### 颜色
+
+| 场景 | Flutter | Vue/CSS | React Native |
+|------|---------|---------|--------------|
+| 纯色 | `Color(0xFF1C2B45)` | `#1C2B45` | `'#1C2B45'` |
+| 透明色 | `Color(0x801C2B45)` | `rgba(28,43,69,0.5)` | `'rgba(28,43,69,0.5)'` |
+| 渐变 | `LinearGradient(colors: [...])` | `linear-gradient(...)` | `LinearGradient` |
+
+### 阴影
+
+```dart
+// Flutter
+BoxShadow(
+  color: Color(0x261C2B45),
+  blurRadius: 20,
+  offset: Offset(8, 8),
+  spreadRadius: 0,
+)
+```
+
+```css
+/* CSS */
+box-shadow: 8px 8px 20px 0px rgba(28, 43, 69, 0.15);
+```
+
+```javascript
+// React Native
+shadowColor: '#1C2B45',
+shadowOffset: { width: 8, height: 8 },
+shadowOpacity: 0.15,
+shadowRadius: 20,
+elevation: 8,  // Android
+```
+
+### 字体
+
+| 属性 | Flutter | CSS | React Native |
+|------|---------|-----|--------------|
+| 字号 | `fontSize: 16` | `font-size: 16px` | `fontSize: 16` |
+| 字重 | `fontWeight: FontWeight.w600` | `font-weight: 600` | `fontWeight: '600'` |
+| 行高 | `height: 1.5` (比例) | `line-height: 24px` | `lineHeight: 24` |
+| 颜色 | `color: Color(0xFF1C2B45)` | `color: #1C2B45` | `color: '#1C2B45'` |
+
+---
+
+## 🔧 MCP 工具使用规范
+
+### Sketch MCP
+
+#### 正确的测量脚本模板
+
+```javascript
+const sketch = require('sketch');
+const doc = sketch.getSelectedDocument();
+const artboard = doc.selectedLayers.layers[0];
+
+function measureLayer(layer) {
+  const result = {
+    name: layer.name,
+    type: layer.type,
+    frame: {
+      x: Math.round(layer.frame.x),
+      y: Math.round(layer.frame.y),
+      width: Math.round(layer.frame.width),
+      height: Math.round(layer.frame.height),
+    },
+  };
+  
+  // 样式
+  if (layer.style) {
+    // 填充色 - 正确处理渐变
+    if (layer.style.fills?.length > 0) {
+      result.fills = layer.style.fills
+        .filter(f => f.enabled)
+        .map(f => extractColor(f));
+    }
+    
+    // 边框
+    if (layer.style.borders?.length > 0) {
+      result.borders = layer.style.borders
+        .filter(b => b.enabled)
+        .map(b => ({
+          color: b.color,
+          thickness: b.thickness,
+        }));
+    }
+    
+    // 阴影
+    if (layer.style.shadows?.length > 0) {
+      result.shadows = layer.style.shadows
+        .filter(s => s.enabled)
+        .map(s => ({
+          color: s.color,
+          blur: s.blur,
+          x: s.x,
+          y: s.y,
+          spread: s.spread,
+        }));
+    }
+    
+    // 圆角
+    if (layer.style.corners) {
+      result.cornerRadius = layer.style.corners.radii;
+    }
+  }
+  
+  // 文字特有属性
+  if (layer.type === 'Text') {
+    result.text = {
+      content: layer.text,
+      fontSize: layer.style.fontSize,
+      fontFamily: layer.style.fontFamily,
+      fontWeight: layer.style.fontWeight,
+      textColor: layer.style.textColor,
+      alignment: layer.style.alignment,
+      lineHeight: layer.style.lineHeight,
+    };
+  }
+  
+  return result;
+}
+```
+
+### Figma MCP（预留）
+
+```javascript
+// Figma API 颜色读取
+function getFigmaColor(paint) {
+  if (paint.type === 'SOLID') {
+    return {
+      type: 'solid',
+      color: rgbaToHex(paint.color, paint.opacity),
+    };
+  } else if (paint.type === 'GRADIENT_LINEAR') {
+    return {
+      type: 'gradient',
+      stops: paint.gradientStops.map(s => ({
+        position: s.position,
+        color: rgbaToHex(s.color),
+      })),
+    };
+  }
+}
+```
+
+---
+
+## ✅ 还原检查清单
+
+### 每个元素必查
+
+- [ ] 尺寸是否精确匹配
+- [ ] 位置/间距是否正确
+- [ ] 颜色是否正确（特别注意渐变）
+- [ ] 圆角是否正确
+- [ ] 阴影效果是否还原
+- [ ] 字体样式是否匹配
+
+### 整体验收
+
+- [ ] 与设计稿截图叠加对比
+- [ ] 不同屏幕尺寸下的适配
+- [ ] 交互状态（hover、active、disabled）
+- [ ] 暗黑模式（如有）
+
+---
+
+## 📚 相关规范
+
+- [Sketch MCP 最佳实践](./mcp-tools/sketch-mcp.md)
+- [Figma MCP 最佳实践](./mcp-tools/figma-mcp.md)（计划中）
+- [颜色系统规范](./color-system.md)（计划中）
+
+---
+
+## 🔄 版本历史
+
+| 版本 | 日期 | 更新内容 |
+|------|------|---------|
+| v1.0 | 2026-01-20 | 初始版本，包含渐变色读取问题解决方案 |
+| v1.1 | 2026-01-21 | 新增：字重映射完整表（含PostScript后缀）、图标导出强制要求、列表间距测量规范 |
+
+---
+
+**维护者**: MTA工作室  
+**创建日期**: 2026-01-20

package/templates/README.md

@@ -70,6 +70,11 @@ templates/
 │   ├── api-layer/
 │   └── themes/
 ├── react/                    # React 项目模板（预留）
+├── design-measurement/       # 设计稿测量模板 ✅ 新增
+│   ├── README.md             # 使用指南
+│   ├── component-measurement.js  # 组件测量
+│   ├── style-extraction.js   # 样式提取
+│   └── gap-measurement.js    # 间距测量
 └── common/                   # 跨框架通用模板
     └── types/                # TypeScript 类型定义 ✅
 ```
@@ -108,6 +113,15 @@ templates/
 |------|--------|------|------|
 | `common/types` | types, 类型 | TypeScript 通用类型 | ✅ 可用 |
 
+### 设计稿测量模板 🆕
+
+| 模板 | 关键词 | 说明 | 状态 |
+|------|--------|------|------|
+| `design-measurement` | 测量, measure | 设计稿测量脚本合集 | ✅ 可用 |
+| `component-measurement.js` | 组件, 边距 | 组件尺寸+相对边距 | ✅ 可用 |
+| `style-extraction.js` | 样式, 渐变, 阴影 | 完整样式提取 | ✅ 可用 |
+| `gap-measurement.js` | 间距, gap | 同级元素间距 | ✅ 可用 |
+
 ---
 
 ## 🔧 模板规范