How Handoff works
The two runtime modes, the path content takes from source to registry, and the terms used across these docs.
Runtime modes
Handoff has two runtime modes. runtime.mode in the config sets the mode, and the build bakes it
in. Handoff never infers the mode from environment variables or a database setting.
- Workspace is the default. Local files are the source of truth, and no database is needed. You author content here.
- Registry is a deployed catalog with a PostgreSQL database. It stores and serves only the content that a workspace publishes to it. It never builds and never reads workspace source.
A connected workspace is a workspace with a registry URL and a credential. It can publish to a registry and check content out of it. It is not a third mode.
build --target registry always produces a registry-mode app, so the base config stays in
workspace mode. See Builds.
The workflow
The Handoff workflow in five steps. 1. Bring in the design: designers bring colors, type, icons and logos in from the Figma library; this is optional. 2. Build and document: the design system team writes components, patterns and guidance pages, with live previews. 3. Publish: the team publishes to a static site or to the shared registry. 4. Review: designers, PMs and stakeholders browse every state, save custom previews, and ask the AI assistant. 5. Build with it: developers pull in code and tokens, and coding agents read the system over MCP. Feedback and changes go back to step 2.
The same steps as commands:
| Step | Command | Result |
|---|---|---|
| Fetch foundations | handoff-app fetch | Tokens, CSS, Sass, and assets in exported/ |
| Author and preview | handoff-app start | Documentation at http://localhost:3000 with live rebuilds |
| Build a static site | handoff-app build | out/static |
| Build a registry | handoff-app build --target registry | Next.js server bundle in out/registry |
| Share content | handoff-app publish all | Catalog items, pages, tokens, and assets in the registry |
| Reuse content | handoff-app checkout all | Registry content written into another workspace |
What a deployment serves
Every server deployment (a running workspace or a registry) serves:
- The documentation app: component, pattern, foundation, and Markdown pages.
- A read API under
/api/docs/, which the app itself uses. See HTTP API. - An MCP endpoint at
/api/mcp/, unless the build turns it off. See MCP. - The AI assistant, when the config declares an AI connection. See AI assistant.
A registry adds sign-in, accounts, access tokens, the publish and checkout API, and custom previews. A static site has no API routes, so it has no MCP endpoint and no assistant.
Terms
- Working directory: the directory that holds
handoff.config.ts. Every command runs against it.HANDOFF_WORKING_PATHsets a different one. - Catalog item: one documented UI entry, with a declaration file, a stable id, and previews.
- Component: a catalog item with an
implementation(React, Handlebars, or CSF). - Pattern: a catalog item with a
compositionof other catalog items. - Preview: a named state of a catalog item, exported from its declaration.
- Custom preview: a component state that a registry reader saves with their own args.
- Foundations: the tokens and assets that
fetchreads from Figma. - Page: a Markdown documentation page under
pages/. - Profile: a config file that merges onto the base config for one environment.