handoff-app/README.md

Automated documentation toolchain for building client side documentation from figma

# Handoff - Design Token Automation

<a aria-label="NPM version" href="https://www.npmjs.com/package/handoff-app">
  <img alt="" src="https://img.shields.io/npm/v/handoff-app?style=for-the-badge&labelColor=000000">
</a>
<a aria-label="License" href="https://github.com/convertiv/handoff-app/blob/main/License.md">
  <img alt="" src="https://img.shields.io/npm/l/handoff-app?style=for-the-badge&labelColor=000000">
</a>

A design token pipeline to read figma files, extract tokens as JSON, and
transform tokens into dev ready artifacts.

## Table of Contents

- [What Is Handoff?](#what-is-handoff)
- [How does it work](#how-does-it-work)
  - [Handoff is in Beta!](#handoff-is-in-beta)
- [Requirements](#requirements)
- [Get Started](#get-started)
- [Table of Contents](#table-of-contents-1)
  - [Figma](#figma)
  - [Create a project](#create-a-project)
  - [Test fetch](#test-fetch)
- [Further Reading](#further-reading)
- [Maintainers](#maintainers)
- [Contributing](#contributing)
- [License](#license)

## What Is Handoff?

Handoff is an open source toolchain for building and managing robust design systems.
Handoff enables developers to pull data from Figma, document complex components,
and deploy documentation as a static site. Handoff renders the documentation as a
JSON API and then builds a human readable interface on that JSON API. Our goal is
to make Design Systems and DS documentation a part of the production pipeline,
rather than an extra process.

Handoff is a collection tools:

- **Figma Data Extraction** - A framework for extracting standardized design
tokens, foundations, and component metadata from Figma.
- **Build Pipeline** - A set of transformers for building SASS, CSS,
  Style Dictionary, Javascript, and render previews from your components.
- **Documentation Web App** - A static, client side, Javascript web app that
  renders live, working previews of your components, tokens and styles.

## Quickstart

You can start up

Follow our full quickstart guide here - [Get Started](https://www.handoff.com/docs/quickstart)

## How does it work?



- [Get Started](https://www.handoff.com/docs/quickstart)
- [Requirements](https://www.handoff.com/docs/overview/requirements)
- [Integrating Tokens](https://www.handoff.com/docs/tokens/integration)
- [Customization](https://www.handoff.com/docs/customization)

Once Handoff extracts design tokens and variables, it builds a statically
generated NextJS application that can be published to the web. This asset
can be hosted on a static webhost (NGINX, s3/Cloudfront, Cloudflare pages
etc).

- [Tokens Overview](https://www.handoff.com/docs/tokens)
- [Build Site](https://www.handoff.com/docs/tokens/publishing)

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

- [CI/CD Integration](https://www.handoff.com/docs/guide/cicd)


## Requirements

- Node 20
- NPM 10
- A paid Figma account is required to publish the Figma file library, if
you want to use the token extraction

## Get Started

### Figma

1. Open the [Handoff Figma starter](https://www.figma.com/file/IGYfyraLDa0BpVXkxHY2tE/Starter-%5BV2%5D?node-id=0%3A1&t=iPYW37yDmNkJBt1t-0)
   and duplicate this project to your account

2. Publish components to the library

- Click on the Figma logo at the top left
- Click on `Libraries`
- Click on the current file
- Click publish changes

You'll need a developer token if you don't have one already

- Click on the Figma logo in the top left
- Go to `Help and Account`
- Click on `Account Settings`
- Scroll to `Personal Access Token`
- Enter a token name and hit enter
- Note that token for the next steps

## Create a project

- Run `npm install -g handoff-app`
- Create a new directory for your project `mkdir my-new-project`
- In that folder (`cd my-new-project`), run `handoff-app fetch`
- Handoff will prompt for your developer token, and the file id of your figma
  file. The file id can be found in the url of the file -
  https://www.figma.com/file/{file_id}/{slug}
- Start the project `handoff-app start`

This will fetch the latest from your Figma file and it will boot a demo site at
http://localhost:3000

## Test Fetch

- Now go back to your Figma file and change a button color
- Republish the changes to the library. Click on the publish button from the main
  dropdown. You'll see a list of changes that have been made. Clicking publish
  will make those changes available to handoff.
- Back in your project, open a new terminal tab and type `npm run fetch`

Once that runs, your browser should update with the new colors.

## Further Reading

- [Configure your project](https://www.handoff.com/docs/customization)
- [Customize the content](https://www.handoff.com/docs/customization/content)
- [Integrate tokens with your project](https://www.handoff.com/docs/tokens/integration)
- [Build to Static Assets](https://www.handoff.com/docs/tokens/publishing)
- [Integrate with Github Actions CI/CD](https://www.handoff.com/docs/infrastructure/github/)
- [Integrate with Bitbucket Pipelines CI/CD](https://www.handoff.com/docs/infrastructure/bitbucket/)

## Maintainers

[@bradmering](https://github.com/bradmering)

[@DomagojGojak](https://github.com/DomagojGojak).

[@Natko](https://github.com/Natko).

## Contributing

Feel free to dive in! [Open an issue](https://github.com/Convertiv/handoff-app/issues/new) or submit PRs.

Handoff follows the [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) Code of Conduct.

## License

[MIT](LICENSE) ©Convertiv