Skip to content

feat: Add page-level filtering for icons and images#54

Merged
alexey1312 merged 4 commits intomainfrom
alexey1312/add-page-fillter
Feb 11, 2026
Merged

feat: Add page-level filtering for icons and images#54
alexey1312 merged 4 commits intomainfrom
alexey1312/add-page-fillter

Conversation

@alexey1312
Copy link
Copy Markdown
Collaborator

Description

Add optional figmaPageName field to enable page-level filtering for icons and images. Previously, filtering was limited to file → frame, which caused incorrect exports when multiple Figma pages contained identically-named frames. Filtering now supports file → page → frame with a 3-tier fallback: entry → common → nil.

  • Add figmaPageName to PKL FrameSource, Common.Icons, and Common.Images schemas
  • Add pageName to IconsSourceInput, ImagesSourceInput, IconsLoaderConfig, ImagesLoaderConfig
  • Update ImageLoaderBase.fetchImageComponents() filter to check containingFrame.pageName
  • Thread pageName through all loading methods (8 methods in ImageLoaderBase, IconsLoader, ImagesLoader)
  • Update all 8 entry bridge files to pass figmaPageName to source inputs
  • Add --page / -p CLI option to download commands
  • Add commented-out figmaPageName examples to init template configs
  • Add 13 new tests for page name resolution and passthrough
  • Update CONFIG.md with figmaPageName documentation

@alexey1312 alexey1312 changed the title Add page-level filtering for icons and images feat: Add page-level filtering for icons and images Feb 11, 2026
@gemini-code-assist
Copy link
Copy Markdown

Summary of Changes

Hello @alexey1312, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the asset export process by introducing page-level filtering for Figma icons and images. Previously, filtering was limited to the frame level, which could lead to incorrect exports when multiple Figma pages contained frames with identical names. The new functionality allows for more precise control over which assets are exported by specifying the Figma page, thereby preventing naming conflicts and improving the reliability of asset generation. This change impacts configuration, CLI usage, and the core loading logic, ensuring a robust and flexible filtering mechanism.

Highlights

  • Page-Level Filtering: Introduced an optional figmaPageName field across the system to enable filtering of icons and images by their Figma page, resolving issues with identically-named frames across different pages.
  • 3-Tier Fallback Logic: Implemented a new file → page → frame filtering hierarchy with a 3-tier fallback mechanism: entry-specific configuration, common configuration, then nil (no page filter).
  • CLI Integration: Added a new --page / -p CLI option to download commands, allowing users to specify a Figma page name directly from the command line.
  • Schema and Configuration Updates: Updated PKL schemas (FrameSource, Common.Icons, Common.Images), Swift source input structs (IconsSourceInput, ImagesSourceInput), and loader configurations (IconsLoaderConfig, ImagesLoaderConfig) to incorporate the new figmaPageName field.
  • Loader and Export Logic Enhancement: Modified ImageLoaderBase.fetchImageComponents() and related loading/export methods across IconsLoader, ImagesLoader, and DownloadImageLoader to utilize the pageName for filtering.
  • Extensive Testing: Added 13 new unit tests to validate the correct resolution and passthrough of the figmaPageName across various configurations and loading scenarios.
  • Documentation and Examples: Updated CONFIG.md with documentation for figmaPageName and included commented-out examples in initial template configurations for Android, Flutter, iOS, and Web.
  • File Path Handling Improvement: Corrected the Destination.url logic in FileContents.swift and FileWriter.swift to properly handle and create subdirectories when generating file paths, ensuring correct output structure.
Changelog
  • CLAUDE.md
    • Updated internal documentation regarding the process for adding new fields to loader configs and FrameSource, specifically mentioning download command files and a testing indentation 'gotcha'.
  • CONFIG.md
    • Added documentation for the new figmaPageName field in Common.Icons, Common.Images, and FrameSource.
    • Included commented-out figmaPageName examples in the icons and images configuration sections.
    • Updated the inherited fields list for iOS.IconsEntry, iOS.ImagesEntry, Android.IconsEntry, Android.ImagesEntry, Flutter.IconsEntry, Flutter.ImagesEntry, Web.IconsEntry, and Web.ImagesEntry to include figmaPageName.
    • Added figmaPageName to the list of fields that apply the 3-tier fallback logic.
  • Sources/ExFig-Android/Config/AndroidIconsEntry.swift
    • Passed figmaPageName to the IconsSourceInput initializer.
  • Sources/ExFig-Android/Config/AndroidImagesEntry.swift
    • Passed figmaPageName to the ImagesSourceInput initializer.
  • Sources/ExFig-Flutter/Config/FlutterIconsEntry.swift
    • Passed figmaPageName to the IconsSourceInput initializer.
  • Sources/ExFig-Flutter/Config/FlutterImagesEntry.swift
    • Passed figmaPageName to the ImagesSourceInput initializer in two locations.
  • Sources/ExFig-Web/Config/WebIconsEntry.swift
    • Passed figmaPageName to the IconsSourceInput initializer.
  • Sources/ExFig-Web/Config/WebImagesEntry.swift
    • Passed figmaPageName to the ImagesSourceInput initializer.
  • Sources/ExFig-iOS/Config/iOSIconsEntry.swift
    • Passed figmaPageName to the IconsSourceInput initializer.
  • Sources/ExFig-iOS/Config/iOSImagesEntry.swift
    • Passed figmaPageName to the ImagesSourceInput initializer.
  • Sources/ExFigCLI/Context/IconsExportContextImpl.swift
    • Added pageName parameter to IconsLoaderConfig initializations in loadIcons and loadIconsWithGranularCache methods.
  • Sources/ExFigCLI/Context/ImagesExportContextImpl.swift
    • Added pageName parameter to ImagesLoaderConfig initializations in loadImages and loadImagesWithGranularCache methods.
  • Sources/ExFigCLI/Input/DownloadOptions.swift
    • Added a new optional pageName property with --page / -p CLI options.
  • Sources/ExFigCLI/Loaders/DownloadImageLoader.swift
    • Added an optional pageName parameter to loadVectorImages and loadRasterImages.
    • Modified fetchImageComponents to accept an optional pageName and filter components based on containingFrame.pageName.
  • Sources/ExFigCLI/Loaders/IconsLoader.swift
    • Added an optional pageName property to IconsLoaderConfig.
    • Updated IconsLoaderConfig initializers (forIOS, forAndroid, forFlutter, forWeb, defaultConfig) to include pageName and implement the 3-tier fallback logic.
    • Added a pageName computed property to IconsLoader.
    • Passed pageName to loadVectorImages and loadVectorImagesWithGranularCache calls within IconsLoader.
  • Sources/ExFigCLI/Loaders/ImageLoaderBase.swift
    • Added an optional pageName parameter to fetchImageComponents, fetchImageComponentsWithGranularCache, and fetchImageComponentsWithGranularCacheAndPairing.
    • Modified the filtering logic in fetchImageComponents to include pageName if provided.
    • Passed pageName to underlying fetchImageComponents calls in loadVectorImages, loadVectorImagesWithGranularCache, loadVectorImagesWithGranularCacheAndPairing, loadPNGImages, and loadPNGImagesWithGranularCache.
  • Sources/ExFigCLI/Loaders/ImagesLoader.swift
    • Added an optional pageName property to ImagesLoaderConfig.
    • Updated ImagesLoaderConfig initializers (forIOS, forAndroid, forFlutter, forWeb, defaultConfig) to include pageName and implement the 3-tier fallback logic.
    • Added a pageName computed property to ImagesLoader.
    • Passed pageName to loadPNGImages, loadVectorImages, loadPNGImagesWithGranularCache, and loadVectorImagesWithGranularCache calls within ImagesLoader.
  • Sources/ExFigCLI/Output/DownloadExportHelpers.swift
    • Added an optional pageName parameter to fetchImageComponents.
    • Modified the filtering logic in fetchImageComponents to include pageName if provided.
  • Sources/ExFigCLI/Output/FileWriter.swift
    • Updated the logic for determining directory URLs from file.destination.url to correctly handle relative paths containing subdirectories.
  • Sources/ExFigCLI/Resources/Schemas/Common.pkl
    • Added figmaPageName: String? to the FrameSource class with documentation.
    • Added figmaPageName: String? to the Icons class with documentation.
    • Added figmaPageName: String? to the Images class with documentation.
  • Sources/ExFigCLI/Resources/androidConfig.swift
    • Added commented-out figmaPageName examples to the common.icons and common.images sections.
  • Sources/ExFigCLI/Resources/flutterConfig.swift
    • Added commented-out figmaPageName examples to the common.icons and common.images sections.
  • Sources/ExFigCLI/Resources/iOSConfig.swift
    • Added commented-out figmaPageName examples to the common.icons and common.images sections.
  • Sources/ExFigCLI/Resources/webConfig.swift
    • Added commented-out figmaPageName examples to the common.icons and common.images sections.
  • Sources/ExFigCLI/Subcommands/DownloadIcons.swift
    • Added an optional pageName property with --page / -p CLI options.
    • Passed the resolved pageNameValue to the DownloadExportHelpers.fetchImageComponents method.
  • Sources/ExFigCLI/Subcommands/DownloadImages.swift
    • Passed downloadOptions.pageName to loader.loadVectorImages and loader.loadRasterImages.
  • Sources/ExFigConfig/Generated/Android.pkl.swift
    • Added figmaPageName property to Android.IconsEntry and Android.ImagesEntry.
    • Included figmaPageName in the initializers for Android.IconsEntry and Android.ImagesEntry.
  • Sources/ExFigConfig/Generated/Common.pkl.swift
    • Added figmaPageName property to Common_FrameSource protocol and Common.FrameSource class.
    • Included figmaPageName in the initializer for Common.FrameSource.
    • Added figmaPageName property to Common.Icons and Common.Images classes.
    • Included figmaPageName in the initializers for Common.Icons and Common.Images.
  • Sources/ExFigConfig/Generated/Flutter.pkl.swift
    • Added figmaPageName property to Flutter.IconsEntry and Flutter.ImagesEntry.
    • Included figmaPageName in the initializers for Flutter.IconsEntry and Flutter.ImagesEntry.
  • Sources/ExFigConfig/Generated/Web.pkl.swift
    • Added figmaPageName property to Web.IconsEntry and Web.ImagesEntry.
    • Included figmaPageName in the initializers for Web.IconsEntry and Web.ImagesEntry.
  • Sources/ExFigConfig/Generated/iOS.pkl.swift
    • Added figmaPageName property to iOS.IconsEntry and iOS.ImagesEntry.
    • Included figmaPageName in the initializers for iOS.IconsEntry and iOS.ImagesEntry.
  • Sources/ExFigCore/FileContents.swift
    • Modified the url computed property in Destination to correctly handle relative file paths that include subdirectories.
  • Sources/ExFigCore/Protocol/IconsExportContext.swift
    • Added an optional pageName property to IconsSourceInput.
    • Included pageName in the IconsSourceInput initializer.
  • Sources/ExFigCore/Protocol/ImagesExportContext.swift
    • Added an optional pageName property to ImagesSourceInput.
    • Included pageName in the ImagesSourceInput initializer.
  • Tests/ExFigCoreTests/FileContentsTests.swift
    • Added new test cases (testURLWithSubdirectoryPath, testURLWithDeepSubdirectoryPath, testURLPreservesSimpleFileURLPath) to verify correct handling of subdirectory paths in Destination.url.
  • Tests/ExFigTests/Helpers/TestHelpers.swift
    • Updated PKLConfig.make to accept optional iconsPageName and imagesPageName parameters for generating test configurations.
  • Tests/ExFigTests/Input/EnumBridgingTests.swift
    • Added figmaPageName to various entry initializers for comprehensive testing of enum bridging.
  • Tests/ExFigTests/Loaders/IconsLoaderConfigTests.swift
    • Added swiftlint:disable file_length type_body_length directives.
    • Added pageName to IconsLoaderConfig initializers.
    • Introduced new test cases (testForIOS_entryPageNameOverridesCommon, testForIOS_fallbackToCommonPageName, testForIOS_pageNameNilByDefault, testForAndroid_entryPageNameOverridesCommon, testDefaultConfig_usesCommonPageName, testDefaultConfig_pageNameNilByDefault, testPageNamePreservedThroughEntryToSourceToConfig) to verify page name resolution and passthrough.
  • Tests/ExFigTests/Loaders/ImagesLoaderConfigTests.swift
    • Added swiftlint:disable file_length directive.
    • Added pageName to ImagesLoaderConfig initializers.
    • Introduced new test cases (testForIOS_entryPageNameOverridesCommon, testForIOS_fallbackToCommonPageName, testForIOS_pageNameNilByDefault, testDefaultConfig_usesCommonPageName, testDefaultConfig_pageNameNilByDefault, testPageNamePreservedThroughEntryToSourceToConfig) to verify page name resolution and passthrough.
  • Tests/ExFigTests/Output/FileWriterTests.swift
    • Added new test cases (testWriteCreatesSubdirectoriesFromFilePath, testWriteParallelCreatesSubdirectoriesFromFilePath) to ensure FileWriter correctly creates subdirectories based on file paths.
Activity
  • The pull request introduces a new feature for page-level filtering in Figma asset exports.
  • The author, alexey1312, has implemented changes across configuration schemas, core loading logic, CLI options, and testing frameworks.
  • No specific reviewer comments or discussions have been recorded yet for this pull request.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Enhance configurations to allow filtering by Figma page names. This change aids in distinguishing components across pages with identical frame names. Updates include:

- Introduced `figmaPageName` in both `FrameSource` and platform-specific entries.
- Updated relevant loading functions and configurations to acknowledge this filter.
- Improved tests to validate various fallback scenarios for `figmaPageName`.
@alexey1312 alexey1312 force-pushed the alexey1312/add-page-fillter branch from 8206c7c to ddfaba5 Compare February 11, 2026 04:40
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces page-level filtering for icons and images by adding a figmaPageName field. The changes are extensive and well-executed, touching configuration schemas, data loaders, CLI commands, and documentation. The new feature is consistently threaded through all layers of the application, and the accompanying tests are thorough, covering the new logic and fallback behaviors. I've identified a couple of minor maintainability improvements in the test files.

Comment thread Tests/ExFigTests/Loaders/IconsLoaderConfigTests.swift
Comment thread Tests/ExFigTests/Loaders/ImagesLoaderConfigTests.swift Outdated
@alexey1312 alexey1312 merged commit b63fee1 into main Feb 11, 2026
1 check passed
@alexey1312 alexey1312 deleted the alexey1312/add-page-fillter branch February 11, 2026 05:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant