Migrating from Balsamiq
How to move a .bmpr archive into Wireframe Maker, and what to check afterwards. Import is one-way by design: nothing writes back to .bmpr.
1. Import
node scripts/import-bmpr.mjs "My Project.bmpr" projects/my-project.wfm.json
Output looks like this (a real run against a six-year-old 170-screen archive):
Imported YepiPet.App-v2.7
170 screens (13 dividers, 8 trashed→tombstoned) · 86 versions (0 branch-only screens) · 87 assets (0 duplicates merged)
52123 controls · 45 types · 157 distinct icons
- Image references unknown asset 37CCA6EC-84AA-4F06-850A-47FF0A89B65E
Wrote projects/my-project.wfm.json (18.9 MB)
The
86 versionsline counts alternates only — the non-master branches. Elsewhere you may see 87 for the same archive, which counts every branch including master. Both are right; they answer different questions.
Read the report. It is the audit trail for the migration:
| Line | What to check |
|---|---|
| screens / versions / assets | Matches what Balsamiq shows you |
| controls / types | If any type is listed as unsupported, those controls still imported — they render as labelled placeholders |
| warnings | Each one is a real finding. In the example above the source archive itself contains a dangling image reference |
2. Check icon coverage first if you care about fidelity
One in four controls in a typical archive is an icon, so this is the single biggest fidelity risk:
node scripts/icon-audit.mjs "My Project.bmpr" node_modules/font-awesome/css/font-awesome.css
It reports distinct icons, total uses, and any names it cannot resolve. The YepiPet archive scored 99.94% against Font Awesome 4, with four stray FA6-style names that are aliased in src/render/fa4.ts.
3. What is translated, and how
| Balsamiq | Wireframe Maker |
|---|---|
| SQLite archive | JSON document (SPEC.md) |
| Branches | Versions, with sparse overrides kept exactly as-is |
Branch names like v2.7-Backup, Former Official… | Parsed into a real status (active / candidate / archived / rejected); the original name is preserved verbatim |
Date-prefixed names (20210412 Ideas) | createdAt inferred, name kept |
> in screen names | Real folder path |
Screens named -- Section -- | Real divider nodes in the tree |
| Coordinates as strings | Numbers (guaranteed finite) |
| Colours as signed ints | #rrggbb; -1 means "skin default" and is omitted, not turned into black |
icon: {ID, size} | icon + iconSize |
| Base64 images in the archive | Assets, deduplicated by content hash |
| Trashed screens | Tombstones (deletedAt) — recoverable, not deleted |
| Unknown control types | Preserved with unsupported: true |
4. Verify
The strongest check is the one the importer's own test suite runs: control census in equals control census out, counted through nested groups and every branch override. If you want to run it against your file, point the fixture at it:
cp "My Project.bmpr" fixtures/yepipet-v2.7.bmpr # or edit the path in the test
npm test -- bmpr
Then open the app and spot-check ten or fifteen screens against Balsamiq side by side. Fidelity issues are rendering bugs, not data loss — the census already proved the data arrived.
5. What does not come across
- Balsamiq Symbols. No archive we have tested uses them (the YepiPet archive
has zero), so there is no import path. Use Components instead — extraction is two clicks and instances update live.
- Thumbnails. Regenerated, not imported.
- Balsamiq Cloud comments and project metadata beyond what the file contains.
6. After migrating
Commit the JSON. That is the moment the migration is real:
git add projects/my-project.wfm.json
git commit -m "Migrate design archive to open format"
From here the file is yours: diffable, scriptable, and readable without this application or any other.