Updating readme

.vscode/settings.json

@@ -10,5 +10,8 @@
   },
   "[typescriptreact]": {
     "editor.defaultFormatter": "vscode.typescript-language-features"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "unifiedjs.vscode-remark"
   }
 }

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