@fprad0/skill-master-mcp 0.0.9 → 0.0.11

package/docs/skill-candidates/v0.0.10/figma-use/references/validation-and-recovery.md

@@ -0,0 +1,109 @@
+# Validation Workflow & Error Recovery
+
+> Part of the [use_figma skill](../SKILL.md). How to debug, validate, and recover from errors.
+
+## Contents
+
+- `get_metadata` vs `get_screenshot`
+- Error Recovery After Failed `use_figma`
+- Cleanup Pattern
+- Recommended Workflow
+
+
+## `get_metadata` vs `get_screenshot`
+
+After each `use_figma` call, validate results using the right tool for the job. Do NOT reach for `get_screenshot` every time — it is expensive and should be reserved for visual checks.
+
+### `get_metadata` — Use for intermediate validation (preferred)
+
+`get_metadata` returns an XML tree of node IDs, types, names, positions, and sizes. Use it to confirm:
+
+- **Structure & hierarchy**: correct parent-child relationships, component nesting, section contents
+- **Node counts**: expected number of variants created, children present
+- **Naming**: variant property names follow the `property=value` convention
+- **Positioning & alignment**: x/y coordinates, width/height values match expectations
+- **Layout properties**: auto-layout direction, sizing mode, padding, spacing
+- **Component set membership**: all expected variants are inside the ComponentSet
+
+```
+Example: After creating a ComponentSet with 120 variants, call get_metadata on the
+ComponentSet node to verify all 120 children exist with correct names, sizes, and positions
+— without waiting for a full render.
+```
+
+**When to use `get_metadata`:**
+- After creating/modifying nodes — to verify structure, counts, and names
+- After layout operations — to verify positions and dimensions
+- After combining variants — to confirm all components are in the ComponentSet
+- After binding variables — to verify node properties (use use_figma to read bound variables if needed)
+- Between multi-step workflows — to confirm step N succeeded before starting step N+1
+
+### `get_screenshot` — Use after each major creation milestone
+
+`get_screenshot` renders a pixel-accurate image. It is the only way to verify visual correctness (colors, typography rendering, effects, variable mode resolution). It is slower and produces large responses, so don't call it after every single `use_figma` — but do call it after each major milestone to catch visual problems early.
+
+**When to use `get_screenshot`:**
+- **After creating a component set** — verify variants look correct, grid is readable, nothing is collapsed or overlapping
+- **After composing a layout** — verify overall structure and spacing
+- **After binding variables/modes** — verify colors and tokens resolved correctly
+- **After any fix or recovery** — verify the fix didn't introduce new visual issues
+- **Before reporting results to the user** — final visual proof
+
+**What to look for in screenshots** — these are the most commonly missed issues:
+- **Cropped/clipped text** — line heights or frame sizing cutting off descenders, ascenders, or entire lines
+- **Overlapping content** — elements stacking on top of each other due to incorrect sizing or missing auto-layout
+- **Placeholder text** still showing ("Title", "Heading", "Button") instead of actual content
+
+## CRITICAL: Error Recovery After Failed `use_figma`
+
+> **THIS IS NOT OPTIONAL.** Every `use_figma` error MUST trigger the recovery steps below. Skipping these steps leaves orphaned nodes in the file that will cause duplicates and inconsistencies on retry.
+
+**Scripts can partially execute before hitting an error.** A failed `use_figma` does NOT roll back — nodes created before the error line persist in the file. This leaves the file in an **inconsistent, partially-modified state**.
+
+**Mandatory recovery steps when `use_figma` returns an error (DO NOT SKIP):**
+1. **STOP — do NOT immediately fix the code and retry.** The file has partial state that must be inspected first.
+2. **Immediately call `get_metadata`** on the parent node (section, page, or ComponentSet) to see what was partially created.
+3. **If `get_metadata` doesn't make the damage clear** (e.g. positions look fine but visual state is uncertain), call `get_screenshot` to assess visual damage.
+4. **Write a cleanup script** to remove orphaned/incomplete nodes before retrying. Use `page.findChildren()` to locate stray nodes.
+5. **Only after cleanup is confirmed**, fix the original script and retry.
+6. **Never retry the failed script blindly** — the partial state means a retry will create duplicates or hit new errors.
+
+```
+Example: A script creating 8 components fails on component #5.
+Components 1-4 exist on the page. A naive retry creates components 1-8 again,
+leaving 12 components total (4 orphaned duplicates). Always clean up first.
+```
+
+### Cleanup Pattern
+
+```js
+// Cleanup pattern: find and remove orphaned nodes from a failed run
+(async () => {
+  try {
+    const page = figma.currentPage;
+    // Find orphaned components that weren't combined into a ComponentSet
+    const orphans = page.findChildren(n =>
+      n.type === 'COMPONENT' && n.name.includes('variant=')
+    );
+    for (const orphan of orphans) orphan.remove();
+    figma.closePlugin('Cleaned up ' + orphans.length + ' orphaned nodes');
+  } catch(e) { figma.closePluginWithFailure(e.toString()); }
+})()
+```
+
+## Recommended Workflow
+
+```
+1. use_figma  →  Create/modify nodes
+2. get_metadata     →  Verify structure, counts, names, positions (fast, cheap)
+3. use_figma  →  Fix any structural issues found
+4. get_metadata     →  Re-verify fixes
+5. ... repeat as needed ...
+6. get_screenshot   →  Visual check after each major milestone
+
+⚠️ ON ERROR at any step:
+   a. get_metadata    →  Inspect partial state (always do this first)
+   b. get_screenshot  →  Only if metadata doesn't make the damage clear
+   c. use_figma →  Clean up orphaned/incomplete nodes
+   d. THEN retry the failed operation
+```

package/docs/skill-candidates/v0.0.10/figma-use/references/variable-patterns.md

@@ -0,0 +1,354 @@
+# Variable & Token API Patterns
+
+> Part of the [use_figma skill](../SKILL.md). How to correctly create, bind, scope, and alias variables using the Plugin API.
+>
+> For design system context (aliasing strategy, mode decisions, code syntax philosophy, grouping conventions), see [wwds-variables](working-with-design-systems/wwds-variables.md).
+
+## Contents
+
+- Creating Variable Collections and Modes
+- Creating Variables (All Types)
+- Binding Variables to Node Properties
+- Variable Scopes: What They Are and How to Set Them
+- Variable Aliasing (VARIABLE_ALIAS)
+- Code Syntax (setVariableCodeSyntax)
+- Discovering Existing Variables in the File
+- Effect Styles (For Shadows)
+
+
+## Creating Variable Collections and Modes
+
+```javascript
+const collection = figma.variables.createVariableCollection("MyCollection");
+
+// A new collection starts with 1 mode named "Mode 1" — always rename it
+collection.renameMode(collection.modes[0].modeId, "Light");
+
+// Add additional modes (returns the new modeId)
+const darkModeId = collection.addMode("Dark");
+const lightModeId = collection.modes[0].modeId;
+```
+
+**Mode limits are plan-dependent:** Free = 1 mode, Professional = up to 4, Organization/Enterprise = 40+. If you need many modes, split across multiple collections.
+
+## Creating Variables (All Types)
+
+`figma.variables.createVariable(name, collection, resolvedType)` — the second argument accepts a collection object or ID string (object preferred).
+
+```javascript
+// COLOR — values use {r, g, b, a} (all 0–1 range, includes alpha)
+const colorVar = figma.variables.createVariable("my-color", collection, "COLOR");
+colorVar.setValueForMode(modeId, { r: 0.2, g: 0.36, b: 0.96, a: 1 });
+
+// FLOAT — for spacing, radii, sizing, numeric values
+const floatVar = figma.variables.createVariable("my-spacing", collection, "FLOAT");
+floatVar.setValueForMode(modeId, 16);
+
+// STRING — for font families, font style names, any text value
+const stringVar = figma.variables.createVariable("my-font", collection, "STRING");
+stringVar.setValueForMode(modeId, "Inter");
+
+// BOOLEAN
+const boolVar = figma.variables.createVariable("my-flag", collection, "BOOLEAN");
+boolVar.setValueForMode(modeId, true);
+```
+
+**Note:** Paint colors use `{r, g, b}` (no alpha), but COLOR variable values use `{r, g, b, a}` (with alpha). Don't mix them up.
+
+## Binding Variables to Node Properties
+
+### Color Bindings (Fills, Strokes)
+
+`setBoundVariableForPaint` returns a **NEW paint** — you must capture the return value:
+
+```javascript
+// Create a base paint, bind the variable, assign the result
+const basePaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } };
+const boundPaint = figma.variables.setBoundVariableForPaint(basePaint, "color", colorVar);
+node.fills = [boundPaint];
+
+// Only SOLID paints support color variable binding — gradients/images will throw
+```
+
+### Numeric Bindings (Spacing, Radii, Sizing)
+
+`setBoundVariable` binds FLOAT/STRING/BOOLEAN variables to node properties:
+
+```javascript
+// Padding
+node.setBoundVariable("paddingTop", spacingVar);
+node.setBoundVariable("paddingBottom", spacingVar);
+node.setBoundVariable("paddingLeft", spacingVar);
+node.setBoundVariable("paddingRight", spacingVar);
+
+// Gap
+node.setBoundVariable("itemSpacing", gapVar);
+node.setBoundVariable("counterAxisSpacing", gapVar);
+
+// Corner radius — use individual corners, NOT cornerRadius
+node.setBoundVariable("topLeftRadius", radiusVar);
+node.setBoundVariable("topRightRadius", radiusVar);
+node.setBoundVariable("bottomLeftRadius", radiusVar);
+node.setBoundVariable("bottomRightRadius", radiusVar);
+
+// Size
+node.setBoundVariable("width", sizeVar);
+node.setBoundVariable("height", sizeVar);
+node.setBoundVariable("minWidth", sizeVar);
+node.setBoundVariable("maxWidth", sizeVar);
+
+// Other
+node.setBoundVariable("opacity", opacityVar);
+node.setBoundVariable("strokeWeight", strokeVar);
+```
+
+**Not bindable via setBoundVariable:** `fontSize`, `fontWeight`, `lineHeight` — set these directly on text nodes.
+
+### Effect Bindings
+
+```javascript
+const effectCopy = JSON.parse(JSON.stringify(node.effects[0]));
+const newEffect = figma.variables.setBoundVariableForEffect(effectCopy, "color", colorVar);
+// ⚠️ Returns a NEW effect — must capture return value!
+node.effects = [newEffect];
+// Valid fields: "color" (COLOR), "radius" | "spread" | "offsetX" | "offsetY" (FLOAT)
+```
+
+### Applying a Mode to a Frame
+
+```javascript
+// All bound children of this frame will resolve to the specified mode's values
+frame.setExplicitVariableModeForCollection(collection.id, modeId);
+```
+
+Without this, all nodes use the collection's default (first) mode.
+
+## Variable Scopes: What They Are and How to Set Them
+
+`variable.scopes` controls which Figma property pickers show the variable. The default is `["ALL_SCOPES"]` which shows it everywhere — this is almost never what you want.
+
+```javascript
+variable.scopes = ["FRAME_FILL", "SHAPE_FILL"];  // only fill pickers
+variable.scopes = ["TEXT_FILL"];                   // only text color picker
+variable.scopes = ["GAP"];                         // only gap/spacing pickers
+variable.scopes = ["CORNER_RADIUS"];               // only radius pickers
+variable.scopes = [];                              // hidden from all pickers
+```
+
+**All valid scope values:**
+`ALL_SCOPES`, `TEXT_CONTENT`, `CORNER_RADIUS`, `WIDTH_HEIGHT`, `GAP`, `ALL_FILLS`, `FRAME_FILL`, `SHAPE_FILL`, `TEXT_FILL`, `STROKE_COLOR`, `STROKE_FLOAT`, `EFFECT_FLOAT`, `EFFECT_COLOR`, `OPACITY`, `FONT_FAMILY`, `FONT_STYLE`, `FONT_WEIGHT`, `FONT_SIZE`, `LINE_HEIGHT`, `LETTER_SPACING`, `PARAGRAPH_SPACING`, `PARAGRAPH_INDENT`
+
+**Always check the existing file's scope patterns before creating variables** — match whatever convention is already in use. See "Discovering Existing Variables" below.
+
+## Variable Aliasing (VARIABLE_ALIAS)
+
+A variable's value can reference another variable via alias. This is how semantic tokens reference primitive tokens:
+
+```javascript
+// Set a variable's value as an alias to another variable
+semanticVar.setValueForMode(modeId, {
+  type: 'VARIABLE_ALIAS',
+  id: primitiveVar.id
+});
+```
+
+When the primitive changes, the semantic variable updates automatically across all modes.
+
+## Code Syntax (setVariableCodeSyntax)
+
+Links a Figma variable back to its code counterpart. Call once per platform:
+
+```javascript
+variable.setVariableCodeSyntax('WEB', 'var(--color-bg-default)');
+variable.setVariableCodeSyntax('ANDROID', 'colorBgDefault');
+variable.setVariableCodeSyntax('iOS', 'Color.bgDefault');
+
+// Read back: variable.codeSyntax → { WEB: '...', ANDROID: '...', iOS: '...' }
+```
+
+**When deriving CSS names from Figma names**, replace both slashes AND spaces with hyphens:
+
+```javascript
+// WRONG — leaves spaces in CSS variable name
+`var(--${figmaName.replace(/\//g, '-').toLowerCase()})`
+
+// CORRECT — replace all whitespace and slashes
+`var(--${figmaName.replace(/[\s\/]+/g, '-').toLowerCase()})`
+
+// BEST — use the original CSS variable name from the source, not a derived one
+`var(${token.cssVar})`
+```
+
+## Discovering Existing Variables in the File
+
+**Always inspect the file's existing variables before creating new ones.** Different files use different naming conventions, scope patterns, and collection structures. Match what's already there.
+
+### List collections with mode info
+
+```javascript
+(async () => {
+  try {
+    const collections = figma.variables.getLocalVariableCollections();
+    const results = collections.map(c => ({
+      name: c.name,
+      id: c.id,
+      varCount: c.variableIds.length,
+      modes: c.modes.map(m => ({ name: m.name, id: m.modeId }))
+    }));
+    figma.closePlugin(JSON.stringify(results));
+  } catch(e) { figma.closePluginWithFailure(e.toString()); }
+})()
+```
+
+### Inspect scope patterns used in existing variables
+
+```javascript
+(async () => {
+  try {
+    const collections = figma.variables.getLocalVariableCollections();
+    const scopeGroups = {};
+    for (const c of collections) {
+      for (const id of c.variableIds) {
+        const v = figma.variables.getVariableById(id);
+        const key = JSON.stringify(v.scopes);
+        if (!scopeGroups[key]) scopeGroups[key] = [];
+        scopeGroups[key].push(v.name);
+      }
+    }
+    figma.closePlugin(JSON.stringify(scopeGroups));
+  } catch(e) { figma.closePluginWithFailure(e.toString()); }
+})()
+```
+
+### Build a name→variable lookup for reuse
+
+```javascript
+const varByName = {};
+for (const v of figma.variables.getLocalVariables()) {
+  varByName[v.name] = v;
+}
+
+// Bind to existing variable by name — no hex values needed
+function bindFill(node, varName) {
+  const v = varByName[varName];
+  if (!v) throw new Error(`Variable not found: ${varName}`);
+  const paint = figma.variables.setBoundVariableForPaint(
+    { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', v
+  );
+  node.fills = [paint];
+}
+```
+
+**Only create new variables for tokens that have no match in the file.** After building the lookup, compare against the needed tokens and create variables only for the delta.
+
+## Listing Collections with Full Variable Details
+
+The async API returns richer data including code syntax and scopes per variable:
+
+```javascript
+/**
+ * Lists all local variable collections defined in the current Figma file,
+ * including metadata for their modes and variables.
+ *
+ * @returns {Promise<Array<{
+ *   name: string,
+ *   id: string,
+ *   modes: Array<[name: string, modeId: string]>,
+ *   variables: Array<[name: string, id: string, codeSyntax: object, scopes: string[]]>
+ * }>>}
+ */
+async function listVariableCollectionsAndVariables() {
+  const collections = await figma.variables.getLocalVariableCollectionsAsync();
+  const results = [];
+  for (const collection of collections) {
+    const vars = [];
+    for (const id of collection.variableIds) {
+      const v = await figma.variables.getVariableByIdAsync(id);
+      vars.push([v.name, v.id, v.codeSyntax, v.scopes]);
+    }
+    results.push({
+      name: collection.name,
+      id: collection.id,
+      modes: collection.modes.map(m => [m.name, m.modeId]),
+      variables: vars
+    });
+  }
+  return results;
+}
+```
+
+Full runnable script:
+
+```javascript
+(async () => {
+  try {
+    const results = await listVariableCollectionsAndVariables();
+    figma.closePlugin(JSON.stringify(results));
+  } catch(e) { figma.closePluginWithFailure(e.toString()); }
+})()
+```
+
+## Setting and Removing Code Syntax
+
+Must be executed in the file the variable is defined in:
+
+```javascript
+/**
+ * Set the code syntax for a variable for a specific platform.
+ *
+ * @param {string} variableId
+ * @param {'WEB'|'ANDROID'|'iOS'} platform
+ * @param {string} syntax
+ */
+async function setVariableCodeSyntax(variableId, platform, syntax) {
+  const variable = await figma.variables.getVariableByIdAsync(variableId);
+  variable.setVariableCodeSyntax(platform, syntax);
+}
+
+/**
+ * Remove code syntax for a variable for one or more platforms.
+ *
+ * @param {string} variableId
+ * @param {Array<'WEB'|'ANDROID'|'iOS'>} platforms — defaults to all three
+ */
+async function removeVariableCodeSyntax(variableId, platforms = ["WEB", "ANDROID", "iOS"]) {
+  const variable = await figma.variables.getVariableByIdAsync(variableId);
+  for (const platform of platforms) {
+    variable.removeVariableCodeSyntax(platform);
+  }
+}
+
+/**
+ * Set a value for a variable in a specific mode.
+ * For aliases, value must be: { type: 'VARIABLE_ALIAS', id: '<variableId>' }
+ *
+ * @param {string} variableId
+ * @param {string} modeId
+ * @param {string|number|boolean|RGB|RGBA|{type: 'VARIABLE_ALIAS', id: string}} value
+ */
+async function setVariableValueForMode(variableId, modeId, value) {
+  const variable = await figma.variables.getVariableByIdAsync(variableId);
+  variable.setValueForMode(modeId, value);
+}
+```
+
+## Effect Styles (For Shadows)
+
+Shadows can't be stored as variables. Use effect styles. For comprehensive patterns, see [effect-style-patterns.md](effect-style-patterns.md).
+
+```javascript
+const shadow = figma.createEffectStyle();
+shadow.name = "Shadow/Subtle";
+shadow.effects = [{
+  type: "DROP_SHADOW",
+  color: { r: 0, g: 0, b: 0, a: 0.06 },
+  offset: { x: 0, y: 2 },
+  radius: 8,
+  spread: 0,
+  visible: true,
+  blendMode: "NORMAL"
+}];
+
+// Apply to a node
+frame.effectStyleId = shadow.id;
+```

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

@@ -0,0 +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

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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).

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

@@ -0,0 +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).