Overview

Handoff is design system documentation and automation, built to be read by more than just developers. A UI for humans to browse, an MCP server for AI agents to query, and a REST API for scripts and other services all read from the same underlying data. None of it is hand-written prose that quietly falls out of date the first time a component changes.

You'd reach for it because most design system docs are written once and trusted forever, right up until the components change and nobody updates the page. Handoff inverts that: your tokens, components, pages, and assets live in one place and get served out fresh everywhere they're needed, so a developer reading the UI, an agent calling MCP, and a script hitting the REST API are all looking at the same facts.

At a high level, here's how: a workspace (your project's own repo) pulls tokens from Figma and pushes everything it has, tokens, components, docs, icons, into a registry, a Postgres-backed deployment of the same application. The registry is the hub. The UI, the API, and MCP all read from it. Architecture is the deep dive on how that actually works; this page is the argument for why it's worth doing.

Documentation and automation, for humans and agents alike

Handoff isn't a docs site with an API bolted on afterward. Every piece of your design system, tokens, components, patterns, pages, assets, is meant to be reachable three ways: a UI a person can click through, an MCP server an agent can call, and a REST API anything else can hit. Add a token or ship a new component once, and all three surfaces pick it up, because they read from the same data instead of three separately maintained descriptions of it. See Architecture → The three-surfaces principle for how that's enforced in the codebase, not just claimed in a diagram.

A data hub you own, not a rented corner of someone else's SaaS

Your design system's data, tokens, component metadata, documentation, brand assets, lives in your own registry, backed by Postgres you control. It isn't sitting inside a third-party product you're renting seats on. You can query it, export it, point another tool at it, or build something new on top of it. Nothing here is locked behind someone else's UI or someone else's pricing tier.

This is also the shape the rest of Handoff assumes: several sources feeding in, one hub holding the data, and several things built on top of it.

Built for more than the design engineering team

A design system only earns its keep if people beyond the two or three engineers who built it can actually use it. Handoff is built so a PM can browse the UI without asking someone to walk them through it, a non-developer can prototype an idea against real components instead of a mockup, and anyone curious can poke at the actual tokens and patterns rather than a screenshot of them. The more people who can build on a design system, the more it's worth having one.

The payoff: automation that gets smarter as your data does

This is where the hub model actually pays off. An MCP tool is only as good as the data behind it, and a lot of design-system MCP servers are thin wrappers around a handful of hand-maintained facts. Handoff's tools read the same rich, structured, constantly-synced data the UI and API do: real component metadata, real token values, real usage docs, kept current because pushing an update is part of the normal workflow, not a separate documentation chore.

Better data means an agent can do more with it: generate a component that actually matches your system's conventions, answer a token question with the real value instead of a guess, or pull in a stack guide before writing a line of code. The more automated and accurate the data going in, the more capable the agent coming out. See MCP → Tool catalog for what that looks like today.

Where to go next

• Architecture: how it actually works, the two run modes, the DATABASE_URL switch, the three-surfaces principle, and the workspace → registry flow.
• Workspace: installing the CLI, project conventions, the token pipeline. Start here if you work in a client project repo.
• Registry: deploying a registry, first-admin setup, env vars, the stakeholder-facing UI.
• API: the REST surface: OpenAPI spec, auth & scopes, and each route cluster.
• MCP: the Model Context Protocol server: tool catalog, auth, onboarding.
• Concepts: one page per data type, showing its UI + REST + MCP surface together.