Project Settings

Project Settings overview

To access settings for your Project, click on the Settings cog icon at the bottom left of your screen.

This will open the project settings dialog:

image

In here you'll find tabs for:

General settings - set name and description for your library and toggle functionality on and off

Includes - edit the files and Projects included in this Project

Extensions - extend Interplay with custom functionality

Fonts - map web fonts to their desktop equivalents

These are described in more detail in the sections below.

General Settings

image

On the General Settings tab of project settings you can specify the following:

Name - the display name of this Project

Summary - a description of this Project

Icon - an image to use in cards (tiles) display of your Project

Published as Design System - toggle this to on to make the content of this Project available to be included in Figma and other Projects (paid plans only)

Includes Settings

On the Includes tab, we can specify settings for files to include for components in this project.

image

Wrapping Component - Specify any top-level component such as a ThemeProvider that your imported code components require. This wrapping component must be exported from your build along with your other code components.

Include Components - Specify any component that must be included on the page when your imported code components are run e.g. GlobalStyles

Include Files - Specify URLs of any files that need to be included on the page with your components e.g. externally hosted CSS files. You can also deploy and include CSS files from your repo during your import.

Regenerate Thumbnails - Changing include settings often will change the appearance of your components presets (e.g. if new styles are now included on the page). To regenerate the preset navigation thumbnails with your new settings, click "Regenerate Thumbnails".

For more detail about these settings please see

Extensions

image

You can add code snippets to Interplay to extend or customise its behaviour. You can add your code snippet inline or point to a hosted snippet.

To add an Extension:

  1. Go to Project Settings > Extensions Tab > click 'Add Extension'
  2. Give your extension a name and description
  3. Either enter a URL to your hosted code snippet, or switch to the Editor tab to enter your code snippet inline

Example: Passing live tokens as a computed theme property

For example, you might add a code snippet that reads live Tokens in your project and passes them to your code components as a theme object.

To do this, we would create an extension. In the extension code we assign a name of Base Theme Provider:

image

Add the code to populate a theme object from the live tokens in the Interplay project context:

const flatten = (obj, res = {}) => {		
	//flatten object implementation
}

const set = (obj, path, value) => {
  //set object attribute implementation
};

interplay.addExtension({
  id: 'baseTheme',
  name: 'Base Theme Provider',
  type: 'ComputedValue',
  value: (context) => {
    const { tokens } = context;
    const tokenNames = Object.keys(tokens);
    
    const themeTokens = {};
    tokenNames.forEach((tokenName) => {
      const token = tokens[tokenName];
      set(themeTokens, tokenName, token.value);
    }, {});

    // flatten the colors and fonts
    return {
      ...themeTokens,
      colors: flatten(themeTokens.colors),
      typography: {
        ...themeTokens.typography.theme,
        ...themeTokens.typography.primary,
        ...themeTokens.typography.mono,
      }
    };
  },
});

This computed theme property is then available to set on the project wrapper component that passes the theme to the components.

So we Edit Properties of our imported Wrapper component, set the input type to Computed Value (i.e. not user input) and choose the Base Theme Provider computed value we created above.

image

Now when we edit the design tokens in our project they will be dynamically passed to the code components in the theme object.

Custom Font Mappings

Sometimes the font rendered in Figma looks different to how it's displayed on the web. This usually happens if you are using system fonts or custom web fonts.

The issue here is these fonts often have a different name in your operating system than they do on the web, so we cannot automatically select the correct typeface settings in Figma based on the css font style settings.

To work around this you can add rules to translate the web font styles into the correct names we can look for on your system.

image

Each mapping is an object with two parts, the rule and the value:

rule - what you would like to match: specify the fontFamily to match and can optionally also the fontSize this rule applies to

value - value you would like to override when there is a match on that rule

Editing the font mapping for your Project

To update how fonts are mapped:

  1. Go to Project Settings > Fonts tab
  2. Click on the Settings icon in the bottom left
  3. Go to the Font Mapping tab on the top

Examples

Custom Web Fonts

Here's an example of how you would specify what fontFamily you would like to use in Figma when your components use the popular Inter variable font in the browser.

[ 
  {
    "rule": { "fontFamily": "Inter var" },
    "value": { "fontFamily": "Inter" }
  }, 
]

System fonts

System fonts are a little tricky because what's rendered in the browser depends which operating system and version you are running. You can let Interplay know which fonts to use for system fonts by using the font mapping.

You can also use advanced matching rules if the font rules change depending on the size. An example of when you would need this is how Apple use the SF Display fonts on larger font sizes.

[ 
  {
    "rule": { "fontFamily": "-apple-system", "fontSize": { ">": 19 } },
    "value": { "fontFamily": "SF Pro Display" }
  },
  {
    "rule": { "fontFamily": "-apple-system" },
    "value": {  "fontFamily": "SF Pro Text" }
  } 
]

Font mapping walkthrough

For demo purposes, let's map a web font used by Auth0's Cosmos components to a completely different font in Figma. Ordinarily of course you would be mapping to the correct Figma font for your components. For this walkthrough we'll map to Happy Monkey so we can easily see the difference.

  1. After importing the cosmos components into Interplay, here is the Alert component as it normally appears in the browser:
  2. image
  3. From our knowledge of the component, or by inspecting the component in the browser we see that it is using the fakt-web font family.
  4. image
  5. Go to Project Settings > Fonts to access the font map
  6. Add a mapping to map fakt-web to another font in Figma, in this case Happy Monkey
image

  1. Like all edits, this edit of the Project settings is noted as a pending change on the Version History tab in Interplay:
  2. image
  3. We enter a description of the change and choose Commit Changes.
  4. When we use the component in Figma, we find it is now rendered using the Happy Monkey font:
  5. image

Default Font Maps

These are the common font mappings Interplay is preconfigured with.

[ 
  {
    "rule": { "fontFamily": "Inter var" },
    "value": { "fontFamily": "Inter" }
  }, 
  {
    "rule": { "fontFamily": "-apple-system", "fontSize": { ">": 19 } },
    "value": { "fontFamily": "SF Pro Display" }
  },
  {
    "rule": { "fontFamily": "-apple-system" },
    "value": {  "fontFamily": "SF Pro Text" }
  } 
]