@fprad0/skill-master-mcp 0.0.11 → 1.0.0

package/docs/skill-candidates/v0.0.10/figma-use/references/working-with-design-systems/maintainers.yml

@@ -1,9 +1,9 @@
-wwds-components--creating.md: mcp_server
-wwds-components--using.md: mcp_server
-wwds-components.md: mcp_server
-wwds-effect-styles.md: mcp_server
-wwds-text-styles.md: mcp_server
-wwds-variables--creating.md: mcp_server
-wwds-variables--using.md: mcp_server
-wwds-variables.md: mcp_server
-wwds.md: mcp_server
+wwds-components--creating.md: mcp_server
+wwds-components--using.md: mcp_server
+wwds-components.md: mcp_server
+wwds-effect-styles.md: mcp_server
+wwds-text-styles.md: mcp_server
+wwds-variables--creating.md: mcp_server
+wwds-variables--using.md: mcp_server
+wwds-variables.md: mcp_server
+wwds.md: mcp_server

package/docs/skill-candidates/v0.0.10/figma-use/references/working-with-design-systems/wwds-components--creating.md

@@ -1,17 +1,17 @@
-# Working with design systems: Creating Components
-
-When creating Figma components, you need to start by understanding the source and its intent.
-
-If the user is asking you to create a component based on a design or specification, you need to understand the property model before you build anything. What variants are needed? What text, boolean, or instance swap properties exist? Getting the structure right upfront matters because restructuring a component after instances exist is destructive.
-
-If you are given a code component as reference (React props, tokens, etc.), your goal is to reflect the property surface as closely as makes sense in Figma's model. Not all code properties translate directly — hover and focus states are not props in web code, but they are variants in Figma. Understand those gaps and make deliberate decisions about how to represent them.
-
-Variants are the most important thing to get right. Each combination of variant values creates a node on the canvas. Redundant combinations still exist as explicit nodes — there is no way to conditionally exclude them. Define only the axes you actually need.
-
-Non-variant properties (text, boolean, instance swap) should be added after the variant structure is established. These are defined at the component/component set level and referenced by descendant nodes via `componentPropertyReferences`. Always connect them — a property that isn't wired to a descendant is invisible to users of the component.
-
-If the user asks you to make architectural decisions, lean toward fewer variants and more boolean/text properties where possible. Variants multiply combinatorially; the other property types do not. An optional slot property in code might be a combination of instance swap and boolean visibility.
-
-When naming properties, casing is less important since translation layers like Code Connect can do the mapping to represent the code form. Feel free to take a sentence or capitalized case approach for better readability in Figma.
-
-Keep in mind that components often need to be published and connected to Code Connect for the full design-to-code workflow to work. Creating the component is only one part of the system.
+# Working with design systems: Creating Components
+
+When creating Figma components, you need to start by understanding the source and its intent.
+
+If the user is asking you to create a component based on a design or specification, you need to understand the property model before you build anything. What variants are needed? What text, boolean, or instance swap properties exist? Getting the structure right upfront matters because restructuring a component after instances exist is destructive.
+
+If you are given a code component as reference (React props, tokens, etc.), your goal is to reflect the property surface as closely as makes sense in Figma's model. Not all code properties translate directly — hover and focus states are not props in web code, but they are variants in Figma. Understand those gaps and make deliberate decisions about how to represent them.
+
+Variants are the most important thing to get right. Each combination of variant values creates a node on the canvas. Redundant combinations still exist as explicit nodes — there is no way to conditionally exclude them. Define only the axes you actually need.
+
+Non-variant properties (text, boolean, instance swap) should be added after the variant structure is established. These are defined at the component/component set level and referenced by descendant nodes via `componentPropertyReferences`. Always connect them — a property that isn't wired to a descendant is invisible to users of the component.
+
+If the user asks you to make architectural decisions, lean toward fewer variants and more boolean/text properties where possible. Variants multiply combinatorially; the other property types do not. An optional slot property in code might be a combination of instance swap and boolean visibility.
+
+When naming properties, casing is less important since translation layers like Code Connect can do the mapping to represent the code form. Feel free to take a sentence or capitalized case approach for better readability in Figma.
+
+Keep in mind that components often need to be published and connected to Code Connect for the full design-to-code workflow to work. Creating the component is only one part of the system.

package/docs/skill-candidates/v0.0.10/figma-use/references/working-with-design-systems/wwds-components--using.md

@@ -1,17 +1,17 @@
-# Working with design systems: Using Components
-
-When using Figma components, you need to start by understanding the state of the source and the state of Figma.
-
-For the source, you need to know what component is being referenced. This could come from a component key, a node ID, a name, or a Code Connect mapping. If you have a component key from a design system library, prefer `importComponentByKeyAsync` over finding by name, since names are not unique. If you only have a name, search the page or use `search_design_system` to find the right match.
-
-For Figma, you need to know whether the component is local or in a library. Local components can be accessed directly by node ID. Published library components must be imported first — `importComponentByKeyAsync` or `importComponentSetByKeyAsync` — before an instance can be created.
-
-Before setting properties on an instance, read `componentPropertyDefinitions` from the main component first. Property names are not simple strings — TEXT, BOOLEAN, and INSTANCE_SWAP properties have a `#uid` suffix (e.g. `"Label#1234"`). Only VARIANT properties are plain names (e.g. `"Size"`). Using the wrong key in `setProperties` will silently do nothing.
-
-A component might have multiple text properties, which are not possible to derive from text node layer names. Look to the properties to help you understand what values to set, rather than thinking of setting text node characters directly.
-
-When you need to set a nested instance swap (e.g. an icon property), you need the component key of the swap target, not just its name. Import the target component and pass its node ID.
-
-Be aware that instances inside other instances are nested and changes made to a nested instance may be treated as overrides. If the intent is to change the default appearance, you need to modify the main component, not the instance.
-
-When selecting which variant to use, read the `componentProperties` on the instance to see the current state, and `componentPropertyDefinitions` on the main component to see all available options.
+# Working with design systems: Using Components
+
+When using Figma components, you need to start by understanding the state of the source and the state of Figma.
+
+For the source, you need to know what component is being referenced. This could come from a component key, a node ID, a name, or a Code Connect mapping. If you have a component key from a design system library, prefer `importComponentByKeyAsync` over finding by name, since names are not unique. If you only have a name, search the page or use `search_design_system` to find the right match.
+
+For Figma, you need to know whether the component is local or in a library. Local components can be accessed directly by node ID. Published library components must be imported first — `importComponentByKeyAsync` or `importComponentSetByKeyAsync` — before an instance can be created.
+
+Before setting properties on an instance, read `componentPropertyDefinitions` from the main component first. Property names are not simple strings — TEXT, BOOLEAN, and INSTANCE_SWAP properties have a `#uid` suffix (e.g. `"Label#1234"`). Only VARIANT properties are plain names (e.g. `"Size"`). Using the wrong key in `setProperties` will silently do nothing.
+
+A component might have multiple text properties, which are not possible to derive from text node layer names. Look to the properties to help you understand what values to set, rather than thinking of setting text node characters directly.
+
+When you need to set a nested instance swap (e.g. an icon property), you need the component key of the swap target, not just its name. Import the target component and pass its node ID.
+
+Be aware that instances inside other instances are nested and changes made to a nested instance may be treated as overrides. If the intent is to change the default appearance, you need to modify the main component, not the instance.
+
+When selecting which variant to use, read the `componentProperties` on the instance to see the current state, and `componentPropertyDefinitions` on the main component to see all available options.

package/docs/skill-candidates/v0.0.10/figma-use/references/working-with-design-systems/wwds-components.md

@@ -1,50 +1,50 @@
-# Components
-
-Components overlap a lot with the idea of components in a codebase, but with some gaps and other Figma-specific use cases. Components in Figma can be reusable entities that do not have a comparable library pattern, or they can be published and distributed in a library that is aligned to a code forms.
-
-Properties can vary from code in different ways, but alignment to code can still happen without a direct relationship. For example, an interactive pattern in code (like a button) can have many states. A lot of these states (active, focused etc) would be expressed in Figma as variants, which is a concept more closely aligned to properties in a code library. In the case of web this is confusing since hover is not a prop, it is a pseudo selector. At the same time, a color variant might be perfectly aligned between design and code (a property in both places). These discrepancies are accounted for in translation with Figma's Code Connect (deterministic context mapping), but in the case of these tools, must be understood to be properly used.
-
-Figma has four property types, which can be inspected in the component definition's `componentPropertyDefinitions`. To fully understand the component, its descendants must be traversed. Property types include:
-
-- Variant
-  - This is reflected as permutations of the component in a Component Set on the canvas. Each variant is explicitly visualized, including an redundant permutations ("Small + Primary + Disabled" may look the same as "Small Secondary Sisabled"). These permutations create different variants implicitly in Figma and it is handled through layer naming (`Variant=Primary,Size=Small,State=Disabled`).
-- Text/String
-  - Text properties are stored on the component parent, but can be mapped to Text node descendants.
-  - `node.componentPropertyReferences.characters` on a descendant text node are how you determine where the text property is referenced (can be multiple, though unlikely).
-- Boolean
-  - Boolean properties are stored on the component parent, but can be mapped to any node descendant that can have its visibility toggled.
-  - `node.componentPropertyReferences.visible` on a descendant node are how you determine where the boolean property is referenced.
-- Instance Swap
-  - Instance swap properties are stored on the component parent, but can be mapped to Instance node descendants.
-  - `node.componentPropertyReferences.mainComponent` on a descendant instance node are how you determine where the instance property is referenced. A classic example of this is an icon property.
-
-## Descriptions
-
-Components, component sets, and instances all inherit `PublishableMixin`, which includes a writable `description` string. Setting a description is important for any component intended to be used by others — it appears in Figma's dev mode and component panel, and is surfaced in MCP context when reading component metadata.
-
-Descriptions should explain the component's intent and any non-obvious usage constraints. They are not a substitute for Code Connect annotations, but they are always visible without any tooling setup.
-
-```js
-component.description =
-  "Primary action button. Use for the single most important action on a page.";
-```
-
-Variant components (children of a component set) also have a `description` field, but in practice the component set description is what users see. Set it on the component set, not on individual variant nodes.
-
-To read descriptions when auditing:
-
-```js
-// Get all component sets and their descriptions
-figma.root
-  .findAllWithCriteria({ types: ["COMPONENT_SET"] })
-  .map((n) => ({ name: n.name, description: n.description }));
-```
-
-## Usage guidelines
-
-- [Creating components](wwds-components--creating.md): What you must consider when creating new components.
-- [Using components](wwds-components--using.md): What you must consider when trying to use the right components.
-
-## Code patterns
-
-For runnable code examples (creating, importing, discovering, inspecting components), see [component-patterns.md](../component-patterns.md).
+# Components
+
+Components overlap a lot with the idea of components in a codebase, but with some gaps and other Figma-specific use cases. Components in Figma can be reusable entities that do not have a comparable library pattern, or they can be published and distributed in a library that is aligned to a code forms.
+
+Properties can vary from code in different ways, but alignment to code can still happen without a direct relationship. For example, an interactive pattern in code (like a button) can have many states. A lot of these states (active, focused etc) would be expressed in Figma as variants, which is a concept more closely aligned to properties in a code library. In the case of web this is confusing since hover is not a prop, it is a pseudo selector. At the same time, a color variant might be perfectly aligned between design and code (a property in both places). These discrepancies are accounted for in translation with Figma's Code Connect (deterministic context mapping), but in the case of these tools, must be understood to be properly used.
+
+Figma has four property types, which can be inspected in the component definition's `componentPropertyDefinitions`. To fully understand the component, its descendants must be traversed. Property types include:
+
+- Variant
+  - This is reflected as permutations of the component in a Component Set on the canvas. Each variant is explicitly visualized, including an redundant permutations ("Small + Primary + Disabled" may look the same as "Small Secondary Sisabled"). These permutations create different variants implicitly in Figma and it is handled through layer naming (`Variant=Primary,Size=Small,State=Disabled`).
+- Text/String
+  - Text properties are stored on the component parent, but can be mapped to Text node descendants.
+  - `node.componentPropertyReferences.characters` on a descendant text node are how you determine where the text property is referenced (can be multiple, though unlikely).
+- Boolean
+  - Boolean properties are stored on the component parent, but can be mapped to any node descendant that can have its visibility toggled.
+  - `node.componentPropertyReferences.visible` on a descendant node are how you determine where the boolean property is referenced.
+- Instance Swap
+  - Instance swap properties are stored on the component parent, but can be mapped to Instance node descendants.
+  - `node.componentPropertyReferences.mainComponent` on a descendant instance node are how you determine where the instance property is referenced. A classic example of this is an icon property.
+
+## Descriptions
+
+Components, component sets, and instances all inherit `PublishableMixin`, which includes a writable `description` string. Setting a description is important for any component intended to be used by others — it appears in Figma's dev mode and component panel, and is surfaced in MCP context when reading component metadata.
+
+Descriptions should explain the component's intent and any non-obvious usage constraints. They are not a substitute for Code Connect annotations, but they are always visible without any tooling setup.
+
+```js
+component.description =
+  "Primary action button. Use for the single most important action on a page.";
+```
+
+Variant components (children of a component set) also have a `description` field, but in practice the component set description is what users see. Set it on the component set, not on individual variant nodes.
+
+To read descriptions when auditing:
+
+```js
+// Get all component sets and their descriptions
+figma.root
+  .findAllWithCriteria({ types: ["COMPONENT_SET"] })
+  .map((n) => ({ name: n.name, description: n.description }));
+```
+
+## Usage guidelines
+
+- [Creating components](wwds-components--creating.md): What you must consider when creating new components.
+- [Using components](wwds-components--using.md): What you must consider when trying to use the right components.
+
+## Code patterns
+
+For runnable code examples (creating, importing, discovering, inspecting components), see [component-patterns.md](../component-patterns.md).

package/docs/skill-candidates/v0.0.10/figma-use/references/working-with-design-systems/wwds-effect-styles.md

@@ -1,52 +1,52 @@
-# Working with design systems: Effect Styles
-
-Effect styles in Figma are named, reusable definitions of one or more visual effects — drop shadows, inner shadows, and blurs. They are the closest equivalent to a shadow or elevation token in a design system.
-
-Effect styles are distinct from variables. There is no single variable type that represents a shadow. However, individual numeric and color properties within an effect _can_ be bound to variables, allowing shadow values to participate in a token system.
-
-## Model
-
-An `EffectStyle` has one core writable property beyond the base style fields:
-
-| Property      | Type                    | Notes                                                 |
-| ------------- | ----------------------- | ----------------------------------------------------- |
-| `name`        | `string`                | Slash-delimited for grouping (e.g. `"Elevation/200"`) |
-| `effects`     | `ReadonlyArray<Effect>` | **Read-only array** — clone, modify, reassign         |
-| `description` | `string`                | Inherited from `BaseStyleMixin`                       |
-
-### Effect types
-
-An `Effect` is a discriminated union. The most common types:
-
-| `type`            | Key properties                                                                                       |
-| ----------------- | ---------------------------------------------------------------------------------------------------- |
-| `DROP_SHADOW`     | `color: RGBA`, `offset: Vector`, `radius: number`, `spread: number`, `visible: boolean`, `blendMode` |
-| `INNER_SHADOW`    | Same as `DROP_SHADOW`                                                                                |
-| `LAYER_BLUR`      | `radius: number`, `visible: boolean`                                                                 |
-| `BACKGROUND_BLUR` | `radius: number`, `visible: boolean`                                                                 |
-
-All colors are in 0–1 range (`RGBA`), not 0–255.
-
-### Variable bindings on effects
-
-Effect properties that can be bound to variables (via `setBoundVariableForEffect(effect, field, variable)` on a node, or inline when constructing):
-
-`color`, `radius`, `spread`, `offsetX`, `offsetY`
-
-Note: `setBoundVariableForEffect` returns a **new** effect object — you must capture it and reassign the `effects` array.
-
-### Applying an effect style to a node
-
-Assign the style's `id` to the node's `effectStyleId`. The node's `effects` property will then reflect the style's values.
-
-## Common gotchas
-
-- **`effects` is read-only**: You cannot mutate the array in place. Clone it, modify the clone, then reassign: `style.effects = [...style.effects, newEffect]`.
-- **Effects stack in order**: The order of effects in the array matters visually. Drop shadows render bottom-to-top.
-- **Colors are RGBA 0–1**: `{ r: 0, g: 0, b: 0, a: 0.15 }` — not hex, not 0–255.
-- **`getLocalEffectStyles()` is deprecated**: Always use `getLocalEffectStylesAsync()`.
-- **Styles are not automatically applied**: Creating an `EffectStyle` has no effect on any node until you assign its ID to a node.
-
-## Code patterns
-
-For runnable code examples (listing, creating, applying effect styles), see [effect-style-patterns.md](../effect-style-patterns.md).
+# Working with design systems: Effect Styles
+
+Effect styles in Figma are named, reusable definitions of one or more visual effects — drop shadows, inner shadows, and blurs. They are the closest equivalent to a shadow or elevation token in a design system.
+
+Effect styles are distinct from variables. There is no single variable type that represents a shadow. However, individual numeric and color properties within an effect _can_ be bound to variables, allowing shadow values to participate in a token system.
+
+## Model
+
+An `EffectStyle` has one core writable property beyond the base style fields:
+
+| Property      | Type                    | Notes                                                 |
+| ------------- | ----------------------- | ----------------------------------------------------- |
+| `name`        | `string`                | Slash-delimited for grouping (e.g. `"Elevation/200"`) |
+| `effects`     | `ReadonlyArray<Effect>` | **Read-only array** — clone, modify, reassign         |
+| `description` | `string`                | Inherited from `BaseStyleMixin`                       |
+
+### Effect types
+
+An `Effect` is a discriminated union. The most common types:
+
+| `type`            | Key properties                                                                                       |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `DROP_SHADOW`     | `color: RGBA`, `offset: Vector`, `radius: number`, `spread: number`, `visible: boolean`, `blendMode` |
+| `INNER_SHADOW`    | Same as `DROP_SHADOW`                                                                                |
+| `LAYER_BLUR`      | `radius: number`, `visible: boolean`                                                                 |
+| `BACKGROUND_BLUR` | `radius: number`, `visible: boolean`                                                                 |
+
+All colors are in 0–1 range (`RGBA`), not 0–255.
+
+### Variable bindings on effects
+
+Effect properties that can be bound to variables (via `setBoundVariableForEffect(effect, field, variable)` on a node, or inline when constructing):
+
+`color`, `radius`, `spread`, `offsetX`, `offsetY`
+
+Note: `setBoundVariableForEffect` returns a **new** effect object — you must capture it and reassign the `effects` array.
+
+### Applying an effect style to a node
+
+Assign the style's `id` to the node's `effectStyleId`. The node's `effects` property will then reflect the style's values.
+
+## Common gotchas
+
+- **`effects` is read-only**: You cannot mutate the array in place. Clone it, modify the clone, then reassign: `style.effects = [...style.effects, newEffect]`.
+- **Effects stack in order**: The order of effects in the array matters visually. Drop shadows render bottom-to-top.
+- **Colors are RGBA 0–1**: `{ r: 0, g: 0, b: 0, a: 0.15 }` — not hex, not 0–255.
+- **`getLocalEffectStyles()` is deprecated**: Always use `getLocalEffectStylesAsync()`.
+- **Styles are not automatically applied**: Creating an `EffectStyle` has no effect on any node until you assign its ID to a node.
+
+## Code patterns
+
+For runnable code examples (listing, creating, applying effect styles), see [effect-style-patterns.md](../effect-style-patterns.md).

package/docs/skill-candidates/v0.0.10/figma-use/references/working-with-design-systems/wwds-text-styles.md

@@ -1,90 +1,90 @@
-# Working with design systems: Text Styles
-
-Text 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.
-
-Text 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.
-
-## Model
-
-A `TextStyle` has the following writable properties:
-
-| Property           | Type             | Notes                                                                        |
-| ------------------ | ---------------- | ---------------------------------------------------------------------------- |
-| `name`             | `string`         | Slash-delimited for grouping (e.g. `"Heading/XL"`)                           |
-| `fontSize`         | `number`         | In pixels                                                                    |
-| `fontName`         | `FontName`       | `{ family: string, style: string }` — **font must be loaded before setting** |
-| `letterSpacing`    | `LetterSpacing`  | `{ value: number, unit: 'PIXELS' \| 'PERCENT' }`                             |
-| `lineHeight`       | `LineHeight`     | `{ value: number, unit: 'PIXELS' \| 'PERCENT' }` or `{ unit: 'AUTO' }`       |
-| `textCase`         | `TextCase`       | `'ORIGINAL' \| 'UPPER' \| 'LOWER' \| 'TITLE' \| 'SMALL_CAPS'`                |
-| `textDecoration`   | `TextDecoration` | `'NONE' \| 'UNDERLINE' \| 'STRIKETHROUGH'`                                   |
-| `paragraphSpacing` | `number`         |                                                                              |
-| `paragraphIndent`  | `number`         |                                                                              |
-| `description`      | `string`         | Inherited from `BaseStyleMixin`                                              |
-
-### lineHeight and letterSpacing format
-
-These properties must be objects — not bare numbers:
-
-```js
-// WRONG — bare number throws
-style.lineHeight = 1.5;
-style.letterSpacing = 0;
-
-// CORRECT
-style.lineHeight = { unit: "AUTO" }; // auto line height
-style.lineHeight = { value: 24, unit: "PIXELS" }; // fixed pixel height
-style.lineHeight = { value: 150, unit: "PERCENT" }; // 150% line height
-
-style.letterSpacing = { value: 0, unit: "PIXELS" }; // zero tracking
-style.letterSpacing = { value: -2, unit: "PIXELS" }; // tight tracking
-style.letterSpacing = { value: 5, unit: "PERCENT" }; // percent-based tracking
-```
-
-When reading a `lineHeight` back, always check `unit` first — `{ unit: 'AUTO' }` has no `value` key.
-
-### Variable bindings on text styles
-
-The following fields can be bound to variables via `style.setBoundVariable(field, variable)`:
-
-`fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `letterSpacing`, `lineHeight`, `paragraphSpacing`, `paragraphIndent`
-
-To unbind: `style.setBoundVariable(field, null)`
-
-**Important: `setBoundVariable` is NOT available on `TextStyle` in headless `use_figma` mode.**
-
-It 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:
-
-```js
-// In use_figma (headless) — variable binding not available
-const ts = figma.createTextStyle();
-ts.fontSize = 24; // set directly; cannot bind to a variable
-
-// In a real interactive plugin — variable binding works
-const ts = figma.createTextStyle();
-ts.setBoundVariable("fontSize", fontSizeVariable);
-```
-
-If live variable binding on text styles is required, the recommended approach is to:
-
-1. Create the text styles with raw values via `use_figma`
-2. Open the file in Figma and bind variables interactively via the Styles panel, OR
-3. Use an interactive plugin that runs in the Figma editor (not headless)
-
-### Applying a text style to a node
-
-Once 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.
-
-## Common gotchas
-
-- **Font must be loaded before setting `fontName`**: Call `await figma.loadFontAsync({ family, style })` before creating or modifying a text style's font.
-- **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.
-- **`setBoundVariable` not available headless**: `TextStyle.setBoundVariable()` throws `"not a function"` in `use_figma` / headless mode. Set raw values instead and bind interactively if needed.
-- **Styles are not automatically applied**: Creating a `TextStyle` has no effect on any node until you assign its ID to a text node.
-- **`getLocalTextStyles()` is deprecated**: Always use `getLocalTextStylesAsync()`.
-- **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.
-- **Slash grouping is visual only**: `"Heading/XL"` and `"HeadingXL"` are different names; the slash is just a UI affordance.
-- **`lineHeight` and `letterSpacing` must be objects**: `style.lineHeight = 1.5` throws. Always use `{ value, unit }` format or `{ unit: 'AUTO' }`.
-
-## Code patterns
-
-For runnable code examples (listing, creating, probing fonts, type ramps, applying styles), see [text-style-patterns.md](../text-style-patterns.md).
+# Working with design systems: Text Styles
+
+Text 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.
+
+Text 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.
+
+## Model
+
+A `TextStyle` has the following writable properties:
+
+| Property           | Type             | Notes                                                                        |
+| ------------------ | ---------------- | ---------------------------------------------------------------------------- |
+| `name`             | `string`         | Slash-delimited for grouping (e.g. `"Heading/XL"`)                           |
+| `fontSize`         | `number`         | In pixels                                                                    |
+| `fontName`         | `FontName`       | `{ family: string, style: string }` — **font must be loaded before setting** |
+| `letterSpacing`    | `LetterSpacing`  | `{ value: number, unit: 'PIXELS' \| 'PERCENT' }`                             |
+| `lineHeight`       | `LineHeight`     | `{ value: number, unit: 'PIXELS' \| 'PERCENT' }` or `{ unit: 'AUTO' }`       |
+| `textCase`         | `TextCase`       | `'ORIGINAL' \| 'UPPER' \| 'LOWER' \| 'TITLE' \| 'SMALL_CAPS'`                |
+| `textDecoration`   | `TextDecoration` | `'NONE' \| 'UNDERLINE' \| 'STRIKETHROUGH'`                                   |
+| `paragraphSpacing` | `number`         |                                                                              |
+| `paragraphIndent`  | `number`         |                                                                              |
+| `description`      | `string`         | Inherited from `BaseStyleMixin`                                              |
+
+### lineHeight and letterSpacing format
+
+These properties must be objects — not bare numbers:
+
+```js
+// WRONG — bare number throws
+style.lineHeight = 1.5;
+style.letterSpacing = 0;
+
+// CORRECT
+style.lineHeight = { unit: "AUTO" }; // auto line height
+style.lineHeight = { value: 24, unit: "PIXELS" }; // fixed pixel height
+style.lineHeight = { value: 150, unit: "PERCENT" }; // 150% line height
+
+style.letterSpacing = { value: 0, unit: "PIXELS" }; // zero tracking
+style.letterSpacing = { value: -2, unit: "PIXELS" }; // tight tracking
+style.letterSpacing = { value: 5, unit: "PERCENT" }; // percent-based tracking
+```
+
+When reading a `lineHeight` back, always check `unit` first — `{ unit: 'AUTO' }` has no `value` key.
+
+### Variable bindings on text styles
+
+The following fields can be bound to variables via `style.setBoundVariable(field, variable)`:
+
+`fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `letterSpacing`, `lineHeight`, `paragraphSpacing`, `paragraphIndent`
+
+To unbind: `style.setBoundVariable(field, null)`
+
+**Important: `setBoundVariable` is NOT available on `TextStyle` in headless `use_figma` mode.**
+
+It 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:
+
+```js
+// In use_figma (headless) — variable binding not available
+const ts = figma.createTextStyle();
+ts.fontSize = 24; // set directly; cannot bind to a variable
+
+// In a real interactive plugin — variable binding works
+const ts = figma.createTextStyle();
+ts.setBoundVariable("fontSize", fontSizeVariable);
+```
+
+If live variable binding on text styles is required, the recommended approach is to:
+
+1. Create the text styles with raw values via `use_figma`
+2. Open the file in Figma and bind variables interactively via the Styles panel, OR
+3. Use an interactive plugin that runs in the Figma editor (not headless)
+
+### Applying a text style to a node
+
+Once 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.
+
+## Common gotchas
+
+- **Font must be loaded before setting `fontName`**: Call `await figma.loadFontAsync({ family, style })` before creating or modifying a text style's font.
+- **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.
+- **`setBoundVariable` not available headless**: `TextStyle.setBoundVariable()` throws `"not a function"` in `use_figma` / headless mode. Set raw values instead and bind interactively if needed.
+- **Styles are not automatically applied**: Creating a `TextStyle` has no effect on any node until you assign its ID to a text node.
+- **`getLocalTextStyles()` is deprecated**: Always use `getLocalTextStylesAsync()`.
+- **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.
+- **Slash grouping is visual only**: `"Heading/XL"` and `"HeadingXL"` are different names; the slash is just a UI affordance.
+- **`lineHeight` and `letterSpacing` must be objects**: `style.lineHeight = 1.5` throws. Always use `{ value, unit }` format or `{ unit: 'AUTO' }`.
+
+## Code patterns
+
+For runnable code examples (listing, creating, probing fonts, type ramps, applying styles), see [text-style-patterns.md](../text-style-patterns.md).

package/docs/skill-candidates/v0.0.10/figma-use/references/working-with-design-systems/wwds-variables--creating.md

@@ -1,13 +1,13 @@
-# Working with design systems: Creating Variables
-
-When creating Figma variables, you need to start by understanding the state of the source data.
-
-If the user is asking you to create variables based on values, they likely want you to indicate the structure. Whether or not you use semantic aliasing primitive will be based on the inputs you are given about the source data.
-
-If you are given code inputs (JSON, CSS, etc) your goal should be to reflect the existing patterns as closely as possible, but also embrace the design context as distinct from code. For example, casing is less important since you have code syntax that can directly represent the code form. Feel free to take a sentence or capitalized case approach for better readability in Figma.
-
-It is important to understand the underlying structure before you create anything. If there is an implied aliased setup, you want to get that right. You may also need to anticipate modes to know how to split things up. Sizes and Colors likely have different mode requirements in complex systems, so you want to consider that as you create the structure.
-
-If someone asks you to just make a decision based on best practices, that answer will be relative to the complexity of the environment. A simple theme is great best practice for simple needs. Similarly, a complex extended collection setup for someone on an enterprise plan might also be best practice as well.
-
-Keep in mind that systems might also require you to handle text and effect styles for some of the things specified in token libraries.
+# Working with design systems: Creating Variables
+
+When creating Figma variables, you need to start by understanding the state of the source data.
+
+If the user is asking you to create variables based on values, they likely want you to indicate the structure. Whether or not you use semantic aliasing primitive will be based on the inputs you are given about the source data.
+
+If you are given code inputs (JSON, CSS, etc) your goal should be to reflect the existing patterns as closely as possible, but also embrace the design context as distinct from code. For example, casing is less important since you have code syntax that can directly represent the code form. Feel free to take a sentence or capitalized case approach for better readability in Figma.
+
+It is important to understand the underlying structure before you create anything. If there is an implied aliased setup, you want to get that right. You may also need to anticipate modes to know how to split things up. Sizes and Colors likely have different mode requirements in complex systems, so you want to consider that as you create the structure.
+
+If someone asks you to just make a decision based on best practices, that answer will be relative to the complexity of the environment. A simple theme is great best practice for simple needs. Similarly, a complex extended collection setup for someone on an enterprise plan might also be best practice as well.
+
+Keep in mind that systems might also require you to handle text and effect styles for some of the things specified in token libraries.

package/docs/skill-candidates/v0.0.10/figma-use/references/working-with-design-systems/wwds-variables--using.md

@@ -1,13 +1,13 @@
-# Working with design systems: Using Variables
-
-When using Figma variables, you need to start by understanding the state of the source and the state of Figma.
-
-For the source, you need to know the breadth of variables code representation. CSS, JSON, theme providers etc will all be able to indicate what the user will expect you to cover in Figma. Some beginner users might not even know what does and doesn't exist in Figma, and if you cant discover that on your own, you will need their help making the right decision.
-
-For Figma, you need to know what collections exist, what their modes are, and what values and names and code syntaxes are in them. This will help you make sure you are using the right things. For properties that "should" have variables but don't, you likely will need to ask the user what to do. Your understanding of Figma's current state should come first.
-
-You can use code syntax and your understanding of the environment you are expected to be referencing to know which variable in Figma to use. You can also use Figma's variable scopes as indicators if they are specified. It is best to audit those up front.
-
-When using variables you should also be aware of mode mismatches, the default mode in Figma may not be the mode referenced by the user in their expectations. Similarly, many collections may refer to values, but the most specific collection is what you should be using. For example, a semantic collection that aliases a primitive collection, the semantic collection would be what you reference. A component token collection (eg. button/background/primary) might alias a semantic collection, and it is the component collection you need to reference. In some other examples, there may be no aliasing and you're simply value matching.
-
-Gap and padding values for frames are really important and often have to be interpreted semantically or based on layout component values.
+# Working with design systems: Using Variables
+
+When using Figma variables, you need to start by understanding the state of the source and the state of Figma.
+
+For the source, you need to know the breadth of variables code representation. CSS, JSON, theme providers etc will all be able to indicate what the user will expect you to cover in Figma. Some beginner users might not even know what does and doesn't exist in Figma, and if you cant discover that on your own, you will need their help making the right decision.
+
+For Figma, you need to know what collections exist, what their modes are, and what values and names and code syntaxes are in them. This will help you make sure you are using the right things. For properties that "should" have variables but don't, you likely will need to ask the user what to do. Your understanding of Figma's current state should come first.
+
+You can use code syntax and your understanding of the environment you are expected to be referencing to know which variable in Figma to use. You can also use Figma's variable scopes as indicators if they are specified. It is best to audit those up front.
+
+When using variables you should also be aware of mode mismatches, the default mode in Figma may not be the mode referenced by the user in their expectations. Similarly, many collections may refer to values, but the most specific collection is what you should be using. For example, a semantic collection that aliases a primitive collection, the semantic collection would be what you reference. A component token collection (eg. button/background/primary) might alias a semantic collection, and it is the component collection you need to reference. In some other examples, there may be no aliasing and you're simply value matching.
+
+Gap and padding values for frames are really important and often have to be interpreted semantically or based on layout component values.