# Figma Font Loading Requirements Before Text Operations: Complete Plugin Guide

> Avoid Figma plugin errors. Learn essential font loading requirements using await figma loadFontAsync before text operations. Master this critical step for smooth plugin development.

- Repository: [Figma/mcp-server-guide](https://github.com/figma/mcp-server-guide)
- Tags: how-to-guide
- Published: 2026-03-30

---

**Every font must be explicitly loaded via `await figma.loadFontAsync({ family, style })` before reading or writing any text property in Figma plugins, or the script will throw a "font not loaded" runtime error.**

When developing Figma plugins using the `use_figma` skill in the **figma/mcp-server-guide** repository, understanding font loading requirements before text operations is essential for successful script execution. The Figma Plugin API operates within a **sandboxed JavaScript environment** that requires explicit font initialization prior to any text manipulation. Failing to adhere to these mandatory loading sequences results in invisible text, clipped layouts, and complete script failures.

## Why Font Loading Is Mandatory in the Figma Plugin Sandbox

The requirement to load fonts before text operations stems from four architectural constraints enforced by the Figma plugin runtime as documented in the MCP server guide.

1. **Sandboxed Runtime Isolation**: The plugin executes in a separate JavaScript sandbox that maintains its own memory space and cannot access the Figma editor's native font cache. According to the repository documentation, this isolation prevents automatic font availability.

2. **Asynchronous Font Acquisition**: Fonts may reside on local disks or remote servers, requiring asynchronous fetching. The `figma.loadFontAsync()` method returns a `Promise` that resolves only after the font data is fully available in the sandbox memory.

3. **Runtime Error Prevention**: Attempting to set `fontName`, `characters`, `fontSize`, or any glyph-dependent property without prior loading immediately throws the `"font not loaded"` error. As noted in [`skills/figma-use/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/SKILL.md) (Critical Rule #8, lines 28-30), this error halts the entire atomic script execution.

4. **Rendering Consistency**: Loaded fonts ensure accurate text measurements for line height, width calculations, and layout positioning, preventing visual glitches like clipped text lines or incorrect bounding boxes.

## The Four-Step Font Loading Workflow

The **figma/mcp-server-guide** repository establishes a strict workflow for font initialization before text operations. Following this sequence prevents runtime exceptions and ensures proper node creation.

1. **Collect Unique Font Descriptors**: Gather distinct `{ family, style }` objects for every font variant required by your script.

2. **Execute Parallel Loading**: Use `await Promise.all(fonts.map(f => figma.loadFontAsync(f)))` to load multiple fonts simultaneously, optimizing performance when handling multiple styles.

3. **Modify Text Properties Only After Await**: Create or modify **TextNode** and **TextStyle** objects only after the font loading Promise resolves.

4. **Return Node IDs**: Always return the created or mutated node IDs in the response object, as required by the `use_figma` skill specification.

## Code Implementation Patterns for Font Loading

### Creating a Simple Text Node

The most basic pattern requires loading the font before instantiating the text node. This follows the example in [`skills/figma-use/references/text-style-patterns.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/text-style-patterns.md) (lines 91-93) and enforces Critical Rule #8 from [`skills/figma-use/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/SKILL.md).

```javascript
// Load the font first
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' })

// Create the text node and set its content
const txt = figma.createText()
txt.characters = 'Hello, world!'
txt.fontSize = 24
txt.fontName = { family: 'Inter', style: 'Regular' }

// Position the node away from (0,0) to avoid overlap
txt.x = 100
txt.y = 50

return { createdNodeIds: [txt.id] }

```

### Bulk Loading for Multiple Styles

When working with design systems or multiple text styles, deduplicate font descriptors and load them in parallel. This pattern appears in [`skills/figma-generate-library/references/token-creation.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/references/token-creation.md) (line 699) and [`skills/figma-use/references/common-patterns.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/common-patterns.md).

```javascript
// Define all fonts you will need
const fontSet = new Set()
fontSet.add(JSON.stringify({ family: 'Inter', style: 'Bold' }))
fontSet.add(JSON.stringify({ family: 'Inter', style: 'Medium' }))

// Load them in parallel
await Promise.all(
  [...fontSet].map(f => figma.loadFontAsync(JSON.parse(f)))
)

// Now safely create several styled text nodes
const headings = [
  { text: 'Title',    size: 32, font: { family: 'Inter', style: 'Bold' } },
  { text: 'Subtitle', size: 24, font: { family: 'Inter', style: 'Medium' } },
]

return { createdNodeIds: headings.map(item => {
  const node = figma.createText()
  node.fontName = item.font
  node.fontSize = item.size
  node.characters = item.text
  node.x = 100
  node.y = 50 + 60 * headings.indexOf(item)
  return node.id
})}

```

### Updating Existing Text Styles

When modifying existing **TextStyle** objects, you must load the font even if it was previously used elsewhere. The [`skills/figma-use/references/working-with-design-systems/wwds-text-styles.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/working-with-design-systems/wwds-text-styles.md) (lines 79-80) explicitly requires this for any `fontName` modification.

```javascript
// Assume you already have a TextStyle object `style`
await figma.loadFontAsync(style.fontName) // must load before modification

style.fontSize = 18
style.lineHeight = { unit: 'PIXELS', value: 24 }

// Return the updated style ID
return { mutatedNodeIds: [style.id] }

```

## Common Pitfalls and Solutions

| Pitfall | Symptom | Fix |
|---------|---------|-----|
| **Omitted `await` on `loadFontAsync`** | Script proceeds, then throws "font not loaded" | Always `await` the Promise; see SKILL rule #17 in [`skills/figma-use/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/SKILL.md) |
| **Incorrect Style String** (e.g., `"SemiBold"` vs `"Semi Bold"`) | `loadFontAsync` rejects with error | Probe with `try/catch` or use `figma.listAvailableFontsAsync()` to discover exact style names as noted in [`wwds-text-styles.md`](https://github.com/figma/mcp-server-guide/blob/main/wwds-text-styles.md) (line 80) |
| **Loading Fonts in Tight Loops** | Unnecessary promises, slower execution | Deduplicate first using a `Set` of JSON-stringified descriptors before mapping to load calls |
| **Setting `fontName` Before Loading** | Immediate runtime error on property assignment | Load **before** any property assignment; the rule is enforced by the plugin sandbox per [`plugin-api-standalone.d.ts`](https://github.com/figma/mcp-server-guide/blob/main/plugin-api-standalone.d.ts) (line 1585) |
| **Forgetting to Return IDs** | Subsequent steps cannot reference created nodes | Follow SKILL checklist item "MUST return ALL created/mutated node IDs" |

## Key Repository Files for Font Management

The **figma/mcp-server-guide** repository contains authoritative documentation for font handling across these specific files:

- **[`skills/figma-use/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/SKILL.md)**: Contains Critical Rule #8 (lines 28-30) mandating font loading before text operations
- **[`skills/figma-use/references/working-with-design-systems/wwds-text-styles.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/working-with-design-systems/wwds-text-styles.md)**: Provides detailed guidance on loading fonts before creating or modifying **TextStyle** objects (lines 79-80)
- **[`skills/figma-use/references/text-style-patterns.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/text-style-patterns.md)**: Demonstrates practical implementation patterns with `loadFontAsync` calls (lines 91-93)
- **[`skills/figma-use/references/plugin-api-standalone.index.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/plugin-api-standalone.index.md)**: Lists `loadFontAsync` as a required precondition for text edits (line 77)
- **[`skills/figma-use/references/plugin-api-standalone.d.ts`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/plugin-api-standalone.d.ts)**: Contains TypeScript definitions and method signatures with documentation comments (line 1585)
- **[`skills/figma-generate-library/references/token-creation.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/references/token-creation.md)**: Shows bulk-loading patterns for design token generation workflows (line 699)
- **[`skills/figma-use/references/common-patterns.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/common-patterns.md)**: Provides reusable loading snippets for common plugin scenarios

## Summary

- **Font loading is mandatory**: Every script must call `await figma.loadFontAsync({ family, style })` before accessing any text properties.
- **Load before create**: Always initialize fonts prior to calling `figma.createText()` or modifying `fontName` on existing nodes.
- **Parallelize for performance**: Use `Promise.all()` with deduplicated font sets when handling multiple styles.
- **Return node IDs**: Always return created or mutated node IDs to satisfy the `use_figma` skill contract.
- **Reference authoritative sources**: Follow the specific file paths and line references in [`skills/figma-use/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/SKILL.md) and related documentation.

## Frequently Asked Questions

### What happens if I skip font loading before setting text properties?

The Figma plugin sandbox immediately throws a `"font not loaded"` runtime error that halts the entire script execution. According to the source code in [`skills/figma-use/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/SKILL.md), this is Critical Rule #8 because the sandboxed runtime cannot access the editor's font cache without explicit asynchronous loading.

### Can I load multiple fonts simultaneously in Figma plugins?

Yes. The `figma.loadFontAsync()` method returns a Promise, allowing you to use `Promise.all()` to load multiple font families and styles in parallel. The repository recommends deduplicating your font descriptors first (using a `Set` of JSON-stringified objects) to avoid redundant loading operations, as shown in [`skills/figma-generate-library/references/token-creation.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/references/token-creation.md).

### How do I find the correct style string for a font family?

Use `figma.listAvailableFontsAsync()` to retrieve the exact style names available for each font family. As documented in [`skills/figma-use/references/working-with-design-systems/wwds-text-styles.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/working-with-design-systems/wwds-text-styles.md) (line 80), style names must match exactly (e.g., `"Semi Bold"` versus `"SemiBold"`), and this API call reveals the correct formatting for the `style` parameter in `loadFontAsync()`.

### Do I need to reload fonts for every plugin execution?

Yes. Because the plugin runs in a sandboxed environment that does not persist state between executions, you must call `figma.loadFontAsync()` every time your script runs, even for fonts that were loaded in previous executions. The font cache is isolated per script invocation according to the architectural constraints described in the repository documentation.