fix: Code Connect using variant node IDs instead of component set node IDs

CLAUDE.md

@@ -247,10 +247,20 @@ as string literals in ExFigCore inits; use shared constants only within ExFigCLI
 ### RTL Detection Design
 
 - `Component.iconName`: uses `containingComponentSet.name` for variants, own `name` otherwise
+- `Component.codeConnectNodeId`: uses `containingComponentSet.nodeId` for variants, own `nodeId` otherwise (Figma Code Connect rejects variant node IDs)
 - `Component.defaultRTLProperty = "RTL"`: shared constant in ExFigCLI for the magic string
 - PNG images intentionally do NOT carry `isRTL` — raster images skip mirroring by design
 - `buildPairedComponents` must use `iconName` (not `name`) — variant `name` is `"RTL=Off"`, not the icon name
 
+### Modifying Node ID Logic (AssetMetadata / ImagePack)
+
+When changing how node IDs are resolved (e.g., `codeConnectNodeId`), update ALL construction sites in `ImageLoaderBase.swift`:
+
+1. `AssetMetadata` in `fetchImageComponentsWithGranularCache` (~line 156)
+2. `AssetMetadata` in `fetchImageComponentsWithGranularCacheAndPairing` (~line 220)
+3. `ImagePack` primaryNodeId in `loadVectorImages` (vector/SVG path)
+4. `ImagePack` primaryNodeId in `loadPNGImages` (raster path)
+
 ### Adding a CLI Command
 
 1. Create `Sources/ExFigCLI/Subcommands/NewCommand.swift` implementing `AsyncParsableCommand`

Sources/ExFigCLI/Loaders/ImageLoaderBase.swift

@@ -152,9 +152,10 @@ class ImageLoaderBase: @unchecked Sendable {
         )
 
         // Build metadata for all assets (for Code Connect and template generation)
-        // Use iconName to get the real name (component set name for variants)
-        let allAssetMetadata = allComponents.map { nodeId, component in
-            AssetMetadata(name: component.iconName, nodeId: nodeId, fileId: fileId)
+        // Use component set data for variants: iconName for name, codeConnectNodeId for node ID.
+        // Figma Code Connect rejects variant node IDs — requires top-level component/component set IDs.
+        let allAssetMetadata = allComponents.map { _, component in
+            AssetMetadata(name: component.iconName, nodeId: component.codeConnectNodeId, fileId: fileId)
         }
 
         guard let manager = granularCacheManager, !allComponents.isEmpty else {
@@ -216,8 +217,8 @@ class ImageLoaderBase: @unchecked Sendable {
         let allComponents = try await fetchImageComponents(
             fileId: fileId, frameName: frameName, pageName: pageName, filter: filter, rtlProperty: rtlProperty
         )
-        let allAssetMetadata = allComponents.map { nodeId, component in
-            AssetMetadata(name: component.iconName, nodeId: nodeId, fileId: fileId)
+        let allAssetMetadata = allComponents.map { _, component in
+            AssetMetadata(name: component.iconName, nodeId: component.codeConnectNodeId, fileId: fileId)
         }
 
         guard let manager = granularCacheManager, !allComponents.isEmpty else {
@@ -505,7 +506,7 @@ class ImageLoaderBase: @unchecked Sendable {
                     isRTL: component.useRTL(rtlProperty: rtlProperty)
                 )
             }
-            let primaryNodeId = components.first?.0
+            let primaryNodeId = components.first.map(\.1.codeConnectNodeId)
             return ImagePack(
                 name: packName,
                 images: packImages,
@@ -645,7 +646,7 @@ class ImageLoaderBase: @unchecked Sendable {
                     )
                 }
             }
-            let primaryNodeId = components.first?.0
+            let primaryNodeId = components.first.map(\.1.codeConnectNodeId)
             return ImagePack(
                 name: packName,
                 images: packImages,
@@ -892,6 +893,13 @@ public extension Component {
         containingFrame.containingComponentSet?.name ?? name
     }
 
+    /// Node ID for Code Connect: component set ID for variants, own ID otherwise.
+    /// Figma Code Connect rejects variant node IDs — use this to avoid
+    /// "node is not a top level component or component set" errors.
+    var codeConnectNodeId: String {
+        containingFrame.containingComponentSet?.nodeId ?? nodeId
+    }
+
     /// Extracts the RTL variant value from the component name (e.g. "Off" from "RTL=Off").
     /// Parses "Property=Value, Property2=Value2" format used by Figma variant components.
     func rtlVariantValue(propertyName: String) -> String? {

Tests/ExFigTests/Loaders/ComponentRTLTests.swift

@@ -156,6 +156,41 @@ final class ComponentRTLTests: XCTestCase {
         XCTAssertFalse(component.useRTL(rtlProperty: ""))
     }
 
+    // MARK: - codeConnectNodeId
+
+    func testCodeConnectNodeId_variantComponent_usesComponentSetNodeId() {
+        let component = makeComponent(
+            name: "RTL=Off",
+            componentSetName: "arrow-left"
+        )
+        // Component set nodeId is "99:0", own nodeId is "1:0"
+        XCTAssertEqual(component.codeConnectNodeId, "99:0")
+    }
+
+    func testCodeConnectNodeId_regularComponent_usesOwnNodeId() {
+        let component = makeComponent(name: "arrow-left")
+        XCTAssertEqual(component.codeConnectNodeId, "1:0")
+    }
+
+    func testCodeConnectNodeId_variantWithMultipleProperties_usesComponentSetNodeId() {
+        let component = makeComponent(
+            name: "State=Default, RTL=Off",
+            componentSetName: "new-orders"
+        )
+        XCTAssertEqual(component.codeConnectNodeId, "99:0")
+    }
+
+    func testCodeConnectNodeId_componentSetWithNilNodeId_fallsBackToOwnNodeId() {
+        // When containingComponentSet exists but has no nodeId (anomalous API response),
+        // should fall back to component's own nodeId
+        let component = makeComponent(
+            name: "RTL=Off",
+            componentSetName: "arrow-left",
+            componentSetNodeId: nil
+        )
+        XCTAssertEqual(component.codeConnectNodeId, "1:0")
+    }
+
     // MARK: - defaultRTLProperty
 
     func testDefaultRTLProperty() {
@@ -168,14 +203,21 @@ final class ComponentRTLTests: XCTestCase {
         name: String,
         description: String? = nil,
         frameName: String = "Icons",
-        componentSetName: String? = nil
+        componentSetName: String? = nil,
+        componentSetNodeId: String? = "99:0"
     ) -> Component {
         let descriptionField = description.map { ", \"description\": \"\($0)\"" } ?? ""
 
         let componentSetField = if let componentSetName {
-            """
-            , "containingComponentSet": { "nodeId": "99:0", "name": "\(componentSetName)" }
-            """
+            if let componentSetNodeId {
+                """
+                , "containingComponentSet": { "nodeId": "\(componentSetNodeId)", "name": "\(componentSetName)" }
+                """
+            } else {
+                """
+                , "containingComponentSet": { "name": "\(componentSetName)" }
+                """
+            }
         } else {
             ""
         }