@nick848/fet 1.1.12 → 1.1.13

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 import {
   FetError,
   toFetError
-} from "../chunk-J5WB4KAL.js";
+} from "../chunk-YKRUVIJ6.js";
 
 // src/cli/index.ts
 import { createInterface as createInterface3 } from "readline/promises";
@@ -2080,7 +2080,13 @@ function renderFetConfig(scan, language = "zh-CN") {
       figmaGuard: {
         enabled: true,
         mode: "require_before_ui",
-        onUncertainty: "stop_and_ask"
+        onUncertainty: "stop_and_ask",
+        sync: {
+          enabled: true,
+          apiKeyEnv: "FIGMA_ACCESS_TOKEN",
+          inlineImageMaxBytes: 32768,
+          requireBeforeUi: true
+        }
       },
       uiDisplayContract: {
         enabled: true
@@ -2530,17 +2536,27 @@ function figmaStopHandoffRelativePath(changeId) {
 function figmaApplyInstructionsRelativePath(changeId) {
   return `openspec/changes/${changeId}/.fet/figma-apply-instructions.md`;
 }
+function figmaDesignManifestRelativePath(changeId) {
+  return `openspec/changes/${changeId}/.fet/figma-design-manifest.yaml`;
+}
+function figmaSyncInstructionsRelativePath(changeId) {
+  return `openspec/changes/${changeId}/.fet/figma-sync-instructions.md`;
+}
 function renderFigmaRequireBeforeUiBody(language, changeId) {
   const stopPath = figmaStopHandoffRelativePath(changeId);
+  const syncPath = figmaSyncInstructionsRelativePath(changeId);
+  const manifestPath3 = figmaDesignManifestRelativePath(changeId);
   if (language === "en") {
     return `## Mandatory before any UI implementation
 
 Complete these steps **before** writing or editing UI code (components, pages, styles, layout):
 
-1. Read \`${stopPath}\` for detected Figma links and stop rules.
-2. Use **Figma MCP/API** (or an approved Figma tool) to read every linked frame/node referenced by this change.
-3. In your reply, briefly list design facts you confirmed from Figma (frames, colors, typography, spacing, components, states).
-4. Only then implement UI tasks from \`tasks.md\`.
+1. Run \`fet figma sync --change ${changeId}\` (requires \`FIGMA_ACCESS_TOKEN\` or \`--token\`) so FET downloads **all nodes** and **image assets** into \`.fet/figma-assets/\`.
+2. Read \`${syncPath}\`, \`${manifestPath3}\`, and \`figma-nodes.json\` in the same folder\u2014use on-disk asset paths for backgrounds and large images (not base64 in source).
+3. Read \`${stopPath}\` for detected Figma links and stop rules.
+4. If sync is impossible, use **Figma MCP/API** to read every linked frame/node; do not skip image fills or exportable layers.
+5. In your reply, briefly list design facts you confirmed (frames, colors, typography, spacing, components, states, asset paths).
+6. Only then implement UI tasks from \`tasks.md\`.
 
 ## Forbidden
 
@@ -2556,10 +2572,12 @@ Follow the stop rules in \`${stopPath}\`. Pause implementation, explain what fai
 
 \u5728\u7F16\u5199\u6216\u4FEE\u6539 UI \u4EE3\u7801\uFF08\u7EC4\u4EF6\u3001\u9875\u9762\u3001\u6837\u5F0F\u3001\u5E03\u5C40\uFF09**\u4E4B\u524D**\uFF0C\u6309\u987A\u5E8F\u5B8C\u6210\uFF1A
 
-1. \u9605\u8BFB \`${stopPath}\` \u4E2D\u7684 Figma \u94FE\u63A5\u4E0E\u505C\u6B62\u89C4\u5219\u3002
-2. \u4F7F\u7528 **Figma MCP/API**\uFF08\u6216\u5DF2\u914D\u7F6E\u7684 Figma \u5DE5\u5177\uFF09\u8BFB\u53D6\u672C change \u5F15\u7528\u7684\u6BCF\u4E2A\u753B\u677F/\u8282\u70B9\u3002
-3. \u5728\u56DE\u590D\u4E2D\u7B80\u8981\u5217\u51FA\u5DF2\u4ECE Figma \u786E\u8BA4\u7684\u8BBE\u8BA1\u4E8B\u5B9E\uFF08\u753B\u677F\u3001\u989C\u8272\u3001\u5B57\u53F7\u3001\u95F4\u8DDD\u3001\u7EC4\u4EF6\u3001\u72B6\u6001\u7B49\uFF09\u3002
-4. \u5B8C\u6210\u4EE5\u4E0A\u6B65\u9AA4\u540E\uFF0C\u518D\u6309 \`tasks.md\` \u5B9E\u65BD UI \u4EFB\u52A1\u3002
+1. \u6267\u884C \`fet figma sync --change ${changeId}\`\uFF08\u9700 \`FIGMA_ACCESS_TOKEN\` \u6216 \`--token\`\uFF09\uFF0C\u7531 FET \u62C9\u53D6**\u5168\u90E8\u8282\u70B9**\u5E76\u5C06\u56FE\u7247\u7D20\u6750\u843D\u76D8\u5230 \`.fet/figma-assets/\`\u3002
+2. \u9605\u8BFB\u540C\u76EE\u5F55 \`${syncPath}\`\u3001\`${manifestPath3}\`\u3001\`figma-nodes.json\`\uFF1B\u5927\u56FE\u7528\u6587\u4EF6\u8DEF\u5F84\u5F15\u7528\uFF0C\u7981\u6B62\u5728\u6E90\u7801\u4E2D\u5185\u8054\u5927\u4F53\u79EF base64\u3002
+3. \u9605\u8BFB \`${stopPath}\` \u4E2D\u7684 Figma \u94FE\u63A5\u4E0E\u505C\u6B62\u89C4\u5219\u3002
+4. \u82E5\u65E0\u6CD5 sync\uFF0C\u5219\u7528 **Figma MCP/API** \u8BFB\u53D6\u6BCF\u4E2A\u753B\u677F/\u8282\u70B9\uFF0C\u4E0D\u5F97\u9057\u6F0F\u56FE\u7247\u586B\u5145\u4E0E\u53EF\u5BFC\u51FA\u56FE\u5C42\u3002
+5. \u5728\u56DE\u590D\u4E2D\u7B80\u8981\u5217\u51FA\u5DF2\u786E\u8BA4\u7684\u8BBE\u8BA1\u4E8B\u5B9E\uFF08\u753B\u677F\u3001\u989C\u8272\u3001\u5B57\u53F7\u3001\u95F4\u8DDD\u3001\u7EC4\u4EF6\u3001\u72B6\u6001\u3001\u7D20\u6750\u8DEF\u5F84\uFF09\u3002
+6. \u5B8C\u6210\u4EE5\u4E0A\u6B65\u9AA4\u540E\uFF0C\u518D\u6309 \`tasks.md\` \u5B9E\u65BD UI \u4EFB\u52A1\u3002
 
 ## \u7981\u6B62
 
@@ -2702,16 +2720,21 @@ function renderFigmaStopNextStep(changeId, language) {
   const path = figmaStopHandoffRelativePath(changeId);
   return language === "en" ? `Before UI implementation, read ${path}. If Figma access fails or design details are unclear, stop and ask the user\u2014do not guess styles.` : `\u5B9E\u65BD UI \u524D\u9605\u8BFB ${path}\u3002Figma \u8BBF\u95EE\u5931\u8D25\u6216\u8BBE\u8BA1\u7EC6\u8282\u4E0D\u660E\u786E\u65F6\u7ACB\u5373\u505C\u6B62\u5E76\u5411\u7528\u6237\u63D0\u95EE\uFF0C\u4E0D\u8981\u731C\u6D4B\u6837\u5F0F\u3002`;
 }
-function renderFigmaApplyNextSteps(changeId, language, mode) {
+function renderFigmaApplyNextSteps(changeId, language, mode, options) {
   const applyPath = figmaApplyInstructionsRelativePath(changeId);
   const stopPath = figmaStopHandoffRelativePath(changeId);
+  const syncPath = figmaSyncInstructionsRelativePath(changeId);
+  const apiKeyEnv = options?.apiKeyEnv ?? "FIGMA_ACCESS_TOKEN";
   if (mode === "require_before_ui") {
+    const syncStep = options?.syncDone === true ? language === "en" ? `Figma design data is synced. Read ${syncPath} and figma-design-manifest.yaml before UI work.` : `Figma \u8BBE\u8BA1\u6570\u636E\u5DF2\u540C\u6B65\u3002\u5B9E\u65BD UI \u524D\u9605\u8BFB ${syncPath} \u4E0E figma-design-manifest.yaml\u3002` : options?.syncMissingToken ? language === "en" ? `Run fet figma sync --change ${changeId} with ${apiKeyEnv} set to fetch all nodes and assets before UI work.` : `\u5B9E\u65BD UI \u524D\u6267\u884C fet figma sync --change ${changeId}\uFF08\u914D\u7F6E ${apiKeyEnv}\uFF09\uFF0C\u62C9\u53D6\u5168\u90E8\u8282\u70B9\u4E0E\u7D20\u6750\u3002` : language === "en" ? `Run fet figma sync --change ${changeId} if not already synced; then read ${syncPath}.` : `\u82E5\u5C1A\u672A\u540C\u6B65\uFF0C\u6267\u884C fet figma sync --change ${changeId}\uFF0C\u5E76\u9605\u8BFB ${syncPath}\u3002`;
     return language === "en" ? [
-      `Before any UI task: read and follow ${applyPath} (mandatory). Use Figma MCP/API for every linked frame\u2014do not invent styles.`,
+      syncStep,
+      `Before any UI task: read and follow ${applyPath} (mandatory). Use synced assets and node tree\u2014do not invent styles.`,
       `If Figma access fails or design details are unclear, stop per ${stopPath} and ask the user before continuing.`,
       `After Figma is confirmed, read openspec/changes/${changeId}/tasks.md and implement pending tasks.`
     ] : [
-      `\u5B9E\u65BD\u4EFB\u4F55 UI \u4EFB\u52A1\u524D\uFF1A\u5FC5\u987B\u9605\u8BFB\u5E76\u9075\u5B88 ${applyPath}\uFF1B\u7528 Figma MCP/API \u8BFB\u53D6\u6BCF\u4E2A\u94FE\u63A5\u7684\u753B\u677F\uFF0C\u7981\u6B62\u81EA\u521B\u6837\u5F0F\u3002`,
+      syncStep,
+      `\u5B9E\u65BD\u4EFB\u4F55 UI \u4EFB\u52A1\u524D\uFF1A\u5FC5\u987B\u9605\u8BFB\u5E76\u9075\u5B88 ${applyPath}\uFF1B\u4F7F\u7528\u5DF2\u540C\u6B65\u7684\u8282\u70B9\u6811\u4E0E\u7D20\u6750\u8DEF\u5F84\uFF0C\u7981\u6B62\u81EA\u521B\u6837\u5F0F\u3002`,
       `Figma \u8BBF\u95EE\u5931\u8D25\u6216\u8BBE\u8BA1\u7EC6\u8282\u4E0D\u6E05\uFF1A\u6309 ${stopPath} \u7ACB\u5373\u505C\u6B62\u5E76\u5411\u7528\u6237\u63D0\u95EE\uFF0C\u786E\u8BA4\u540E\u518D\u7EE7\u7EED\u3002`,
       `\u8BBE\u8BA1\u786E\u8BA4\u540E\uFF0C\u518D\u9605\u8BFB openspec/changes/${changeId}/tasks.md \u5E76\u5B9E\u65BD\u5F85\u529E\u4EFB\u52A1\u3002`
     ];
@@ -3545,8 +3568,8 @@ async function exists4(path) {
 }
 
 // src/commands/proxy.ts
-import { readFile as readFile17 } from "fs/promises";
-import { join as join22 } from "path";
+import { readFile as readFile19 } from "fs/promises";
+import { join as join26 } from "path";
 
 // src/figma-guard.ts
 import { readdir as readdir3, readFile as readFile10, stat as stat7 } from "fs/promises";
@@ -3701,11 +3724,757 @@ async function readOptional3(path) {
   }
 }
 
+// src/figma/config.ts
+import { readFile as readFile11 } from "fs/promises";
+import { join as join17 } from "path";
+import { parseDocument as parseDocument3 } from "yaml";
+var DEFAULT_FIGMA_SYNC_CONFIG = {
+  enabled: true,
+  apiKeyEnv: "FIGMA_ACCESS_TOKEN",
+  inlineImageMaxBytes: 32768,
+  requireBeforeUi: true
+};
+async function loadFigmaSyncConfig(projectRoot) {
+  try {
+    const raw = await readFile11(join17(projectRoot, "openspec", "config.yaml"), "utf8");
+    const doc = parseDocument3(raw);
+    const fetNode = doc.get("fet", true);
+    const guardNode = fetNode?.get?.("figmaGuard");
+    const syncNode = guardNode?.get?.("sync");
+    if (!syncNode || typeof syncNode.get !== "function") {
+      return DEFAULT_FIGMA_SYNC_CONFIG;
+    }
+    const enabled = syncNode.get("enabled");
+    const apiKeyEnv = syncNode.get("apiKeyEnv");
+    const inlineImageMaxBytes = syncNode.get("inlineImageMaxBytes");
+    const requireBeforeUi = syncNode.get("requireBeforeUi");
+    return {
+      enabled: enabled === void 0 ? true : Boolean(enabled),
+      apiKeyEnv: typeof apiKeyEnv === "string" && apiKeyEnv.trim() ? apiKeyEnv.trim() : DEFAULT_FIGMA_SYNC_CONFIG.apiKeyEnv,
+      inlineImageMaxBytes: typeof inlineImageMaxBytes === "number" && inlineImageMaxBytes > 0 ? inlineImageMaxBytes : DEFAULT_FIGMA_SYNC_CONFIG.inlineImageMaxBytes,
+      requireBeforeUi: requireBeforeUi === void 0 ? true : Boolean(requireBeforeUi)
+    };
+  } catch {
+    return DEFAULT_FIGMA_SYNC_CONFIG;
+  }
+}
+function resolveFigmaAccessToken(config, explicitToken) {
+  if (explicitToken?.trim()) {
+    return explicitToken.trim();
+  }
+  const fromEnv = process.env[config.apiKeyEnv];
+  return fromEnv?.trim() ? fromEnv.trim() : null;
+}
+
+// src/figma/sync.ts
+import { mkdir as mkdir7, writeFile as writeFile2 } from "fs/promises";
+import { join as join21 } from "path";
+
+// src/tdd/fingerprint.ts
+import { createHash } from "crypto";
+import { readdir as readdir4, readFile as readFile12, stat as stat8 } from "fs/promises";
+import { join as join18, relative as relative3 } from "path";
+async function collectPlanningSources(projectRoot, changeId) {
+  const changeRoot = join18(projectRoot, "openspec", "changes", changeId);
+  const sources = [];
+  const rootFiles = ["proposal.md", "tasks.md", "design.md"];
+  for (const name of rootFiles) {
+    const path = join18(changeRoot, name);
+    if (await exists5(path)) {
+      sources.push(relative3(projectRoot, path).replace(/\\/g, "/"));
+    }
+  }
+  const specsDir = join18(changeRoot, "specs");
+  if (await exists5(specsDir)) {
+    for (const file of await walkFiles(specsDir)) {
+      if (file.endsWith(".md")) {
+        sources.push(relative3(projectRoot, file).replace(/\\/g, "/"));
+      }
+    }
+  }
+  return sources.sort();
+}
+async function computePlanningFingerprint(projectRoot, changeId) {
+  const sources = await collectPlanningSources(projectRoot, changeId);
+  const hash = createHash("sha256");
+  for (const source of sources) {
+    const content = await readFile12(join18(projectRoot, source), "utf8");
+    hash.update(source);
+    hash.update("\0");
+    hash.update(content);
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+async function walkFiles(dir) {
+  const entries = await readdir4(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const path = join18(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkFiles(path));
+    } else if (entry.isFile()) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+async function exists5(path) {
+  try {
+    await stat8(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/figma/api.ts
+var FIGMA_API_BASE = "https://api.figma.com/v1";
+async function fetchFigmaFile(fileKey, accessToken, nodeIds) {
+  const params = new URLSearchParams();
+  if (nodeIds?.length) {
+    params.set("ids", nodeIds.join(","));
+    params.set("depth", "8");
+  }
+  const query = params.size ? `?${params.toString()}` : "";
+  const url = nodeIds?.length ? `${FIGMA_API_BASE}/files/${fileKey}/nodes${query}` : `${FIGMA_API_BASE}/files/${fileKey}${query}`;
+  const response = await fetch(url, {
+    headers: { "X-Figma-Token": accessToken }
+  });
+  if (!response.ok) {
+    throw new FetError({
+      code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+      message: `Figma API request failed (${response.status})`,
+      details: { fileKey, status: response.status, statusText: response.statusText },
+      recoverable: true,
+      suggestedCommand: "Check FIGMA_ACCESS_TOKEN and file permissions, then rerun fet figma sync."
+    });
+  }
+  const body = await response.json();
+  if (body.nodes && nodeIds?.length) {
+    const first = nodeIds.map((id) => body.nodes?.[id]?.document).find(Boolean);
+    if (!first) {
+      throw new FetError({
+        code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+        message: "Figma API returned no nodes for the requested node-id.",
+        details: { fileKey, nodeIds },
+        recoverable: true
+      });
+    }
+    return {
+      name: body.name ?? fileKey,
+      document: first,
+      components: body.components,
+      styles: body.styles
+    };
+  }
+  if (!body.document) {
+    throw new FetError({
+      code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+      message: "Figma API returned an empty document.",
+      details: { fileKey },
+      recoverable: true
+    });
+  }
+  return {
+    name: body.name ?? fileKey,
+    document: body.document,
+    components: body.components,
+    styles: body.styles
+  };
+}
+async function fetchFigmaImageUrls(fileKey, accessToken, imageRefs) {
+  if (!imageRefs.length) {
+    return {};
+  }
+  const response = await fetch(`${FIGMA_API_BASE}/files/${fileKey}/images`, {
+    headers: { "X-Figma-Token": accessToken }
+  });
+  if (!response.ok) {
+    throw new FetError({
+      code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+      message: `Figma image metadata request failed (${response.status})`,
+      details: { fileKey, status: response.status },
+      recoverable: true
+    });
+  }
+  const body = await response.json();
+  const result = {};
+  for (const ref of imageRefs) {
+    const url = body.images?.[ref];
+    if (url) {
+      result[ref] = url;
+    }
+  }
+  return result;
+}
+async function fetchFigmaNodeExports(fileKey, accessToken, nodeIds, format = "png") {
+  if (!nodeIds.length) {
+    return {};
+  }
+  const params = new URLSearchParams({
+    ids: nodeIds.join(","),
+    format,
+    scale: "2"
+  });
+  const response = await fetch(`${FIGMA_API_BASE}/images/${fileKey}?${params.toString()}`, {
+    headers: { "X-Figma-Token": accessToken }
+  });
+  if (!response.ok) {
+    return {};
+  }
+  const body = await response.json();
+  const result = {};
+  for (const id of nodeIds) {
+    const url = body.images?.[id];
+    if (url) {
+      result[id] = url;
+    }
+  }
+  return result;
+}
+async function downloadBinary(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new FetError({
+      code: "FILE_SYSTEM_ERROR" /* FileSystemError */,
+      message: `Failed to download Figma asset (${response.status})`,
+      details: { url },
+      recoverable: true
+    });
+  }
+  const buffer = new Uint8Array(await response.arrayBuffer());
+  const mimeType = response.headers.get("content-type")?.split(";")[0]?.trim() || "application/octet-stream";
+  return { bytes: buffer, mimeType };
+}
+
+// src/figma/download-assets.ts
+import { mkdir as mkdir6, writeFile } from "fs/promises";
+import { join as join19 } from "path";
+
+// src/figma/paths.ts
+function figmaFetDirRelative(changeId) {
+  return `openspec/changes/${changeId}/.fet`;
+}
+function figmaDesignManifestRelativePath2(changeId) {
+  return `${figmaFetDirRelative(changeId)}/figma-design-manifest.yaml`;
+}
+function figmaNodesRelativePath(changeId) {
+  return `${figmaFetDirRelative(changeId)}/figma-nodes.json`;
+}
+function figmaSyncInstructionsRelativePath2(changeId) {
+  return `${figmaFetDirRelative(changeId)}/figma-sync-instructions.md`;
+}
+function figmaAssetsDirRelative(changeId) {
+  return `${figmaFetDirRelative(changeId)}/figma-assets`;
+}
+function figmaAssetFileRelative(changeId, fileKey, assetId, ext) {
+  const safeId = assetId.replace(/:/g, "-");
+  return `${figmaAssetsDirRelative(changeId)}/${fileKey}/${safeId}.${ext}`;
+}
+
+// src/figma/download-assets.ts
+function extensionForMime(mimeType) {
+  if (mimeType.includes("svg")) {
+    return "svg";
+  }
+  if (mimeType.includes("jpeg") || mimeType.includes("jpg")) {
+    return "jpg";
+  }
+  if (mimeType.includes("webp")) {
+    return "webp";
+  }
+  return "png";
+}
+function toBase64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+async function downloadFigmaAssets(options) {
+  const assets = [];
+  const assetsRoot = join19(options.projectRoot, "openspec", "changes", options.changeId, ".fet", "figma-assets", options.fileKey);
+  await mkdir6(assetsRoot, { recursive: true });
+  const refUrls = await fetchFigmaImageUrls(options.fileKey, options.accessToken, [
+    ...new Set(options.imageRefs.map((item) => item.ref))
+  ]);
+  for (const item of options.imageRefs) {
+    const url = refUrls[item.ref];
+    if (!url) {
+      continue;
+    }
+    const { bytes, mimeType } = await downloadBinary(url);
+    const ext = extensionForMime(mimeType);
+    const assetId = `ref-${item.ref}`;
+    const relativePath = figmaAssetFileRelative(options.changeId, options.fileKey, assetId, ext);
+    const entry = await persistAsset({
+      projectRoot: options.projectRoot,
+      relativePath,
+      assetId,
+      name: item.name,
+      nodeId: item.nodeId,
+      imageRef: item.ref,
+      kind: "image-ref",
+      bytes,
+      mimeType,
+      config: options.config
+    });
+    assets.push(entry);
+  }
+  const exportIds = options.exportNodeIds.map((item) => item.nodeId).filter((id) => !assets.some((asset) => asset.nodeId === id));
+  if (!exportIds.length) {
+    return assets;
+  }
+  const exportUrls = await fetchFigmaNodeExports(options.fileKey, options.accessToken, exportIds.slice(0, 30));
+  for (const item of options.exportNodeIds) {
+    const url = exportUrls[item.nodeId];
+    if (!url) {
+      continue;
+    }
+    const { bytes, mimeType } = await downloadBinary(url);
+    const ext = extensionForMime(mimeType);
+    const relativePath = figmaAssetFileRelative(options.changeId, options.fileKey, item.nodeId, ext);
+    const entry = await persistAsset({
+      projectRoot: options.projectRoot,
+      relativePath,
+      assetId: item.nodeId,
+      name: item.name,
+      nodeId: item.nodeId,
+      kind: "node-export",
+      bytes,
+      mimeType,
+      config: options.config
+    });
+    assets.push(entry);
+  }
+  return assets;
+}
+async function persistAsset(options) {
+  const absolutePath = join19(options.projectRoot, options.relativePath);
+  await mkdir6(join19(absolutePath, ".."), { recursive: true });
+  if (options.bytes.byteLength <= options.config.inlineImageMaxBytes) {
+    const inlinePath = `${options.relativePath}.inline.json`;
+    await writeFile(
+      join19(options.projectRoot, inlinePath),
+      JSON.stringify({
+        mimeType: options.mimeType,
+        base64: toBase64(options.bytes)
+      }),
+      "utf8"
+    );
+    return {
+      id: options.assetId,
+      kind: options.kind,
+      name: options.name,
+      nodeId: options.nodeId,
+      imageRef: options.imageRef,
+      storage: "inline",
+      relativePath: inlinePath,
+      mimeType: options.mimeType,
+      bytes: options.bytes.byteLength
+    };
+  }
+  await writeFile(absolutePath, options.bytes);
+  return {
+    id: options.assetId,
+    kind: options.kind,
+    name: options.name,
+    nodeId: options.nodeId,
+    imageRef: options.imageRef,
+    storage: "file",
+    relativePath: options.relativePath,
+    mimeType: options.mimeType,
+    bytes: options.bytes.byteLength
+  };
+}
+
+// src/figma/manifest.ts
+import { readFile as readFile13 } from "fs/promises";
+import { join as join20 } from "path";
+import { parseDocument as parseDocument4, stringify as stringify3 } from "yaml";
+async function readFigmaDesignManifest(projectRoot, changeId) {
+  try {
+    const raw = await readFile13(join20(projectRoot, figmaDesignManifestRelativePath2(changeId)), "utf8");
+    const doc = parseDocument4(raw).toJSON();
+    if (!doc?.schemaVersion) {
+      return null;
+    }
+    return doc;
+  } catch {
+    return null;
+  }
+}
+function renderFigmaDesignManifestYaml(manifest) {
+  return stringify3(manifest);
+}
+
+// src/templates/figma-sync.ts
+function renderFigmaSyncInstructions(options) {
+  const title = options.language === "en" ? "Figma sync (this change)" : "Figma \u540C\u6B65\uFF08\u672C change\uFF09";
+  const intro = options.language === "en" ? `FET synced **${options.nodeCount}** nodes and **${options.assetCount}** assets (${options.fileAssetCount} saved as files on disk). Use this data before UI implementation\u2014do not guess visuals.` : `FET \u5DF2\u540C\u6B65 **${options.nodeCount}** \u4E2A\u8282\u70B9\u3001**${options.assetCount}** \u4E2A\u7D20\u6750\uFF08\u5176\u4E2D **${options.fileAssetCount}** \u4E2A\u5927\u56FE\u5DF2\u843D\u76D8\uFF09\u3002\u5B9E\u65BD UI \u524D\u5FC5\u987B\u57FA\u4E8E\u8FD9\u4E9B\u6570\u636E\uFF0C\u7981\u6B62\u731C\u6D4B\u89C6\u89C9\u6548\u679C\u3002`;
+  const readSteps = options.language === "en" ? `## Required reading order (before UI code)
+
+1. \`${options.manifestPath}\` \u2014 node summaries, colors, typography, asset paths.
+2. \`${options.nodesPath}\` \u2014 full Figma node tree (JSON) for layout and nested structure.
+3. \`openspec/changes/${options.changeId}/.fet/figma-assets/\` \u2014 background images and exports (use file paths in code, not base64 for large assets).
+4. \`figma-apply-instructions.md\` and \`figma-stop.md\` in the same folder \u2014 guard rules.
+
+## Asset usage in code
+
+- **storage: file** \u2192 import or reference the \`relativePath\` under the project root (e.g. \`public/\` or \`src/assets/\` after copy).
+- **storage: inline** \u2192 small icons only; read \`.inline.json\` if needed.
+- Never embed multi\u2011hundred\u2011KB images as base64 in source.` : `## \u5B9E\u65BD UI \u524D\u5FC5\u8BFB\uFF08\u987A\u5E8F\uFF09
+
+1. \`${options.manifestPath}\` \u2014 \u8282\u70B9\u6458\u8981\u3001\u989C\u8272\u3001\u5B57\u53F7\u3001\u7D20\u6750\u8DEF\u5F84\u3002
+2. \`${options.nodesPath}\` \u2014 \u5B8C\u6574 Figma \u8282\u70B9\u6811\uFF08JSON\uFF09\uFF0C\u7528\u4E8E\u5E03\u5C40\u4E0E\u5D4C\u5957\u7ED3\u6784\u3002
+3. \`openspec/changes/${options.changeId}/.fet/figma-assets/\` \u2014 \u80CC\u666F\u56FE\u4E0E\u5BFC\u51FA\u56FE\uFF08\u4EE3\u7801\u4E2D\u7528\u6587\u4EF6\u8DEF\u5F84\uFF0C\u5927\u56FE\u7981\u6B62 base64\uFF09\u3002
+4. \u540C\u76EE\u5F55 \`figma-apply-instructions.md\`\u3001\`figma-stop.md\` \u2014 \u5B88\u536B\u89C4\u5219\u3002
+
+## \u4EE3\u7801\u4E2D\u5982\u4F55\u4F7F\u7528\u7D20\u6750
+
+- **storage: file** \u2192 \u5C06 \`relativePath\` \u590D\u5236\u5230 \`public/\` \u6216 \`src/assets/\` \u540E\u5F15\u7528\u3002
+- **storage: inline** \u2192 \u4EC5\u7528\u4E8E\u5C0F\u56FE\u6807\uFF1B\u5FC5\u8981\u65F6\u8BFB\u53D6 \`.inline.json\`\u3002
+- \u7981\u6B62\u5728\u6E90\u7801\u4E2D\u5185\u8054\u6570\u767E KB \u4EE5\u4E0A\u7684 base64 \u56FE\u7247\u3002`;
+  return `---
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generatedAt: ${options.generatedAt}
+changeId: ${options.changeId}
+purpose: figma-sync
+---
+
+# ${title}
+
+${intro}
+
+${readSteps}
+`;
+}
+function renderFigmaSyncNextSteps(changeId, language, apiKeyEnv) {
+  if (language === "en") {
+    return [
+      `Run fet figma sync --change ${changeId} (set ${apiKeyEnv}) to fetch all Figma nodes and download assets before UI work.`,
+      `Read openspec/changes/${changeId}/.fet/figma-sync-instructions.md and figma-design-manifest.yaml after sync.`
+    ];
+  }
+  return [
+    `\u5B9E\u65BD UI \u524D\u6267\u884C fet figma sync --change ${changeId}\uFF08\u914D\u7F6E ${apiKeyEnv}\uFF09\uFF0C\u62C9\u53D6\u5168\u90E8\u8282\u70B9\u5E76\u4E0B\u8F7D\u7D20\u6750\u3002`,
+    `\u540C\u6B65\u540E\u9605\u8BFB openspec/changes/${changeId}/.fet/figma-sync-instructions.md \u4E0E figma-design-manifest.yaml\u3002`
+  ];
+}
+
+// src/figma/url.ts
+var FILE_KEY_PATTERN = /figma\.com\/(?:file|design|proto)\/([a-zA-Z0-9]+)/i;
+var NODE_ID_PATTERN = /[?&]node-id=([\d]+)-([\d]+)/i;
+function parseFigmaUrl(url) {
+  const fileMatch = url.match(FILE_KEY_PATTERN);
+  if (!fileMatch?.[1]) {
+    return null;
+  }
+  const nodeMatch = url.match(NODE_ID_PATTERN);
+  return {
+    fileKey: fileMatch[1],
+    nodeId: nodeMatch ? `${nodeMatch[1]}:${nodeMatch[2]}` : void 0,
+    url
+  };
+}
+function parseFigmaUrls(urls) {
+  const seen = /* @__PURE__ */ new Set();
+  const parsed = [];
+  for (const url of urls) {
+    const item = parseFigmaUrl(url);
+    if (!item) {
+      continue;
+    }
+    const key = `${item.fileKey}:${item.nodeId ?? ""}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    parsed.push(item);
+  }
+  return parsed;
+}
+
+// src/figma/walk.ts
+function rgbaFill(fill) {
+  if (fill.type !== "SOLID" || !fill.color) {
+    return null;
+  }
+  const { r, g, b, a = 1 } = fill.color;
+  const alpha = Math.round(a * 100) / 100;
+  return `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${alpha})`;
+}
+function summarizeFills(fills) {
+  if (!fills?.length) {
+    return void 0;
+  }
+  const out = [];
+  for (const fill of fills) {
+    if (fill.visible === false) {
+      continue;
+    }
+    if (fill.type === "IMAGE" && fill.imageRef) {
+      out.push(`image:${fill.imageRef}`);
+    } else {
+      const color = rgbaFill(fill);
+      if (color) {
+        out.push(color);
+      }
+    }
+  }
+  return out.length ? out : void 0;
+}
+function summarizeNode(node) {
+  const summary = {
+    id: node.id,
+    name: node.name,
+    type: node.type,
+    visible: node.visible !== false
+  };
+  if (node.absoluteBoundingBox) {
+    summary.width = node.absoluteBoundingBox.width;
+    summary.height = node.absoluteBoundingBox.height;
+  }
+  if (node.layoutMode) {
+    summary.layoutMode = node.layoutMode;
+  }
+  const fills = summarizeFills(node.fills);
+  if (fills) {
+    summary.fills = fills;
+  }
+  if (node.characters) {
+    summary.characters = node.characters.slice(0, 200);
+  }
+  if (node.style) {
+    summary.textStyle = {
+      fontFamily: node.style.fontFamily,
+      fontSize: node.style.fontSize,
+      fontWeight: node.style.fontWeight,
+      lineHeight: node.style.lineHeightPx
+    };
+  }
+  if (node.children?.length) {
+    summary.children = node.children.map((child) => child.id);
+  }
+  return summary;
+}
+function walkFigmaDocument(root) {
+  const nodes = [];
+  const imageRefs = [];
+  const exportNodeIds = [];
+  const seenRefs = /* @__PURE__ */ new Set();
+  function visit(node) {
+    nodes.push(summarizeNode(node));
+    for (const fill of node.fills ?? []) {
+      if (fill.type === "IMAGE" && fill.imageRef && fill.visible !== false && !seenRefs.has(fill.imageRef)) {
+        seenRefs.add(fill.imageRef);
+        imageRefs.push({ ref: fill.imageRef, nodeId: node.id, name: node.name });
+      }
+    }
+    const hasImageFill = node.fills?.some((fill) => fill.type === "IMAGE" && fill.visible !== false);
+    if (hasImageFill && (node.type === "RECTANGLE" || node.type === "FRAME" || node.type === "COMPONENT" || node.type === "INSTANCE")) {
+      exportNodeIds.push({ nodeId: node.id, name: node.name });
+    }
+    for (const child of node.children ?? []) {
+      visit(child);
+    }
+  }
+  visit(root);
+  return { nodes, imageRefs, exportNodeIds };
+}
+
+// src/figma/sync.ts
+async function syncFigmaAssets(options) {
+  const syncConfig = await loadFigmaSyncConfig(options.projectRoot);
+  if (!syncConfig.enabled) {
+    return null;
+  }
+  const { urls, sources } = await collectFigmaUrlsFromChange(options.projectRoot, options.changeId);
+  if (!urls.length) {
+    throw new FetError({
+      code: "INVALID_ARGUMENTS" /* InvalidArguments */,
+      message: "No Figma URLs found in this change.",
+      details: { changeId: options.changeId },
+      recoverable: true,
+      suggestedCommand: `Add a Figma link to openspec/changes/${options.changeId}/proposal.md or design.md`
+    });
+  }
+  const token = resolveFigmaAccessToken(syncConfig, options.accessToken);
+  if (!token) {
+    throw new FetError({
+      code: "INVALID_ARGUMENTS" /* InvalidArguments */,
+      message: `Figma access token missing. Set ${syncConfig.apiKeyEnv} or pass --token.`,
+      details: { apiKeyEnv: syncConfig.apiKeyEnv },
+      recoverable: true,
+      suggestedCommand: `FIGMA_ACCESS_TOKEN=*** fet figma sync --change ${options.changeId}`
+    });
+  }
+  const parsed = parseFigmaUrls(urls);
+  if (!parsed.length) {
+    throw new FetError({
+      code: "INVALID_ARGUMENTS" /* InvalidArguments */,
+      message: "Could not parse any Figma file keys from the detected URLs.",
+      details: { urls },
+      recoverable: true
+    });
+  }
+  const planningFingerprint = await computePlanningFingerprint(options.projectRoot, options.changeId);
+  const existing = await readFigmaDesignManifest(options.projectRoot, options.changeId);
+  if (!options.force && existing && existing.planningFingerprint === planningFingerprint && existing.figmaUrls.join(",") === urls.join(",")) {
+    return {
+      manifestPath: figmaDesignManifestRelativePath2(options.changeId),
+      nodesPath: figmaNodesRelativePath(options.changeId),
+      instructionsPath: figmaSyncInstructionsRelativePath2(options.changeId),
+      assetsDir: join21("openspec", "changes", options.changeId, ".fet", "figma-assets"),
+      manifest: existing,
+      written: false
+    };
+  }
+  if (options.plan) {
+    return {
+      manifestPath: figmaDesignManifestRelativePath2(options.changeId),
+      nodesPath: figmaNodesRelativePath(options.changeId),
+      instructionsPath: figmaSyncInstructionsRelativePath2(options.changeId),
+      assetsDir: join21("openspec", "changes", options.changeId, ".fet", "figma-assets"),
+      manifest: {
+        schemaVersion: 1,
+        fetVersion: FET_VERSION,
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        changeId: options.changeId,
+        planningFingerprint,
+        figmaUrls: urls,
+        figmaSources: sources,
+        files: parsed.map((item) => ({
+          fileKey: item.fileKey,
+          url: item.url,
+          rootNodeId: item.nodeId,
+          nodeCount: 0,
+          assetCount: 0
+        })),
+        nodes: [],
+        assets: []
+      },
+      written: false
+    };
+  }
+  const allNodes = [];
+  const allAssets = [];
+  const files = [];
+  const nodesByFile = {};
+  for (const item of parsed) {
+    const file = await fetchFigmaFile(item.fileKey, token, item.nodeId ? [item.nodeId] : void 0);
+    const walked = walkFigmaDocument(file.document);
+    allNodes.push(...walked.nodes);
+    nodesByFile[item.fileKey] = {
+      name: file.name,
+      rootNodeId: item.nodeId ?? file.document.id,
+      document: file.document,
+      components: file.components ?? {},
+      styles: file.styles ?? {}
+    };
+    const assets = await downloadFigmaAssets({
+      projectRoot: options.projectRoot,
+      changeId: options.changeId,
+      fileKey: item.fileKey,
+      accessToken: token,
+      config: syncConfig,
+      imageRefs: walked.imageRefs,
+      exportNodeIds: walked.exportNodeIds.slice(0, 20)
+    });
+    allAssets.push(...assets);
+    files.push({
+      fileKey: item.fileKey,
+      url: item.url,
+      rootNodeId: item.nodeId,
+      nodeCount: walked.nodes.length,
+      assetCount: assets.length
+    });
+  }
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const manifest = {
+    schemaVersion: 1,
+    fetVersion: FET_VERSION,
+    generatedAt,
+    changeId: options.changeId,
+    planningFingerprint,
+    figmaUrls: urls,
+    figmaSources: sources,
+    files,
+    nodes: allNodes,
+    assets: allAssets
+  };
+  const fetDir = join21(options.projectRoot, "openspec", "changes", options.changeId, ".fet");
+  await mkdir7(fetDir, { recursive: true });
+  const manifestPath3 = figmaDesignManifestRelativePath2(options.changeId);
+  const nodesPath = figmaNodesRelativePath(options.changeId);
+  const instructionsPath = figmaSyncInstructionsRelativePath2(options.changeId);
+  await atomicWrite(join21(options.projectRoot, manifestPath3), renderFigmaDesignManifestYaml(manifest));
+  await writeFile2(join21(options.projectRoot, nodesPath), JSON.stringify(nodesByFile, null, 2), "utf8");
+  await atomicWrite(
+    join21(options.projectRoot, instructionsPath),
+    renderFigmaSyncInstructions({
+      changeId: options.changeId,
+      generatedAt,
+      manifestPath: manifestPath3,
+      nodesPath,
+      language: options.language,
+      nodeCount: allNodes.length,
+      assetCount: allAssets.length,
+      fileAssetCount: allAssets.filter((asset) => asset.storage === "file").length
+    })
+  );
+  return {
+    manifestPath: manifestPath3,
+    nodesPath,
+    instructionsPath,
+    assetsDir: join21("openspec", "changes", options.changeId, ".fet", "figma-assets"),
+    manifest,
+    written: true
+  };
+}
+async function tryAutoSyncFigmaAssets(options) {
+  const syncConfig = await loadFigmaSyncConfig(options.projectRoot);
+  if (!syncConfig.enabled) {
+    return { synced: false, skipped: true, missingToken: false };
+  }
+  const { urls } = await collectFigmaUrlsFromChange(options.projectRoot, options.changeId);
+  if (!urls.length) {
+    return { synced: false, skipped: true, missingToken: false };
+  }
+  const token = resolveFigmaAccessToken(syncConfig);
+  if (!token) {
+    return { synced: false, skipped: false, missingToken: true };
+  }
+  const existing = await readFigmaDesignManifest(options.projectRoot, options.changeId);
+  const planningFingerprint = await computePlanningFingerprint(options.projectRoot, options.changeId);
+  if (existing && existing.planningFingerprint === planningFingerprint && existing.figmaUrls.join(",") === urls.join(",")) {
+    return {
+      synced: false,
+      skipped: true,
+      missingToken: false,
+      result: {
+        manifestPath: figmaDesignManifestRelativePath2(options.changeId),
+        nodesPath: figmaNodesRelativePath(options.changeId),
+        instructionsPath: figmaSyncInstructionsRelativePath2(options.changeId),
+        assetsDir: join21("openspec", "changes", options.changeId, ".fet", "figma-assets"),
+        manifest: existing,
+        written: false
+      }
+    };
+  }
+  const result = await syncFigmaAssets({
+    projectRoot: options.projectRoot,
+    changeId: options.changeId,
+    language: options.language,
+    accessToken: token
+  });
+  return { synced: Boolean(result?.written), skipped: false, missingToken: false, result: result ?? void 0 };
+}
+
 // src/ui-display-contract.ts
 import { existsSync as existsSync2 } from "fs";
-import { readdir as readdir4, readFile as readFile11, stat as stat8 } from "fs/promises";
-import { join as join17, relative as relative3 } from "path";
-import { parse as parse3, parseDocument as parseDocument3 } from "yaml";
+import { readdir as readdir5, readFile as readFile14, stat as stat9 } from "fs/promises";
+import { join as join22, relative as relative4 } from "path";
+import { parse as parse3, parseDocument as parseDocument5 } from "yaml";
 var DEFAULT_CONFIG2 = {
   enabled: true
 };
@@ -3715,8 +4484,8 @@ var BACKTICK_PATH_PATTERN = /`([^`]+\.(?:ya?ml|json))`/gi;
 var OPENAPI_BARE_PATTERN = /\b(openapi\.ya?ml|swagger\.ya?ml|swagger\.json)\b/gi;
 async function loadUiDisplayContractConfig(projectRoot) {
   try {
-    const raw = await readFile11(join17(projectRoot, "openspec", "config.yaml"), "utf8");
-    const doc = parseDocument3(raw);
+    const raw = await readFile14(join22(projectRoot, "openspec", "config.yaml"), "utf8");
+    const doc = parseDocument5(raw);
     const fetNode = doc.get("fet", true);
     const node = fetNode?.get?.("uiDisplayContract");
     if (!node || typeof node.get !== "function") {
@@ -3731,12 +4500,12 @@ async function loadUiDisplayContractConfig(projectRoot) {
   }
 }
 async function collectApiSourcesFromChange(projectRoot, changeId) {
-  const changePath = join17(projectRoot, "openspec", "changes", changeId);
+  const changePath = join22(projectRoot, "openspec", "changes", changeId);
   const paths = /* @__PURE__ */ new Set();
   const sources = [];
   const candidates = ["proposal.md", "tasks.md", "design.md"];
   for (const name of candidates) {
-    const filePath = join17(changePath, name);
+    const filePath = join22(changePath, name);
     const content = await readOptional4(filePath);
     if (!content) {
       continue;
@@ -3749,7 +4518,7 @@ async function collectApiSourcesFromChange(projectRoot, changeId) {
       }
     }
   }
-  const specsPath = join17(changePath, "specs");
+  const specsPath = join22(changePath, "specs");
   for (const filePath of await listMarkdownFiles2(specsPath)) {
     const content = await readOptional4(filePath);
     if (!content) {
@@ -3757,7 +4526,7 @@ async function collectApiSourcesFromChange(projectRoot, changeId) {
     }
     const found = extractApiDocPaths(content, projectRoot);
     if (found.length) {
-      sources.push(relative3(projectRoot, filePath).replaceAll("\\", "/"));
+      sources.push(relative4(projectRoot, filePath).replaceAll("\\", "/"));
       for (const path of found) {
         paths.add(path);
       }
@@ -3783,7 +4552,7 @@ function extractApiDocPaths(content, projectRoot) {
     const common = ["openapi.yaml", "openapi.yml", "docs/openapi.yaml", "swagger.yaml", "swagger.json"];
     for (const candidate of common) {
       const normalized = normalizeRepoPath(candidate, projectRoot);
-      if (normalized && existsSync2(join17(projectRoot, normalized))) {
+      if (normalized && existsSync2(join22(projectRoot, normalized))) {
         found.add(normalized);
       }
     }
@@ -3793,7 +4562,7 @@ function extractApiDocPaths(content, projectRoot) {
 async function extractOpenApiSchemas(projectRoot, relativePaths) {
   const schemas = [];
   for (const rel of relativePaths) {
-    const absolute = join17(projectRoot, rel);
+    const absolute = join22(projectRoot, rel);
     const content = await readOptional4(absolute);
     if (!content) {
       continue;
@@ -3869,9 +4638,9 @@ async function ensureChangeUiDisplayContract(options) {
   if (!config.enabled) {
     return null;
   }
-  const figma = await collectFigmaUrlsFromChange(options.projectRoot, options.changeId);
+  const figma2 = await collectFigmaUrlsFromChange(options.projectRoot, options.changeId);
   const api = await collectApiSourcesFromChange(options.projectRoot, options.changeId);
-  const hasFigma = figma.urls.length > 0;
+  const hasFigma = figma2.urls.length > 0;
   const hasApi = api.paths.length > 0;
   if (!hasFigma && !hasApi) {
     return null;
@@ -3884,14 +4653,14 @@ async function ensureChangeUiDisplayContract(options) {
     changeId: options.changeId,
     generatedAt,
     fetVersion: options.fetVersion,
-    figmaUrls: figma.urls,
-    figmaSources: figma.sources,
+    figmaUrls: figma2.urls,
+    figmaSources: figma2.sources,
     apiPaths: api.paths,
     apiSources: api.sources,
     apiSchemas
   });
   const contractContent = renderUiDisplayContractYaml(doc);
-  const contractAbsolutePath = join17(options.projectRoot, contractRelativePath);
+  const contractAbsolutePath = join22(options.projectRoot, contractRelativePath);
   const existingContract = await readOptional4(contractAbsolutePath);
   let written = false;
   if (existingContract !== contractContent) {
@@ -3906,7 +4675,7 @@ async function ensureChangeUiDisplayContract(options) {
     hasFigma,
     hasApi
   });
-  const applyAbsolutePath = join17(options.projectRoot, applyRelativePath);
+  const applyAbsolutePath = join22(options.projectRoot, applyRelativePath);
   const existingApply = await readOptional4(applyAbsolutePath);
   if (existingApply !== applyContent) {
     await atomicWrite(applyAbsolutePath, applyContent);
@@ -3973,9 +4742,9 @@ async function listMarkdownFiles2(root) {
 }
 async function walk2(dir, files) {
   try {
-    const entries = await readdir4(dir, { withFileTypes: true });
+    const entries = await readdir5(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join17(dir, entry.name);
+      const fullPath = join22(dir, entry.name);
       if (entry.isDirectory()) {
         await walk2(fullPath, files);
       } else if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -3988,8 +4757,8 @@ async function walk2(dir, files) {
 }
 async function readOptional4(path) {
   try {
-    await stat8(path);
-    return await readFile11(path, "utf8");
+    await stat9(path);
+    return await readFile14(path, "utf8");
   } catch {
     return null;
   }
@@ -4034,9 +4803,9 @@ async function assertChangeExists(ctx, changeId) {
 }
 
 // src/tdd/config.ts
-import { readFile as readFile12 } from "fs/promises";
-import { join as join18 } from "path";
-import { parseDocument as parseDocument4 } from "yaml";
+import { readFile as readFile15 } from "fs/promises";
+import { join as join23 } from "path";
+import { parseDocument as parseDocument6 } from "yaml";
 var DEFAULT_CONFIG3 = {
   enabled: true,
   mode: "require_before_apply",
@@ -4044,8 +4813,8 @@ var DEFAULT_CONFIG3 = {
 };
 async function loadTddConfig(projectRoot) {
   try {
-    const raw = await readFile12(join18(projectRoot, "openspec", "config.yaml"), "utf8");
-    const doc = parseDocument4(raw);
+    const raw = await readFile15(join23(projectRoot, "openspec", "config.yaml"), "utf8");
+    const doc = parseDocument6(raw);
     const fetNode = doc.get("fet", true);
     const node = fetNode?.get?.("tdd");
     if (!node || typeof node.get !== "function") {
@@ -4079,70 +4848,12 @@ function isTddRequired(config) {
   return config.enabled && config.mode === "require_before_apply";
 }
 
-// src/tdd/fingerprint.ts
-import { createHash } from "crypto";
-import { readdir as readdir5, readFile as readFile13, stat as stat9 } from "fs/promises";
-import { join as join19, relative as relative4 } from "path";
-async function collectPlanningSources(projectRoot, changeId) {
-  const changeRoot = join19(projectRoot, "openspec", "changes", changeId);
-  const sources = [];
-  const rootFiles = ["proposal.md", "tasks.md", "design.md"];
-  for (const name of rootFiles) {
-    const path = join19(changeRoot, name);
-    if (await exists5(path)) {
-      sources.push(relative4(projectRoot, path).replace(/\\/g, "/"));
-    }
-  }
-  const specsDir = join19(changeRoot, "specs");
-  if (await exists5(specsDir)) {
-    for (const file of await walkFiles(specsDir)) {
-      if (file.endsWith(".md")) {
-        sources.push(relative4(projectRoot, file).replace(/\\/g, "/"));
-      }
-    }
-  }
-  return sources.sort();
-}
-async function computePlanningFingerprint(projectRoot, changeId) {
-  const sources = await collectPlanningSources(projectRoot, changeId);
-  const hash = createHash("sha256");
-  for (const source of sources) {
-    const content = await readFile13(join19(projectRoot, source), "utf8");
-    hash.update(source);
-    hash.update("\0");
-    hash.update(content);
-    hash.update("\0");
-  }
-  return `sha256:${hash.digest("hex")}`;
-}
-async function walkFiles(dir) {
-  const entries = await readdir5(dir, { withFileTypes: true });
-  const files = [];
-  for (const entry of entries) {
-    const path = join19(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...await walkFiles(path));
-    } else if (entry.isFile()) {
-      files.push(path);
-    }
-  }
-  return files;
-}
-async function exists5(path) {
-  try {
-    await stat9(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 // src/tdd/manifest.ts
-import { mkdir as mkdir6, readFile as readFile14, stat as stat10 } from "fs/promises";
-import { dirname as dirname8, join as join20 } from "path";
-import { parse as parse4, stringify as stringify3 } from "yaml";
+import { mkdir as mkdir8, readFile as readFile16, stat as stat10 } from "fs/promises";
+import { dirname as dirname8, join as join24 } from "path";
+import { parse as parse4, stringify as stringify4 } from "yaml";
 function tddManifestPath(projectRoot, changeId) {
-  return join20(projectRoot, tddManifestRelativePath(changeId));
+  return join24(projectRoot, tddManifestRelativePath(changeId));
 }
 async function readTddManifest(projectRoot, changeId) {
   const path = tddManifestPath(projectRoot, changeId);
@@ -4151,7 +4862,7 @@ async function readTddManifest(projectRoot, changeId) {
   } catch {
     return null;
   }
-  const doc = parse4(await readFile14(path, "utf8"));
+  const doc = parse4(await readFile16(path, "utf8"));
   if (!doc || doc.schemaVersion !== 1 || doc.changeId !== changeId) {
     return null;
   }
@@ -4159,15 +4870,15 @@ async function readTddManifest(projectRoot, changeId) {
 }
 async function writeTddManifest(projectRoot, manifest) {
   const relative6 = tddManifestRelativePath(manifest.changeId);
-  const path = join20(projectRoot, relative6);
-  await mkdir6(dirname8(path), { recursive: true });
-  await atomicWrite(path, stringify3(manifest));
+  const path = join24(projectRoot, relative6);
+  await mkdir8(dirname8(path), { recursive: true });
+  await atomicWrite(path, stringify4(manifest));
   return relative6;
 }
 async function writeTddResults(projectRoot, results) {
   const relative6 = tddResultsRelativePath(results.changeId);
-  const path = join20(projectRoot, relative6);
-  await mkdir6(dirname8(path), { recursive: true });
+  const path = join24(projectRoot, relative6);
+  await mkdir8(dirname8(path), { recursive: true });
   await atomicWrite(path, `${JSON.stringify(results, null, 2)}
 `);
   return relative6;
@@ -4275,8 +4986,8 @@ async function git(cwd, args) {
 }
 
 // src/state/store.ts
-import { mkdir as mkdir7, readFile as readFile15 } from "fs/promises";
-import { join as join21 } from "path";
+import { mkdir as mkdir9, readFile as readFile17 } from "fs/promises";
+import { join as join25 } from "path";
 
 // src/language.ts
 var DEFAULT_LANGUAGE = "zh-CN";
@@ -4398,7 +5109,7 @@ var StateStore = class {
   project;
   async readGlobal() {
     try {
-      const value = JSON.parse(await readFile15(this.globalPath(), "utf8"));
+      const value = JSON.parse(await readFile17(this.globalPath(), "utf8"));
       assertGlobalState(value);
       return value;
     } catch (error) {
@@ -4413,13 +5124,13 @@ var StateStore = class {
   }
   async writeGlobal(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir7(join21(this.projectRoot, "openspec"), { recursive: true });
+    await mkdir9(join25(this.projectRoot, "openspec"), { recursive: true });
     await atomicWrite(this.globalPath(), `${JSON.stringify(state, null, 2)}
 `);
   }
   async readChange(changeId) {
     try {
-      const value = JSON.parse(await readFile15(this.changePath(changeId), "utf8"));
+      const value = JSON.parse(await readFile17(this.changePath(changeId), "utf8"));
       assertChangeState(value);
       return value;
     } catch (error) {
@@ -4434,15 +5145,15 @@ var StateStore = class {
   }
   async writeChange(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir7(join21(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
+    await mkdir9(join25(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
     await atomicWrite(this.changePath(state.changeId), `${JSON.stringify(state, null, 2)}
 `);
   }
   globalPath() {
-    return join21(this.projectRoot, "openspec", "fet-state.json");
+    return join25(this.projectRoot, "openspec", "fet-state.json");
   }
   changePath(changeId) {
-    return join21(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
+    return join25(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
   }
 };
 function isNotFound(error) {
@@ -4450,11 +5161,11 @@ function isNotFound(error) {
 }
 
 // src/state/tasks.ts
-import { readFile as readFile16 } from "fs/promises";
+import { readFile as readFile18 } from "fs/promises";
 async function readCompletedTaskIds(tasksPath) {
   let content;
   try {
-    content = await readFile16(tasksPath, "utf8");
+    content = await readFile18(tasksPath, "utf8");
   } catch {
     return [];
   }
@@ -4617,6 +5328,8 @@ async function applyWorkflowCommand(ctx, args) {
         fetVersion: ctx.fetVersion
       })
     ]);
+    const figmaSyncConfig = await loadFigmaSyncConfig(ctx.projectRoot);
+    const figmaAutoSync = figmaGuard ? await tryAutoSyncFigmaAssets({ projectRoot: ctx.projectRoot, changeId, language: ctx.language }) : null;
     const applyNextSteps = [
       `Read openspec/changes/${changeId}/tasks.md and the instructions output.`,
       "Implement pending tasks and update task checkboxes only after the work is done.",
@@ -4627,7 +5340,13 @@ async function applyWorkflowCommand(ctx, args) {
       applyNextSteps.unshift(...renderUiDisplayContractApplyNextSteps(changeId, ctx.language));
     }
     if (figmaGuard) {
-      applyNextSteps.unshift(...renderFigmaApplyNextSteps(changeId, ctx.language, figmaGuard.mode));
+      applyNextSteps.unshift(
+        ...renderFigmaApplyNextSteps(changeId, ctx.language, figmaGuard.mode, {
+          syncMissingToken: figmaAutoSync?.missingToken,
+          syncDone: figmaAutoSync?.synced || figmaAutoSync?.skipped && Boolean(figmaAutoSync.result),
+          apiKeyEnv: figmaSyncConfig.apiKeyEnv
+        })
+      );
       applyNextSteps.splice(applyNextSteps.length - 1, 0, ...renderVisualVerifyNextSteps(changeId, ctx.language));
     }
     ctx.output.result({
@@ -4642,6 +5361,7 @@ async function applyWorkflowCommand(ctx, args) {
         status,
         graphContext: runState.graphContext,
         figmaGuard: figmaGuard ?? void 0,
+        figmaSync: figmaAutoSync ?? void 0,
         uiDisplayContract: uiContract ?? void 0
       }
     });
@@ -5040,7 +5760,7 @@ async function createChangelogEntry(projectRoot, changeId) {
   };
 }
 async function appendChangelog(projectRoot, entry) {
-  const changelogPath = join22(projectRoot, "CHANGELOG.md");
+  const changelogPath = join26(projectRoot, "CHANGELOG.md");
   const existing = await readOptional5(changelogPath);
   const legacyContentLabel = "\u66F4\u65B0\u5185\u5BB9";
   const block = `updateTime: ${entry.updateTime}
@@ -5053,12 +5773,12 @@ ${block}` : block;
   await atomicWrite(changelogPath, next);
 }
 async function readChangeRequirement(projectRoot, changeId) {
-  const changeRoot = join22(projectRoot, "openspec", "changes", changeId);
-  const proposal = await readOptional5(join22(changeRoot, "proposal.md"));
+  const changeRoot = join26(projectRoot, "openspec", "changes", changeId);
+  const proposal = await readOptional5(join26(changeRoot, "proposal.md"));
   if (proposal) {
     return summarizeMarkdown(proposal);
   }
-  const readme = await readOptional5(join22(changeRoot, "README.md"));
+  const readme = await readOptional5(join26(changeRoot, "README.md"));
   if (readme) {
     return summarizeMarkdown(readme);
   }
@@ -5070,7 +5790,7 @@ function summarizeMarkdown(content) {
 }
 async function readOptional5(path) {
   try {
-    return await readFile17(path, "utf8");
+    return await readFile19(path, "utf8");
   } catch {
     return null;
   }
@@ -5425,17 +6145,17 @@ async function updateCommand(ctx) {
 }
 
 // src/commands/tdd.ts
-import { mkdir as mkdir8 } from "fs/promises";
-import { join as join24 } from "path";
+import { mkdir as mkdir10 } from "fs/promises";
+import { join as join28 } from "path";
 
 // src/tdd/extract-cases.ts
-import { readFile as readFile18 } from "fs/promises";
-import { join as join23 } from "path";
+import { readFile as readFile20 } from "fs/promises";
+import { join as join27 } from "path";
 async function extractCasesFromChange(projectRoot, changeId, sources) {
   const cases = [];
   const seen = /* @__PURE__ */ new Set();
   for (const source of sources) {
-    const content = await readFile18(join23(projectRoot, source), "utf8");
+    const content = await readFile20(join27(projectRoot, source), "utf8");
     if (source.endsWith("tasks.md")) {
       for (const item of extractTaskCases(content, changeId)) {
         if (!seen.has(item.id)) {
@@ -5569,12 +6289,12 @@ async function tddCommand(ctx) {
       testCommand: testCommand2
     });
     const manifestPath3 = await writeTddManifest(ctx.projectRoot, manifest);
-    const fetDir = join24(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-    await mkdir8(fetDir, { recursive: true });
+    const fetDir = join28(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+    await mkdir10(fetDir, { recursive: true });
     const instructionsPath = tddInstructionsRelativePath(changeId);
     const specPath = tddSpecRelativePath(changeId);
-    await atomicWrite(join24(ctx.projectRoot, instructionsPath), renderTddInstructions(changeId, manifest, ctx.language));
-    await atomicWrite(join24(ctx.projectRoot, specPath), renderTddSpec(changeId, manifest, ctx.language));
+    await atomicWrite(join28(ctx.projectRoot, instructionsPath), renderTddInstructions(changeId, manifest, ctx.language));
+    await atomicWrite(join28(ctx.projectRoot, specPath), renderTddSpec(changeId, manifest, ctx.language));
     const changeState = await ctx.stateStore.getOrCreateChange(changeId, "implement");
     changeState.tdd = {
       status: "ready",
@@ -5816,14 +6536,81 @@ function truncate(value, max = 2e3) {
   return value.length > max ? `${value.slice(0, max)}\u2026` : value;
 }
 
+// src/commands/figma.ts
+import { mkdir as mkdir11 } from "fs/promises";
+import { join as join29 } from "path";
+async function figmaSyncCommand(ctx, options) {
+  await withProjectLock(ctx.projectRoot, { command: "figma", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    const changeId = await resolveChangeId(ctx);
+    await assertChangeExists(ctx, changeId);
+    const syncConfig = await loadFigmaSyncConfig(ctx.projectRoot);
+    const result = await syncFigmaAssets({
+      projectRoot: ctx.projectRoot,
+      changeId,
+      language: ctx.language,
+      accessToken: options.token,
+      force: Boolean(options.force),
+      plan: Boolean(options.plan)
+    });
+    if (!result) {
+      ctx.output.result({
+        ok: true,
+        command: "figma",
+        summary: msg(ctx.language, "Figma \u540C\u6B65\u5DF2\u7981\u7528\uFF08fet.figmaGuard.sync.enabled: false\uFF09\u3002", "Figma sync is disabled (fet.figmaGuard.sync.enabled: false)."),
+        data: { changeId, enabled: false }
+      });
+      return;
+    }
+    if (options.plan) {
+      ctx.output.result({
+        ok: true,
+        command: "figma",
+        summary: msg(ctx.language, "Figma \u540C\u6B65\u8BA1\u5212\u5DF2\u751F\u6210\u3002", "Figma sync plan ready."),
+        data: {
+          changeId,
+          files: result.manifest.files,
+          figmaUrls: result.manifest.figmaUrls
+        },
+        nextSteps: [`fet figma sync --change ${changeId}`]
+      });
+      return;
+    }
+    await mkdir11(join29(ctx.projectRoot, "openspec", "changes", changeId, ".fet"), { recursive: true });
+    ctx.output.result({
+      ok: true,
+      command: "figma",
+      summary: result.written ? msg(
+        ctx.language,
+        `\u5DF2\u540C\u6B65 ${result.manifest.nodes.length} \u4E2A\u8282\u70B9\u3001${result.manifest.assets.length} \u4E2A\u7D20\u6750\u3002`,
+        `Synced ${result.manifest.nodes.length} node(s) and ${result.manifest.assets.length} asset(s).`
+      ) : msg(ctx.language, "Figma \u8BBE\u8BA1\u6570\u636E\u5DF2\u662F\u6700\u65B0\uFF0C\u8DF3\u8FC7\u91CD\u65B0\u4E0B\u8F7D\u3002", "Figma design data is up to date; skipped re-download."),
+      data: {
+        changeId,
+        written: result.written,
+        manifestPath: result.manifestPath,
+        nodesPath: result.nodesPath,
+        instructionsPath: result.instructionsPath,
+        assetsDir: result.assetsDir,
+        nodeCount: result.manifest.nodes.length,
+        assetCount: result.manifest.assets.length,
+        fileAssetCount: result.manifest.assets.filter((asset) => asset.storage === "file").length
+      },
+      nextSteps: result.written ? [
+        `Read ${result.instructionsPath} before UI implementation.`,
+        ...renderFigmaSyncNextSteps(changeId, ctx.language, syncConfig.apiKeyEnv).slice(1)
+      ] : [`Read ${result.instructionsPath} before UI implementation.`]
+    });
+  });
+}
+
 // src/commands/visual.ts
-import { mkdir as mkdir10 } from "fs/promises";
-import { join as join28 } from "path";
+import { mkdir as mkdir13 } from "fs/promises";
+import { join as join33 } from "path";
 
 // src/visual/config.ts
-import { readFile as readFile19 } from "fs/promises";
-import { join as join25 } from "path";
-import { parseDocument as parseDocument5 } from "yaml";
+import { readFile as readFile21 } from "fs/promises";
+import { join as join30 } from "path";
+import { parseDocument as parseDocument7 } from "yaml";
 var DEFAULT_CONFIG4 = {
   enabled: true,
   compareMode: "layout-only",
@@ -5832,8 +6619,8 @@ var DEFAULT_CONFIG4 = {
 };
 async function loadVisualConfig(projectRoot) {
   try {
-    const raw = await readFile19(join25(projectRoot, "openspec", "config.yaml"), "utf8");
-    const doc = parseDocument5(raw);
+    const raw = await readFile21(join30(projectRoot, "openspec", "config.yaml"), "utf8");
+    const doc = parseDocument7(raw);
     const fetNode = doc.get("fet", true);
     const node = fetNode?.get?.("visual");
     if (!node || typeof node.get !== "function") {
@@ -5879,10 +6666,10 @@ function isVisualRequiredForVerify(config, hasFigma) {
 
 // src/visual/playwright.ts
 import { createRequire } from "module";
-import { dirname as dirname9, join as join26 } from "path";
+import { dirname as dirname9, join as join31 } from "path";
 import { pathToFileURL } from "url";
 async function resolvePlaywright(projectRoot) {
-  const require2 = createRequire(join26(projectRoot, "package.json"));
+  const require2 = createRequire(join31(projectRoot, "package.json"));
   const candidates = ["playwright", "@playwright/test"];
   for (const name of candidates) {
     try {
@@ -5914,11 +6701,11 @@ async function capturePagesWithPlaywright(projectRoot, manifest, baseUrl) {
   return results;
 }
 async function captureSinglePage(projectRoot, browser, changeId, pageDef, baseUrl) {
-  const { mkdir: mkdir15 } = await import("fs/promises");
+  const { mkdir: mkdir18 } = await import("fs/promises");
   const { join: joinPath } = await import("path");
   const screenshotRelative = visualPageScreenshotRelative(changeId, pageDef.id);
   const screenshotAbsolute = joinPath(projectRoot, screenshotRelative);
-  await mkdir15(dirname9(screenshotAbsolute), { recursive: true });
+  await mkdir18(dirname9(screenshotAbsolute), { recursive: true });
   const url = new URL(pageDef.route, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).toString();
   const pwPage = await browser.newPage();
   try {
@@ -5983,11 +6770,11 @@ async function extractRegions(page, pageDef) {
 }
 
 // src/visual/manifest.ts
-import { mkdir as mkdir9, readFile as readFile20, stat as stat11 } from "fs/promises";
-import { dirname as dirname10, join as join27 } from "path";
-import { parse as parse5, stringify as stringify4 } from "yaml";
+import { mkdir as mkdir12, readFile as readFile22, stat as stat11 } from "fs/promises";
+import { dirname as dirname10, join as join32 } from "path";
+import { parse as parse5, stringify as stringify5 } from "yaml";
 function visualManifestPath(projectRoot, changeId) {
-  return join27(projectRoot, visualManifestRelativePath(changeId));
+  return join32(projectRoot, visualManifestRelativePath(changeId));
 }
 async function readVisualManifest(projectRoot, changeId) {
   const path = visualManifestPath(projectRoot, changeId);
@@ -5996,7 +6783,7 @@ async function readVisualManifest(projectRoot, changeId) {
   } catch {
     return null;
   }
-  const doc = parse5(await readFile20(path, "utf8"));
+  const doc = parse5(await readFile22(path, "utf8"));
   if (!doc || doc.schemaVersion !== 1 || doc.changeId !== changeId) {
     return null;
   }
@@ -6004,15 +6791,15 @@ async function readVisualManifest(projectRoot, changeId) {
 }
 async function writeVisualManifest(projectRoot, manifest) {
   const relative6 = visualManifestRelativePath(manifest.changeId);
-  const path = join27(projectRoot, relative6);
-  await mkdir9(dirname10(path), { recursive: true });
-  await atomicWrite(path, stringify4(manifest));
+  const path = join32(projectRoot, relative6);
+  await mkdir12(dirname10(path), { recursive: true });
+  await atomicWrite(path, stringify5(manifest));
   return relative6;
 }
 async function readVisualCapture(projectRoot, changeId) {
-  const path = join27(projectRoot, visualCaptureRelativePath(changeId));
+  const path = join32(projectRoot, visualCaptureRelativePath(changeId));
   try {
-    const doc = JSON.parse(await readFile20(path, "utf8"));
+    const doc = JSON.parse(await readFile22(path, "utf8"));
     if (doc?.schemaVersion === 1 && doc.changeId === changeId) {
       return doc;
     }
@@ -6023,16 +6810,16 @@ async function readVisualCapture(projectRoot, changeId) {
 }
 async function writeVisualCapture(projectRoot, capture) {
   const relative6 = visualCaptureRelativePath(capture.changeId);
-  const path = join27(projectRoot, relative6);
-  await mkdir9(dirname10(path), { recursive: true });
+  const path = join32(projectRoot, relative6);
+  await mkdir12(dirname10(path), { recursive: true });
   await atomicWrite(path, `${JSON.stringify(capture, null, 2)}
 `);
   return relative6;
 }
 async function writeVisualResults(projectRoot, results) {
   const relative6 = visualResultsRelativePath(results.changeId);
-  const path = join27(projectRoot, relative6);
-  await mkdir9(dirname10(path), { recursive: true });
+  const path = join32(projectRoot, relative6);
+  await mkdir12(dirname10(path), { recursive: true });
   await atomicWrite(path, `${JSON.stringify(results, null, 2)}
 `);
   return relative6;
@@ -6426,10 +7213,10 @@ async function ensureManifest(ctx, changeId, baseUrl) {
     baseUrl
   );
   await writeVisualManifest(ctx.projectRoot, manifest);
-  const fetDir = join28(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  await mkdir10(fetDir, { recursive: true });
-  await atomicWrite(join28(ctx.projectRoot, visualInstructionsRelativePath(changeId)), renderVisualInstructions(changeId, manifest, ctx.language));
-  await atomicWrite(join28(ctx.projectRoot, visualSpecRelativePath(changeId)), renderVisualSpec(changeId, manifest, ctx.language));
+  const fetDir = join33(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  await mkdir13(fetDir, { recursive: true });
+  await atomicWrite(join33(ctx.projectRoot, visualInstructionsRelativePath(changeId)), renderVisualInstructions(changeId, manifest, ctx.language));
+  await atomicWrite(join33(ctx.projectRoot, visualSpecRelativePath(changeId)), renderVisualSpec(changeId, manifest, ctx.language));
   const changeState = await ctx.stateStore.getOrCreateChange(changeId, "verify");
   changeState.visual = {
     status: "ready",
@@ -6482,8 +7269,8 @@ async function recordVisualFailure(ctx, changeId, planningFingerprint, steps, ca
 
 // src/commands/verify.ts
 import { createHash as createHash2 } from "crypto";
-import { mkdir as mkdir11, readFile as readFile21, stat as stat12 } from "fs/promises";
-import { join as join29 } from "path";
+import { mkdir as mkdir14, readFile as readFile23, stat as stat12 } from "fs/promises";
+import { join as join34 } from "path";
 async function verifyCommand(ctx, options) {
   if (options.auto) {
     const scan = await ctx.scanner.scan(ctx.projectRoot, {});
@@ -6552,9 +7339,9 @@ async function writeInstructions(ctx, changeId) {
   await assertTestPassed(ctx, changeId);
   await assertVisualPassed(ctx, changeId);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join29(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join29(dir, "verify-instructions.md");
-  await mkdir11(dir, { recursive: true });
+  const dir = join34(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  const instructionsPath = join34(dir, "verify-instructions.md");
+  await mkdir14(dir, { recursive: true });
   await atomicWrite(instructionsPath, renderVerifyInstructions(changeId, generatedAt));
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
   state.currentPhase = "verify";
@@ -6572,7 +7359,7 @@ async function markDone(ctx, changeId) {
   await assertTestPassed(ctx, changeId);
   await assertVisualPassed(ctx, changeId);
   const declaredAt = (/* @__PURE__ */ new Date()).toISOString();
-  const instructionsPath = join29(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
+  const instructionsPath = join34(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
   const instructions = await readInstructions(ctx, instructionsPath, changeId);
   const instructionsGeneratedAt = readFrontMatterValue(instructions, "generatedAt") ?? declaredAt;
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
@@ -6597,7 +7384,7 @@ async function markDone(ctx, changeId) {
 async function readInstructions(ctx, path, changeId) {
   try {
     await stat12(path);
-    const content = await readFile21(path, "utf8");
+    const content = await readFile23(path, "utf8");
     const fileChangeId = readFrontMatterValue(content, "changeId");
     if (fileChangeId !== changeId) {
       throw new FetError({
@@ -6720,9 +7507,9 @@ function renderIdeModelPolicy(command, language = "zh-CN") {
 import { resolve } from "path";
 
 // src/adapters/codex/index.ts
-import { mkdir as mkdir12, readFile as readFile22, stat as stat13 } from "fs/promises";
+import { mkdir as mkdir15, readFile as readFile24, stat as stat13 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname11, join as join30 } from "path";
+import { dirname as dirname11, join as join35 } from "path";
 
 // src/adapters/commands.ts
 var FET_STANDALONE_COMMANDS = ["tdd", "test", "visual"];
@@ -7383,7 +8170,7 @@ Steps:
 3. Follow the native apply output. If JSON output is unavailable, read the files referenced by the terminal output and the artifacts under openspec/changes/<change-id>/.
 4. If \`openspec/changes/<change-id>/.fet/figma-apply-instructions.md\` exists (or apply nextSteps mention Figma):
    - Read it and \`figma-stop.md\` in the same folder before any UI code.
-   - Use Figma MCP/API to read every linked frame; briefly confirm design facts in your reply.
+   - Run \`fet figma sync\` when possible; read \`figma-design-manifest.yaml\`, \`figma-nodes.json\`, and \`.fet/figma-assets/\` (file paths for large images). Otherwise use Figma MCP/API for every linked frame; briefly confirm design facts in your reply.
    - If Figma access fails or design details are unclear, stop and ask the user\u2014do not guess styles or implement UI.
 5. If \`openspec/changes/<change-id>/.fet/ui-display-contract.yaml\` exists (or apply nextSteps mention UI display contract):
    - Read it and \`ui-field-apply-instructions.md\` in the same folder before UI that binds API data.
@@ -7929,7 +8716,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists6(join30(projectRoot, ".codex")) || await exists6(join30(projectRoot, "AGENTS.md")),
+      detected: await exists6(join35(projectRoot, ".codex")) || await exists6(join35(projectRoot, "AGENTS.md")),
       reason: "Codex adapter is available for projects that use AGENTS.md"
     };
   }
@@ -7968,7 +8755,7 @@ var CodexAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir12(dirname11(target), { recursive: true });
+      await mkdir15(dirname11(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(displayPath);
     }
@@ -7995,9 +8782,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join30(resolveCodexHome(), file.path);
+    return join35(resolveCodexHome(), file.path);
   }
-  return join30(projectRoot, file.path);
+  return join35(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -8006,11 +8793,11 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join30(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join35(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
-    return await readFile22(path, "utf8");
+    return await readFile24(path, "utf8");
   } catch {
     return null;
   }
@@ -8025,8 +8812,8 @@ async function exists6(path) {
 }
 
 // src/adapters/cursor/index.ts
-import { mkdir as mkdir13, readFile as readFile23, stat as stat14 } from "fs/promises";
-import { dirname as dirname12, join as join31 } from "path";
+import { mkdir as mkdir16, readFile as readFile25, stat as stat14 } from "fs/promises";
+import { dirname as dirname12, join as join36 } from "path";
 
 // src/adapters/cursor/templates.ts
 function cursorFigmaStopRuleFile(language = DEFAULT_LANGUAGE) {
@@ -8272,12 +9059,14 @@ function renderApplySkill(usage, language) {
   const figmaBlock = language === "en" ? `If \`fet apply\` output or the change has \`openspec/changes/<change-id>/.fet/figma-apply-instructions.md\`:
 
 1. Read that file and \`figma-stop.md\` in the same folder before any UI code.
-2. Use Figma MCP/API to read every linked frame; do not invent colors, spacing, or layout.
+2. Run \`fet figma sync\` when possible; read \`figma-design-manifest.yaml\`, \`figma-nodes.json\`, and \`.fet/figma-assets/\` (use file paths for large images, not base64).
+3. Otherwise use Figma MCP/API for every linked frame; do not invent colors, spacing, or layout.
 3. If Figma fails or design is unclear, stop and ask the user\u2014do not guess styles or mark UI tasks done.
 4. After design is confirmed, implement tasks from \`tasks.md\`.` : `\u82E5 \`fet apply\` \u8F93\u51FA\u6216 change \u4E2D\u5B58\u5728 \`openspec/changes/<change-id>/.fet/figma-apply-instructions.md\`\uFF1A
 
 1. \u5728\u6539\u4EFB\u4F55 UI \u4EE3\u7801\u524D\uFF0C\u5148\u9605\u8BFB\u8BE5\u6587\u4EF6\u4E0E\u540C\u76EE\u5F55 \`figma-stop.md\`\u3002
-2. \u7528 Figma MCP/API \u8BFB\u53D6\u6BCF\u4E2A\u94FE\u63A5\u7684\u753B\u677F\uFF1B\u7981\u6B62\u81EA\u521B\u989C\u8272\u3001\u95F4\u8DDD\u3001\u5E03\u5C40\u3002
+2. \u4F18\u5148\u6267\u884C \`fet figma sync\`\uFF1B\u9605\u8BFB \`figma-design-manifest.yaml\`\u3001\`figma-nodes.json\` \u4E0E \`.fet/figma-assets/\`\uFF08\u5927\u56FE\u7528\u6587\u4EF6\u8DEF\u5F84\uFF0C\u7981\u6B62 base64\uFF09\u3002
+3. \u5426\u5219\u7528 Figma MCP/API \u8BFB\u53D6\u6BCF\u4E2A\u753B\u677F\uFF1B\u7981\u6B62\u81EA\u521B\u989C\u8272\u3001\u95F4\u8DDD\u3001\u5E03\u5C40\u3002
 3. Figma \u5931\u8D25\u6216\u8BBE\u8BA1\u4E0D\u6E05\u65F6\u7ACB\u5373\u505C\u6B62\u5E76\u5411\u7528\u6237\u63D0\u95EE\uFF0C\u4E0D\u8981\u731C\u6837\u5F0F\uFF0C\u4E0D\u8981\u628A UI \u4EFB\u52A1\u6807\u4E3A\u5B8C\u6210\u3002
 4. \u8BBE\u8BA1\u786E\u8BA4\u540E\uFF0C\u518D\u6309 \`tasks.md\` \u5B9E\u65BD\u4EFB\u52A1\u3002`;
   return `<!-- FET:MANAGED
@@ -8381,7 +9170,7 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists7(join31(projectRoot, ".cursor")),
+      detected: await exists7(join36(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
@@ -8398,10 +9187,10 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join31(projectRoot, file.path);
+      const target = join36(projectRoot, file.path);
       const existing = await readExisting2(target);
       if (file.path === ".cursor/hooks.json") {
-        await mkdir13(dirname12(target), { recursive: true });
+        await mkdir16(dirname12(target), { recursive: true });
         await atomicWrite(target, mergeCursorHooksJson(existing, file.content));
         written.push(file.path);
         continue;
@@ -8417,7 +9206,7 @@ var CursorAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir13(dirname12(target), { recursive: true });
+      await mkdir16(dirname12(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(file.path);
     }
@@ -8427,7 +9216,7 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join31(projectRoot, file.path);
+      const target = join36(projectRoot, file.path);
       const content = await readExisting2(target);
       const hooksManaged = file.path === ".cursor/hooks.json" && Boolean(content?.includes('"writeBoundary"'));
       const hookScript = file.path.startsWith(".cursor/hooks/fet-guard-") && file.path.endsWith(".mjs");
@@ -8445,7 +9234,7 @@ var CursorAdapter = class {
 };
 async function readExisting2(path) {
   try {
-    return await readFile23(path, "utf8");
+    return await readFile25(path, "utf8");
   } catch {
     return null;
   }
@@ -8465,12 +9254,12 @@ import { promisify as promisify4 } from "util";
 
 // src/openspec/inspector.ts
 import { readdir as readdir6, stat as stat15 } from "fs/promises";
-import { join as join32 } from "path";
+import { join as join37 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join32(projectRoot, "openspec");
-  const changesPath = join32(openspecPath, "changes");
-  const legacyArchivePath = join32(openspecPath, "archive");
-  const changesArchivePath = join32(changesPath, "archive");
+  const openspecPath = join37(projectRoot, "openspec");
+  const changesPath = join37(openspecPath, "changes");
+  const legacyArchivePath = join37(openspecPath, "archive");
+  const changesArchivePath = join37(changesPath, "archive");
   return {
     exists: await exists8(openspecPath),
     changes: await listDirectories(changesPath, { exclude: ["archive"] }),
@@ -8478,13 +9267,13 @@ async function inspectOpenSpecProject(projectRoot) {
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join32(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join32(changePath, "tasks.md");
-  const specsPath = join32(changePath, "specs");
+  const changePath = join37(projectRoot, "openspec", "changes", changeId);
+  const tasksPath = join37(changePath, "tasks.md");
+  const specsPath = join37(changePath, "specs");
   return {
     changeId,
     exists: await exists8(changePath),
-    hasProposal: await exists8(join32(changePath, "proposal.md")),
+    hasProposal: await exists8(join37(changePath, "proposal.md")),
     hasTasks: await exists8(tasksPath),
     hasSpecs: await exists8(specsPath),
     tasksPath,
@@ -8686,12 +9475,12 @@ function escapeRegExp(value) {
 
 // src/scanner/routes.ts
 import { readdir as readdir7, stat as stat16 } from "fs/promises";
-import { join as join33, relative as relative5, sep } from "path";
+import { join as join38, relative as relative5, sep } from "path";
 async function scanRoutes(projectRoot) {
   const candidates = ["src/routes", "src/pages", "app", "pages"];
   const routes = [];
   for (const candidate of candidates) {
-    const root = join33(projectRoot, candidate);
+    const root = join38(projectRoot, candidate);
     if (!await exists9(root)) {
       continue;
     }
@@ -8719,7 +9508,7 @@ async function listFiles(root) {
   const entries = await readdir7(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join33(root, entry.name);
+    const path = join38(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {
@@ -8887,9 +9676,9 @@ async function createCommandContext(command, options) {
 import { createInterface as createInterface2 } from "readline/promises";
 
 // src/update/check.ts
-import { mkdir as mkdir14, readFile as readFile24, writeFile } from "fs/promises";
+import { mkdir as mkdir17, readFile as readFile26, writeFile as writeFile3 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname13, join as join34 } from "path";
+import { dirname as dirname13, join as join39 } from "path";
 var DEFAULT_CACHE_TTL_MS = 6 * 60 * 60 * 1e3;
 function getFetUpdateCheckMode(env = process.env) {
   const value = env.FET_UPDATE_CHECK?.trim().toLowerCase();
@@ -8962,11 +9751,11 @@ function formatFetUpdateWarning(availability, language) {
 }
 function cachePath() {
   const home = process.env.FET_UPDATE_CHECK_CACHE_HOME?.trim() || homedir2();
-  return join34(home, ".fet", "update-check-cache.json");
+  return join39(home, ".fet", "update-check-cache.json");
 }
 async function readUpdateCheckCache() {
   try {
-    const raw = await readFile24(cachePath(), "utf8");
+    const raw = await readFile26(cachePath(), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.latestVersion !== "string" || typeof parsed.checkedAt !== "string") {
       return null;
@@ -8982,8 +9771,8 @@ async function readUpdateCheckCache() {
 }
 async function writeUpdateCheckCache(cache) {
   const path = cachePath();
-  await mkdir14(dirname13(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(cache, null, 2)}
+  await mkdir17(dirname13(path), { recursive: true });
+  await writeFile3(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
 
@@ -9070,6 +9859,19 @@ addGlobalOptions(program.command("doctor").description("\u8BCA\u65AD\u72B6\u6001
   wrap("doctor", (ctx, options) => doctorCommand(ctx, { fixLock: Boolean(options.fixLock) }))
 );
 addGlobalOptions(program.command("tdd").description("\u6839\u636E\u89C4\u5212\u4EA7\u7269\u751F\u6210 change \u7EA7 TDD \u6E05\u5355\u4E0E\u6D4B\u8BD5\u6307\u5F15")).action(wrap("tdd", tddCommand));
+var figma = addGlobalOptions(program.command("figma").description("Figma \u8BBE\u8BA1\u7A3F\u540C\u6B65\uFF08\u62C9\u53D6\u8282\u70B9\u6811\u5E76\u4E0B\u8F7D\u7D20\u6750\uFF09"));
+addGlobalOptions(
+  figma.command("sync").description("\u4ECE Figma API \u540C\u6B65\u5168\u90E8\u8282\u70B9\u4E0E\u56FE\u7247\u7D20\u6750\u5230 change/.fet/").option("--token <token>", "Figma Personal Access Token\uFF08\u4E5F\u53EF\u7528 FIGMA_ACCESS_TOKEN\uFF09").option("--force", "\u5F3A\u5236\u91CD\u65B0\u4E0B\u8F7D\uFF0C\u5FFD\u7565\u5DF2\u6709\u540C\u6B65\u7ED3\u679C").option("--plan", "\u4EC5\u8F93\u51FA\u540C\u6B65\u8BA1\u5212\uFF0C\u4E0D\u8C03\u7528 Figma API")
+).action(
+  wrap(
+    "figma",
+    (ctx, options) => figmaSyncCommand(ctx, {
+      token: options.token,
+      force: Boolean(options.force),
+      plan: Boolean(options.plan)
+    })
+  )
+);
 addGlobalOptions(program.command("test").description("\u6309 change TDD \u6E05\u5355\u8FD0\u884C\u5355\u6D4B\u5E76\u8BB0\u5F55\u7EFF\u706F\u72B6\u6001").option("--plan", "\u4EC5\u8F93\u51FA\u5C06\u6267\u884C\u7684\u6D4B\u8BD5\u547D\u4EE4\uFF0C\u4E0D\u8FD0\u884C")).action(
   wrap("test", (ctx, options) => testCommand(ctx, { plan: Boolean(options.plan) }))
 );
@@ -9202,4 +10004,3 @@ function extractGlobalOptions(args) {
   }
   return options;
 }
-//# sourceMappingURL=index.js.map