1# Text Style API Patterns
2 
3> Part of the [use_figma skill](../SKILL.md). How to create, apply, and inspect text styles using the Plugin API.
4>
5> For design system context (when to create text styles, how they relate to tokens, headless limitations), see [wwds-text-styles](working-with-design-systems/wwds-text-styles.md).
6 
7## Contents
8 
9- Listing Text Styles
10- Creating a Text Style
11- Probing Font Styles
12- Creating a Type Ramp (Multi-Step)
13- Importing Library Text Styles
14- Applying Text Styles to Nodes
15 
16## Listing Text Styles
17 
18```javascript
19/**
20 * Lists all local text styles with their key properties.
21 *
22 * @returns {Promise<Array<{id: string, name: string, key: string, fontSize: number, fontName: FontName, lineHeight: LineHeight, letterSpacing: LetterSpacing}>>}
23 */
24async function listTextStyles() {
25  const styles = await figma.getLocalTextStylesAsync();
26  return styles.map(s => ({
27    id: s.id,
28    name: s.name,
29    key: s.key,
30    fontSize: s.fontSize,
31    fontName: s.fontName,
32    lineHeight: s.lineHeight,
33    letterSpacing: s.letterSpacing
34  }));
35}
36```
37 
38Full runnable script:
39 
40```javascript
41const results = await listTextStyles();
42return results;
43```
44 
45## Creating a Text Style
46 
47Font **MUST** be loaded before setting `fontName`. `lineHeight` and `letterSpacing` must be `{value, unit}` objects — bare numbers throw.
48 
49```javascript
50/**
51 * Creates a text style with all typographic properties set.
52 * Font MUST be loaded before calling.
53 *
54 * @param {string} name - Slash-delimited name, e.g. "body/base"
55 * @param {{ family: string, style: string }} fontName
56 * @param {number} fontSize - In pixels
57 * @param {{ value: number, unit: 'PIXELS' | 'PERCENT' } | { unit: 'AUTO' }} lineHeight
58 * @param {{ value: number, unit: 'PIXELS' | 'PERCENT' }} [letterSpacing]
59 * @param {string} [description] - e.g. the CSS variable name "CSS: var(--font-body-base)"
60 * @returns {TextStyle}
61 */
62function createTextStyleFull(name, fontName, fontSize, lineHeight, letterSpacing, description) {
63  const style = figma.createTextStyle();
64  style.name = name;
65  style.fontName = fontName;
66  style.fontSize = fontSize;
67  style.lineHeight = lineHeight; // { unit: 'AUTO' } | { value, unit: 'PIXELS'|'PERCENT' }
68  if (letterSpacing) style.letterSpacing = letterSpacing;
69  if (description) style.description = description;
70  return style;
71}
72```
73 
74## Probing Font Styles
75 
76Font style names vary per provider and per file (`"SemiBold"` vs `"Semi Bold"`). Always probe before hardcoding:
77 
78```javascript
79/**
80 * Probes available font styles for a given family.
81 * Useful when font style names are unknown (e.g. "SemiBold" vs "Semi Bold").
82 *
83 * @param {string} family - Font family name, e.g. "Inter"
84 * @param {string[]} stylesToTest - Candidate style names to probe
85 * @returns {Promise<string[]>} - Style names that loaded successfully
86 */
87async function probeAvailableFontStyles(family, stylesToTest) {
88  const available = [];
89  for (const style of stylesToTest) {
90    try {
91      await figma.loadFontAsync({ family, style });
92      available.push(style);
93    } catch (_) {}
94  }
95  return available;
96}
97```
98 
99## Creating a Type Ramp (Multi-Step)
100 
101Handles font loading, deduplication, and idempotency. Each entry: `[name, fontFamily, fontStyle, fontSize_px, lineHeight, cssVar]`.
102 
103**HEADLESS NOTE:** `setBoundVariable` on `TextStyle` is not supported in `use_figma`. This function sets raw values. To bind variables, do it interactively in Figma after creation.
104 
105```javascript
106/**
107 * Creates a full type ramp from a token definition array.
108 * Handles font loading, deduplication, and idempotency.
109 *
110 * Each entry: [name, fontFamily, fontStyle, fontSize_px, lineHeight, cssVar]
111 *   - lineHeight: { unit: 'AUTO' } or { value: number, unit: 'PIXELS' | 'PERCENT' }
112 *
113 * @param {Array} defs - Array of [name, fontFamily, fontStyle, fontSize, lineHeight, cssVar] tuples
114 * @returns {Promise<{ created: string[], skipped: string[] }>}
115 */
116async function createTypeRamp(defs) {
117  const uniqueFonts = new Set();
118  for (const [, family, style] of defs) {
119    uniqueFonts.add(JSON.stringify({ family, style }));
120  }
121  await Promise.all(
122    [...uniqueFonts].map(f => figma.loadFontAsync(JSON.parse(f)))
123  );
124 
125  const existing = new Set(
126    (await figma.getLocalTextStylesAsync()).map(s => s.name)
127  );
128 
129  const created = [];
130  const skipped = [];
131 
132  for (const [name, family, style, fontSize, lineHeight, cssVar] of defs) {
133    if (existing.has(name)) {
134      skipped.push(name);
135      continue;
136    }
137    const ts = figma.createTextStyle();
138    ts.name = name;
139    ts.fontName = { family, style };
140    ts.fontSize = fontSize;
141    ts.lineHeight = lineHeight ?? { unit: 'AUTO' };
142    if (cssVar) ts.description = `CSS: var(${cssVar})`;
143    created.push(name);
144  }
145 
146  return { created, skipped };
147}
148```
149 
150Full runnable script:
151 
152```javascript
153const defs = [
154  ['heading/xl', 'Inter', 'Bold',      48, { unit: 'PIXELS', value: 56 }, '--font-heading-xl'],
155  ['heading/lg', 'Inter', 'Bold',      36, { unit: 'PIXELS', value: 44 }, '--font-heading-lg'],
156  ['body/base',  'Inter', 'Regular',   16, { unit: 'AUTO' },              '--font-body-base'],
157  ['body/sm',    'Inter', 'Regular',   14, { unit: 'AUTO' },              '--font-body-sm'],
158  ['code/base',  'Roboto Mono', 'Regular', 14, { unit: 'AUTO' },          '--font-code-base'],
159];
160const result = await createTypeRamp(defs);
161return result;
162```
163 
164## Importing Library Text Styles
165 
166For text styles from **team libraries**, use `importStyleByKeyAsync`:
167 
168```javascript
169// Import a library text style by key
170const headingStyle = await figma.importStyleByKeyAsync("TEXT_STYLE_KEY");
171// Apply to a text node
172await textNode.setTextStyleIdAsync(headingStyle.id);
173```
174 
175`search_design_system` with `includeStyles: true` returns style keys you can import this way. Prefer importing library styles over creating new ones.
176 
177## Applying Text Styles to Nodes
178 
179```javascript
180/**
181 * Applies a text style to all TEXT nodes on the current page that match a given name pattern.
182 *
183 * @param {string} styleId - The ID of a TextStyle.
184 * @param {string} nodeNamePattern - Substring match against node names.
185 * @returns {Promise<number>} - Number of nodes the style was applied to.
186 */
187async function applyTextStyleToMatchingNodes(styleId, nodeNamePattern) {
188  const textNodes = figma.currentPage.findAllWithCriteria({ types: ['TEXT'] });
189  let applied = 0;
190  for (const node of textNodes) {
191    if (node.name.includes(nodeNamePattern)) {
192      await node.setTextStyleIdAsync(styleId);
193      applied++;
194    }
195  }
196  return applied;
197}
198```
199 
200Full runnable script:
201 
202```javascript
203const applied = await applyTextStyleToMatchingNodes('STYLE_ID', 'Heading');
204return { applied };
205```
206