The best design and development teams imbue design and brand consistency across multiple products with 

. When designers and developers collaborate on and regularly contribute to a design system, communication between designers and developers improves since a design system serves as a single source of truth for design guidelines, workflows and elements. By having a design system, everyone understands what set of colors, typography, components, etc. defines the brand and unifies the digital experience. 

A tool for building robust design systems is 

. Unlike most other tools, Figma allows teams to work together on design systems in real-time. Design systems constantly evolve to meet users' growing expectations and/or adopt the latest UI/UX trends and patterns, so using a tool like Figma helps to organize, maintain and easily locate design elements. Plus, Figma provides an 

, which gives developers an easy way to extract CSS code from any design element. This close mapping to code makes developer handoff more seamless. Designers can edit styles and assets within the design system, and developers can view those changes immediately and quickly adapt them into the products. 

 speeds up this process. With a single Storybook addon, 

, a Figma design system (or any design system) gets directly embedded in the addon panel of the Storybook UI. Any updates made to the design system are synced to the Storybook addon, so developers don't have to switch back and forth between Figma and Storybook to implement these updates in code. They no longer need to ask for links to the updated parts of the design system.

Below, I'm going to show you how to embed a Figma file in Storybook with the 

For this tutorial, we will recreate a button component from the 

 with React and write stories that represent the different UI states this component supports (e.g., disabled). Material 3 Design Kit is a Figma community file for Google's 

Before proceeding further, duplicate this file to your Figma account's Draft folder and open it to ensure you have access to the design system. When you navigate to the "Components" page, you should see the buttons in the Figma canvas.

To get started, create a new directory named 

$ mkdir figma-storybook
$ cd figma-storybook
$ npm init -y

Install React and React DOM as dependencies:

: Storybook automatically has built-in TypeScript support, so any components written in TypeScript should work with Storybook with no additional configuration needed.

To style the React component, install two packages of the Emotion library as dependencies:

$ npm install --save @emotion/styled @emotion/react

Within the root of this project's directory, create a 

 directory to this directory. Then, delete the contents of the 

$ mkdir src
$ mv stories src/stories
$ rm -rf src/stories/*

 directory, let's inform Storybook of the new location of this directory:

module.exports = {
  "stories": [
    "../src/stories/**/*.stories.mdx",
    "../src/stories/**/*.stories.@(js|jsx|ts|tsx)"
  ],
  // ...
};

Looking at the design system in Figma, the button's CSS styles can be copied from the Inspect panel.

Using these CSS styles, let's implement the button as a React component.

$ mkdir src/components
$ touch src/components/Button{,.styles}.tsx

 as button categories to avoid any confusion with HTML 

Each category comes with five unique visual states: 

 states purely with CSS via the pseudo-classes 

import React, { ReactNode } from "react";
import S from "./Button.styles";

export interface ButtonProps {
  className?: string;
  children: ReactNode;
  type?: "button" | "submit" | "reset";
  primaryCategory?: "filled" | "outlined" | "text" | "elevated" | "tonal";
  secondaryCategory?: "enabled" | "disabled";
  onClick?: (evt: SyntheticEvent) => void;
}

const Button = ({
  className,
  children,
  type = "button",
  primaryCategory = "filled",
  secondaryCategory = "enabled",
  onClick,
}: ButtonProps): JSX.Element => (
  <S.Button
    type={type}
    className={className}
    primaryCategory={primaryCategory}
    secondaryCategory={secondaryCategory}
    disabled={secondaryCategory === "disabled"}
    onClick={onClick}
  >
    {children}
  </S.Button>
);

export default Button;

import styled from "@emotion/styled";
import { ButtonProps } from "./Button";

const BACKGROUND_COLORS = {
  filled: {
    enabled: "rgba(103, 80, 164, 1)",
    hovered: "rgba(103, 80, 164, 0.92)",
    focusedOrPressed: "rgba(103, 80, 164, 0.88)",
    disabled: "rgba(31, 31, 31, 0.12)",
  },
};

const COLORS = {
  filled: {
    enabled: "rgba(255, 255, 255, 1)",
    hovered: "rgba(255, 255, 255, 1)",
    focusedOrPressed: "rgba(255, 255, 255, 1)",
    disabled: "rgba(28, 27, 31, 0.38)",
  },
};

const Button = styled.button<ButtonProps>`
  background: ${(props) =>
    BACKGROUND_COLORS[props.primaryCategory][props.secondaryCategory]};
  color: ${(props) => COLORS[props.primaryCategory][props.secondaryCategory]};
  border-radius: 100px;
  padding: 10px 24px;
  height: 40px;
  letter-spacing: 0.1px;
  display: flex;
  justify-content: center;
  align-items: center;
  text-align: center;
  font-family: "Roboto";
  font-style: normal;
  font-weight: 500;
  font-size: 14px;
  line-height: 20px;
  text-decoration: none;
  cursor: pointer;
  outline: none;
  transition: 0.3s all;
  border: none;
  pointer-events: ${(props) =>
    props.secondaryCategory === "disabled" && "none"};
  user-select: none;
  position: relative;

  &::after {
    content: "";
    position: absolute;
    top: 0;
    left: 0;
    z-index: 1;
    border-radius: inherit;
    width: 100%;
    height: 100%;
    background-position: center;
    background-image: radial-gradient(
      circle,
      rgba(255, 255, 255, 0.4) 1%,
      transparent 1%
    );
    opacity: 0;
    transition: none;
    will-change: background-size;
  }

  &:hover {
    background: ${(props) =>
      BACKGROUND_COLORS[props.primaryCategory]["hovered"]};
    color: ${(props) => COLORS[props.primaryCategory]["hovered"]};
    box-shadow: 0px 1px 2px rgba(0, 0, 0, 0.3),
      0px 1px 3px 1px rgba(0, 0, 0, 0.15);
  }

  &:focus,
  &:active {
    background: ${(props) =>
      BACKGROUND_COLORS[props.primaryCategory]["focusedOrPressed"]};
    color: ${(props) => COLORS[props.primaryCategory]["focusedOrPressed"]};
    box-shadow: none;
  }

  &:focus {
    &::after {
      background-size: 15000%;
      opacity: 1;
      transition: 0.2s background-size linear;
    }
  }

  &:active {
    &::after {
      background-size: 5000%;
      opacity: 0;
      transition: none;
    }
  }
`;

export default {
  Button,
};

 that's recognizable from Material Design UIs. When the user clicks or touches the button, the ripple spreads out in a circular motion from the point of interaction, like a ripple in water. The ripple gives visual feedback to the user that the element has been clicked or touched.

For Storybook to load the button's font family "Roboto," let's wrap stories with a decorator that adds an Emotion 

 component for injecting global styles like CSS resets and font faces. In this case, the 

 component will import the "Roboto" font family from Google Fonts and make it available to all components rendered in stories.

import { addDecorator } from "@storybook/react";
import { Global, css } from "@emotion/react";

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
};

addDecorator((story) => (
  <>
    <Global
      styles={css`
        @import url("https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700;900&display=swap");
      `}
    />
    {story()}
  </>
));

 state should render a button that's clickable and touchable. The story for the 

 state should render a button that's grayed out and not interactive. 

import { ComponentMeta, Story } from "@storybook/react";
import Button, { ButtonProps } from "../components/Button";

export default {
  title: "Components/FilledButton",
  component: Button,
} as ComponentMeta<typeof Button>;

const Template: Story<ButtonProps> = (args) => <Button {...args}></Button>;

export const Enabled = Template.bind({});

Enabled.args = {
  primaryCategory: "filled",
  secondaryCategory: "enabled",
  children: <span>Enabled</span>,
};

export const Disabled = Template.bind({});

Disabled.args = {
  primaryCategory: "filled",
  secondaryCategory: "disabled",
  children: <span>Disabled</span>,
};

If a designer decides to change the color of the button in the design system, then you would have to launch Figma and open the design system in Figma before being able to see what the new color is and copy the new color from the Inspect panel.

Let's improve this workflow by having the design system readily accessible in Storybook.

To connect stories directly to Figma, install the 

$ npm install --save-dev storybook-addon-designs

module.exports = {
  // ...
  addons: [
    "storybook-addon-designs",
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
  ],
  // ...
};

In Figma, right-click on the filled button with the text "Enabled" and copy its link. 

A link makes navigating large Figma files easier by referencing a specific element within the file. When visiting the link, Figma brings the referenced element to the forefront of the canvas and highlights it.  

 define a story's metadata and determine which addons to apply to a story. In this case, the 

// ...

Enabled.parameters = {
  design: {
    type: "figma",
    url: "https://www.figma.com/file/Jp0btOGVdHYO6XdPnKtpeu/Material-3-Design-Kit-(Community)?node-id=50716%3A11407",
  }
};

 for Figma file, etc.) to embed in the addon panel. 

 as the link to the filled button with the text "Enabled" in the Figma file to embed a live view of the Figma file (zoomed into this button) in the addon panel.

Save the changes and wait for the Storybook UI to reload.

The view has a "Figma" label in the top-left corner, and the user can move around and zoom in (and out of) the Figma file.

Since you have a different link for each component variant, let's repeat these same steps for the 

// ...

Disabled.parameters = {
  design: {
    type: "figma",
    url: "https://www.figma.com/file/Jp0btOGVdHYO6XdPnKtpeu/Material-3-Design-Kit-(Community)?node-id=50716%3A11396",
  }
};

Currently, all you can do within the live view is move around and zoom in (and out of) the Figma file. 

To be able to inspect design tokens and extract CSS code from the live view, we must embed the Figma file with an enhanced spec viewed called 

 type, but it requires providing a Figma access token to Storybook so that the addon can tell the Figma API to render the Figma file using Figspec components.

Copy the Figma access token. Then, create a 

 file within the root of the project directory and add an environment variable named 

STORYBOOK_FIGMA_ACCESS_TOKEN=XXXXXX-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX 

import { ComponentMeta, Story } from "@storybook/react";
import { SyntheticEvent } from "react";
import Button, { ButtonProps } from "../components/Button";

export default {
  title: "Components/FilledButton",
  component: Button,
} as ComponentMeta<typeof Button>;

const Template: Story<ButtonProps> = (args) => <Button {...args}></Button>;

export const Enabled = Template.bind({});

Enabled.args = {
  primaryCategory: "filled",
  secondaryCategory: "enabled",
  children: <span>Enabled</span>,
};

Enabled.parameters = {
  design: {
    type: "figspec",
    url: "https://www.figma.com/file/Jp0btOGVdHYO6XdPnKtpeu/Material-3-Design-Kit-(Community)?node-id=50716%3A11407",
  },
};

export const Disabled = Template.bind({});

Disabled.args = {
  primaryCategory: "filled",
  secondaryCategory: "disabled",
  children: <span>Disabled</span>,
};

Disabled.parameters = {
  design: {
    type: "figspec",
    url: "https://www.figma.com/file/Jp0btOGVdHYO6XdPnKtpeu/Material-3-Design-Kit-(Community)?node-id=50716%3A11396",
  },
};

Restart Storybook so that the environment variable is loaded.

When you click on the button in the live view, a panel with the button's CSS code appears.

: You can click either the button's background or the button's text to get either's CSS code. 

If you change the background color of the button in the Figma file, then that change will automatically be seen in the live view.

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Embedding Figma Files in Storybook

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript