feat(icons): Add dark mode generation via Figma Variable Modes

.github/workflows/release.yml

@@ -319,4 +319,3 @@ jobs:
           git add Formula/exfig.rb
           git diff --staged --quiet || git commit -m "chore: bump to v${{ steps.version.outputs.version }}"
           git push
-

CLAUDE.md

@@ -122,6 +122,9 @@ Twelve modules in `Sources/`:
 **MCP data flow:** `exfig mcp` → StdioTransport (JSON-RPC on stdin/stdout) → tool handlers → PKLEvaluator / TokensFileSource / FigmaAPI
 **MCP stdout safety:** `OutputMode.mcp` + `TerminalOutputManager.setStderrMode(true)` — all CLI output goes to stderr
 **Claude Code plugins:** [exfig-plugins](https://github.com/DesignPipe/exfig-plugins) marketplace — MCP integration, setup wizard, export commands, config review, troubleshooting
+**Plugin sync checklist:** When adding features visible to end users (new dark mode approach, new CLI flag, new MCP tool), update DesignPipe/exfig-plugins skills: `exfig-mcp-usage`, `exfig-config-review` (common-issues.md), `exfig-troubleshooting` (error-catalog.md), `exfig-setup`. Clone to `/tmp/exfig-plugins`, branch, commit, PR.
+
+**Variable-mode dark icons:** `FigmaComponentsSource.loadIcons()` → `VariableModeDarkGenerator` — fetches Variables API, resolves alias chains, replaces hex colors in SVG via `SVGColorReplacer`. Third dark mode approach alongside `darkFileId` and `suffixDarkMode`.
 
 **Batch mode:** Single `@TaskLocal` via `BatchSharedState` actor — see `ExFigCLI/CLAUDE.md`.
 
@@ -229,6 +232,41 @@ When relocating a type (e.g., `Android.WebpOptions` → `Common.WebpOptions`), u
 5. PKL examples (`Schemas/examples/*.pkl`)
 6. DocC docs (`ExFig.docc/**/*.md`), CONFIG.md
 
+### Variable-Mode Dark Icons (VariableModeDarkGenerator)
+
+Three dark mode approaches for icons (mutually exclusive):
+
+1. `darkFileId` — separate Figma file for dark icons (global `figma` section)
+2. `suffixDarkMode` — `Common.SuffixDarkMode` on `Common.Icons`/`Images`/`Colors`, splits by name suffix
+3. `variablesDarkMode` — `Common.VariablesDarkMode` on `FrameSource` (per-entry), resolves Figma Variable bindings
+
+Approach 3 is configured via nested `variablesDarkMode: VariablesDarkMode?` on `FrameSource`.
+Integration point: `FigmaComponentsSource.loadIcons()`.
+
+**Algorithm:** fetch `VariablesMeta` → fetch icon nodes → walk children tree to find `Paint.boundVariables["color"]`
+→ resolve dark value via alias chain (depth limit 10, same pattern as `ColorsVariablesLoader.handleColorMode()`)
+→ build `lightHex → darkHex` map → `SVGColorReplacer.replaceColors()` → write dark SVG to temp file.
+
+Key files: `VariableModeDarkGenerator.swift`, `SVGColorReplacer.swift`, `FigmaComponentsSource.swift`.
+
+**Logging requirements:** Every `guard ... else { continue }` in the generation loop must log a warning — silent skips cause invisible data loss. `resolveDarkColor` must check `deletedButReferenced != true` (same as all other variable loaders). `SVGColorReplacer` uses separate regex replacement templates per pattern (attribute patterns have 3 capture groups, CSS patterns have 2 — never share a single template).
+
+**Config validation:** `Config.init` uses `precondition(!fileId.isEmpty)` — catches the documented empty-fileId bug at construction time instead of relying on call-site guards.
+
+**Alias resolution behaviour:** `resolveDarkColor` alias targets resolve using the target collection's `defaultModeId`, NOT the requested modeId — test expectations must account for this (e.g., alias to primitive resolves via "light" default mode, not "dark").
+
+**pkl-swift decoding:** pkl-swift uses **keyed** decoding (by property name, not positional). TypeRegistry is only for `PklAny` polymorphic types and performance — concrete `Decodable` structs (like `VariablesDarkMode`) decode via synthesized `init(from:)` regardless of `registerPklTypes`. New types should still be added to `registerPklTypes()` for completeness, but missing entries do NOT cause silent nil for concrete typed fields.
+
+**Cross-file variable resolution:** Figma variable IDs are file-scoped — alias targets from the icons file don't exist in library files by ID. When `variablesFileId` is set, variables are loaded from BOTH files: icons file (semantic variables matching node boundVariables) + library file (primitives for alias resolution). Matching is by variable **name** across files and mode **name** across collections (not IDs).
+
+**VariablesCache pattern:** `VariablesCache` (Lock + Task dedup) caches Variables API responses by fileId across parallel entries. Created per platform section in `PluginIconsExport`, injected through `SourceFactory` → `FigmaComponentsSource` → `VariableModeDarkGenerator`. Same pattern applicable to `ColorsVariablesLoader` if needed. Failed tasks are evicted (`lock.withLock { tasks[fileId] = nil }` in catch) — transient Figma API errors (429) don't permanently poison the cache.
+
+**ComponentsCache pattern:** `ComponentsCache` (same Lock + Task dedup) caches Components API responses by fileId across parallel entries in standalone mode. Solves the problem that `ComponentPreFetcher` only works in batch mode (`BatchSharedState` is nil in standalone). Created per platform section in `PluginIconsExport`, injected through `SourceFactory` → `FigmaComponentsSource` → `ImageLoaderBase`.
+
+**Alpha handling:** `SVGColorReplacer` supports opacity via `ColorReplacement(hex, alpha)`. When `alpha < 1.0`, replacement adds `fill-opacity`/`stroke-opacity` attributes (SVG) or `;fill-opacity:N` (CSS). Same hex with different alpha IS a valid replacement (e.g., `#D6FB94` opaque → `#D6FB94` transparent).
+
+**Granular cache path:** `IconsExportContextImpl.loadIconsWithGranularCache()` creates its own `IconsLoader` and bypasses `FigmaComponentsSource` entirely. Variable-mode dark generation must be applied explicitly at the end of that method via `applyVariableModeDark(to:source:)`.
+
 ### Module Boundaries
 
 ExFigCore does NOT import FigmaAPI. Constants on `Component` (FigmaAPI, extended in ExFigCLI) are
@@ -239,7 +277,7 @@ ExFigConfig imports ExFigCore but NOT ExFigCLI — `ExFigError` is not available
 
 ### Modifying SourceFactory Signatures
 
-`createComponentsSource` has 8 call sites (4 in `PluginIconsExport` + 4 in `PluginImagesExport`) plus tests in `PenpotSourceTests.swift`.
+`createComponentsSource` has 8 call sites (4 in `PluginIconsExport` + 4 in `PluginImagesExport`) plus tests in `PenpotSourceTests.swift`. Icons sites pass `componentsCache:`, Images sites use default `nil`.
 `createTypographySource` call sites: only tests (not yet wired to production export flow).
 Use `replace_all` on the trailing parameter pattern (e.g., `filter: filter\n        )`) to update all sites at once.
 
@@ -455,6 +493,13 @@ NooraUI.formatLink("url", useColors: true)  // underlined primary
 | SwiftFormat `#if` indent | SwiftFormat 0.60.1 indents content inside `#if canImport()` — this is intentional project style, do not "fix" |
 | SPM `from:` too loose | When code uses APIs from version X, set `from: "X"` not older — SPM may resolve an incompatible earlier version |
 | Granular cache "Access denied" | `GranularCacheManager.filterChangedComponents` degrades gracefully — returns all components on node fetch error instead of failing config |
+| Empty `fileId` in variable dark | `FigmaComponentsSource` must guard `fileId` not empty before calling `VariableModeDarkGenerator` — `?? ""` causes cryptic Figma API 404 |
+| PKL field always `nil` | `registerPklTypes()` is a performance optimization, NOT a correctness requirement for concrete typed fields. For optional nested PKL objects returning `nil`, check: (1) `pkl eval --format json` confirms field present, (2) unit test with `PKLEvaluator.evaluate()` decodes correctly, (3) trace values at bridge layer (`iconsSourceInput()`) with diagnostic log |
+| Granular cache skips dark gen | `loadIconsWithGranularCache()` in `IconsExportContextImpl` bypasses `FigmaComponentsSource` — must call `VariableModeDarkGenerator` explicitly via `applyVariableModeDark()` helper |
+| Variable dark always empty maps | Alias targets are external library variables — set `variablesFileId` in `VariablesDarkMode` PKL config to the library file ID containing primitives |
+| Figma variable IDs file-scoped | Variable IDs differ between files — alias targets from file A can't be found by ID in file B. Use name-based matching (`resolveViaLibrary`) + mode name matching (not modeId) for cross-file resolution |
+| `assertionFailure` in release | `assertionFailure` is stripped in release builds — add `FileHandle.standardError.write()` as production fallback for truly-impossible-but-must-not-be-silent error paths |
+| Components API called N times | `ComponentPreFetcher` only works in batch mode — use `ComponentsCache` via `SourceFactory(componentsCache:)` for standalone multi-entry dedup |
 
 ## Additional Rules
 

CONFIG.md

@@ -205,25 +205,22 @@ colors = new Common.Colors {
   nameValidateRegexp = "^([a-zA-Z_]+)$"
   // [optional] Replacement pattern using captured groups ($n).
   nameReplaceRegexp = "color_$1"
-  // [optional] Extract light/dark from a single file. Default: false
-  useSingleFile = false
-  // [optional] Suffix for dark mode. Default: "_dark"
-  darkModeSuffix = "_dark"
+  // [optional] Extract light/dark from a single file using name suffix splitting
+  // suffixDarkMode = new Common.SuffixDarkMode { suffix = "_dark" }
   // [optional] Suffix for light high contrast. Default: "_lightHC"
   // lightHCModeSuffix = "_lightHC"
   // [optional] Suffix for dark high contrast. Default: "_darkHC"
   // darkHCModeSuffix = "_darkHC"
 }
 ```
 
-| Field                | Type       | Description                                 |
-| -------------------- | ---------- | ------------------------------------------- |
-| `nameValidateRegexp` | `String?`  | RegExp for validating/capturing color names |
-| `nameReplaceRegexp`  | `String?`  | Replacement pattern with captured groups    |
-| `useSingleFile`      | `Boolean?` | Extract all modes from lightFileId          |
-| `darkModeSuffix`     | `String?`  | Dark mode name suffix (default: `_dark`)    |
-| `lightHCModeSuffix`  | `String?`  | Light HC suffix (default: `_lightHC`)       |
-| `darkHCModeSuffix`   | `String?`  | Dark HC suffix (default: `_darkHC`)         |
+| Field                | Type              | Description                                 |
+| -------------------- | ----------------- | ------------------------------------------- |
+| `nameValidateRegexp` | `String?`         | RegExp for validating/capturing color names |
+| `nameReplaceRegexp`  | `String?`         | Replacement pattern with captured groups    |
+| `suffixDarkMode`     | `SuffixDarkMode?` | Dark mode via name suffix splitting         |
+| `lightHCModeSuffix`  | `String?`         | Light HC suffix (default: `_lightHC`)       |
+| `darkHCModeSuffix`   | `String?`         | Dark HC suffix (default: `_darkHC`)         |
 
 ### VariablesColors (Variables API)
 
@@ -276,10 +273,8 @@ icons = new Common.Icons {
   nameValidateRegexp = "^(ic)_(\\d\\d)_([a-z0-9_]+)$"
   // [optional] Replacement pattern
   nameReplaceRegexp = "icon_$2_$1"
-  // [optional] Extract light/dark from a single file. Default: false
-  useSingleFile = false
-  // [optional] Suffix for dark mode icons. Default: "_dark"
-  darkModeSuffix = "_dark"
+  // [optional] Extract light/dark from a single file using name suffix splitting
+  // suffixDarkMode = new Common.SuffixDarkMode { suffix = "_dark" }
   // [optional] Exit with error when pathData exceeds 32,767 bytes (AAPT limit). Default: false
   // strictPathValidation = true
 }
@@ -297,10 +292,8 @@ images = new Common.Images {
   nameValidateRegexp = "^(img)_([a-z0-9_]+)$"
   // [optional] Replacement pattern
   nameReplaceRegexp = "image_$2"
-  // [optional] Extract light/dark from a single file. Default: false
-  useSingleFile = false
-  // [optional] Suffix for dark mode images. Default: "_dark"
-  darkModeSuffix = "_dark"
+  // [optional] Extract light/dark from a single file using name suffix splitting
+  // suffixDarkMode = new Common.SuffixDarkMode { suffix = "_dark" }
 }
 ```
 
@@ -319,14 +312,17 @@ typography = new Common.Typography {
 
 All Icons and Images entries across platforms extend `Common.FrameSource`, which provides:
 
-| Field                | Type      | Default | Description                                             |
-| -------------------- | --------- | ------- | ------------------------------------------------------- |
-| `figmaFrameName`     | `String?` | —       | Override Figma frame name for this entry                |
-| `figmaPageName`      | `String?` | —       | Filter by Figma page name for this entry                |
-| `figmaFileId`        | `String?` | —       | Override Figma file ID for this entry                   |
-| `rtlProperty`        | `String?` | `"RTL"` | Figma component property name for RTL variant detection |
-| `nameValidateRegexp` | `String?` | —       | Regex pattern for name validation                       |
-| `nameReplaceRegexp`  | `String?` | —       | Replacement pattern using captured groups               |
+| Field                | Type                 | Default | Description                                             |
+| -------------------- | -------------------- | ------- | ------------------------------------------------------- |
+| `figmaFrameName`     | `String?`            | —       | Override Figma frame name for this entry                |
+| `figmaPageName`      | `String?`            | —       | Filter by Figma page name for this entry                |
+| `figmaFileId`        | `String?`            | —       | Override Figma file ID for this entry                   |
+| `rtlProperty`        | `String?`            | `"RTL"` | Figma component property name for RTL variant detection |
+| `variablesDarkMode`  | `VariablesDarkMode?` | —       | Dark mode via Figma Variable bindings (see below)       |
+| `nameValidateRegexp` | `String?`            | —       | Regex pattern for name validation                       |
+| `nameReplaceRegexp`  | `String?`            | —       | Replacement pattern using captured groups               |
+
+**VariablesDarkMode** fields: `collectionName` (required), `lightModeName` (required), `darkModeName` (required), `primitivesModeName` (optional), `variablesFileId` (optional — Figma file ID of the library containing the full variable chain including primitives; required when variables alias to an external library).
 
 **RTL Detection:** When `rtlProperty` is set (default `"RTL"`), ExFig detects RTL support via Figma
 COMPONENT_SET variant properties. Components with `RTL=On` variant are automatically skipped (iOS/Android

README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/DesignPipe/exfig/actions/workflows/ci.yml/badge.svg)](https://github.com/DesignPipe/exfig/actions/workflows/ci.yml)
 [![Release](https://github.com/DesignPipe/exfig/actions/workflows/release.yml/badge.svg)](https://github.com/DesignPipe/exfig/actions/workflows/release.yml)
 [![Docs](https://github.com/DesignPipe/exfig/actions/workflows/deploy-docc.yml/badge.svg)](https://DesignPipe.github.io/exfig/documentation/exfigcli)
-![Coverage](https://img.shields.io/badge/coverage-43.65%25-yellow)
+![Coverage](https://img.shields.io/badge/coverage-43.55%25-yellow)
 [![License](https://img.shields.io/github/license/DesignPipe/exfig.svg)](LICENSE)
 
 Export colors, typography, icons, and images from Figma and Penpot to Xcode, Android Studio, Flutter, and Web projects — automatically. Runs on macOS, Linux, and Windows.

Scripts/generate-llms.sh

@@ -127,8 +127,8 @@ generate_llms_full() {
 
 # ── Main ──────────────────────────────────────────────────────────────────────
 
-generate_llms_txt > "$LLMS_TXT"
-generate_llms_full > "$LLMS_FULL"
+generate_llms_txt | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}' > "$LLMS_TXT"
+generate_llms_full | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}' > "$LLMS_FULL"
 
 LINES_TXT=$(wc -l < "$LLMS_TXT" | tr -d ' ')
 LINES_FULL=$(wc -l < "$LLMS_FULL" | tr -d ' ')

Sources/ExFig-Android/Config/AndroidIconsEntry.swift

@@ -20,12 +20,17 @@ public extension Android.IconsEntry {
             frameName: figmaFrameName ?? "Icons",
             pageName: figmaPageName,
             format: .svg,
-            useSingleFile: darkFileId == nil,
+            useSingleFile: darkFileId == nil && variablesDarkMode == nil,
             darkModeSuffix: "_dark",
             rtlProperty: rtlProperty,
             nameValidateRegexp: nameValidateRegexp,
             nameReplaceRegexp: nameReplaceRegexp,
-            penpotBaseURL: resolvedPenpotBaseURL
+            penpotBaseURL: resolvedPenpotBaseURL,
+            variablesCollectionName: variablesDarkMode?.collectionName,
+            variablesLightModeName: variablesDarkMode?.lightModeName,
+            variablesDarkModeName: variablesDarkMode?.darkModeName,
+            variablesPrimitivesModeName: variablesDarkMode?.primitivesModeName,
+            variablesFileId: variablesDarkMode?.variablesFileId
         )
     }
 

Sources/ExFig-Flutter/Config/FlutterIconsEntry.swift

@@ -16,12 +16,17 @@ public extension Flutter.IconsEntry {
             darkFileId: darkFileId,
             frameName: figmaFrameName ?? "Icons",
             pageName: figmaPageName,
-            useSingleFile: darkFileId == nil,
+            useSingleFile: darkFileId == nil && variablesDarkMode == nil,
             darkModeSuffix: "_dark",
             rtlProperty: rtlProperty,
             nameValidateRegexp: nameValidateRegexp,
             nameReplaceRegexp: nameReplaceRegexp,
-            penpotBaseURL: resolvedPenpotBaseURL
+            penpotBaseURL: resolvedPenpotBaseURL,
+            variablesCollectionName: variablesDarkMode?.collectionName,
+            variablesLightModeName: variablesDarkMode?.lightModeName,
+            variablesDarkModeName: variablesDarkMode?.darkModeName,
+            variablesPrimitivesModeName: variablesDarkMode?.primitivesModeName,
+            variablesFileId: variablesDarkMode?.variablesFileId
         )
     }
 

Sources/ExFig-Web/Config/WebIconsEntry.swift

@@ -16,12 +16,17 @@ public extension Web.IconsEntry {
             darkFileId: darkFileId,
             frameName: figmaFrameName ?? "Icons",
             pageName: figmaPageName,
-            useSingleFile: darkFileId == nil,
+            useSingleFile: darkFileId == nil && variablesDarkMode == nil,
             darkModeSuffix: "_dark",
             rtlProperty: rtlProperty,
             nameValidateRegexp: nameValidateRegexp,
             nameReplaceRegexp: nameReplaceRegexp,
-            penpotBaseURL: resolvedPenpotBaseURL
+            penpotBaseURL: resolvedPenpotBaseURL,
+            variablesCollectionName: variablesDarkMode?.collectionName,
+            variablesLightModeName: variablesDarkMode?.lightModeName,
+            variablesDarkModeName: variablesDarkMode?.darkModeName,
+            variablesPrimitivesModeName: variablesDarkMode?.primitivesModeName,
+            variablesFileId: variablesDarkMode?.variablesFileId
         )
     }
 

Sources/ExFig-iOS/CLAUDE.md

@@ -85,6 +85,12 @@ All asset types support dark variants via `AssetPair<T>`. Pattern:
 - Icons: dark variant filenames suffixed with `D` (e.g., `iconD.pdf`)
 - Images: dark variants in imageset with `appearances: [luminosity: dark]`
 
+**Icons dark mode approaches** (mutually exclusive):
+
+1. `darkFileId` — separate Figma file for dark icons
+2. `useSingleFile` + `darkModeSuffix` — dark icons in same file, split by name suffix
+3. Variable modes — `variablesCollectionName` + mode names → SVG color replacement via `VariableModeDarkGenerator`
+
 ### Output Cleanup
 
 Exporters remove old output dirs (`FileManager.removeItem`) before writing when: