diff --git a/.vscode/settings.json b/.vscode/settings.json index 660f1da6..1fe7896a 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,5 +10,8 @@ }, "[typescriptreact]": { "editor.defaultFormatter": "vscode.typescript-language-features" + }, + "[markdown]": { + "editor.defaultFormatter": "unifiedjs.vscode-remark" } } diff --git a/README.md b/README.md index 07c0cbb8..bbf5e94f 100644 --- a/README.md +++ b/README.md @@ -12,134 +12,122 @@ 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?](#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 tool for extracting design tokens from the Figma REST -API and building frontend developer documentation from that Figma file. By -automating the design token delivery, Handoff helps to eliminate bottlenecks -between design and development. +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 of 4 javascript tools: +Handoff is a collection tools: -- **Figma Token Extraction** - A framework for extracting - standardized design foundations and components from Figma. -- **Transformation Pipeline** - A set of transformers for producing SASS, CSS, - Style Dictionary, and preview snippets from that data. -- **Documentation Web App** - A static, client side, Javascript web app that +* **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. -- **Delivery Tools** - Easy build tooling and CI/CD wrapper that allows - automation to render and ship the various deliverables as needed. -## How does it work? - -Handoff works by extracting design foundations and component data from -[well-formed Figma libraries](https://www.figma.com/file/IGYfyraLDa0BpVXkxHY2tE/Starter-%5BV2%5D?node-id=0%3A1&t=iPYW37yDmNkJBt1t-0), -storing them as JSON, and then transforming them into design tokens. Those -design tokens are published as SASS and CSS variables. - -Out of the box, Handoff has native SCSS and CSS maps to connect these tokens to -any site using the [Bootstrap 5](https://getbootstrap.com/) frontend -framework. If you use another framework, or custom CSS, you can easily write -map files to connect the generated tokens with your site or application. - -- [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) +## Quickstart -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). +Follow our full quickstart guide here - [Get Started](https://www.handoff.com/docs/quickstart) -- [Tokens Overview](https://www.handoff.com/docs/tokens) -- [Build Site](https://www.handoff.com/docs/tokens/publishing) +### Fetch tokens and metadata from Figma -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. +1. Add handoff to your project - `npm install handoff-app` +2. Add a fetch command to your scripts -- [CI/CD Integration](https://www.handoff.com/docs/guide/cicd) +``` + "scripts": { + "fetch": "handoff-app fetch" + } +``` -## Handoff is in Beta! +3. Fetch tokens and metadata from your figma project - `npm run fetch` +4. Provide your figma project id and your developer token. Your developer token will need read + access to the file and file library -Handoff is Awesome. Handoff is also really new. We're constantly building -new features, and expanding what it can do. We'd love to chat if you have -a use case that isn't quite met. +### Start a documentation app -## Requirements - -- A paid Figma account is required to publish the Figma file library -- Node 18.17+ -- NPM 8+ +1. Add handoff to your project - `npm install handoff-app` +2. Add a fetch command to your scripts -## Get Started +``` + "scripts": { + "fetch": "handoff-app fetch" + } +``` -### Figma +3. Navigate to localhost:3000 -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 +## How does it work? -2. Publish components to the library +* [Get Started](https://www.handoff.com/docs/quickstart) +* [Requirements](https://www.handoff.com/docs/overview/requirements) +* [Extraction Overview](https://www.handoff.com/docs/figma) +* [App Overview](https://www.handoff.com/docs/app) -- Click on the Figma logo at the top left -- Click on `Libraries` -- Click on the current file -- Click publish changes +The Figma data extraction and the Design System documentation app +are independent pieces - you can use one without the other. Handoff +is designed to quickly scaffold everything you need in a robust design system. -You'll need a developer token if you don't have one already +Handoff centralizes all of the pieces you need in your frontend builds, +allowing you to create robust documentation, and build full components +in whatever framework and structure you want. Using Vite under the hood +Handoff will compile your components to HTML to render in the App. -- 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 +* [Foundation Tokens](https://www.handoff.com/docs/tokens) +* [Building Components](https://www.handoff.com/docs/components) +* [Adding Markdown Pages](https://www.handoff.com/docs/markdown) -## Create a project +The documentation application has a robust documented API. With it +you can construct components in whatever format you want, with +clear documentation. You can hook into the build process and adjust +the build process to suite your needs. Finally the app publishes +a JSON api to allow downstream processes to consume and reason +about components in the library -- 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` +* [Component Structure](https://www.handoff.com/docs/components/api) +* [Hook API](https://www.handoff.com/docs/hooks) +* [REST API](https://www.handoff.com/docs/api) -This will fetch the latest from your Figma file and it will boot a demo site at -http://localhost:3000 +Handoff is designed to be automated, with the pipeline from Figma to +the Documentation Web app executed from a CI/CD process. This provides +automatic, up-to-date, easily readable developer documentation. -## Test Fetch +* [CI/CD Integration](https://www.handoff.com/docs/guide/cicd) -- 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` +## Requirements -Once that runs, your browser should update with the new colors. +* Node 20 +* NPM 10 +* A paid Figma account is required to publish the Figma file library, if + you want to use the token extraction ## 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/) +* [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