Convertiv-motiv NPM

Handoff

Handoff is a toolchain for extracting design tokens from the Figma REST API and building frontend developer documentation from that figma file.

Handoff works by extracts design foundation and component data from well formed Figma libraries, storing them as JSON, and then transforms them into design tokens. Those design tokens are published as SASS and CSS variables.

Once Handoff extracts design tokens and variables, it builds a staticly generated NextJS application that can be published to the web. This asset can be hosted on on an static webhost (nginx, s3/cloudfront, cloudflare pages etc).

This pipeline from Figma to Documentation Web app can be automated via CI/CD to provide automatic, up to date, easily readable developer documentation.

Beta Release

Handoff is currently in beta release. We want you to use it, and we think it works very well within the constraints listed below. We're working hard to harden the current feature set, and to expand the use cases.

We'd love feature ideas and bug reports, either as github issues or email to handoff@convertiv.com.

This project is sponsered and built by Convertiv

Requirements

Node 16
NPM 8

Quick Start

Run npx handoff-app create
Enter a project name at the prompt
Optionally enter a figma file id and developer token
- You can leave these two blank and add them manually via a .env file, or an env variable
- See the .env.example that is created
A folder will be created with the project name in the current directory
cd project-name
Edit the .env file if and provide a figma file id and developer token
Start the project npm run start
- This will fetch the latest from your figma file
- And it will boot a demo site at http://localhost:3000

What Next

Ok, now that you have it running locally, what should you do next?

Publishing Package

You can publish the build static site. Use the build command baked into the generated code.

npm run build

This will fetch everything from figma, and publish a built artifact to the public directory. You can take the contents of that folder and run it on any static web host.

Running Fetch Only

If you run npm run fetch, this will fetch down and run the transformers to get all the token data from figma, but will not generate the static site. The contents of the fetch and transform will be exported to the exported directory.

tokens.json - A json representation of all the tokens extracted from figma
changelog.json - A changelog indicating changes since the last run
preview.json - A json representation of the iframable preview components
variables - A folder containing the css and sass variables for each component

Customizing Handoff

Basic Configuration

config.js contains all the basic configuration options for the site. This file is heavily commented, and strictly typed to make it easy to know what options you have. This config will let you set things like sort order and page text

Preview Templates

The templates directory contains starter code and instructions for the component previews in the static site. These templates default to Bootstrap 5 components. In this folder you can customize the component markup, the styles of the previews, and add javascript that will be executed in the preview frame.

Assets

You can customize any of the static assets published to the site. These assets are stored either in an assets file for prebuilt components (svgs) or in the public directory for things like a favicon. Simply place the asset in the directory and it will get built into the project on build.

Philosophy and Limitations

Handoff is designed to reduce the friction between design and frontend development by creating a set of developer focused tools. These tools are designed to extract data and then transform it into reusable components.

Handoff is highly opinionated. This is partially because extraction of tokens from Figma is difficult, and partially because imposing a highly opinionated structure on design produces better engineering results. Handoff comes from a belief that the foundations and components of a web application should be designed with a high degree of rigour, and then expressive designs can be built on top of that foundation. The expressive design will be better in every facet, if the foundational objects are well built.

The toolchain is designed to be fully modular, allowing you to use only the portions you need, and to extend the framework as desired. The toolchain consists of the following pieces

Figma REST Extractor
- Foundations (Colors, Typogoraphy, Logos, Icons)
- Components
SASS Variable Token Transformer
CSS Variable Token Transformer
Boostrap Preview generator
Static Site Generator

Figma Limitations

Extracting tokens reliably from Figma is difficult, and this toolchain is an ongoing and evolving project. At present, we can extract only with a fairly well structured Figma library. We have published a starter library for you to copy and clone. Using this as a baseline will ensure high quality token export.

TODO: Insert published figma file here.

Token Limitations

At present, we support the following components and structures.

Foundations
- Colors
- Typography
- Logos (SVG)
- Icons (SVG)
Components
- Alerts
- Buttons
- Checkbox
- Input
- Modal
- Pagination
- Radio
- Select
- Switch
- Tooltips
Component Groups
- Type
- State
- Theme
- Active
- Horizontal (activation)
- Vertical (activation)
General Properties (varies by component)
- Background Color (solid)
- Border Color (solid)
- Border Radius (4 corners)
- Border Width
- Padding (left, right, top, bottom)
- Box Shadows
- Component text
- Font weight
- Font Spacing
- Label spacing
- Component spacing

General Limitations (things we're working on)

Figma naming needs to be pretty consistant with our figma starter
Gradient colors don't work TODO: List further limitations

Working directly with this repo

If you want to work directly with the source code, you can check this repo out directly. The code is all in typescript, and the project is broadly seperated into three parts -

Next JS Site generator
Figma Exporter and transformers
Supporting assets (build, installer, resources)

You must compile from typescript when you run the project. The NextJS code has automatic TS compilation, but the figma exporter must be compiled prior to each run. Here are the main commands you can run:

`npm run build:lib`

Builds the figma-exporter fetch source code found in figma-exporter.

`npm run fetch`

Fetch the latest from the figma project specified in the .env file. The user token must have access to the specified project.

`npm run dev`

Runs the app in the development mode.\ Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.\ You will also see any lint errors in the console.

`npm run build:static`

Builds the app for production to the out folder.\ It correctly bundles React in production mode and optimizes the build for the best performance. The build is minified and the filenames include the hashes. Your app is ready to be deployed!