2.0.0

Released 2026-10-16.

Handoff 2 adds a shared registry to the local workspace. You write content in a workspace, publish it to a registry, and check it out in other projects. Coding agents and an AI assistant read the design system through MCP.

New

Registry and connected workspaces

• The registry: a deployed catalog with a PostgreSQL database that stores the catalog items, pages, tokens, and assets a workspace publishes.
• publish and checkout transfer all content, one kind, or specific ids. --dry-run lists the changes and writes nothing. See Publish and checkout.
• Registry accounts, invitations, password reset, and access tokens with read or read-and-write access.
• login and logout, with a device code approved in the browser.
• build --target registry for a standalone registry server, and --package vercel for a Vercel bundle of either target.
• db:migrate applies the registry database migrations.
• Asset storage in PostgreSQL by default, or in any service through a custom provider module, with optional direct uploads.
• Registry email through SMTP or a custom provider module.

MCP and AI assistant

• An MCP endpoint at /api/mcp/ to search and read components, previews, component source, tokens, and pages.
• A connect dialog with client settings for Claude Code, Cursor, and VS Code.
• An AI assistant in the documentation app that uses the same tools, knows the current page, and links to what it read.
• AI connections for OpenAI-compatible APIs (gateways, local Ollama) and custom provider modules. In a registry, readers can add their own keys.

MCP and the assistant need a server: a workspace or a registry. A static site has neither.

Catalog authoring

• defineCatalogItem, one API for components and patterns. catalog.include registers the catalog directories.
• Previews are named exports. Preview<typeof item> types a React preview's args. A preview can declare a render function.
• Handoff builds a React item's CSS from the stylesheets its imports load.
• Previews keep their export order in builds, publish, and checkout.

Other changes

• Config profiles (--profile, HANDOFF_PROFILE), fromEnv() references, and one registry login per profile.
• -c, --config on every command.
• The build cache records every file a component's last build read, Sass partials included. Every full build and every publish uses it.
• Page titles use app.title. The default pages no longer show a hard-coded Handoff title.
• push, push:all, push:tokens, push:assets, and pull run as deprecated aliases of publish and checkout.

Breaking changes

• Node.js 22 or newer and npm 10 or newer are required.
• defineCatalogItem replaces defineReactComponent, defineHandlebarsComponent, defineCsfComponent, defineComponent, and definePattern.
• catalog.include replaces entries.components and entries.patterns.
• Previews are named exports, not a previews map. Fields are renamed, for example title is name and values is args.
• Declarations use .handoff.ts, .handoff.js, or .handoff.cjs. JSON declarations and legacy <name>.json and <name>.js files are not read.
• Figma settings moved to integrations.figma. The access token must be an environment reference.
• The static build goes to out/static, and fetched tokens and assets go to exported/. Neither path contains the project id. The public-<projectId> directories are removed.
• The make:template command is removed.
• The legacy /assets pages are removed. The foundation pages show logos and icons.

Upgrade

Follow Upgrade from 1.x.