Overview

Handoff is an open-source design system runtime, published on npm as handoff-app. It turns design tokens, components, patterns, and pages into working documentation and distributable artifacts.

These docs cover Handoff 2.1.0. See Release notes for what changed in each release.

How it fits together

The design system is authored in a workspace: components and patterns, colors, type, icons and logos, and guidance pages. The workspace is one source of truth next to the code, shows live previews, and is versioned in git. The team publishes it to the registry. In the registry, anyone with the link can read the docs; signed-in members such as designers, PMs, reviewers and developers save custom previews and ask the AI assistant; admins publish, invite people and manage access; access tokens give tools read, preview, or publish access. From the registry, CMS and page builders take component templates and rendered HTML; developers take component code and design tokens into their project; product apps take token CSS and Sass, icons and logos; AI coding agents read components, tokens and pages over MCP.

Author

Workspace

Where the design system team builds it.

• Components and patterns
• Colors, type, icons, logos
• Guidance pages

• One source of truth, next to the code
• Live previews as you work
• Versioned in git

Publish

Publish

Share

Registry

The shared, hosted copy. Who uses it:

• Anyone with the link

  Reads the docs

• Members

  Designers, PMs, reviewers, developers

  Save custom previews, ask the AI assistant

• Admins

  Publish, invite people, manage access

• Access tokens

  Read, save previews, or publish, per token

Used by

Used by

CMS and page builders

Templates and rendered HTML to build pages

Developers

Component code and tokens in their project

Product apps

Token CSS and Sass, icons, logos

AI coding agents

Components, tokens, and pages over MCP

What you get

• A documentation app for your design system. Each component page shows live previews, the property table, usage snippets, and the source. Foundation pages show colors, typography, effects, icons, and logos.
• One catalog API. defineCatalogItem declares React, Handlebars, and Storybook CSF components, and compositions of them, next to the code they document.
• Figma foundations, optional. fetch reads tokens and assets from a Figma library and writes CSS, Sass, and JSON to your project.
• A shared registry. Publish the catalog to a deployed registry with a PostgreSQL database. Other projects check it out. Readers save their own previews of a component.
• MCP for coding agents. Every server deployment has an MCP endpoint. Agents search components, read their properties and previews, and take token values instead of inventing them.
• An AI assistant in the documentation app, which reads through the same MCP tools.

Three ways to serve it

The workspace is the only place that builds content. A registry stores and serves what a workspace publishes to it.

Where to go next

• How Handoff works: runtime modes, the workflow, and the terms these docs use.
• Getting started: create a project, or add Handoff to an existing app.
• Authoring: declare catalog items, compositions, and pages.
• Registry: deploy a registry and publish to it.
• MCP and AI: connect a coding agent.
• Upgrade from 1.x: the migration steps for Handoff 2.