Fanta projects and .fant snapshots
Understand the editable project directory, variant-set layout, and single-file snapshot format.
The working Fanta document is a directory containing fanta.json. Pages, component masters, shared data, and assets are separate files that can be reviewed in Git.
Project layout
| Path | Contains |
|---|---|
fanta.json | Project identity and layout version |
pages/<page>/page.json, page.fnx, page.ids.json | Page header, editable tree, and identity sidecar |
components/<component>/def.json, master.fnx, master.ids.json | A standalone component's definition, editable master, and sidecar |
components/<set>/set.json | One variant set's axes, values, and default variant |
components/<set>/<variant>/def.json, master.fnx, master.ids.json | Each variant's definition, editable master, and sidecar |
doc/variables.json and related files | Tokens, modes, metadata, motion, and prototype state |
doc/asset_library.json | Names and kinds of reusable project media, including unplaced assets |
assets/ | Source binary assets with an integrity index |
AGENTS.md, fanta.md, fnx.d.ts | Project editing guide, design brief, and FNX editor declarations |
exports/ | Derived visual exports, ignored by Git |
Current projects use layout version 5. A component with variants is one set folder; its variant folders are named from axis values, such as components/button/primary-hover/. A component without variants remains directly under components/. Folder slugs can change when names or variant values change; IDs in headers and FNX identify the designs. Commit the manifest, source, sidecars, design brief, shared data, and referenced media together.
The current app reads version 4 projects, where variants were separate top-level component folders and sets were collected in components/sets.json. The next save moves the variants into their set folder, writes set.json, removes the old registry, and changes the manifest to version 5. Earlier layout versions also remain readable. An older app that supports only version 4 or earlier rejects a version 5 manifest, so collaborators should update before an upgraded project is shared.
Use the canvas or structured operations to create and change variant sets. combine_variants, add_variants, remove_variant, arrange_variants, and rename_component keep set metadata and component references together. Do not rename a component by changing only def.json: FNX instances can refer to components by name, and a partial rename can prevent the project from loading.
Fanta saves canvas changes back to project files. It watches for external edits and branch changes, uses atomic file replacement and a transaction journal for multi-file updates, and reports invalid source or overlapping edits. Structural canvas saves retain authored FNX fields and child comments on surviving nodes; if an operation would lose source-only data that Undo could not restore, Fanta reports a preservation error. The Code workspace edits the active page or component FNX and its companion JSON header when the canvas is clean. Both source types are validated against the complete project before a save updates the canvas. Modern FNX with explicit IDs can recover a missing or damaged identity sidecar; older FNX without explicit IDs still needs it.
Unchanged generated design files are not rewritten. Save and external-change checks still inspect project files for integrity, so a very large project may take longer even when a small part changes. If another process writes the same path between Fanta's check and rename, Fanta's watcher or transaction recovery may report a conflict; review the result before continuing.
A received project folder may open in Restricted Mode when it contains project-local configuration or Git metadata that could run commands. The signed Build45 app checks a .zed configuration directory; current source checks .fanta. Current source reads project settings, tasks, and debug configuration from .fanta/, with no verified automatic migration of a legacy .zed/ folder. Review the folder's origin and configuration before enabling project features. Keep its Git history intact; removing it or trusting every project globally is not needed to review the design.
Save As
Choose File → Save As… to copy the current design and assets into a new local folder. The open document then saves to that copy while the original remains available. The destination must be new and separate from the original or another project. Finish an active canvas preview and save or discard unfinished FNX edits before using Save As.
The .fant format
A .fant file is a single-file design snapshot. The format handler can import and export the document together with its assets. Opening a snapshot materializes an editable Fanta project; the original snapshot is not the live, versioned working document.
The format library supports writing .fant snapshots, but the editor controls confirmed in the current app expose PNG, JPG, SVG, and PDF visual exports. For routine handoff, share the editable project directory or a visual export according to the recipient's needs.
See FNX source and visual export.