Skip to content

Using Theme UI as the starting point for your Figma design & Gatsby development

22/04/20204 min readCategory: General

As most developers I didn't want to do yet another todo app to learn a new framework/language. In my case I wanted to solidify my knowledge about Svelte (and TypeScript) after using the former only in the official tutorial. Luckily I found the perfect problem: A problem that I had and wanted to be solved! The end result is a Theme UI Figma plugin (GitHub) that enables a workflow where Theme UI is the starting point for both design & development. And this blog post should explain how that could look like.

Please keep in mind that the plugin is in its early stages (contributions are welcome!) and the process described here itself is not the "ultimate" way of approaching design & development workflow. It's one of the many options. And with that out of the way, let's get started:

#In the beginning there is only a Theme UI config

So, what even is Theme UI? For me personally it's the missing piece between React and CSS-in-JS styling solutions. Using plain Emotion still enabled me to get into bad habits of e.g. using different CSS for things that actually should look the same / feel consistent. Designing with constraints — but still being able to break out of those in one-off cases — is a huge step forward in creating interfaces more quickly and coherent. I think the docs also phrase it in a nice way:

One of the primary motivations behind Theme UI is to make building themeable, constraint-based user interfaces in React as simple and as interoperable as possible. This library builds upon years of work on various libraries, including Basscss, Tachyons, Rebass, Styled System, and various other internal style guides and design systems. While some of the ideas encapsulated within this library may seem familiar, the intent here is to combine modern CSS tooling into a single "mini-framework" with good guidance on how to fall into the pit of success for creating white-label products, themed component libraries, and even full websites.

As the title of this blog posts says you should start with a Theme UI config file (more on that at the end at "Possible improvements"). It can be as simple as:

module.exports = {
  space: [0, 4, 8, 16, 32, 64],
  fonts: {
    body: '-apple-system, BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji"',
    heading: 'inherit',
  fontSizes: [12, 14, 16, 20, 24, 32],
  fontWeights: {
    body: 400,
    heading: 700,
  lineHeights: {
    body: 1.5,
    heading: 1.125,
  colors: {
    text: '#000',
    background: '#fff',
    brand: {
      primary: '#07c',
      secondary: '#30c',
    teal: [null, '#e6fffa', '#b2f5ea', '#81e6d9'],

Save that file as index.js somewhere where you'll find it again. Above config is taken from the Figma Theme UI README as it will generate both typography and color styles in Figma. The theme file can be extended of course, have a look at the spec for that. Lastly, you can use one of the many presets, too. Note: You need to make sure to use module.exports syntax in index.js — and no other content than the config is allowed. Otherwise the Figma plugin has problems parsing your config.

#Figma plugin

First, open Figma and go to the Community tab. Search for Theme UI there — alternatively you can find the plugin with this direct link. After installation you should be able to use it after a Right click => Plugins => Theme UI.

Press the Upload config button and choose the created index.js file. When it successfully loaded you'll be able to toggle two options:

After pressing Apply Styles local styles should appear on the right sidebar. You now can use them in the file you're in or can publish them to your global library.

#Usage in Gatsby

To showcase how to use Theme UI in a React app you'll use Gatsby, as it's easy to get started with and has a plug-n-play plugin for Theme UI.

Install two packages:

npm install theme-ui gatsby-plugin-theme-ui

Add the plugin to your gatsby-config.js:

module.exports = {
  plugins: ["gatsby-plugin-theme-ui"],

And place the aforementioned index.js inside the folder src/gatsby-plugin-theme-ui.

You now can use Theme UI, for example in a header:

/** @jsx jsx */
import { jsx } from "theme-ui"
export default props => (
      // this uses the value from `[2]`
      padding: 2,
      // these use values from `theme.colors`
      color: "background",
      backgroundColor: "brand.primary",

The values used here are directly coming from the config file.

#So, how does the workflow look like?

Until now I've only really explained how you can use Theme UI in Figma and Gatsby but not necessarily how you can use this in your workflow. I personally often use (for my OSS projects) a derivation of the TailwindCSS config, so I tweak some colors, change the font. But I already know how the general Theme UI config should look like.

Or a designer uses tools like Leonardo to generate a palette for you and after converting it to Theme UI you'll need to have it in Figma itself.

#Possible improvements

You rightfully say now: But wait, this only works in one direction! And that is true, it only currently works from Theme UI config => Figma. And I already see value in this workflow. However, it would be really cool to also have Figma => Theme UI. And that request is written down in this GitHub issue. It's something I'll definitely do and I would appreciate any help you might offer!

Once this is implemented the feedback cycle is really short and you can more easily try out other properties.

Sparked your interest? Read all posts in the category General

More posts