CSS Variables and Theming · Figma Plugins

In order to support light and dark themes in your plugin, you will need to update your call to figma.showUI() and replace applicable, hard-coded color values in your plugin CSS with the CSS variables shown here.

API Details

For your plugin UI to get access to the CSS variables, you will need to call figma.showUI() with the new themeColors option:

figma.showUI(__html__, { themeColors: true, /* other options */ })

This will lead to the following changes to the plugin <iframe>:

A figma-light or figma-dark class will be added to the <html> element in the iframe content
A <style id="figma-style"> element will be added to the iframe content containing a set of CSS variables (--figma-color-bg, --figma-color-text, etc…)

You can then use these variables in your CSS using the var() function. For example:

body {
  background-color: var(--figma-color-bg);
  color: var(--figma-color-text);
}

You can also use the figma-light or figma-dark classes on the <html> element to supply your own theme-specific colors:

.figma-light body {
  background-color: white;
  color: blue;
}

.figma-dark body {
  background-color: black;
  color: red;
}

If the user changes their theme preference in Figma Design, the CSS variables in the plugin iframe will dynamically update with new color values.

Please note a couple of caveats with using this new theme API:

FigJam currently does not support dark mode. If your plugin supports FigJam, you will have access to CSS variables (in beta) corresponding to a FigJam-specific light mode. These variables will be named exactly the same as the ones in Figma, but have different colors. For example, FigJam has a purple accent color whereas Figma has a blue accent color. We only anticipate making minor changes to the FigJam light mode colors while in beta.

FigJam semantic color tokens are currently in beta.

If your plugin UI navigates to another URL, do not use the new themeColors option in figma.showUI().

Theme support for externally-hosted plugin UIs is not available at this time.

Semantic Color Tokens

The tokens we are exposing via the Plugin API use the same underlying schema that powers Dark Mode at Figma. At first glance, this may seem like a ton of tokens (and it is), but we’re really excited to be sharing our system in its purest form with our Plugin developers!

If you learn best by doing and want to explore our semantic tokens in an interactive way, install the Theme Colors Inspector plugin.

Tokens Overview

We’ve defined a naming schema that creates predictable behavior across our tokens. For example, additional hierarchy can be created by adding -secondary or -tertiary to any text, icon, or background color, and interactive behavior can be specified by adding -hover, -selected, -disabled.

Our tokens follow a format of

--figma-color-{type}-{color role}-{prominence}-{interaction}

Type `(required)`

This is the only required parameter, and specifies what is the type of thing we want to color? Our four types are bg, text, icon, and border.

Example variables
--figma-color-bg
--figma-color-text

Color Role `(optional)`

Colors in our UI have specific meaning, so we’ve organized hues around how they are used, rather than the hue itself. For example, our default accent color is -brand, which may shift between blue and purple dependent on context.

Example variables
--figma-color-bg-brand
--figma-color-icon-danger

Prominence `(optional)`

To create hierarchy and adjust visual emphasis, bg, text, and icon support -secondary and -tertiary. Similarly, borders come in two flavors — “default” for a border that acts as a divider, and -strong for a border used as the outline around a more prominent element (like a text input).

Example variables
--figma-color-text-secondary
--figma-color-border-strong

Interaction `(optional)`

Some tokens support -hover and -pressed modifiers for interaction states.

Example variables
--figma-color-bg-brand-pressed
--figma-color-icon-danger-hover

Color Roles

To create consistent meaning around our colors, we’ve organized hues by color role. These modifiers can be added to any type of color token — so for example, “red text” would be --figma-color-text-danger, and a “red background” would be --figma-color-bg-danger.

-brand Our default accent color, which may shift between blue in Figma design and purple in FigJam.

-selected Light blue or purple fills for the backgrounds of a selected element, or a border around a focused element.

-disabled Light grey fills for inactive text, buttons, and inputs that a user cannot interact with.

-component Purple text, icons, and backgrounds for component layer names, as well as features connected to components (like variants)

-danger Red indicators when there is an error, or something a user should urgently attend to.

-warning Yellow indicators used to warn a user about a potential problem, such as a missing font.

-success Green indicators used for confirmation, approval, or when a task has completed.

-inverse Dark grey / white fills used for elements that need to be “the opposite of the background color”.

Frequently Used Tokens

While we have many tokens, there are a handful that are very frequently used, and worth knowing about.

Text Colors

--figma-color-text Our default text color for most titles, tabs, and body text.

--figma-color-text-secondary Our secondary text color for inactive tabs, labels, timestamps, and other text that needs to be “lighter” in order to create hierarchy.

--figma-color-text-tertiary Our tertiary text color primarily used for placeholder text (for example in a search input), or for hierarchy below secondary text.

--figma-color-text-disabled Truly disabled text that a user cannot interact with.

--figma-color-text-onbrand White text used against a Blue / Purple background (for example, the text in our “Share” button).

--figma-color-text-brand Blue or purple text used for things like links.

--figma-color-text-danger Red text used to alert users about an error.

--figma-color-text-warning Yellow text used to warn users about a potential problem.

--figma-color-text-success Green text used for confirmation, and approval.

Background Colors

--figma-color-bg Our default white / light grey background fill for most views (like our file browser, editor sidebars, panels, windows, and modals).

--figma-color-bg-secondary A light grey fill used to create sections on top of a background, as well as for some inputs.

Common Hues

--figma-color-bg-brand Blue or purple fill colors for backgrounds like a blue primary button.

--figma-color-bg-danger Red fill color behind destructive buttons, and error banners.

--figma-color-bg-warning Yellow fill color for warning banners

--figma-color-bg-success Green fill color for confirmation banners.

Borders

--figma-color-border Our default border color for dividers between sections.

--figma-color-border-strong The darker border color we use for secondary outline buttons.

--figma-color-border-selected The blue or purple border color we use for focused / selected inputs.

--figma-color-border-danger-strong The red border color we use around inputs that have an error.

Default Token Values

if you are interested in accessing the default values for these tokens, you can get at them by accessing the <style id="figma-style"/> tag via JavaScript inside your UI code.

const styleTagDefinitions = document.getElementById("figma-style").innerHTML;

Using this, you can run this directly in your console to log the defaults for the current theme.

figma.showUI(
  "<script>console.log(document.getElementById('figma-style').innerHTML)</script>",
  { themeColors: true }
);

List of All Available Color Tokens

Figma Design: Light

Figma Design: Dark

FigJam: Light (Beta)