search

iodigital-com / figex

2 stars 0 forks source link

readme

FigEx - Figma Exporter

FigEx is a utility tool to export styles and icons from Figma using the Figma REST API.

Features:

config.json is a simple configuration, telling FigEx what to put where:

{
  "type": "values",
  "templatePath": "../samples/AndroidValues.xml.figex",
  "destinationPath": "~/Downloads/AndroidValuesModeB.xml",
  "defaultMode": "modeB",
  "templateVariables": {
    "templateVarDemo": "\uD83D\uDE80\uD83D\uDE80\uD83D\uDE80"
  }
},
{
  "type": "icons",
  "format": "androidxml",
  "filter": "{% if fullName|startsWith('icon-', true) %} true {% else %} false {% endif %}",
  "fileNames" : "{{ fullName|replaceSpecialChars('_')|lowercase }}",
  "destinationPath": "~/Downloads/icons",
  "clearDestination": true
  }

You can defined template files with Jinja-tokens to generate source code files in any language:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    {{ }}
    {%- for color in colors -%}
    <color name="{{ color.name.snake }}">#{{ color.argb }}</color>
    {% endfor %}
</resources>

Setup in Figma

Nothing to do here really! All you need is the file key from the URL. You can then use this in the configuration (see below).

We use FigEx to export a "style library" file which is not containing the actual visual designs but only colors, text styles, icons and dimensions. The design files then reference this style library. This is a small sample file: https://www.figma.com/design/0VIabis5OosbFC3Q1tYXnT

How to use standalone on macOS / Linux

  1. Make sure Java is installed on your machine, run java --version to confirm
  2. Download a figex.zip from the release list
  3. Extract the zip file and place it in your system
  4. Add the extracted directory to your system's $PATH (macOS)
  5. Create a config file for your project, see the sample/config.json
  6. Create a Figma personal access token
  7. Run export FIGMA_TOKEN="your token"
  8. Run figex -c "path to your config"

How to use standalone on Windows

  1. Make sure Java is installed on your machine, run java --version to confirm
  2. Download a figex.zip from the release list
  3. Extract the zip file and place it in your system
  4. Create a config file for your project, see the sample/config.json
  5. Create a Figma personal access token
  6. Run set FIGMA_TOKEN="your token"
  7. Run java -jar "path to figex jar" -c "path to your config"

How to use as part of your Gradle build system

You can also use FigEx as a gradle dependency, e.g. for your buildSrc in an Android Studio project.

  1. Add JitPack to your buildSrc's settings.gradle

    dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url = uri("https://jitpack.io" }
}
}

  2. Add FigEx to your buildSrc's build.gradle

    implementation("com.github.iodigital-com:figex:Tag|)

    Important: FigEx makes use of com.android.tools:sdk-common as a build dependency, this means there can be a conflict with your Android Gradle Plugin version. If you experience sync issues after adding FigEx, try the following. FigEx will not be able to covert SVG to Android Vector graphics. AGP 8.4.0-8.5.0 is currently tested and working. Consider using FigEx as a standalone tool as an alternative (see above).

    implementation("com.github.iodigital-com:figex:Tag") {
exclude("com.android.tools")
}

  3. Add a Gradle task in the buildSrc

    abstract class ExportFigmaTask : DefaultTask() {

@get:InputFile
var configFile: File = File(IoBuildConfig.rootDir, "config/figex/figex.json")

@get: Input
var token: String = ""

@TaskAction
fun action() = runBlocking {
    try {
        export(
            configFile = configFile,
            figmaToken = requireNotNull(
                System.getenv("FIGMA_TOKEN") ?: token.takeIf { it.isNotBlank() }
            ) { "Missing Figma token" },
        )
    } catch (e: Exception) {
        e.printStackTrace()
        throw e
    }
}
}

  4. Register the task in your main build.gradle

    tasks.register<ExportFigmaTask>("updateFigmaResources").configure { 
    token = ...
    configFile = File(...) // Optional, defaults to config/figex/figex.json
}

  5. Update your Figma resources via gradle:

    gradle updateFigmaResources

Config file

See the example config in the samples directory.

Templating

The templating engine uses Jinja syntax. You can use loops, if statements and more. FigEx's templating is build with jinjava which is also the base of HubSpot's HubL templating system. This means the syntax for if-statements and loops also applies to FigEx, same goes for the filters available. Of course, HubSpot specific variables and functions are not available.

Templating for icon exports

This templating is used in the filter and fileNames configurations.

Templating for values export

This templating is used in the file at the templatePath configuration.

Templating objects

Color

Dimension

Text style

Name

Hint: You can also use Jinja filters to modify the name, e.g. {{ color.name|lowercase|replace("some", "other") }}

Figma

Scale

Build the project