3行まとめ
対象。
値。
状態。
確認。
Figma designは、対象と確認条件を分けてからcodeへ渡します。
- Figma designをCodexへ渡す前に、selection、state、component、design token、対象外を分けます。
- 完成条件は、見た目、操作、利用性、dataの4つに分けて先に書きます。
- PRへ出す時は、差分、画像、確認結果、未決事項を一緒に残します。
Figma designをcodeへ変換する作業は、うまく決まると速いです。選択範囲やvisual referenceを渡して、既存appの画面へ落とす。Codexのuse casesにも、Figma selectionsをstructured design contextとvisual checksでpolished UIへ変換する用途や、screenshotsとvisual referencesからfront-end designを作る用途が紹介されています。
ただし、Figmaを丸ごと渡すだけでは、実装が広がります。既存componentを使うのか、新規componentを作るのか。design tokenはどれに対応するのか。hover、empty、error、permissionのstateはあるのか。どこまで一致すれば完了なのか。ここを決めずに進めると、見た目は近いのにreviewで止まります。
この記事では、2026年6月1日時点のOpenAI公式Codex docsをもとに、Figma designをcodeへ変える前の準備と確認を整理します。Codexのfront-end use casesやapp機能は更新され得るため、導入時は最新docsと自社のdesign systemを確認してください。
この記事でわかること
範囲。
対応。
条件。
証跡。
design-to-codeは、見た目だけでなく根拠と判断を残します。
- FigmaからCodexへ渡すselectionの決め方
- 既存componentとdesign tokenへ当てる方法
- Codexに渡すdesign context、target files、constraintsの作り方
- 受け入れ条件を先に書く理由
- 実装後に見る確認項目
- PRへ出す時に残す証跡
この記事は、Figmaの使い方そのものではありません。すでにdesignがある状態から、Codexに実装へ変換させる前の整理に絞ります。PRDやuser storyがまだ曖昧な場合は、先にCodexでPRDを下書きする前に情報源と決定ログを分けるやCodexでユーザーストーリーをUIモックにする前に決めることで扱った整理を済ませる方が安定します。
前提知識
| 項目 | 内容 | 見方 |
|---|---|---|
| Figma | design to code。 | |
| Front-end | visual reference。 | |
| Features | 作業入口。 | |
| Worktrees | 変更分離。 | |
| AGENTS.md | repo手順。 |
designがある時は、要件作りではなく実装への変換として扱います。
OpenAI公式のCodex Use Casesでは、Figma designをcodeへ変える用途が紹介されています。Figma selectionsをstructured design contextとvisual checksでUIへ変換する、という位置づけです。同じfront-end系のuse casesには、screenshotsやvisual referencesからfront-end designを作る用途、既存appで小さなUI iterationを行う用途も並んでいます。
ここで重要なのは、design-to-codeを「Figmaの見た目をそのまま写す作業」とだけ見ないことです。実務では、既存component、routing、data、permission、loading、error、copy、test、PR reviewが関係します。
Codex Use Casesで見る位置づけ
| 用途 | この記事での扱い |
|---|---|
| Turn Figma designs into code | Figma selectionを既存appへ実装する |
| Build responsive front-end designs | screenshotやvisual referenceからUI案を作る |
| Make granular UI changes | 既存appで小さなUI差分を作る |
| Turn user stories into UI mocks | 実装前に画面案を作る |
| Deploy an app or website | previewや公開先まで進める |
mockとdesign-to-codeの違い
mockは、まだ判断材料の段階です。関係者が見て、flowや情報の優先順位を決めます。
design-to-codeは、既存repoへ変更を入れる段階です。ここでは、見た目だけでなく、既存componentとの対応、dataの出し方、状態、test、PR reviewが必要になります。
Figmaから渡す範囲を決める
| 項目 | 内容 | 見方 |
|---|---|---|
| Frame | 対象frame。 | |
| State | 画面状態。 | |
| Variant | 差分。 | |
| Exclude | 対象外。 |
選択範囲を狭くすると、差分reviewがしやすくなります。
Figmaから渡す範囲は、selection、screen state、variants、対象外で決めます。広すぎるselectionは、Codexにもreviewerにも重いです。
最初は、小さなframe、1つのsection、1つのcomponent groupから始めます。画面全体を一気に変えるより、既存appとの接点が少ない範囲で試す方が成功しやすいです。
selection
selectionは、今回codeへ変換する対象です。Figma上のframe名、component名、対象screen、関連するannotationを残します。
Codexには、selectionだけでなく、どのrepo、どのroute、どのfileへ反映するかも渡します。designだけでは、実装先が分かりません。
screen state
screen stateは、画面の状態です。normal、empty、loading、error、permission denied、long content、disabled、selectedなどを分けます。
Figmaにnormalしかない場合は、Codexへ「他のstateは作らない」のか、「既存patternから補う」のかを明示します。勝手に補わせると、design reviewで戻る可能性が高くなります。
variants
variantsは、componentや状態の差分です。buttonのprimary、secondary、disabled、cardのcompact、expanded、table rowのselectedなどです。
variantsを渡す時は、実装で必要なものだけ選びます。Figma上にある全variantを同時に実装すると、今回のPRが大きくなります。
既存componentへ当てる
- 1Find
既存確認。
- 2Map
対応付け。
- 3Gap
不足確認。
- 4Name
命名。
新規部品を作る前に、既存componentへ当てられるかを見ます。
Figma designをcodeへ変える前に、既存componentへ当てます。新しく作る前に、すでにあるcomponent、utility、theme、tokenを確認します。
この作業を飛ばすと、見た目は近いけれどproduct全体から浮いたUIになります。さらに、同じようなbutton、badge、card、modalが増えて、後で保守しにくくなります。
reuse
reuseでは、既存componentをそのまま使えるかを見ます。button、input、select、badge、table、toast、modal、drawer、tabs、empty stateなどです。
Codexには、Figma上の要素と既存componentの対応表を作らせます。「FigmaのStatus Badgeは、repoのStatusPillで代替できる」のように書くと、reviewしやすくなります。
new component
新規componentが必要な場合は、理由を残します。既存componentでは情報量が足りない、stateが違う、複数画面で再利用する、などです。
ただし、1画面だけの都合で大きな共通componentを作ると、影響範囲が広がります。最初はlocal componentで始め、再利用が見えたら共通化する判断もあります。
token
design tokenは、色、文字、余白、radius、shadow、border、motionなどの値です。Figma上の値をそのままCSSへ書くのではなく、既存themeやtokenへ対応させます。
Codexには、hard-coded valueを避けるように指示します。既存tokenがない場合は、勝手に新しい値を足さず、open questionとして残す方が安全です。
Codexに渡す入力
Figma情報。
対象file。
制約。
確認条件。
入力は、designとrepoの接点が分かる形へまとめます。
Codexに渡す入力は、design context、target files、constraintsです。Figmaだけ渡しても、repoの作法が分からなければ、実装は浮きます。
入力は長ければよいわけではありません。必要なのは、designとrepoの接点です。どの画面へ反映するか、既存componentはどれか、触ってよいfileはどこか、確認方法は何かを束ねます。
design context
design contextには、Figma selection、関連screenshot、annotation、state、token、copy、design ownerを書きます。
Codexには、design contextのうち、確定情報と未決情報を分けさせます。特にcopy、token、stateが未決なら、実装前に確認します。
target files
target filesは、変更候補のfileです。route、page component、shared component、style file、test fileなどを分けます。
Codexにrepoを調べさせる場合も、探索範囲を決めます。front-end全体を自由に触らせるより、対象routeとcomponent directoryを指定する方がreviewしやすくなります。
constraints
constraintsは、守るべき制約です。既存componentを優先する、tokenを使う、API shapeを変えない、copyは既存文体に合わせる、今回のPRでroutingは変えない、などです。
制約がないと、Codexはよい案を広く出してくれます。design-to-codeでは、よい案より、今回の範囲でmergeできる差分が必要です。
受け入れ条件を先に書く
| 項目 | 内容 | 見方 |
|---|---|---|
| Visual | 見た目。 | |
| Behavior | 操作。 | |
| A11y | 利用性。 | |
| Data | 表示値。 |
完了条件を先に書くと、実装後の判断が揃います。
受け入れ条件は、見た目、操作、利用性、dataで分けます。実装後に「なんとなく違う」とならないよう、先に書きます。
Figmaに近いことは大事ですが、実務ではそれだけでは足りません。既存appのcomponent、data、state、accessibility、testも含めて完了条件にします。
visual
visualでは、spacing、hierarchy、color、typography、alignment、stateの見え方を見ます。
ここで大事なのは、すべてをpixel単位で一致させることではありません。designが伝えたい優先順位、情報量、状態の違いがcode上でも保たれているかを見ます。
behavior
behaviorでは、click、keyboard、focus、hover、disabled、loading、submit、cancel、navigationを見ます。
Figmaで見えない部分ほど、実装時に抜けます。Codexには、visualだけでなく、操作条件もacceptance criteriaへ入れさせます。
accessibility
accessibilityでは、heading、label、focus、contrast、keyboard、screen reader向けの名前を見ます。
design-to-codeでは、見た目が近くても、buttonがbuttonとして操作できない、inputにlabelがない、focus位置が分からない、という問題が起きます。review観点に入れておきます。
pixel一致より大事なこと
pixel単位の一致を最初の完了条件にすると、既存componentやthemeとの相性が悪くなることがあります。
大事なのは、userが必要な情報を見つけられること、操作できること、既存productと一貫していること、reviewerが差分を判断できることです。
実装後の確認を分ける
- 1Build
起動。
- 2Inspect
画面確認。
- 3Compare
差分確認。
- 4Fix
修正。
確認は、起動、見た目、操作、差分の順に分けます。
実装後の確認は、local build、画面確認、差分確認、操作確認、testに分けます。全部を「見た目確認」で済ませると、抜けが出ます。
Codexには、変更後に何を確認したかをまとめさせます。起動できたか、対象画面を開けたか、主要stateを見たか、操作したか、testを走らせたかを分けます。
local
localでは、install、build、typecheck、lint、unit test、dev server起動を確認します。repoのAGENTS.mdやREADMEに手順があるなら、それを優先します。
Figma由来の変更でも、package追加やstyle変更がある場合はbuildに影響します。見た目だけで終わらせません。
screenshot
screenshotは、reviewerが差分を見るための証跡です。変更前、変更後、重要stateを残します。
ただし、screenshotだけでは操作やaccessibilityは分かりません。必要に応じて、操作ログ、test結果、console errorの有無も添えます。
reviewer
reviewerは、design owner、front-end owner、product ownerを分けます。全員が同じ観点で見る必要はありません。
design ownerは意図と見た目を見ます。front-end ownerはcomponentと実装品質を見ます。product ownerは要件やuser flowとの整合を見ます。
PRへ出す時の証跡
| 項目 | 内容 | 見方 |
|---|---|---|
| Diff | 変更。 | |
| Shot | 画像。 | |
| Test | 確認。 | |
| Open | 未決。 |
PRには、何を見ればよいかが分かる証跡を添えます。
PRへ出す時は、diff、画像、確認結果、未決事項を添えます。AIが作ったかどうかより、reviewerが判断できる材料が揃っているかが大事です。
PR本文には、Figma link、対象selection、変更file、使ったcomponent、確認したstate、未確認のstate、test結果を書きます。
diff
diffでは、component追加、style変更、token利用、test変更、削除した古い実装を分けます。
大きい差分になった場合は、PRを分けます。design-to-codeは、見た目変更、component整理、data接続、test追加が一度に入りやすいです。
evidence
evidenceは、reviewに必要な証拠です。画像、test結果、URL、確認command、Figma link、owner確認を残します。
Codexには、最後に「確認済み」「未確認」「判断が必要」を分けて報告させます。これがあると、人間reviewが速くなります。
open questions
open questionsは、merge前に決めるものと、次PRでよいものに分けます。
tokenが未決、copyが未承認、stateがFigmaにない、dataがまだない。こうした点を隠さず残す方が、安全に進められます。
よくある失敗
広すぎる。
値が曖昧。
部品増加。
証跡なし。
広いdesignを一度に渡すほど、reviewが難しくなります。
よくある失敗は、画面全体を一度に渡す、既存componentを見ない、Figmaの数値をそのまま埋める、stateをnormalだけで済ませる、PRに証跡を残さないことです。
もう1つは、design reviewとcode reviewを混ぜることです。design ownerが見るべき差分と、front-end ownerが見るべき差分は違います。PR本文で観点を分けると、reviewが進みやすくなります。
Figma designをcodeへ変える作業は、速さだけで評価しない方がよいです。既存productと自然につながるか、保守できる差分か、確認が残っているかを見ます。
FAQ
| 項目 | 内容 | 見方 |
|---|---|---|
| Figma only? | repoも見る。 | |
| Exact? | 条件で判断。 | |
| Tokens? | 先に確認。 | |
| Owner? | 決める。 |
迷ったら、designのどこをcodeで再現するのかへ戻します。
Figmaだけ渡せば実装できますか？
小さな静的UIなら始められる場合があります。ただし、既存repoのcomponent、target files、token、data、stateを渡した方がreviewしやすくなります。
Figmaと完全一致させるべきですか？
完全一致を求める場面もありますが、既存componentやthemeとの整合が大事な場面もあります。先にacceptance criteriaを決め、何を一致させるのかを明確にします。
design tokenがない値はどうしますか？
勝手に新しい値を増やさず、まず既存tokenへ対応できるかを見ます。対応できない場合は、design ownerとfront-end ownerの判断が必要です。
どの段階でPRにしますか？
対象selection、既存component対応、受け入れ条件、確認方法が揃ったらPRにできます。未決が多い場合は、調査PRやprototypeとして分ける方が安全です。
参照した主な情報源
- https://developers.openai.com/codex/explore/
- https://developers.openai.com/codex/use-cases
- https://developers.openai.com/codex/app/features
- https://developers.openai.com/codex/app/worktrees
- https://developers.openai.com/codex/guides/agents-md
次に読むなら
更新履歴
- 2026.06.01
初版。
Codexのfront-end use casesは、導入時に公式docsで見直します。
- 2026年6月1日: OpenAI公式Codex docsを確認して初版を作成しました。