Complete Guide
Everything the UI Anatomy Importer does: how to install it, what it builds, every setting, step-by-step examples, and how to fix the common problems. For the short version see the Guide.
1. Installation
Download and import
- Download the
.unitypackageabove. - In Unity, choose Assets > Import Package > Custom Package... and pick the file.
- Leave everything ticked and press Import. The importer installs to
Assets/UIAnatomyImporter/: anEditorfolder (the importer, its window and settings) and aRuntimefolder (three small components your screens use). - Wait for Unity to compile. A new menu appears: Tools > UI Anatomy.
Requirements: Unity 6 (6000.0 or newer) with the uGUI package, which includes TextMeshPro. Nothing else.
Other ways to install. Every .zip exported from the web app carries the same importer in unity/com.uianatomy.importer. Copy that folder into your project's Packages/ folder to install it as a Package Manager package instead. Use one way or the other, not both.
First-time setup
- TextMeshPro resources. A brand-new project has no TextMeshPro font or shaders. The importer brings in the TMP Essential Resources by itself the first time. If it tells you they are still being imported, run the import once more.
- Settings asset. The first import creates
Assets/UIAnatomy/UIAnatomyImportSettings.asset. Open it from Tools > UI Anatomy > Settings, or edit it inside the import window. - Fonts. For the right look, the fonts used in the design should be installed on your computer or present in the project. See Fonts.
- Sprite atlas. To have the generated atlas packed, turn on Project Settings > Editor > Sprite Packer > Mode.
2. What the importer builds
One import turns one exported screen into these, under <Output Folder>/<ScreenName>/:
| Result | What it is |
|---|---|
| Screen prefab | The whole screen as a uGUI hierarchy: RectTransforms with anchors, layout groups, scroll views, masks, images and TextMeshPro texts, at the positions measured in the design. |
| Template prefabs | One prefab per repeated item (a card, a row, a tab) in Prefabs/. Other copies on the screen are instances of it, with their differences stored as overrides. |
| Sprites | Sprites/: every image, imported as a sprite with its 9-slice border, pixels per unit and a full-rect mesh. |
| Text materials | Materials/: one TextMeshPro material per text style that has an outline or a shadow. |
| Font assets | <Output Folder>/Fonts/: TextMeshPro font assets made for design fonts that the project did not have yet. |
| Sprite atlas | The small interface sprites of the screen, in one atlas. Photos and sample pictures of runtime content stay out. |
| Bindings | A UIAnatomyBindings component on the screen root that lists every field meant to be filled from data, by name. |
| Selection states | A ToggleGroup where the design shows one selected item among copies (tabs), with a component that switches the selected look. |
| Report | import-report.json: how many objects land within 1 unit of the design, how closely the rendered picture matches, what was reused and created, and warnings. |
What it deliberately does not do: it writes no game logic, and it never changes or deletes assets outside the screen's own output folder.
3. Every setting
Settings live in one asset and are remembered between sessions. Change them in the import window or through Tools > UI Anatomy > Settings. To use different rules for different screens, duplicate the asset and pick the copy in the import window.
Output
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Output Folder | Assets/UIAnatomy | The folder that receives one sub-folder per screen. | Your project keeps UI somewhere else, for example Assets/Game/UI. |
| Prefab Prefix | empty | Text added in front of every prefab file name. | Your naming rule needs it, for example UI_. |
| Prefab Suffix | empty | Text added after every prefab file name. | For example View, to get UI_ShopView.prefab. |
Objects
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Strip Copy Numbers | Off | Copies are named Card (2), Card (3). On: they are all named Card. | You find or address children by name and want identical names. |
| Layer | 5 (UI) | The layer given to every created object. | Your UI camera renders a different layer. |
| Build Skipped Objects | Off | Objects the plan marks as not part of the screen (the screen behind a popup) are left out. On: they are built anyway. | You want the background of a popup as a visual reference. |
Prefabs
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Save Template Prefabs | On | Saves one prefab per repeated template. | Off if you only want the single screen prefab. |
| Link Copies To Prefabs | On | Builds the other copies as instances of the template prefab. Copies whose structure differs stay plain objects. | Off if you want a screen with no prefab links, for example to edit copies freely. |
| Add Bindings | On | Adds the UIAnatomyBindings component. | Off if you wire references yourself. |
| Add Selection States | On | Adds ToggleGroups, Toggles and the component that switches the selected look. | Off if you handle tabs and selection with your own system. |
Check
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Compare With Design | On | After building, renders the screen, compares it with the design picture and lists the objects that look most different. | Off to make large imports a little faster, once a screen is known to be right. |
Sprites
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Sprite Compression | Uncompressed | The compression set on imported sprites. | Choose a compressed setting for shipping builds if your atlas settings do not already do it. |
| Sprite Max Size | 4096 | The largest texture size Unity keeps. | Lower it to cap memory on low-end devices. |
| Sprite Filter | Bilinear | The filter mode of imported sprites. | Point for pixel art. |
| Create Sprite Atlas | On | Creates one atlas with the screen's small interface sprites. | Off if you manage atlases yourself. |
Match the design picture
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Match Design Blending | On | Design tools blend see-through colours in sRGB. A Unity project in Linear colour space blends them in linear light, so a dark see-through panel comes out much lighter. With this on, the importer corrects the transparency of the sprites it brings in (and of text and shadow colours) so the screen looks like the design. Exact for black and white, close for other colours. It does nothing in a Gamma project. | Off if your project already corrects UI blending itself (a custom UI shader or an sRGB UI render target). |
| Bake Background Blur | On | uGUI cannot blur what is behind an object. Where the design has a full-screen "background blur" layer, the importer renders everything beneath that layer once, blurs the picture and puts it in as one image called BlurredBackdrop, right under the layer. The blur fades out where the layer's fill fades to transparent, as it does in the design tool. Small blurred panels are not baked. | Off if the background behind the blur moves or changes at run time, or if you use your own blur effect. Import again after changing what lies beneath. |
Two more things are done without a setting. A grey layer in "saturation" or "colour" blend mode (a greyed-out portrait) becomes a greyscale material on the pictures beneath it, using the shader UIAnatomy/Grayscale that ships with the importer. Text auto size is kept only where the design's own text fits at full size; where the design lets text overflow its box, the text keeps its size instead of shrinking.
Progress bars and rings
Anything in the design that shows an amount is built the way it is built by hand in Unity: a track underneath and one Filled image on top, with the fill method that fits the shape. The object that holds them gets a UIAnatomyProgress component.
| In the design | How it is recognised | What is built |
|---|---|---|
| A ring or pie (timer, cooldown) | An ellipse drawn as part of a circle. The start angle, the sweep and the ring thickness are read from the design file. | The background as it is, plus a Fill image: the whole ring, Filled, Radial 360, starting where the design starts and turning the same way. |
| A bar drawn as a "filled" piece beside an "empty" piece | The plan marks the object as a progress bar; the two pieces are found by where they sit. | The track under the whole bar and the fill over the whole bar, Filled, Horizontal or Vertical. |
| A bar drawn as one shape whose gradient stops abruptly | Two gradient stops at the same place followed by one flat colour. | The shape in the flat colour as the track, and a Fill image carrying the gradient. |
The fill amount starts at what the design shows, so the imported screen looks like the design. Gradients are placed so that this is exact at that amount. From code: GetComponent<UIAnatomyProgress>().Value = 0.4f; (0 is empty, 1 is full); onValueChanged fires when it changes. Rows of separate pips or stars are left as separate objects.
Reuse what the project already has
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Find Existing Font | On | For each design font, looks in the whole project for a TextMeshPro font asset with the same family and the same style (weight) and uses it. The log says which asset was used. If none matches, a new font asset is made from a font file in the project or a font installed on the computer. Off: a new font asset is always made, even when a matching one exists. | Off when you want this screen's fonts kept separate from the rest of the project, or to regenerate font assets on purpose. |
| Auto Dedup Assets | On | Before copying an image in, looks in the project for a file with identical content (compared by content hash, not by name) that is imported with the same sprite settings: single sprite, same border, same pixels per unit. If found, the screen uses that existing asset and no copy is created. Assets you already had are never deleted or changed. The log ends with how many assets were reused and how many were created. | Off when each screen must be self-contained, for example to move or delete one screen's folder without affecting others. |
Text
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Fallback Font | none | The font asset used when a design font cannot be found or made. With none set, TextMeshPro's default font is used. | Set your game's main font so missing fonts still look close. |
| Fonts | empty | A table that maps a design font name (Transducer Bold, or just the family Transducer) to one of your font assets. It is checked before anything else. | Your font assets are named differently from the design fonts, or you want to substitute a font. |
| Create Text Materials | On | Creates one material per text style for outlines and shadows. | Off if you assign your own material presets. |
Canvas
These apply only when the screen is placed in the open scene.
| Setting | Default | What it does | When to change it |
|---|---|---|---|
| Place In Scene | Off | After importing, puts the screen under a new Canvas in the open scene. The Place in scene button in the window does the same on demand. | On if you always want to see the result in the scene straight away. |
| Render Mode | Screen Space Overlay | The Canvas render mode. | Screen Space Camera if your UI needs a camera (post-processing, 3D objects in the UI). |
| Scaler From Package | On | Uses the Canvas Scaler setting chosen in the web app. | Off to set the match value yourself. |
| Match Width Or Height | 0 | The match value used when Scaler From Package is off (0 = width, 1 = height). | Together with the option above. |
| Vertex Color Always Gamma Space | On | Keeps UI colours in gamma space. The package's colours are sRGB values. | Leave on in a Linear colour space project. |
4. Worked examples
One screen, from design to prefab
- In the web app, open the screen and press Export for Unity, then Download .zip. Export from the app (not the command line) so vector artwork arrives as PNG.
- In Unity, open Tools > UI Anatomy > Import....
- Drop the
.zipon the window. You do not need to unzip it. - Press Import.
- Read the result: it should say all objects land within 1 unit of the design, and show how closely the picture matches.
- Press Select prefab to find it in the Project window, or Place in scene to see it under a Canvas.
Several screens that share sprites
- In the web app, tick two or more screens on the home page and choose Export together.
- Drop that
.zipon the import window and press Import. Each screen is imported in turn. - With Auto Dedup Assets on, sprites the screens share are stored once. The result line for each screen says how many assets it reused.
Importing a screen again after the design changed
- Export the screen again and import the new
.zipwith the same settings. - The importer builds the new version aside and brings only the changes into the prefabs you have. Components, scripts, child objects and references you added stay. The prefabs and the objects in them keep their ids, so scenes and other prefabs that point into them keep working.
- The window lists what was added, changed and removed. Undo this update puts the prefabs back as they were; Keep this update accepts it.
| Case | What happens |
|---|---|
| The design changed a value, you did not | The new value is written. |
| You changed a value, the design did not | Your value stays. |
| Both changed the same value | When Both Changed decides: Keep Mine (default) or Take Design. The window lists every such value. |
| The design removed an object you never touched | It is deleted. |
| The design removed an object that carries your work | It is kept and switched off, and the window says why (you added a component, changed it, put objects in it, or a component of yours points at it). |
| The design added an object | It is created where the design puts it. |
<Screen>.import-base.bytes; commit it with the prefab). An object is found by its key, not by its name or place, so renaming or moving objects is safe. A screen imported with an importer older than 0.7 has no record: its first import with this version replaces the prefabs once, and updates work from then on. To always replace, set When Screen Exists to Replace.Using your own prefabs, folders and atlas
- Your prefabs. In the import window, open Use your own prefabs, list the components of the package and drop a prefab of yours on any of them. That component is then placed as an instance of your prefab, at the design's position and size; nothing inside it is rebuilt. Texts and pictures are filled in where a child of your prefab has the same name as that part in the design.
- Your folders. Sprites Folder, Prefabs Folder and Materials Folder say where new files go (
{screen}stands for the screen name); empty keeps them inside the screen's own folder. Sprite Name sets the file name, for exampleui_{screen}_{name}. - Your atlas. Add To Atlas puts the new UI sprites into a Sprite Atlas of yours instead of creating one per screen.
- Where to look. Search In lists the folders searched for existing sprites and fonts. Empty means the whole project.
Getting the fonts right
- Import once and read the warnings. A line such as font not in the project, a stand-in was used: Transducer Bold names each missing font.
- Give the importer that font in one of three ways:
- install the font on your computer, or copy its
.ttfor.otfinto the project; the importer then makes a font asset for it; - or create the TextMeshPro font asset yourself and name it after the font (
Transducer Bold SDF); - or map the design font to any font asset in the settings' Fonts table.
- install the font on your computer, or copy its
- Import again. With Find Existing Font on, the log now says using the existing font asset ... for each one.
If a warning says an outline or shadow is wider than the atlas padding allows, create that font asset with more padding (Font Asset Creator, Padding 12 or more for thick outlines).
Trying the screen in the browser first (Unity Preview)
Open a built screen in the app and choose Unity Preview. A Unity player in the page builds the screen with the importer's own code, so what you see is what the import produces, before you download anything.
- Play lets you use the screen like the game: click buttons and tabs, drag and scroll lists. Inspect selects the object you click.
- Device and Canvas Scaler change the screen size, orientation, safe area and scaling at once. The Canvas Scaler setting is the one the export uses.
- Fonts. The package carries no font files, so text shows in a stand-in font and is marked Substituted until you upload the
.ttfor.otffiles the design uses. Uploaded fonts are shared by everyone signed in.
The preview builds the screen from the design alone. Your own prefabs, font assets, reused sprites and the sprite atlas apply when you import the package into your project. A background blur is baked by the importer in Unity and is not shown in the preview.
Filling the screen from code
The texts and pictures in the prefab are sample data from the design. The bindings component lists every field that should come from your game.
using TMPro;
using UIAnatomy;
using UnityEngine;
using UnityEngine.UI;
public class OperativeScreen : MonoBehaviour
{
void Start()
{
var fields = GetComponent<UIAnatomyBindings>();
fields.Find<TMP_Text>("OperativeName").text = "Gus Erickson";
fields.Find<Image>("XpBar").fillAmount = 0.75f;
foreach (var entry in fields.entries)
Debug.Log($"{entry.key} ({entry.kind})"); // list every field
}
}
Kinds: text and image are filled directly, value drives an amount such as a bar, state switches a look, list is filled with copies of a template prefab.
Importing from the command line
Unity -batchmode -quit -projectPath <project> \
-executeMethod UIAnatomy.Importer.ImportFromArgs \
-uiaPackage <zip or folder> [-uiaShot <picture.png>]
It uses the project's settings asset and writes the same report. From an editor script, call UIAnatomy.Importer.ImportAny(path, settings).
5. Reading the report
import-report.json sits next to the screen prefab.
| Field | Meaning |
|---|---|
| within1 / measured | Objects whose position and size are within 1 canvas unit of the design. These should be equal. |
| visual.match | How close the rendered picture is to the design picture, in percent. Missing fonts, parts left out on purpose and background blur lower it. |
| visual.worst | The objects that look most different, with their position. Start here when something looks wrong. |
| reuse | Assets and fonts reused and created, with one line each. |
| copiesLinkedToPrefabs | Copies that became prefab instances, and how many stayed plain. |
| warnings | Things to look at: missing fonts, a dropdown without options, a disabled Sprite Packer. |
| off | Any object more than 1 unit off, with what it got and what the design wanted. |
The rendered picture and a difference picture are kept in the project's Library/UIAnatomyImport/check-<ScreenName>/ folder; the window's Show the difference picture button opens it.
6. Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "Missing signature" when importing the .unitypackage | Recent Unity versions check every package for a publisher signature. | Download the current file from this site; official builds are signed. For a build you made yourself, press Import Anyway. |
| "screen.json is not format ui-anatomy/unity-screen@2" | The .zip was exported by an older version of the web app. | Export the screen again. |
| "not an image Unity can use as a sprite" | The .zip contains SVG files. That happens when it was made from the command line. | Export with the Download button in the web app; it draws vectors as PNG. |
| "font not in the project, a stand-in was used" | No font asset, font file or installed font matches that design font. | See Getting the fonts right. |
| "the outline or shadow is wider than the atlas padding" | The font asset's atlas has too little padding for that outline. | Recreate the font asset with more padding. |
| Translucent panels look lighter than the design | The project uses Linear colour space and Match Design Blending is off, or the panel sits on a small background blur, which is not built. | Turn Match Design Blending on and import again. See Match the design picture. |
| Checks says "The design changed in Figma: N layers are gone" | The Figma file was edited after the screen was analyzed. The plan still describes the old layers, and Figma can no longer export the ones that were removed. | Analyze the screen again from the same link, then build and export. Until then those layers are left out. |
| The background behind a blur does not follow the scene | A full-screen blur was baked into one picture at import time. | Import again after changing the background, or turn Bake Background Blur off and use your own blur. |
| "Shader UIAnatomy/Grayscale was not found" | The importer's Runtime folder is incomplete. | Install the importer package again. |
| "the sprite atlas was created, but Sprite Packer is disabled" | Packing is switched off in the project. | Project Settings > Editor > Sprite Packer > Mode. |
| "dropdown built as a Button" | A dropdown needs a list of options, which a design does not contain. | Replace it with your dropdown, or add a TMP_Dropdown and its template. |
| Some copies are not prefab instances | Their structure differs from the template (a card with an extra badge). | Nothing is wrong. They are built as plain objects and look right. |
| "TextMeshPro's Essential Resources are being imported" | First import in a new project. | Run the import again. |
| A reused sprite disappears from a screen | With Auto Dedup on, it lived in another screen's folder that was deleted. | Import the screen again, or turn Auto Dedup off for self-contained screens. |
| The Tools > UI Anatomy menu is missing | The package did not compile, usually because another script in the project has an error. | Fix the errors in the Console; the menu appears once the project compiles. |
7. Known limits
- Background blur and inner shadows are not built. Hard drop shadows, gradients and soft flat shapes are drawn into sprites.
- Pressed and disabled states of buttons are not read from the design yet. Selected states of tabs are.
- A dropdown is built as a button that shows its sample value.
- Screenshots. A screen analyzed from an image, not a Figma frame, has a plan but no package, so there is nothing to import.
- Unity 6 only. The importer uses Unity 6 APIs.