A "welcome" is in order, and let's also set some expectations while we are at it!

An Introduction to Figma, Figmagic, and Design Systems

I hope you are excited! We'll be using some very nice tools and some skeletons I've pre-provided to fast-track our way to a design system!

The course project

Introduction

Let's take care of the essentials first, like setting up a development environment, Git and Node.

Prerequisites

Figma reshaped how millions of people and companies follow the design process. Now, we're going to form our process around it.

An Intro to Figma: Shortcuts, Frames, and Components

Get a spot in the world's biggest (probably!?) JavaScript community—NPM.

How to Set up NPM to Publish JavaScript Packages

Get hooked up with the premier place on the planet to share, build, and discuss code—open source or otherwise.

Setting up GitHub

Next stop is hosting, where we'll use Cloudflare Pages, one of the most exciting tech services around.

Setting up Cloudflare

Last but not least, we need to get our visual inspection platform and Storybook hosting working. For this, we will turn to Chromatic.

Setting up Chromatic

Preparation

Let me introduce you to my take on the concept of "continuous design."

An Intro to Continuous Design: DevOps for Design

Time to set the stage and see what we can do to be a top shop using continuous design principles and tooling.

Build a Continuous Design Workflow With a Design System

A diagram can be the difference between an organization of "petty kings" doing their own thing and having actionable plans built on a shared identity. What we need is some kind of governance.

Build Better Design and Change Governance With Flows

One magic, simple concept (design token) and a one-stop shop to contain our design equal one hell of a powerhouse.

Intro to Design Tokens: How to Communicate in Design Work

Going from static files, private work, and image-based output to a collaborative, real-time component-oriented tool changes everything about the design workflow.

Why Figma? The Pros of Collaborative Design

Figmagic is the last piece in our toolchain that acts as the glue needed to super-charge your productivity.

An Intro to Figmagic, the Figma CLI For Token Design

Enabling 'Continuous Design'

It's high time to get to know the Figma API, one of the real stars of our show.

How to Use the Figma API and Read Figma Documents

Time to get knee-deep in coding, which we will kick-start by using a bit of boilerplate that we're going to scaffold.

How to Scaffold a React Codebase With Degit

It's vital we have a solid grounding for our component workflow if we are to build an entire library of them. In this lesson, we will set up a smooth, component-driven development workflow from code to Storybook.

Build a Component Development Workflow With Storybook

That song with the "I like to move it-move it" lyrics must have been about pushing code to production...right?

Automatically Deploy React Code to GitHub and Cloudflare

While dogfooding does sound yucky, it's a word that connotes the practice of using one's own things, sometimes to build something new. That's what we will do now with the components we've built.

How to Publish a React Component Library to NPM

Putting in the last fixes for our tooling means getting our Continuous Integration operational.

Finishing the CI Setup

Setting up a pipeline for design and code

With all the other hard, boxy stuff behind us, the perspective now moves to the front-end components and Figma.

How to Set up Figmagic to Interact With Figma via CLI

Working effectively with Figmagic means understanding how and what it actually parses from a document.

How Figma Files Are Organized in Figmagic

Getting to know the configuration options is super important if you want to make the best use of Figmagic.

An Intro to Figmagic Command Line Configuration

Getting to know Figmagic

Let's find our way by analyzing our UX sketches before digging into the details and building anything.

UX Sketching and Double Diamonds: Build Atomic Design

Let's move on from basics to the intermediate level and actually make some designs.

How to Create Design Tokens and Styles in Figma

Let's put the Figma-first approach to the test by taking the step to turn a design into code.

How to Break up Designs Into Small, Atomic Components

Starting our design system

And now for some bells and whistles—graphics and icons!

How to Build Icons in Figma and Export Them With Figmagic

Galloping ever onwards, we'll wave our magic wand and summon our low-complexity components.

Flat vs Nested Elements in Figma and Figmagic

Now, we leave the easy flat components for the more detailed nested ones!

How to Create Nested Figma Elements in Figmagic

Code generation with Figmagic 4 will only take you so far. For our most important and complicated components, we will need to do some manual work, composing small bits into more advanced ones. Let's compose one from what we've made so far!

How to Compose Complex Components With Figmagic

Extra credit time—adding the components for the checkout view.

Finishing the Checkout Components (optional)

Building elements and components

Good documentation is vital and shows that you care about your design system and those who will use it. Lacking good documentation practices could spell doom for a design system.

How to Author Quality Design Documentation

The very first documentation step we will take is to describe what we have built so far.

Add Storybook Descriptions For Self-Documenting Designs

Storybook is a brilliant tool for documentation, and we'll make good use of it in several ways.

How to Structure Storybook for Documentation

Documentation and Storybook

We have talked about "continuity" a lot, so it's about time we address how to deal with change in practice.

How to Plan for Design and Component Life Cycles

Things need to be in order before we continue.

Export Components With GitHub Chromatic Actions

Time to fill up our UI platform with our work to date!

A Beginner's Guide to Using Chromatic With Storybook

Communicating and giving feedback on our work is the lifeblood of a design system.

Building a Feedback Loop For Your Design System

Let's automate the release of new components.

Publish New Design Components With GitHub Actions

Time to place the final cherry on the top. Cue up "I've got the power"!

How to Trigger GitHub Actions From a Figma Plugin

The design life cycle

Summary and thank you

Among developers and architects, "continuous integration and delivery/deployment" (CI/CD for short) has increasingly become the norm for almost two decades. And while frontend development has gone through the framework revolution, going from design to code with the speed expected of CI/CD is still a pain. But it doesn't need to be!

This 10-module course is taught by Mikael Vesavuori, an architect and developer who has helped companies like Polestar redefine their technology and design processes, tooling and ways of working.

In the course, we will create a full component-based React-driven application with Figmagic, underpinned by Storybook, good documentation, and with CI and automated testing.

We will bring the dev-designer collaboration to its current state-of-the-art with a DevOps-inspired life cycle, which could be called “continuous design” (after continuous integration/deployment or CI/CD).

While there is a pre-defined, specific toolset that we’ll use, the end goal of the course is to teach you a wider perspective of what it means to work end-to-end with design systems. Nearly all individual tools are exchangeable: we’re more interested in the capabilities enabling our desired way-of-working than the specific tools chosen to get there.

This course is a comprehensive guide to building a React component library based on a well-architectured design system. You’ll create a full component-based React-driven application with Figmagic, underpinned by Storybook, good documentation, and with CI and automated testing. Learn senior-level system architecture skills for frontend React code; skills you can apply broadly in working on any frontend application.

The newline Guide to React Component Design Systems with Figmagic

How to set up a continuous design pipeline from code to CI/CD, using some of the best services out there

What Figma, Figmagic, and design tokens are and how they enable you to be more productive

How design tokens can function as a contract between designers and developers, setting up powerful new ways of working

The history of design/code tooling and how to argue for process and tooling change

Understand the value of documentation, using Storybook and Figma to document your work

This is the first time in this course we'll dip our toes into what the Figma API looks like and how it works. In this lesson, we will:

 Figma provides and seeing how their API playground works.

The API is read-oriented, so you can't currently write to (i.e., change) documents, comments, files, or anything else.

There is a rate limit on the API, so you should avoid using it excessively.

To call Figma's API, you will need to pass along your token and then specify what you are requesting. The coarsest item we are interested in would be a file, else known as a 

. How about we inspect a brand-new, blank Figma design file?

Let's pop into Figma and create a new file. I will rename mine "My test file."

One of the least intuitive things in Figma is actually finding the document ID itself. We can do this by right-clicking the window tab near the top (with our document name) and clicking 

Paste this somewhere so we can take a look at it. Mine looks like this:

https://www.figma.com/file/fOxMBUY8kQZnL5iHr7FzJc/My-test-file?node-id=0%3A1&viewport=1479%2C677%2C1

{FIGMA_BASE}/{TYPE}/{DOCUMENT_ID}/{DOCUMENT_NAME}?node-id={NODE_ID}&viewport={VIEWPORT_LOCATION}

Some of these are self-explanatory. It's worth mentioning that the main 

, a node essentially denoting an object in your file. The 

 is so we can—just like you have probably done in Google Maps at some point or another—share a location so that others can directly see what you want them to look at.

We will talk more about document structure soon. For now, copy the part between 

—that is the document ID segment we need to use with the API now.

. Indeed, that's the base of the endpoint we will call soon.

The page is not exactly short, and you'll navigate the fastest if you use the left-hand side menu. As always, documentation like this is something you want to bookmark if you are building things with, or for, an API.

You can skip quite a lot of the sections in the beginning. For now, what we want to do is just get a quick glimpse of how stuff looks under the hook. In fact, what we want to do is to scroll all the way down to 

There's a handy API playground here, under the heading 

. Only one piece of data is required, and that is the file ID we just got. Paste it in there. Normally you need a token to use the API—the playground allows you to create a temporary one by just clicking the 

 button. Do so now. After a second or so, you should have that field pre-populated with the temporary token. Click 

. Admittedly, the box with the response is tiny, but if you scroll through the response, it's as real as it gets.

You can try out the other endpoints Figma provides here just as easily. There is no magic wand, so your response depends entirely on what resource you point it to. A blank document won't give much back!

It's about time we get our own token and put things in order!

Open up Figma. Click the Figma icon in the upper left corner. Click 

. Scroll almost all the way down until you see 

Add a token description and press enter/return. You'll be presented a token, which will have a format like 

83715-e8346292-bf3v-88s1-n932-j364ge9h687e

. Copy it. Keep this token a secret, and don't check this into your code! If you do happen to leak it, just revoke the old one and get a new token.

Notice also how you can see whether a token has been used or not, and how you can also revoke access to individual tokens here. We won't do so in this course, but it's really something you want to keep in the back of your head as you continue working with Figma under more production-like circumstances.

Don't worry about my on-screen token: It'll be revoked by the time you see this.

What is reserved for Pro plans and admins

In case you would be interested in creating webhooks, these need to be created by organization admins. Effectively, that rules out free users. There does not appear to be any other differences in what is available through the API in regards to what your plan allows.

---
title: How to Use the Figma API and Read Figma Documents
description: It's high time to get to know the Figma API, one of the real stars of our show.
#privateVideoUrl: https://fullstack.wistia.com/media/xxxxx
isPublicLesson: false
useMdx: true
code: https://gitlab.com/fullstackio/books/newline-course-apps/mikael-vesavuori-react-component-design-systems-with-figmagic-app/-/tree/main/code/module_04/lesson_04.01/App?ref_type=heads
---

This is the first time in this course we'll dip our toes into what the Figma API looks like and how it works. In this lesson, we will:

-   See what Figma offers in ways of documentation and API playground
-   Set up an API client to help us use the Figma API
-   Create our own API token
-   Learn how we know our unique document ID
-   Understand the document structure
-   Learn what we can only do in paid plans

We'll start by scanning the [documentation](https://www.figma.com/developers/api) Figma provides and seeing how their API playground works.

![Figma API docs](https://d2uusema5elisf.cloudfront.net/courses/newline-guide-to-react-component-design-systems-with-figmagic/module_04/lesson_04.01/public/assets/figma-api-docs.png)

## The Figma API in short

The API is read-oriented, so you can't currently write to (i.e., change) documents, comments, files, or anything else.

:::note
There is a rate limit on the API, so you should avoid using it excessively.
:::

To call Figma's API, you will need to pass along your token and then specify what you are requesting. The coarsest item we are interested in would be a file, else known as a _document_. How about we inspect a brand-new, blank Figma design file?

## Finding the document ID

Let's pop into Figma and create a new file. I will rename mine "My test file."

One of the least intuitive things in Figma is actually finding the document ID itself. We can do this by right-clicking the window tab near the top (with our document name) and clicking **Copy Link**.

Paste this somewhere so we can take a look at it. Mine looks like this:

`https://www.figma.com/file/fOxMBUY8kQZnL5iHr7FzJc/My-test-file?node-id=0%3A1&viewport=1479%2C677%2C1`

The sections are—

`{FIGMA_BASE}/{TYPE}/{DOCUMENT_ID}/{DOCUMENT_NAME}?node-id={NODE_ID}&viewport={VIEWPORT_LOCATION}`

Some of these are self-explanatory. It's worth mentioning that the main _type_ you will use is **files**, but there are several more, like **teams** and **components**. Further, Figma has the concept of _nodes_, a node essentially denoting an object in your file. The `viewport` is so we can—just like you have probably done in Google Maps at some point or another—share a location so that others can directly see what you want them to look at.

We will talk more about document structure soon. For now, copy the part between `/file/` and `/My-test-file`—that is the document ID segment we need to use with the API now.

## Checking the API docs/explorer

Go to the [Figma REST API documentation site](https://www.figma.com/developers/api). Note the **Base URL**, <https://api.figma.com>. Indeed, that's the base of the endpoint we will call soon.

The page is not exactly short, and you'll navigate the fastest if you use the left-hand side menu. As always, documentation like this is something you want to bookmark if you are building things with, or for, an API.

You can skip quite a lot of the sections in the beginning. For now, what we want to do is just get a quick glimpse of how stuff looks under the hook. In fact, what we want to do is to scroll all the way down to [`Figma files > Endpoints > GET file`](https://www.figma.com/developers/api#get-files-endpoint).

### Trying the API explorer

There's a handy API playground here, under the heading **Try it out for yourself**. Only one piece of data is required, and that is the file ID we just got. Paste it in there. Normally you need a token to use the API—the playground allows you to create a temporary one by just clicking the **Get personal access token** button. Do so now. After a second or so, you should have that field pre-populated with the temporary token. Click **Submit API request**. Admittedly, the box with the response is tiny, but if you scroll through the response, it's as real as it gets.

:::tip
You can try out the other endpoints Figma provides here just as easily. There is no magic wand, so your response depends entirely on what resource you point it to. A blank document won't give much back!
:::

It's about time we get our own token and put things in order!

## Get your own API token

Open up Figma. Click the Figma icon in the upper left corner. Click `Help and account > Account settings`. Scroll almost all the way down until you see **Personal access tokens**.

![Personal access tokens](https://d2uusema5elisf.cloudfront.net/courses/newline-guide-to-react-component-design-systems-with-figmagic/module_04/lesson_04.01/public/assets/pat.png)

Add a token description and press enter/return. You'll be presented a token, which will have a format like `83715-e8346292-bf3v-88s1-n932-j364ge9h687e`. Copy it. Keep this token a secret, and don't check this into your code! If you do happen to leak it, just revoke the old one and get a new token.

![Personal access tokens, making a new one](https://d2uusema5elisf.cloudfront.net/courses/newline-guide-to-react-component-design-systems-with-figmagic/module_04/lesson_04.01/public/assets/pat-new.png)

Notice also how you can see whether a token has been used or not, and how you can also revoke access to individual tokens here. We won't do so in this course, but it's really something you want to keep in the back of your head as you continue working with Figma under more production-like circumstances.

:::note
Don't worry about my on-screen token: It'll be revoked by the time you see this.
:::

### What is reserved for Pro plans and admins

In case you would be interested in creating webhooks, these need to be created by organization admins. Effectively, that rules out free users. There does not appear to be any other differences in what is available through the API in regards to what your plan allows.

## Setting up an API client

How about we improve our situation a bit by investing a couple of minutes in a proper API client.

There are probably at least a million ways in which you can call an API. For this lesson, unless you already have a favorite tool to do this, I'd recommend you to use [Insomnia](https://insomnia.rest). Insomnia has a free version, and it's available for multiple platforms.

:::note
This step is probably more important for _me_ to show you than it is for _you_ to actually follow, so feel free to just tag along on this one!
:::

One of the key benefits of using a dedicated API client is that we can store payloads, tests, URLs, and all kinds of other data needed to make requests. Without a client, it's very tempting to start placing those pieces of information all over the place, so having it centralized in the API client is really convenient. Figma responses can be very large, so while I'd like to just point to the online version of a tool such as [`httpie`](https://httpie.io/run), it won't quite cut it in this context since the screen simply won't fit the entire response.

### Insomnia document

When you've downloaded and installed Insomnia, start it up. Click `Create > Design Document`. Give it a name, like `Figma API testing`. Click the **Debug** tab. Click the _plus sign_ icon and **New Request**. Because we want to get a document, let's call the request `Get document`.

You'll be presented with a fairly bare interface.

![Insomnia start](https://d2uusema5elisf.cloudfront.net/courses/newline-guide-to-react-component-design-systems-with-figmagic/module_04/lesson_04.01/public/assets/figma-insomnia-start.png)

### Variables

Insomnia, like many of the more competent API clients out there, can use "environments" to store values in variables. You'll remember that the token and document (or file) IDs are our important values. Click the button with the text **No environment**, then **Manage environments**. Into the **Base Environment** text field, paste the below and substitute the actual values with your own values:

```json { actualFilename=./protected/InsomniaEnvironment.json endChar=50 endLine=5 startChar=0 startLine=1 statedFilename=./protected/InsomniaEnvironment.json url=https&#x3A;//gitlab.com/fullstackio/books/newline-guide-to-react-component-design-systems-with-figmagic/module_04/lesson_04.01/protected/InsomniaEnvironment.json }
{
  "FILE_ID": "123",
  "FIGMA_TOKEN": "qwerty"
}
```

In the URL box next to `GET`, which you can toggle to any other HTTP verb (but don't do it now!), place this _exactly as written here_:

    https://api.figma.com/v1/files/{{FILE_ID}}

Anything wrapped in double curly braces will be inferred as a variable. Nifty indeed!

### Custom headers

The last thing to do is to pass the `X-Figma-Token` header to authenticate your request.

Click the `Header` tab. Put in `X-Figma-Token` in the left (key) field, and `{{FIGMA_TOKEN}}` into the right (value) field.

### Call the API

Now, just press `CMD + ENTER` or click `Send` to fire away a request.

The response should be shown in the right-hand side panel. While there is no angelic choir present or anything extraordinarily different with this compared to the API playground, Insomnia will soon prove to be much more versatile than the playground. Not to mention the fact that you can actually read the response easily!

My response is this; mild edits made to keep it short—

```json { actualFilename=./protected/FigmaApiResponseMinimal.json endChar=763 endLine=35 startChar=0 startLine=1 statedFilename=./protected/FigmaApiResponseMinimal.json url=https&#x3A;//gitlab.com/fullstackio/books/newline-guide-to-react-component-design-systems-with-figmagic/module_04/lesson_04.01/protected/FigmaApiResponseMinimal.json }
{
  "document": {
    "id": "0:0",
    "name": "Document",
    "type": "DOCUMENT",
    "children": [
      {
        "id": "0:1",
        "name": "Page 1",
        "type": "CANVAS",
        "children": [],
        "backgroundColor": {
          "r": 0.89803922176361084,
          "g": 0.89803922176361084,
          "b": 0.89803922176361084,
          "a": 1.0
        },
        "prototypeStartNodeID": null,
        "prototypeDevice": {
          "type": "NONE",
          "rotation": "NONE"
        }
      }
    ]
  },
  "components": {},
  "schemaVersion": 0,
  "styles": {},
  "name": "My test file",
  "lastModified": "2021-06-06T15:19:14Z",
  "thumbnailUrl": "https://s3-alpha-sig.figma.com/thumbnails/...",
  "version": "123456789",
  "role": "owner"
}
```

Okay, so that's an impossibly raw and basic example. From the rather flat nesting structure, you can see that most of the fields we are receiving are related to document metadata, such as `version`, `lastModified`, and `name`. In the `document` part, we do get the document with a single child: the page.

Take a few moments to place some actual content in your Figma file.

## Populate some content into Figma

I will first place a frame, and into it, I will:

-   Add an image
-   Add a rectangle with a basic solid fill
-   Add a rectangle with a linear gradient fill
-   Add a group containing two rectangles
-   Add a vector graphic using the Pen tool
-   Add a text snippet