FMT-001 The `.design` file format
The .design file: one JSON object with a tree and a write-append list of events, the assets folder, folding, recovery and migrations.
| Product | SoftForge UI Designer (SoftForge.softforge-ui-designer) |
| Document | FMT-001 |
| Status | Draft; review decisions D3, D14, D15, D22 applied |
| Date | 2026-10-10 |
| Owner | Arthur de Araújo Farias |
| Realises | SRS-001 (#1) PLT-2, PLT-3, PLT-4, DOC-3, COL-4, NFR-2, NFR-3, NFR-6 |
| Related | CLI-001 the ud command (#3) · AI-001 agents and skills (#4) · ARC-001 architecture (#5) |
| JSON Schema | schemas/design-1.0.schema.json (section 11) |
A .design file holds one design document: its pages, layers, components, styles, variables, prototype flows,
comments and named versions. The file is plain UTF-8 JSON and lives in a git repository next to the code it
describes. Images and fonts live next to it in a folder named <name>.design.assets/.
This document is the reference of the format. It is written for a developer or an AI agent who has never seen a
.design file. It follows the design of the Project Board file format 2.0 (.pb): a consolidated tree plus a
write-append list of events, one per line. Where the two formats share a rule, the rule is restated here so
that this document stands alone.
Short version for agents.
- Do not edit
tree. Append events towal, one per line, each line starting with a comma (section 5.3). - Give a new event the largest
seqin the file plus one, and never change a line that is already there (section 5.1). - Prefer the
udcommand: it writes correct events for you (CLI-001). Write by hand only whenudis not available. - Property names are the Figma Plugin API names (
layoutMode,itemSpacing,fills,characters, …). Colours are{r,g,b,a}floats from 0 to 1. Lengths are px. Rotation is in degrees. - Ids are a prefix, a hyphen and 12 random lowercase hex digits:
nd-3f9a0c1e7b2d(Appendix A). node.updatecarries a merge patch inset;nullremoves a property (section 5.9).- Unknown fields are kept; unknown operations are skipped with a warning and stay in the file (section 9).
Generated from issue #2 of planning.pb by
scripts/docs-specs.mjs; the board is the source of truth.
Status. Done 2026-10-10. FMT-001 complete with D3, D14, D15, D22 applied; the document now lives in the comments of this issue.
- 1. Terms
- 2. Overview and goalsEvery change, from the editor, the ud command, a usefigma script or an agent, is one or more events appended to the WAL.
- 3. The top-level objectA design file is one JSON object with five members, written in this order:
- 4. The treeEvery member is optional; a missing map is empty.
- 5. The write-append listwal is an array.
- 6. Folding and conflict rulesThe result is the same on the host, in ud and in the webview, because they run the same core.
- 7. ConsolidationThe WAL grows by one line per change.
- 8. The assets folderImages and fonts of login.design are stored in login.design.assets/ in the same directory (PLT-2).
- 9. Tolerant reading and recoveryA design file is edited by the editor, by ud, by agents writing lines by hand, by people in a text editor and by git merges.
- 10. Versions and migrationsdesignVersion is "<major>.<minor>".
- 11. JSON SchemaThe format is published as a JSON Schema, draft 2020-12 (PLT-4):
- 12. A complete examplelogin.design: a "Screens" page with a login frame in vertical auto layout, a "Components" page with a button component, a theme collection with two modes and two variables, a text style, an instanc…
- Appendix A. Identifier prefixesIds are a prefix, a hyphen and 12 random lowercase hex digits, except where noted.