migrate-component-docs-from-figma

Migrate Docs from Figma

Extract content from Figma documentation layers and produce SEED Design component guideline MDX files.

Inputs

Two inputs are required:

1. Figma node URL(s): The URL(s) of the Figma layer(s) to document. Ask the user if not provided.
2. File name: The MDX file name (e.g., radio, action-button).

Target file: docs/content/components/{file-name}.mdx — the directory is flat and listed alphabetically (category subfolders were removed in #1712).

Step 1: Extract content from Figma

Call get_node_info on each provided Figma node URL to retrieve text content.

• Always use get_node_info (singular) — it accepts figmaUrl directly. Do not use get_nodes_info (plural), which requires a separate fileKey + nodeIds and does not accept URLs.
• If multiple URLs are given, dispatch subagents in parallel — each calls get_node_info and returns the structured result.
• Identify structure in the extracted text: headings, body paragraphs, tables, Do/Don't pairs, etc.

Step 2: Write the MDX

Convert the extracted content into MDX. Leave all image IDs empty for now.

Read references/patterns.md before writing — it contains the MDX component patterns and formatting rules to follow.

Key principles:

• Never add content that is not present in the Figma source in this phase. All body text — descriptions, guidelines, table entries — must come directly from the extracted Figma content. Do not paraphrase, interpret, or add supplementary explanations.
• Bold text from Figma becomes **bold** in markdown.
• Use markdown tables where the content fits a tabular format.
• Always hyperlink other components when mentioned: [Bottom Sheet](/components/bottom-sheet)
• Place FigmaImage after body text, not directly under headings. The correct order within each section is: heading → body text → image. This lets readers understand the context before seeing the visual.
• Follow the standard heading order: Anatomy → Properties → Guidelines → Comparison → V3 Changes → Specification (include only applicable sections).
• Write in Korean. Use official English names for component names and technical terms.
• Use polite tone ("~합니다", "~해 주세요").

Step 3: Map image IDs

Use the find_nodes tool to search for child nodes matching the Document / Image pattern:

find_nodes(name: "Document / Image", nodeId: "{parent layer ID}")

Insert the collected IDs sequentially into the empty id="" / figmaId="" fields from Step 2.

If the number of found IDs does not match the number of empty placeholders, ask the user before proceeding. The mapping may be ambiguous.

Step 4: Review the document

Run through this checklist:

Structure

• PlatformStatusTable is present at the top
• ComponentSpecBlock is present at the bottom for every related rootage spec in /packages/rootage/components/
• Markdown syntax is correct (table alignment, list nesting, etc.)

Terminology

• Component names use official English names (e.g., "Bottom Sheet" not "바텀시트")
• No spelling errors or awkward sentences
• No logical errors (e.g., Component A's description appearing in Component B's doc, duplicate content)

Cross-references

• Other components are hyperlinked when mentioned
• Design tokens are properly referenced (hyperlink to foundation page, or TokenReference component)
• All internal links are valid — verify that href targets in Card, component links (/components/...), and token links (/docs/foundation/design-token/...) point to pages that actually exist by checking the corresponding MDX files under docs/content/

Platform references

• If platform-specific references (Figma, Web/React, iOS, Android) are found, flag them to the user

Reference docs

Use these as examples of well-written docs:

• docs/content/components/radio.mdx — Do/Don't, Grid, Card patterns
• docs/content/components/action-button.mdx — Properties, Guidelines, Comparison patterns