Concepts
Per-entity reference pages, every core Handoff data type and its UI + REST + MCP surface.
Handoff's canonical data model is small: a handful of entity types, each stored in Postgres once a workspace pushes it, and each meant to be reachable through the same three channels, the three-surfaces principle introduced in Architecture. This pillar is one page per entity, each covering:
- What it is: the concept in plain terms, and how it differs from its neighbors.
- Shape: grounded in the actual Postgres tables (
schema-pg.ts), not an idealized model. - Three surfaces: where it shows up in the registry's own UI, which REST routes read/write it, and which MCP tools an agent calls to reach it, each linking out to the fuller reference on its owning pillar (API or MCP) rather than repeating it here.
Use this pillar when you already know what you're looking for (a component, a token, an asset) and want all three surfaces side by side. Use API or MCP directly when you're starting from a route or a tool name instead.
The entities
| Entity | What it is | Page |
|---|---|---|
| Tokens | DTCG-format design tokens — primitive + semantic tiers, multi-axis (brand × scheme). | Tokens |
| Components | A component's structured metadata, raw source, and rendered build output, together. | Components |
| Patterns | Saved compositions of component blocks (playground pages). | Patterns |
| Pages / docs | Markdown documentation pages, pushed or agent-authored. | Pages / docs |
| Design artifacts | AI design-workbench outputs — generated images with a derived component spec. | Design artifacts |
| Assets | Icons, logos, fonts, and general uploaded media. | Assets |
| Changelog / audit | Unified, cross-entity change history with a "why," not just a "what." | Changelog / audit |
How an entity gets here
Every entity above follows the same lifecycle: authored or extracted in a workspace (or, for a
few types, created directly by a stakeholder or an agent in the registry) → validated → pushed via
the sync or registry push APIs → stored in Postgres → served back out through
the stakeholder UI, REST, and MCP. See
Registry → Model for the DataProvider mechanism that makes the same
rendering code work whether the data came from Postgres or, in workspace dev, straight off disk.