Fugen

Fugen is a command line tool for exporting resources and generating code from your Figma files.

Currently, Fugen supports the following entities:

• ✅ Color styles
• ✅ Text styles
• ✅ Shadow styles
• ✅ Images

Watch the video

Table of context

• Installation
  • CocoaPods
  • Homebrew
  • Mint
  • ZIP archive
• Usage
• Configuration
  • Base parameters
  • Figma access token
  • Figma file
  • Generation configuration
• Color styles
• Text styles
• Shadow styles
• Images
• Communication
• License

Installation:

CocoaPods

To install Fugen using CocoaPods dependency manager, add this line to your Podfile:

pod 'Fugen', '~> 1.4.0'

Then run this command:

$ pod install --repo-update

If installing using CocoaPods, the generate command should include a relative path to the Pods/Fugen folder:

$ Pods/Fugen/fugen generate

Installation via CocoaPods is recommended, as it allows to use the fixed version on all team members machines and automate the update process.

Homebrew

For Homebrew dependency manager installation, run:

$ brew install almazrafi/tap/fugen

It's impossible to set a specific package version via Homebrew. If you chose this method, make sure all team members use the same version of Fugen.

Mint

For Mint package manager installation, run:

$ mint install almazrafi/Fugen@1.4.0

ZIP archive

Every release in the repo has a ZIP archive which can be used to integrate Fugen into a project. To use that method, the following steps should be taken:

• Open repository release page.
• Download the 'fugen-x.y.z.zip' archive attached to the latest release.
• Unarchive files into a convenient project folder

If this integration method was chosen, the generation command should include a relative path to the folder with the ZIP-archive content, for example:

$ Fugen/fugen generate

It's recommended to include unarchived files into the Git index (git add Fugen). It will guarantee that all team members are using the same version of Fugen for the project.

Usage

Fugen provides a simple command for code generation:

$ fugen generate

As the result, the source code files will be received according to the configuration (see Configuration), which by default should be placed to .fugen.yml file.

If you need, you can use a specific path to the configuration, just pass it in the --config parameter. For example:

$ fugen generate --config 'Folder/fugen.yml'

Fugen requests files data using Figma API, so make sure you have the internet connection on while generating the code.

The resulting code could be easily customized with Stencil-templates. If standard templates are not enough, a custom template could be used. Just specify its path in the configuration.

Integration

There is no point to run fugen generate at the build stage, as Fugen doesn't work with local resources, which can be changed during development. All data for code generation is in Figma. Also, there won't be any merge conflicts, if you use design versioning.

So, it is much better to generate code just once and keep it in the Git index. Also run fugen generate for the following reasons:

• to upgrade to a new design version in Figma
• after updating Fugen version

There are also some recommendations on integration based on technologies used in a project. All of them are listed in this section and will be updated as feedback is received.

In case you have any problems or suggestions related to integration, please open the corresponding request in Issues.

CocoaPods

If you are using CocoaPods dependency manager, run code generating command from pre-install event handler in Podfile:

pre_install do |installer|
  system "Pods/Fugen/fugen generate"
end

That will allow connecting the code generation command with updating Fugen version and will reduce the number of commands executed while cloning the project.

🚨 If you want to keep the generated files in the Development Pod, this integration method is ideal. In this case the generation should be run after loading Fugen and before installing all Pods. Otherwise, new files will not be indexed on time and won't get included into the Xcode-project.

Configuration

YAML file is used for Fugen configuration. Define all necessary parameters of code generation in this file.

Configuration is divided into several sections:

• base: base parameters that are actual for all other configuration sections (see Base parameters)
• colorStyles: parameters of color styles generation step (see Color styles).
• textStyles: parameters of text styles generation step (see Text styles).
• images: parameters of the step of loading and generating code for images (see Images).

Any parameter from base section will be inherited and could be overwritten in the section of the particular generation step. If some section of the generation step is missing in the configuration, it will be skipped during fugen generate command execution.

Base parameters

Each step of generation is using the following base parameters:

• accessToken: an access token string that is needed to execute Figma API requests (see Figma access token).
• file: URL of a Figma file, which data will be used to generate code (see Figma file).

In order not to duplicate these fields in the configuration, you can specify them in the base section. They will be used by those generation steps for which these parameters are not defined. For example:

base:
  accessToken: 25961-4ac9fbc9-3bd8-4c43-bbe2-95e477f8a067
  file: https://www.figma.com/file/61xw2FQn61Xr7VVFYwiHHy/Fugen-Demo

colorStyles: { }

textStyles:
  file: https://www.figma.com/file/SSeboI2x0jmeG4QO8iBMqX/Fugen-Demo-iOS

If a base parameter is missing for both the generation step section and in the base section, then as a result of the execution fugen generate command, the corresponding error will be received.

Figma access token

Authorization is required to receive Figma files. The authorization is implemented by transferring a personal access token. This token could be created in a few simple steps:

1. Open account settings in Figma.
2. Press "Create a new personal access token" button in the "Personal Access Tokens" section.
3. Enter a description for the token (for instance, "Fugen").
4. Copy the created token to the clipboard.

Then paste the received access token in the accessToken field of the configuration. It is enough to define it only in the base section if this token allows access to all Figma files, which appear in the configuration. For example:

base:
  accessToken: 25961-4ac9fbc9-3bd8-4c43-bbe2-95e477f8a067
...

You can also set the name of the environment variable in the env field instead of the access token value itself. For example:

base:
  accessToken:
    env: FUGEN_ACCESS_TOKEN
...

If for a certain file you need to use a different access token, it should be specified in the corresponding section of the configuration (see Base parameters).

Figma file

Fugen requests Figma file by using the identifier from its URL. This URL should be placed in the file field of the configuration. For example:

base:
  file: https://www.figma.com/file/61xw2FQn61Xr7VVFYwiHHy/Fugen-Demo
...

In addition to the file identifier itself, the URL could also contain additional parameters and generally has the following format:

https://www.figma.com/file/:id/:title?version-id=:version-id&node-id=:node-id

To get the file, the following parameters are used:

• id: the identifier of the file.
• version-id: the identifier of the file version. If this parameter is omitted, the current version will be used.
• node-id: identifier of the selected frame. If this parameter is present, then only the data from this frame will be used.

The URL of the Figma file opened in the browser can be easily obtained from the address bar.

🚨 Be careful with the node-id parameter, as in Figma the wrong frame could be selected. Then the wrong data will be used for generation.

Alternative configuration

Sometimes using the file URL is not flexible enough. In this case you can define an object with the following fields instead of the URL in the file parameter:

• key: a string with the f