figma-android-xml

# figma-android-xml A [Claude Code](https://claude.com/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 ```bash 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](https://www.figma.com/blog/introducing-figmas-dev-mode-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/<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 还原差异并修复必要资源和布局。 ``` ## 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).