Limitations and troubleshooting

Figma and translation limitations

Supported Figma layer types

Relay only supports the following layer types:

  • Text nodes
  • Image nodes (PNG, JPEG, etc.)
  • Frame nodes (autolayout and non-autolayout)
  • Components and variants, component instances
  • Vector nodes

Unsupported Figma layers and features

  • Prototyping features
  • Masking groups
  • Slice layers

Unsupported Figma properties

There are several unsupported properties, including:

  • Inner shadow, layer blur, and background blur
  • Layer rotation (vector rotation is supported)
  • Layer or stroke blend modes (fill blend mode is supported)
  • Text properties:
    • Paragraph spacing
    • Paragraph indent
    • Number styling
    • Letterforms
    • Stylistic sets
    • Strikethrough and underline
    • Line height (still works when applied to the entire text element)
  • Vector properties:
    • Features not supported by Android’s VectorDrawable format:
      • Embedded bitmap images
        • Except for rectangles, which are supported as images rather than vectors
      • Dashed strokes
      • Blur
      • Shadow
      • Pattern
      • Mask
      • Group opacity
      • Radial gradient focal point
    • Features not supported by the SVG format:
      • Angular gradients
      • Diamond gradients
    • Boolean operations between vector objects (union / subtract / intersect / exclude)
      • A workaround is to combine and flatten into a single vector

Partially supported Figma layers and properties

  • Text truncation (ellipsis) works most reliably when the text item is only one line
  • Fill color:
    • Images can only have one image fill, but can have additional fills of other types (e.g., gradients)
    • For gradients, only linear is supported. Future releases will provide additional support for the remaining gradient types (radial, diamond, and angular).
    • In the Figma plugin, there isn’t a way to specify that a parameter can accept multiple fills. If you want to parameterize a fill color, only solid colors are currently supported for parameters
  • Drop shadows:
    • Drop shadows currently do not work on the following layers:
      • Non-rectangular vectors
      • Rotated rectangular vector
    • Multiple drop shadows per layer are not supported.
    • Drop shadow blend modes other than “Normal” are only available on Android versions 10+ (ignored otherwise).
    • Drop shadows on layers are only available on Android versions 9+, except text, which is available on all Android versions supported by Compose.
    • Shadows will always show behind transparent layers in Compose.
  • Absolute positioning within Auto Layout:
    • Absolutely positioned objects must be either behind or in front of all of the auto-layout elements in the frame. Any absolute positioned objects that are layered between auto-layout elements will be pushed to the front of these objects.
    • Nesting auto-layout frames with absolutely positioned objects inside other auto-layout frames can result in incorrect layout, since the bounding box of the nested frame is affected by the positioned items in that frame.

Multiple styles are dropped if passed into text parameter with one style

If a parent component tries to pass text with multiple styles into a nested component text parameter with only one style, the multiple styles are lost in the generated Compose code. Only the original style of the text parameter is kept.

This degradation is necessary to avoid type mismatches that prevent generated code from compiling. If the text in a component has multiple styles, the generated composable will have an AnnotatedText parameter. If the text in a component has only one style, the generated composable will have a plain String parameter. In the above scenario, we need to convert the parent component’s rich text from AnnotatedText to String, dropping the multiple styles, so that it can be passed to the nested component instance.

Nested components with same variant properties as parent component fails to compile

If two components have a [design variant]{:.external} with the same property name, and one nests the other, then in generated code, the enums created for the two variants will have the same name, and there will be a compile error:

Conflicting import, imported name '(variant property)' is ambiguous

To work around this, change the variant property name of one of the components.

Font support

We currently only support fonts from Google Fonts.

Android Studio troubleshooting

I received an error about converting SVG resources on Windows

FAILURE: Build failed with an exception.
*   What went wrong:
Execution failed for task ':app:generateDebugRelayCode'.
> A failure occurred while executing com.google.relay.gradle.GenerateCode$GenerateCodeWorkAction
      > Converting SVG files: Exception Converting SVG resources for my_packaged_component
        The syntax of the command is incorrect

Your Android Studio project name may be too long. On Windows, the full path of the Android Studio project must be no more than 70 characters. We are working to increase this length in a future release.

Updates are not imported into Android Studio

The plugin will only pull down the latest named version of your Figma file. Double check that you have created a new named version of your Figma file with the changes.

I receive an error about SVG and Java Runtime when building

Converting SVG Files: Exception running shell command 'cd /path-to/relay/bin; path/to/relay/bin/vd-tool -c -in path/to/hello_card -out /var/folders/...'.
The operation couldn't be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.

Install Java Runtime, then build again.

I receive an error about fonts when building

You may see an error similar to:

FAILURE: Build failed with an exception.
*   What went wrong:
Execution failed for task ':app:generateDebugRelayCode'.
> Multiple task action failures occurred:
   > A failure occurred while executing com.google.relay.gradle.GenerateCode$GenerateCodeWorkAction
      > /Users/me/AndroidStudioProjects/MyProject/app/build/generated/res/relay/debug/font/relay_inter_bold.ttf
   > A failure occurred while executing com.google.relay.gradle.GenerateCode$GenerateCodeWorkAction
      > /Users/me/AndroidStudioProjects/MyProject/app/build/generated/res/relay/debug/font/relay_inter_bold.ttf

This is caused by a race condition: multiple components trying to copy the same font to the same directory. We are working to fix this problem. Meanwhile, simply try building again.

In Android Studio, undoing a deleted UI Package folder may fail

If you delete a UI Package folder within the ui-packages folder in Android Studio, and then undo the deletion, any file within that folder that had not been opened before deletion may not be restored properly.

Workaround: Re-import the version of the Figma file that you need using File > New > Import UI Packages… You can also click on every file within the UI Package folder upon import, to ensure they will be restored properly.

Updating resources outside ui-packages do not force a new build

Updating a dependency located outside the ui-packages directory (such as a theme mapping file or reference component file) does not force code to be regenerated when you build the project.

Workaround: To force an update to generated code, clean the project (go to Build > Clean Project) or delete the generated code folder associated with the UI Package that needs to be updated. Then, build again.

Generated code or ui-packages folders are missing in Android project browser

In some cases, folders generated by the Relay for Android Studio plugin don't appear in the Android project browser.

Workaround: To reload project folders, right-click on a top-level folder and select "Reload from Disk."

App themes for child components are not updated

When a parent component is re-imported with a new app theme, its child components (listed in DEPS.txt) will not pick up the new theme.

Workaround: Copy the preview theme from the parent component's config.json, and replace the child components' preview themes with it in each respective config.json. After you rebuild, the themes in the child components' generated code will be fixed.

UI Package name must start with letter

If a UI Package name does not start with a letter, Relay will generate Compose code that does not compile, with an error message that says The resource name must start with a letter.

Workaround: In Figma, rename the UI Package name so it starts with a letter.

Font padding in Compose does not match Figma

Figma and Compose lay out text within its bounding box differently. Compose adds more padding along the top of the bounding box.

Workaround: You will have to move the text location in Figma up a few pixels to get it to line up correctly in Compose. We are working on a permanent fix.