Extract a complete set of specifications in a phased manner from Figma wireframes,docs/ and output them as Markdown under that location.Do not infer or fill in attributes not explicitly present in Figma , but include in the main document the range that can be objectively derived from the components (page roles, state transitions, design suggestions, typical pain points, etc.).
Output structure
docs/
├── existing-codebase.md # extension モードのみ
├── pages/
│ ├── README.md # ページインデックス + 横断サマリー
│ └── <page-slug>.md # 6 セクション固定: 構成要素 / テキスト要素一覧 / アクションボタン / 参照モデル / 利用コンポーネント / 関連する未解決事項
├── use-cases.md
├── actors.md
├── data-model.md
├── components.md
└── reviews/
├── coverage-review.md
├── data-model-review.md
└── components-review.md
ID naming conventions (with scope)
| Target | ID format | Example |
|---|---|---|
| Use case | UC-XX |
UC-01 |
| Actor | A-XX |
A-01 |
| Entity | E-XX |
E-01 |
| Entity columns | E-XX.C-YY |
E-01.C-03 |
| Entity indexes | E-XX.I-YY |
E-01.I-01 |
| Relation | R-XX |
R-01 |
| Component | CMP-XX |
CMP-01 |
| Component parameters | CMP-XX.P-YY |
CMP-01.P-02 |
| Component event handlers | CMP-XX.H-YY |
CMP-01.H-01 |
Numbers are numbered in discovery order with zero-padded 2 digits . When referencing them in subsequent steps, always use this ID, andalways write the name together (example: `E-02.C-06`（Award.application_close_at））。
Principle of not filling in gaps and permissible range of objective extraction
Prohibited (inferential filling)
- Fabricating attributes that do not exist in Figma (business requirements, KPIs, strategic goals)
- Adding plausible-sounding extra features (e.g., user registration, authentication, payment) on one's own
- Making up fictional persona attributes (specific age, occupation, family structure)
Permitted (objective extraction; may be described in the main document)
- Derivable from the page name + components: role descriptions
- Attribute state transitions / lifecycle (the ENUM values themselves are in Figma)
- CMS / operations / SEO design suggestions (naturally derived from the structure)
- Actor classification (primary / secondary / offstage) and typical pain points
- Action behavior overview (those uniquely determined by component name + parent element + icon)
Items to leave unstated in Figma
List the deficiencies for the first time in the review steps (Step 6 / 9 / 12) and present them to the user. Writing "unstated" in the main document is only for cases that do not fall under the above "Permitted".
Prerequisites
figma-devThe MCP server (Figma:get_design_contextetc.) is authenticated (if unauthenticated, prompt authentication with/mcp)- Working in the output destination directory
- The following have been obtained from the user:
- Figma URL（
https://www.figma.com/design/:fileKey/...） - Project goals(required as evaluation criteria during review)
- Transfer destination(local Markdown / Notion / GitHub Wiki, etc.)
- Implementation mode(see next section)
- Figma URL（
Implementation mode × Execution mode
Implementation mode (confirmed in Step 0)
| Mode | Purpose | Execution of Step 0.5 |
|---|---|---|
new |
New app | Skip |
extension |
Feature extension of existing app | Execute(reuse of existing assets is assumed) |
extension In this mode, design in the priority order of existing model → add column → new Entity. For details, see references/extension-mode-guide.md .
Execution mode (confirmed in Step 0)
| Mode | Confirmation frequency | Step 14 |
|---|---|---|
| Hybrid (recommended) | After Step 0 / 1 / 4 / 6 / 7 / 9 / 12 | According to user preference |
| Fully automatic | Review presentation only | Includes question loop |
Iterative reflection (extension recommended) |
Same as hybrid | Always execute |
Recommended path
| Case | Recommended mode combination |
|---|---|
| New app + lightweight use | new + Hybrid |
| Feature extension of existing repository | extension + Iterative reflection |
Step overview
| Step | Content | Model | Parallelization | Target |
|---|---|---|---|---|
| 0 | Preparation (URL + goal + transcription destination + implementation mode acquisition) | Parent (Opus) | — | All modes |
| 0.5 | Existing codebase investigation | Sub (Sonnet) | — | extension only |
| 1 | Page list extraction + canvas size auto-detection | Parent + Figma MCP | — | All modes |
| 2 | Extraction of each page's structure | Sub (Sonnet) | Parallel per page | All modes |
| 3 | Extraction of each page's actions (with source column) | Sub (Sonnet) | Parallel per page | All modes |
| 4 | Use case extraction | Parent (Opus) | — | All modes |
| 5 | Actor extraction + UC×Actor matrix | Parent (Opus) | — | All modes |
| 6 | Consistency review + cross-cutting summary append | Parent (Opus) | — | All modes |
| 7 | Data model extraction (state transitions + design notes) | Parent (Opus) | — | All modes |
| 8 | Append model references to each page | Sub (Sonnet) | Parallel per page | All modes |
| 9 | Data model review | Parent (Opus) | — | All modes |
| 10 | Component extraction (commonization policy + mapping verification) | Parent (Opus) | — | All modes |
| 11 | Add component references to each page | Sub (Sonnet) | Parallel per page | All modes |
| 12 | Component review | Parent (Opus) | — | All modes |
| 13 | Add "related unresolved items" to each page | Sub (Sonnet) | Parallel per page | All modes |
| 14 | Iterative review reflection (question loop → reflect in all related documents) | Parent + Sub | Review units are serial / reflection is parallel | Iterative reflection mode recommended |
Model assignment policy
| Purpose | Model |
|---|---|
| Figma JSON → Markdown formatting (Step 2 / 3 / 8 / 11 / 0.5 / 14c) | Sonnet |
| Synthesis/abstraction (Step 4 / 5) | Opus |
| Design decisions (Step 7 / 10) | Opus |
| Review judgment (Step 6 / 9 / 12) | Opus |
| Question loop design (Step 14a / 14b) | Opus |
Step details
Step 0: Preparation
- Confirm with the user:
- Figma URL (request if not available)
- Project goal (required for use in review)
- Output directory (default
docs/） - Destination (if Notion etc., switch relative path links to the "{{filename}} (separate page)" notation)
- Implementation mode: If an existing repository (
Gemfile/package.json/app//src/) exists in the working directory, proposeextension. Otherwisenew
- Extract
fileKeyfrom the URL docs/pages/とdocs/reviews/Create- Check whether an existing
docs/exists, and confirm whether overwriting is allowed - Save the project goal at the beginning of
docs/reviews/coverage-review.mdSave at the beginning of extensionIf in mode, execute Step 0.5
Step 0.5: Existing codebase investigation (extension mode only)
For details, see references/extension-mode-guide.md .
Investigate the main assets of the existing repository with one Sonnet sub-agent, and output todocs/existing-codebase.md :
- Existing model list (with 4-level evaluation of Figma relevance)
- Existing routing (Figma-related only)
- Existing view assets
- Existing settings (Settings etc.)
- Summary of reuse candidates(the most important section referenced in Step 7 / 14)
For the sub-agent prompt, see the Step 0.5 section of references/sub-agent-prompts.md .
Step 1: Page list extraction
figma-useLoad the skillFigma:get_metadataEnumerate all pages/top-level frames withuse_figmaor- Determine the implementation targets (exclude slices and annotation bands)
- Automatic canvas size detection:
- Aggregate the width of all pages subject to implementation, and if there is only one unique value → determine it as "single-width design (mobile-oriented)" and automatically append to "Unconfirmed / Additional Information Required" in the README
- If there are two or more unique values → determine it as responsive-ready
- Detection of the presence of prototype Reactions:
- If there are zero Reactions → determine it as wireframe level
- Only some are set → mixed mode
- Determine the slug for each page
docs/pages/README.mdCreate the skeleton of (cross-cutting summary will be appended in Step 6)
Step 2-3: Per-page structure and action extraction (parallel)
Launch Sonnet subagents in parallel per page. For prompt details, see references/sub-agent-prompts.md .
- Step 2: Component list table, text elements, page role overview (objectively extractable)
- Step 3: Action button list (with source column, with vocabulary restrictions)
Step 4: Use case extraction
docs/pages/ Read all of and list explicitly readable UCs in docs/use-cases.md . In hybrid mode, insert a summary check.
Required fields for each UC: UC-XX / use case name / use case category / purpose / scenario / preconditions and subsequent UC / whether data is updated.
Step 5: Actor extraction + UC×Actor matrix
docs/use-cases.md Aggregate the actors appearing from and generatedocs/actors.md .
- Required fields for each actor: A-XX / name / classification (primary, secondary, offstage) / role / goal / typical pain points / main operations / UC list
- UC×Actor matrix required(rows=UC, columns=all actors, involvement is "●")
- Immediately after the matrix, add "readable facts" in prose
Step 6: Consistency review + cross-cutting summary append
6a: Consistency review (output only)
docs/reviews/coverage-review.md List the following in :
- UCs / Actors that are missing from the goal perspective
- Pages / Action Buttons that are missing from the UC perspective
6b: Cross-cutting summary append (pages/README.md)
- Common elements (Header / Footer / Menu Overlay)
- Interaction distribution across the entire site
- Implications for entity / data design(input for Step 7)
- Unconfirmed / Additional Information Required
Step 7: Data model extraction
docs/pages/README.mdRead the "Implications for entity / data design" section of (starting point for Step 7)docs/pages/Read all of- In extension mode:
docs/existing-codebase.mdRead "Existing model list" and "Summary of reuse candidates" in - Classify explicitly readable Entity / Relation
docs/data-model.mdGenerate (state transition section and design notes required）- Check Entity list summary in hybrid mode
Avoiding over-definition
"Generic Entities for which no corresponding page/display element exists in Figma" (StaticPage、User、Session etc.) are not defined in the main body, and are only proposed on the review side.
Design priority order in extension mode
- Reuse existing model as-is
- Add columns to existing model
- Repurpose existing columns (Must confirm presence/absence of conflicts by grepping the actual code）
- Create new Entity
For details, see the "Step 7 Extension" section of references/extension-mode-guide.md .
Step 8: Append model references to each page (parallel)
Launch Sonnet subagents in parallel per page. For details, see references/sub-agent-prompts.md .
Responsibilities of the parent agent
- Advance preparation:
data-model.mdExtract the list of usable Entity / column IDs from and include it in the subagent prompt (to prevent fabrication of items outside the list) - Post-verification:
grep "^## 参照モデル" docs/pages/*.mdConfirm that there is exactly one hit per page with
Aggregation rules (redundancy reduction)
- Aggregate multiple display elements that reference the same column
- Combine static text into one line
- Target for the number of lines per section is within 8 lines (to ensure readability）
Step 9: Data model review (output only)
docs/reviews/data-model-review.md List the following in (Priority labels "Required / Recommended / Optional" are mandatory）：
- There is a display element on the page but no corresponding Entity / column
- Over-definition of Entity / columns
- FK consistency
- Excess or deficiency of indexes
Step 10: Component extraction
docs/pages/Read all ofextensionIn the case of mode, consider existing UI assets (docs/existing-codebase.md"Existing view assets" in- Classify display elements into Atomic Design (Atoms / Molecules / Organisms / Templates)
- Place a "Commonalization Policy Summary" section at the beginning
- Make the page-to-Organism mapping verification table mandatory(If even one unsupported cell remains, add it)
docs/components.mdGenerate
For details, see the "Step 10 Extension" section of references/extension-mode-guide.md .
Required fields for each component: CMP-XX / name / overview / Atomic Design type / parameter list / event handler list.
Step 11: Append component references to each page (parallel)
Same pattern as Step 8. For details, see references/sub-agent-prompts.md .
Aggregation rules
- Output targets are Organism / Template / major Molecule only(Atoms are omitted because they are included by design)
- Multiple usage locations of the same component are aggregated into "number of usage locations"
Post-verification by the parent agent
grep "^## 利用コンポーネント" docs/pages/*.md
Also verify whether the CMP-XX used on the page components.md actually exists in.
Step 12: Component review (output only)
docs/reviews/components-review.md List the following in (Priority label required）：
- There is a display element on the page but no corresponding component → usually "Required"
- A component is defined but not used → usually "Optional"
- Candidates for consolidating similar components → usually "Recommended"
- Excess or deficiency of parameters/event handlers → classified by content
Step 13: Add "related open issues" to each page (parallel)
Read the three reviews and extract missing items related to the current page by reverse lookup.
Extraction rules:
- The current page is mentioned in coverage-review's "Missing Page / Action"
- The current page slug appears in data-model-review's "exists on page but not in model"
- The current page slug appears in components-review's "exists on page but component undefined"
If none apply, write "Not applicable".
Step 14: Iterative review reflection
For details, see references/step-14-review-iteration.md .
Progress checklist (copy and use)
Step 14 進行:
- [ ] データモデルレビュー: 質問ループ完了
- [ ] データモデルレビュー: data-model.md 反映完了
- [ ] データモデルレビュー: pages/ 並列反映完了
- [ ] データモデルレビュー: サマリー再集計完了
- [ ] 整合性レビュー: 質問ループ完了
- [ ] 整合性レビュー: coverage-review.md 反映完了
- [ ] 整合性レビュー: pages/actors/use-cases 並列反映完了
- [ ] 整合性レビュー: サマリー再集計完了
- [ ] コンポーネントレビュー: 質問ループ完了
- [ ] コンポーネントレビュー: components.md 反映完了
- [ ] コンポーネントレビュー: pages/ 並列反映完了
- [ ] コンポーネントレビュー: サマリー再集計完了
- [ ] 最終サマリーをユーザーに提示
Key points of the question loop
- Process in the order data model → consistency → components Process in the order of
- No more than 4 items per round（
AskUserQuestion(due to the tool's question limit) - Consolidate related items into 1 question(e.g., consolidate 6 ON DELETE behavior items into 1 question)
- Do not ask about Figma-undefined/design-pending items; attach a "design pending" label
Implementation pattern for parallel launch
Per-step parallel launch is achieved by arranging multiple Agent tool calls within 1 message :
// Step 2 並列起動の擬似コード
const pages = ["top", "award-detail-open", ...];
const agents = pages.map(p => Agent({
description: `${p} 構造抽出`,
subagent_type: "general-purpose",
model: "sonnet",
prompt: extractStep2Prompt(p),
}));
Steps 2 / 3 / 8 / 11 / 13 / 14c are steps that are parallelized per page or per review. Step 0.5 launches a single Sonnet subagent once in extension mode (not subject to parallelization).
Checkpoints for hybrid dialogue
| Timing | Confirmation content | Skip condition |
|---|---|---|
| Step 0 | URL / goal / transcription destination / output destination / implementation mode | All already presented |
| After Step 0.5 | Existing codebase investigation results | In new mode |
| After Step 1 | Extracted page list + canvas size detection results | In fully automatic mode |
| After Step 4 | UC list summary (optional) | In fully automatic mode |
| After Step 7 | Data model Entity list summary (optional) | In fully automatic mode |
| After Step 6 / 9 / 12 | Each review result (with priority labels) | Cannot be skipped |
| After Step 13 | Confirmation of the addition of "Related unresolved items" on each page | In fully automatic mode |
| During Step 14 | Question loop for iterative review reflection | When the user does not want Step 14 |
| After Step 14 | Final summary after reflection | Cannot be skipped (when Step 14 is executed) |
Behavior on error
- Figma MCP unauthenticated →
/mcpprompt authentication with - Node ID error → Check the fileKey part of the URL, ask the user to resubmit
- Subagent failure → Parent retries directly (Sonnet → Opus fallback)
- Output file already exists → Ask the user to confirm overwrite / append / cancel
- Many "Not described in Figma" items → Proceed with the "Not described" notation as is (list them in the review step)
Finishing
After completing all 15 steps (Step 0 to 14. In extension mode, Step 0.5 is included, and Step 14 only if desired),Make final verification mandatory：
Final verification checklist
# 1. 全ページに 6 セクションが揃っているか
for f in docs/pages/*.md; do
if [ "$(basename $f)" != "README.md" ]; then
echo "=== $f ==="
grep "^## " "$f"
fi
done
Expected 6 sections (fixed order):
## 構成要素## テキスト要素一覧## アクションボタン## 参照モデル## 利用コンポーネント## 関連する未解決事項
Entity / CMP consistency verification
grep -ho "E-[0-9]\+" docs/pages/*.md | sort -u > /tmp/used_entities.txt
grep -ho "E-[0-9]\+" docs/data-model.md | sort -u > /tmp/defined_entities.txt
diff /tmp/used_entities.txt /tmp/defined_entities.txt
If an ID used on a page is not in the master, there is a high possibility that a subagent fabricated the number. Re-execute the relevant page.
Additional verification when Step 14 is executed
# 解消マークが付いた項目数を確認
for f in docs/reviews/*.md; do
echo "=== $f ==="
grep -c "解消済み" "$f"
done
# 取り下げ ID の能動的参照（取り下げ説明以外）が残っていないか
grep -rn "{{取り下げた ID パターン}}" docs/pages/ docs/actors.md docs/use-cases.md | \
grep -v "取り下げ\|統合\|解消済み\|旧\|~~"
Completion report
- List of generated files and the line count of each file (in extension mode,
docs/existing-codebase.mdis also included) - Summary of the 3 review reports (number of deficiencies detected + counts by priority)
- When Step 14 is executed: Number of resolutions in the specification confirmation iteration process, and the nature of remaining items (waiting for Figma design / future requirements)
- Mandatory items the user should handle manually
- Final verification result (sections complete, ID consistency OK)
Related skills and reference files
Skills
figma-use—use_figmaMust be loaded before calling MCP tools (included in the official Figma plugin)
references/ directory
extension-mode-guide.md— Detailed guide for Step 0.5 / 7 / 10 in extension modestep-14-review-iteration.md— Complete process for iterative review reflectionsub-agent-prompts.md— Prompt templates for subagentsoutput-templates.md— Framework for the output Markdown