# Figma Android Xml

> Claude Code skill: high-fidelity Figma-to-Android XML restoration via Figma MCP, with 22 battle-tested pitfalls

- **Type:** MCP server
- **Install:** `agentstack add mcp-jahonn-figma-android-xml`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jahonn](https://agentstack.voostack.com/s/jahonn)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jahonn](https://github.com/jahonn)
- **Source:** https://github.com/jahonn/figma-android-xml

## Install

```sh
agentstack add mcp-jahonn-figma-android-xml
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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//?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](https://github.com/jahonn)
- **Source:** [jahonn/figma-android-xml](https://github.com/jahonn/figma-android-xml)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jahonn-figma-android-xml
- Seller: https://agentstack.voostack.com/s/jahonn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.