@fprad0/skill-master-mcp 0.0.9 → 0.0.11

package/docs/skill-candidates/v0.0.10/figma-generate-library/scripts/bindVariablesToComponent.js

@@ -0,0 +1,110 @@
+/**
+ * bindVariablesToComponent
+ *
+ * Binds design token variables to the visual properties of a component node.
+ * Supports fills, strokes, all padding directions, item spacing, and corner radius.
+ * Only binds properties for which a variable ID is provided in `bindings`.
+ *
+ * This function should be called on each variant individually within a component
+ * set, OR on the component set itself for properties shared by all variants.
+ *
+ * @param {ComponentNode | FrameNode | RectangleNode} component
+ *   The Figma node to mutate. Usually a ComponentNode or one of its children.
+ * @param {{
+ *   fills?: string,
+ *   strokes?: string,
+ *   paddingTop?: string,
+ *   paddingBottom?: string,
+ *   paddingLeft?: string,
+ *   paddingRight?: string,
+ *   itemSpacing?: string,
+ *   cornerRadius?: string
+ * }} bindings
+ *   Each key is a visual property name; each value is a Figma Variable ID
+ *   (e.g. "VariableID:123:456"). Omit a key to skip binding that property.
+ * @returns {{ mutatedNodeIds: string[] }}
+ *   List of node IDs that were mutated (for audit/validation purposes).
+ */
+function bindVariablesToComponent(component, bindings) {
+  const mutatedNodeIds = []
+
+  if (!component) {
+    return { mutatedNodeIds }
+  }
+
+  // --- Fills ---
+  if (bindings.fills) {
+    const fillVar = figma.variables.getVariableById(bindings.fills)
+    if (fillVar) {
+      const existingFills = component.fills
+      if (Array.isArray(existingFills) && existingFills.length > 0) {
+        // Bind the color of the first fill to the variable
+        const boundFill = figma.variables.setBoundVariableForPaint(
+          existingFills[0],
+          'color',
+          fillVar,
+        )
+        component.fills = [boundFill, ...existingFills.slice(1)]
+      } else {
+        // No existing fill — create a solid fill bound to the variable
+        const boundFill = figma.variables.setBoundVariableForPaint(
+          { type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } },
+          'color',
+          fillVar,
+        )
+        component.fills = [boundFill]
+      }
+      mutatedNodeIds.push(component.id)
+    }
+  }
+
+  // --- Strokes ---
+  if (bindings.strokes) {
+    const strokeVar = figma.variables.getVariableById(bindings.strokes)
+    if (strokeVar) {
+      const existingStrokes = component.strokes
+      if (Array.isArray(existingStrokes) && existingStrokes.length > 0) {
+        const boundStroke = figma.variables.setBoundVariableForPaint(
+          existingStrokes[0],
+          'color',
+          strokeVar,
+        )
+        component.strokes = [boundStroke, ...existingStrokes.slice(1)]
+      } else {
+        const boundStroke = figma.variables.setBoundVariableForPaint(
+          { type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } },
+          'color',
+          strokeVar,
+        )
+        component.strokes = [boundStroke]
+      }
+      if (!mutatedNodeIds.includes(component.id)) {
+        mutatedNodeIds.push(component.id)
+      }
+    }
+  }
+
+  // --- Spacing properties (FLOAT variables bound via setBoundVariable) ---
+  const floatBindings = [
+    ['paddingTop', 'paddingTop'],
+    ['paddingBottom', 'paddingBottom'],
+    ['paddingLeft', 'paddingLeft'],
+    ['paddingRight', 'paddingRight'],
+    ['itemSpacing', 'itemSpacing'],
+    ['cornerRadius', 'cornerRadius'],
+  ]
+
+  for (const [bindingKey, figmaProp] of floatBindings) {
+    if (bindings[bindingKey]) {
+      const variable = figma.variables.getVariableById(bindings[bindingKey])
+      if (variable) {
+        component.setBoundVariable(figmaProp, variable)
+        if (!mutatedNodeIds.includes(component.id)) {
+          mutatedNodeIds.push(component.id)
+        }
+      }
+    }
+  }
+
+  return { mutatedNodeIds }
+}

package/docs/skill-candidates/v0.0.10/figma-generate-library/scripts/cleanupOrphans.js

@@ -0,0 +1,127 @@
+/**
+ * cleanupOrphans
+ *
+ * Finds and removes all Figma nodes (pages, frames, components, variables,
+ * and variable collections) that were tagged with the given `dsb_run_id`
+ * by a previous build run. This is safe cleanup: it uses plugin data tags,
+ * never name-prefix matching, so it cannot accidentally delete user-owned nodes.
+ *
+ * Use this when a build run fails mid-way and you need to reset to a clean
+ * slate before retrying. The function traverses the entire document looking
+ * for `dsb_run_id` plugin data matching `runId`.
+ *
+ * Variables and variable collections are handled separately (they are not
+ * scene nodes and cannot be discovered via node traversal).
+ *
+ * @param {string} runId - The dsb_run_id value to match (e.g. "ds-build-2024-001").
+ * @returns {Promise<{
+ *   removedCount: number,
+ *   removedIds: string[]
+ * }>}
+ */
+async function cleanupOrphans(runId) {
+  if (!runId) {
+    throw new Error('cleanupOrphans: runId is required.')
+  }
+
+  const removedIds = []
+  const originalPage = figma.currentPage
+
+  // --- Remove tagged scene nodes (pages, frames, components, etc.) ---
+  // Collect pages to remove (can't remove during iteration)
+  const pagesToRemove = []
+
+  for (const page of figma.root.children) {
+    if (page.getPluginData('dsb_run_id') === runId) {
+      pagesToRemove.push(page)
+      continue
+    }
+
+    // Traverse all nodes on this page
+    await figma.setCurrentPageAsync(page)
+
+    const nodesToRemove = []
+    page.findAll((node) => {
+      if (node.getPluginData('dsb_run_id') === runId) {
+        nodesToRemove.push(node)
+        return false // Don't descend — removing the parent removes its children
+      }
+      return true
+    })
+
+    // Remove deepest nodes first (children before parents) to avoid
+    // "parent no longer exists" errors
+    const sorted = nodesToRemove.sort((a, b) => {
+      // Sort by depth descending: deeper nodes first
+      return getDepth(b) - getDepth(a)
+    })
+
+    for (const node of sorted) {
+      if (node && node.parent) {
+        removedIds.push(node.id)
+        node.remove()
+      }
+    }
+  }
+
+  // Remove tagged pages last
+  for (const page of pagesToRemove) {
+    // Cannot remove the last page in the document
+    if (figma.root.children.length <= 1) {
+      break
+    }
+    removedIds.push(page.id)
+    page.remove()
+  }
+
+  // --- Remove tagged variables ---
+  const allVariables = figma.variables.getLocalVariables()
+  for (const variable of allVariables) {
+    if (variable.getPluginData('dsb_run_id') === runId) {
+      removedIds.push(variable.id)
+      variable.remove()
+    }
+  }
+
+  // --- Remove tagged variable collections ---
+  // Must be done after variables are removed
+  const allCollections = figma.variables.getLocalVariableCollections()
+  for (const collection of allCollections) {
+    if (collection.getPluginData('dsb_run_id') === runId) {
+      removedIds.push(collection.id)
+      collection.remove()
+    }
+  }
+
+  // Restore original page (if it still exists)
+  try {
+    await figma.setCurrentPageAsync(originalPage)
+  } catch (_) {
+    // Original page was removed — switch to first available page
+    if (figma.root.children.length > 0) {
+      await figma.setCurrentPageAsync(figma.root.children[0])
+    }
+  }
+
+  return {
+    removedCount: removedIds.length,
+    removedIds,
+  }
+}
+
+/**
+ * Returns the depth of a node in the document tree.
+ * Root children (pages) have depth 1; their children have depth 2; etc.
+ *
+ * @param {BaseNode} node
+ * @returns {number}
+ */
+function getDepth(node) {
+  let depth = 0
+  let current = node
+  while (current.parent) {
+    depth++
+    current = current.parent
+  }
+  return depth
+}

package/docs/skill-candidates/v0.0.10/figma-generate-library/scripts/createComponentWithVariants.js

@@ -0,0 +1,148 @@
+/**
+ * createComponentWithVariants
+ *
+ * Creates a component set by generating all combinations of `variantAxes`,
+ * building one Figma component per combination, then calling
+ * `figma.combineAsVariants` to produce the component set. After combining,
+ * the variants are repositioned into a grid so they don't all stack at (0, 0).
+ *
+ * @param {{
+ *   name: string,
+ *   variantAxes: Record<string, string[]>,
+ *   baseProps: {
+ *     width: number,
+ *     height: number,
+ *     fills?: Paint[],
+ *     padding?: {top?: number, bottom?: number, left?: number, right?: number},
+ *     radius?: number,
+ *     layoutMode?: 'HORIZONTAL' | 'VERTICAL' | 'NONE',
+ *     itemSpacing?: number
+ *   },
+ *   page: PageNode
+ * }} config
+ *   - `name`: Component set name (e.g. "Button").
+ *   - `variantAxes`: Each key is a variant property name; each value is an array of
+ *     allowed values. All combinations are generated (Cartesian product).
+ *     Example: { Size: ['Small', 'Medium', 'Large'], Style: ['Primary', 'Ghost'] }
+ *     produces 6 variants.
+ *   - `baseProps`: Visual properties applied to every variant.
+ *   - `page`: The PageNode to create components on (must be set as current page by caller).
+ * @param {string} [runId] - Optional dsb_run_id to tag every node.
+ * @returns {Promise<{
+ *   componentSet: ComponentSetNode,
+ *   variants: ComponentNode[]
+ * }>}
+ */
+async function createComponentWithVariants(config, runId) {
+  const { name, variantAxes, baseProps, page } = config
+
+  // Ensure we are on the correct page
+  await figma.setCurrentPageAsync(page)
+
+  // Compute Cartesian product of variant axes
+  const axisNames = Object.keys(variantAxes)
+  const axisValues = axisNames.map((k) => variantAxes[k])
+  const combinations = cartesianProduct(axisValues)
+
+  // Build one component per combination
+  const components = []
+  for (const combo of combinations) {
+    const comp = figma.createComponent()
+
+    // Name: "Property=Value, Property=Value, ..."
+    comp.name = axisNames.map((ax, i) => `${ax}=${combo[i]}`).join(', ')
+
+    // Base geometry
+    comp.resize(baseProps.width, baseProps.height)
+
+    // Fills
+    if (baseProps.fills !== undefined) {
+      comp.fills = baseProps.fills
+    } else {
+      comp.fills = [{ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } }]
+    }
+
+    // Corner radius
+    if (baseProps.radius !== undefined) {
+      comp.cornerRadius = baseProps.radius
+    }
+
+    // Auto-layout
+    if (baseProps.layoutMode && baseProps.layoutMode !== 'NONE') {
+      comp.layoutMode = baseProps.layoutMode
+      comp.primaryAxisAlignItems = 'CENTER'
+      comp.counterAxisAlignItems = 'CENTER'
+      if (baseProps.itemSpacing !== undefined) {
+        comp.itemSpacing = baseProps.itemSpacing
+      }
+    }
+
+    // Padding
+    if (baseProps.padding) {
+      comp.paddingTop = baseProps.padding.top ?? 0
+      comp.paddingBottom = baseProps.padding.bottom ?? 0
+      comp.paddingLeft = baseProps.padding.left ?? 0
+      comp.paddingRight = baseProps.padding.right ?? 0
+    }
+
+    // Plugin data
+    const variantKey = axisNames.map((ax, i) => `${ax}:${combo[i]}`).join('|')
+    comp.setPluginData('dsb_key', `component/${name}/${variantKey}`)
+    if (runId) {
+      comp.setPluginData('dsb_run_id', runId)
+    }
+
+    page.appendChild(comp)
+    components.push(comp)
+  }
+
+  // Combine into a component set
+  const componentSet = figma.combineAsVariants(components, page)
+  componentSet.name = name
+  componentSet.setPluginData('dsb_key', `componentSet/${name}`)
+  if (runId) {
+    componentSet.setPluginData('dsb_run_id', runId)
+  }
+
+  // Grid layout — variants stack at (0, 0) after combineAsVariants; reposition them.
+  const GRID_GAP = 16
+  const cols = Math.max(1, axisValues[axisValues.length - 1]?.length ?? 1)
+  const variantWidth = baseProps.width
+  const variantHeight = baseProps.height
+
+  componentSet.children.forEach((variant, idx) => {
+    const col = idx % cols
+    const row = Math.floor(idx / cols)
+    variant.x = col * (variantWidth + GRID_GAP)
+    variant.y = row * (variantHeight + GRID_GAP)
+  })
+
+  // Resize component set to wrap its children with padding
+  const totalCols = Math.min(cols, combinations.length)
+  const totalRows = Math.ceil(combinations.length / cols)
+  const PADDING = 40
+  componentSet.resize(
+    totalCols * variantWidth + (totalCols - 1) * GRID_GAP + PADDING * 2,
+    totalRows * variantHeight + (totalRows - 1) * GRID_GAP + PADDING * 2,
+  )
+
+  // Position component set at a safe canvas location
+  componentSet.x = 480
+  componentSet.y = 80
+
+  return { componentSet, variants: componentSet.children }
+}
+
+/**
+ * Computes the Cartesian product of multiple arrays.
+ * cartesianProduct([[A, B], [1, 2]]) → [[A,1], [A,2], [B,1], [B,2]]
+ *
+ * @param {Array<string[]>} arrays
+ * @returns {string[][]}
+ */
+function cartesianProduct(arrays) {
+  return arrays.reduce(
+    (acc, curr) => acc.flatMap((combo) => curr.map((val) => [...combo, val])),
+    [[]],
+  )
+}

package/docs/skill-candidates/v0.0.10/figma-generate-library/scripts/createDocumentationPage.js

@@ -0,0 +1,139 @@
+/**
+ * createDocumentationPage
+ *
+ * Creates a new Figma page with a standardized documentation layout: a page
+ * title, optional description, and an ordered list of sections each built by
+ * a caller-supplied `contentFn`. The content function receives the section
+ * frame and may append any nodes to it.
+ *
+ * This function is used for standalone documentation pages (e.g. a Foundations
+ * page, a Getting Started page, or a component page with documentation).
+ * It does not handle component sets — those live on separate pages created by
+ * createComponentWithVariants.
+ *
+ * @param {string} pageName - The Figma page name (e.g. "Foundations", "Getting Started").
+ * @param {{
+ *   title: string,
+ *   description?: string,
+ *   sections: Array<{
+ *     name: string,
+ *     contentFn: (sectionFrame: FrameNode) => Promise<void>
+ *   }>
+ * }} config
+ *   - `title`: Large heading displayed at the top of the page.
+ *   - `description`: Optional subtitle displayed below the heading.
+ *   - `sections`: Ordered list of sections. Each section gets its own frame
+ *     with a heading and is passed to `contentFn` for population.
+ * @param {string} [runId] - Optional dsb_run_id to tag every created node.
+ * @returns {Promise<{
+ *   page: PageNode,
+ *   titleNode: TextNode,
+ *   frameIds: string[]
+ * }>}
+ *   `frameIds` is an ordered list of IDs for the root frame and each section frame.
+ */
+async function createDocumentationPage(pageName, config, runId) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' })
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' })
+  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' })
+
+  // Create and activate the page
+  const page = figma.createPage()
+  page.name = pageName
+  await figma.setCurrentPageAsync(page)
+
+  if (runId) {
+    page.setPluginData('dsb_run_id', runId)
+    page.setPluginData('dsb_key', `page/${pageName}`)
+  }
+
+  const frameIds = []
+
+  // Root scroll container — 1440px wide, auto-height
+  const root = figma.createFrame()
+  root.name = pageName
+  root.layoutMode = 'VERTICAL'
+  root.primaryAxisAlignItems = 'MIN'
+  root.counterAxisAlignItems = 'MIN'
+  root.itemSpacing = 80
+  root.paddingTop = 80
+  root.paddingBottom = 120
+  root.paddingLeft = 80
+  root.paddingRight = 80
+  root.layoutSizingHorizontal = 'FIXED'
+  root.layoutSizingVertical = 'HUG'
+  root.resize(1440, 1)
+  root.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }]
+  root.x = 0
+  root.y = 0
+  page.appendChild(root)
+
+  if (runId) {
+    root.setPluginData('dsb_run_id', runId)
+    root.setPluginData('dsb_key', `frame/root/${pageName}`)
+  }
+
+  frameIds.push(root.id)
+
+  // Page header: title + optional description
+  const header = figma.createFrame()
+  header.name = 'Header'
+  header.layoutMode = 'VERTICAL'
+  header.itemSpacing = 12
+  header.layoutSizingHorizontal = 'FILL'
+  header.layoutSizingVertical = 'HUG'
+  header.fills = []
+  root.appendChild(header)
+
+  const titleNode = figma.createText()
+  titleNode.fontName = { family: 'Inter', style: 'Bold' }
+  titleNode.characters = config.title
+  titleNode.fontSize = 40
+  titleNode.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }]
+  titleNode.layoutSizingHorizontal = 'FILL'
+  header.appendChild(titleNode)
+
+  if (config.description) {
+    const descNode = figma.createText()
+    descNode.fontName = { family: 'Inter', style: 'Regular' }
+    descNode.characters = config.description
+    descNode.fontSize = 16
+    descNode.lineHeight = { value: 24, unit: 'PIXELS' }
+    descNode.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }]
+    descNode.layoutSizingHorizontal = 'FILL'
+    header.appendChild(descNode)
+  }
+
+  // Sections
+  for (const section of config.sections) {
+    const sectionFrame = figma.createFrame()
+    sectionFrame.name = `Section/${section.name}`
+    sectionFrame.layoutMode = 'VERTICAL'
+    sectionFrame.itemSpacing = 20
+    sectionFrame.layoutSizingHorizontal = 'FILL'
+    sectionFrame.layoutSizingVertical = 'HUG'
+    sectionFrame.fills = []
+    root.appendChild(sectionFrame)
+
+    if (runId) {
+      sectionFrame.setPluginData('dsb_run_id', runId)
+      sectionFrame.setPluginData('dsb_key', `frame/section/${pageName}/${section.name}`)
+    }
+
+    // Section heading
+    const sectionHeading = figma.createText()
+    sectionHeading.fontName = { family: 'Inter', style: 'Bold' }
+    sectionHeading.characters = section.name
+    sectionHeading.fontSize = 24
+    sectionHeading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }]
+    sectionHeading.layoutSizingHorizontal = 'FILL'
+    sectionFrame.appendChild(sectionHeading)
+
+    // Invoke the caller's content function to populate the section
+    await section.contentFn(sectionFrame)
+
+    frameIds.push(sectionFrame.id)
+  }
+
+  return { page, titleNode, frameIds }
+}

package/docs/skill-candidates/v0.0.10/figma-generate-library/scripts/createSemanticTokens.js

@@ -0,0 +1,108 @@
+/**
+ * createSemanticTokens
+ *
+ * Creates a batch of Figma variables in the given collection, one per entry in
+ * `tokenMap`. Supports raw values, variable alias references, code syntax, and
+ * scopes. Returns a map of token name → Variable for use in subsequent steps.
+ *
+ * @param {VariableCollection} collection - The target variable collection.
+ * @param {Record<string, string>} modeIds - Map of {modeName: modeId} from createVariableCollection.
+ * @param {Array<{
+ *   name: string,
+ *   type: 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN',
+ *   values: Record<string, string | number | boolean | {type: 'VARIABLE_ALIAS', id: string}>,
+ *   scopes?: VariableScope[],
+ *   codeSyntax?: {WEB?: string, ANDROID?: string, iOS?: string}
+ * }>} tokenMap - Ordered list of token definitions.
+ *   - `name`: Variable name using slash hierarchy (e.g. "color/bg/primary").
+ *   - `type`: Figma variable type.
+ *   - `values`: Map of {modeName: value}. Values can be raw (hex string for COLOR,
+ *     number for FLOAT) or alias objects {type: 'VARIABLE_ALIAS', id: variableId}.
+ *     For COLOR, raw values are accepted as hex strings ("#rrggbb" or "#rrggbbaa")
+ *     and converted to {r, g, b, a} automatically.
+ *   - `scopes`: Array of VariableScope strings. Omit to use [] (hidden/primitive).
+ *   - `codeSyntax`: Platform code syntax strings. Omit to skip.
+ * @param {string} [runId] - Optional dsb_run_id to tag every variable.
+ * @returns {Promise<{variables: Record<string, Variable>}>}
+ *   `variables` maps each token name to its created Variable object.
+ */
+async function createSemanticTokens(collection, modeIds, tokenMap, runId) {
+  const variables = {}
+
+  for (const token of tokenMap) {
+    // Create the variable
+    const variable = figma.variables.createVariable(token.name, collection, token.type)
+
+    // Tag for cleanup
+    variable.setPluginData('dsb_key', `variable/${token.name}`)
+    if (runId) {
+      variable.setPluginData('dsb_run_id', runId)
+    }
+
+    // Set values for each mode
+    for (const [modeName, rawValue] of Object.entries(token.values)) {
+      const modeId = modeIds[modeName]
+      if (!modeId) {
+        throw new Error(
+          `createSemanticTokens: mode "${modeName}" not found in modeIds for token "${token.name}". ` +
+            `Available modes: ${Object.keys(modeIds).join(', ')}`,
+        )
+      }
+
+      let value = rawValue
+
+      // Convert hex strings to Figma RGBA for COLOR type
+      if (token.type === 'COLOR' && typeof rawValue === 'string' && rawValue.startsWith('#')) {
+        value = hexToFigmaColor(rawValue)
+      }
+
+      variable.setValueForMode(modeId, value)
+    }
+
+    // Set scopes (default: empty array = hidden from property pickers / primitives)
+    variable.scopes = token.scopes || []
+
+    // Set code syntax per platform
+    if (token.codeSyntax) {
+      if (token.codeSyntax.WEB) {
+        variable.setVariableCodeSyntax('WEB', token.codeSyntax.WEB)
+      }
+      if (token.codeSyntax.ANDROID) {
+        variable.setVariableCodeSyntax('ANDROID', token.codeSyntax.ANDROID)
+      }
+      if (token.codeSyntax.iOS) {
+        variable.setVariableCodeSyntax('iOS', token.codeSyntax.iOS)
+      }
+    }
+
+    variables[token.name] = variable
+  }
+
+  return { variables }
+}
+
+/**
+ * Converts a hex color string to a Figma RGBA object.
+ * Supports "#rgb", "#rrggbb", and "#rrggbbaa".
+ *
+ * @param {string} hex
+ * @returns {{ r: number, g: number, b: number, a: number }}
+ */
+function hexToFigmaColor(hex) {
+  let h = hex.replace('#', '')
+
+  // Expand shorthand #rgb → #rrggbb
+  if (h.length === 3) {
+    h = h
+      .split('')
+      .map((c) => c + c)
+      .join('')
+  }
+
+  const r = parseInt(h.substring(0, 2), 16) / 255
+  const g = parseInt(h.substring(2, 4), 16) / 255
+  const b = parseInt(h.substring(4, 6), 16) / 255
+  const a = h.length === 8 ? parseInt(h.substring(6, 8), 16) / 255 : 1
+
+  return { r, g, b, a }
+}

package/docs/skill-candidates/v0.0.10/figma-generate-library/scripts/createVariableCollection.js

@@ -0,0 +1,49 @@
+/**
+ * createVariableCollection
+ *
+ * Creates a new Figma variable collection with the specified name and modes.
+ * If `modeNames` has more than one entry, the first mode is renamed from
+ * Figma's default "Mode 1" to the first name, and additional modes are added.
+ *
+ * Every created collection is tagged with `dsb_key` plugin data so it can be
+ * found and cleaned up idempotently by `cleanupOrphans`.
+ *
+ * @param {string} name - The display name of the collection (e.g. "Color", "Spacing").
+ * @param {string[]} modeNames - Ordered list of mode names (e.g. ["Light", "Dark"] or ["Value"]).
+ * @param {string} [runId] - Optional dsb_run_id to tag for cleanup.
+ * @returns {Promise<{
+ *   collection: VariableCollection,
+ *   modeIds: Record<string, string>
+ * }>}
+ *   `modeIds` maps each mode name to its modeId string.
+ */
+async function createVariableCollection(name, modeNames, runId) {
+  if (!modeNames || modeNames.length === 0) {
+    throw new Error('createVariableCollection: modeNames must have at least one entry.')
+  }
+
+  // Create the collection — Figma always creates it with one mode named "Mode 1".
+  const collection = figma.variables.createVariableCollection(name)
+
+  // Tag for idempotent cleanup
+  collection.setPluginData('dsb_key', `collection/${name}`)
+  if (runId) {
+    collection.setPluginData('dsb_run_id', runId)
+  }
+
+  // modeIds accumulator
+  const modeIds = {}
+
+  // Rename the default first mode
+  const defaultMode = collection.modes[0]
+  collection.renameMode(defaultMode.modeId, modeNames[0])
+  modeIds[modeNames[0]] = defaultMode.modeId
+
+  // Add additional modes
+  for (let i = 1; i < modeNames.length; i++) {
+    const newModeId = collection.addMode(modeNames[i])
+    modeIds[modeNames[i]] = newModeId
+  }
+
+  return { collection, modeIds }
+}