A Claude Code skill for generating high-fidelity Android XML layouts from Figma designs via the Figma MCP server.
简体中文 · English
Vibe-coded Figma → Android conversion looks 60% right and breaks in subtle ways: assets that download as SVG-disguised-as-PNG, custom views that flatten gradient-rich designs, setSelected cascades that fail on MIUI, edge-to-edge content that hides under the status bar.
This skill enforces a resource-first, validate-early workflow and ships 22 battle-tested pitfalls harvested from real production work — so the next session catches in one turn what previously took three rebuilds and a session rollback.
When invoked, the skill makes Claude:
- Inspect first — read
colors.xml/dimens.xml/themes.xml, checktargetSdk, identify existing custom widgets, before touching any layout - Pull from Figma MCP —
get_design_context,get_metadata,get_variable_defs, screenshots - Output a Design Spec Report (Gate 1) — colors →
@color/..., spacing →@dimen/..., typography, layout structure, component mapping, asset list — before writing any XML - Generate in order: resources → text styles → drawables → layout XML → minimal Kotlin/ViewBinding
- Validate with
./gradlew assembleDebug(or single-flavor variant for speed) - Iterate via screenshot diff when both Figma and device screenshots are available
git clone https://github.com/jahonn/figma-android-xml.git \
~/.claude/skills/figma-android-xml(or use your platform's skill installation path).
Then invoke in Claude Code:
/figma-android-xml https://www.figma.com/design/... activity_login.xml
- Claude Code (or any platform that loads SKILL.md skills)
- Figma MCP server connected
- An Android project with View-system XML (not Compose)
These are the gotchas I've seen burn the most time. Full details with symptom / cause / fix in SKILL.md.
| # | Pitfall | Why it bites |
|---|---|---|
| 1 | SVG-as-PNG trap | Figma exports vector groups as raw SVG bytes saved with .png extension. BitmapFactory can't decode → blank ImageView. Convert to VectorDrawable XML. |
| 4 | Mask group can't run in XML View system | Figma's alpha mask isn't supported by the View framework. Use Compose, custom view + BitmapShader, or accept the deviation. |
| 7 | match_parent + weight=1 collision |
Mixing both in LinearLayout vertical pushes siblings off-screen on some Android versions. Use 0dp + weight. |
| 8 | targetSdk 35 enforces edge-to-edge |
Activity content slides under status bar. Add fitsSystemWindows="true" on the Activity root, not just fragments. |
| 11 | duplicateParentState is fragile on MIUI/EMUI |
State-list selector + parent setSelected cascade is unreliable across ROMs. Use an explicit Java selectTab(int) helper. |
| 21 | Reading many images in one turn → API 400 | Anthropic's image-processing endpoint hard-errors after ~13+ image reads. Use ls -lhS for verification; Read ≤ 2 images per turn for visual disambiguation only. |
| 22 | MD5 compare doesn't help if format is wrong | If Figma keeps exporting SVG instead of PNG, bytes match across re-downloads. Check PNG header magic bytes first. |
22 pitfalls total, organized by:
- Asset format (1–6)
- Layout / inset (7–10)
- State management (11–12)
- Figma access (13–16)
- Build (17–18)
- Custom view (19–20)
- Workflow & verification (21–22)
figma-android-xml/
├── SKILL.md # The skill itself (loaded by Claude)
├── README.md # This file
├── README.zh-CN.md # 中文版
├── LICENSE
├── checklists/
│ └── xml-review-checklist.md # XML quality gates
└── templates/
├── figma-spec-report.md # Design Spec Report template
└── implementation-summary.md # End-of-task summary template
/figma-android-xml https://www.figma.com/design/<fileKey>/?node-id=34-335 \
activity_login.xml
/figma-android-xml 请根据当前 Figma Frame 实现 res/layout/fragment_product_detail.xml，
XML + ViewBinding，不要用 Compose。
/figma-android-xml 对比 figma.png 和 actual.png，只列出 XML 还原差异并修复必要资源和布局。
Pitfalls are battle scars, not theory. If you hit a Figma-Android failure mode that's not yet documented, PRs are welcome — please include:
- Symptom (the visible failure)
- Cause (what's actually wrong under the hood)
- Fix (a recipe that worked)
MIT — see LICENSE.