Includes and Font mappings

Includes

On the Includes tab, we can specify files or special components to include on pages running components in this project.

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 Running the CLI

Figma 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 solve this you can add mapping rules to translate the web font names into the correct font names to look for on your system.

Editing the font mapping

To update how fonts are mapped:

1. At the bottom left of your screen, click the settings icon to open Design System Settings

2. Go to the Font Mapping tab on the top

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

rule - allows you to specify:

• The fontFamily you would like to match. You can get the name value to set for this fontFamily by inspecting the css styles on the element in the browser preview.

• (Optional) The fontSize this rule applies to.

value - value you would like to override when there is a match on that rule. You can get the target fontFamily name from the font selector dropdown in Figma (available when you have the correct font installed)

Once you have updated your font map, commit your changes to your Design System Project to push the update through to Figma.

Here is a walkthrough of configuring a font map:

Walkthrough: Font mapping

Font map 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" }
	}
]

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" }
	}
]

Extensions

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:

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.

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