@routerhub/agent-rules 1.5.84 → 1.5.85

package/AGENTS.base.md

@@ -336,6 +336,37 @@ Closes #456
 - Figma 中配置或表达的跳转、链接、页面流、弹窗、hover/click 等交互必须同步实现；原型未明确但影响流程闭环的交互，需先核对现有产品或询问用户，禁止自行脑补。
 - 交付前必须对照 Figma 做视觉和交互验收，发现无法完全还原的素材、字体、数据或平台限制时，必须明确说明差异和原因。
 
+### Figma 设计还原规范（MCP 三步验证法）
+
+⚠️ Figma 设计还原时，**禁止直接使用 `get_design_context` 生成的 Tailwind 代码**。`get_design_context` 的代码是大模型推导的近似值，数值（px、间距、尺寸）、布局结构（flex 方向、嵌套关系）和定位方式（absolute/flex）都可能与 Figma 真实设计不符，必须通过以下三步验证：
+
+**第 1 步：`get_design_context` → 获取设计意图**
+- 用 `get_design_context` 了解组件的整体结构、颜色、字体、视觉效果
+- ⚠️ 仅用于理解设计意图，**数值和结构不可信**
+
+**第 2 步：`get_metadata` → 获取精确坐标（唯一事实源）**
+- `get_metadata` 返回的是 Figma 内部每个节点的**真实 x/y/width/height 坐标**，这是所有尺寸、间距、定位的唯一事实源
+- 用 metadata 坐标反推间距：section 内子元素 y 坐标 = section 的 top padding，子元素高度 + 上边距 + 下边距 = 父级高度
+- 用 metadata 验证布局结构：同级兄弟节点的 x/y 关系决定它们是横向还是纵向排列，子节点 x 坐标决定它是 flex 子元素还是 absolute 定位
+
+**第 3 步：`get_metadata` 坐标反推规则**
+
+| 场景 | 反推方法 |
+|------|----------|
+| Section 上下 padding | 子元素 y 坐标 = 上 padding；父级高度 - 子元素 y - 子元素高度 = 下 padding |
+| 元素间距（gap） | 兄弟元素之间的 y 差值（纵向）或 x 差值（横向） |
+| 元素是 flex 还是 absolute | 子元素 x 超出父元素左边界 → absolute；子元素在父元素范围内 → flex |
+| 固定宽度还是自适应 | metadata 有明确 width 值 → 固定宽度；否则 → 自适应 |
+| 元素是否有旋转/变换 | `get_design_context` 中有 `rotate`、`-translate-` 等类名 |
+
+**常见踩坑清单：**
+
+1. **`get_design_context` 生成的 padding 不准** → 必须以 metadata 坐标为基准重新计算
+2. **按钮被嵌套在文字 `flex-col` 内部** → metadata 中同级 x 坐标不同、y 坐标相近 = 横向并排，不应嵌套
+3. **固定宽度容器被改成了全宽** → metadata 中有明确 width 的容器不能去掉固定宽度
+4. **装饰图片被当成 flex 子元素** → metadata 中 x 坐标超出父元素范围 = absolute 定位
+5. **`justify-between` + 全宽把元素推到极端两端** → 必须先确认 metadata 中内容行的宽度
+
 ## 文件约束
 
 - 不随意修改核心业务文件和 API 相关代码，不编写或修改 `README.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.84",
+  "version": "1.5.85",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/frontend.md

@@ -10,6 +10,37 @@ outputName: "frontend"
 - Figma 中配置或表达的跳转、链接、页面流、弹窗、hover/click 等交互必须同步实现；原型未明确但影响流程闭环的交互，需先核对现有产品或询问用户，禁止自行脑补。
 - 交付前必须对照 Figma 做视觉和交互验收，发现无法完全还原的素材、字体、数据或平台限制时，必须明确说明差异和原因。
 
+### Figma 设计还原规范（MCP 三步验证法）
+
+⚠️ Figma 设计还原时，**禁止直接使用 `get_design_context` 生成的 Tailwind 代码**。`get_design_context` 的代码是大模型推导的近似值，数值（px、间距、尺寸）、布局结构（flex 方向、嵌套关系）和定位方式（absolute/flex）都可能与 Figma 真实设计不符，必须通过以下三步验证：
+
+**第 1 步：`get_design_context` → 获取设计意图**
+- 用 `get_design_context` 了解组件的整体结构、颜色、字体、视觉效果
+- ⚠️ 仅用于理解设计意图，**数值和结构不可信**
+
+**第 2 步：`get_metadata` → 获取精确坐标（唯一事实源）**
+- `get_metadata` 返回的是 Figma 内部每个节点的**真实 x/y/width/height 坐标**，这是所有尺寸、间距、定位的唯一事实源
+- 用 metadata 坐标反推间距：section 内子元素 y 坐标 = section 的 top padding，子元素高度 + 上边距 + 下边距 = 父级高度
+- 用 metadata 验证布局结构：同级兄弟节点的 x/y 关系决定它们是横向还是纵向排列，子节点 x 坐标决定它是 flex 子元素还是 absolute 定位
+
+**第 3 步：`get_metadata` 坐标反推规则**
+
+| 场景 | 反推方法 |
+|------|----------|
+| Section 上下 padding | 子元素 y 坐标 = 上 padding；父级高度 - 子元素 y - 子元素高度 = 下 padding |
+| 元素间距（gap） | 兄弟元素之间的 y 差值（纵向）或 x 差值（横向） |
+| 元素是 flex 还是 absolute | 子元素 x 超出父元素左边界 → absolute；子元素在父元素范围内 → flex |
+| 固定宽度还是自适应 | metadata 有明确 width 值 → 固定宽度；否则 → 自适应 |
+| 元素是否有旋转/变换 | `get_design_context` 中有 `rotate`、`-translate-` 等类名 |
+
+**常见踩坑清单：**
+
+1. **`get_design_context` 生成的 padding 不准** → 必须以 metadata 坐标为基准重新计算
+2. **按钮被嵌套在文字 `flex-col` 内部** → metadata 中同级 x 坐标不同、y 坐标相近 = 横向并排，不应嵌套
+3. **固定宽度容器被改成了全宽** → metadata 中有明确 width 的容器不能去掉固定宽度
+4. **装饰图片被当成 flex 子元素** → metadata 中 x 坐标超出父元素范围 = absolute 定位
+5. **`justify-between` + 全宽把元素推到极端两端** → 必须先确认 metadata 中内容行的宽度
+
 ## 文件约束
 
 - 不随意修改核心业务文件和 API 相关代码，不编写或修改 `README.md`。