FigSync

This document covers the full FigSync workflow. Start with Installation and Quick Start; go deep on How It Works for the pipeline detail; reach Troubleshooting when something doesn't import the way you expect.

⤓ Installation

Import once. The Hub window lights up from the menu.

From the Unity Asset Store

Prerequisites

FigSync uses Unity packages that ship with a default Unity 2021.3+ install:

• com.unity.ugui (the Canvas / UGUI runtime).
• com.unity.textmeshpro ≥ 3.0 (text rendering — TMP Essential Resources required).
• com.unity.nuget.newtonsoft-json ≥ 3.2.1 (JSON serialisation).

If TMP Essential Resources isn't imported yet, the first sync will surface a one-time warning. Run Window → TextMeshPro → Import TMP Essential Resources and re-sync.

What gets installed

Assets/FigSync/
  Editor/                     // Pipeline, drawers, settings, hub window
    Bridge/                   // Local HTTP bridge for the Figma plugin
    Drawers/                  // One drawer per Unity UGUI component
    Hub/                      // Tools → FigSync window + settings store
    Pipeline/                 // Numbered Step01..Step26 deterministic flow
    Settings/                 // Per-tab settings UI (UI Toolkit)
    Web/                      // Figma REST + Google Fonts clients
  Runtime/                    // Shaders, helper components, ScriptableObjects
    Components/               // FigSyncSyncHelper, dropshadow, blur, etc.
    Shaders/                  // SDF rounded-corner + gradient
  Generated/                  // Per-sync output: sprites, fonts, snapshot, report
  Documentation/              // You are hereProject

🔌 Figma Plugin (Optional)

The fastest path for FigJam files, complex frames, or offline sync.

FigSync ships with a Figma plugin called FigSyncExporter. Installed in Figma, it captures the full plugin-API node tree (which is richer than REST), bundles every fill image and pre-rendered vector raster, and pushes the result to Unity over a local HTTP bridge. The Unity Hub picks up the push automatically — no copy/paste of node ids.

Why use the plugin path

Install the plugin

⚡ Quick Start

Zero to a synced Canvas in about a minute.

⚙ How It Works

A 27-step deterministic pipeline, runnable resumable cancellable.

Each sync runs as a sequence of named steps. Steps log their start and finish to the Console (look for the [FigSync] prefix); the Hub window mirrors the same status as a per-step progress strip. A failed step stops the pipeline early; the scene either keeps the prior state intact (if the failure happened pre-Draw) or surfaces the partial result with a HelpBox explaining where it broke.

Steps, in order

What happens at Draw time

The Draw step iterates the FlatList. Each entry is either reused, deferred, or freshly drawn:

• Reused — node's hash matches the prior snapshot AND a scene GameObject with the matching FigSyncSyncHelper.NodeId still exists. Re-parented under its updated parent; no children re-created.
• Deferred — user unticked the root in the diff window. Same as Reused (preserve existing scene state), but new descendants under that root are skipped entirely.
• Drawn fresh — the right drawer is resolved by tag (Image, Text, Vector, Button, Toggle, etc.), instantiates a GameObject, sets RectTransform, applies fill + text + auto-layout, stamps a FigSyncSyncHelper with the node id and hash.

What happens at Finalise time

After every node has a GameObject, a per-backend Finalise pass runs second-pass work that needs the full hierarchy in place:

• Bind TMP fonts to text components from the per-family _SDF.asset.
• Add FigSyncRoundedCorner on every node with non-zero corner radius. The component encodes radius + stroke + shadow into vertex uv channels so a single SDF shader draws them all.
• Attach FigSyncDropShadow on every node with a DropShadow effect; FigSyncBackgroundBlurCompositor on every node with BackgroundBlur.
• Apply auto-layout drivers (LayoutGroup + ContentSizeFitter + spacer injection for SPACE_BETWEEN).
• If the source is FigJam, inject the dotted canvas backdrop as the first sibling under each page.

🔒 Authentication

Three options. Pick one. Or two.

Option 1 — Personal Access Token

Simplest path. Generate a token at figma.com/settings (Personal access tokens section), paste it into Tools → FigSync → Settings → Auth → Personal Access Token. The token stays in EditorPrefs (base64-obfuscated, never written to assets) and is sent only over HTTPS to Figma's REST API.

Option 2 — OAuth

Click Sign in with Figma in the Auth tab. A browser tab opens Figma's consent screen; after approval Figma redirects to a one-shot local listener on 127.0.0.1 with the auth code. FigSync exchanges that for an access + refresh token pair and stores both in EditorPrefs (same obfuscation as the PAT). Refresh tokens rotate automatically; expired tokens trigger a transparent refresh on next call.

Option 3 — The Figma plugin

No tokens needed. Install the plugin in Figma and push directly. The plugin reads node data using its own Figma plugin sandbox permissions; FigSync receives an HTTPS-style ZIP bundle over a loopback port. No credentials leave your machine.

🌐 The Hub Window

One window, every control. Tools → FigSync.

Sync tab

The everyday surface. Paste a Figma URL, choose the import mode (Live URL, Offline ZIP, Bridge push), and click Sync. A status strip across the top of the window mirrors what's happening behind the scenes — current step, elapsed time, last warning. A right-side panel shows the last sync's diagnostic summary (node count, sprite count, fonts bound, missing fonts, anything that went sideways).

Settings tabs

Each tab edits one slice of the FigSyncProjectSettings ScriptableObject (lives at Assets/FigSync/FigSyncProjectSettings.asset; commit it). Changes apply on next sync.

• Auth — Personal Access Token, OAuth sign-in, Google Fonts API key, bridge port.
• Main Settings — output folder, backend (UGUI), root canvas reference, debug verbosity.
• Buttons — how Figma "Button" tags map to UGUI Button vs ToggleButton vs custom prefabs.
• Images & Sprites — sprite atlas mode, dedup threshold, slicing rules.
• Text & Fonts — font family overrides, locale, TMP atlas resolution.
• Localisation — bind keys for Unity Localization or I2 Localization packages.
• Import Events — per-frame Pre/PostImport ScriptableObject callbacks.
• Prefab Creator — turn synced frames into prefabs automatically.
• Shadows — DropShadow / InnerShadow rendering quality, BG blur toggle.
• Debug — verbose logging, diagnostic reports, snapshot management.
• Codegen — emit per-frame C# reference classes alongside the synced GameObjects.

🔍 Diff & Re-sync

Re-sync without losing the work you did between syncs.

After every successful sync FigSync writes a hash snapshot of the node tree to Generated/_figsync_snapshot.json. On the next sync, the pipeline diffs the incoming nodes against that snapshot before any scene mutation. The result is a per-root summary of what would change.

The diff window

When there's at least one change, the diff window opens before DrawHierarchy:

• Per-root summary chips — +added ~modified −removed counts at the page level.
• Foldable groups — one per root frame, with per-node entries inside. Click to expand a group.
• Per-root Apply toggles — untick a root to defer it. Deferred roots aren't touched this sync; their previously-drawn GameObjects stay exactly as you left them.
• Continue / Cancel — Continue applies everything not deferred; Cancel aborts the sync with the scene unchanged.

What "preserve" means at the GameObject level

Three cases survive a re-sync identically:

First sync, no snapshot

The diff window is skipped on first sync — nothing to compare against. The pipeline writes a snapshot at the end. Every sync from the second onwards benefits from the diff path.

📐 Auto-Layout

Figma's auto-layout maps to UGUI LayoutGroup + ContentSizeFitter end-to-end.

A Figma frame with auto-layout becomes a Unity GameObject with the matching HorizontalLayoutGroup, VerticalLayoutGroup, or GridLayoutGroup, plus a ContentSizeFitter when the sizing mode is "Hug contents". Children flow in the same direction, with the same padding, gap, and primary/counter alignment.

What's wired

• Direction (Horizontal / Vertical / Grid) — chooses the LayoutGroup component.
• Padding & gap (the four sides + itemSpacing) — LayoutGroup padding + spacing.
• Primary alignment (Start / Center / End / Space Between) — LayoutGroup childAlignment; SPACE_BETWEEN uses injected invisible FigSyncLayoutSpacer children for the slack.
• Counter alignment — aligns the off-axis children to start/centre/end of the cross axis.
• Sizing (Fixed / Hug contents / Fill container) — combination of ContentSizeFitter + LayoutElement.
• ABSOLUTE children (a child of an auto-layout frame with "absolute position" toggled in Figma) get a LayoutElement.ignoreLayout so they keep their baked anchored position instead of flowing.

What's not wired

See the dedicated Known Limitations for the specifics:

• Auto-layout Wrap mode falls through to free-position layout.
• Grid with non-uniform tracks (per-cell column / row sizes) flattens to uniform cells.
• Constraints on flow children are intentionally ignored; the LayoutGroup owns placement.

🔗 Constraints (Anchors)

Figma per-axis constraints drive UGUI anchors so layouts respond to Canvas resize.

Every Figma child carries a per-axis constraint (Min / Max / Center / Stretch / Scale). FigSync maps them onto the child's anchorMin / anchorMax + offsetMin / offsetMax so the child reacts the right way when its parent rect changes size.

Re-sizing the root Canvas at runtime should re-flow the design exactly the way it would in Figma's preview.

🌈 Gradients

Four gradient kinds, rendered procedurally in one SDF shader.

FigSync renders Figma gradients on the GPU instead of baking them to a texture. Four kinds are supported: GRADIENT_LINEAR, GRADIENT_RADIAL, GRADIENT_ANGULAR, and GRADIENT_DIAMOND — the full set Figma can author. Multi-stop ramps up to 4 stops render natively; 5+ stop ramps collapse to first + last + two middle stops (see Known Limitations).

How gradients render

The same FigSync/RoundedCorner SDF shader that handles rounded corners also handles gradients. The two are composed at the fragment level: gradient sampled first, alpha multiplied by the corner SDF, output to screen. One Image + one Material per node, no extra draw call.

What's preserved

• Gradient handles — the start/end points (Linear), centre + radius (Radial), centre + rotation (Angular), centre + width/height (Diamond) are passed as material uniforms.
• Per-stop colours & alpha — encoded in the four-stop ramp uniform.
• Gradient on top of a stroke — works the same way; stroke renders at the SDF edge band.
• Gradient on a rotated rect — rotation is baked into the rect's local coords; the gradient stays aligned to Figma's intent.

◯ Rounded Corners

SDF rounded corners with per-corner radii, stroke band, drop shadow, inner shadow.

Nodes with a non-zero corner radius receive a FigSyncRoundedCorner runtime component (built on Unity's BaseMeshEffect). The component encodes the corner radii, stroke width, drop-shadow offset, and inner-shadow offset into the mesh's UV channels — one shader draws every effect against the SDF distance field, no extra GameObjects or quads.

What's encoded

• Per-corner radii — Figma's rectangleCornerRadii are read directly; uniform cornerRadius sets all four equal.
• Stroke band — stroke weight + alignment (Inside / Center / Outside) drives the SDF outline thickness.
• Drop shadow — up to four stacked drop shadows (Figma allows arbitrary; we render the first four). Offset, blur, spread, colour per layer.
• Inner shadow — up to four stacked inner shadows.
• Gradient fill — composed at the same fragment stage (see Gradients).

Why an SDF shader instead of PNG raster

SDF stays crisp at any scale — rounded buttons look right at 0.5x and 4x zoom alike. PNG raster would force a fixed-resolution bake that aliases under scale. The SDF path also unifies stroke + corner + shadow into a single draw call, so a screen with 50 rounded panels is 50 draw calls, not 200.

☀ Shadows & BackgroundBlur

Drop shadow, inner shadow, layer blur, and Figma's signature glass effect.

Drop & inner shadow

Up to four stacked drop shadows and four stacked inner shadows per node, all rendered against the same SDF. No extra GameObjects, no overlay quads — just additional uniforms on the shared material. Stacking is preserved: Figma's first shadow is the topmost layer.

Layer blur

A Figma LayerBlur effect on a leaf node renders procedurally by widening the SDF edge. On a node with children, the procedural path can't blur the descendants — FigSync routes the whole subtree to the PNG raster path where Figma bakes the blur server-side, then displays the result as a Unity sprite.

Background blur (the glass effect)

A Figma BackgroundBlur blurs whatever sits behind the consumer node — the iOS-style frosted-glass look. FigSync ships a procedural backdrop:

• A FigSyncBackgroundBlurCompositor snapshots the Canvas's Render Camera into a RenderTexture once per frame.
• Each consumer node samples that RT through a Gaussian blur kernel matching the radius from Figma.
• The consumer's own fill (a semi-transparent tint) composites over the blurred sample.

✏ Text & Fonts

TMP with automatic font download. Mixed inline styles. Locale-aware.

Text rendering

Every Figma TEXT node becomes a Unity TextMeshProUGUI. Size, alignment, line height, letter spacing, and colour map directly. Multi-line text wrap respects the bbox width; single-line bbox-height nodes get NoWrap so labels overflow horizontally instead of stacking.

Automatic font download

The DownloadFonts step resolves every font family used in the file through:

1. Your Google Fonts API key, if you've set one in Settings → Auth (returns TTFs from gstatic.com directly).
2. The public Google Fonts CSS endpoint as fallback.
3. The Fontsource CDN for variable fonts Google ships only as WOFF2.
4. The Adobe Edge font index for non-Google families.

Each resolved TTF is imported as a Unity Font and baked into a TMP _SDF.asset at Generated/Fonts/<Family>-<Weight>.asset. On subsequent syncs the baked asset is reused — no re-download.

Fonts that didn't resolve

For proprietary families (Whyte, Figma Hand, custom) or Google variable fonts that don't ship a TTF download path (Inter, Newsreader), the import surfaces a one-shot dialog at the end of the sync listing what to drop in. Save the TTFs to Assets/FigSync/Generated/Fonts/ using the convention <Family>-<weight>.ttf (e.g. Inter-400.ttf); the next sync auto-binds them to every matching text component.

Mixed inline styles

A single Figma text node can mix weights, italics, underlines, and strikethroughs per character. FigSync reads the per-segment styling and emits TMP rich-text tags (<b>, <i>, <u>, <s>) for the segments that diverge from the node-level base style. Cross-family inline segments keep their weight + italic but render in the base family asset (see Known Limitations for the TMP atlas reason).

🎨 Sprites & Atlases

Auto-classified, auto-deduped, auto-sliced.

Some nodes can't be drawn procedurally — complex vector icons, photo fills, baked illustrations. For those, FigSync pulls a PNG from Figma's /v1/images endpoint (or reads the pre-rendered PNG from the plugin bundle), saves it under Generated/<FolderName>/<NodeName>.png, and binds it as an Image.sprite.

How classification works

The ClassifyImages step decides per-node whether to route to the raster path:

• Photos & complex vectors — raster.
• Pure solid / gradient rectangles — procedural.
• Vector paths with simple fills — meshed via FigSyncVectorGraphic (triangulated on the CPU, drawn as a UGUI graphic).
• Nodes inside a baked parent — suppressed; the parent's PNG already contains them.

Dedup

The DedupeSprites step hashes every freshly-written PNG; duplicates (same pixel content) collapse to a single asset on disk with the other nodes pointing at it via reference. Cuts asset count and binary size sharply on screens with repeated iconography.

Slicing

The SliceSprites step looks for the manual sidecar convention — a node named BG/9slice or with a tag suffix — and writes 9-slice border data into the sprite asset's border field so UGUI Image rendering with type Sliced reuses the same texture across multiple sizes.

☀️ FigJam Support

Stickies, connectors, shape-with-text, and the signature dotted canvas.

FigJam files are first-class. The pipeline auto-detects FigJam at the editor level (the editorType field in meta.json, with a node-type heuristic fallback for older exports) and switches on FigJam-specific rendering paths.

What's rendered natively

• Sticky notes — baked from Figma's /v1/images PNG so the body + text + colour render as one sprite.
• Connectors (the no/yes/etc. arrows) — same path, baked PNG.
• Shape-with-text (Buy ice cream / Has ice cream? / etc.) — baked PNG with the inset text included.
• Sections — treated as plain frames.

The dotted canvas backdrop

FigJam's signature dotted-grid canvas isn't a Figma node — it's painted by FigJam itself behind whatever's on the page. Frames that look "white on left, dotted on right" actually have a transparent right half with the canvas dots showing through. FigSync detects FigJam files and injects a _FigJamCanvasDots Image as the lowest sibling under each page. The tile is 24×24 px, opaque, with a soft grey dot — matches FigJam's rendered look in side-by-side comparisons.

Inline icons over text

FigJam tutorial frames often place an icon (.key / ctrl / esc) over a run of whitespace inside a text node ("Press           and drag"). Figma renders the space narrow enough to fit the icon; TMP renders it wider and forces an early wrap. FigSync rewrites runs of 3+ consecutive spaces as <space=Npx> TMP tags so the line wraps where Figma intends it to.

🔧 Settings

One ScriptableObject. Safe to commit.

Settings live as a ScriptableObject at Assets/FigSync/FigSyncProjectSettings.asset. Edit through the Hub window's tab views, or select the asset and use the Inspector.

Tokens (Personal Access Token, OAuth refresh, Google Fonts API key) are stored separately in EditorPrefs with base64-XOR obfuscation. They never write to assets or version control.

⚠ Known Limitations

What FigSync doesn't fully render, why, and how to work around it.

This is the single source of truth for FigSync's known trade-offs. If you hit something not listed here, mail ragendom@gmail.com with a minimal repro.

💡 Troubleshooting

Common failure modes, what they mean, how to recover.

Sync errors

Common issues

Enable verbose logging when in doubt

Set Debug Verbosity = Verbose in Settings → Debug and re-sync. Every step logs its inputs, decisions, and counts to the Console with the [FigSync] prefix. The diagnostic report at Generated/_figsync_report.json also captures the full per-node decision trace.

❓ FAQ

Quick answers to the questions that come up most.

📬 Support

Need help? Reach out.