Design Artifacts
AI design-workbench outputs, generated images with a derived component spec.
A design artifact is a saved output of the registry's AI design workbench: an image (an AI-generated composition, or an uploaded reference), the context that produced it, and, once extracted, a structured component spec an engineer or agent can build a real component from. It's a design-side reference a component can be generated from or linked back to, not a component or pattern itself.
Requires AI configuration
The design workbench needs HANDOFF_AI_API_KEY (or a cloud AI proxy) configured, see
Registry → Environment variables. Without it, /design and its
MCP tools are unavailable.
Shape
handoff_design_artifact carries the full workbench state for one artifact: status
(draft/review/approved), the final imageUrl plus sourceImages (uploaded references),
componentGuides (selected existing components used as style reference),
foundationContext (a snapshot of foundations sent to the AI), conversationHistory
(iteration-by-iteration prompt/image pairs), extracted assets + assetsStatus, and
componentSpec (structured JSON, the part that connects this entity to
Components) and componentSpecMd (an editable markdown version,
authoritative after a user edits it) with its own specStatus. A publicAccess flag opts an
artifact into the public
share page. Two job tables back the async parts of this pipeline:
handoff_design_generation_job (image generation) and component_generation_job (turning a
spec into a real, built component, with an iteration loop bounded by maxIterations and a
visualScore from vision-based comparison).
Three surfaces
| Surface | Where |
|---|---|
| UI | /design (the workbench itself), /design/library + /design/library/[id] (saved artifacts, browse/detail), /design/library/[id]/share (public share page — only reachable when publicAccess is set), /design/assets (extracted asset review), /design/settings, see Registry → Stakeholder-facing UI routes. |
| REST | A family of POST/GET /api/handoff/ai/* routes covers design-artifact extraction/CRUD and generation (generate-design, generate-pattern, foundation-preview, layout-guide analysis) — called out in API → /api/handoff as an internal/evolving surface not yet fully spec'd in openapi.yaml, so it isn't enumerated route-by-route here. |
| MCP | handoff_list_design_artifacts, handoff_get_design_artifact, handoff_create_design_artifact (requires a real user JWT — explicitly rejects the legacy sync secret, since it attributes authorship to a specific person), handoff_get_component_spec (the structured spec + editable markdown for a saved artifact), handoff_generate_component_from_design (fetch, or queue generation of, a spec + assets for local component generation). Registry mode only for most of these. See MCP → Tool catalog § Design Artifacts. |
Relationship to Figma MCP
handoff-app's MCP RFC describes an illustrative "Figma → Handoff component" flow where a
design agent combines Handoff's own context tools with a separate Figma MCP server
(get_design_context, get_screenshot). Handoff deliberately doesn't embed a Figma client
inside its own MCP server; Figma access is a different MCP server's job, composed by the agent.
Design artifacts are Handoff's own path to the same destination (a built component from a design
reference) that doesn't depend on a second MCP server being connected.