figma-spec

Figma の仕様書を扱う

figma.spec.* API を使用する前に、必ず whoami を呼び出し、対象ファイルのプラン（新しいファイルの場合は保存先のプラン）で specs_enabled: true になっていることを確認してください。whoami では、どのプランがファイルを所有しているかは特定できません。プランが不明な場合は、必ずユーザーに確認してください。ファイルキーや別のプランへのアクセス権から推測してはいけません。そのプランで specs_enabled が false または未設定の場合は、Specs を利用できないことを説明し、ワークフローを中止してください。

ネイティブの Figma 仕様書は、SPEC_BLOCK ノード内の GitHub Flavored Markdown（GFM）です。スタンドアロンの Figma 仕様書には仕様書が 1 つだけ含まれますが、FigJam ファイルやデザインファイルには複数の仕様書を埋め込めます。

Figma 仕様書を見つけて選択する

指定された URL に node-id が含まれている場合は、figma.getNodeByIdAsync で解決し、type === "SPEC_BLOCK" かつ specBlockType === "DOCUMENT" であることを必須とします。そうでない場合は、findAllWithCriteria({ types: ['SPEC_BLOCK'] }) を使って現在のページを検索し、specBlockType === "DOCUMENT" で絞り込みます。必要に応じて figma.spec.getContent で内容を確認し、目的の仕様書が見つかるまで続けてください。現在のページにない場合は、他のページを 1 つずつ page.loadAsync() で読み込み、目的の仕様書が見つかった時点で検索を終了してください。

解決したルート ID をすべてのコンテンツ呼び出しに渡してください。ファイルに Figma 仕様書が 1 つだけ含まれると分かっている場合に限り、specNodeId を省略できます。それ以外の場合、省略するとエラーになります。代替手段として通常のキャンバステキストノードを編集してはいけません。

キャンバスに Figma 仕様書を作成する

// Creates an embedded Figma spec on a Design or FigJam canvas (not a standalone Figma spec file).
const { specNodeId } = await figma.spec.createOnCanvasAsync({
  title: 'Untitled spec',
  content: '# Title\n\nA paragraph.\n',
})

const specNode = await figma.getNodeByIdAsync(specNodeId)
if (!specNode) throw new Error('The created Figma spec could not be resolved')

const after = await figma.spec.getContent({ specNodeId })
if (!after.markdown.includes('A paragraph.')) {
  throw new Error('The new Figma spec content was not applied')
}

空でない title と content 文字列（'' も使用可能）を必ず渡してください。title はルートの名前です。必要な # H1 は content に含めてください。

コンテンツメソッド

// READ — returns specNodeId, markdown, title, etc.
// The body is `markdown`, not `content`.
const before = await figma.spec.getContent({ specNodeId: chosenSpec.id })
const page = await figma.spec.getContent({
  specNodeId: before.specNodeId,
  offset: 100,
  maxLines: 50,
})

// REPLACE — clears + recreates the document; use only for an empty first draft.
await figma.spec.setContent({
  specNodeId: before.specNodeId,
  content: '# Title\n\nA paragraph.\n',
})

// EDIT — find/replace; each oldText must match exactly once.
await figma.spec.editContent({
  specNodeId: before.specNodeId,
  edits: [{ oldText: 'First paragraph.', newText: 'Edited first paragraph.' }],
})

const after = await figma.spec.getContent({ specNodeId: before.specNodeId })
if (!after.markdown.includes('Edited first paragraph.')) {
  throw new Error('The targeted Figma spec edit was not applied')
}

• 編集前と書き込みの検証には、同じ specNodeId を指定した getContent を使用してください。スクリーンショットに頼ってはいけません。
• マルチプレイヤー環境で安全な、的を絞った editContent を既定で使用してください。
• 破壊的な setContent は、空の初回草稿を作成する場合、またはドキュメント全体の置き換えを明示的に求められた場合にのみ使用してください。

重要なルール

1. editContent は一致が正確に 1 件であることを必須とします。 oldText が 0 件または複数件一致すると、変更は行われずに失敗します。一致箇所を一意にするため、前後の文脈を追加してください。
2. Markdown はプレーン文字列として渡してください。 Buffer／base64 でエンコードしたり、atob() でデコードしたりしてはいけません。base64 を使用できるのは、Markdown 内の画像データ URL に限られます。
3. Markdown とノードの走査を分けてください。 figma.spec.* はコンテンツを処理します。ノードの走査で参照できるのは、ドキュメントのルートと埋め込みキャンバスの分岐のみです。
4. コメントマーカーを保持してください。 重なり合う [comment:<uuid>]…[/comment:<uuid>] のペアは、同じテキストの周囲で変更せずに維持してください。そうしないと、スレッドが切り離されたり消えたりする可能性があります。判断に迷った場合は、マークされた範囲をそのままコピーし、その周囲を編集してください。
5. 移植可能な参照を使用してください。 共有 Figma 仕様書では、マシン固有のパスや localhost の URL ではなく、GitHub のパーマリンクなどのリンクを使用してください。

スタイル

• タイトルブロックは、テキストが空の場合も含めて、常に最初に H1 形式で配置してください。削除したり、前にブロックを挿入したりしてはいけません。
• 表のヘッダー行では太字のテキストを優先してください。
• 下線には、複合書式の場合も含めて <ins> を使用してください（例：<ins>**太字かつ下線付き**</ins>）。HTML インポートでしか機能しない <u> は使用しないでください。

画像

setContent または editContent 内の画像には、GFM の画像構文を使用します。

• ![alt](data:image/png;base64,...) はバイト列を埋め込み、デコードしてアップロードします。
• ![alt](https://host/img.png) はサーバー側で取得します。許可されていないホストは拒否されます。

getContent は、画像 URL を https://<host>/spec/<fileKey>/image/<sha>?w=<width>&h=<height> として出力します。

コメント

アンカー付きスレッドには figma.spec.comments.* を使用してください。変更に確信が持てない場合は、黙って編集するよりコメントを残すことを優先してください。

const comment = await figma.spec.comments.create({
  specNodeId: before.specNodeId,
  anchorText: 'the exact rendered text to anchor to', // MUST appear exactly once
  contextText: 'a longer unique substring containing anchorText', // optional; disambiguates repeats
  message: 'Comment body (markdown).',
})

const { root, replies, hasMore } = await figma.spec.comments.getThread({ uuid: comment.uuid })
await figma.spec.comments.reply({ uuid: comment.uuid, message: 'A reply.' })

• anchorText は、レンダリングされた Figma 仕様書内で正確に 1 回だけ一致する必要があります。繰り返し出現するテキストを区別するには、それを含む、より長い contextText を使用してください。
• getThread と reply では、[comment:<uuid>] マーカーで示されるルートコメント UUID が必要です。reply に返信 UUID を渡してはいけません。