Figma Android Xml

figma-android-xml

A Claude Code skill for generating high-fidelity Android XML layouts from Figma designs via the Figma MCP server.

[简体中文](./README.zh-CN.md) · English

Why this skill

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.

What it does

When invoked, the skill makes Claude:

1. Inspect first — read colors.xml / dimens.xml / themes.xml, check targetSdk, identify existing custom widgets, before touching any layout
2. Pull from Figma MCP — get_design_context, get_metadata, get_variable_defs, screenshots
3. Output a Design Spec Report (Gate 1) — colors → @color/..., spacing → @dimen/..., typography, layout structure, component mapping, asset list — before writing any XML
4. Generate in order: resources → text styles → drawables → layout XML → minimal Kotlin/ViewBinding
5. Validate with ./gradlew assembleDebug (or single-flavor variant for speed)
6. Iterate via screenshot diff when both Figma and device screenshots are available

Quick start

Install as a Claude Code skill

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

Prerequisites

• Claude Code (or any platform that loads SKILL.md skills)
• Figma MCP server connected
• An Android project with View-system XML (not Compose)

Highlights from the pitfalls catalog

These are the gotchas I've seen burn the most time. Full details with symptom / cause / fix in [SKILL.md](./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)

Project structure

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

Invocation examples

/figma-android-xml https://www.figma.com/design//?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 还原差异并修复必要资源和布局。

Contributing

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)

License

MIT — see [LICENSE](./LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jahonn
• Source: jahonn/figma-android-xml
• License: MIT

Install and usage instructions live in the source repository linked above.