@framerjs/component-importer

Component Importer

The component-importer is a command line tool that makes it easy to import TypeScript-based React design systems into Framer X. It analyzes your production design system's source code and generates readable React components that can be loaded by Framer X.

Let's take a quick look at the generated code.

Example: importing a button from the baseui design system

import * as React from "react"
import * as BaseUi from "baseui/button"
import { addPropertyControls, ControlType } from "framer"

function Button(props) {
    return <BaseUi.Button {...props} />
}

addPropertyControls(Button, { // <=== Inferred Property Controls
    kind: {
        type: ControlType.Enum,
        defaultValue: "primary",
        options: ["primary", "secondary"]
    },
    label: { type: ControlType.String },
    isLoading: { type: ControlType.Boolean, defaultValue: false },
})

By analyzing the button component's TypeScript definitions, we can infer its property controls, similar to React Storybook's knobs. This means you can now drag your button to the Framer X canvas and modify it using a GUI that everyone can understand:

Why?

Design Systems lower engineering costs by keeping a single source of truth for your company's visual language. They have been successfully adopted by the industry's most sophisticated players like Google, Microsoft and Uber. Even the UK and US government have one!

There's still one big problem though: production design systems are typically only accesible to technical designers, comfortable enough with the command line and familiar with web development tooling like Webpack, TypeScript/Flow, React/Angular, etc. This means that designers often end up having to maintain their own copy which is expensive to keep in sync.

The component-importer makes it possible to import your company's design system into Framer X so designers can start prototyping with components that behave just like they do in production.

Increasing design system adoption

As a design system maintainer, your design system's value is proportional to its adoption. To be successful you'll need to think beyond just developing components, but also about making sure that they are well documented and intuitive for everyone involved in the process - this can range from designers and engineers to product managers and content creators. The component-importer tries to lower the barrier of adoption by making your production design system available for everyone.

Getting started

To install run yarn global add @framerjs/component-importer. This will globally install the component-importer executable.

Example: importing the Base Web design system

Let's go through the process of importing the Base Web design system from scratch.

Step 1: project setup

Create a Framer X folder-backed project:

• Create a new Framer X project
• Hold Option and click File › Save As
• In the save dialog, click the File Format dropdown and select "Framer X (Folder)"
• Click Save

NOTE: .framerfx projects are regular NPM projects. Go to your favorite text editor and try to open the folder we just created. The contents should look something like this:

build/
code/
design/
metadata/
node_modules/
package.json
README.md
tsconfig.json
yarn.lock

As you can see, it's a good ol' NPM package with its package.json and node_modules. It also has a tsconfig.json file as Framer X supports TypeScript by default.

Step 2: add dependencies

Before we import Base Web, we will first need to add it as a dependency:

# cd into the project created in the previous step.
cd ~/my-project.framerfx

# Base Web's npm package name is `baseui`
yarn add baseui

Step 3: run the component-importer

In order to configure the component importer you will need to setup a configuration file, usually at the root of your project.

The component-importer init command will help you setup the appropriate defaults for your project.

The general syntax is component importer init <packageName>, an example being component-importer init @blueprintjs/core which will attempt to import the @blueprintjs/core package into your Framer X project.

Now you can run the following command for your design system of choice:

component-importer init baseui

Examples

Looking for projects using the component-importer?

• Base Web: Uber's design system.
  • Source Code
  • Framer X package
• Office UI Fabric: Microsoft's design system.
  • Source Code
• Grommet: A mobile-first, themeable design system used by companies like IBM, Netflix and Sony.
  • Source Code
  • Framer X package
• Salesforce Lightning
  • Source Code

Documentation

Looking to dive deeper into the component-importer? These guides are here to help:

• The CLI: Detailed documentation on how to use the component-importers CLI.
• Configuration: Fine tuning the importer with the importer.config.json.
• Re-importing: How to keep your Framer X project in sync with your design system.

External resources & articles

Want to learn more about design systems?

• Measuring Impact Cristiano Rastelli measures the impact of moving Badoo to a design system, filled with colorful charts 📊 and graphs 📈.
• Estimating Costs & Value Trying to convince your manager about building a design system? Bryn Rozzier explains a simple technique to estimate the ROI 💰 of building a design system.
• Driving Adoption Got a design system, but nobody is using it? Jeroen from segment.io explains what it took to convince other engineers to adopt Evergreen 💗.