/figma-swiftui

SwiftUI → Figma (code → design)

Translate SwiftUI source code into a Figma design using use_figma. This doc covers the SwiftUI-specific translation knowledge; the API-level rules for use_figma itself live in figma-use, the screen-assembly workflow lives in figma-generate-design, and the component / variant / variable workflow lives in figma-generate-library. Load whichever of those match the scope of the request, and use this doc to drive the SwiftUI semantic interpretation of the source.

Assumes the shared context in SKILL.md is loaded.

1. Decide the scope first

What is actually being pushed into Figma? The scope decides which companion skill to load.

If the scope is unclear from the prompt, ask before writing — building a component set when the user wanted a screen frame (or vice versa) is expensive to undo.

2. Discover before creating

Before writing any use_figma script, run the discovery the figma-use and figma-generate-design skills already require — but with SwiftUI-shaped expectations:

• Existing variables. Does the file already have a semantic color collection with iOS-flavored names (label/primary, background/secondary, separator/non-opaque)? Use it. If not, the names from Apple's HIG (see §4) are reasonable defaults.
• Existing components. Search via search_design_system for the SwiftUI controls you're about to translate — Button, Toggle, Slider, Picker (Segmented), NavigationBar, TabBar, etc. Most design systems already have these; rebuilding produces duplicates.
• Apple's official design libraries. Apple publishes per-OS Figma libraries as Community libraries — iOS 18 and iPadOS 18, iOS and iPadOS 26, watchOS 26, visionOS 26. Many files don't have them subscribed yet, but they're available to add. Call get_libraries and check libraries_added_to_file first, then libraries_available_to_add (Apple's libraries show up with source: "community"). Once you have the library's libraryKey, scope every subsequent search_design_system call with includeLibraryKeys: [appleLibraryKey] so you only match Apple's authored components instead of every other library the file has ever subscribed. Naming is stable across these libraries — Navigation Bar - iPhone (Compact Size Class), Status Bar - iPhone, Tab Bar - iPhone, Row, Button, Segmented Control, Stepper — so queries can be specific. Prefer the matching library over hand-rolling SF-Symbol-and-rectangle approximations.
• Code Connect mappings. If the project already has figma-code-connect templates pointing the existing Figma components at SwiftUI source (or vice versa), follow them — don't generate parallel components. See figma-code-connect.
• Device frame conventions. Apple's Figma libraries ship Product Bezels components — the physical hardware shell around the screen, sized to match real device dimensions (iPhone 16: 393 × 852, iPhone 16 Pro: 402 × 874, iPad models likewise). Search search_design_system for Product Bezels and drop the matching bezel as the outer wrapper rather than drawing your own. The screen frame nested inside the bezel must match the width of the chrome components from the same library — Nav Bar, Tab Bar, Status Bar are authored at the same width as the bezel they belong to. Sizing the screen at 393 and dropping in a 402-wide nav bar produces a misaligned design. This pixel-width discipline applies only to the outer screen frame and the chrome components — inner content still uses auto-layout (FILL/HUG) and Figma's responsive constraints, not absolute x/y positioning. SwiftUI's layout is relative, and the Figma representation should be too inside the screen.

3. Map SwiftUI structure to Figma structure

The SwiftUI source already encodes intent — translate the system semantics, not the rendered pixels.

Reach for built-in design-system components first — every SwiftUI control above has a Figma equivalent in most libraries. Custom shapes only when the design genuinely deviates from a system control.

4. Map system colors to Figma variables

When the SwiftUI source uses HIG semantic colors, bind to (or create) Figma variables with the matching semantics. Never paste a hex.

If the source uses a project-specific token (Color.brandPrimary, Color("AccentColor")), look for the matching semantic variable in Figma before creating a new one. When creating variables, follow figma-generate-library — set scopes explicitly (FRAME_FILL, SHAPE_FILL for backgrounds, TEXT_FILL for labels, STROKE_COLOR for separators); never leave ALL_SCOPES.

Dark mode: model both modes on the same variable collection. If the SwiftUI source distinguishes via .preferredColorScheme(.dark) or different literal colors per scheme, model both modes; otherwise the system-color mapping inherits dark mode for free.

5. SF Symbols → Figma glyphs

Image(systemName: "gear") in SwiftUI becomes a text node in Figma whose character is set via figma.util.getSfSymbolCharacter(name) — a use_figma helper that takes the SF Symbol name and returns the matching character string. Never hand-look up codepoints, never paste literal \u{…} escapes into your script.

await figma.loadFontAsync({ family: "SF Pro", style: "Regular" })
const icon = figma.createText()
icon.fontName = { family: "SF Pro", style: "Regular" }
icon.fontSize = 17
icon.characters = figma.util.getSfSymbolCharacter("square.and.arrow.up")
// bind icon.fills to a label/* variable so the glyph tints with surrounding text

The helper throws RangeError when the name is unknown — if that happens, surface the gap to the user; do not silently fall back to a different glyph or paste a guessed codepoint.

Fall back to uploading a PNG / SVG via upload_assets only when the symbol's tint must be independent of the surrounding label color (a colored brand glyph, a multicolor variant), or when the target file pre-dates SF Symbol support.

For long-term linkage, set up a Code Connect mapping pointing a Figma "Icon" component (with an INSTANCE_SWAP property for each symbol) at the SwiftUI source's Image(systemName: …) — see figma-code-connect. The next design → code task on this file will then return SwiftUI directly.

6. Typography

SwiftUI maps to a small set of named text styles. Mirror them as Figma text styles, not as raw font properties on each text node.

The SF Pro family is system-resident in iOS, so the Figma file needs SF Pro (and SF Pro Rounded) loaded — verify via await figma.listAvailableFontsAsync() before writing text. If only Inter is available, ask the user before substituting; Inter's metrics diverge enough that text-overflow bugs surface after translation.

When the SwiftUI source specifies a custom font (.custom("Foo-Bold", …) or Font.custom("Foo", …)):

1. Look up the exact family/style via await figma.listAvailableFontsAsync() before any text write — the Postscript name in .custom(_) (e.g. Foo-Bold) does NOT always match the Figma family + style pair (commonly Foo family + Bold style). Pick the matching pair from the available-fonts list.
2. If the font is missing from the file, stop and surface the gap to the user. Custom fonts have to be uploaded to the Figma team / org before the file can use them; substituting SF Pro silently produces a misleading design.
3. Mirror each distinct .font(.custom(_)) call as its own named Figma text style (e.g. Brand/Display Bold 17) rather than as inline overrides on individual text nodes — consistent with the §6 rule that named styles beat raw font properties.

7. Modifier translation (only what's worth materializing)

Many SwiftUI modifiers should not survive translation as visual nodes — they're runtime concerns. Translate the visual ones, capture the design-intent ones as annotations, drop the purely-runtime ones, and model state as variants.

Translate (visual). .padding(_), .frame(width:height:), .cornerRadius(_), .background(_), .foregroundStyle(_), .font(_), .fontWeight(_), .shadow(_), .opacity(_), .overlay(_), .clipShape(_), .border(_). .glassEffect() → a Figma material effect (if the library has one), otherwise a frame with a .regularMaterial-style blur effect style.

Capture as a Figma annotation. Modifiers that carry design-relevant intent but have no visual representation become annotations on the node, categorized so the next design → code task can recover them. Use a category that matches the modifier's role:

Annotations are the catch-all for "the view had behavior X that the static design can't show, but design → code on the next pass needs to know about." Prefer a small number of clear categories (Accessibility, Layout, Behavior, …) over free-form notes.

Drop (purely runtime, no design intent). .onTapGesture { … }, .onAppear { … }, .task { … }, .environment(_), .preferredColorScheme(_) (model as a mode on the variable collection, not a property on the node), .animation(_, value:) (motion is not a static visual property — capture it via Code Connect, not on the static node).

Translate carefully (model as a variant, not a property). .disabled(_) is a state — model it as a component variant (State=Disabled), not as a top-level property of the instance. Same goes for .isHidden(_), hover/pressed states, etc.

8. Loop back via Code Connect

Once the Figma component exists and the SwiftUI source is in the repo, set up a Code Connect mapping so the design and the code stay linked. See figma-code-connect for the workflow. The mapping is what makes the next design → code task on the same file return correct SwiftUI snippets instead of generic React+Tailwind.

Limit Code Connect to your project's custom components. System SwiftUI controls (Button, Toggle, Slider, Picker, Stepper, DatePicker, ProgressView, TextField, Label, NavigationStack, TabView, List, Form, Section, etc.) already have first-party mappings shipped with the design context tool — overriding them with a project-local Code Connect template makes the design → code output worse, not better. If a SwiftUI source uses one of these, leave it to the built-in mapping and only Code Connect the custom wrappers around it.

9. What NOT to translate

These show up in SwiftUI sources but should be omitted or simplified when building the Figma design:

• Preview providers — #Preview { … } (iOS 17+ macro form) and the older struct ContentView_Previews: PreviewProvider { … } { static var previews: some View { … } } form (which is still everywhere in older codebases). Both are Xcode-only scaffolding with no Figma equivalent.
• State plumbing (@State, @Binding, @Observable, @AppStorage) — model the on-screen values (the rendered string, the selected enum case), not the binding itself.
• Conditional rendering (if isLoading { ProgressView() } else { … }) — render one state in the primary frame, model the others as variants or separate frames.
• GeometryReader / PreferenceKey plumbing — these solve responsive-layout problems that Figma's auto-layout solves natively. Don't materialize them as nodes.
• @ViewBuilder helper functions — inline the result at the call site in the Figma representation; don't mirror the function structure as nested frames.
• .task / .refreshable / .searchable data-loading hooks — model the resulting screen state (loaded, empty, loading spinner) as separate variants, not the hooks themselves.

Output

Per figma-use, every use_figma script must return all created/mutated node IDs and follow the incremental workflow (skeleton first, then fill, validate with get_metadata / screenshots between steps). For SwiftUI → Figma specifically:

1. Inspect first. Does the file already have the variables, text styles, and components implied by the SwiftUI source? Match what is there.
2. Tokens before components. If you are creating variables (per §4), do it before building any view that binds to them.
3. Components before screens. Translate each SwiftUI view into a Figma component before composing a screen from instances. Don't inline.
4. One screen at a time. Even for multi-screen flows, build one screen, take a screenshot, get sign-off, then move on. The same checkpoint discipline from figma-generate-design and figma-generate-library applies.