Wireframe Maker format specification
Format: wireframe-maker · Version: 1 · File extension: .wfm.json
This document is normative. The format is deliberately simple enough to read, write, and diff without this application — that is the point of it existing.
A design document is a semantic model, not a drawing. Fidelity is a rendering choice, not a property of the document.
1. Guarantees
A conforming reader/writer must uphold these. They are what makes the format safe to build on:
| # | Guarantee |
|---|---|
| G1 | Numbers are numbers. Every coordinate and size is a JSON number, never a string. |
| G2 | Nothing is silently dropped. An unrecognised control type is preserved with unsupported: true; an unrecognised field is preserved verbatim. |
| G3 | Unknown fields survive a round-trip. A v1 reader loading a v1.x file written by a newer tool must not strip fields it does not understand. |
| G4 | Deletion is a tombstone. Objects carry deletedAt; they are removed only by an explicit purge. |
| G5 | IDs are stable and shared across versions. The same control keeps one id in master and in every override — this is what makes structural diffing possible. |
| G6 | Absent means inherit. A missing property means "use the skin default"; it never means a concrete value such as white or zero. |
2. Top level
{
"format": "wireframe-maker",
"version": 1,
"project": { },
"screens": { },
"versions": { },
"assets": { },
"components": { },
"tree": [ ],
"comments": [ ]
}
format and version are required. components is optional. All maps are keyed by the object's own id.
project
{
"id": "prj_1a2b",
"name": "YepiPet App",
"description": "optional",
"settings": {
"skin": "sketch",
"fontFace": "Balsamiq Sans",
"fontSize": 13,
"linkColor": "#2b79a4",
"selectionColor": "#2b79a4"
},
"variables": { "petName": "Juno", "owners": ["Ada", "Sam"] }
}
skin is sketch or clean — a rendering choice, not content. variables resolve {placeholder} tokens found in control text; a value may be a string or a list of strings.
3. Screens
{
"id": "scr_a1b2",
"name": "Notification E-Mail",
"path": ["Pet", "Share"],
"order": 237893.179,
"notes": "optional free text",
"canvas": { "width": 1024, "height": 900, "device": "phone" },
"underlay": { "asset": "ast_x1", "opacity": 0.35, "locked": true },
"controls": [ ],
"meta": { }
}
| Field | Notes |
|---|---|
path | Folder ancestry as real structure, not a naming convention |
order | Float sort key, so a screen can be inserted between two others without renumbering |
underlay | A sketch or PDF page traced over; purely a background |
meta.divider | true marks a section separator rather than a real screen |
Screen metadata (name, path, order, trash) lives on the master screen. Screen content (controls) is what versions override.
4. Controls
{
"id": "ctl_0009",
"type": "SubTitle",
"x": 304, "y": 449, "w": 138, "h": 28,
"z": 9,
"locked": false,
"autoSize": true,
"unsupported": false,
"link": { "target": "scr_home", "mode": "navigate" },
"props": { "text": "Muchi (2 Yr)" },
"children": [ ],
"meta": { },
"copiedFrom": "ctl_0003"
}
idis unique within a resolved screen, and is shared with the same
control in other versions (G5).
zascending renders in front. Ties render in array order.childrenappears on groups. Child coordinates are absolute, not relative
to the parent.
link.modeisnavigate,overlay, orback;targetis a screen id and
is omitted for back.
Text markup
props.text carries inline markup, kept verbatim rather than parsed into a tree:
| Syntax | Meaning |
|---|---|
*text* | Bold — adds to the control's base weight, never removes it |
\n | Line break |
{name} | Substituted from project.variables; left visible when unresolved |
Multi-item controls
ComboBox, List and DataGrid rows are newline-separated. ButtonBar, TabBar and Alert buttons are comma-separated. selectedIndex picks the active item.
Colours
#rrggbb strings. On buttons, color is the fill; the label uses textColor, or automatic contrast when absent.
5. Versions
A version stores only the screens it changes.
{
"id": "ver_yepitag",
"name": "v2.7.0-YepiTag",
"status": "candidate",
"basedOn": "master",
"createdBy": "claude",
"createdAt": "2026-08-17T09:00:00Z",
"overrides": { "scr_a1b2": { }, "scr_c3d4": null }
}
statusisactive,candidate,archived, orrejected.overrides[screenId]holds a full replacement screen, ornullmeaning **this
version deletes that screen**.
- The base version has id
masterandisBase: true.
Resolution — the whole versioning model in one line:
resolve(screen, version) = version.overrides[screen] ?? base.screens[screen]
An override of null resolves to "not present in this version".
6. Components
{
"id": "cmp_nav",
"name": "Nav bar",
"w": 200, "h": 40,
"controls": [ ]
}
Component-local control coordinates are relative to the component origin. An instance is a control of type __instance__:
{
"id": "ctl_x", "type": "__instance__", "component": "cmp_nav",
"x": 100, "y": 50, "w": 200, "h": 40, "z": 5, "props": {},
"instanceOverrides": { "c2": { "text": "Overridden" } }
}
Instances expand at render time: children are placed at the instance origin, scaled if the instance is resized, given ids of the form instanceId~childId, and per-instance property overrides applied. An instance whose component is missing must still render as a placeholder (G2).
7. Assets, tree, comments
{ "id": "ast_c3d4", "name": "avatar.jpg", "mime": "image/jpeg",
"width": 400, "height": 300, "hash": "1f4a2c9e",
"src": "data:image/jpeg;base64,…" }
src is a data URI in bundle form, a relative path in unpacked form, or a URL.
"tree": [
{ "type": "folder", "name": "Pet", "children": [ { "type": "screen", "id": "scr_a1b2" } ] },
{ "type": "divider", "name": "v2.5: Medical Records", "screen": "scr_div1" }
]
{ "id": "cmt_1", "anchor": { "screen": "scr_a1b2", "control": "ctl_9", "version": "ver_x" },
"body": "Tap target looks small", "resolved": false, "replyTo": "cmt_0",
"createdBy": "claude", "createdAt": "2026-08-17T09:00:00Z" }
A comment anchors to a control, or to a region {x,y,w,h}, or to the screen.
8. Common fields
Every object may carry attribution and tombstone fields:
{ "createdBy": "user-id", "createdAt": "ISO-8601",
"modifiedBy": "user-id", "modifiedAt": "ISO-8601",
"deletedAt": "ISO-8601", "deletedBy": "user-id" }
User ids are opaque strings. claude is reserved for AI authorship.
9. Physical forms
| Form | Layout |
|---|---|
| Bundle | One .wfm.json; assets inlined as data URIs |
| Unpacked | project.json + screens/*.json + assets/*.json — one file per screen, so a design change is a readable diff in a pull request |
Both deserialise to the identical logical document.
10. Versioning of the format itself
version is an integer. A reader encountering a higher version must still attempt to load, preserving unknown fields (G3), and should warn rather than refuse. Breaking changes increment the integer; additive changes do not.
11. What this format deliberately does not have
Stated so that implementers do not wait for it: no auto-layout or constraint system, no freeform vector paths, no per-pixel styling, and no way to express a Balsamiq .bmpr round-trip. Import from .bmpr is one-way by design.