CSS Variables and Theming
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
orfigma-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 infigma.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}
(required)
Type 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
(optional)
Color Role 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
(optional)
Prominence 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
(optional)
Interaction 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 }
);