# Figma API Quirks — Reference Table

> Figma Plugin API 边角 quirk 汇总。**Path A（Figma mockup）专用**。
> 这些是工具 quirk，不是设计规则——违反不等于设计错误，但忽略会导致实现 bug。
>
> 设计规则 → [`../design-process.md`](../design-process.md) + [`../domain-tvu.md`](../domain-tvu.md)
> 详细版本（含完整 code snippet）→ [`../figma-technical-reference.md`](../figma-technical-reference.md)
>
> 来源：mockup-conventions.md 原 M17-M20（2026-05-12 重构迁入）

---

| # | Quirk | 规则 | 实证 |
|---|---|---|---|
| **Q1** | 1px 节点无法凭几何判视觉性质 | 看到 `height=1` 或 `width=1` → 必须 probe `.fills`；有 fill = visible divider，无 fill = transparent spacer | mockup `2956:4746`（1090×1）当 divider 抄入，实际是 spacer → 标题横线穿越 |
| **Q2** | `setBoundVariableForPaint` 返回 paint opacity 默认 1 | 绑 Color Variable 与设 opacity **必须分两步**（先 bind，再 fresh fills mutation 设 opacity）| Session 4 次 opacity 失效（State Pill / Badge / Pipeline chip / Auto-refresh）|
| **Q3** | Instance 被 set 过字段后 master 改动不 propagate | master 改 fills/opacity 等字段后，必须脚本**扫所有 instance force-sync** | Clone 后 instance style 静默 stick，master 改动不生效 |
| **Q4** | 全 FIXED 或全 FILL 一刀切会导致布局错误 | 每列按内容类型独立判断：真定长 → FIXED；真变长 → FILL + truncation；responsive-display → FILL + textAutoResize=TRUNCATE | 3 轮列宽迭代（全 FILL grow=2/1/1 → grow=1 → 混合）才到位 |

---

详细 code snippet 见 [`../figma-technical-reference.md`](../figma-technical-reference.md)。