Components (Structured + Raw + Rendered)
How Handoff represents a component across its documentation, raw source, and rendered preview.
A component in Handoff is three related but distinct facets of the same entity, not one blob:
- Structured: the declaration: title, description, group,
properties(the typed prop contract), andpreviews(named value-sets). Read/written as JSON. - Raw: the actual Handoff-layer source files (
.handoff.tsdeclaration, templates, styles, scripts) pushed from the workspace, stored for display and forpull. - Rendered: the built preview artifacts (HTML/CSS/JS/JSON) produced by the workspace's build step and pushed alongside the declaration.
This split mirrors the same authoring-spec-vs-canonical-record distinction the token pipeline
uses for DTCG: a component author writes a friendly defineComponent({...}) module in the
workspace (the authoring adapter); what gets pushed and stored is the validated, three-facet
canonical record.
Shape
| Table | Facet | Holds |
|---|---|---|
handoff_component | Structured | id, path, title, description, group, type, properties, previews, and a full data blob for round-trip. source marks provenance: disk (workspace filesystem), db (created in-app), or figma. |
handoff_component_source | Raw | One row per (componentId, filePath) — the actual .handoff.ts/template/style/script file contents pushed from the workspace. External dependencies (e.g. a shared UI package in a monorepo) are not stored here; those come from git. |
component_artifact | Rendered | One row per (componentId, filename) — built HTML/CSS/JS/JSON, populated only by the push API. The registry never builds a component itself; all builds happen locally in the workspace (see Workspace → CLI reference). |
handoff_component_version | History | One row per push, capturing a full metadata snapshot, a change summary, source-file hashes, and the pushed-by/"why" (message + lazy AI summary), see Changelog / audit. |
handoff_component_preview | Registry-authored previews | Distinct from the code-authored previews inside handoff_component.data (which are replaced wholesale on every push): these are named value-sets authored by a PM/designer/LLM directly in the registry, version-anchored to a component_version so they stay valid even after the contract moves on. |
Validation is a fourth, cross-cutting facet
Each push can carry per-component validation results (accessibility, schema, contrast, or
custom validators, see handoff-app's ADR-002). These aren't a separate row per component;
they roll up into the append-only handoff_validation_run health-snapshot log surfaced at
/system/health, see Changelog / audit for how change
history and validation history relate.
Three surfaces
| Surface | Where |
|---|---|
| UI | /system/component (catalog) and /system/component/[component] (per-component doc + rendered preview), see Registry → Stakeholder-facing UI routes. |
| REST | Public: GET /api/components (flat catalog list), GET /api/component/{path} (serves one built artifact file). Session-authenticated: GET/PATCH /api/handoff/components (PATCH is admin-only metadata edit), POST /api/handoff/components/build (enqueue a preview build), GET /api/handoff/components/validation, GET /api/handoff/components/history, see API → /api/handoff. Push/pull specifically go through POST /api/sync/upload / GET /api/sync/changes, see API → /api/sync. |
| MCP | handoff_search_components, handoff_get_component (slimmed for context — excludes compiled sharedStyles CSS, validation results, and Figma sync metadata), handoff_get_component_reference (style reference image for a slot), handoff_get_reference (generated reference material by id). Registry-authored previews: handoff_create_preview, handoff_update_preview, and handoff_preview_component (an interactive MCP App, not plain JSON). History: handoff_component_history, handoff_recent_changes, handoff_change_why. See MCP → Tool catalog § Components / Previews / Change Inquiry. |
What v1's template pages become in v2
The legacy site's managing_handoff/{handlebars,react,csf}_templates pages described a
materialize-per-client templating model, see Registry → Model.
v2 replaces the bulk of that with the build/preview pipeline above plus MCP
stack guides (per-stack authoring conventions an agent reads before
generating a component). One CLI command from the old model still ships: make:template <component> [state] scaffolds a new template for an existing component, see
Workspace → CLI reference § Eject / make.