@fprad0/skill-master-mcp 0.0.11 → 1.0.0

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

@@ -1,512 +1,512 @@
-# Common Patterns
-
-> Part of the [use_figma skill](../SKILL.md). Working code examples for frequently used operations.
-
-## Contents
-
-- Basic Script Structure
-- Create a Styled Shape
-- Create a Text Node
-- Create Frame with Auto-Layout
-- Create Variable Collections and Bindings
-- Create Components and Import by Key
-- Component Sets with Variable Modes
-- Multi-Step Large ComponentSet Pattern
-- Read Existing Nodes and Return Data
-
-
-## Basic Script Structure
-
-```js
-(async () => {
-  try {
-    const createdNodeIds = []
-    const mutatedNodeIds = []
-
-    // Your code here — track every node you create or mutate
-    // createdNodeIds.push(newNode.id)
-    // mutatedNodeIds.push(existingNode.id)
-
-    figma.closePlugin(JSON.stringify({
-      success: true,
-      createdNodeIds,
-      mutatedNodeIds,
-      // Plus any other useful data for subsequent calls
-      count: createdNodeIds.length
-    }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Create a Styled Shape
-
-```js
-(async () => {
-  try {
-    // Find clear space to the right of existing content
-    const page = figma.currentPage
-    let maxX = 0
-    for (const child of page.children) {
-      maxX = Math.max(maxX, child.x + child.width)
-    }
-
-    const rect = figma.createRectangle()
-    rect.name = "Blue Box"
-    rect.resize(200, 100)
-    rect.fills = [{ type: 'SOLID', color: { r: 0.047, g: 0.549, b: 0.914 } }]
-    rect.cornerRadius = 8
-    rect.x = maxX + 100  // offset from existing content
-    rect.y = 0
-    figma.currentPage.appendChild(rect)
-    figma.closePlugin(JSON.stringify({ nodeId: rect.id }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Create a Text Node
-
-```js
-(async () => {
-  try {
-    // Find clear space to the right of existing content
-    const page = figma.currentPage
-    let maxX = 0
-    for (const child of page.children) {
-      maxX = Math.max(maxX, child.x + child.width)
-    }
-
-    await figma.loadFontAsync({ family: "Inter", style: "Regular" })
-    const text = figma.createText()
-    text.characters = "Hello World"
-    text.fontSize = 16
-    text.fills = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }]
-    text.textAutoResize = 'WIDTH_AND_HEIGHT'
-    text.x = maxX + 100
-    text.y = 0
-    figma.currentPage.appendChild(text)
-    figma.closePlugin(JSON.stringify({ nodeId: text.id }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Create Frame with Auto-Layout
-
-```js
-(async () => {
-  try {
-    // Find clear space to the right of existing content
-    const page = figma.currentPage
-    let maxX = 0
-    for (const child of page.children) {
-      maxX = Math.max(maxX, child.x + child.width)
-    }
-
-    const frame = figma.createFrame()
-    frame.name = "Card"
-    frame.layoutMode = 'VERTICAL'
-    frame.primaryAxisAlignItems = 'MIN'
-    frame.counterAxisAlignItems = 'MIN'
-    frame.paddingLeft = 16
-    frame.paddingRight = 16
-    frame.paddingTop = 12
-    frame.paddingBottom = 12
-    frame.itemSpacing = 8
-    frame.layoutSizingHorizontal = 'HUG'
-    frame.layoutSizingVertical = 'HUG'
-    frame.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }]
-    frame.cornerRadius = 8
-    frame.x = maxX + 100
-    frame.y = 0
-    figma.currentPage.appendChild(frame)
-    figma.closePlugin(JSON.stringify({ nodeId: frame.id }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Create Variable Collection with Multiple Modes
-
-```js
-(async () => {
-  try {
-    const collection = figma.variables.createVariableCollection("Theme/Colors")
-    // Rename the default mode
-    collection.renameMode(collection.modes[0].modeId, "Light")
-    const darkModeId = collection.addMode("Dark")
-    const lightModeId = collection.modes[0].modeId
-
-    const bgVar = figma.variables.createVariable("bg", collection, "COLOR")
-    bgVar.setValueForMode(lightModeId, { r: 1, g: 1, b: 1, a: 1 })
-    bgVar.setValueForMode(darkModeId, { r: 0.1, g: 0.1, b: 0.1, a: 1 })
-
-    const textVar = figma.variables.createVariable("text", collection, "COLOR")
-    textVar.setValueForMode(lightModeId, { r: 0, g: 0, b: 0, a: 1 })
-    textVar.setValueForMode(darkModeId, { r: 1, g: 1, b: 1, a: 1 })
-
-    figma.closePlugin(JSON.stringify({
-      collectionId: collection.id,
-      lightModeId,
-      darkModeId,
-      bgVarId: bgVar.id,
-      textVarId: textVar.id
-    }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Bind Color Variable to a Fill
-
-```js
-(async () => {
-  try {
-    const variable = figma.variables.getVariableById("VariableID:1:2")
-    const rect = figma.createRectangle()
-    const basePaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }
-
-    // setBoundVariableForPaint returns a NEW paint — capture it!
-    const boundPaint = figma.variables.setBoundVariableForPaint(basePaint, "color", variable)
-    rect.fills = [boundPaint]
-
-    figma.closePlugin(JSON.stringify({ nodeId: rect.id }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Create Component Variants with Component Properties
-
-Component properties (TEXT, BOOLEAN, INSTANCE_SWAP) MUST be added inside the per-variant loop, BEFORE `combineAsVariants`. The component set inherits them from its children.
-
-```js
-(async () => {
-  try {
-    await figma.loadFontAsync({ family: "Inter", style: "Regular" })
-
-    // Assume defaultIconComp is an existing icon component (discovered earlier)
-    const defaultIconComp = figma.getNodeById('ICON_COMPONENT_ID')
-
-    const components = []
-    const variants = ["primary", "secondary"]
-
-    for (const variant of variants) {
-      const comp = figma.createComponent()
-      comp.name = `variant=${variant}`
-      comp.layoutMode = 'HORIZONTAL'
-      comp.primaryAxisAlignItems = 'CENTER'
-      comp.counterAxisAlignItems = 'CENTER'
-      comp.paddingLeft = 12
-      comp.paddingRight = 12
-      comp.paddingTop = 8
-      comp.paddingBottom = 8
-      comp.layoutSizingHorizontal = 'HUG'
-      comp.layoutSizingVertical = 'HUG'
-      comp.cornerRadius = 6
-      comp.itemSpacing = 8
-
-      // TEXT property — label
-      const labelKey = comp.addComponentProperty('Label', 'TEXT', 'Button')
-      const label = figma.createText()
-      label.characters = "Button"
-      label.fontSize = 14
-      comp.appendChild(label)
-      label.componentPropertyReferences = { characters: labelKey }
-
-      // BOOLEAN + INSTANCE_SWAP — icon slot
-      const showIconKey = comp.addComponentProperty('Show Icon', 'BOOLEAN', false)
-      const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', defaultIconComp.id)
-      const iconInstance = defaultIconComp.createInstance()
-      comp.insertChild(0, iconInstance)  // icon before label
-      iconInstance.componentPropertyReferences = {
-        visible: showIconKey,
-        mainComponent: iconSlotKey
-      }
-
-      components.push(comp)
-    }
-
-    const componentSet = figma.combineAsVariants(components, figma.currentPage)
-    componentSet.name = "Button"
-
-    // Layout variants in a row after combining (they stack at 0,0 by default)
-    const colW = 140
-    componentSet.children.forEach((child, i) => {
-      child.x = i * colW
-      child.y = 0
-    })
-    // Resize from actual child bounds — formula-based sizing is error-prone
-    let maxX = 0, maxY = 0
-    for (const c of componentSet.children) {
-      maxX = Math.max(maxX, c.x + c.width)
-      maxY = Math.max(maxY, c.y + c.height)
-    }
-    componentSet.resizeWithoutConstraints(maxX + 40, maxY + 40)
-
-    figma.closePlugin(JSON.stringify({
-      componentSetId: componentSet.id,
-      componentIds: components.map(c => c.id)
-    }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Import a Component by Key (Team Libraries)
-
-`importComponentByKeyAsync` and `importComponentSetByKeyAsync` import components from **team libraries** (not the same file you're working in). For components in the current file, use `figma.getNodeByIdAsync()` or `findOne()`/`findAll()` to locate them directly.
-
-```js
-(async () => {
-  try {
-    // Import a single published component by key
-    const comp = await figma.importComponentByKeyAsync("COMPONENT_KEY")
-    const instance = comp.createInstance()
-    instance.x = 40
-    instance.y = 40
-    figma.currentPage.appendChild(instance)
-
-    // Import a published component set by key and select a variant
-    const compSet = await figma.importComponentSetByKeyAsync("COMPONENT_SET_KEY")
-    const variant =
-      compSet.children.find((c) =>
-        c.type === "COMPONENT" && c.name.includes("size=md")
-      ) || compSet.defaultVariant
-
-    const variantInstance = variant.createInstance()
-    variantInstance.x = 240
-    variantInstance.y = 40
-    figma.currentPage.appendChild(variantInstance)
-
-    figma.closePlugin(JSON.stringify({
-      componentId: comp.id,
-      componentSetId: compSet.id,
-      placedInstanceIds: [instance.id, variantInstance.id]
-    }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Component Set with Variable Modes (Full Pattern)
-
-```js
-(async () => {
-  try {
-    await figma.loadFontAsync({ family: "Inter", style: "Medium" })
-
-    // 1. Create color collection with modes per variant
-    const colors = figma.variables.createVariableCollection("Component/Colors")
-    colors.renameMode(colors.modes[0].modeId, "primary")
-    const primaryMode = colors.modes[0].modeId
-    const secondaryMode = colors.addMode("secondary")
-
-    const bgVar = figma.variables.createVariable("bg", colors, "COLOR")
-    bgVar.setValueForMode(primaryMode, { r: 0, g: 0.4, b: 0.9, a: 1 })
-    bgVar.setValueForMode(secondaryMode, { r: 0, g: 0, b: 0, a: 0 })
-
-    const textVar = figma.variables.createVariable("text-color", colors, "COLOR")
-    textVar.setValueForMode(primaryMode, { r: 1, g: 1, b: 1, a: 1 })
-    textVar.setValueForMode(secondaryMode, { r: 0.1, g: 0.1, b: 0.1, a: 1 })
-
-    // 2. Create components with variable bindings
-    const modeMap = { primary: primaryMode, secondary: secondaryMode }
-    const components = []
-
-    for (const [variantName, modeId] of Object.entries(modeMap)) {
-      const comp = figma.createComponent()
-      comp.name = "variant=" + variantName
-      comp.layoutMode = "HORIZONTAL"
-      comp.primaryAxisAlignItems = "CENTER"
-      comp.counterAxisAlignItems = "CENTER"
-      comp.paddingLeft = 12; comp.paddingRight = 12
-      comp.layoutSizingHorizontal = "HUG"
-      comp.layoutSizingVertical = "HUG"
-      comp.cornerRadius = 6
-
-      // Bind background fill to variable
-      const bgPaint = figma.variables.setBoundVariableForPaint(
-        { type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", bgVar
-      )
-      comp.fills = [bgPaint]
-
-      // Add text with bound color
-      const label = figma.createText()
-      label.fontName = { family: "Inter", style: "Medium" }
-      label.characters = "Button"
-      label.fontSize = 14
-      const textPaint = figma.variables.setBoundVariableForPaint(
-        { type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", textVar
-      )
-      label.fills = [textPaint]
-      comp.appendChild(label)
-
-      // 3. CRITICAL: Set explicit mode so this variant renders correctly
-      comp.setExplicitVariableModeForCollection(colors.id, modeId)
-
-      components.push(comp)
-    }
-
-    // 4. Combine into component set
-    const componentSet = figma.combineAsVariants(components, figma.currentPage)
-    componentSet.name = "Button"
-
-    figma.closePlugin(JSON.stringify({
-      componentSetId: componentSet.id,
-      colorCollectionId: colors.id
-    }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
-
-## Large ComponentSet with Variable Modes (Multi-Step Pattern)
-
-For component sets with many variants (50+), split into multiple `use_figma` calls:
-
-**Call 1: Create variable collections and return IDs**
-
-```js
-(async () => {
-  try {
-    // Hex-to-0-1 helper
-    const hex = (h) => {
-      if (!h) return { r: 0, g: 0, b: 0, a: 0 }; // transparent
-      return {
-        r: parseInt(h.slice(1,3), 16) / 255,
-        g: parseInt(h.slice(3,5), 16) / 255,
-        b: parseInt(h.slice(5,7), 16) / 255,
-        a: 1
-      };
-    };
-
-    const coll = figma.variables.createVariableCollection("MyComponent/Colors");
-    coll.renameMode(coll.modes[0].modeId, "mode1");
-    const mode2Id = coll.addMode("mode2");
-
-    // Create variables from data map
-    const colorData = { "bg/default": ["#0B6BCB", "#636B74"], /* ... */ };
-    const modeOrder = ["mode1", "mode2"];
-    const modeIds = { mode1: coll.modes[0].modeId, mode2: mode2Id };
-    const varIds = {};
-
-    for (const [name, values] of Object.entries(colorData)) {
-      const v = figma.variables.createVariable(name, coll, "COLOR");
-      values.forEach((hex_val, i) => {
-        v.setValueForMode(modeIds[modeOrder[i]], hex_val ? hex(hex_val) : { r:0, g:0, b:0, a:0 });
-      });
-      varIds[name] = v.id;
-    }
-
-    // Return ALL IDs — needed by subsequent calls
-    figma.closePlugin(JSON.stringify({ collId: coll.id, modeIds, varIds }));
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString());
-  }
-})()
-```
-
-**Call 2: Create components using stored IDs, combine and layout**
-
-```js
-(async () => {
-  try {
-    await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
-
-    // Paste IDs from Call 1 as literals
-    const collId = "VariableCollectionId:X:Y";
-    const modeIds = { mode1: "X:0", mode2: "X:1" };
-    const varIds = { /* ... from Call 1 ... */ };
-
-    const getVar = (id) => figma.variables.getVariableById(id);
-    const bindColor = (varId) => figma.variables.setBoundVariableForPaint(
-      { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', getVar(varId)
-    );
-
-    const components = [];
-    for (const mode of ["mode1", "mode2"]) {
-      for (const state of ["default", "hover"]) {
-        const comp = figma.createComponent();
-        comp.name = `mode=${mode}, state=${state}`;
-        comp.layoutMode = 'HORIZONTAL';
-        comp.primaryAxisAlignItems = 'CENTER';
-        comp.counterAxisAlignItems = 'CENTER';
-        comp.layoutSizingHorizontal = 'HUG';
-        comp.layoutSizingVertical = 'HUG';
-        comp.fills = [bindColor(varIds[`bg/${state}`])];
-        comp.setExplicitVariableModeForCollection(collId, modeIds[mode]);
-        // ... add text children ...
-        components.push(comp);
-      }
-    }
-
-    // Combine — all children stack at (0,0)!
-    const cs = figma.combineAsVariants(components, figma.currentPage);
-    cs.name = "MyComponent";
-
-    // CRITICAL: layout variants in a structured grid mapped to variant axes.
-    const stateOrder = ["default", "hover"];
-    const modeOrder2 = ["mode1", "mode2"];
-    const colW = 140, rowH = 56;
-
-    for (const child of cs.children) {
-      const props = Object.fromEntries(
-        child.name.split(', ').map(p => p.split('='))
-      );
-      const col = stateOrder.indexOf(props.state);
-      const row = modeOrder2.indexOf(props.mode);
-      child.x = col * colW;
-      child.y = row * rowH;
-    }
-    // Resize from actual child bounds
-    let maxX = 0, maxY = 0;
-    for (const child of cs.children) {
-      maxX = Math.max(maxX, child.x + child.width);
-      maxY = Math.max(maxY, child.y + child.height);
-    }
-    cs.resizeWithoutConstraints(maxX + 40, maxY + 40);
-
-    // Wrap in section
-    const section = figma.createSection();
-    section.name = "MyComponent Section";
-    section.appendChild(cs);
-    section.resizeWithoutConstraints(cs.width + 200, cs.height + 200);
-
-    figma.closePlugin(JSON.stringify({ csId: cs.id, count: components.length }));
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString());
-  }
-})()
-```
-
-## Read Existing Nodes and Return Data
-
-```js
-(async () => {
-  try {
-    const page = figma.currentPage
-    const nodes = page.findAll(n => n.type === 'FRAME')
-    const data = nodes.map(n => ({
-      id: n.id,
-      name: n.name,
-      width: n.width,
-      height: n.height,
-      childCount: n.children?.length || 0
-    }))
-    figma.closePlugin(JSON.stringify({ frames: data }))
-  } catch (e) {
-    figma.closePluginWithFailure(e.toString())
-  }
-})()
-```
+# Common Patterns
+
+> Part of the [use_figma skill](../SKILL.md). Working code examples for frequently used operations.
+
+## Contents
+
+- Basic Script Structure
+- Create a Styled Shape
+- Create a Text Node
+- Create Frame with Auto-Layout
+- Create Variable Collections and Bindings
+- Create Components and Import by Key
+- Component Sets with Variable Modes
+- Multi-Step Large ComponentSet Pattern
+- Read Existing Nodes and Return Data
+
+
+## Basic Script Structure
+
+```js
+(async () => {
+  try {
+    const createdNodeIds = []
+    const mutatedNodeIds = []
+
+    // Your code here — track every node you create or mutate
+    // createdNodeIds.push(newNode.id)
+    // mutatedNodeIds.push(existingNode.id)
+
+    figma.closePlugin(JSON.stringify({
+      success: true,
+      createdNodeIds,
+      mutatedNodeIds,
+      // Plus any other useful data for subsequent calls
+      count: createdNodeIds.length
+    }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Create a Styled Shape
+
+```js
+(async () => {
+  try {
+    // Find clear space to the right of existing content
+    const page = figma.currentPage
+    let maxX = 0
+    for (const child of page.children) {
+      maxX = Math.max(maxX, child.x + child.width)
+    }
+
+    const rect = figma.createRectangle()
+    rect.name = "Blue Box"
+    rect.resize(200, 100)
+    rect.fills = [{ type: 'SOLID', color: { r: 0.047, g: 0.549, b: 0.914 } }]
+    rect.cornerRadius = 8
+    rect.x = maxX + 100  // offset from existing content
+    rect.y = 0
+    figma.currentPage.appendChild(rect)
+    figma.closePlugin(JSON.stringify({ nodeId: rect.id }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Create a Text Node
+
+```js
+(async () => {
+  try {
+    // Find clear space to the right of existing content
+    const page = figma.currentPage
+    let maxX = 0
+    for (const child of page.children) {
+      maxX = Math.max(maxX, child.x + child.width)
+    }
+
+    await figma.loadFontAsync({ family: "Inter", style: "Regular" })
+    const text = figma.createText()
+    text.characters = "Hello World"
+    text.fontSize = 16
+    text.fills = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }]
+    text.textAutoResize = 'WIDTH_AND_HEIGHT'
+    text.x = maxX + 100
+    text.y = 0
+    figma.currentPage.appendChild(text)
+    figma.closePlugin(JSON.stringify({ nodeId: text.id }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Create Frame with Auto-Layout
+
+```js
+(async () => {
+  try {
+    // Find clear space to the right of existing content
+    const page = figma.currentPage
+    let maxX = 0
+    for (const child of page.children) {
+      maxX = Math.max(maxX, child.x + child.width)
+    }
+
+    const frame = figma.createFrame()
+    frame.name = "Card"
+    frame.layoutMode = 'VERTICAL'
+    frame.primaryAxisAlignItems = 'MIN'
+    frame.counterAxisAlignItems = 'MIN'
+    frame.paddingLeft = 16
+    frame.paddingRight = 16
+    frame.paddingTop = 12
+    frame.paddingBottom = 12
+    frame.itemSpacing = 8
+    frame.layoutSizingHorizontal = 'HUG'
+    frame.layoutSizingVertical = 'HUG'
+    frame.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }]
+    frame.cornerRadius = 8
+    frame.x = maxX + 100
+    frame.y = 0
+    figma.currentPage.appendChild(frame)
+    figma.closePlugin(JSON.stringify({ nodeId: frame.id }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Create Variable Collection with Multiple Modes
+
+```js
+(async () => {
+  try {
+    const collection = figma.variables.createVariableCollection("Theme/Colors")
+    // Rename the default mode
+    collection.renameMode(collection.modes[0].modeId, "Light")
+    const darkModeId = collection.addMode("Dark")
+    const lightModeId = collection.modes[0].modeId
+
+    const bgVar = figma.variables.createVariable("bg", collection, "COLOR")
+    bgVar.setValueForMode(lightModeId, { r: 1, g: 1, b: 1, a: 1 })
+    bgVar.setValueForMode(darkModeId, { r: 0.1, g: 0.1, b: 0.1, a: 1 })
+
+    const textVar = figma.variables.createVariable("text", collection, "COLOR")
+    textVar.setValueForMode(lightModeId, { r: 0, g: 0, b: 0, a: 1 })
+    textVar.setValueForMode(darkModeId, { r: 1, g: 1, b: 1, a: 1 })
+
+    figma.closePlugin(JSON.stringify({
+      collectionId: collection.id,
+      lightModeId,
+      darkModeId,
+      bgVarId: bgVar.id,
+      textVarId: textVar.id
+    }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Bind Color Variable to a Fill
+
+```js
+(async () => {
+  try {
+    const variable = figma.variables.getVariableById("VariableID:1:2")
+    const rect = figma.createRectangle()
+    const basePaint = { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }
+
+    // setBoundVariableForPaint returns a NEW paint — capture it!
+    const boundPaint = figma.variables.setBoundVariableForPaint(basePaint, "color", variable)
+    rect.fills = [boundPaint]
+
+    figma.closePlugin(JSON.stringify({ nodeId: rect.id }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Create Component Variants with Component Properties
+
+Component properties (TEXT, BOOLEAN, INSTANCE_SWAP) MUST be added inside the per-variant loop, BEFORE `combineAsVariants`. The component set inherits them from its children.
+
+```js
+(async () => {
+  try {
+    await figma.loadFontAsync({ family: "Inter", style: "Regular" })
+
+    // Assume defaultIconComp is an existing icon component (discovered earlier)
+    const defaultIconComp = figma.getNodeById('ICON_COMPONENT_ID')
+
+    const components = []
+    const variants = ["primary", "secondary"]
+
+    for (const variant of variants) {
+      const comp = figma.createComponent()
+      comp.name = `variant=${variant}`
+      comp.layoutMode = 'HORIZONTAL'
+      comp.primaryAxisAlignItems = 'CENTER'
+      comp.counterAxisAlignItems = 'CENTER'
+      comp.paddingLeft = 12
+      comp.paddingRight = 12
+      comp.paddingTop = 8
+      comp.paddingBottom = 8
+      comp.layoutSizingHorizontal = 'HUG'
+      comp.layoutSizingVertical = 'HUG'
+      comp.cornerRadius = 6
+      comp.itemSpacing = 8
+
+      // TEXT property — label
+      const labelKey = comp.addComponentProperty('Label', 'TEXT', 'Button')
+      const label = figma.createText()
+      label.characters = "Button"
+      label.fontSize = 14
+      comp.appendChild(label)
+      label.componentPropertyReferences = { characters: labelKey }
+
+      // BOOLEAN + INSTANCE_SWAP — icon slot
+      const showIconKey = comp.addComponentProperty('Show Icon', 'BOOLEAN', false)
+      const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', defaultIconComp.id)
+      const iconInstance = defaultIconComp.createInstance()
+      comp.insertChild(0, iconInstance)  // icon before label
+      iconInstance.componentPropertyReferences = {
+        visible: showIconKey,
+        mainComponent: iconSlotKey
+      }
+
+      components.push(comp)
+    }
+
+    const componentSet = figma.combineAsVariants(components, figma.currentPage)
+    componentSet.name = "Button"
+
+    // Layout variants in a row after combining (they stack at 0,0 by default)
+    const colW = 140
+    componentSet.children.forEach((child, i) => {
+      child.x = i * colW
+      child.y = 0
+    })
+    // Resize from actual child bounds — formula-based sizing is error-prone
+    let maxX = 0, maxY = 0
+    for (const c of componentSet.children) {
+      maxX = Math.max(maxX, c.x + c.width)
+      maxY = Math.max(maxY, c.y + c.height)
+    }
+    componentSet.resizeWithoutConstraints(maxX + 40, maxY + 40)
+
+    figma.closePlugin(JSON.stringify({
+      componentSetId: componentSet.id,
+      componentIds: components.map(c => c.id)
+    }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Import a Component by Key (Team Libraries)
+
+`importComponentByKeyAsync` and `importComponentSetByKeyAsync` import components from **team libraries** (not the same file you're working in). For components in the current file, use `figma.getNodeByIdAsync()` or `findOne()`/`findAll()` to locate them directly.
+
+```js
+(async () => {
+  try {
+    // Import a single published component by key
+    const comp = await figma.importComponentByKeyAsync("COMPONENT_KEY")
+    const instance = comp.createInstance()
+    instance.x = 40
+    instance.y = 40
+    figma.currentPage.appendChild(instance)
+
+    // Import a published component set by key and select a variant
+    const compSet = await figma.importComponentSetByKeyAsync("COMPONENT_SET_KEY")
+    const variant =
+      compSet.children.find((c) =>
+        c.type === "COMPONENT" && c.name.includes("size=md")
+      ) || compSet.defaultVariant
+
+    const variantInstance = variant.createInstance()
+    variantInstance.x = 240
+    variantInstance.y = 40
+    figma.currentPage.appendChild(variantInstance)
+
+    figma.closePlugin(JSON.stringify({
+      componentId: comp.id,
+      componentSetId: compSet.id,
+      placedInstanceIds: [instance.id, variantInstance.id]
+    }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Component Set with Variable Modes (Full Pattern)
+
+```js
+(async () => {
+  try {
+    await figma.loadFontAsync({ family: "Inter", style: "Medium" })
+
+    // 1. Create color collection with modes per variant
+    const colors = figma.variables.createVariableCollection("Component/Colors")
+    colors.renameMode(colors.modes[0].modeId, "primary")
+    const primaryMode = colors.modes[0].modeId
+    const secondaryMode = colors.addMode("secondary")
+
+    const bgVar = figma.variables.createVariable("bg", colors, "COLOR")
+    bgVar.setValueForMode(primaryMode, { r: 0, g: 0.4, b: 0.9, a: 1 })
+    bgVar.setValueForMode(secondaryMode, { r: 0, g: 0, b: 0, a: 0 })
+
+    const textVar = figma.variables.createVariable("text-color", colors, "COLOR")
+    textVar.setValueForMode(primaryMode, { r: 1, g: 1, b: 1, a: 1 })
+    textVar.setValueForMode(secondaryMode, { r: 0.1, g: 0.1, b: 0.1, a: 1 })
+
+    // 2. Create components with variable bindings
+    const modeMap = { primary: primaryMode, secondary: secondaryMode }
+    const components = []
+
+    for (const [variantName, modeId] of Object.entries(modeMap)) {
+      const comp = figma.createComponent()
+      comp.name = "variant=" + variantName
+      comp.layoutMode = "HORIZONTAL"
+      comp.primaryAxisAlignItems = "CENTER"
+      comp.counterAxisAlignItems = "CENTER"
+      comp.paddingLeft = 12; comp.paddingRight = 12
+      comp.layoutSizingHorizontal = "HUG"
+      comp.layoutSizingVertical = "HUG"
+      comp.cornerRadius = 6
+
+      // Bind background fill to variable
+      const bgPaint = figma.variables.setBoundVariableForPaint(
+        { type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", bgVar
+      )
+      comp.fills = [bgPaint]
+
+      // Add text with bound color
+      const label = figma.createText()
+      label.fontName = { family: "Inter", style: "Medium" }
+      label.characters = "Button"
+      label.fontSize = 14
+      const textPaint = figma.variables.setBoundVariableForPaint(
+        { type: "SOLID", color: { r: 0, g: 0, b: 0 } }, "color", textVar
+      )
+      label.fills = [textPaint]
+      comp.appendChild(label)
+
+      // 3. CRITICAL: Set explicit mode so this variant renders correctly
+      comp.setExplicitVariableModeForCollection(colors.id, modeId)
+
+      components.push(comp)
+    }
+
+    // 4. Combine into component set
+    const componentSet = figma.combineAsVariants(components, figma.currentPage)
+    componentSet.name = "Button"
+
+    figma.closePlugin(JSON.stringify({
+      componentSetId: componentSet.id,
+      colorCollectionId: colors.id
+    }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```
+
+## Large ComponentSet with Variable Modes (Multi-Step Pattern)
+
+For component sets with many variants (50+), split into multiple `use_figma` calls:
+
+**Call 1: Create variable collections and return IDs**
+
+```js
+(async () => {
+  try {
+    // Hex-to-0-1 helper
+    const hex = (h) => {
+      if (!h) return { r: 0, g: 0, b: 0, a: 0 }; // transparent
+      return {
+        r: parseInt(h.slice(1,3), 16) / 255,
+        g: parseInt(h.slice(3,5), 16) / 255,
+        b: parseInt(h.slice(5,7), 16) / 255,
+        a: 1
+      };
+    };
+
+    const coll = figma.variables.createVariableCollection("MyComponent/Colors");
+    coll.renameMode(coll.modes[0].modeId, "mode1");
+    const mode2Id = coll.addMode("mode2");
+
+    // Create variables from data map
+    const colorData = { "bg/default": ["#0B6BCB", "#636B74"], /* ... */ };
+    const modeOrder = ["mode1", "mode2"];
+    const modeIds = { mode1: coll.modes[0].modeId, mode2: mode2Id };
+    const varIds = {};
+
+    for (const [name, values] of Object.entries(colorData)) {
+      const v = figma.variables.createVariable(name, coll, "COLOR");
+      values.forEach((hex_val, i) => {
+        v.setValueForMode(modeIds[modeOrder[i]], hex_val ? hex(hex_val) : { r:0, g:0, b:0, a:0 });
+      });
+      varIds[name] = v.id;
+    }
+
+    // Return ALL IDs — needed by subsequent calls
+    figma.closePlugin(JSON.stringify({ collId: coll.id, modeIds, varIds }));
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString());
+  }
+})()
+```
+
+**Call 2: Create components using stored IDs, combine and layout**
+
+```js
+(async () => {
+  try {
+    await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
+
+    // Paste IDs from Call 1 as literals
+    const collId = "VariableCollectionId:X:Y";
+    const modeIds = { mode1: "X:0", mode2: "X:1" };
+    const varIds = { /* ... from Call 1 ... */ };
+
+    const getVar = (id) => figma.variables.getVariableById(id);
+    const bindColor = (varId) => figma.variables.setBoundVariableForPaint(
+      { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', getVar(varId)
+    );
+
+    const components = [];
+    for (const mode of ["mode1", "mode2"]) {
+      for (const state of ["default", "hover"]) {
+        const comp = figma.createComponent();
+        comp.name = `mode=${mode}, state=${state}`;
+        comp.layoutMode = 'HORIZONTAL';
+        comp.primaryAxisAlignItems = 'CENTER';
+        comp.counterAxisAlignItems = 'CENTER';
+        comp.layoutSizingHorizontal = 'HUG';
+        comp.layoutSizingVertical = 'HUG';
+        comp.fills = [bindColor(varIds[`bg/${state}`])];
+        comp.setExplicitVariableModeForCollection(collId, modeIds[mode]);
+        // ... add text children ...
+        components.push(comp);
+      }
+    }
+
+    // Combine — all children stack at (0,0)!
+    const cs = figma.combineAsVariants(components, figma.currentPage);
+    cs.name = "MyComponent";
+
+    // CRITICAL: layout variants in a structured grid mapped to variant axes.
+    const stateOrder = ["default", "hover"];
+    const modeOrder2 = ["mode1", "mode2"];
+    const colW = 140, rowH = 56;
+
+    for (const child of cs.children) {
+      const props = Object.fromEntries(
+        child.name.split(', ').map(p => p.split('='))
+      );
+      const col = stateOrder.indexOf(props.state);
+      const row = modeOrder2.indexOf(props.mode);
+      child.x = col * colW;
+      child.y = row * rowH;
+    }
+    // Resize from actual child bounds
+    let maxX = 0, maxY = 0;
+    for (const child of cs.children) {
+      maxX = Math.max(maxX, child.x + child.width);
+      maxY = Math.max(maxY, child.y + child.height);
+    }
+    cs.resizeWithoutConstraints(maxX + 40, maxY + 40);
+
+    // Wrap in section
+    const section = figma.createSection();
+    section.name = "MyComponent Section";
+    section.appendChild(cs);
+    section.resizeWithoutConstraints(cs.width + 200, cs.height + 200);
+
+    figma.closePlugin(JSON.stringify({ csId: cs.id, count: components.length }));
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString());
+  }
+})()
+```
+
+## Read Existing Nodes and Return Data
+
+```js
+(async () => {
+  try {
+    const page = figma.currentPage
+    const nodes = page.findAll(n => n.type === 'FRAME')
+    const data = nodes.map(n => ({
+      id: n.id,
+      name: n.name,
+      width: n.width,
+      height: n.height,
+      childCount: n.children?.length || 0
+    }))
+    figma.closePlugin(JSON.stringify({ frames: data }))
+  } catch (e) {
+    figma.closePluginWithFailure(e.toString())
+  }
+})()
+```