/master.fnx` for a variant set in layout v5), document state under `doc/`, and an `assets/` tree. `doc/asset_library.json` records named media even before placement; `doc/motion.json` holds authored motion data. New projects seed `AGENTS.md`, a project-local `fanta.md` design specification, and FNX helper files without replacing a customized specification. `exports/` and previews are output paths, not the source of truth. [Project structure and source rules →](/docs/concepts/document-model)
Structural canvas saves retain authored FNX attributes on surviving nodes and source comments when supported. A deletion or type change that would silently lose source-only data can make Save refuse the change with a preservation error. Saved files remain intact, but the live canvas edit may remain until Undo; edit FNX directly to remove that data intentionally. [Source preservation →](/docs/concepts/fnx-design-as-source)
On direct-download macOS, a fresh `.fig` import stages a complete sibling project before publishing it; if that first publication fails, the parsed design stays open for a save retry. Existing project saves use the transaction journal, and unchanged generated design files are not rewritten. A received project with project-local settings or executable Git configuration can open in **Restricted Mode** until you review and trust it. The signed Build45 app checks `.zed` settings; current source checks `.fanta`. [Import →](/docs/formats/figma-import) · [Project format →](/docs/formats/fant)
## Edit by hand [#edit-by-hand]
### Canvas and organization [#canvas-and-organization]
* Select, marquee, pan, zoom, resize, rotate, nudge, duplicate, group, frame, and ungroup layers. Snapping uses the grid and edges or centers in the active page or opened component subtree; a different page does not attract the drag. A Select gesture cancels its pending move if its mouse press is lost. Scale selected content proportionally; the inspector also exposes rotate, flip, align, distribute, and Tidy up for eligible selections. Duplicating a component or complete variant set carries its definitions and internal links. Same-document Paste reuses live definitions, or restores captured definitions with new IDs if the originals were removed. Cut, Delete, and Duplicate respect layer locks; Paste validates component dependencies before applying a change. [Canvas tools →](/docs/editor/tools)
* Create and manage pages. The layers panel supports selection, renaming, nesting, order changes, visibility, and locking. [Pages and layers →](/docs/concepts/pages-world-space)
* Draw frames and sections, shapes, arrows, text, vector paths, and freehand marks. Edit path geometry, and convert a suitable single vector path into **Text on Path**. Double-click can edit selected text or vectors, crop an image, drill into a container, or reveal properties, depending on the node. Rounded ancestor clips exclude invisible child artwork from authoring hits. Editable Design Crop shows Ratio, Cancel, and Apply controls; Apply commits a pending crop as one undoable change. Its controls have narrow-canvas insets in Build45 source, though this exact layout lacks a separate installed-app check. Right-click exposes applicable edit, structure, and component actions. [Canvas tools →](/docs/editor/tools), [Vectors and text paths →](/docs/concepts/vectors-icons-svg)
* Paste bitmap images, or use the local picker to place supported raster images and MP4 video. Editable SVG can come from Project Assets or a supported generation result; audio is placed from Project Assets. Canvas copy and paste of design layers can cross pages within one document; a cross-document canvas paste is explicitly rejected. [Media and import →](/docs/formats)
* Open **Assets** in the file inspector to reuse stored images, SVG, MP4, or audio across pages. Generated results can be added to the project before placement. [Project Assets →](/docs/editor/assets)
### Inspect and style [#inspect-and-style]
The inspector includes position, size, rotation, corner properties, opacity, blend, fills, strokes, typography, effects, layout, component controls, interactions, and export settings. The exact controls depend on what is selected. The image and video paint source chooser lists compatible project media and refreshes after asset, layer, Undo/Redo, or project reload changes. **Select matching layers** finds same-kind descendants on the active page; Sections match Sections rather than ordinary Frames or Groups. An editable TextPath layer offers **Edit object** for inline text editing. Bound paints and supported node properties display values resolved through the active variable mode. **Detach** bakes a bound fill’s current color for direct editing. Independent corner values remain separate, and mixed selections show mixed values; some mixed-value edits commit when the gesture ends rather than previewing live. During a dirty source draft, one selected layer’s accepted properties remain readable while writes stay locked. Constraint data persists, but constraint controls are disabled in the default Design inspector. [Inspector →](/docs/editor/inspector)
Current source commits a valid focused numeric property draft before Save, Save All, or closing with Save, and rejects an invalid draft without discarding it. Merely focusing a rounded X/Y display preserves its underlying fractional value; typed fractional TextPath X/Y edits follow painted bounds under transformed parents. These paths have bounded tests; the signed Build45 recording is not a general acceptance test for them.
Frames support horizontal, vertical, and grid auto-layout, child sizing, alignment, wrapping, and size constraints. Grid tracks can use fixed, fractional, or content-sized values, and children can be pinned to cells; Figma grid behavior still has gaps, including auto rows and spanning-child sizing. Components and instances support reusable masters, variant sets, properties, and instance values. A project variant set can appear as one frame on the first visible page and has one source folder containing its variants. Instance actions resolve the visible member from the set default, overrides, and active variable modes. Detach preserves supported appearance and refuses combinations it cannot preserve. Variable collections support modes, aliases, typed values, and property bindings. Agents can edit these structures through the live operation surface, including fill and effect stacks, per-side and dashed strokes, constraints, and shapes. Effects beyond drop/inner shadows and layer/background blur remain unsupported. [Auto-layout →](/docs/concepts/auto-layout) · [Components →](/docs/concepts/components) · [Variables →](/docs/concepts/variables)
Instance text exposed through a component property can use the placed instance’s active variable mode. A direct text-content variable binding stays authoritative and is read-only in instance text editing; change the variable or binding instead. **Go to main component** uses the currently resolved variant member and pauses scope navigation while source edits are pending. [Components and instances →](/docs/concepts/components)
### Prototype, animate, and discuss [#prototype-animate-and-discuss]
Fanta has prototype interactions and preview surfaces. Closing an interaction detail keeps its interaction; **Remove** deletes it. Motion mode supports clips, tracks, keyframes, playback, typed Current time seeking, and guarded auto-keyframe editing; time comments can anchor feedback to a point in an animation. [Prototyping →](/docs/concepts/prototyping) · [Motion →](/docs/editor/motion)
Canvas comments support pins, replies, mentions, attachments, and resolution. Comments and page-bound measurements or developer annotations are saved with project metadata. They are project-local, not live multiplayer comments. [Comments and surfaces →](/docs/editor/surfaces) · [Dev mode →](/docs/editor/dev-mode)
### Dev inspection [#dev-inspection]
Dev mode switches to a read-only inspection session for art and Code source. It offers layer inspection, measurements, annotations, and Saved Code for handoff. Measurements and annotations remain editable page marks. The **Readiness** control is currently unavailable. [Dev mode →](/docs/editor/dev-mode)
## Work with agents [#work-with-agents]
**External agents.** Fanta's local MCP server is enabled by default and can be turned off in Settings. With a design open and the server running, the `fanta --mcp-stdio` bridge connects clients such as Claude Code and Codex to the focused design. The committed server registers **13 tools**:
| Tool | Purpose |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_editor_state` | Focused page or component, selection, bounds, and placement hints. Its component preview is capped at 100; `component_count` and `more_components` signal when to page the design system. |
| `get_guidelines` | Design guidance and the project's `fanta.md` context. |
| `get_design_system` | Component properties, variants, variable collections, modes, values, and bindings. One `offset`/`limit` independently pages components, sets, and variables (default 100, maximum 200); follow each `more_*` flag. |
| `prepare_design_asset` | Open an image or SVG generation draft for user review; it does not submit generation. |
| `batch_get` | Read nodes and geometry; page large results with `offset` and `limit`. A page listing may traverse at most 1,000 nodes and each response is capped at 256 KiB. Choose `summary`, projected `style`, or `raw` detail (raw requires exact IDs). |
| `batch_design` | Stream 43 typed creation, layout, styling, variable, and component operations. Content edits form one undoable batch; selection- or viewport-only batches create no content undo step. Optional activity identifies the editing agent. |
| `get_screenshot` | Inspect a rendered page or node, optionally at a Motion clip playhead. |
| `read_fnx_source` | Read a bounded slice of a project's source. |
| `validate_fnx_source` | Validate a complete FNX or supported project JSON candidate without writing it. |
| `import_image` | Store an image from a path, HTTP(S) URL, or encoded source in Project Assets. |
| `list_comments` | Read comment threads on a page. |
| `reply_comment` | Reply to a thread and optionally resolve it. |
| `report_agent_activity` | Show a named agent's current page, node, source file, or workspace focus in the local app. |
The connection command copied by the running app includes its executable and instance data directory. Activity reports can follow an agent across the Canvas, Variables, and Code workspaces; idle reports expire. They are not cross-agent locks or networked collaboration. [Connection guide →](/docs/getting-started/connect-an-agent) · [Tool reference →](/docs/tools)
**In-app agent.** The docked Agent Panel can inspect and edit the canvas through native design tools. It has review and planning modes, design comments, project image import, and activity reporting paths. A completed Plan can offer **Apply plan**, which switches to Write and sends the plan for implementation. In current source, a native Agent turn stops after 64 model requests, including continuations and agent-managed retries, while completed work remains; this is not a credit limit and is not claimed as an installed Build45 check. The separate **Build** editor mode uses a signed-in v2 agent to turn a brief into tasks, preview each canvas result, and let you Accept, Retry, Skip, or Stop; optional automatic acceptance is available. Native specialist agents can share the lead chat's reference images with supported models. The managed provider reads chat models and credit estimates from a signed-in catalog; other providers can be configured. Its `evaluate_with_jev` tool requests typed decisions from the hosted service when signed in. The generation workspace can hand a draft design request to the panel for review before sending. [Agents and AI →](/docs/agents)
**Generation workspace.** Signed-in users can search the live catalog for image, video, audio, and vector workflows. Recipes and controls depend on the selected model, including video frames, duration, resolution, and audio options where supported. Results can be previewed, saved, reused as source, or added to Project Assets. Saved uncertain submissions can be retried or recovered before starting another job. Placed images become bitmap layers; supported SVG becomes editable vectors; MP4 becomes video; WAV, MP3, and FLAC become audio layers. Public accounts need sign-in and purchased credits for managed generation. [Media generation →](/docs/agents/media-generation)
**Settings and account.** Settings manages appearance, canvas panels, source editing, model providers, hosted tools, MCP connections, account, billing, and privacy controls. Billing usage charts use rolling 7, 30, or 90-day UTC windows when the service provides data; boundary calendar days can be partial. New purchases use web Billing. Public accounts have no free AI trial or signup credits; hosted AI requires purchased credits. Existing founder exceptions are restricted on the backend. The hosted MCP connections used by Fanta's in-app agent are separate from the 13-tool local canvas server above. A Mac App Store feature build blocks Fanta from launching local agent, MCP, and terminal processes; remote HTTP MCP connections remain available. [Settings and build differences →](/docs/editor/settings)
## Formats and output [#formats-and-output]
| Format or output | Current behavior |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Native project folder | Editable, source-backed, and suitable for Git; Save As creates another copy. Layout v5 groups a variant set and its members under one component folder; older v4 projects upgrade on save. [Details →](/docs/formats) |
| `.fnx` | JSX-like page/component source. Its printer retains finite numeric values, including very small ones, instead of rounding them to zero. Complete candidates can be validated before writing. [Syntax and limits →](/docs/formats/fnx) |
| `.fig` | Opens through an importer and attempts a native sibling project. Supported Boolean operands remain editable; known structure losses receive warnings. Import fidelity and write access vary. [Details →](/docs/formats/figma-import) |
| Images and local MP4 | Supported raster images can be pasted or placed through the local picker; it also places MP4 video, which can be trimmed without changing the source file. [Details →](/docs/editor/assets) |
| `.fant` | A snapshot/container format supported by the format layer; the live editable project is the folder. [Details →](/docs/formats/fant) |
| PNG, JPEG, SVG, PDF | Inspector export for a selection or page, with scale, dimensions, and presets where supported. JPEG uses fixed quality 95 and loses transparency; choose PNG when exact pixels or alpha matter. [Details →](/docs/formats/export) |
## Current limits [#current-limits]
* The documented alpha target is **Apple Silicon macOS**. Other platforms have build scaffolding, but are not supported releases. [Install notes →](/docs/getting-started/install)
* Some visible tools and inspector actions remain incomplete. Fanta reports unavailable actions where possible. Grid auto-layout is implemented with the Figma behavior gaps above; effects are limited to drop/inner shadows and layer/background blur, **Pass Through** has no engine equivalent, and Dev **Readiness** is unavailable. [Editor status →](/docs/editor/tools)
* Large `.fig` imports can be slow and memory intensive. Source reads and node reads have response limits, including a 1,000-node page-listing traversal budget, so agents should page through large documents. [Troubleshooting →](/docs/mcp/troubleshooting)
* In non-Store builds, Fanta prefers its bundled Git and falls back to a system `git` for automatic initialization outside existing repositories. A design still saves if `git init` fails. Automatic initialization is disabled in the Mac App Store feature build. [Version control →](/docs/guides/version-control-designs)
* A generated result over 128 MiB cannot be added to Project Assets. Placing a bitmap is also limited to 32 MiB, 32 megapixels, and 16,384 px per side; the local MP4 picker has a 100 MiB cap. Audio needs a decodable duration and is placed through **Add to project → Assets → Place**, not the direct **Add to design** action. [Project Assets →](/docs/editor/assets)
* Bounded MP3 placement, Save, Undo/Redo, and cold storage checks pass, but cold Audio preview was absent in the checked project. WAV preview and broader audio recovery remain unverified. [Media generation →](/docs/agents/media-generation)
* Source synchronization has conflict handling and save recovery, but an external write to the same path can still race Fanta's check and rename. Fanta keeps the last valid canvas when an external source reload fails and reports the error for repair. Recent changes reduce redundant reloads and preserve unaffected layout geometry, yet large-project Save and some draft-recovery journeys remain under release validation. Keep Git history for important projects. [Source editing →](/docs/concepts/fnx-design-as-source)
* Large-page rendering and native responsiveness remain under validation. Current macOS source normally uses Skia Graphite on Metal and falls back to Ganesh if Graphite cannot start. Retained translation is enabled by default; `FANTA_RETAINED_TRANSLATION=0` disables it. These renderer changes postdate the signed Build45 installer, and bounded checks do not establish a general native drag latency target.
* The Public Alpha release is a direct-download Apple Silicon Mac app. Signed Build45 passed notarization, stapling, bounded installation checks, and an anonymous public download checksum check. The reviewed public workflows use that signed app. Clean-account installation and migration from an older version remain unverified; other Mac architectures are outside this release. Automatic updates are disabled. [Install notes →](/docs/getting-started/install)
* Node graph, generic AI artifact, and embed node types render as placeholders. Existing 3D content can survive unrelated edits and saves, but that does not establish a complete 3D editor.
* Canvas comments and agent cursor presence are local to the open app and project. Real-time multi-user editing and cross-agent locks are not part of the current implementation.
* The current external MCP surface is the 13 registered tools above. Older references to a `:3846` HTTP server, 127 design tools, `cargo run -p fanta-app`, or `save_document` describe a different implementation.
* In current source, app keymap actions use `fanta::` and app links use `fanta://`; the signed Build45 package uses `zed::` and `zed://`. Review custom keymaps and links when a newer installer is available. [Shortcuts →](/docs/editor/shortcuts)
The [alpha issue log in fanta-edit](https://github.com/jeanc18rlos/fanta-edit/blob/9e582bee494b85f54e4dcb4084b5d55acd097d37/docs/alpha/KNOWN_ISSUES.md) records earlier implementation and release observations. Several entries predate the committed features described here. The [release capability coverage report](https://github.com/jeanc18rlos/fanta-edit/blob/9e582bee494b85f54e4dcb4084b5d55acd097d37/docs/alpha/CAPABILITY_COVERAGE.md) records bounded checks and remaining native limits; this map describes implemented source paths. [Installation](/docs/getting-started/install) records the released package separately.
# Demos and examples (/docs/demos)
The launch overview and three recordings below use the accepted signed Fanta 1.0.0
Public Alpha app. These players use silent recordings with captions and load
when you choose Play. Captions identify later checkpoints and reopened views.
Complete, readable workflows matter more than speed.
## Examples [#examples]
### I Asked AI to Recreate Airbnb — Here’s the Result [#i-asked-ai-to-recreate-airbnb--heres-the-result]
A walkthrough from [Fanta Design Editor](https://www.youtube.com/@FantaDesignEditor).
[Watch on YouTube](https://youtu.be/3-dNfeDpgu0)
## The ten-minute exercise [#the-ten-minute-exercise]
Download the owned [Fanta Launch Card sample](/launch/alpha-1.0.0-20261012/Fanta-launch-card-sample.zip)
and unzip it into a folder you own. Open its native project or import the included
original [Fanta Launch Card .fig](/launch/alpha-1.0.0-20261012/Fanta-Launch-Card.fig).
The card uses native text and shapes without third-party artwork. Keep a fresh
copy for resets. The [download page](https://www.fantaisa.net/download) reports
app availability and installation steps.
| Time | Action | Observable result |
| -------- | ------------------------------------------------------------------------------------------ | ---------------------------------------- |
| 0–2 min | Open the unzipped sample project, or import its original `.fig` and save into a new folder | Canvas and layers show the same design |
| 2–4 min | Change one shape's fill or position, then Undo and Redo | Both before and after states are visible |
| 4–6 min | Save, open Code and inspect Review Changes | FNX and Git show the canvas edit |
| 6–8 min | Change a Text layer's existing `content` literal in Code and save | Canvas shows the valid source edit |
| 8–10 min | Save, close and reopen, then export a selected frame as PNG | Saved content returns and the PNG opens |
Keep node IDs unchanged and retain the manifest, identity sidecars and assets.
An invalid source draft retains the last valid canvas and file with an error.
Resolve or discard it before visual edits. Saving multiple buffers is sequential.
[Source editing](/docs/concepts/fnx-design-as-source).
## Agent extension [#agent-extension]
The recorded example uses an **external Opus 5.5 agent through Fanta MCP** to
edit one CTA. It shows the resulting native layers, saved source and Undo/Redo.
The request ran through the external client; the footage shows the actual result
and its inspection in Fanta. Captions identify the later source-view recovery
described in [troubleshooting](/docs/mcp/troubleshooting#code-reports-a-source-refresh-warning).
[Connect the agent](/docs/getting-started/connect-an-agent), verify the intended
project with `get_editor_state`, and ask for one edit:
> Change only the existing button label to “Explore Fanta”. Keep its geometry,
> styles, IDs and all other layers unchanged. Inspect the result and stop.
> Do not generate media or call paid services.
Inspect the canvas and FNX, then Undo and Redo. Use the configured verified route
and approved spending controls. The local bridge is separate from hosted metered
services. [Tool scopes](/docs/mcp).
## Help with the first workflow [#help-with-the-first-workflow]
Use verified community and issue links on the download page for product reports.
Include version, macOS, steps and screenshots. Keep account or billing reports
private at [support@fantaisa.net](mailto:support@fantaisa.net).
# Fanta vs Figma (/docs/fanta-vs-figma)
Fanta is built around **your design as source**: a local project folder that you can edit visually, inspect as FNX, and review in Git. Figma is built around shared cloud files and real-time collaboration. Both can connect AI agents to design work; the difference is where the working document lives and how you review changes. [Fanta project model](/docs/concepts/document-model) · [Figma's cloud and offline model](https://help.figma.com/hc/en-us/articles/360040328553-What-can-I-do-offline-in-Figma).
## Compare the workflow [#compare-the-workflow]
| Workflow | Fanta | Figma |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Working document | A folder containing FNX, managed JSON, identity sidecars, and assets. | Cloud files with link sharing and access permissions. [Sharing guide](https://help.figma.com/hc/en-us/articles/1500007609322-Guide-to-sharing-and-permissions) |
| Editing | Canvas and validated source editing describe the same document. | Visual editing in a shared design file, including simultaneous multiplayer editing. [Multiplayer](https://www.figma.com/blog/multiplayer-editing-in-figma/) |
| History and review | Save source files, inspect text diffs, and make Git commits. Branches and pull requests can use your existing Git host. | File version history, plus design branches and review/merge on eligible plans. [Version history](https://help.figma.com/hc/en-us/articles/360038006754-View-a-file-s-version-history) · [Branching](https://help.figma.com/hc/en-us/articles/360063144053-Guide-to-branching) |
| AI agents | A local MCP bridge reads and edits the open design; agents can also work with project source. | Figma's MCP can retrieve design context, use Code Connect, and create or modify native canvas content. [MCP documentation](https://developers.figma.com/docs/figma-mcp-server/) |
| Local work | Project files are local. Hosted models, generation, and some asset downloads still need a connection. | Loaded pages support some offline editing and sync after reconnection; full functionality needs internet access. [Offline support](https://help.figma.com/hc/en-us/articles/360040328553-What-can-I-do-offline-in-Figma) |
## What FNX changes [#what-fnx-changes]
FNX is Fanta's readable, static JSX-like design format. It describes scene nodes such as frames and text, their properties, and their children. It is **design source**, not executable React or a finished application.
That means a spacing or text edit can become a file change you inspect alongside implementation work. The canvas helps you judge appearance; the source diff helps you understand what changed. Keep the companion JSON and assets with FNX so references and identities survive. [What is FNX?](/docs/formats/fnx) · [Design as source](/docs/concepts/fnx-design-as-source).
The reviewed Public Alpha workflow follows the same design through the canvas, source, and Git. [Watch the complete workflow](/docs/demos).
## Who each workflow serves [#who-each-workflow-serves]
Fanta fits a team or individual who wants designs stored with project files, agents working on the same document, and review through Git. You can keep a design project inside an existing repository and review source and visual output together. Git still requires deliberate commits, conflict resolution, and a remote if you want to share it. [Git workflow](/docs/guides/version-control-designs).
Figma fits teams that want people to work in one shared file, share a link for review, and manage access through its collaboration system. Its broader ecosystem includes design, whiteboarding, presentations, and developer handoff. [Sharing and products](https://help.figma.com/hc/en-us/articles/1500007609322-Guide-to-sharing-and-permissions).
Fanta's local agent activity is not shared cloud presence or a cross-agent lock. Coordinate agents editing the same area and review their output. The current supported alpha target is Apple Silicon macOS; check [installation](/docs/getting-started/install) and [capabilities](/docs/capabilities) for build-specific limits.
## Bring an existing Figma design [#bring-an-existing-figma-design]
With permission to export the file, use Figma's **File → Save local copy**, then open the `.fig` in Fanta. Figma's local copy omits comments and version history. [Figma's export guide](https://help.figma.com/hc/en-us/articles/8403626871063-Save-a-local-copy-of-files).
Fanta converts supported content into a native project. Treat this as a migration: inspect important pages, components, and exported images before continuing. Known flattened or omitted structures receive warnings, but the absence of a warning does not prove full fidelity. Fanta does not promise complete Figma parity or a live connection back to the original file. [Import behavior and limits](/docs/formats/figma-import).
Figma documents `.fig` as a proprietary format that may change, and recommends its official APIs for third-party integrations. That makes visual verification of migrated files especially useful. [Format guidance](https://help.figma.com/hc/en-us/articles/8403626871063-Save-a-local-copy-of-files).
# Fanta documentation (/docs)
Fanta is a native design editor built around an ordinary project folder. Canvas edits write readable `.fnx` files; valid source edits update the canvas. If Git is available, those changes can be reviewed and committed like code. **Your design is source.**
The **Apple Silicon macOS Public Alpha** is available from the [official download page](https://www.fantaisa.net/download). These pages track [fanta-edit main at `e143440a`](https://github.com/jeanc18rlos/fanta-edit/tree/e143440a93732422ac37c6ad1901ff14c420ec7b), with build and release limits called out where they matter. The signed installer is bound to earlier source `57d86330`; later source changes are not part of that accepted package, and only bounded installed-app workflows have been reviewed. Start with the [full capability map](/docs/capabilities).
## A first pass [#a-first-pass]
1. Use **File → New Design…** or open a `.fig` file. Fanta creates a native project directory when it can write to the chosen location.
2. Work on the canvas, in the inspector, or in the Code workspace. Valid external `.fnx` edits reload the canvas.
3. Connect an agent to the running app through its local MCP bridge, if you want one.
4. Let autosave update the project files, review the Git diff, then export a page or selection.
The site also serves [`/llms.txt`](/llms.txt), [`/llms-full.txt`](/llms-full.txt), and a Markdown version of each page.
# Roadmap and current limits (/docs/roadmap)
Fanta's direction is to bring visual design, readable source, Git, and agents into one workspace. The immediate focus is making that loop dependable: edit, save, review, reopen, and keep your design intact.
This page separates **implemented workflows**, **planned improvements and validation**, and **exploratory directions**. It describes the documented work, without promising delivery dates. A feature implemented in source may not yet be in your installed app. Use the [installation guide](/docs/getting-started/install) for the accepted package and the [capability map](/docs/capabilities) for detailed limits.
## Available workflows [#available-workflows]
| Area | Current capability |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Visual design | Pages and layers, shapes, text, vectors, frames, components, variables, and supported horizontal, vertical, and grid auto-layout. [Editor](/docs/editor) |
| Design as source | FNX and managed JSON, validated Code edits, canvas synchronization, and source conflict handling. [FNX](/docs/formats/fnx) |
| Git | File diffs and commits when a repository and Git are available. Non-Store builds can initialize new project repositories; Store feature builds skip that setup. [Version control](/docs/guides/version-control-designs) |
| Agents | Local MCP inspection, edits, screenshots, source validation, and an in-app Agent Panel. [Connect an agent](/docs/getting-started/connect-an-agent) |
| Motion and prototypes | Clips, keyframes, supported property animation, playback, and supported prototype interactions. [Motion](/docs/editor/motion) · [Prototyping](/docs/concepts/prototyping) |
| Import and output | `.fig` migration, supported media assets, and PNG, JPEG, SVG, or PDF export. [Formats](/docs/formats) |
The [reviewed demos](/docs/demos) show a bounded native edit, source and Git workflow, and external agent edit on the accepted signed Public Alpha app. They establish those examples; the broader source inventory includes workflows with separate acceptance work.
## Planned improvements and validation priorities [#planned-improvements-and-validation-priorities]
| Focus | What the work is intended to improve | Current boundary |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source reliability | Preserve drafts, saved files, and the last valid canvas during conflicts, failed reloads, and interrupted saves. | Concurrent external edits and multiwindow recovery need broader native validation. The signed demo also recorded a saved-source refresh warning; reopening restored its source view. [Recovery guidance](/docs/mcp/troubleshooting#code-reports-a-source-refresh-warning) |
| Large projects | Reduce save cost and improve dragging, rendering, and memory behavior on dense imported pages. | Renderer checks and performance work exist, but they do not establish a universal speed advantage or the native drag target. [Current limits](/docs/capabilities#current-limits) |
| Editing consistency | Complete inspector and per-node journeys, including lock handling, entry into editors, Undo/Redo, and save/reopen. | Bounded checks pass; more node, property, gesture, and dependency combinations remain to be checked. |
| Media reliability | Broaden playback, seeking, trimming, recovery, and saved-asset checks across supported audio and video. | Placing a media layer or opening its properties does not establish every playback and editing workflow. [Assets](/docs/editor/assets) |
| Motion expansion | Extend the existing property-animation tools toward path animation. | **Path** is marked “soon” and disabled in the current animation menu. It has no published delivery date. [Motion](/docs/editor/motion) |
| Release quality | Verify advertised workflows against the exact distributed build, including installation, account services, and repeatable persistence. | Acceptance is tied to a particular package and journey. Follow the live [download page](https://www.fantaisa.net/download) for availability. |
The reliability and acceptance priorities come from the repository's [capability coverage report](https://github.com/jeanc18rlos/fanta-edit/blob/main/docs/alpha/CAPABILITY_COVERAGE.md) and [capability guide](https://github.com/jeanc18rlos/fanta-edit/blob/main/docs/fanta/capabilities.md). Dated reports retain earlier failures and pending checks, so read their named build and later corrections before treating an item as current.
## Longer-term directions [#longer-term-directions]
The source specifications name broader image, audio, video, 3D, and game-editor work as future directions. Dedicated editor experiences are exploratory rather than announced releases. The [feature specification guide](https://github.com/jeanc18rlos/fanta-edit/blob/main/features/README.md) asks for acceptance scenarios as these areas develop; its `.feature` files are human-readable specifications, not an automated test runner.
Some specialist node types already exist in the format. Node graph, generic AI artifact, and embed content currently use placeholders; preserving 3D payloads through save/reopen does not establish a complete 3D editor. [Specialist boundaries](/docs/capabilities#current-limits).
## Limits to plan around [#limits-to-plan-around]
Fanta currently targets Apple Silicon macOS. Other operating systems, Intel builds, full Figma import parity, and shared cloud multiplayer are not established supported workflows. Same-document canvas paste is supported; cross-document paste is rejected. Some Figma grid behaviors and effects remain unsupported, and Dev **Readiness** is unavailable. These are current limits, not delivery commitments. [Detailed capabilities](/docs/capabilities) · [Fanta vs Figma](/docs/fanta-vs-figma).
For important work, keep the complete project in Git, review source changes with screenshots, and test the workflows you depend on in your installed version. Report reproducible issues with the app version, steps, expected result, and screenshots through the verified support links on the download page.
# Inside the app (/docs/screenshots)
These screenshots were taken in the installed **Fanta Public Alpha 1.0.0** app on **October 13, 2026**, using our own Launch Card and Docs Showcase projects. Each close-up links to the original full app capture.
## Layers [#layers]
Expand a frame to see its children. Here, **Launch Card** contains text, shapes, the Design Tile, and a **CTA Button** with its own label. [Explore the editor surfaces →](/docs/editor/surfaces)
## Variables and modes [#variables-and-modes]
Open the **Variables** workspace to work with collections, mode values, and aliases. The showcase’s sample collection, **Fanta Brand**, uses Light and Dark values for the navy-and-orange launch card, plus spacing and radius tokens. **Semantic/Action** aliases **Color/Accent**. [Work with variables →](/docs/concepts/variables) · [Official brand identity →](/docs/brand)
## Auto layout [#auto-layout]
Select a container to edit its **Layout** controls. This button uses a horizontal layout with centered alignment and separate vertical and horizontal padding. [Set up auto layout →](/docs/concepts/auto-layout)
## A component master [#a-component-master]
The **CTA Button** was created as a component in the app. Its inspector identifies it as **Component**; the sample has no exposed component properties yet. [Create components and instances →](/docs/concepts/components)
## FNX source [#fnx-source]
Switch to **Code**, then choose **FNX**, to inspect the page’s design source. The launch card appears as nested frames, text, and shapes with stable layer IDs. [Understand FNX →](/docs/concepts/fnx-design-as-source) · [Version control a design →](/docs/guides/version-control-designs)
## Motion [#motion]
**Motion** shows the selected layer’s animation controls and timeline. The showcase includes a **CTA fade in** clip: button opacity goes from 0 to 100% over 800 ms within a 1.2-second clip. The capture is paused at 0.8 seconds. [Animate a layer →](/docs/editor/motion)
## Prototype interactions [#prototype-interactions]
In **Prototype**, open an interaction to inspect its trigger and action. The showcase button uses **On click → Open link** with the docs URL and an Instant transition. [Build a prototype →](/docs/concepts/prototyping)
# In-app AI (/docs/agents/in-app-ai)
Fanta includes an Agent Panel for design work inside the desktop editor. The panel can read the current design and design system, make structured edits, inspect comments, capture screenshots, and place generated images. Source-capable modes can edit saved FNX and managed JSON files.
## Start with the document [#start-with-the-document]
Open a Fanta project or imported Figma file, then describe the page, frame, or selection you want changed. Give the agent dimensions, content, style, reference images, and constraints where they matter. Ask it to inspect the design and show a screenshot after each meaningful change.
The built-in design tools include design\_state, design\_system, design\_edit, design\_screenshot, design\_comments, prepare\_design\_asset, and place\_generation. Read design\_system before creating variables or components. design\_edit paints ordered operations on the live canvas one by one, then commits a labeled batch as one undo step. A failed or canceled batch rolls back its preview. Build one visible component or screen section at a time; inspect each milestone before continuing.
Use a project-root fanta.md to give the native designer a product brief, visual direction, layout and asset preferences, design-system conventions, and acceptance checks. It reads that file before each model round. Nested specifications refine workspace rules, with a 64 KiB combined limit; direct user instructions and the selected mode's permissions take precedence. See [project context](/docs/mcp/custom-rules).
In current source, a native Agent turn is limited to 64 model requests across tool continuations, agent-managed retries, model fallback, and automatic compaction. Provider-internal retries are outside this count. At the limit, the turn stops with a visible message and keeps completed work. Send a new message to start a fresh turn. This is a request limit, not a credit or spending cap; the release recordings do not establish native acceptance of this limit.
## Choose an agent mode [#choose-an-agent-mode]
**Edit Visual** applies undoable canvas operations. **Write** and **Full Access** can edit saved FNX and managed JSON source. **Ultra** coordinates specialists on larger tasks. **Plan** and **Review** preserve the scene while they inspect and advise; Plan can read comments but cannot reply or resolve them. Available tools depend on the selected mode and model.
After a successful completed Plan response, the panel offers **Apply plan** and **Keep planning**. Applying switches that thread to Write mode and sends an implementation request for the plan; keeping it open lets you continue discussing it. The actions appear only after a successful completed Plan response.
## Plan & build in Build mode [#plan--build-in-build-mode]
The editor's **Build** mode opens a separate **Plan & build** inspector sidebar. Enter a design brief and choose **Plan & build**. Fanta sends the current page scene, supported design operations, and the project's fanta.md context to its v2 agent service. The service plans tasks and returns canvas operations for the current task. Fanta applies those operations as one undoable preview for you to review.
Choose **Accept** to send the resulting scene back for a lint and critique check; Fanta then moves to the next task or offers revised operations when a check fails. **Retry** can include notes and requests new operations after undoing the latest preview. **Skip** removes that preview and moves on. **Stop** ends the session and keeps work already applied. If you turn on **Accept each task automatically** before starting, the panel accepts previews as they arrive; this switch is off by default. The panel shows task status, reported issues, and credits used.
Build mode requires Fanta sign-in, available credits when charged, and a configured server that offers /v2/agent/sessions. Preview and dev channel defaults target the v2 service; the stable channel default still points to the older API, so Build may report that the v2 API is unavailable. A failed operation batch rolls back; choose **Accept** to send its errors back to the agent. If you edit the canvas after a preview, Retry or Skip will leave it in place rather than undoing your later edits; use Undo manually if you want to remove it.
Build mode's task-by-task session is separate from the Agent Panel's **Plan** mode and **Apply plan** action above.
The Thinking control appears when the selected model reports support for reasoning effort; it changes the request but does not expose private reasoning. The built-in agent can read source files, and source-capable modes can save small, complete FNX subtrees or typed JSON changes. The Code workspace itself edits the selected page or component FNX and its page.json or def.json companion. For other managed JSON, use file tools and validate the complete candidate before writing. See [FNX source](/docs/formats/fnx).
## Follow visible work [#follow-visible-work]
The agent reports its current action and focus. **Follow** can move with it across canvas pages, component tabs, variables, and source files; the Code workspace can reveal the reported FNX or JSON path. While an agent reports activity for the open project, the Canvas workspace shows a pulsing edge around the canvas alongside the agent controls. Distinct agent names and colors help identify the lead agent and specialists. In Ultra mode, specialists receive the lead chat's reference images when their model supports image input. The lead can give specialists separate components or pages, and their names remain stable during the work.
Use **Pause follow** to stop automatic source scrolling while inspecting a file. Activity indicators expire when an agent stops reporting, and the agent should clear its activity when finished. These indicators show focus; they are not cross-agent edit locks.
For an image or SVG icon, the agent can call prepare\_design\_asset to open a draft in Fanta's generation composer. You review available models and submit it there; preparing a draft does not run generation. place\_generation can fetch a generated image URL and place it in the project.
## AI provider and account [#ai-provider-and-account]
Fanta's default settings include a managed Fanta AI provider. After sign-in, the provider reads the current chat-model catalog from the service and shows each model's supported tools, images, context size, and credit information when supplied. The app also exposes settings for connecting your own supported provider credentials. Provider availability and model choices can change, so inspect **Settings → AI & Models** for the options available to your account.
The displayed model price, output limit, and agent profile do not set a total spending cap for a session: tool calls, retries, and auxiliary requests can add usage. Review available credits and the active model before sending. Paid-request pricing and caps have not passed live acceptance in the release coverage report.
Preview and dev channel defaults point Fanta's account, model, edit-prediction, and hosted MCP settings at its v2 backend. Their fanta-design hosted tool connection is enabled in the channel defaults; the stable default enables the account-backed fanta generation connection and lists fanta-design disabled. Service availability and account access still determine what appears in the app.
The Fanta-hosted MCP connections use the signed-in account when their endpoint matches the configured backend and no explicit authentication header is set. A managed connection that receives 401 asks you to sign out and sign in again; a startup timeout leaves an unused OAuth session cached for that endpoint. This is separate from the [local canvas MCP bridge](/docs/mcp/connect). The authentication failure paths have isolated tests, while live managed-tool execution and recovery still need verification.
The built-in agent also registers evaluate\_with\_jev for typed decisions about supplied text or structured state. It can ask one to eight named boolean, choice, or score questions and returns structured answers instead of a chat reply. The request is limited to 8 KiB, requires Fanta sign-in, and is unavailable in restricted agent mode. The tool describes a minimum charge of one Fanta credit for a successful call; actual availability and billing depend on the connected service. This is an in-app agent tool, not one of the thirteen external canvas MCP tools.
Fanta-hosted chat and generation require sign-in and purchased credits for public accounts. Subscriptions and one-time packs are purchased through [web Billing](https://app.fantaisa.net/billing). Public trial, signup, and referral credits are not offered; only designated founder accounts retain complimentary hosted access. Supported provider keys use the connected provider's own billing. See [pricing and credits](/docs/platform/pricing), [media generation](/docs/agents/media-generation), and [Settings](/docs/editor/settings).
## Review what changed [#review-what-changed]
Inspect updated layers, source diffs, comments, and screenshots in the editor. Continue with manual canvas tools, request a revision, or undo an edit batch. Structured design operations can create variables, bind compatible properties, combine and edit component variants, set gradient fills, arrange grid layouts, and set exposed instance properties. For individual rich-text runs or another property outside the operation vocabulary, work through [FNX source](/docs/formats/fnx).
The local MCP server and Agent Panel both work with the open desktop design, but their tool names and permissions differ. Agent presence reflects reported activity in the running app.
# Agents & AI (/docs/agents)
Fanta combines an editable design canvas with an in-app agent, a local MCP connection for external agents, and hosted tools for generating media. These are related workflows, but they expose different controls.
## Choose a workflow [#choose-a-workflow]
| Workflow | Use it for | Where it runs |
| ------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------------------------- |
| [Agent Panel](/docs/agents/in-app-ai) | Ask for design changes, or plan and apply a plan in a chat thread | In Fanta |
| [Build mode](/docs/agents/in-app-ai) | Give a brief, then review and accept, retry, or skip each agent-built task | In Fanta, with the v2 service |
| [Local MCP](/docs/agents/workflows) | Let an external agent inspect and edit the open canvas | Through the running desktop app |
| [Generation Workspaces](/docs/agents/media-generation) | Generate images, video, audio, vectors, and masks | Hosted models, with results reviewed in Fanta |
| [FNX and managed JSON source](/docs/formats/fnx) | Edit detailed design properties and review source diffs | In project files |
The local MCP server exposes thirteen tools for canvas state and edits, design-system inspection, source validation, image import, comments, activity, and screenshots. The in-app agent has related design-state, edit, screenshot, design-system, comment, and generation-placement tools. Their names and permissions differ; see the [external tool reference](/docs/tools) and [Agent Panel](/docs/agents/in-app-ai).
The documented external-agent bridge and in-app local agent process workflows apply to a non-Store build. A Mac App Store feature build prevents Fanta from launching local external agent and MCP processes or terminal tools. Remote HTTP MCP connections can still be configured in Settings. [Build differences →](/docs/editor/settings)
## A reliable design loop [#a-reliable-design-loop]
1. Open a Fanta project or an imported Figma document in the desktop app.
2. Read the editor state and Fanta's design guidelines.
3. Inspect relevant node IDs, existing variables and components, open comments, and a screenshot.
4. Apply one small, labeled batch for a visible component or screen section. Its operations paint in sequence and commit as one undo step.
5. Capture another screenshot and inspect the result.
6. Revise as needed, address review comments, then save or export for handoff.
A batch\_design call streams a visible preview and finishes as one undoable transaction. If an operation fails or the call is canceled, the preview rolls back. The edit response includes IDs for created nodes. Use exact IDs from the current document, not layer names. The operation vocabulary includes gradient paints, effects, grid layout, component variants, variables, and instance properties. For changes outside that vocabulary, read the full FNX or managed JSON source and validate a complete candidate before writing it. Report a stable agent identity and focus to let the user follow work across pages and source tabs.
The local MCP connection works against the design open in the running desktop app. Fanta-hosted AI requires sign-in and purchased credits for public accounts; available models and prices come from Fanta's live catalog. Buy subscriptions or credit packs through [web Billing](https://app.fantaisa.net/billing). See [pricing and credits](/docs/platform/pricing).
See [reference-grounded design](/docs/agents/reference-grounded) and [review and revision](/docs/agents/review-revision) for practical workflows.
# Media generation (/docs/agents/media-generation)
Fanta's Generation Workspaces expose **Image**, **Video**, **Audio**, **Vector**, **Design**, and **Masks** modes. Hosted generation requires sign-in and purchased credits for public accounts. The app loads a searchable model catalog from the service, so models, controls, account access, and credit estimates can change. Check the selected model's controls and estimated cost before submitting. Buy subscriptions or credit packs through [web Billing](https://app.fantaisa.net/billing); public accounts receive no free trial or signup credits. See [pricing and credits](/docs/platform/pricing).
## What each mode does [#what-each-mode-does]
| Mode | Typical work |
| ------ | ------------------------------------------------------------- |
| Image | Create an image from text or use an image and mask as inputs. |
| Video | Generate from text or animate an image. |
| Audio | Create speech or music. |
| Vector | Create an SVG from a prompt or trace an image. |
| Design | Prepare a design request for review in the Agent Panel. |
| Masks | Create or refine a mask for a supported image workflow. |
Starter templates help begin image, video, audio, and SVG requests: editorial and product images, cinematic and atmospheric video, narration and music, or a geometric symbol and monogram. Pick a model and recipe before setting its controls. Fanta reads the model's capabilities to show relevant options, such as video duration, resolution, audio, camera controls, or an optional ending frame. Supported inputs and output formats depend on that model. A source image can come from a local PNG, JPEG, or WebP file or a captured canvas region where the recipe permits it.
## Agent-prepared assets [#agent-prepared-assets]
An agent using the local canvas MCP bridge can call prepare\_design\_asset with an image or SVG idea. Fanta opens the existing generation composer with the prompt filled in. If the suggested model is compatible and present in the live catalog, Fanta selects it; otherwise you choose an available model. **The tool does not submit a job.** Review the prompt, model, controls, and cost in the composer, then choose **Generate** when ready.
An agent can also use import\_image to register an image made elsewhere. It accepts exactly one local path, HTTP or HTTPS URL, or base64 source; it returns the saved project asset ID and path. Importing does not place a new canvas layer. Use the Assets panel or an FNX edit to use the image. The import is limited to 32 MiB, and remote downloads time out after 60 seconds.
## Review and save a result [#review-and-save-a-result]
Select an output to preview it. On macOS, the result view can play generated video and audio. The audio player shows the decoded duration before playback and supports seeking, ten-second jumps, speed, mute, and volume controls. **Save result** writes the chosen output to a file you select; Fanta can use media already loaded for preview. In a Mac App Store build, the Save dialog grants access to the selected destination.
When generated audio reaches its end, the position readout and seek bar remain at the known duration. Active image outputs in the gallery inherit their creation timestamp from generation history when the service supplies it.
Recent experiments use a descriptive creation title when the service can provide one, with a local prompt-based label as fallback. An output in generation history is separate from the current design until you add it. You can reuse supported raster results as a source for another run. A mask is used in a supported masking workflow and cannot be added to project Assets as a standalone canvas asset. Design mode prepares a prompt for the Agent Panel; it asks the agent to inspect FNX source, prefer source edits where practical, and verify the result with screenshots. It is not a direct generative canvas render.
## Recover an uncertain request [#recover-an-uncertain-request]
If a submission's outcome is uncertain, use **Retry submission** or its saved **Recover…** entry to check and resume that request. Fanta blocks another generation until the saved request is resolved. Recovery checks the current account and whether the saved model is still available. This behavior has local tests; recovery against a live provider still needs verification.
## Add a result to a project [#add-a-result-to-a-project]
With a project canvas open, choose **Add to project** for a supported result. Fanta copies it into the project's asset storage and records its name and kind in the persistent asset library. Open **Assets** in the file inspector, choose the target under **Place in**, and use the **+** button on the asset row. You can place the same stored asset again without repeating generation.
| Result | Project placement |
| ------------------ | ----------------------- |
| PNG, JPEG, or WebP | Bitmap image layer |
| Supported SVG | Editable vector content |
| MP4 | Video layer |
| WAV, MP3, or FLAC | Audio layer |
The placed media is centered in the visible viewport and scaled to fit. On macOS, select an audio or video layer in **Motion** or **Prototype** mode to use its playback controls. A bounded MP3 placement and cold storage check passed, but the placed Audio preview was absent after reopening the checked project; WAV preview was not verified. This is separate from previewing an unplaced generation result. Video preparation uses the playable timeline duration, including clips with MP4 edit lists, for placement and trimming. See [Project Assets](/docs/editor/assets) for the full workflow and limits. Some generation views also offer **Add to design** directly for image, SVG, or video results. Even if that direct button appears beside audio, use the project Assets route: the direct path does not decode audio for placement.
## Place local media without generation [#place-local-media-without-generation]
The canvas toolbar's media placement command opens a **Place image or MP4 video** file picker. It accepts one PNG, JPEG, WebP, GIF, BMP, TIFF, or MP4 at a time. It places the media on the active, visible, editable page, centers it in the viewport, scales it down to fit within about 80% of the visible area, and selects the new layer. The placement is one undo step. A local audio file uses the project Assets workflow instead.
Local image placement is limited to 32 MiB, 32 megapixels, and 16,384 pixels per side. Local MP4 placement is limited to 100 MiB and requires the macOS decoder; video preview also has a 32 megapixel resolution limit. Generated-result downloads and Add to project have a separate 128 MiB media cap, although generated bitmap assets still have a 32 MiB image preparation limit. Fanta reports an error if decoding or preparation fails. Finish a pending source edit or canvas preview before placing local media.
MP4 describes a container, not a guarantee that every video inside it will play. Fanta checks for movie metadata, a video track, valid dimensions and duration, and a supported track transform; playback and placement also depend on macOS decoding that file. If a clip fails preparation, save or convert it to a playable MP4 and try again.
Adding or placing an asset requires an editable project. Save or discard unfinished FNX source edits first. Model availability, credits, and prices are live service conditions; this page describes the app workflow rather than a fixed catalog or guaranteed price.
# Design from a reference (/docs/agents/reference-grounded)
A reference is most useful when the agent can compare it with the actual Fanta canvas. Start with the page and the target frame rather than asking for a broad visual imitation.
## Give the agent usable input [#give-the-agent-usable-input]
Include the reference image or a clear description, the intended canvas size, any required copy and assets, and the elements that must remain. Identify an existing page, frame, or node if the task is a revision. Ask the agent to read the editor state and relevant nodes before changing the document.
For an empty page, get\_editor\_state can look for space for a requested width and height. A batch\_get call then exposes exact node IDs and details. get\_design\_system shows existing tokens and components, while get\_screenshot gives the agent a visual baseline. These reads help it place new work without guessing IDs or overwriting nearby content.
## Build and compare [#build-and-compare]
1. Define a frame at the target size and lay out the major regions.
2. Add text, shape, image, and component layers in small, visible batches. Finish one component or screen section before starting the next.
3. Use auto layout where content needs to flow with changes.
4. Capture a screenshot of the page or target node.
5. Compare hierarchy, spacing, type, color, and crop with the reference; adjust the mismatches.
The structured edit surface supports solid and gradient paints, typography, strokes, shadow and blur stacks, variables, component variants, and horizontal, vertical, or grid layout. It cannot directly set every design property. For individual rich-text runs or another unsupported property, inspect the [FNX source](/docs/formats/fnx), validate the complete candidate, and edit the relevant project file.
## Keep the result editable [#keep-the-result-editable]
Use native frames, text, and shapes for the layout. Place bitmap images where the reference contains photography or raster detail. Hosted image and vector generation can supply new assets. prepare\_design\_asset opens a user-reviewed image or SVG prompt without submitting it; import\_image saves a returned raster file or URL to project Assets without placing a layer. Generated SVG can become editable vector layers when added to the design. In Ultra mode, delegated specialists can receive the lead chat’s reference images when their model supports images; give each specialist a distinct page or component and inspect their visible milestones. Verify the result in Fanta before exporting.
A reference image is guidance, not proof of pixel-for-pixel equivalence. Compare screenshots at the same target dimensions, and inspect text, clipping, and responsive behavior in the live editor.
# Review and revision (/docs/agents/review-revision)
Review an agent edit in the editor before treating the design as finished. Fanta provides canvas screenshots, layer inspection, an undoable edit history, and project source files for this loop.
## Review a canvas edit [#review-a-canvas-edit]
Ask the agent to capture a screenshot after applying an edit. Check the target frame at its intended size: alignment, text overflow, clipping, spacing, contrast, image crop, and visual hierarchy. Use batch\_get to inspect precise properties when a screenshot is ambiguous. Give the next revision as a short list of observable changes.
A batch\_design edit paints each operation as a temporary preview, then commits the batch as one undo transaction. If an operation fails or the batch is canceled, the preview rolls back and the result identifies the failing operation. If a completed batch is wrong, undo it in Fanta or request a corrective batch. Work with exact node IDs obtained from the current document.
## Review source changes [#review-source-changes]
Pages and component masters are stored as FNX files with companion JSON headers. Read FNX through read\_fnx\_source or normal file tools; inspect managed JSON with file tools. The MCP reader slices by 1-based line offset, so follow its next\_offset before replacing a file. Check a complete FNX or managed JSON candidate with validate\_fnx\_source before writing. Existing files are checked against the full project, including types and references. External edits to an open project are picked up by the editor after a short delay. A source parse error leaves the last valid canvas state visible while you fix the file. See [FNX source](/docs/formats/fnx).
Source files are useful for Git review. Check the actual canvas too: a clean textual diff alone does not establish that the rendered design is correct.
Check the reverse as well: a visible canvas edit does not prove the source saved. Fanta retains authored FNX comments and extra attributes during structural saves when it can. If deletion or a node-type change would lose a source-only attribute that Undo cannot restore, it reports a preservation error. Undo the canvas edit or make an intentional source edit and validate it, then verify both canvas and diff again.
## Comments and handoff [#comments-and-handoff]
Fanta's canvas comments can attach pins to design positions and hold replies, mentions, attachments, and resolved state. They are stored as project page metadata. External agents can call list\_comments for unresolved threads on the active page, or include resolved threads and choose a page. Use reply\_comment with the exact thread ID to answer, and set resolve: true only after the request has been verified. The in-app agent's related tool is design\_comments. Comments do not appear in PNG, JPG, SVG, or PDF exports.
When the design is ready, export the selected layers or active page from the editor. For another editable copy, keep the native project directory or use a supported snapshot workflow. See [formats and interoperability](/docs/formats).
# Agent workflows (/docs/agents/workflows)
In a non-Store build, Fanta exposes a local MCP server from the running desktop app. Its stdio bridge is the Fanta executable with --mcp-stdio. The bridge forwards MCP requests to the app's private Unix socket. Keep Fanta open with a design document loaded. This is a local desktop connection, not a public TCP endpoint. A packaged Mac App Store bridge has not been verified.
## Connect [#connect]
Choose **Help → Connect Claude Code / Codex…** in a non-Store Fanta build. It copies project-scoped configuration using the running executable and its user data directory. The command shape is:
fanta --mcp-stdio --user-data-dir
Put the copied Codex snippet in the project's .codex/config.toml, or run the copied Claude Code command from the project directory. Fanta's local MCP server is enabled in the default settings. If the client cannot connect, check that the installed app is running and a project or imported .fig document is open. See [connection steps](/docs/mcp/connect).
## Available tools [#available-tools]
| Tool | Purpose |
| ------------------------------------ | -------------------------------------------------------------------------------------------------- |
| get\_editor\_state | Project, pages, active page, components, selection, viewport, editability, and optional free space |
| get\_design\_system | Collections, modes, typed variables, bindings, component properties, and variant sets |
| prepare\_design\_asset | Open an image or SVG generation draft for user review; does not submit it |
| get\_guidelines | Design rules, coordinate conventions, and recommended working method |
| batch\_get | List a page tree or inspect exact node IDs, with depth and pagination controls |
| batch\_design | Stream ordered design operations as one undoable batch |
| get\_screenshot | Render a PNG of a page, node, or motion-clip sample |
| read\_fnx\_source | List or read project FNX files in slices |
| validate\_fnx\_source | Check a complete FNX or managed JSON candidate without writing |
| import\_image | Save a file, HTTP(S) URL, or base64 image in project Assets without placing a layer |
| list\_comments | Read page review threads, unresolved by default |
| reply\_comment | Reply to a thread and optionally resolve it |
| report\_agent\_activity | Show the agent's action and canvas, variable, or source-file focus |
The canvas uses world coordinates in pixels, with the origin at the upper left and Y increasing downward. Node IDs must come from current editor state or a node read. Page listings use depth and pagination controls and refuse traversals over 1,000 nodes; narrow very large reads instead of fetching an entire imported page at once. get\_editor\_state advertises the operation capabilities supported by the running editor. batch\_get accepts detail: an ID lookup defaults to editable style, while a page listing defaults to summary. Choose style for a detailed listing or raw with IDs for internal records. Inspect styles before writing them back.
## Build in visible milestones [#build-in-visible-milestones]
Read the state, guidelines, relevant nodes, design system, open comments, and a baseline screenshot. Build one component or screen section at a time. Give each batch\_design call a descriptive label and a small group of related operations. Fanta previews content edits as the batch runs, then commits them as one undo step. A selection- or viewport-only batch creates no content undo step. If an operation fails or the batch is canceled, content edits roll back; selection and viewport changes are not transactional. The response identifies the failing operation and returns created IDs on success.
To make the work followable, call report\_agent\_activity with a stable agent\_id and agent\_name, the current action, and the page, node, or world position. Pass that same identity in batch\_design.activity so each streamed step stays attributed to the agent. When moving to a source file, include its project-contained source\_path and workspace (canvas, variables, or code). A user who chooses **Follow** can track the reported page, component tab, file, and workspace. Clear activity with active: false when finished. These presence indicators report focus; they are not edit locks between agents.
Structured operations cover frames, text, images, variables, bindings, ordering, selection, and viewport changes. The expanded vocabulary also includes create\_shape for lines, polygons, stars, and paths; set\_fill for solid, linear, radial, and image paints; set\_effects for shadow and blur stacks; set\_constraints; and stroke sides, dash, cap, and join. set\_grid\_layout defines fixed, fractional, or content-sized columns, and set\_layout\_child can place and span a grid cell. Component operations can turn matching layers into a master and instances, combine or extend variants, remove or arrange a variant, and rename a component.
Use batch\_get with detail: "style" to inspect values in the operation vocabulary before changing an existing node. For individual rich-text runs and other properties without a structured operation, inspect the full FNX source, validate a complete candidate, save with file tools, and verify the reloaded canvas. Managed JSON also needs full typed validation before writing. See [FNX source](/docs/formats/fnx).
## Verify visually [#verify-visually]
After each milestone, use get\_screenshot and compare the result with the brief or reference. It renders the active page by default; pass a page index or node ID to narrow the view. The default maximum output dimension is 768 pixels, capped at 1568. An existing motion\_clip ID plus playhead\_ms samples animation. A screenshot is a read tool, not a file export. For deliverables, use the [export controls](/docs/formats/export).
# Auto layout (/docs/concepts/auto-layout)
# Auto layout [#auto-layout]
Auto layout arranges a container's children using direction, spacing, padding, alignment, and sizing rules. Use it for repeated items, buttons, cards, and sections that need to respond when their contents change. Fanta supports horizontal and vertical stacks and a grid. The inspector separates a container's layout settings from each selected child's sizing and alignment settings.
## Set up a layout [#set-up-a-layout]
1. Select a frame or another supported container.
2. Open the **Layout** section in the inspector and enable auto layout.
3. Choose horizontal, vertical, or grid layout, then set spacing, padding, and alignment.
4. Select a child to adjust its sizing or placement within the layout.
5. Resize the container or edit child content to check the result.
You can also reach layout actions from the layer context menu. A free-positioned layer may move when you put it into a layout container because the parent now calculates child placement. Check the result on the canvas.
## Arrange a grid [#arrange-a-grid]
1. Select a frame or group, enable auto layout, and choose **Grid**.
2. Set the column and row counts and each track's sizing: fixed pixels, fractional space (`fr`), or Hug content. Set column and row gaps and padding.
3. Leave items in automatic row flow, or switch to manual positioning to pin their current cells.
4. Select a child to set its column, row, span, and horizontal or vertical alignment within the cell.
Switching a stack to Grid starts with approximately square, equal `1fr` columns for its current children. Rows are added as needed and default to Hug sizing. Children without pinned cells fill the first free cell row by row. A child can span tracks; a child with absolute layout participation stays outside the grid flow. Fixed and Hug frame sizing still applies. The track-count controls accept 1–256 rows or columns, while the engine can generate additional Hug rows for children. In a Hug sized frame, fractional tracks size to content rather than dividing free space. [Figma import](/docs/formats/figma-import) maps supported grid tracks, gaps, anchors, spans, and child alignment.
Agents can set horizontal, vertical, or grid containers with `set_auto_layout`, including `gap`, `padding`, alignment, distribution, `fixed` or `hug` sizing, min and max size, wrapping, and `counter_gap` where applicable. `set_grid_layout` defines columns, rows, and gaps; `set_layout_child` can pin a grid child to a cell, set its spans and alignment, or return it to automatic placement. For a button, use a horizontal Hug layout and an auto-width label; for a card, choose a fixed width and auto-height paragraph text. See [layout operations](/docs/tools/layout).
The canvas supports an 8 px snap grid and nearby node edges and centers while moving objects; snapping is a separate feature from auto layout. Grid placement is solved in `crates/fanta-doc/src/layout/grid.rs`; the current inspector controls are wired in `crates/fig_viewer/src/gpui_adapters/design.rs`.
# Components and instances (/docs/concepts/components)
# Components and instances [#components-and-instances]
A component is a reusable master layer tree. An instance refers to that master and can carry local overrides. Fanta stores component masters in `components//master.fnx`, alongside the project's page source.
## Create and use a component [#create-and-use-a-component]
1. Put the layers you want to reuse in a frame or group, then select that container.
2. Choose **Create component** from the layer or canvas context menu, or the inspector's selection controls. The new master stays in place.
3. Right-click the master and choose **Create instance**. The new instance appears beside the master and is selected. A component set's frame can create a set instance that initially shows its default variant.
4. Select an instance to change supported local properties or a variant choice.
5. Use **Go to main component** to find the rendered master. Use the instance controls to reset overrides or detach the instance when you need an independent layer tree.
Open a component master to edit it in its own canvas. The master root appears as a row in Layers; expand it to inspect and select its descendants. Selecting a descendant reveals its ancestor chain in the panel.
## Variant sets and properties [#variant-sets-and-properties]
Components can have variants and exposed text, boolean, number, color, instance-swap, and variant properties. Create a set from at least two standalone masters; Fanta groups them inside a set frame and arranges them by their variant values. Names such as `Variant=Primary, State=Hover` define axes and values; plain names become values on a single **Variant** axis. The first selected master becomes the default. Duplicate combinations are rejected.
An instance's variant choices appear before its other component properties in the inspector. Changing one axis keeps the others and swaps to the exact matching master. A sparse set has no result for a combination that has not been authored, so that choice leaves the instance as it was. **Go to main component** opens the member currently rendered, including a set default or a member selected by a variable alias and the placed instance's active or inherited mode. If a source draft is unsaved, navigation to another page or component scope is refused until you save or discard the draft. Reset clears local customizations and restores the resolved default member's size. Detach expands a supported instance to independent content; if its combined opacity, effects, blur, or blend cannot be preserved, Fanta explains the refusal and leaves the instance unchanged.
The inspector also shows Content rows for visible text inside an instance. Editing one writes a local text override; resetting it returns to the master value. Canvas text editing resolves alias-backed component properties at the placed instance's mode. A direct text-content variable binding remains authoritative and prevents a local content edit; change the variable or remove the binding first. Text inside a nested instance is not recursively exposed as a Content row.
When you duplicate a component master or a complete variant set, Fanta clones its component definitions and remaps the duplicate to those new definitions. Duplicating an ordinary instance keeps its reference to the existing master. Page duplication also clones component definitions belonging to the duplicated page.
Copying a master or complete variant set captures its definitions. If the original is later removed, Paste can restore the captured definitions with new IDs and reconnect copied instances; repeated Paste after Cut makes independent restored copies. Paste of an ordinary instance continues to use its existing live component reference. Cut refuses an incomplete variant set. Removing a master detaches supported surviving instances so their artwork remains; unresolved dependencies or combinations that cannot keep the appearance cause a refusal before removal. Cut, Delete, and Duplicate respect direct and inherited layer locks. A failed Cut leaves the prior clipboard content in place.
An external agent can promote a frame or group with `create_component`, combine two or more standalone master node IDs with `combine_variants`, expose a property with `create_component_property`, bind it to a compatible descendant field with `bind_component_property`, and change an instance with `set_instance_property`. The `componentize` operation can take a master and structurally matching copies, replace the copies with instances, and preserve their visual differences as overrides. It refuses copies with different kinds or child structures. Read `get_design_system` between structural steps for exact set IDs, axes, properties, and allowed values. Invalid property types roll back the batch. See [components and variants](/docs/tools/components-instances).
Component and instance operations are implemented in `crates/fig_viewer/src/properties_ops.rs`, `component_actions.rs`, `componentize.rs`, and `variant_sets.rs`. Storage is defined in `crates/fanta-format/src/project/layout.rs`.
# Document model (/docs/concepts/document-model)
# Document model [#document-model]
A Fanta design is a local project folder. New Design creates a project with a page. The folder contains fanta.json, page source under pages/, component source under components/, shared metadata under doc/, and media bytes under assets/. doc/asset\_library.json records reusable media names and kinds even before an asset is placed on a page. FNX files describe editable layer trees; sidecars preserve identity and ordering. Generated previews and exports are ignored by Git. Fanta also seeds fanta.md, a project-local design brief; existing edits to it are preserved.
A page has a root and its own layer tree. Frames, shapes, text, images, paths, groups, sections, slices, component instances, and other node kinds live in that tree. Properties include geometry, paints, typography, effects, horizontal, vertical, or grid layout, variable bindings, motion clips, and prototype interactions. Page metadata can also hold comments, measurements, and developer annotations. The editor exposes those properties through the canvas and inspector according to the selected node.
## Components and variants [#components-and-variants]
A standalone component has a definition and master tree under components/\/. In the current layout version 5, a component with variants is one folder: components/\/set.json holds its axes, values, and default variant, while each components/\/\/ holds that variant's def.json, master.fnx, and master.ids.json. A set is represented on canvas by a frame containing its variant masters. Instances select variants through exposed properties and may override supported content or style.
Names determine readable folder slugs and may appear in FNX component references; IDs preserve identity. Use the canvas or structured component operations to combine, add, remove, arrange, or rename variants and components so their references and definitions move together. Older version 4 projects with a flat components/sets.json registry open in the current app and migrate to version 5 on save. See [project layout](/docs/formats/fant).
## Work with a project [#work-with-a-project]
1. Choose **File → New Design** or open a supported design.
2. Add and organize pages in the Layers panel.
3. Edit layers on the canvas or in the inspector. Fanta saves local changes after a short delay.
4. Switch to the Code workspace when you need to inspect or edit FNX or the selected source's JSON header. Save valid source to update the canvas.
5. Use **File → Review Changes** or **Commit** when you want to inspect or record project changes in Git.
Opening a bare .fig file attempts to create an editable sibling Fanta project and leaves the original file untouched. If the location cannot be written, Fanta keeps the imported design in memory until it can save a project. .fig is an import format, not Fanta's native save target. Fanta can also import .fant files. Export from the inspector to PNG, JPG, SVG, or PDF; export is separate from saving the project.
Fanta watches project files for external edits. If the canvas has no unsaved changes, an external edit can reload. With local edits, Fanta attempts a three-way merge and surfaces conflicts for review. Keep the project folder together when sharing or moving it.
## Source references [#source-references]
The folder layout is defined in crates/fanta-format/src/project/layout.rs and component\_dirs.rs. New Design and import behavior are in crates/fig\_viewer/src/new\_design.rs and document.rs. Source saving is in crates/fanta-format/src/project/source\_edit.rs.
# FNX design as source (/docs/concepts/fnx-design-as-source)
# FNX design as source [#fnx-design-as-source]
FNX is the text format Fanta uses to describe your design. A frame becomes a Frame element, a text layer becomes a Text element, and properties such as position, color, and layout become attributes. Nesting elements describes the layer hierarchy. You can read those files, edit them, and review their changes in Git.
The canvas and the source are two views of the same project. Draw or adjust a layer, and Fanta saves the change to FNX. Save a valid source edit, and Fanta updates the canvas. An agent can work on that same design through supported canvas operations or source edits.
## Design source and application code [#design-source-and-application-code]
FNX uses a familiar JSX-like shape, but it is a static design description. Its values describe nodes and their properties; Fanta parses them instead of executing arbitrary JavaScript. It does not provide React state, event handlers, or a running application. The function wrapper in generated source is a readable container for the design tree.
This makes the design accessible to source tools without pretending the artwork is already a finished app. Use FNX to author and inspect the design, then implement application behavior in your chosen framework. See [Design to code](/docs/guides/design-to-code-fnx) for that workflow.
## What a project stores [#what-a-project-stores]
Fanta stores page layer trees in pages/\/page.fnx. A standalone component master is components/\/master.fnx. With layout version 5, a variant set lives under components/\/ with set.json and one \/master.fnx per member. FNX is a readable, static JSX-like representation of nodes and properties. It prints explicit node IDs. Companion page.ids.json and master.ids.json sidecars carry supporting identity and sibling order information.
Other project data is managed JSON: page and component headers, variant sets, variables and modes, motion, prototypes, metadata, asset indexes, and more. The project also seeds fanta.md for design intent and AGENTS.md for agent guidance. Page and component artwork remains in FNX; JSON holds shared data and metadata.
A source file may express placement through parent-relative transforms, including X and Y translation, and width and height shorthand. It has conveniences for Rect and Ellipse shapes and colors through fnxColor. A TextPath element stores its own path geometry and text. A frame can express horizontal, vertical, or grid auto layout with fixed, fractional, or content-sized tracks. The canvas presents the resolved result.
When Fanta prints FNX, finite numbers keep their exact numeric value across a source round trip. Tiny floating-point values are not rounded to zero; those with many leading zeros may use exponent notation. This protects fine geometry and source-only data, though it can also make small arithmetic residue visible in Git diffs.
## Edit source in Fanta [#edit-source-in-fanta]
1. Open the **Code** workspace. Select **FNX** for the active page or component master, or **JSON** for that source's page.json or def.json companion. A variant opens its own source under the set folder.
2. Make a small, complete change. Once either buffer is dirty, canvas edits are locked to avoid competing changes.
3. Save. Fanta validates the edited source against the complete project before writing, then reloads the canvas. It checks JSON types and references, so valid JSON syntax alone is insufficient.
4. If validation fails, read the error, repair the source, and save again. An invalid edit leaves the last valid canvas and saved file intact.
The Code workspace has **Find** for the active FNX or JSON editor. **Discard draft** discards unsaved changes in only the selected buffer; another dirty source buffer keeps the canvas edit lock until it is saved or discarded too. A source Save handles the selected dirty buffer first, then the other if necessary. Successful Save retains the authored text edit in Undo history and saves geometry recomputed from that source change with it.
The workspace protects against a file changing on disk during a save. It blocks source saving while canvas changes or file conflicts still need resolution. Invalid source leaves the last valid file and canvas intact, so repair the draft or discard it. Unknown FNX attributes may produce nonfatal diagnostics; inspect warnings and the rendered result.
After either kind of edit, review both the rendered design and its source diff. A screenshot shows the visual result; the diff shows which properties, text, or references changed. [Version-control your designs](/docs/guides/version-control-designs) explains checkpoints, branches, and review.
## Canvas edits and authored source [#canvas-edits-and-authored-source]
The editor patches the affected FNX when a canvas property changes. For a structural canvas edit, it rebuilds the changed tree while retaining authored attributes on surviving nodes, such as a page root's source-only dimensions or a future field, and keeps JSX child comments with their nodes on reparent. Explicitly removing a field in source is respected on later saves.
If deleting a node or changing its kind would lose source-only attributes or child comments that canvas Undo cannot reconstruct, Fanta reports a preservation error instead of silently rewriting the file. Edit FNX directly to remove that content intentionally, then retry the canvas change. Persisted files remain protected after a refused save; use canvas Undo if the attempted operation is still visible.
## Edit with an external editor or agent [#edit-with-an-external-editor-or-agent]
External file edits are reconciled into the open project. Before writing an FNX or managed JSON candidate, an external agent can call validate\_fnx\_source with the complete candidate and project path. The tool validates without writing. For an existing managed file, it checks the candidate in the context of the full project; a new managed file receives a typed or syntax check until its companion source exists. Then save with normal file tools and inspect the canvas.
Keep existing IDs and references. Modern FNX with explicit IDs can recover a missing or damaged identity sidecar; Fanta reconstructs identity and order from the source and repairs the sidecar on a successful save. Older FNX without explicit IDs still needs its sidecar. Commit source, sidecars, headers, and assets together.
Do not rename a component by editing only its def.json name. An FNX instance may reference that name, and the project can fail to load if its references are left behind. Use the canvas or rename\_component; use the variant operations to maintain set.json and member folders. The Code workspace edits only the selected page or component FNX and companion header, while external file tools can reach other managed files.
The implementation lives in crates/fanta-fnx/src/, crates/fanta-format/src/project/, and crates/fig\_viewer/src/code\_workspace.rs. See [FNX source](/docs/formats/fnx) and [Fanta project layout](/docs/formats/fant).
# Concepts (/docs/concepts)
# Concepts [#concepts]
Fanta is a visual design editor built around a local, editable project. A project contains pages, reusable components, assets, variable collections, and a source representation of its layers. You can work on the canvas, in the inspector, or in the Code and Variables workspaces.
Start with [the document model](/docs/concepts/document-model) to understand what is saved. Then explore [pages and coordinates](/docs/concepts/pages-world-space), [auto layout](/docs/concepts/auto-layout), [components](/docs/concepts/components), [variables](/docs/concepts/variables), [vectors and SVG](/docs/concepts/vectors-icons-svg), and [prototyping](/docs/concepts/prototyping).
If you want to inspect the design as source, see [FNX](/docs/concepts/fnx-design-as-source). Source editing is available in the Code workspace, with validation and a canvas reload when you save. The editor also keeps a readable JSON view.
Fanta includes imported node types and effects whose editor support varies. The pages here describe the working controls and point out known limits so you can choose a reliable workflow.
# Pages and coordinates (/docs/concepts/pages-world-space)
# Pages and coordinates [#pages-and-coordinates]
A project can contain multiple pages. Use the Pages section of the Layers panel to create, select, rename, duplicate, reorder, or delete pages. A page contains its own layer tree, and selecting it changes the active canvas. The panel can also search and replace names and text.
Canvas coordinates use pixels with X increasing to the right and Y increasing downward. Canvas and live design tool coordinates are in world space. A node's visible position combines its parent transforms. In FNX, placement is represented relative to its parent, so a child may have different local and canvas coordinates.
When drawing, moving, or resizing, edge and center snap targets come from the active page or the component subtree opened for editing. Another page cannot supply a layer snap target, even if its layers overlap in world coordinates. Grid snapping remains available within the current canvas scope.
## Place and inspect a layer [#place-and-inspect-a-layer]
1. Select the intended page.
2. Create a frame or shape with a toolbar tool, or use a live design tool.
3. Select the layer and use the inspector's X, Y, width, height, and rotation controls for precise changes.
4. Use the Layers panel to move a layer within or between page trees.
A page root scopes rendering and export. When exporting the active page, unrelated pages do not appear just because they reuse the same coordinate values. You can also export selected layers.
Duplicating a page copies its layer tree and component definitions belonging to that page. Prototype links whose targets are inside the copied tree point to the copies; links to targets outside it keep their original destinations. Clean canvas tabs restore their project, page, or component scope when the workspace reopens.
The page operations are implemented in `crates/fig_viewer/src/design_panel.rs` and `crates/fig_viewer/src/gpui_adapters/pages.rs`. Export targeting is in `crates/fig_viewer/src/export.rs`.
# Prototyping (/docs/concepts/prototyping)
# Prototyping [#prototyping]
Prototype interactions connect an event on a layer to an action. The inspector's Prototype section provides controls for triggers, destinations, and transitions. Then use **Present** to try the flow.
Available triggers include click, drag, hover, while pressing, after a delay, and key input. Imported interactions may also include mouse enter, mouse leave, and while hovering. Actions include navigating to a destination, opening an overlay, scrolling to a target, setting a variable, updating a variant, opening a link, going back, and closing an overlay. Transitions include instant, dissolve, smart animate, and directional slide, push, or move effects.
## Build a simple flow [#build-a-simple-flow]
1. Create at least two frames or pages with the states you want to show.
2. Select the interactive layer.
3. In the Prototype section, add a trigger and navigation action.
4. Set the destination and transition.
5. Choose **Present** and test the interaction.
## Open a link from a button [#open-a-link-from-a-button]
The sample button uses an **On click** trigger to open the Fanta docs. Select the button, open **Prototype**, and use **Add interaction** to create a reaction. Open the interaction's detail control, choose **On click** for **Trigger** and **Open link** for **Action**, then enter the destination in **URL**. This example uses `https://fanta-docs.vercel.app/`, **Instant** for **Transition**, and **None** for **Motion clip**.
In an interaction's detail view, **X** closes the details and keeps the interaction. Use **Remove interaction** on its row to delete it. Closing the details applies a valid pending parameter edit; if a value is invalid, Fanta keeps the details open and shows the error. When you copy a layer tree within the document, references to destinations inside that copied tree are remapped to the new nodes. References outside it continue to point to their original targets.
The prototype data model is in `crates/fanta-doc/src/node/prototype.rs`; controls and presentation are in `crates/fig_viewer/src/prototype_panel.rs` and `crates/fig_viewer/src/view.rs`. Imported prototype features can be broader than the controls currently exposed, so test the flow in Present mode.
# Variables (/docs/concepts/variables)
# Variables [#variables]
Variables let one value drive multiple properties. Fanta's Variables workspace lets you create collections, variables, and modes, edit values, create aliases, and bind values to design properties. The active mode can be selected for a scope so the same design can resolve different values.
The variable editor handles color, number, string, and boolean values. The agent operation schema also accepts typed `typography` variables. Imported documents may contain additional variable data; inspect the current design system before changing it.
## Create a collection and bind a value [#create-a-collection-and-bind-a-value]
1. Open the **Variables** workspace.
2. Create a collection and a variable in it.
3. Set a value for each relevant mode.
4. Return to the canvas, select a layer, and bind a compatible property in the inspector.
5. Switch modes and inspect the resulting design.
In our sample, **Collections** selects the illustrative **Fanta Brand** launch-card collection, while **Groups** filters its Color, Radius, Semantic, and Spacing entries. Use **Create variable** at the bottom of the workspace to add another value. Under **Modes**, **Project** selects **Dark** and **Page: Fanta Studio** uses **Inherit parent**, so the page follows the project's mode.
Aliases point one variable at another. Check alias and mode resolution when a bound property appears to use a surprising value. Variable workspace controls are in `crates/fig_viewer/src/variables_workspace.rs`; value types are in `crates/fanta-doc/src/value.rs`.
For a color paint bound to a variable, the inspector shows its resolved color in the active mode and the variable name. The paint's opacity and visibility are read-only while the color binding is in place. Use **Detach** on the color variable to keep the resolved color as an ordinary paint, then edit the paint independently.
The Design inspector also resolves single-layer opacity, visibility, and uniform vector radius bindings through aliases and inherited mode pins. If an explicit four-corner radius is present, it takes precedence over the uniform radius binding. An unresolved binding shows the layer's fallback value with a label and can still be detached. A direct text-content binding on component text prevents local text edits in both the canvas and the instance Content row; edit the variable or remove the binding to change that text.
## Work through an agent [#work-through-an-agent]
Call `get_design_system` (or in-app `design_system`) first to read collection IDs, modes, typed values, and selected-node bindings. The external `batch_design` operations can create collections and variables, add a mode, set values or aliases per mode, set an active mode for the document or a frame, and bind or unbind compatible properties. Binding targets include fill or stroke color, stroke width, corner radius, opacity, visibility, text content or style, and clip size. Use exact IDs from the response for follow-up edits; names work only when unique.
The managed variable sources are `doc/variables.json` and `doc/active_modes.json`. If you edit one directly, validate the complete candidate with `validate_fnx_source` before saving and inspect the canvas after reload. See [style and variables](/docs/tools/style-variables) for an MCP example.
# Vectors, icons, and SVG (/docs/concepts/vectors-icons-svg)
# Vectors, icons, and SVG [#vectors-icons-and-svg]
Fanta has native vector tools: Pen, Node Edit, basic shapes, line, arrow, polygon, star, and path selection. You can refine paths on the canvas and use layer actions such as outline stroke or flatten when appropriate. A selected layer can be copied as SVG from its context menu, and the inspector can export SVG or PDF.
Right-click a selected vector on the canvas and choose **Edit vector** to enter Node Edit. Its path anchors appear as soon as editing opens. **Flatten** checks whether it can preserve the artwork's appearance and behavior. It can refuse variable bindings, nested component masters, animated children, masks, unsupported child effects or blends, clipped content, and pattern sources referenced by another layer. Simplify or detach that content first. A supported flatten remains undoable.
For authoring hits, rounded ancestor clips exclude invisible portions of Text, Vector, and Bitmap children. Node Edit can reach a visible vector underneath a clipped child; selected-node controls and parent-frame bounds keep their normal behavior. Source tests cover this repair, while matching installed-app acceptance remains pending.
## Boolean shapes [#boolean-shapes]
A Boolean layer keeps its operand shapes and an operation: **Union**, **Subtract**, **Intersect**, or **Exclude**. Select it to change the operation and edit applicable fills and strokes in the inspector. A supported Figma Boolean import keeps editable operands and the imported baked vector appearance. Changing its operation or operands makes Fanta recompute the result. If an imported operation or operand cannot be represented, Fanta may keep a flattened vector instead and report an import warning; inspect the layer before relying on further Boolean edits.
To reshape an authored Boolean, enter one of its vector operands with **Edit vector**, drag a path anchor, and leave Node Edit. The Boolean result updates from the operands. Check the result and save the design; imported baked Boolean geometry may behave differently when recomputed.
## Text on a path [#text-on-a-path]
Select one visible, unlocked vector and choose **Text on Path**. Fanta replaces the vector with a TextPath layer, carries its path into the text layer, and opens inline editing. The path must be finite and nonzero length. Rounded corners and clipped geometry must be flattened or removed first. The vector may have no paint or one normal solid fill or stroke; gradients, image paints, blend modes, and multiple paints are not accepted by the conversion.
TextPath has its own FNX element and owned path data, so it survives a source round trip. To change the text later, select one editable TextPath layer and choose **Edit object** in the Design inspector header, or use **Edit text** in its canvas context menu. The inspector action selects all text when editing opens. See [Tools](/docs/editor/tools) for the canvas workflow.
## Work with an icon [#work-with-an-icon]
1. Draw with Pen or start from a basic shape or arrow.
2. Select **Node Edit** to adjust the path.
3. Set fills and strokes in the inspector.
4. Copy the layer as SVG or export it from the inspector.
5. Reopen the exported file in your target workflow to confirm its appearance.
The live design tool surface can create frames, rectangles, ellipses, text, images, and instances and can change their properties. It does not expose a dedicated `create_svg` or `create_icon` operation. SVG media import has a conversion path that can make supported geometry editable, but it rejects features such as embedded images, text, masks, filters, patterns, and some gradients. For complex SVG artwork, verify the imported result.
Tool definitions are in `crates/fig_viewer/src/tools.rs`, Text on Path conversion in `crates/fanta-tools/src/text_path.rs`, SVG conversion in `crates/fig_viewer/src/generation_media.rs`, and export in `crates/fig_viewer/src/export.rs`.
# Project Assets (/docs/editor/assets)
The **Assets** section of the file inspector lists media stored with the open project. It includes generated results added through **Add to project** and supported image, video, or audio files already used by the design. Each row shows a name, media type, size, and a preview when available. Assets remain in the project even when they are not placed on a page.
## Add and place generated media [#add-and-place-generated-media]
1. Open a project canvas and create an image, SVG, video, or audio result in [Generation Workspaces](/docs/agents/media-generation).
2. Select the result and choose **Add to project**. Fanta copies supported media into the project and records it in `doc/asset_library.json`.
3. Expand **Assets** in the file inspector. Choose the destination under **Place in**, then use the **+** button on the asset row. Its tooltip says **Place on selected page**.
4. Inspect the new layer. Fanta places it near the center of the visible canvas and fits large media within the viewport. You can place a stored asset on another page later.
PNG, JPEG, and WebP become bitmap layers. A supported SVG is parsed into editable vector content. MP4 becomes a video layer. WAV, MP3, and FLAC become audio layers with a decoded duration. On macOS, selected audio and video layers have playback controls in **Motion** or **Prototype** mode. In a bounded MP3 placement check, storage and history survived cold reopen, but the Audio preview was absent for both the original and newly placed MP3; WAV preview was not verified.
## Place a file from your computer [#place-a-file-from-your-computer]
On an editable canvas page, press **Command Shift K** to open **Place image or MP4 video**. Choose one PNG, JPEG, WebP, GIF, BMP, TIFF, or MP4 file. Fanta decodes and places it near the center of the visible canvas as a layer, fits oversized media to the viewport, and stores its bytes with the project. MP4 placement requires the macOS video decoder. The file picker also rejects unsupported or corrupt files and reports the reason on the canvas.
Direct placement has separate limits from **Add to project**: images are capped at 32 MiB, 16,384 px per side, and 32 megapixels; MP4 files are capped at 100 MiB. Finish any active edit before placing media, and stay on the same page while the file is prepared. If preparation exceeds 30 seconds, try a smaller file.
## Storage and limits [#storage-and-limits]
Project media bytes are stored under `assets/`; the library's names and kinds are stored in `doc/asset_library.json`. Commit those files with the page source so another copy of the project can resolve the media. See [Document model](/docs/concepts/document-model).
**Add to project** rejects an empty result, a file over 128 MiB, or an unsupported media format. A raster image over 32 megapixels cannot be placed on the canvas. SVG must parse as supported editable vectors; MP4 and audio must decode to usable media. Missing or unsupported assets remain visible in the file inspector's Assets section with the placement action disabled and a reason. The Design inspector's image and video paint source chooser lists only compatible project assets. Placing also requires a page and a clean, editable source state.
Local placement is implemented in `crates/fig_viewer/src/view_media.rs` and `crates/fig_viewer/src/generation_media.rs`. Masks cannot be added to Assets as standalone media. They remain inputs to supported generation workflows.
# Comments (/docs/editor/comments)
# Comments [#comments]
Comments are anchored to a point on a design page. They are saved in page metadata, so they travel with the project. Open **Comments** mode or choose the **Comment** tool (**C**), click the canvas to place a pin, write a message, and send it. A draft does not become a saved comment until you send it.
Click a pin to open its thread. The thread shows the original message, replies, author, and relative time. You can reply, resolve or reopen the thread, delete it, and copy its text. The document **Comments** panel lists threads from all pages, shows open and resolved counts, and opens a selected thread on its page. Dev mode can read and copy comments, but its thread mutation controls are disabled.
## Add context to a message [#add-context-to-a-message]
The composer has controls to mention an agent or layer, attach images or files, and choose an AI skill. Skills are **Summarize**, **Search**, **Format**, and **Review**. When a message with a skill is posted, Fanta opens its prompt as a reviewed draft in the Agent Panel; posting the comment does not submit the agent run. Attachments are saved as path references in comment metadata rather than embedded bytes, so keep referenced files accessible to collaborators.
You can attach context to the initial message or a reply. If a reply has unsent text or attachments, Fanta asks you to send or clear it before switching to another thread or placing another comment. If posting fails, the composer retains its contents for retry.
## Comment on motion [#comment-on-motion]
In **Motion**, use the time comment control at the current playhead, then place a pin and send the comment. Its anchor stores both clip and time. The document Comments panel labels a timed thread and navigates to that clip and time when opened. See [Motion](/docs/editor/motion).
Implementation: `crates/fig_viewer/src/comments.rs` defines page metadata, threads, replies, attachments, skills, and motion anchors; `crates/fig_viewer/src/comments_ui.rs` handles composer and canvas interactions; `crates/fig_viewer/src/comments_panel.rs` lists document comments.
# Dev mode (/docs/editor/dev-mode)
# Dev mode [#dev-mode]
Dev mode is for reading a loaded design and recording implementation details. Enter it from the mode switcher or press **Shift D** while the canvas has focus. Fanta switches to **Inspect** and shows a compact toolbar with Inspect, Hand, Measurement, Annotation, **Saved Code**, and an exit to Design.
Dev mode keeps artwork and both FNX and JSON source read-only. You can inspect a layer and open the saved Code workspace, but you cannot use the Variables workspace until you return to Design. Save or cancel active source edits, art edits, or comment drafts before changing the Dev session. A **Readiness unavailable** button is present but disabled in the current build.
## Measurements [#measurements]
1. Select **Measurement** or press **Shift M**.
2. Drag on the visible page from the start point to the end point. Hold Shift while dragging when you want the constrained measurement behavior.
3. Select a measurement to inspect it. With the Measurement tool, drag either endpoint to adjust it or drag its segment or label to move it. You can copy or delete a selected measurement from its controls.
Measurements belong to the page, so switching pages shows that page's measurements. They are stored as page metadata and participate in document undo and redo. They are separate from the artwork layer tree. An interrupted drag keeps a preview that can be canceled with Escape.
## Annotations [#annotations]
1. Select **Annotation** or press **Shift T**.
2. Click the page, write a note, and choose **Add**.
3. Select its pin or choose it from **Annotations on this page**. You can copy its text, edit it, move the pin, or delete it.
Notes stay at a fixed page position and record author and creation time. Unsaved note text is retained if an operation is interrupted so you can copy or cancel it. Annotations are also page metadata, separate from ordinary layers.
**Inspect** can read existing measurements and notes without moving or editing them. Measurement and Annotation tools require an editable design page for changes. The marks are available in Design and Dev canvas sessions.
Implementation: mode boundaries and toolbar are in `crates/fig_viewer/src/view_dev_mode.rs`; page marks and their controls are in `crates/fig_viewer/src/measurements.rs`, `crates/fig_viewer/src/annotations.rs`, `crates/fig_viewer/src/view_measurements.rs`, and `crates/fig_viewer/src/view_annotations.rs`.
# Editor (/docs/editor)
# Editor [#editor]
Fanta's editor has three main workspaces: **Canvas**, **Variables**, and **Code**. Canvas is where you select and draw layers. Variables manages reusable values and modes. Code opens the active page or component's FNX and JSON source files. Saving a source edit validates the project before the canvas reloads it.
Within the canvas, modes include **Design**, **Motion**, **Draw**, **Dev**, **Code**, **Prototype**, **Comments**, and **Build**. The available panels and controls follow the selected mode and layer. The Layers panel organizes pages and nodes; the file inspector's **Assets** section places stored media; the design inspector edits the current selection. A toolbar gives you selection, shape, drawing, text, and view tools.
## A typical session [#a-typical-session]
1. Create a design with **File → New Design**, or open an existing design.
2. Select a page and create a frame, shape, text layer, or other supported node.
3. Select the layer on the canvas or in Layers. Use the inspector for precise properties.
4. Organize the tree through Layers: rename, hide, lock, group, reorder, or move a layer to another page. Use **Assets** to place a stored image, SVG, video, or audio result.
5. Use **Variables** for shared values, **Code** for the active page or component's FNX and JSON source, and **Present** for prototype testing.
6. Export a selection or page through the inspector when you need a deliverable.
Fanta saves its local project after a short idle period. If saving fails, it shows a notice until a later save succeeds; the design remains unsaved in the meantime. The project is a folder, so keep its metadata, pages, components, and assets together. Read [Document model](/docs/concepts/document-model) for the file structure.
Learn the [tools](/docs/editor/tools), [inspector](/docs/editor/inspector), [Project Assets](/docs/editor/assets), [surfaces](/docs/editor/surfaces), [Motion](/docs/editor/motion), [Dev mode](/docs/editor/dev-mode), [Comments](/docs/editor/comments), [Settings](/docs/editor/settings), and [shortcuts](/docs/editor/shortcuts). Editor modes and workspaces are defined in `crates/fig_viewer/src/editor_session.rs`.
# Inspector (/docs/editor/inspector)
# Inspector [#inspector]
The inspector reflects the current selection. Select one layer for its full set of compatible controls or several layers for shared properties and multi-selection actions. A control may be absent or unavailable for a node type that does not support it.
The inspector toolbar has zoom out and in, a percentage menu with 25%, 50%, 100%, and 200%, **Fit to View**, **Fit to Selection**, and a control to collapse or show Properties. When Properties is collapsed, these view controls stay in a compact floating bar. In Prototype mode, the toolbar also offers **Play Prototype** when the document has an entry frame.
Common sections include geometry and rotation, corners and smoothing, appearance and opacity, blend mode, fills and strokes, typography, image fitting, layout and child layout, effects, prototype interactions, variable bindings, components and instances, and export. Use the inspector when exact dimensions or values matter; canvas handles are faster for rough adjustments.
With one layer selected, the selection header offers **Select matching layers** when another layer of the same kind exists on the active page. It selects matching descendants on that page without changing artwork or adding an Undo step. Sections match other Sections, even when their paints or inspector presets differ; they do not match ordinary Frames or Groups. Component masters keep their component identity. Converting a layer to a Frame or Section changes which layers match it.
For a selection, the arrange controls align layers by left, center, right, top, middle, or bottom edge. With three or more selected layers, distribute them horizontally or vertically; **Tidy up** works with two or more. Transform actions rotate the selection clockwise by 90° or flip it horizontally or vertically. Controls that cannot apply to the current selection are unavailable. The default inspector does not expose editable constraints.
The opacity, visibility, and uniform vector radius fields show resolved values when bound to variables, including aliases and active or inherited mode pins. Explicit independent corner values take precedence over a bound uniform radius; unresolved bindings show the layer's fallback value and remain detachable. Four authored corners remain independent even when all four numbers match. For a mixed selection, opacity shows a mixed state and applies one value to the selected layers when the edit commits. Drag a numeric value to scrub it; Escape cancels a draft, and a completed edit is undoable. Mixed-selection opacity does not preview directly on the canvas during the scrub.
A valid numeric property draft still in focus is committed before Save, Save All, or a close action with Save. Invalid input blocks that save and remains available for correction or cancellation. Merely focusing an X/Y field whose display is rounded does not replace its underlying fractional value; a typed fractional X/Y edit is preserved.
For a grid frame, Layout exposes column and row tracks, gaps, automatic or manual item positioning, and each selected child's cell, span, and alignment. [Grid layout →](/docs/concepts/auto-layout) An instance's variant choices appear before its other component properties; picking a value swaps to the matching variant when that combination exists. [Components →](/docs/concepts/components)
An instance's component section also lists Content rows for its visible text layers. Edit a Content row to create a local text override, or reset it to use the master value. A direct text-content variable binding makes that row read-only; edit the variable or remove its binding first. Nested instance text is not recursively listed as a Content row.
## Paints and effects [#paints-and-effects]
The paint list supports adding and removing fills or strokes, toggling individual paint visibility, changing a paint kind, and editing gradient stops in a popover. A gradient edit previews on the canvas and commits as an undoable change. The effects list supports drop and inner shadows. Available controls depend on the selected node and paint. During stable pans, Fanta can reuse rendered effect layers; moving or editing artwork refreshes affected effects while unrelated layers may remain cached. This does not change the saved design.
For an image or video paint, the source chooser lists placeable project assets. It shows a project's asset-library name when available, otherwise a layer name or a generic name; video sources are available on macOS. The list follows asset and layer changes, Undo/Redo, and project reloads. [Project Assets →](/docs/editor/assets)
To crop a selected image, double-click it on the canvas or use **Crop image** in the canvas context menu. The Design canvas then shows Ratio, Cancel, and Apply crop controls above the toolbar. The pending crop is a preview until applied. [Crop an image →](/docs/editor/tools#crop-an-image)
A Boolean layer exposes its Union, Subtract, Intersect, or Exclude operation, plus applicable fills and strokes. Color paints bound to a variable show the value resolved for the active mode and the variable name. Detach the color variable to edit that paint's color, opacity, or visibility independently; detach keeps the currently resolved color. Specialized layer kinds can expose common wrapper properties such as position, layer appearance, effects, and export even when their internal content is not editable here.
## Text on Path [#text-on-path]
A selected TextPath layer exposes typography plus controls for where text starts on the path, direction (forward or reverse), and which side of the path carries the text. Start can be edited as a segment and position or as an offset along the current contour. With one editable TextPath layer selected, choose **Edit object** in the inspector header to open inline text editing with all text selected. This action is unavailable for multiple selections, locked layers or ancestors, read-only states, and virtual TextPath content inside an instance. The editor checks the current selection again before acting, so an outdated inspector command does not edit a different layer. This layer has a focused property set: paragraph spacing and indentation, list controls, vertical alignment, text resize and truncation, and some decoration and case controls are read-only because they do not exist on text paths. The text fill is limited to color and opacity.
TextPath X and Y fields use its painted bounds. Editing one coordinate moves the visible path text to that displayed position, including under a transformed parent, without changing the path shape or other coordinate.
## Export [#export]
1. Select one or more layers to export each selected layer. To export the active page, clear the selection and activate that page.
2. Open the **Export** section in the inspector.
3. Choose PNG, JPG, SVG, or PDF.
4. For raster formats, choose 1×, 2×, 4×, or custom dimensions.
5. Export and inspect the resulting file.
Raster export is limited to 8192 px per side and 16 million total pixels. If a requested size exceeds a limit, reduce the scale or dimensions. Exporting the active page scopes output to that page. Multiple selected layers can be exported as targets.
Fills include solid colors, gradients, patterns, images, and shaders. Video paint is available on macOS. The renderer uses Skia's standard blend modes, additive blending for Linear Dodge, and a separate blender for Linear Burn. Some imported or visible controls may have incomplete editing paths and show a notice. Drop shadows and inner shadows render as effects. For any imported design or unusual paint combination, inspect the exported result.
Inspector UI and snapshots are in `crates/fig_viewer/src/properties_panel.rs` and `crates/fig_viewer/src/properties_snapshot.rs`; export limits and formats are in `crates/fig_viewer/src/export.rs`. Paint handling is in `crates/fanta-render/src/paint.rs`.
# Motion (/docs/editor/motion)
# Motion [#motion]
Motion mode adds an animation timeline below the canvas and an Animations inspector for the selected layer. Motion is stored in the design document as clips, tracks, and keyframes. Select one layer before adding an animation or keyframe.
## Create an animation [#create-an-animation]
1. Open **Motion** with a design page loaded and select one layer.
2. If the timeline has no clip, choose **Create animation**.
3. In the Animations inspector, use **+** to add Position, Scale, Rotation, Size, or Opacity. These presets create start and end keyframes. The toolbar also offers **Slide in**, **Scale in**, **Rotate in**, **Grow**, and **Fade in**.
4. Select the animation to adjust its direction or amount, delay, duration, and easing. Drag the playhead or press **Play** to preview it.
The preset editor recognizes only its own simple start/end pattern. If you change timing or values into a custom keyframe sequence, edit it in the timeline; Fanta displays **Custom keyframes** rather than rewriting it with the preset controls. A layer can have one animation per property in an active clip. **Path** appears in the add menu as “soon” and is disabled. Size is offered only for compatible layers.
## Edit the timeline [#edit-the-timeline]
The timeline offers Play/Pause, Return to start, Loop playback, a Current time field, clip name and duration, a **+ Keyframe** menu, and zoom controls. Type a time in Current time and press Return to seek the playhead. The keyframe menu includes Position X/Y, Rotation, Scale X/Y, Opacity, and Fill color. Select a keyframe to change its interpolation between Linear and Hold, choose an easing preset or custom cubic Bézier values, or delete it. Drag a keyframe horizontally to retime it within the clip. Click the clip name or duration to edit them.
The capture shows a **1.20 s** clip with the playhead at **0.80 s**. Expand **CTA Button** in the timeline to see its **Opacity** track and the diamond keyframes. Select a diamond to edit that keyframe, or drag it along the time ruler to change when it occurs.
Turn on **Auto key** to edit compatible values in the **At playhead** inspector while playback is paused. Those edits preview immediately and commit as keyframe changes. Without Auto key, the playhead values are read-only. For multiple clips, choose the active one from the Motion inspector. Playback cannot start without a clip of positive duration.
## Comment on a moment [#comment-on-a-moment]
Motion can attach a comment to the active clip and playhead time. Use the **time comment** control, place its pin on the canvas, and send the comment. Opening that thread from the document Comments panel returns to the associated clip and time. A pending comment must be sent or canceled before switching context.
Implementation: `crates/fig_viewer/src/motion_panel.rs` defines presets, inspector properties, and disabled Path animation; `crates/fig_viewer/src/timeline.rs` defines playback and keyframe controls; `crates/fig_viewer/src/motion_edit.rs` commits clip and keyframe edits; `crates/fig_viewer/src/comments_ui.rs` anchors and navigates motion comments.
# Settings and build differences (/docs/editor/settings)
Fanta's Settings window groups everyday preferences and account controls. The available actions depend on the build and the signed-in account.
In Settings search, Escape clears the search while keeping Settings open; Command-W closes the Settings window.
| Area | Current controls |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| General | Startup view, autosave, quit confirmation, and system file dialogs. |
| Appearance | Color and icon themes, interface text size. |
| Canvas | Show or hide Layers, Inspector, Files, Git, and Threads panels. |
| Editor | Cursor and line-number settings, FNX source text size, keyboard shortcuts. |
| AI & Models | Open the Agent Panel and configure model providers. |
| MCP & Tools | Toggle Fanta hosted tools or the live canvas MCP server; manage configured MCP servers. |
| Account, Billing, and Privacy | Account links, credit and plan views when available, diagnostics and usage controls, legal links. |
## MCP connections inside Fanta [#mcp-connections-inside-fanta]
The **MCP & Tools** page separates Fanta's hosted tools, the live canvas server used by external clients, extension tools, and MCP servers that the in-app agent can call. For the last group, Fanta can save a server globally or for a workspace, add or edit it, enable or disable it, authenticate, retry, remove it, and show connection status. Supported connection types include a local command and a remote HTTP endpoint. [Connect an external agent to Fanta's canvas →](/docs/mcp/connect)
The committed defaults differ by release channel. Preview and Dev point account, model, and hosted MCP requests to Fanta's v2 service and enable a separate remote **fanta-design** MCP connection. Stable keeps the original service endpoint and leaves that connection disabled. Available remote tools and models depend on the connected service; check the active build and account when one is missing.
The Mac App Store feature build cannot launch local command-backed MCP servers, external agent processes, terminal commands, or external formatters from inside Fanta. Remote project connections are also disabled. Its MCP settings direct you to remote HTTP servers instead. This restriction does not remove the live canvas server toggle or prove that an external client cannot connect to the Store build; that inbound path needs build-specific verification. Non-Store builds retain the local command option.
## Account and privacy [#account-and-privacy]
Billing views show account state, credit balance, usage, plans, and activity when the service provides them. Usage offers rolling 7, 30, and 90-day UTC windows ending at the request time; the first and last calendar days in its daily chart can therefore be partial. Daily usage and usage by API key use the same request bounds, and CSV export uses the selected range. New AI credit and subscription purchases happen through [web Billing](https://app.fantaisa.net/billing). Public accounts receive no signup, referral, or trial credits. Local editing remains free; hosted AI requires purchased credits. Restore, sync, redemption, and introductory trial actions are discontinued. Previously purchased Apple subscriptions must still be canceled in the Apple Account. Checkout availability, products, prices, and account entitlements come from the live billing service. Deleting a Fanta account is separate from canceling a subscription.
Privacy controls include crash diagnostics and anonymous usage metrics. The App Store feature build also describes macOS access to user-selected files, saved sign-in, and network services under **App Access**. See [Install and build](/docs/getting-started/install) for distribution status and setup.
# Keyboard shortcuts (/docs/editor/shortcuts)
# Keyboard shortcuts [#keyboard-shortcuts]
These are the default macOS canvas bindings. A tool can use a shortcut while the canvas has focus; a text field may consume the same key for typing.
| Action | Shortcut |
| ---------------------------------- | --------------------------------------- |
| New Design | Command N |
| Undo / Redo | Command Z / Command Shift Z |
| Copy / Cut / Paste | Command C / Command X / Command V |
| Duplicate | Command D |
| Place local media | Command Shift K |
| Delete | Delete |
| Select all | Command A |
| Group / Ungroup | Command G / Command Shift G |
| Frame selection | Command Option G |
| Present | Command Option Return |
| Zoom in / out | Command + / Command - |
| Zoom to 100% | Command 0 |
| Zoom to fit / selection | Shift 1 / Shift 2 |
| Move | V |
| Hand | H; hold Space to pan temporarily |
| Scale | K |
| Rectangle / Ellipse / Line / Arrow | R / O / L / Shift L |
| Pen / Pencil | P / Shift P |
| Edit Path | A |
| Frame / Section / Slice | F / Shift S / S |
| Text | T |
| Comment | C |
| Measurement / Annotation | Shift M / Shift T |
| Enter Dev mode | Shift D |
| Nudge | Arrow key; Shift plus arrow moves 10 px |
| Cancel current interaction | Escape |
Escape commits and exits an active text edit; for a text draft blocked by a direct variable binding, it cancels the draft. These bindings come from `assets/keymaps/default-macos.json` and canvas handlers in `crates/fig_viewer/src/view.rs`. Tool or operating-system settings may alter what reaches the canvas.
Custom keymap action names differ by build: the signed Build45 app uses `zed::` for inherited app actions, while current source uses `fanta::`. If you carry a custom keymap into a future source-based build, review its app action names and verify each binding in that build. This rename has not been validated in a newer public installer.
# Editor surfaces (/docs/editor/surfaces)
# Editor surfaces [#editor-surfaces]
## Canvas and Layers [#canvas-and-layers]
The canvas shows the active page and its selectable layers. The Layers panel lets you select and range-select layers, expand groups, rename nodes, toggle visibility and locking, and drag layers above, below, or inside other nodes. When you open a component master, its root appears as an editable row in Layers; expand it to see the master's children. Its context menu includes duplicate and delete, copy as SVG or PNG, copy properties, move to page, group and ungroup, frame or section conversion, flatten, outline stroke, mask, media replacement and cropping, layout, and component actions. The available actions depend on the layer.
The Pages area of Layers creates, selects, renames, duplicates, reorders, and deletes pages. It also includes a page link action and name/text search and replace. Right-click on the canvas for a shorter menu tailored to what you clicked, including direct text, vector, image, media, and component actions. [Canvas tools →](/docs/editor/tools)
Drag the edge of the Layers or Properties sidebar to resize it. The panel contents respond as the width changes.
## Files and Project Assets [#files-and-project-assets]
The file inspector shows project files and an **Assets** section for stored images, SVG, video, and audio. Generated results can be added to this library without creating a page layer. Choose a target page under **Place in** and use the asset row's **+** button when you want a layer. Missing files or unsupported formats show a disabled placement action with a reason. [Project Assets →](/docs/editor/assets)
## Variables [#variables]
The Variables workspace manages collections, modes, values, aliases, and bindings. Create a collection and variable, set mode values, then bind compatible selected layer properties. Scope a mode to preview a different value set.
## Code [#code]
The Code workspace opens the active page's `page.fnx` and `page.json`, or a component master's `master.fnx` and `def.json`. Select **FNX** or **JSON** to edit that source file. **Find** searches the selected source buffer. Save the design once before opening source. Save or discard canvas changes before editing source; while either source buffer has unsaved changes, canvas content editing is locked, but pan and selection remain available.
While a source draft is unsaved, select one canvas layer to read its last accepted properties in the Design inspector, including position, size, and layout gap. These rows cannot be edited until the draft is saved or discarded. With no selection or a mixed selection, the inspector asks you to select one layer. A source draft also blocks **Go to main component** when that action would switch page or component scope; save or discard the draft first.
Save source to validate the edited file against the project, write it, and reload the canvas. FNX saves also maintain its ID sidecar. Invalid JSON stays in the editor with an error and does not replace the saved file or the last good canvas. If both FNX and JSON have changes, Fanta saves and validates them in sequence. **Discard draft** discards unsaved edits in the selected source file only; switch between FNX and JSON to check each buffer. Resolve any on-disk file conflict before retrying. When an in-app agent is writing the selected FNX file, Code shows its name and can follow its live source location. Choose **Pause follow** to navigate independently, and **Follow** to resume.
The canvas can also show an **Agents** control for active design agents. Select an agent to follow its current page or component and its Canvas, Variables, or Code workspace. Select the agent again to stop following. Source activity can open the relevant source tab. A clean canvas tab restores its project, page, or component location when the workspace reopens.
Current source saves an intentionally empty design tab layout, so restarting does not reopen a tab that you closed. Explicitly opening that project again opens one tab; repeating Open reuses it after a project manifest replacement. These paths have bounded source tests; installed-app behavior beyond the recorded workflows remains unverified.
## Dev mode [#dev-mode]
Dev mode is a read-only artwork inspection session with page-bound measurements and annotations. It starts on a loaded canvas, activates Inspect, and offers **Inspect**, **Hand**, **Measurement**, **Annotation**, and **Saved Code**. The Code workspace is read-only while Dev mode is active; Variables is unavailable. A **Readiness unavailable** control is disabled in the current build. See [Dev mode](/docs/editor/dev-mode) for the workflow.
## Motion [#motion]
Motion mode shows the animation timeline and Motion inspector. Create or select a clip, add an animation to one selected layer, and preview or edit keyframes at the playhead. See [Motion](/docs/editor/motion) for properties, timing, and current limits.
## Build [#build]
Build mode opens **Plan & build** beside the canvas. With a signed-in account on a build connected to Fanta's v2 service, describe a design task, review each proposed canvas change, then **Accept**, **Retry** with feedback, **Skip**, or **Stop**. You can choose automatic acceptance. Retry and Skip undo the latest preview when it is still safe to undo; Stop leaves changes already applied on the canvas. [Agent workflows →](/docs/agents)
## Prototype and comments [#prototype-and-comments]
Use the Prototype inspector controls to connect triggers and actions, then **Present** to test the flow. The Comments mode and tool provide a page-anchored discussion surface with threads, replies, attachments, mentions, resolution, and time-linked comments on motion clips. The document Comments panel lists comments across pages and opens the selected thread. See [Comments](/docs/editor/comments) for mentions, attachments, replies, and reviewed Agent drafts.
Fanta has a live local design tool interface for agents. Its operations cover creating common nodes, changing style and layout properties, and inspecting structure; it does not use a required fixed HTTP port. See [agent integration](/docs/plugin) and [Settings](/docs/editor/settings) for current setup and build differences.
Layer behavior is in `crates/fig_viewer/src/design_panel.rs` and `crates/fig_viewer/src/layer_context_ops.rs`. Variables and Code are in `crates/fig_viewer/src/variables_workspace.rs` and `crates/fig_viewer/src/code_workspace.rs`.
# Tools (/docs/editor/tools)
# Tools [#tools]
The toolbar includes selection tools, shapes, frames, drawing tools, text, comments, and navigation. You can choose a tool from the toolbar or use a shortcut where one is assigned.
## Select and transform [#select-and-transform]
**Move** selects layers and moves them. Click a layer, Shift or Command click to extend the selection, or drag from empty canvas to draw a marquee. Double-click drills into a container's child; an initial click on a nested layer can select the outer frame first. Selection shows resize and rotation handles. **Scale** is a dedicated tool for scaling selected content. Arrow keys nudge by 1 px; Shift plus an arrow nudges by 10 px. Escape cancels an active interaction.
With **Move** active in Design mode, double-click an already selected text layer to edit text, a vector to edit nodes, or an image to crop it. Double-clicking an instance opens text editing if the pointer is over editable instance text; otherwise it shows Properties. Video, audio, and other supported non-shape layers also reveal Properties. The first double-click into a frame or group selects a child; a later double-click can edit that child. The editor checks the visible hit target, so a covered or locked layer does not open through another layer.
Entering **Edit vector** or **Edit Path** shows the selected path's anchors immediately. To edit a Boolean operand, enter its selected vector child and use those anchors. During ordinary text editing, Escape commits the text and exits. If a text-content variable binding begins controlling the text while a draft is open, Fanta keeps the draft and asks you to copy it if needed; Escape then cancels that blocked draft.
**Inspect** selects artwork for inspection in Dev mode without editing it. **Path Selection** targets paths. Rectangle Selection, Ellipse Selection, Lasso, Polygonal Lasso, and Magic Wand provide area selection. **Crop** edits an image's visible area. **Hand** pans the view; hold Space to pan temporarily.
Moving layers can snap to the 8 px grid and to other layers' edges or centers. Layer targets come from the active page, or the component subtree you have opened for editing; layers on unrelated pages do not attract the drag. Watch the canvas guides when positioning objects. If a Select drag loses its mouse press outside the canvas or when the window deactivates, Fanta cancels the pending move, so returning the pointer does not continue it.
Right-click a layer on the canvas to select it and open a context menu. A click within the current selection keeps that selection; a click on an unselected nested layer selects its top-level layer for the page. The menu offers copy, cut, paste, duplicate, delete, grouping, and front/back ordering where editable. Depending on the target, it also offers **Edit text** for ordinary or path text, **Edit vector**, **Crop image**, media or layer Properties, component actions, auto layout, outline stroke, flatten, or mask actions. A Properties entry reveals the Design inspector if it is collapsed. Specialized layers expose their own Properties entry, including Boolean, node graph, 3D, AI artifact, and embed layers. Escape closes the menu without clearing the selection. Right-click empty canvas to clear the selection and access Paste. The canvas menu is unavailable while presenting a prototype or using Draw mode.
Copy and paste work within one design document, including between its pages. Canvas paste into a different document is unavailable. Duplicating a component master or a complete variant set also duplicates its component definitions, so the copy can be edited independently.
Keyboard Cut, Delete, and Duplicate respect a selected layer's own lock and locks inherited from its ancestors. When Cut or Delete cannot preserve component content, Fanta refuses the operation with an explanation; a failed Cut leaves the existing clipboard unchanged. See [Components and instances](/docs/concepts/components) for the supported copy and removal cases.
## Crop an image [#crop-an-image]
In Design mode on an editable canvas, select an image and double-click it, or choose **Crop image** from its canvas context menu. The Crop tool shows **Ratio**, **Cancel**, and **Apply crop** controls above the toolbar. Choose a ratio, such as **1:1**, then drag a crop rectangle on the image. The ratio constrains the preview before the document changes.
Build45 source keeps those controls inset when the canvas is narrow. This exact layout is not part of its recorded installed-app checks.
Choose **Apply crop** to commit the pending rectangle as one undoable change. Applying without a pending rectangle leaves the document unchanged. **Cancel** first discards a pending rectangle while keeping Crop active; choose **Cancel** again to leave Crop. The controls are available while Crop is active in editable Design mode.
## Create and draw [#create-and-draw]
* **Frame**, **Section**, and **Slice** establish structure or export areas.
* **Rectangle**, **Ellipse**, **Line**, **Arrow**, **Polygon**, and **Star** create geometry.
* **Pen** builds paths; **Node Edit** adjusts their geometry.
* **Brush**, **Pencil**, and **Eraser** provide freehand drawing and editing.
* **Text** creates text layers.
* **Comment** places a comment in the canvas workflow.
* **Measurement** and **Annotation** create page-bound developer marks in Dev mode; they do not create ordinary artwork layers.
## Text on Path [#text-on-path]
1. Select exactly one visible, unlocked vector path.
2. Choose **Text on Path**. Fanta converts that vector to a TextPath layer and opens inline text editing.
3. Replace the placeholder text and use text controls to style it.
The conversion keeps the vector path as the text baseline. It needs a finite path with nonzero length. Flatten rounded corners and remove clipping first. The source vector must have either no paint or exactly one normal solid fill or stroke; gradients, image paints, blends, and multiple paints are rejected. The converted layer is editable and renders on the canvas. Its inspector can change the text start, direction, and side of the path. Some ordinary text layout controls do not apply to path text. See [Vectors, icons, and SVG](/docs/concepts/vectors-icons-svg).
The toolbar catalog is in `crates/fig_viewer/src/tools.rs`. Selection and transform behavior are in `crates/fanta-tools/src/select/dispatch.rs` and `crates/fanta-tools/src/scale.rs`; Text on Path conversion is in `crates/fanta-tools/src/text_path.rs`, and snapping is in `crates/fanta-canvas/src/snap.rs`.
# Export designs (/docs/formats/export)
Fanta's visual export controls support PNG, JPG, SVG, and PDF. Add export settings in the inspector, choose a format, and run the export. Raster PNG and JPG presets offer 1x, 2x, and 4x scale. The app writes files into the project's exports/ directory.
## What gets exported [#what-gets-exported]
If layers are selected, each selected layer is exported separately using its visual bounds. With no selection, Fanta exports the active page. Output names are made safe for filenames, and duplicate selected-layer names receive distinct names.
PNG and JPG are raster images. JPG is encoded as opaque RGB at a fixed quality setting of 95; transparent areas are composited over white. JPG compression can change pixel colors, particularly near sharp transitions. Use PNG when you need transparency or pixel-level comparison, and inspect important JPG exports. SVG and PDF are visual outputs, not editable Fanta project files. To keep working with design layers, retain the [native project](/docs/formats/fant). Canvas comments and editor measurement annotations are review aids; they are excluded from rendered output.
## Size limits [#size-limits]
Raster export is bounded by an 8192-pixel maximum dimension and about 16 million total pixels per output. A large design at 4x may exceed these limits; reduce the scale or export a smaller selection. The export flow reports failures rather than silently writing a partial result.
## Agent screenshots are different [#agent-screenshots-are-different]
The local MCP get\_screenshot tool returns PNG image content to the agent for inspection. It captures the active page by default, or a specified page or node, and defaults to a 768-pixel maximum dimension; the requested maximum is clamped to 16–1568 pixels. It is a review tool, not the inspector's file-export command. The 13 local MCP tools do not include a separate file export method for PNG, SVG, PDF, or JSX.
# Fanta projects and .fant snapshots (/docs/formats/fant)
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 [#project-layout]
| Path | Contains |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| fanta.json | Project identity and layout version |
| pages/\/page.json, page.fnx, page.ids.json | Page header, editable tree, and identity sidecar |
| components/\/def.json, master.fnx, master.ids.json | A standalone component's definition, editable master, and sidecar |
| components/\/set.json | One variant set's axes, values, and default variant |
| components/\/\/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 [#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 [#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](/docs/formats/fnx) and [visual export](/docs/formats/export).
# Import from Figma (/docs/formats/figma-import)
Fanta can open a local .fig file and convert it into an editable project. The import path handles Figma document data such as pages, layers, components, instances, auto layout, vectors, effects, variables, and supported Boolean operations where Fanta's document model can represent them.
## Open a .fig file [#open-a-fig-file]
Open the file in the desktop app. On first open, Fanta parses it and attempts to materialize a sibling Fanta project directory. You can edit the imported design from that first session. The original .fig remains an import source; the saved Fanta project becomes the working copy. If writing beside the import fails, Fanta shows the parsed design in memory and retries project creation on save. Choose a writable location if macOS limits access to the sibling folder.
In the direct-download Mac build, a fresh sibling project is prepared in a temporary directory and published only after its files have been written and flushed. The final publication step refuses to replace a destination that another process created. If publication fails, the imported design remains open in memory and the first save can retry creating the project.
If you open the same .fig again after a sibling project was created, Fanta redirects to that project. This preserves newer edits instead of reimporting the original file over them.
## Check the result [#check-the-result]
Large imported documents can contain thousands of nodes. Inspect the page tree and key components in the editor, then compare visual output against the source.
Supported Union, Subtract, Intersect, and Exclude Boolean operations retain their operands as editable layers. Fanta keeps the imported vector appearance while the operands and operation are unchanged, then recomputes geometry when you edit them. Undo can restore the imported appearance. If an operation is unsupported or operands cannot be used, Fanta falls back to a vector; those operands are not separately editable.
On first import, Fanta shows a canvas notice when it detects known structure loss: flattened Boolean operations, omitted unsupported or malformed layers, or layers with unsupported parent relationships. The notice gives counts and Boolean fallback reasons. It does not prove that all rendering and component overrides match Figma, and absence of a notice does not establish full fidelity. Compare important pages visually and inspect the layers you plan to edit.
For agent inspection, batch\_get supports depth limits and pagination. Read smaller portions of a large imported page and request detailed nodes by ID. Capture a screenshot of the page or relevant node to review rendering.
Continue work in the Fanta project directory and keep its project files and assets together. Use [visual export](/docs/formats/export) when you need PNG, JPG, SVG, or PDF output.
# FNX design source (/docs/formats/fnx)
FNX is Fanta's text source for a page or component master. Pages live at pages/\/page.fnx. Standalone component masters live at components/\/master.fnx; a variant master lives one level deeper at components/\/\/master.fnx. Each element is a scene node; literal attributes hold its properties and nested elements hold its children.
## Read a small design [#read-a-small-design]
This compact page example describes a 320 × 180 frame containing an orange rectangle:
```tsx
export default function Card() {
return (
);
}
```
name is the layer label; id is its stable identity. The rectangle's x and y place it relative to its parent. width and height describe its geometry, and fills describes its paint. Changing 80 to 120 makes the rectangle wider when the valid source is saved and reloaded.
Generated files can also include JSX declarations, imports, and additional properties. Keep the generated header and project companions when editing an existing file, and use fresh IDs when creating your own nodes. This example explains the source tree; a working project also needs its manifest and supporting files.
FNX is declarative design data. It supports literal strings, numbers, arrays, and objects, with helpers such as fnxColor for colors. Its JSX-like appearance does not make it executable React application code: arbitrary functions, dynamic rendering, and application event handlers are outside the format. See [FNX design as source](/docs/concepts/fnx-design-as-source) for the canvas-to-source workflow.
## Edit safely [#edit-safely]
FNX is a restricted, static JSX-like grammar, not arbitrary executable React or JavaScript. Preserve an existing element's explicit id when changing that node. Give a copied or newly created node a new ID. Keep its companion page.ids.json or master.ids.json sidecar with the project; it records identity and sibling order.
Modern FNX with explicit valid IDs on every element can recover from a missing or damaged sidecar. Fanta reconstructs the sidecar from the source and repairs it on a successful save. Older source without explicit IDs still requires the sidecar. Do not remove sidecars as part of a normal edit.
The Code workspace offers **FNX** and its companion **JSON** header for the active page or component master. Both are editable while the canvas is clean. For a variant, the companion is its own def.json under the set folder. **Find** searches the selected FNX or JSON editor. **Discard draft** reloads only the selected source buffer, leaving a draft in the other buffer intact.
Fanta locks canvas edits while either source buffer is dirty; saving validates the complete project, writes the source, and reloads the canvas. When both buffers have edits, Save processes the selected buffer first, then the other. A conflict or simultaneous canvas edit blocks the source save until resolved. Successful Save retains the authored text edit as an Undo step and persists layout geometry recomputed from the source change. A failed validation keeps the last saved file and canvas visible. You can also use an external editor or an agent's file tools.
The local MCP read\_fnx\_source tool reads bounded source slices. validate\_fnx\_source checks a complete FNX or managed JSON candidate and returns diagnostics without writing. For an existing project file, validation materializes the full candidate project, including typed values and references. A new managed file is checked against its source schema until its companion exists.
Canvas edits patch affected source while preserving unrelated comments and whitespace where possible. Structural edits such as inserting or reparenting a node now keep authored attributes on surviving nodes, including source-only page dimensions, and carry a child comment with its node. An explicit source edit remains authoritative: if you remove an attribute in FNX, a later canvas rebuild does not recreate it.
FNX printing preserves the exact value of finite JSON numbers, including very small coordinates, sizes, gradient stops, and authored extension data. It no longer rounds magnitudes below 1e-9 to zero. Extremely small floating-point values may print in exponent notation to keep the file readable, so a source diff can show arithmetic residue that earlier versions hid. Integer values retain their integer form.
A delete or node-type change can be refused when it would erase an authored FNX attribute or child comment that canvas Undo could not restore. The editor reports a preservation error; make the intended removal in FNX first, then retry the canvas operation. A failed save leaves the persisted files intact, but a preceding live canvas change may need Undo. Invalid syntax or unresolved references leave the previous valid canvas visible and show a diagnostic. Unknown attributes can produce nonfatal warnings; inspect the rendered result. Fanta can also detect overlapping canvas and external edits and surface a conflict.
## Readable references and version 5 layout [#readable-references-and-version-5-layout]
In layout version 4 and 5 projects, an instance may refer to a component by name, such as component="Button". A bare component ID also works and is required when names are ambiguous; Fanta prints IDs in that case. Variable bindings may use collection and variable paths such as $Theme/bg, including in a bindings map. The variables themselves live in doc/variables.json. Colors print through fnxColor("#RRGGBB"), or eight-digit hex for opacity.
Version 5 changes where variant sources live, rather than removing these readable references. A version 4 project remains readable and moves to version 5 on its next save. Earlier app builds reject a version 5 manifest. Do not rename a component by editing its def.json name alone: instances may use the old name. Use the canvas or rename\_component operation, which updates references with the definition. Project-local AGENTS.md gives a syntax guide, and fnx.d.ts supplies editor declarations.
FNX can express a frame's horizontal, vertical, or grid auto layout. A grid frame stores tracks in its grid property; child layout\_child.grid selects an explicit cell or leaves placement automatic. Paints, effects, constraints, and rich-text runs can also be represented in source.
## When to use it [#when-to-use-it]
Structured agent operations now cover linear and radial gradient fills, layered effects, constraints, vector shapes, grid layout, strokes, components and variant sets, variables, and bindings. FNX remains useful for source review in Git, source-level edits, and properties such as individual rich-text runs that the structured operation vocabulary does not edit. Keep referenced binary media in assets/; FNX refers to an asset by ID rather than embedding raw bytes.
An isolated FNX file is not the full project: it depends on the manifest, sidecars, shared document data, and referenced assets.
# Formats & interoperability (/docs/formats)
Fanta's editable document is a project directory with a fanta.json manifest. In layout version 5, each variant set has one folder containing its set definition and member masters. Pages, standalone components, variables, metadata, and assets also live in separate files. The persistent [Project Assets](/docs/editor/assets) library can store named media before it is placed on a page. A canvas edit updates the affected project files, and valid saved source changes reload in the canvas.
## Choose the right output [#choose-the-right-output]
| Format | Main purpose | Editable in Fanta? |
| ------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------- |
| [Fanta project directory](/docs/formats/fant) | Continue designing and version source and assets in Git | Yes |
| [.fant snapshot](/docs/formats/fant) | Package a design and its assets as one file | Import into an editable project |
| [.fnx source](/docs/formats/fnx) | Review or edit a page or component master as static JSX-like source | Yes, within a project |
| [.fig import](/docs/formats/figma-import) | Bring an existing Figma design into Fanta | Imported into an editable project |
| [PNG, JPG, SVG, PDF](/docs/formats/export) | Share a visual result | Rendered output |
The Code workspace can edit FNX and its selected page or component JSON header when the canvas is clean, validate the complete project, and reload the canvas on save. An external editor or agent can edit other managed project files too; validate typed JSON and references before writing. New projects include a fanta.md design brief, AGENTS.md editing guide, and FNX editor support files.
## Save and version [#save-and-version]
Keep the project manifest, page and component source, ID sidecars, shared document data, asset library metadata, and media bytes together in Git. An external file edit is reconciled into the open editor; invalid source leaves the last valid canvas visible with a diagnostic. If a canvas change and file change overlap, Fanta presents a conflict.
**File → Save As…** creates a new local project copy, including current edits and assets, and points subsequent saves to that copy. The original project stays intact. The .fant handler supports import and export at the format layer, but a snapshot is not the editable working directory. The confirmed editor export controls produce visual files. See [project and snapshot details](/docs/formats/fant).
# Connect an Agent (/docs/getting-started/connect-an-agent)
For the Public Alpha, use the installed app's copied instructions and verify the exact open project before editing. The [agent recording and sample task](/docs/demos#agent-extension) show the first bounded workflow.
The recorded example uses an external Opus 5.5 agent through Fanta MCP, then
inspects the native result, saved FNX and Undo/Redo in the accepted signed app.
Keep Fanta running with the intended design open. The app starts a local MCP server by default over a private Unix socket. The fanta --mcp-stdio command bridges an agent's stdio MCP connection to that running app; it does not open a network port. In settings, fanta\_live\_mcp.enabled can disable the server.
In a non-Store build, choose **Help → Connect Claude Code / Codex…** to copy instructions for the current executable and user data directory. The welcome page also offers **Copy command** for Claude Code and **Copy Codex config**. The copied values matter if you use a development build, multiple profiles, or a custom data directory: the bridge must find the discovery file written by the same running app.
## Claude Code [#claude-code]
Run the copied command from the design project directory. Its shape is:
```bash
claude mcp add --scope project --transport stdio fanta -- '/Applications/Fanta.app/Contents/MacOS/fanta' --mcp-stdio --user-data-dir '/path/to/the/running/Fanta/data-directory'
```
Replace both paths with the values copied from Fanta. The project scope keeps this registration with the project. Restart Claude Code after adding it.
## Codex [#codex]
Put the copied TOML snippet in this project's .codex/config.toml, then restart the agent. Its shape is:
```toml
[mcp_servers.fanta]
command = "/Applications/Fanta.app/Contents/MacOS/fanta"
args = ["--mcp-stdio", "--user-data-dir", "/path/to/the/running/Fanta/data-directory"]
```
Use the exact executable and data directory shown by Fanta. Do not assume the default profile path if you launched the app with --user-data-dir or FANTA\_USER\_DATA\_DIR.
## Verify the connection [#verify-the-connection]
Check the client's MCP status and call get\_editor\_state. A successful connection shows an **Agent connected** notice in Fanta. The current local server offers these 13 tools:
| Work | Tools |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Inspect the canvas | get\_editor\_state, get\_guidelines, batch\_get, get\_screenshot |
| Edit and inspect source | batch\_design, read\_fnx\_source, validate\_fnx\_source |
| Reuse and prepare assets | get\_design\_system, prepare\_design\_asset, import\_image |
| Review with agents | list\_comments, reply\_comment, report\_agent\_activity |
Start with guidelines and editor state, then [follow the design build loop](/docs/mcp/build-loop). batch\_design now paints each operation while it runs and commits the batch as one undo step; a failed or canceled batch rolls back. Use a stable agent\_id and agent\_name in report\_agent\_activity and batch\_design.activity so **Follow** can track the work. Report a project-contained source\_path and workspace when moving to code or variables. An agent can validate a complete FNX or managed JSON candidate before writing it; validation alone does not modify the project. import\_image saves an image to project assets but does not place a layer. prepare\_design\_asset opens a prefilled image or SVG composer for your review and does not submit generation.
Fanta's in-app **MCP & Tools** settings connect the built-in agent to other tool servers. They are a separate direction from this live canvas bridge. The commands above are verified for non-Store builds. Connecting an external client to a packaged Mac App Store build needs separate validation; that build cannot launch command-backed MCP servers from inside Fanta. See [Settings and build differences](/docs/editor/settings).
## One bounded first task [#one-bounded-first-task]
After `get_editor_state` identifies the intended saved sample, request:
> Change only the existing button label to “Explore Fanta”. Keep its geometry,
> styles, IDs and all other layers unchanged. Inspect the result and stop.
> Do not generate media or call paid services.
Check the canvas and corresponding FNX, then use Undo and Redo. For source work,
read the complete relevant file, preserve IDs and validate the complete candidate
with `validate_fnx_source` before using the agent's normal file tools. There is
no local `edit_fnx_source` tool. Read-source results can be truncated, so inspect
the continuation information. The local bridge is separate from the metered
hosted API and does not configure credentials or establish spending limits.
# Your First Project (/docs/getting-started/first-project)
Use the [same ten-minute exercise as the launch demos](/docs/demos#the-ten-minute-exercise). Reviewed silent recordings, screenshots and short GIFs appear on the [demos page](/docs/demos).
1. Choose **File → New Design…** and select a new folder, or **File → Open…** to import a Figma .fig. Fanta attempts to create a project beside the import; if the location is not writable, save the imported design to a folder you can access.
2. Open fanta.md in the project root and record the intended audience, visual direction, palette, typography, layout rules, and acceptance checks. Fanta seeds this brief without replacing an existing one. The adjacent AGENTS.md explains how agents should edit the design source.
3. Draw a rectangle or frame. About a second after editing stops, Fanta saves the change into the project folder. The working source is under pages/, not inside the original .fig.
4. Open the **Code** workspace to inspect and edit the page's .fnx or its companion page.json. Use **Find** in the selected source editor and **Discard draft** if you want to reload that buffer's saved version. Save a valid, complete source change to reload the canvas; the authored edit remains undoable after Save. Fanta checks JSON types and project references, not just syntax. You can also edit project files in another code editor; the open canvas reloads after a valid save.
5. In a non-Store build, choose **File → Review Changes** or inspect the Git diff. Use **File → Commit…** when the screenshot and source diff agree. Fanta initializes Git when a bundled or system Git is available, unless the project is already inside a repository.
**File → Save As…** makes a new local project copy with the current edits and assets, then continues saving to the new folder. The original stays in place. Choose a new destination rather than an occupied or nested project folder. Save or discard unfinished FNX source edits and finish active canvas previews before using Save As.
Let a canvas edit autosave before modifying the same nodes in FNX, and let source reload before continuing on canvas. After moving or adding layers, inspect the FNX diff: Fanta preserves authored attributes and child comments on surviving nodes. If a delete or type change is refused to protect source-only data, edit FNX intentionally or undo the visible canvas change. Keep the manifest, \*.ids.json sidecars, fanta.md, and assets with the project. If you add component variants, the current version 5 layout groups their masters under one set folder; use a current Fanta build before sharing a migrated project. The non-Store app bundle includes Git, so Xcode Command Line Tools are not normally needed for project initialization. Mac App Store feature builds do not initialize Git automatically; use an external Git client for version history.
# Getting Started (/docs/getting-started)
Fanta is a macOS design editor. Its working document is a project folder with a fanta.json manifest and readable .fnx design source. Canvas edits save into that folder; editing valid source in a code editor reloads the canvas. **File → New Design…** creates the manifest, page and component directories, and project-local AGENTS.md, fanta.md, FNX type declarations, and editor configuration. Use fanta.md to record the design brief, audience, visual direction, foundations, component system, and acceptance checks.
You can also open a Figma .fig file and continue in an editable Fanta project. In a non-Store build, Git can track the source changes. [Your first project](/docs/getting-started/first-project) walks through a canvas edit, its FNX source, and review.
Fanta's local MCP bridge lets an external agent inspect and edit the open canvas. The app copies a connection command for the running installation and its data directory; use that command for your project. [Connect an agent](/docs/getting-started/connect-an-agent) explains the setup.
# Install & Build (/docs/getting-started/install)
## Install Fanta 1.0.0 Public Alpha [#install-fanta-100-public-alpha]
The first public distribution targets **Apple Silicon Macs**. Use the
[official download page](https://www.fantaisa.net/download) for current
availability, the immutable installer, checksum and macOS versions actually
tested for that package. The public label is **Public Alpha**, the app version is
**1.0.0**, and the internal release channel is **stable**.
The final **Build45** package is Developer ID signed, Apple-notarized and stapled.
Distribution and tested installation checks have passed. The **Public Alpha is
available** through the official download page. The [launch overview and three
workflows](/docs/demos) have been reviewed on this signed app.
The accepted package is bound to source
`57d86330289153ead8a3bdbd114e1fa530a74e03`. Its `Fanta-aarch64.dmg` SHA-256 is:
```text
5e6b68605bbb601e70778acb2b8fcf72186d1b9a368b7947554f316ab96b87b8
```
On **12 October 2026**, an authenticated Chrome draft download retained
quarantine and passed Gatekeeper as Notarized Developer ID. Native edit, Save,
normal Quit and reopen passed. Finder replacement with the same signed build
preserved the saved change after reopening, and the installed bundle matched the
accepted signed bundle. After publication, an anonymous public Chrome download
matched the accepted DMG checksum. These checks do not establish clean-account
installation or migration from an older version.
1. When the download page reports availability, download `Fanta-aarch64.dmg`
and `SHA256SUMS.txt` from its linked GitHub prerelease.
2. Verify the checksum in the folder containing both files:
```bash
shasum -a 256 -c SHA256SUMS.txt
```
Continue only when the installer reports `OK`.
3. Open the disk image, drag **Fanta** into **Applications**, and eject the image.
4. Open Fanta from Applications. macOS may ask you to confirm opening an app
downloaded from the internet.
5. Follow the [ten-minute exercise](/docs/demos#the-ten-minute-exercise).
The accepted package has passed signature, notarization, stapling and Gatekeeper
checks. If Gatekeeper refuses the public installer, stop and report the dialog to
[support@fantaisa.net](mailto:support@fantaisa.net). Do not remove quarantine or
bypass Gatekeeper. Earlier ad-hoc-signed internal QA packages retain their
original identities and are separate artifacts.
## Requirements [#requirements]
The signed Build45 package was tested on an **Apple Silicon Mac running macOS
27.0 (26A428)**. A minimum supported macOS version has not been established. Check
the download page for the tested versions of each package. Intel and universal
installers are outside this release.
## Manual updates [#manual-updates]
Automatic updates are disabled in this alpha. Save work, close Fanta and back up
the complete project folder before replacing the app. Download the newer public
installer, verify its checksum and drag its Fanta app into Applications. Choose
**Replace**, keeping your project and application data folders. Reopen the sample,
make an edit, save and reopen it before continuing important work.
## Limits and support [#limits-and-support]
Start with a copy of a small project. Imported Figma structures and rendering can
differ. Code edits supported FNX and managed JSON, while **Saved Code** in Dev
mode is read-only. Source drafts can lock conflicting canvas edits, and saving
several source buffers is sequential rather than an atomic rollback operation.
Review project trust prompts and keep manifests, identity sidecars and assets
with the source. [Current capabilities and limitations](/docs/capabilities).
In a **12 October 2026 signed Build45** recording, Code showed
`Could not refresh saved source: oneshot canceled` after a canvas Save. The saved
FNX retained the edit and reopening that project restored the source view.
Verify the saved change and resolve any unsaved drafts before closing, then
reopen before editing source. Report a persistent warning or a saved-source/canvas
mismatch. See [source refresh troubleshooting](/docs/mcp/troubleshooting#code-reports-a-source-refresh-warning).
Use the verified community and issue-reporting links on the download page for
reproducible bugs. Include app version, macOS, steps and expected versus observed
behavior. Send account and billing reports privately to
[support@fantaisa.net](mailto:support@fantaisa.net).
A separate Mac App Store feature build exists in source. It is a different
packaging route and does not establish public Store availability. The installer
and external-agent guidance on this page describe the direct-download build.
## Build from source [#build-from-source]
Clone the [fanta-edit repository](https://github.com/jeanc18rlos/fanta-edit), install its Rust and macOS build dependencies, and run from the repository root:
```bash
cargo run
```
The Cargo package and its binary are both named fanta. Use cargo build --release -p fanta for a release binary. The repository uses ./script/clippy for linting. The release verifier's `--stage lint` checks twelve editor and engine crates with all features, then separately checks `fanta-format`, `fig_viewer`, and `fs` with default features.
Maintainers can enable **build diagnostics** on a manual macOS release workflow run. This opt-in setting records bounded CPU, memory, disk, and swap progress during the Cargo build and retains Cargo timing reports when produced. It is disabled by default and requires GitHub Actions CI. Diagnostic output helps investigate a build; it does not establish signing, notarization, installation, or release readiness.
## Mac App Store build differences [#mac-app-store-build-differences]
A build compiled with mac\_app\_store is sandboxed. It does not ship the CLI helper or bundled Git runtime and does not automatically initialize Git repositories. It cannot launch command-backed MCP servers, external agent processes, terminal tasks, or external formatters from inside the app, and remote project connections are disabled. Remote HTTP MCP servers remain available.
All new AI credit and subscription purchases use [web Billing](https://app.fantaisa.net/billing). The current public non-Store DMG supports web checkout. Native Store web-billing controls are a source change for the next app release; the backend already prevents the retired Apple purchase, restore, offer-code, and trial paths from granting AI credits. Public accounts receive no signup, referral, or trial credits. Existing founder exceptions are restricted on the backend. Previously purchased Apple subscriptions must still be canceled in the Apple Account.
The in-app live canvas MCP server is a separate setting, but an external client's bridge to a packaged Store build still needs validation. File access follows macOS user-selected Open and Save permissions. See [Settings and build differences](/docs/editor/settings).
Next choose **File → New Design…** or **File → Open…** to import a .fig file. See [Your First Project](/docs/getting-started/first-project).
# Quickstart: Claude Code (/docs/getting-started/quickstart-claude-code)
Open a design in Fanta and [connect Claude Code](/docs/getting-started/connect-an-agent). Try this prompt:
> Read Fanta's design guidelines and active page. Find space for a 360 × 220 card, add a named frame and text, arrange them vertically, then show me a screenshot. Review the resulting source diff.
Claude Code should call get\_guidelines and get\_editor\_state with empty\_space: \[360, 220], then inspect nearby nodes with batch\_get. It can create the frame with batch\_design; the result returns a node ID for a later batch that adds children. A batch paints its operations on the canvas as they run, then commits as one undo step; an error rolls back the preview. Use a small batch for one visible section. Call report\_agent\_activity with a stable agent ID and name, then pass that identity in batch\_design.activity if you want Fanta’s Follow control to track the streamed steps. There are no temporary name bindings between operations.
For source editing, ask the agent to read the page path returned by get\_editor\_state, prepare the complete FNX document, call validate\_fnx\_source with that candidate, then write the file only after validation succeeds. The open canvas reloads valid saved source. The project-local AGENTS.md explains syntax and stable IDs; fanta.md records the design brief. For managed JSON edits, validate the complete candidate too; valid JSON syntax alone does not prove its types and references are valid.
get\_screenshot can target the new frame ID. The canvas edit autosaves to FNX; **File → Review Changes** shows the Git diff in a non-Store build when the project is in Git. Ask for a focused correction and another screenshot if the result needs work.
# Build a card with auto-layout (/docs/guides/auto-layout-card)
1. Call `get_guidelines`, then `get_editor_state` with `empty_space: [360,220]`. Use its coordinates for the new top-level frame.
2. Use `batch_design` to `create_node` with `node_type: "frame"`, a name, size 360 × 220, and a solid fill. Give the batch a label such as `"Create sign-in card"`.
3. Read the returned frame ID. In a later batch, create heading and supporting text nodes with that ID as `parent`. Give text boxes enough width and height.
4. Use `set_auto_layout` with `direction: "vertical"`, `gap`, `padding`, and intentional axis sizing; style text with `set_text_style`, using `auto_height` when a paragraph should wrap. Use `set_layout_child` for a child's growth or alignment. Auto-layout controls child positions, so do not also set child `x`/`y`.
5. Screenshot the frame, correct spacing if needed, then review the autosaved `.fnx` diff.
```json
{"label":"Lay out card","ops":[{"op":"set_auto_layout","id":"","direction":"vertical","gap":12,"padding":[20],"primary_sizing":"hug","counter_sizing":"fixed"}]}
```
For a gallery of cards, create a containing frame and call `set_grid_layout` with columns such as `["1fr","1fr","1fr"]` and a gap. Its children fill cells row by row; pin a featured card with `set_layout_child` column, row, and span fields. See [grid layout](/docs/tools/layout).
# Build a component & variants (/docs/guides/component-variants)
1. Build a frame or group for the reusable element and inspect its exact ID with `batch_get`.
2. Promote it with `{"op":"create_component","id":""}` in `batch_design`. The master stays on canvas, and the response includes its component ID.
3. For states such as Default and Hover, name each standalone master with axis values such as `Variant=Primary, State=Default` and `Variant=Primary, State=Hover`, promote them, and pass their master node IDs to `combine_variants`. The result returns `component_set` and `frame`; the frame displays the variants as a grid. Plain master names instead form one `Variant` axis. Use `get_design_system` to read the exact set and axis values.
4. To expand a set later, promote another `Axis=Value` master and call `add_variants` with the set ID and its master node ID. `remove_variant` takes a member out as a standalone component, `arrange_variants` tidies the set frame, and `rename_component` changes a component or set name safely.
5. Expose a `variant` axis or a text, boolean, number, color, or instance-swap property with `create_component_property`. For a descendant field, bind it with `bind_component_property` using the descendant node ID and a compatible target such as `{"prop":"text_content"}`.
6. Place a linked copy with `create_instance`, passing the component or set ID and world `x`/`y` coordinates. Use `set_instance_property` with an exposed property ID or unique name and a value of the right type.
7. Change the master, screenshot an instance, and inspect its source under `components///master.fnx`.
```json
{"label":"Place button","ops":[{"op":"create_instance","component":"","x":480,"y":120}]}
```
Master, variant-set, and exposed instance-property operations are in the external MCP schema. Read `get_design_system` after structural changes; invalid values fail and roll back the batch. Use `rename_component` rather than editing component metadata or folder names by hand.
In the editor, **Go to main component** on a variant-set instance opens the member the instance currently displays, including a member selected through a variable mode. **Reset all overrides** restores the resolved default member and its size. Save or discard a Code workspace draft before navigating to another component. A directly bound text-content variable controls its instance text; edit the variable or remove that binding before editing the text in place. Text reached through an exposed component-property alias remains editable.
The editor's Copy/Paste can carry a complete component or variant set with its captured definitions. If the original has been removed, Paste restores an independent usable copy. Cutting only part of a variant set is refused; select the whole set when it needs to move together. Review the saved FNX diff after structural changes.
# Design-to-code with .fnx (/docs/guides/design-to-code-fnx)
A Fanta page is `.fnx` source under `pages/`; a standalone component master is under `components//master.fnx`, and a variant master is under `components///master.fnx`. Canvas operations autosave into those files, and valid file edits in your own code editor reload the open canvas.
In Fanta's **Code** workspace, choose the active page or component's **FNX** or companion **JSON** tab. Save canvas changes before editing source. A dirty source buffer temporarily locks canvas editing; **Save** validates and applies source, refreshes the editor and canvas, and preserves source Undo history. If both source buffers have drafts, Save processes each before releasing the canvas. **Find** searches the active buffer; **Discard draft** reloads only the selected buffer from disk. Resolve an on-disk conflict before saving, and finish a source operation before starting another.
Canvas saves preserve authored FNX comments and source attributes on surviving nodes, including attributes this editor version does not understand. If deleting a node or changing its type would lose a source-only attribute that canvas Undo cannot restore, persistence reports a preservation error. Undo the canvas edit, or intentionally remove the attribute in FNX and validate the complete source before trying the canvas operation again. A change visible on canvas is not yet a saved project change.
1. Use `get_editor_state` to find the source path. `read_fnx_source` lists files and pages text; its `offset` is a 1-based line number. Follow `truncated` and `next_offset` when reading large files.
2. Edit a complete `.fnx` candidate with ordinary file tools, keeping its syntax well formed. Call `validate_fnx_source` with the project-relative path and complete candidate before writing. Managed JSON files, including `fanta.json` and `*.ids.json` identity sidecars, can also be edited after inspecting their schema. Preserve existing identities and validate the complete project candidate before saving. For renaming or restructuring components and variant sets, use the editor or `batch_design` operations; manually changing a `def.json`, `set.json`, or component folder can break name-based page references.
3. Save, let Fanta reload and finish any computed layout write, then call `get_editor_state` and `get_screenshot` to confirm the result. If the canvas reports a source conflict, resolve it before continuing canvas edits.
4. Review and commit the Git diff.
`.fnx` is design source, not a promise of production React export. The current external MCP server has no `export_jsx` tool; implement application code in your own project.
# Guides (/docs/guides)
These workflows use the current Fanta desktop app. Each ends with a screenshot and source diff, since both are needed to review a design change.
# Run a multi-agent build (/docs/guides/multi-agent-build)
The external MCP server acts on the most recently focused design. `batch_design` is atomic and undoable, but it does not lock nodes across agents. Assign one coordinator to review combined work.
1. Map pages and components with `get_editor_state` and `batch_get`.
2. Give each agent a distinct page, frame, component, or source file. Share exact IDs or paths. Each agent should use `report_agent_activity` with a stable ID and name, its current action, page/node or source path, and `workspace` (`canvas`, `variables`, or `code`). Use the same ID and name in `batch_design.activity` so Follow can track its streamed placements.
3. Have each agent finish canvas edits and let autosave complete before another edits the same source file. Do not mix canvas and source edits on the same nodes simultaneously. A dirty Code workspace draft locks canvas edits; save or discard it before handing the design to a canvas agent.
4. Build one component or section per batch so each operation appears on the canvas while the call runs. Verify each region with `get_screenshot` and inspect the Git diff for unexpected changes. A failed or interrupted batch rolls back its preview.
5. Clear activity with `active: false` when an agent finishes, then commit reviewed changes with ordinary Git.
Fanta's thirteen-tool external MCP surface reports agent activity and can follow an agent across canvas pages, component views, variables, and code files. It has no `spawn_agent`, `vcs_begin_task`, or cross-agent edit lock. Unrefreshed activity expires after about 30 seconds; parallel task assignment belongs to the client or team workflow.
# Version-control your designs (/docs/guides/version-control-designs)
Git records named checkpoints of files, called commits. Because Fanta stores designs as FNX and JSON, those checkpoints can describe a changed headline, a wider button, or a different layout value. You can compare versions, try an idea on a branch, and share a proposed change for review.
Fanta writes canvas edits to the design project after a short autosave delay. **Autosave updates your files; a commit records a checkpoint in Git.** In non-Store builds, Fanta initializes the folder as a Git repository when a bundled or system Git is available, unless the folder is already inside another repository. A `.fig` import attempts to create a source-backed project beside the original file; commit the project, not the import alone.
*The launch-card demo changes “FANTA / STUDIO” to “FANTA / PUBLIC ALPHA” and a button frame's width from 184 to 220. Both edits appear in the FNX diff.*
## Review and commit an edit [#review-and-commit-an-edit]
1. Make a canvas or `.fnx` edit. Let canvas autosave finish, or save and validate the source draft.
2. Inspect the changed frame or page on the canvas. Capture a screenshot when you need a visual record for review.
3. In a non-Store build, choose **File → Review Changes** or run `git diff` in the project. Confirm the source diff matches the intended visual result.
4. Stage the intended files and commit through **File → Commit…** or your Git client. Use a message that explains the design change, such as “Widen the launch-card button.” Include any new assets the design uses.
Keep the project manifest, page and component FNX, identity sidecars, shared JSON, and referenced assets together. A lone page.fnx may depend on components, variables, or images elsewhere in the project. Check for new, untracked files as well as modified files. A text diff cannot show all changes inside binary media, so review those assets visually too.
## Try an idea on a branch [#try-an-idea-on-a-branch]
A branch gives an experiment its own sequence of commits. Create a branch in Fanta's Git surfaces or your usual Git client before changing the design. For example, from a clean project repository:
```sh
git switch -c design/launch-card
```
Make the edit, compare the canvas and source, and commit it on that branch. If your repository has a remote, push the branch with your Git client and open a review in your repository host. Include screenshots and explain the intended result alongside the file diff. Git history stays local until you push or otherwise share the repository; a local commit does not publish the design.
Save or discard pending canvas and source drafts before switching branches. Fanta watches the project files and reconciles external changes, including a branch switch. If the branch changes the project's manifest ID, open it as a different project. Resolve any reported file conflicts before continuing to edit.
## Merge with visual review [#merge-with-visual-review]
Git can merge text edits in different places, but a clean text merge does not establish that the combined design is correct. Two changes can interact through layout, variable bindings, components, or asset references even when Git reports no conflict.
When a merge has conflicts, resolve the FNX and its related project data together. Keep a node's existing ID with that node, and preserve IDs used by references. Never leave Git conflict markers in source you expect Fanta to parse. Validate the resolved project, reopen or reload it, and inspect the affected pages and components before accepting the merge.
This workflow supports asynchronous design review using your team's repository tools. It does not establish live multiplayer editing or automatically resolve competing visual changes.
## Source preservation and build differences [#source-preservation-and-build-differences]
Structural canvas edits retain authored FNX attributes and child comments on surviving nodes. Check the diff after moving or adding layers, especially in source you have customized by hand. A delete or type change that would remove source-only information may be refused; remove that information deliberately in FNX first if that is your intent. A refused save protects the files on disk, while the visible canvas edit may need Undo before you continue.
The external MCP server edits the design but does not commit it. The old `vcs_*` tool names are absent. If no `.git` was created in a non-Store build, check the bundled or system Git and initialize the repository with a Git client. Mac App Store feature builds intentionally skip automatic `git init`.
A Mac App Store feature build also omits bundled Git and blocks local command execution inside Fanta. Use a separate Git client for version history in that build. These restrictions describe the build configuration, not a claim that a public Store release is available. See [Install and build](/docs/getting-started/install) for distribution details.
# Get the best output (/docs/mcp/best-output)
* Read `get_guidelines` and `get_editor_state` before editing. Work on the focused design and ask for empty space when adding a top-level composition. Read `get_design_system` before making tokens or components and `list_comments` before revising reviewed work.
* Read a shallow tree first, then exact IDs. Page wide documents with `offset` and `limit`; page listings that traverse more than 1,000 nodes and responses over 256 KiB are refused. Use `batch_get` with `detail: "style"` to inspect the editable values before replacing a fill, effect, layout, or constraint.
* Batch operations for one visible component or screen section with a useful label. Content edits preview in order and commit as one undo step; a failed operation rolls content edits back. Selection and viewport changes are not transactional. Use returned created IDs in later batches.
* Use frames for clipping and auto-layout, groups for organization. Set container sizing and child participation explicitly where needed. Horizontal, vertical, and grid layouts are supported; use `set_grid_layout` for columns and rows rather than hand-built nested rows when a true grid fits the content.
* Screenshot the changed node or page, inspect it visually, and review the autosaved `.fnx` diff.
* Edit `.fnx` or managed project JSON directly for supported source changes outside the MCP operation vocabulary. Read all relevant source first, preserve node and component identities, validate the complete candidate with `validate_fnx_source`, and let it reload before touching the same nodes on canvas.
* Import generated image files or URLs with `import_image`, then place the saved asset using an appropriate editor or source workflow. `prepare_design_asset` only opens a generation draft for user review.
* Use `report_agent_activity` for visible milestones, including the actual page, node, coordinates, source path, and workspace. Reuse the same agent ID and name in `batch_design.activity`; clear the activity with `active: false` when finished. Reply to comments in their threads and resolve only verified requests.
See the [tool reference](/docs/tools) and [alpha known issues](https://github.com/jeanc18rlos/fanta-edit/blob/main/docs/alpha/KNOWN_ISSUES.md).
# The build loop (/docs/mcp/build-loop)
1. **Orient:** call `get_guidelines`, then `get_editor_state`. Check the project, focused page, selection, and editability. For a new top-level frame, pass `empty_space: [width, height]`.
2. **Inspect:** call `batch_get` for the page tree. Its default `summary` listing includes up to 200 direct children at depth 2. Follow `more_children` with `offset` and `limit`, then fetch exact IDs; those reads default to editable `style` detail. Call `get_design_system` before inventing tokens, variants, or components. Read unresolved `list_comments` threads when revising existing work.
3. **Edit:** call `batch_design` with `ops` and a descriptive `label` for one component or section. Content edits preview in order while the call runs, then commit as one undoable transaction. A selection- or viewport-only batch creates no undo step. Failure rolls back content edits, while selection and viewport changes are not transactional; use returned created IDs in follow-up calls. Pass optional `activity` with the same `agent_id` and `agent_name` used in `report_agent_activity` so Follow stays with this agent during each placement. Use `import_image` when an external generator returns an image file or URL. It saves an asset without adding a layer.
4. **Verify:** call `get_screenshot`, preferably for the changed node. Inspect the PNG, adjust with another batch, and capture again. For motion, pass an existing `motion_clip` ID and `playhead_ms` to inspect sampled frames.
5. **Review:** allow autosave, check for a save error, inspect the `.fnx` Git diff, and address relevant comment threads with `reply_comment`. A canvas batch can succeed while a later structural save refuses to lose authored FNX data. Resolve only after verifying the requested change, then commit the intended result.
For changes beyond the operation vocabulary, locate the complete `.fnx` or managed JSON source with `read_fnx_source`, pass the complete candidate to `validate_fnx_source`, edit it with ordinary file tools, and let Fanta reload before more canvas work on the same nodes. Report the actual `source_path` and `workspace` (`canvas`, `variables`, or `code`) while changing files so Follow can open the relevant view. Activity does not lock the document.
# Connect an agent (/docs/mcp/connect)
1. Run a non-Store Fanta build and focus an open design. A source build uses `cargo run`; the non-Store app binary is `/Applications/Fanta.app/Contents/MacOS/fanta` when installed there.
2. Choose **Help → Connect Claude Code / Codex…** in Fanta. It copies commands for the *running app executable* and its user data directory. Run the Claude command from the project directory, or put the Codex snippet in that project's `.codex/config.toml`. For example, an app installed at `/Applications/Fanta.app` produces this command shape:
```bash
claude mcp add --scope project --transport stdio fanta -- '/Applications/Fanta.app/Contents/MacOS/fanta' '--mcp-stdio' '--user-data-dir' ''
```
Codex (`.codex/config.toml` in the project):
```toml
[mcp_servers.fanta]
command = "/Applications/Fanta.app/Contents/MacOS/fanta"
args = ["--mcp-stdio", "--user-data-dir", ""]
```
3. Restart the client, check `/mcp`, and call `get_editor_state`. The live server exposes thirteen tools. Keep Fanta running with the intended design open.
`fanta_live_mcp.enabled` defaults to true in Fanta user settings. Setting it false turns the local server off. The bridge checks that the discovered app process is alive, so a stale socket-discovery file after an unclean quit does not count as a connection. Copy the command again when the Fanta executable or user data directory changes. See [Troubleshooting](/docs/mcp/troubleshooting).
These steps are verified for non-Store builds. The Mac App Store feature build prevents Fanta from launching local command-backed MCP servers as a client, while remote HTTP servers remain supported. That restriction is separate from the inbound live canvas server; the packaged Store bridge has not been verified. See [Settings and build differences](/docs/editor/settings).
# Custom rules & project context (/docs/mcp/custom-rules)
A new Fanta project includes an `AGENTS.md` seed. Put project-specific working conventions there. The in-app designer also reads a project-root `fanta.md` before each model round for product and visual direction, layout preferences, asset choices, design-system conventions, and acceptance criteria. Nested project specifications can refine workspace rules; the combined design-specification context has a 64 KiB limit. Direct user instructions, `AGENTS.md`, and the current agent mode and tool permissions take precedence.
```md
# Product design rules
- Reuse existing color and spacing variables before adding tokens.
- Use the existing button component for primary actions.
- Check narrow-width wrapping and screenshot each changed screen.
```
`get_guidelines` describes the current coordinate system, batch workflow, source editing rules, and project design specification when one is present. Read it at the start of an external-agent session. Project instructions add local choices; they do not change the live tool schema. Review an agent’s proposed `.fnx` diff before committing.
# MCP Server (/docs/mcp)
Fanta’s MCP server is part of the running desktop app. It uses a private Unix socket, and `fanta --mcp-stdio` bridges stdio clients to it. It acts on the most recently focused design.
The connection instructions below are for a non-Store build. Fanta's Settings can also configure local or remote MCP tools for its own in-app agent. The Mac App Store feature build blocks Fanta from launching local MCP commands, while remote HTTP tools remain available. That is a different direction from an external client connecting to Fanta's live canvas server. [Build differences →](/docs/editor/settings)
| Tool | Purpose |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `get_editor_state` | Read the active project, pages, selection, viewport, and free placement space. |
| `get_design_system` | Inspect components, variants, variable collections, modes, values, and selected-node bindings. |
| `prepare_design_asset` | Open a draft image or SVG generation request for the user to review and submit. |
| `batch_get` | Read exact nodes or a paged page tree. |
| `batch_design` | Preview content edits, then commit or roll back one undoable transaction; selection- or viewport-only batches create no undo step. |
| `get_screenshot` | Render a page, node, or motion-clip sample as PNG. |
| `read_fnx_source` | List or read source files in the open project. |
| `validate_fnx_source` | Check a complete FNX or managed project JSON candidate without writing it. |
| `get_guidelines` | Read design, source-editing, and project-specification guidance. |
| `import_image` | Save an image from a file, URL, or base64 source into project Assets. |
| `list_comments` | Read canvas comment threads on a page. |
| `reply_comment` | Reply to a thread and optionally resolve it after verification. |
| `report_agent_activity` | Show an agent's canvas, variables, or code activity for Follow. |
The built-in Agent Panel uses the same `design_surface::DesignOp` vocabulary through its own tools. External MCP clients see these thirteen tools, rather than a tool for every design operation. Read the [tool reference](/docs/tools) for the operation list.
In a `batch_design` call, content edits appear on the canvas progressively while the call runs. Content edits form one undo step; a selection- or viewport-only batch creates none. If an operation fails, the content preview rolls back; earlier selection or viewport changes can remain. Keep batches to one visible component or screen section so the user can follow each milestone.
The current `batch_design` schema includes 43 operations, covering grid layout, shape creation, gradients and image fills, effect stacks, constraints, componentizing similar layers, and variant-set maintenance. Call `get_editor_state` to inspect capability flags for the running build, then read nodes with `batch_get` before making a change.
# Troubleshooting (/docs/mcp/troubleshooting)
## The client cannot connect [#the-client-cannot-connect]
Open Fanta and focus a design before starting the stdio bridge. Use **Help → Connect Claude Code / Codex…** to copy the command for this running executable, including its `--user-data-dir` value. Check `fanta_live_mcp.enabled`, restart the client, and call `get_editor_state`. The bridge exits when the app is closed or MCP is disabled.
The documented bridge is for non-Store builds. If you are configuring an MCP server **inside** Fanta, check **Settings → MCP & Tools** for its status, scope, and connection type. A Mac App Store feature build cannot launch a local command-backed server; use a remote HTTP server there. External-client bridging to a packaged Store build has not been verified.
## An in-app HTTP MCP server cannot authenticate [#an-in-app-http-mcp-server-cannot-authenticate]
The configured Fanta-hosted `fanta` (`/mcp`) and `fanta-design` (`/v2/mcp`) connections use your signed-in Fanta account when their endpoints match the configured account backend and no explicit `Authorization` or `x-api-key` header overrides it. If one returns 401, sign out and sign in to Fanta again. An ordinary startup timeout does not clear a separate cached OAuth session for that endpoint; check the server status and network before changing credentials.
Other HTTP MCP servers can use their own OAuth flow. If such a server fails to start without an authentication challenge while a cached OAuth session exists, Fanta can clear that server's stale session and rediscover authorization. A server configured with an explicit authentication header uses that header instead; check its value after a 401. These rules concern servers used **by** Fanta's in-app agent, not the local `fanta --mcp-stdio` bridge used by external agents. The managed-server failure paths have isolated tests; production service recovery remains unverified.
## The wrong design is active [#the-wrong-design-is-active]
`get_editor_state` reports the active page and selection. Focus the intended design and read state again. The server acts on the most recently focused canvas.
## A tree query is refused [#a-tree-query-is-refused]
`batch_get` has two separate limits. A page listing that would traverse more than 1,000 nodes is refused before its response is built; lower `depth`, reduce `limit` and advance `offset`, or fetch relevant exact IDs. A response over 256 KiB is also refused; request fewer nodes or use `detail: "summary"` instead of `"style"`. A wide imported `.fig` page can have thousands of siblings.
## Source looks incomplete [#source-looks-incomplete]
`read_fnx_source` returns at most 64 KiB by default. Its `offset` is a **1-based line number**. Follow `truncated` and `next_offset`; use a larger `max_bytes` for an unusually long line (ceiling 1 MiB). Never replace a file based on a partial slice.
## Source did not reload [#source-did-not-reload]
Validate a complete candidate with `validate_fnx_source`, save the `.fnx` or managed JSON file in the open project, and allow the reload. An identity sidecar such as `page.ids.json` can be edited, but preserve existing node IDs and validate the complete project before saving; a parseable JSON file alone may still be invalid. Fanta logs live at `~/Library/Logs/Fanta/`.
Finish an active canvas preview or unsaved Code draft before trying to reload the same source. Fanta keeps the last valid canvas if an external source edit cannot be parsed and reports a conflict; repair the file and let the watcher reload it. If you are using the Code workspace, **Discard draft** reloads only the selected FNX or JSON buffer from disk. Saving source can also fail when canvas changes are unsaved, the file changed on disk, or another source save or discard is in progress; resolve that state and retry.
## Code reports a source refresh warning [#code-reports-a-source-refresh-warning]
A **12 October 2026 recording on signed Build45** showed
`Could not refresh saved source: oneshot canceled` in the Code workspace after a
canvas Save. In that case, the saved FNX retained the edited CTA and helper text;
closing and reopening the project restored a clean source view. The cause and
frequency are not established, and this recovery does not prove every refresh
warning is harmless.
Verify that the saved source contains the expected change and resolve any
unsaved canvas or Code drafts before closing. Reopen the same project before
making further source edits. If the warning persists, a save fails, or the saved
source and canvas disagree, stop editing and report the app version, macOS,
steps and exact warning through the support links on the
[download page](https://www.fantaisa.net/download). Remove secrets and private
project content from any logs or screenshots you share.
## A canvas change appears, but the source did not save [#a-canvas-change-appears-but-the-source-did-not-save]
Check the editor's save error and the project diff. A delete or node-type change can be refused at persistence time when an authored FNX attribute would be lost and canvas Undo could not restore it. Undo that canvas change, or edit the FNX source to remove the attribute intentionally, validate it, and retry. Structural saves also refuse a rewrite that cannot retain authored FNX comments. Do not treat a successful `batch_design` response as proof that autosave reached disk.
# Pricing & credits (/docs/platform/pricing)
Local design editing is free and does not consume hosted AI credits. Public
accounts receive **no trial, signup, or referral credits**. Hosted AI requires
paid credits; complimentary access is restricted to designated founder
accounts.
Buy subscriptions and one-time credit packs through
[web Billing](https://app.fantaisa.net/billing). Prices below are in USD before
applicable taxes. Billing shows available offers and final checkout terms.
## Subscriptions [#subscriptions]
| Plan | Monthly billing | Annual billing | Monthly credits | Seats |
| ---- | --------------- | -------------- | --------------- | ----- |
| Free | $0 | — | 0 | 1 |
| Pro | $24/month | $240/year | 3,000 | 1 |
| Plus | $49/month | $490/year | 7,000 | 1 |
| Max | $99/month | $990/year | 15,000 | 1 |
| Team | $40/month | $400/year | 6,000 shared | 5 |
Annual plans are paid once a year and release their credit allowance monthly,
not as a full-year grant at checkout. Pro, Plus, and Max are individual plans
with one seat and release 3,000, 7,000, and 15,000 credits per month respectively.
Team releases a shared 6,000 credits per month across its five seats. Allowances
require a verified paid term. Unused paid credits roll over. Larger individual
allowances do not promise unlimited generation or different model availability;
the app shows enabled models and each request's credit estimate.
## One-time credit packs [#one-time-credit-packs]
| Price | Credits |
| ----- | ------- |
| $5 | 500 |
| $12 | 1,500 |
| $35 | 5,000 |
Packs work with Free, Pro, Plus, Max, and Team. They add to the same
organization balance without starting a subscription. The organization owner or admin manages
purchases in web Billing. Credits arrive after verified payment; returning
from checkout alone does not credit the account.
## Companies and studios [#companies-and-studios]
Sign in with your Fanta account and
[create a company workspace](https://app.fantaisa.net/teams/new). Creating a
workspace does not start a subscription or grant free AI credits. Choose Team in that workspace's Billing page for five seats and
one shared paid balance; individual plans remain one-seat plans.
The workspace owner or admin can manage
[members and email invitations](https://app.fantaisa.net/organization) and
review [member usage](https://app.fantaisa.net/usage). Invitations require the
recipient to sign in with the verified email address that was invited. Select the intended workspace before buying:
Billing rechecks the workspace and asks you to reload if it has changed.
Share [project Git links](https://app.fantaisa.net/projects) through the
workspace while keeping repositories with your existing Git host. Each teammate still needs access at that host. These
links do not upload or host project files in Fanta.
To use a company balance in the desktop app, select the company workspace on
the web, then sign in again in Fanta on the desktop.
Pro, Plus, Max, and Team accounts are excluded from donated agent-trace
feedback storage and Fanta's training capture. This does not disable ordinary support or account
management. Connected AI providers apply their own data policies.
## Before running AI [#before-running-ai]
The app shows the account's enabled models, estimated cost, and remaining
balance. One credit represents $0.01 in the AI pricing meter; subscriptions
and packs determine what you pay for the credit allowance. The current
in-app quote is authoritative for a new request.
**Requests blocked before provider dispatch and generation failures confirmed
during reconciliation bill 0 credits.** Interrupted requests can consume
credits, and uncertain provider results can keep credits reserved until
reconciliation. Prior successful metered agent calls retain their spend.
## Cancellation and partial refunds [#cancellation-and-partial-refunds]
Under our voluntary refund policy, **spent hosted AI credits are not
refundable**. Requests for partial refunds are limited to **unused paid
credits** and require manual review using the original purchase price and terms,
plus payment and usage evidence. Your current credit balance alone does not
determine refund eligibility or amount. Contact
[support@fantaisa.net](mailto:support@fantaisa.net) for review.
Canceling a subscription through web Billing stops its next renewal. Annual
cancellation does not automatically refund or prorate the annual payment.
Requests concerning unused credits or future annual allowances require manual
review; there are no automatic refunds or prorations. Deleting the Fanta account
does not cancel an external subscription.
Refunds required by law or the payment provider still apply. See
[Fanta's billing terms](https://www.fantaisa.net/terms#billing) and
[Polar's buyer terms](https://polar.sh/legal/checkout-buyer-terms).
The plan and pack catalog was checked **13 October 2026**. Model availability
and credit costs can change, so use the live catalog in the app rather than a
downloaded pricing snapshot. Local tools and supported provider keys are
separate from Fanta-hosted AI; connected providers apply their own charges.
# Claude Code plugin (/docs/plugin)
The plugin in the [Fanta-JS repository](https://github.com/jeanc18rlos/Fanta-JS) provides a ready-to-use MCP connection, a `/design` command, and three skills for building and checking designs. It talks to the **running Fanta desktop app** through `/Applications/Fanta.app/Contents/MacOS/fanta --mcp-stdio`. See the [plugin README](https://github.com/jeanc18rlos/Fanta-JS/blob/main/plugin/README.md) for what it configures.
The plugin is optional. Claude Code and Codex can also connect directly using the [agent connection guide](/docs/getting-started/connect-an-agent).
## Install [#install]
1. Install Fanta in `/Applications`, launch it, and open a design.
2. In Claude Code, run:
```bash
claude plugin marketplace add jeanc18rlos/Fanta-JS
claude plugin install fanta@fanta
```
3. Confirm the `fanta` MCP server is connected, then try:
```text
/design Add a 320×180 card with a heading and primary button to the current page.
```
If Fanta is installed elsewhere, update the executable path or [connect directly](/docs/mcp/connect).
The local server exposes [13 tools](/docs/tools), including design-system inspection, FNX and managed JSON validation, asset import, comment review, agent activity, and canvas edit and screenshot tools. `batch_design` now carries 43 operations, including grid layout, fill and effect stacks, vector shapes, componentizing copies, and variant-set maintenance. A call previews its operations one by one while remaining one undoable transaction. The plugin teaches Claude to inspect the live design, build one visible section at a time, verify it, and rely on autosave.
The bundled MCP configuration uses the default `/Applications/Fanta.app` path. For a different app location or user-data directory, use the exact connection command copied from the running Fanta instance and update the plugin's MCP configuration.
Older plugin versions pointed to an HTTP service on `:3846` and named tools that the current app does not expose. The plugin has since moved from the `fanta-docs` marketplace to Fanta-JS, and copies installed from `fanta-docs` no longer update. If you added that marketplace, remove it, then follow the install steps above:
```bash
claude plugin uninstall fanta@fanta-docs
claude plugin marketplace remove fanta-docs
```
# Agent recipes (/docs/plugin/recipes)
These examples assume Fanta is running with a project open and the plugin or [direct MCP connection](/docs/mcp/connect) is active.
## Build a card [#build-a-card]
```text
/design On the active page, create a 320×180 frame called Welcome card. Add a heading and a primary button inside it. Build one visible section at a time with auto-layout where needed. Show a screenshot and summarize the .fnx change.
```
## Revise a selection [#revise-a-selection]
```text
Inspect the current selection. Change its fill to #4F46E5 and its corner radius to 12. Keep its size and position, then show a screenshot.
```
## Reuse a component [#reuse-a-component]
```text
Inspect the selected card and similar copies. If their layer structures match, componentize them so the first is the master and the others become instances with their different text and fills preserved. Verify the result on canvas.
```
## Review before committing [#review-before-committing]
```text
Inspect and screenshot the active page. Check for unparented layers. Read relevant .fnx source and summarize the design changes visible in Git.
```
## Reuse the design system [#reuse-the-design-system]
```text
Inspect the current component properties, variant sets, variable collections, and modes. Reuse the existing spacing and color tokens in a new card; show a screenshot and list the bindings you applied.
```
## Address review comments [#address-review-comments]
```text
List unresolved comments on the active page. Address the comment on the selected card, capture a screenshot, then reply to that exact thread with what changed.
```
The agent can use `get_design_system`, `batch_get`, `get_screenshot`, and `list_comments` for verification. With `report_agent_activity` and the same identity in `batch_design.activity`, Fanta can follow its streamed canvas edits and file changes. `prepare_design_asset` only opens a reviewed generation draft. Export and commit remain app or filesystem workflows, rather than additional local MCP tools.
## Lay out a grid [#lay-out-a-grid]
```text
Build three card columns in one grid frame. Use 1fr tracks with 16 px gaps, pin the featured card across two columns, and show a screenshot at the intended size.
```
# Plugin skills (/docs/plugin/skills)
The plugin ships three Markdown skills. They guide Claude Code; the Fanta app controls which MCP operations are available.
| Skill | Helps with |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `fanta-design` | Inspect editable node styles, stream small `batch_design` edits with agent activity, and check each result. |
| `fanta-verify` | Check structure and screenshots, validate FNX or managed JSON, review comments, and inspect Git changes. |
| `fanta-components` | Componentize copies, create and maintain variant sets, expose properties, and place linked instances. |
The source is under [`plugin/skills`](https://github.com/jeanc18rlos/Fanta-JS/tree/main/plugin/skills) in the Fanta-JS repository. See the [tool reference](/docs/tools) for the actual server contract. The plugin adds guidance and configuration, not new Fanta tools.
# Architecture (/docs/reference/architecture)
Fanta’s desktop executable is built by the `fanta` Cargo package and named `fanta`. `fig_viewer` connects the design UI, canvas, project persistence, and local MCP server to the vendored design engine.
| Area | Source |
| ------------------------------------- | ----------------------------------------------------------- |
| App shell and executable | `crates/fanta` |
| Design UI, source reload, export, MCP | `crates/fig_viewer` |
| Agent operation types and guidelines | `crates/design_surface` |
| Scene graph and edit operations | `crates/fanta-doc` |
| `.fnx` parser and printer | `crates/fanta-fnx` |
| Project layout and `.fant` format | `crates/fanta-format` |
| Figma import | `crates/fanta-fig-interop` |
| Canvas, rendering, text, human tools | `fanta-canvas`, `fanta-render`, `fanta-text`, `fanta-tools` |
| Presentation engine | `crates/fanta-present` |
A project contains `fanta.json`, `.fnx` source under `pages/` and `components/`, managed JSON metadata, assets, an `AGENTS.md` seed, and a `fanta.md` design specification. Layout v5 stores a variant set in `components//set.json` with each member in a child folder; standalone components keep their own component folder. The reader accepts v4 sets and migrates them on the next save. Canvas operations autosave to source; valid source changes reload the canvas; Git tracks the folder. The Code workspace validates the active page or component's FNX and paired JSON against the project before writing them. Structural canvas saves retain supported authored FNX fields and comments on surviving nodes; a lossy destructive change reports a preservation error instead of silently rewriting the source.
The external MCP server runs in the app over a private Unix socket. `fanta --mcp-stdio` discovers the socket and bridges a client to the focused design. The 13 registered tools use the shared `design_surface` provider; `batch_design` streams 43 typed `DesignOp` values. Content edits form one undoable transaction and roll back if an operation fails; selection and viewport changes are not transactional. `batch_get` projects requested nodes as a summary, editable style, or raw data; raw requires exact node IDs. The bridge can receive `--user-data-dir` to target the running instance. The older `fanta-app` / `fanta-ai` crate map and fixed HTTP port do not describe this checkout.
# Changelog (/docs/reference/changelog)
## October 19, 2026 source alignment [#october-19-2026-source-alignment]
These pages now track published [fanta-edit main at `e143440a`](https://github.com/jeanc18rlos/fanta-edit/tree/e143440a93732422ac37c6ad1901ff14c420ec7b). Changes merged after the previous checkpoint renamed the app's Cargo package and action namespace to `fanta`, its project-local configuration directory to `.fanta`, and its app link scheme to `fanta://`. The repository now builds explicitly with `cargo run -p fanta`; plain `cargo run` works through the workspace default. The local canvas MCP roster remains 13 tools with 43 design operations; no new format or generation behavior was found in this source interval.
The accepted signed Build45 installer is still bound to earlier source `57d86330`. It uses `.zed` project settings, `zed::` app actions in keymaps, and `zed://` app links. Current source uses `.fanta`, `fanta::`, and `fanta://`. Custom configuration and links should be reviewed when moving to a future build; automatic migration and a newer public installer have not been verified.
## October 15, 2026 source update [#october-15-2026-source-update]
These pages track published [fanta-edit main at `44584c26`](https://github.com/jeanc18rlos/fanta-edit/tree/44584c26eebb91b1ae97dd07a6715cb22ef289ee). The signed Fanta 1.0.0 Public Alpha installer remains bound to earlier source `57d86330`; this source update is not a new accepted app build.
External MCP still registers 13 tools. `get_editor_state` now previews at most 100 components and reports the total and whether more remain. `get_design_system` pages variables, components, and variant sets independently, and `batch_get` rejects page listings whose traversal exceeds 1,000 nodes. Default page reads and screenshots follow the focused page or opened component. A `batch_design` batch containing only selection or viewport operations does not create an undo step; content edits still commit as one undoable batch.
Current macOS source prefers Skia Graphite on Metal, with Ganesh fallback if Graphite cannot start. Retained translation is enabled unless `FANTA_RETAINED_TRANSLATION=0`. Loading, scoped saving, canvas panning, and memory use have changed for large documents. Bounded benchmarks and source tests do not establish general responsiveness or behavior in the released Build45 installer. Native builds route new AI credit purchases to web Billing; existing Apple subscriptions still open Apple's subscription management.
## October 13, 2026 source and release update [#october-13-2026-source-and-release-update]
At this checkpoint the pages tracked [fanta-edit main at `9e582bee`](https://github.com/jeanc18rlos/fanta-edit/tree/9e582bee494b85f54e4dcb4084b5d55acd097d37). The signed Fanta 1.0.0 Public Alpha installer is bound to source `57d86330`; that checkpoint had no later application-code changes. Source inclusion and installed-app acceptance are described separately. The [official download page](https://www.fantaisa.net/download) makes the Public Alpha available. Its matching Developer ID-signed and notarized DMG passed local installation and save/reopen checks, and an anonymous public download matched the accepted checksum. Clean-account installation and migration from an older version remain unverified.
Current source limits a native Agent turn to 64 model requests, preserving completed work at the visible stop. Other changes since the previous source baseline cover focused numeric draft handling before Save and close, fractional TextPath positioning, rounded-clip targeting, closed-tab restoration, narrow-canvas Crop controls, generated-audio completion feedback, gallery timestamps, and Settings search Escape behavior. The external MCP surface remains 13 tools with 43 design operations; FNX and import/export formats did not change in this interval.
## October 11, 2026 source update [#october-11-2026-source-update]
The docs now track published `fanta-edit` main at [`22f73419`](https://github.com/jeanc18rlos/fanta-edit/tree/22f734193844eab66485e3cb322b529c2965e297). On direct-download macOS, a fresh `.fig` import stages and flushes a complete sibling project before publishing it; if publication fails, the parsed design remains open for a save retry. The project guide also clarifies received-folder Restricted Mode and the limits of concurrent external writes.
Canvas snapping now searches indexed layer targets in the active page or opened component subtree. A Select gesture cancels its pending move if the mouse press is lost, and editable Design Crop shows Ratio, Cancel, and Apply controls. Billing usage charts use one rolling UTC window for their 7, 30, or 90-day daily and key views. Project loading and text-layout caching changed internally; these source changes and mounted tests do not establish native responsiveness or complete installed-app acceptance.
Maintainers can opt into macOS release build diagnostics. The latest documented internal arm64 DMG check used earlier source `79cc2ef8` and an ad-hoc signature; its public release job was skipped. A Developer ID-signed, notarized download and clean-Mac installation remain unverified. The local canvas MCP interface remains 13 tools and 43 design operations.
## October 9, 2026 source update [#october-9-2026-source-update]
The docs now track published `fanta-edit` main at [`79cc2ef8`](https://github.com/jeanc18rlos/fanta-edit/tree/79cc2ef8c094149e8496476c1cb53e2945b8b54a). A single editable TextPath layer offers **Edit object** in the inspector, and **Select matching layers** treats Sections as Sections on the active page. The canvas Properties menu also routes supported specialist layers to the Design inspector. These paths have mounted editor tests; installed-app acceptance remains separate.
JPEG export now uses fixed quality 95, remains lossy, and writes an opaque image. A focused bitmap regression passes, while the source coverage report still records an earlier native JPEG comparison failure. The renderer now retains unaffected effect layers during scene edits and invalidates affected layers; native responsiveness is still under validation.
For outbound account-backed MCP, a failed startup now preserves an unused endpoint OAuth session. Local canvas MCP remains 13 tools and 43 design operations. The release coverage report records bounded Audio and internal ad-hoc DMG checks, but cold MP3 preview was absent in its placement fixture. A Developer ID-signed public download, clean-Mac install, and live managed-service journeys remain unverified.
## October 8, 2026 source update [#october-8-2026-source-update]
The docs now track published `fanta-edit` main at [`d386b9f4`](https://github.com/jeanc18rlos/fanta-edit/tree/d386b9f48557c35302ae8b28c195db453f490141). FNX printing now preserves finite numeric values exactly, including very small values that previously printed as zero. The media guides clarify placement routes: the local picker handles supported raster images and MP4 video; editable SVG can come from Project Assets or generation results, while audio placement uses Project Assets. Video preview and trim have bounded development checks, while arbitrary codecs and installed-release media behavior remain unverified.
The Mac packaging workflow now aligns both bundle version fields with the source version and retries the specific transient busy-disk-image error without replacing a prior finished DMG. These checks improve packaging reliability; the signed download and clean-Mac installation remain separate release gates. The external MCP interface remains at 13 tools and 43 design operations.
## October 7, 2026 source update [#october-7-2026-source-update]
The docs now track published `fanta-edit` main at [`a022ddb4`](https://github.com/jeanc18rlos/fanta-edit/tree/a022ddb4eb0828dea734584aea8e63e6cb503c05). Structural canvas saves preserve authored FNX attributes and comments on surviving nodes; Save reports a preservation error if a destructive edit would lose source-only data. During an unsaved source draft, the accepted properties of one selected layer remain readable while canvas writing stays locked.
Canvas Cut, Delete, and Duplicate now respect layer locks more consistently. Paste checks component dependencies and can restore a captured component or complete variant set after its original definition was removed. The inspector shows more resolved variable values and independent corner fields; variant navigation and instance text editing follow the visible member and binding rules. Edit Path shows anchors on entry, and Escape can finish active canvas text editing. The external MCP roster remains 13 tools with 43 design operations.
The retained Metal translation renderer is opt-in and its native performance target remains unverified. The selected distribution is a direct-download Mac app, with mounted-DMG verification added to packaging; signed download and clean-Mac installation still require validation. The [release coverage report](https://github.com/jeanc18rlos/fanta-edit/blob/a022ddb4eb0828dea734584aea8e63e6cb503c05/docs/alpha/CAPABILITY_COVERAGE.md) distinguishes bounded checks from release readiness.
## October 6, 2026 source update [#october-6-2026-source-update]
The docs now track published `fanta-edit` main at [`8fe28c69`](https://github.com/jeanc18rlos/fanta-edit/tree/8fe28c69bda2dca80bd01c70f93a6912148e7668). Figma import now preserves supported Boolean operands and warns about known flattened or omitted structures. Canvas and keyboard duplication preserve copied component definitions, complete variant sets, and supported internal prototype links; same-document Paste retains existing definitions, while cross-document canvas Paste reports that it is unsupported. The inspector adds or repairs controls for mixed selections, bound paint, Boolean nodes, rotation, flipping, alignment, distribution, and Tidy up.
The Code workspace gains embedded Find, selected-buffer **Discard draft**, and source Save/Undo preservation. The editor also improves project/source reload ownership and layout preservation. The prototype detail's **X** closes the detail without deleting its interaction; **Remove** is the deletion action. Current time in Motion accepts a typed seek. The [source release coverage report](https://github.com/jeanc18rlos/fanta-edit/blob/8fe28c69bda2dca80bd01c70f93a6912148e7668/docs/alpha/CAPABILITY_COVERAGE.md) records bounded native checks alongside open large-project Save, draft recovery, final artifact, and distribution gates. These implementation changes do not establish a new packaged release.
## October 5, 2026 source update [#october-5-2026-source-update]
The docs now track published `fanta-edit` main at [`23b1ff95`](https://github.com/jeanc18rlos/fanta-edit/tree/23b1ff95766052a83351e6584171b58a21f7f570). The editor implements grid auto-layout, node-aware double-click and canvas context-menu actions, and a separate **Build** mode for task-based agent design with review controls. Grid still has documented Figma behavior gaps. Variant sets gain a visible frame and operations to grow, shrink, arrange, and rename them; project layout v5 stores a set and its member components in one folder, migrating v4 on save.
The external server still exposes 13 MCP tools, with 43 `batch_design` operations. New operations cover fills and effects, constraints, shape creation, grid layout, and component/variant-set work. `batch_get` can return a summary, editable style projection, or raw node data. These pages describe merged implementation; packaged release and hosted-service availability require separate verification.
## October 4, 2026 source update [#october-4-2026-source-update]
The docs now track published `fanta-edit` main at [`af712551`](https://github.com/jeanc18rlos/fanta-edit/tree/af712551269bdd2c7eedc45d0ea1567228fae686). The Code workspace can edit the active page or component's paired JSON alongside FNX, validate the complete candidate against the project, and reload the canvas. Modern FNX with explicit IDs can recover a missing or damaged sidecar. A failed external source reload keeps the last valid canvas and reports a repairable error.
External `batch_design` still exposes 33 operations through the same 13 MCP tools, but now streams each operation visibly while retaining one undoable, rollback-safe batch. An optional `activity` identity and richer `report_agent_activity` fields let Fanta follow an agent across the Canvas, Variables, and Code workspaces. The source also improves property editing, component-master navigation, and the in-app agent workflow. These are implementation claims, not a new packaged release announcement.
## October 3, 2026 source update [#october-3-2026-source-update]
The docs now track `fanta-edit` main at [`182b111c`](https://github.com/jeanc18rlos/fanta-edit/tree/182b111c18415c4170abf31a9660ec11231fd2d2). The external live MCP bridge registers 13 tools. New tools inspect the design system, prepare an image or SVG generation draft for user review, validate FNX without writing, import an image into the project, read and reply to comments, and report an agent's local canvas activity. `batch_design` also has operations for child layout, variables and modes, variant sets, component properties, and instance values.
The editor source adds direct local image and MP4 placement, proportional scaling, arrow drawing, Text on Path, Motion keyframes and playback, persistent measurements and annotations, and a guarded Dev inspection session. Project creation seeds a `fanta.md` design specification. Save As, media playback and trimming, account views, and source save recovery also changed. These pages describe the committed implementation; public packaging and service availability still depend on the build and deployment.
## September 29, 2026 source update [#september-29-2026-source-update]
The docs now track `fanta-edit` main at [`ebabb405`](https://github.com/jeanc18rlos/fanta-edit/tree/ebabb405779ef9772b8b2de6f227ad5a9776bdc6). Its implemented changes include a persistent Project Assets panel; placement of generated image, SVG, MP4, and WAV/MP3/FLAC audio assets; audio preview, duration, seeking, and save fixes; catalog-driven generation controls; managed chat-model discovery; the in-app Jev evaluation tool; and a new Settings window with MCP, account, billing, and privacy sections.
The source also contains a Mac App Store feature build with process and Git restrictions. The distribution and packaged external-agent bridge are described conditionally because source and merged commits alone do not establish public availability or end-to-end release validation.
## Current alpha documentation [#current-alpha-documentation]
This edition introduced the native Fanta app and its `.fnx` project workflow. It corrected earlier references to a separate `fanta-app` executable, fixed HTTP MCP port, and per-action MCP roster. At that source revision the external interface had six tools through `fanta --mcp-stdio`; the October 3 source revision above extends it to 13.
The docs cover project creation, Git review, Figma import, the agent build loop, source editing, and the supported alpha editor paths. The [source](https://github.com/jeanc18rlos/fanta-edit) and its [known issues](https://github.com/jeanc18rlos/fanta-edit/blob/main/docs/alpha/KNOWN_ISSUES.md) remain the record of implementation and validation status.
At that revision, several visible controls were not connected. The dated entries above supersede those observations where implementation changed. The issue log and release coverage report separate current source behavior from native-app and distribution validation.
# CLI & binaries (/docs/reference/cli)
From the [fanta-edit repository](https://github.com/jeanc18rlos/fanta-edit):
| Command | Purpose |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `cargo run -p fanta` | Build and run the current app package; plain `cargo run` also works because `fanta` is the workspace default. |
| `cargo build --release -p fanta` | Build `target/release/fanta`. |
| `./script/bundle-mac` | Package the macOS app and DMG. |
| `./script/clippy` | Repository lint workflow. |
| `script/smoke-mcp ` | Exercise the live MCP/design loop against a running app. |
With a project open in a non-Store Fanta build, choose **Connect External Agent** in Fanta. It copies project-scoped Codex and Claude Code instructions with the running app's actual executable and user-data directory. The Claude Code command has this shape:
```bash
claude mcp add --scope project --transport stdio fanta -- /Applications/Fanta.app/Contents/MacOS/fanta --mcp-stdio --user-data-dir ''
```
Use the copied command verbatim so the instance path is correct. For Codex, Fanta provides a `[mcp_servers.fanta]` snippet for the trusted project's `.codex/config.toml`. The bridge requires a running app and focused design. `fanta_live_mcp.enabled` defaults to true in user settings. There is no `FANTA_MCP_ADDR` or `fanta-mcp` binary in this checkout. The packaged Mac App Store bridge has not been verified; its in-app local MCP subprocesses are disabled.
Current source also registers `fanta://` app links; the signed Build45 app was built from earlier source that registered `zed://`. This protocol rename has not been checked in a newer public installer.
# Reference (/docs/reference)
These pages track published fanta-edit main at `e143440a`: a native macOS editor with a source-backed project format and a 13-tool external MCP server. The signed Public Alpha installer is bound to earlier source `57d86330`; later source changes have not been accepted as a new installer.
# LLM-readable docs (/docs/reference/llms)
Agents can read the site through [`/llms.txt`](/llms.txt), [`/llms-full.txt`](/llms-full.txt), the **Copy Markdown** button on each page, or page Markdown URLs under `/llms.mdx/docs/`. Source Markdown lives in the [fanta-docs repository](https://github.com/jeanc18rlos/fanta-docs).
Reading the docs does not give an agent access to a canvas. To make a live design change, start Fanta and [connect to its local MCP server](/docs/mcp/connect). The connected server’s `get_guidelines` response and tool schema describe the current build. For alpha limitations, consult the [known issues](https://github.com/jeanc18rlos/fanta-edit/blob/main/docs/alpha/KNOWN_ISSUES.md).
# Agent orchestration & presence (/docs/tools/agent-control)
Start a session with `get_guidelines` and `get_editor_state` to identify the focused design and active page. `report_agent_activity` shows an external agent's current work location and action in Fanta. Give each agent a stable `agent_id`, a readable `agent_name`, and an `action`; optionally include `page`, exact `node`, world coordinates as `[x,y]`, `project_root`, `source_path`, and `workspace` (`canvas`, `variables`, or `code`). Report each visible editing milestone and when moving between files or workspaces. A source path must stay inside the active Fanta project. Set `active: false` when finished. Unrefreshed reports expire after about 30 seconds.
Pass the same identity as `batch_design.activity` when editing canvas nodes. The operation batch previews one step at a time and updates the agent's focus; Fanta can follow that agent across canvas pages, component views, variables, and code. The Canvas workspace shows a pulsing edge while an agent reports activity for the open project. `activity` is optional for older clients; unidentified external edits use a shared fallback identity. Follow may change the visible page while a batch runs; an omitted `parent` still uses the page captured when the batch started.
```json
{"label":"Build card","activity":{"agent_id":"designer-a","agent_name":"Merlyn","action":"Building card","workspace":"canvas"},"ops":[{"op":"set_props","id":"","name":"Card"}]}
```
If several agents work on one project, assign distinct nodes or source files and use one coordinator to review their screenshots and Git diffs. `batch_design` commits or rolls back as one undoable transaction, but activity reports do not lock nodes or files. The external MCP surface has no `spawn_agent`, `agent_playbook`, or task-lock tool.
The built-in Agent Panel uses design tools and reports its own identity and activity. Its profile and permission controls differ from the external MCP interface.
# Comments and review threads (/docs/tools/comments)
`list_comments` reads canvas comment threads on the active page. Pass `page` to inspect another page or `include_resolved: true` to include closed threads. The result includes each thread's pin position and replies. Read unresolved feedback before revising a reviewed design.
`reply_comment` takes the exact thread `id` from `list_comments`, a `body`, and optional `page`, `author`, and `resolve`. The default author is “Fanta Agent.” Reply with the change or finding; set `resolve: true` only after the requested work is verified on the canvas. Comments are stored with the project page metadata and are separate from visual exports.
The in-app Agent Panel has a related `design_comments` tool. In Plan mode it may read threads but cannot reply or resolve them. See [review and revision](/docs/agents/review-revision).
# Components, instances & variants (/docs/tools/components-instances)
Build a frame or group, read its exact ID, and promote it:
```json
{"label":"Make button component","ops":[{"op":"create_component","id":""}]}
```
The master stays on canvas and the result returns a component ID. Place a copy with `create_instance`, using the ID or a unique component name:
```json
{"label":"Place button","ops":[{"op":"create_instance","component":"","x":400,"y":120}]}
```
An instance inherits its master’s size and follows later master edits. `get_editor_state` previews at most 100 component source paths. If `more_components` is true, page `get_design_system` with `offset` and `limit` for the remaining definitions; its components and variant sets have separate counts and `more_*` flags. A standalone component uses `components//master.fnx`. A variant set uses one `components//` folder with `set.json` and a subfolder with `master.fnx` for each variant. Older flat variant folders are read and moved into the set folder on the next save.
## Componentize existing copies [#componentize-existing-copies]
`componentize` takes two or more similar, side-by-side layer IDs. The first becomes the master; every other copy is replaced in place by an instance, preserving supported differences such as text, fills, hidden layers, and opacity as overrides. The copies must have the same structure: matching layer kinds in the same order. The operation reports `component` and new `instances` IDs; a mismatch fails without replacing the copies.
```json
{"label":"Reuse cards","ops":[{"op":"componentize","ids":["",""]}]}
```
To make variants, first promote two or more standalone master nodes with `create_component`, then pass their **master node IDs** to `combine_variants`. Name masters after their axis values, for example `Variant=Primary, State=Default` and `Variant=Primary, State=Hover`, to create separate axes. Plain names become values of one `Variant` axis. The operation creates one set frame, arranges its variants in a grid, and reports `component_set` and `frame`; use the set ID (or unique name) in `create_instance`.
```json
{"label":"Add button variants","ops":[{"op":"combine_variants","ids":["",""],"name":"Button"}]}
```
`add_variants` adds standalone masters named `Axis=Value` to an existing set. New axes give older variants a `Default` value. `remove_variant` accepts a variant master node ID or component ID and leaves that variant as a standalone component beside the set frame. `arrange_variants` restores the set frame and grid order. `rename_component` changes a component or set name along with its master or frame layer; names must remain unique. Use these operations for structural changes rather than manually renaming a `def.json`, `set.json`, or component folder, since pages refer to component names.
`create_component_property` can expose a `variant` axis or a `text`, `boolean`, `number`, `color`, or `instance_swap` property on a component. For a field on a descendant, use `bind_component_property` with its node ID, a compatible `target` such as `{"prop":"text_content"}`, and the exposed property ID or unique name. `set_instance_property` changes an instance's exposed property; the value must match its kind.
Read `get_design_system` after each structural step to obtain exact set, property, and axis values. An invalid target or property value fails the batch and rolls it back.
# Create, insert & arrange (/docs/tools/create)
`create_node` supports `frame`, `rectangle`, `ellipse`, and `text`. Give world-space `x`, `y`, `width`, and `height`; optionally pass `name`, a solid hex `fill`, `text`, `font_size`, or a parent node ID. `create_shape` adds `line`, `polygon`, `star`, and SVG `path` vector shapes with a world-space box; polygons accept `points`, stars also accept `inner_ratio`, and a path requires SVG `d` data in `path`. An open path or line has a stroke by default and no fill. Without `parent`, a node goes on the page active **when the batch starts**, even if Follow changes the viewed page during a streamed edit.
```json
{"label":"Add card","ops":[{"op":"create_node","node_type":"frame","name":"Card","x":100,"y":100,"width":320,"height":180,"fill":"#F7F7F7"}]}
```
```json
{"label":"Add accent star","ops":[{"op":"create_shape","shape":"star","x":120,"y":120,"width":48,"height":48,"points":5,"fill":"#F59E0B"}]}
```
The response returns a `created` ID. Use it in a later call when placing a child; the batch has no named temporary-ID bindings. `create_image` takes encoded PNG/JPEG/WebP/GIF bytes, including a data URI, and saves an image asset. It does not fetch a URL; `import_image` can save an HTTP(S) image to project Assets without creating a layer. `create_instance` places a linked component copy.
`duplicate`, `group`, `frame_selection`, `ungroup`, `reparent`, `set_index`, and `delete` organize existing nodes. A frame clips and can have a background; a group is plain organization. Deleting a container removes its subtree, so inspect exact IDs first. Each operation previews visibly as the call runs. Any failed operation rolls back the entire batch. After a structural edit, confirm autosave and the FNX diff: persistence can refuse deletion or a node-type change that would lose an authored source-only attribute.
# Tool Reference (/docs/tools)
Fanta's external MCP server acts on the focused design. Use **Help → Connect Claude Code / Codex…** to copy the command for the running app. It exposes **thirteen** tools, with `batch_design` carrying the individual edit operations.
| Tool | Purpose |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_editor_state` | Read project, pages, selection, viewport, editability; optionally ask for `empty_space: [width,height]`. |
| `get_design_system` | Read components, variant sets, variable collections, modes, values, and selected bindings. |
| `prepare_design_asset` | Open a user-reviewed image or SVG generation draft without submitting it. |
| `get_guidelines` | Read current design and source-editing rules. |
| `batch_get` | Read exact nodes or a paged page tree. |
| `batch_design` | Preview content edits in order, then commit or roll back one undoable transaction; selection- or viewport-only batches create no undo step. |
| `get_screenshot` | Render a page, node, or motion-clip sample as PNG. |
| `read_fnx_source` | List or read source files in slices. |
| `validate_fnx_source` | Validate a complete FNX or managed project JSON candidate without writing. |
| `import_image` | Import a local file, HTTP(S) URL, or base64 image into project Assets. |
| `list_comments` | Read unresolved or resolved canvas comment threads. |
| `reply_comment` | Reply to a thread and optionally mark it resolved. |
| `report_agent_activity` | Report an agent's canvas, variables, or code focus to Fanta. |
`batch_design` takes `ops: [{"op":"…",…}]`, an optional `label`, and optional `activity` containing a stable `agent_id`, `agent_name`, and `action`. Reuse the identity from `report_agent_activity` to keep Follow on the same agent during streamed placements. Its current 43 operations are:
* **Create and arrange:** `create_node`, `create_shape`, `create_image`, `create_instance`, `set_props`, `set_index`, `rotate`, `align`, `distribute`, `group`, `frame_selection`, `ungroup`, `duplicate`, `reparent`, `delete`, `select`, `set_viewport`.
* **Style and layout:** `set_stroke`, `set_shadow`, `set_effects`, `set_fill`, `set_text_style`, `set_constraints`, `set_auto_layout`, `set_grid_layout`, `set_layout_child`.
* **Variables:** `create_variable_collection`, `add_variable_mode`, `create_variable`, `set_variable_value`, `set_variable_mode`, `bind_variable`, `unbind_variable`.
* **Components:** `create_component`, `componentize`, `combine_variants`, `add_variants`, `remove_variant`, `arrange_variants`, `rename_component`, `create_component_property`, `bind_component_property`, `set_instance_property`.
Ask your MCP client for the live schema to see every field and enum value. `get_editor_state.capabilities` advertises newer operation support in the running build. Content edits are shown one by one while the call runs. They commit as one undo step; a failed operation rolls content edits back. Selection and viewport changes are not transactional. `batch_get` can return editable `style` detail, so inspect a node before changing its full fill or effect stack.
# Read, query & debug (/docs/tools/inspect)
`get_editor_state` reports the project root, pages, focused page or opened component, selection, viewport, editability, hints, and capability flags for newer design operations. Its `components` overview contains at most 100 definitions; check `component_count` and `more_components`, then use `get_design_system` to discover the rest. Pass `empty_space: [width,height]` to find a free top-left for a new top-level frame on the focused canvas.
`get_design_system` reports collections, modes, typed variables, component properties, and variant sets. `offset` and `limit` page the variables, components, and component sets **independently** with the same window (default 100, maximum 200). Advance `offset` until each relevant `more_variables`, `more_components`, or `more_component_sets` flag is false; their counts can differ. `collection` filters variables only. `include_bindings: true` reads bindings on selected nodes. `list_comments` reads unresolved review threads by default.
`batch_get` without `ids` lists the focused page or opened component by default. It uses depth 2, 200 direct children, and `detail: "summary"`. The result reports `child_count`, `children_offset`, `children_limit`, and `more_children`; continue with `offset` and `limit` until done. A page listing is refused if it would traverse more than 1,000 nodes, even when its response is small; reduce `depth` or `limit`, page top-level layers with `offset`, or request relevant exact IDs. With exact `ids`, the default `detail: "style"` reports editable world bounds, fills, strokes, effects, layout, constraints, text, and bindings in the design-operation vocabulary. Use `detail: "style"` on a page listing to merge these properties into each listed node; `detail: "raw"` returns internal node records only with exact IDs. Pass `include_geometry: true` for world bounds on a summary. A response over 256 KiB is also refused rather than truncated; narrow depth, child count, IDs, geometry, or detail.
Read `style` before replacing a node's entire paint or effect stack. A reported image fill references an existing asset, while `set_fill` requires encoded image bytes in `source`; internal or read-only paint kinds are not all writable through that operation.
`read_fnx_source` without `path` lists source files. With a project-relative path, it returns source text with `truncated`, `next_offset`, and a notice. `offset` is a 1-based **line** number; `limit` counts lines. The default text budget is 64 KiB per call, with `max_bytes` capped at 1 MiB. Follow `next_offset` before making whole-file edits. Imported `.fig` pages may be much wider than one result.
`validate_fnx_source` accepts a project-relative `path` and optional complete `source` candidate. With `source`, it checks the candidate without writing it; without `source`, it checks the saved file. It also checks managed project JSON: the manifest, document metadata and motion, variables and modes, component definitions and sets, page headers, asset index, and FNX identity sidecars. For an existing JSON file, validation checks whether the complete project can load with the candidate. Repair diagnostics before saving with file tools; valid JSON syntax alone is insufficient.
# Auto-layout, transform & viewport (/docs/tools/layout)
`set_auto_layout` takes an `id`, `direction` (`horizontal`, `vertical`, `grid`, or `none`), and optional `gap`, `padding`, `align_items`, and `justify`. Padding accepts one, two, or four numbers. It also accepts `primary_sizing` and `counter_sizing` (`fixed` or `hug`), `min_size` and `max_size` as `[width,height]`, `wrap`, `counter_gap`, and `align_content` (`auto` or `space_between`) for wrapped lines. Use `null` in either size-limit slot to clear that axis's limit. Once a container is in auto-layout, change layout rules or sibling order instead of setting child `x` and `y`.
```json
{"label":"Lay out card","ops":[{"op":"set_auto_layout","id":"","direction":"vertical","gap":12,"padding":[20]}]}
```
Use `set_layout_child` on a child to set its positive `grow` value, cross-axis `align_self`, or `absolute` participation. A text node's `set_text_style.sizing` can be `fixed`, `auto_height` (wrap at its width), or `auto_width` (hug unwrapped text). For a minimum-size button, use horizontal layout, `hug` sizing, `[128,48]` minimum size, and an `auto_width` label. For a card, a fixed counter-axis width with `auto_height` body text gives predictable wrapping.
## Grid layout [#grid-layout]
On a frame that was not already a grid, `set_auto_layout` with `direction: "grid"` starts with roughly square equal columns for existing children. Use `set_grid_layout` for exact tracks: a non-negative number is fixed pixels, `"1fr"` and `"2fr"` share leftover width, and `"auto"` hugs content. Set at least one column; `rows` is optional and extra rows are added as children need them. `gap` sets column and row gaps, and `row_gap` can override the latter.
```json
{"label":"Set card grid","ops":[{"op":"set_grid_layout","id":"","columns":["1fr","1fr","1fr"],"gap":16}]}
```
Unpinned children fill cells row by row. `set_layout_child` can pin a child with zero-based `column` and `row`, `column_span` and `row_span`, and `cell_horizontal` / `cell_vertical` (`start`, `center`, `end`). `auto_place: true` removes a pin; send it without cell fields. `grow: 1` fills the cell width and `align_self: "stretch"` fills its height. Explicit cell fields only apply to children of a grid container.
`set_constraints` controls how a node moves or resizes when its parent frame changes size outside auto layout: horizontal `left`, `right`, `left_right`, `center`, or `scale`; vertical `top`, `bottom`, `top_bottom`, `center`, or `scale`. Omitted axes keep their current values.
`align` aligns two or more nodes to a shared edge or center line, or one node to its parent. `distribute` spaces three or more nodes along an axis. `rotate` sets an absolute angle; `set_index` changes sibling z-order; `reparent` moves a node while preserving its world position. `set_viewport` stores canvas center or zoom.
# Generation & references (/docs/tools/media)
The `batch_design` operation `create_image` accepts a `data:image/...;base64,...` URI or raw base64 for an encoded PNG, JPEG, WebP, or GIF. You can provide width or height to preserve aspect ratio, and `meta` to record provenance. Fanta ingests it as an asset under `assets/images/` on save.
`create_image` does not fetch `http(s)` URLs. Use `import_image` with exactly one of `path` (absolute or project relative), HTTP(S) `url`, or base64 `source` to save an image into the project's Assets panel. It returns an asset ID and saved path but does **not** create a canvas layer. A URL import has a download timeout and image-size limit. Use a separate placement workflow or valid FNX source edit when the design needs that asset on canvas.
`set_fill` can replace a frame or shape's paint stack with an image paint. Its `source` is encoded PNG/JPEG/WebP/GIF bytes, and `fit` can be `fill`, `fit`, `stretch`, or `tile`. It ingests the bytes as an asset in the same undoable batch. A style read may show an existing image's asset ID; that ID is not the `source` argument for `set_fill`.
`prepare_design_asset` accepts `kind: "image"` or `"svg"`, a prompt, and optional `preferred_model`. It opens the existing generation composer for the user to review; it does not submit a request or spend credits. The external MCP surface has no direct `generate_image` or `generate_media` tool. Some toolbar AI commands also open drafts that require the user to send them.
Inspect imported or placed media on canvas and with `get_screenshot`. See the [known issues](https://github.com/jeanc18rlos/fanta-edit/blob/main/docs/alpha/KNOWN_ISSUES.md) for alpha limitations.
# Prototyping & interactions (/docs/tools/prototype)
The external MCP server’s `batch_design` schema has no operation for prototype flows, reactions, transitions, or animation keyframes. Older `create_flow` and `set_reaction` examples are not valid for this alpha server.
Authored animation clips live in `doc/motion.json`, apart from page `.fnx` nodes. Read the existing schema before editing clips, tracks, or keyframes with file tools, preserve IDs, and validate screenshots at several `motion_clip` / `playhead_ms` samples. The external MCP tools can inspect motion samples, but cannot author a clip through `batch_design`. Check the current app and [known issues](https://github.com/jeanc18rlos/fanta-edit/blob/main/docs/alpha/KNOWN_ISSUES.md) for UI readiness.
# Sessions, input & checkpoints (/docs/tools/session)
`batch_design` previews content edits in order while the call runs, then commits them as one named undo step. A batch containing only `select` or `set_viewport` operations changes the current view without a content preview or undo step. If an operation fails or the call is interrupted, content edits in the batch roll back; selection and viewport changes are not transactional. The result identifies a failing operation. Use a descriptive `label` for a single component or coherent section; a whole screen in one batch is harder to follow and review.
Canvas edits autosave to `.fnx` after editing stops. Review the source diff and use Git commits for durable milestones. A dirty Code workspace FNX or JSON buffer locks canvas editing until its draft is saved or discarded. Source Save validates and reloads the project; **Discard draft** reloads the selected buffer from disk. Finish a source edit and its reload before returning to canvas edits on the same nodes.
An undoable canvas batch and a persisted source change are separate checkpoints. When a structural edit would discard an authored FNX attribute or comment, the source writer can refuse the save even after the change appeared on canvas. Read the save error and diff; Undo the canvas edit or make an intentional, validated FNX change before retrying.
The external MCP server does not expose pointer-event replay, checkpoints, or `try_edit` tools. Use the editor for manual interaction and the MCP tools for state, node queries, transactional edits, screenshots, source reading, comments, and agent activity.
# Style, typography & design tokens (/docs/tools/style-variables)
| `batch_design` operation | Change |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `set_props` | Name, position, size, opacity, first paint replaced by a solid fill, corner radius, text, hidden, locked. |
| `set_fill` | Replace all fills with solid, linear or radial gradients, or image paints; `[]` clears them. |
| `set_stroke` | First outline color, width, alignment, per-side widths, dash pattern, cap, and join; width 0 removes it. |
| `set_shadow` | First drop shadow or all drop shadows with `remove: true`. |
| `set_effects` | Replace the complete stack of drop and inner shadows, layer blur, and background blur; `[]` clears it. |
| `set_text_style` | Font family, weight, size, line height, letter spacing, alignment, glyph color, and text-box sizing for the whole text node. |
Colors use `#RRGGBB` or `#RRGGBBAA`. Omitted fields in `set_props`, `set_stroke`, and `set_text_style` are unchanged; `set_fill` and `set_effects` replace whole stacks. Read the node with `batch_get` using `detail: "style"` before replacing one. For example:
```json
{"label":"Style title","ops":[{"op":"set_text_style","id":"","font_weight":700,"font_size":24,"color":"#202020"}]}
```
```json
{"label":"Style card","ops":[{"op":"set_fill","id":"","paints":[{"kind":"linear","stops":[{"position":0,"color":"#FFFFFF"},{"position":1,"color":"#E7EEFF"}]}]},{"op":"set_effects","id":"","effects":[{"kind":"drop_shadow","color":"#0000001A","y":8,"blur":24}]}]}
```
A gradient needs at least two stops between 0 and 1. Linear gradient `from` and `to` and radial gradient `center` use coordinates in the node's 0–1 box; a radial `radius` is a fraction of its size. An image paint needs encoded PNG/JPEG/WebP/GIF bytes in `source`, not a URL or an existing asset ID. Per-side stroke widths on a frame or rectangle use `[top,right,bottom,left]`; for example `[0,0,1,0]` makes a bottom border. `dash` alternates on/off lengths; an empty array makes it solid. Use `set_text_style` for glyph color rather than `set_fill` on a text node.
## Reusable variables [#reusable-variables]
Call `get_design_system` before adding tokens. It returns collections, modes, typed variables, component metadata, and source paths. Use `offset` and `limit` (default 100, maximum 200) to page variables, components, and component sets independently. Continue while the relevant `more_variables`, `more_components`, or `more_component_sets` flag is true. `collection` filters variables only; `include_bindings: true` includes bindings on selected nodes. Existing names must be unique when used in place of IDs.
Use `create_variable_collection` (default mode `Default`), `add_variable_mode`, `create_variable`, and `set_variable_value` to create values by mode. Variable kinds are `color`, `float`, `string`, `boolean`, and `typography`; a value can also alias another variable using `{"alias":""}`. `set_variable_mode` selects a collection mode for the document or pins one to a frame. `bind_variable` and `unbind_variable` connect values to node properties.
```json
{"label":"Create theme color","ops":[{"op":"create_variable_collection","name":"Theme","modes":["Light","Dark"]},{"op":"create_variable","collection":"Theme","name":"surface/accent","kind":"color","value":"#2255EE"}]}
```
After reading the returned IDs, set the second mode and bind a node:
```json
{"label":"Apply theme color","ops":[{"op":"set_variable_value","variable":"surface/accent","mode":"Dark","value":"#88AAFF"},{"op":"bind_variable","id":"","property":{"prop":"fill_color"},"variable":"surface/accent"}]}
```
Binding targets include indexed fill and stroke color or stroke width, corner radius, opacity, visibility, text content, text style, and clip width or height. Use the live schema to check type compatibility. For per-run rich text or paint kinds not supported by `set_fill`, read the complete `.fnx` section and validate a complete candidate with `validate_fnx_source` before saving.
# Version control (/docs/tools/vcs)
Canvas edits autosave as `.fnx` source in a project folder, so `git diff` shows the change when the project is in a repository. In non-Store builds, **File → Review Changes** opens a review UI and **File → Commit…** records the reviewed change. A new project is initialized when a bundled or system Git is available, unless the folder is already inside a repository.
The external MCP server has no `vcs_begin_task`, `vcs_commit`, or `vcs_promote` tools. An agent can edit through MCP and use ordinary Git tools against the project folder if its environment allows. Screenshot the result and review the source diff before committing.
The non-Store app bundle includes Git, so Xcode Command Line Tools are not normally required. Mac App Store feature builds save projects without automatic `git init`; use a separate Git client for version history there.
# Export & visual verification (/docs/tools/verify)
`get_screenshot` renders the active page to PNG. Pass `page` for another page, `node` for a node region, or `max_dimension` to cap its longer side (default 768 px, maximum 1568 px). Pass an exact `motion_clip` ID from `get_editor_state.motion_clips` and a `playhead_ms` sample time to inspect authored motion. The result is MCP image content, so an agent can inspect the actual rendered design.
After `batch_design`, screenshot the changed frame, compare it with the intended layout, make a targeted correction, and inspect another screenshot. Review the `.fnx` diff after autosave. A successful operation response alone is not a visual check.
The external MCP server has no `export_png`, `export_svg`, `compare_screenshot`, or `review_design` tool. Fanta’s editor export UI can write PNG, JPG, SVG, and PDF under the project’s `exports/` directory. Use the UI for those outputs; `get_screenshot` is the MCP verification tool.
