1-to-1 mapping

Stay organized with collections Save and categorize content based on your preferences.

In this tutorial, we are going to use a PlayBar component designed to graphically display the sound spectrum.

We’ll be creating a PlaybackCard component that contains the PlayBar. The PlayBar component already has an existing implementation (a composable function) in the code called MyPlayBar. Instead of generating code from the Figma component, we want to use the existing implementation. To do so, we'll set up a simple 1:1 mapping from a package in Figma to our code component.

1 to 1 mapping component overview diagram

Download the sample project

We will use the HelloMapping project downloaded in the previous section. Please follow the instructions on the Mapped Components Tutorial page if you haven't already downloaded it.

Existing component in code

  1. In Android Studio, open com/example/helloMapping/MyPlayBar.kt.

    MyPlayBar.kt in the Android view

    The signature of MyPlayBar looks like this.

    fun MyPlayBar(
        modifier: Modifier = Modifier,
        color: Color = Color(0xFFA697BF),
        numPeaks: Int = 8,
    )
    
  2. Click on the Start Interactive Mode button above the preview. You can see the bars animate.

    Preview of MyPlayBar
    Split view button

Copy Figma example

We’ll be using an existing Figma file as an example for this tutorial. Make sure you’re logged into your Figma account.

  1. Download the Figma file 1-to-1-Mapping.fig to your computer.
  2. In Figma, go to the file browser. Along the left-hand side, hover over Drafts. A + icon will appear — click the + icon, then Import to import the 1-to-1-Mapping.fig file that you just downloaded.
  3. Open the imported file in Figma.

    1-to-1-Mapping.fig

Packaging components in Figma

This file has a PlayBar component and a PlaybackCard component. We'll be adding an instance of the PlayBar component into the PlaybackCard. Note that this PlayBar is only static in Figma — a picture to be replaced with the implementation in code.

  1. Open the Relay for Figma plugin.
  2. Select the PlayBar component and click Create UI Package.

    The Figma plugin with the PlayBar component selected
  3. With the package selected, add a description to the summary box, for example, “PlayBar component to display sound spectrum, mapped to MyPlayBar”.

Placing mapped component in a card

Let's add an instance of this PlayBar component into the PlaybackCard component.

  1. Select the PlaybackCard component and click Create UI Package.

    The Figma plugin with the PlaybackCard component selected
  2. Copy and place the instance of PlayBar into the card under the Playbar-Container layer.

    Placing the instance of PlayBar in the PlaybackCard

Writing a mapping file

Use a mapping file to map a packaged component in Figma to the composable function.

  1. Go to your HelloMapping Android Studio project and select the Project view.

    Project view in the dropdown menu
  2. Create a directory ui-package-resources/mappings/ under app/src/main/.

  3. Under mappings/ , create a file called play_bar.map.

    play_bar.map in the Project view

    Copy and paste the following code, then save and close the file. This file tells the code generator how to reach the desired composable function, in this case, com.example.hellomapping.MyPlayBar.

    {
        "target": "MyPlayBar",
        "package": "com.example.hellomapping"
    }
    

Import design from Figma

Let’s now see this component in code!

  1. Add a new named version of your Figma file. Go to File > Save to Version History, and then enter a title and description of your new version (any title and description works here).
  2. In the upper right-hand corner of Figma, click on the Share button. In the dialog box that opens, click Copy link.
  3. Switch to the Android Studio project. Go to File > New > Import UI Packages… from the Android Studio menu bar.
  4. Paste the URL of your Figma file and click Next. If you are on macOS and see a Keychain Access prompt, enter your password and click Always Allow.
  5. Wait for the file to be downloaded. On success, you should see the preview of two components: play_bar and playback_card. Click Finish.
  6. Click Make Project button on the main toolbar to build your project. This may take a couple of minutes. Click on the Build tab at the bottom of Android Studio to view build results.

Inspecting the generated code

  1. In Android view, open app/java/com/example/hellomapping/playbackcard/PlaybackCard.kt, which is the generated Jetpack Compose code for our PlaybackCard Figma component. You’ll see a preview of the imported card.
  2. To confirm this component is functional, click the Start Interactive Mode button above the preview. You can see the bars animate inside the card.

    Preview of PlaybackCard
  3. In the code, search for PlayBarInstance. You can see that the PlayBar nested instance has been mapped to MyPlayBar.

    @Composable
    fun PlayBarInstance(modifier: Modifier = Modifier) {
        MyPlayBar(modifier = modifier)
    }
    

Next Step

Mapping with variants

In the next tutorial, we will create a more advanced mapping using variants in Figma.