1# Working with design systems: Text Styles
2 
3Text styles in Figma are named, reusable typography definitions. They are the closest equivalent to a type ramp in a design token library. A text style bundles font family, size, weight, line height, letter spacing, and other typographic properties into a single named entity that can be applied to text nodes.
4 
5Text styles are distinct from variables. You cannot put typography into a single variable — there is no composite variable type. However, individual properties on a text style _can_ be bound to variables (e.g. binding `fontSize` to a size variable, or `fontFamily` to a string variable), which allows the style to participate in a token system.
6 
7## Model
8 
9A `TextStyle` has the following writable properties:
10 
11| Property           | Type             | Notes                                                                        |
12| ------------------ | ---------------- | ---------------------------------------------------------------------------- |
13| `name`             | `string`         | Slash-delimited for grouping (e.g. `"Heading/XL"`)                           |
14| `fontSize`         | `number`         | In pixels                                                                    |
15| `fontName`         | `FontName`       | `{ family: string, style: string }` — **font must be loaded before setting** |
16| `letterSpacing`    | `LetterSpacing`  | `{ value: number, unit: 'PIXELS' \| 'PERCENT' }`                             |
17| `lineHeight`       | `LineHeight`     | `{ value: number, unit: 'PIXELS' \| 'PERCENT' }` or `{ unit: 'AUTO' }`       |
18| `textCase`         | `TextCase`       | `'ORIGINAL' \| 'UPPER' \| 'LOWER' \| 'TITLE' \| 'SMALL_CAPS'`                |
19| `textDecoration`   | `TextDecoration` | `'NONE' \| 'UNDERLINE' \| 'STRIKETHROUGH'`                                   |
20| `paragraphSpacing` | `number`         |                                                                              |
21| `paragraphIndent`  | `number`         |                                                                              |
22| `description`      | `string`         | Inherited from `BaseStyleMixin`                                              |
23 
24### lineHeight and letterSpacing format
25 
26These properties must be objects — not bare numbers:
27 
28```js
29// WRONG — bare number throws
30style.lineHeight = 1.5;
31style.letterSpacing = 0;
32 
33// CORRECT
34style.lineHeight = { unit: "AUTO" }; // auto line height
35style.lineHeight = { value: 24, unit: "PIXELS" }; // fixed pixel height
36style.lineHeight = { value: 150, unit: "PERCENT" }; // 150% line height
37 
38style.letterSpacing = { value: 0, unit: "PIXELS" }; // zero tracking
39style.letterSpacing = { value: -2, unit: "PIXELS" }; // tight tracking
40style.letterSpacing = { value: 5, unit: "PERCENT" }; // percent-based tracking
41```
42 
43When reading a `lineHeight` back, always check `unit` first — `{ unit: 'AUTO' }` has no `value` key.
44 
45### Variable bindings on text styles
46 
47The following fields can be bound to variables via `style.setBoundVariable(field, variable)`:
48 
49`fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `letterSpacing`, `lineHeight`, `paragraphSpacing`, `paragraphIndent`
50 
51To unbind: `style.setBoundVariable(field, null)`
52 
53**Important: `setBoundVariable` is NOT available on `TextStyle` in headless `use_figma` mode.**
54 
55It is only available in interactive plugin context (UI plugins, Figma editor). When running through `use_figma` (MCP, assistant headless runtime), calling `ts.setBoundVariable(...)` will throw `"not a function"`. In this context, set raw values directly instead:
56 
57```js
58// In use_figma (headless) — variable binding not available
59const ts = figma.createTextStyle();
60ts.fontSize = 24; // set directly; cannot bind to a variable
61 
62// In a real interactive plugin — variable binding works
63const ts = figma.createTextStyle();
64ts.setBoundVariable("fontSize", fontSizeVariable);
65```
66 
67If live variable binding on text styles is required, the recommended approach is to:
68 
691. Create the text styles with raw values via `use_figma`
702. Open the file in Figma and bind variables interactively via the Styles panel, OR
713. Use an interactive plugin that runs in the Figma editor (not headless)
72 
73### Applying a text style to a node
74 
75Once you have a `TextStyle`, apply it to a `TextNode` by assigning its `id` to the node's `textStyleId` property. You can also use the async setter `setTextStyleIdAsync(id)`. Setting `textStyleId` on a node does **not** require the font to be loaded — only editing the text content or font properties directly does.
76 
77## Common gotchas
78 
79- **Font must be loaded before setting `fontName`**: Call `await figma.loadFontAsync({ family, style })` before creating or modifying a text style's font.
80- **Font style names are file-dependent**: Font style names like `"SemiBold"` vs `"Semi Bold"` vary by font provider and Figma file. Always probe by calling `loadFontAsync` and catching errors to discover the correct style string rather than guessing.
81- **`setBoundVariable` not available headless**: `TextStyle.setBoundVariable()` throws `"not a function"` in `use_figma` / headless mode. Set raw values instead and bind interactively if needed.
82- **Styles are not automatically applied**: Creating a `TextStyle` has no effect on any node until you assign its ID to a text node.
83- **`getLocalTextStyles()` is deprecated**: Always use `getLocalTextStylesAsync()`.
84- **Names are not unique**: Two text styles can share the same name. Match by ID or `key` when looking up a known style, not by name alone.
85- **Slash grouping is visual only**: `"Heading/XL"` and `"HeadingXL"` are different names; the slash is just a UI affordance.
86- **`lineHeight` and `letterSpacing` must be objects**: `style.lineHeight = 1.5` throws. Always use `{ value, unit }` format or `{ unit: 'AUTO' }`.
87 
88## Code patterns
89 
90For runnable code examples (listing, creating, probing fonts, type ramps, applying styles), see [text-style-patterns.md](../text-style-patterns.md).
91