Wireframe Maker

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
G1Numbers are numbers. Every coordinate and size is a JSON number, never a string.
G2Nothing is silently dropped. An unrecognised control type is preserved with unsupported: true; an unrecognised field is preserved verbatim.
G3Unknown 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.
G4Deletion is a tombstone. Objects carry deletedAt; they are removed only by an explicit purge.
G5IDs 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.
G6Absent 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": { }
}
FieldNotes
pathFolder ancestry as real structure, not a naming convention
orderFloat sort key, so a screen can be inserted between two others without renumbering
underlayA sketch or PDF page traced over; purely a background
meta.dividertrue 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"
}

control in other versions (G5).

to the parent.

is omitted for back.

Text markup

props.text carries inline markup, kept verbatim rather than parsed into a tree:

SyntaxMeaning
*text*Bold — adds to the control's base weight, never removes it
\nLine 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 }
}

version deletes that screen**.

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

FormLayout
BundleOne .wfm.json; assets inlined as data URIs
Unpackedproject.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.