Workspace
Running Handoff inside a client project repo, install, config, conventions, and the token pipeline.
A workspace is a client project repo (e.g. <project>/handoff/) that uses handoff-app as a
CLI tool, not as something it deploys. It holds component source and build artifacts, page/doc
markdown, handoff.config.*, and a design-system/ directory (the DTCG token pipeline). This is
one of the two run modes. The Registry is the
deployed, database-backed counterpart a workspace pushes to.
What lives in a workspace
| Piece | Where | Covered in |
|---|---|---|
| Config | handoff.config.{ts,js,cjs,json} | handoff.config.* resolution |
| Component / pattern declarations | entries.components / entries.patterns paths (.handoff.ts/.js/.json files) | Directory conventions |
| Page markdown | pages/**/*.md | Directory conventions |
| Design tokens | design-system/tokens/{primitive,semantic,brands}/*.tokens.json → design-system/dist/ | Token pipeline |
| Icons / logos | icons/catalog.json, logos/logo-set.json | Directory conventions |
| Local CLI/sync state | .handoff/ (gitignored) | .handoff/ runtime state |
The workspace never deploys itself
Every command that talks to a registry is explicit HTTP, driven by the CLI:
handoff-app fetch: pulls raw design tokens from Figma.handoff-app start: runs a local, filesystem-backed preview (no database). (handoff-app devis a Next.js-only debugging mode that builds no components.)handoff-app push:all/push: pushes config, tokens, components, pages, and assets to a registry overPOST /api/registry/*andPOST /api/sync/upload.handoff-app pull: pulls remote edits back down viaGET /api/sync/changes.
Two CLI commands (prepare-runtime, vercel-build) still materialize and build a full Next.js
app from the workspace; that's the deprecated v1 per-project deploy model. The registry is
now its own handoff-app deployment; workspaces push content to it instead. See
CLI reference for both commands' deprecation notices.
Where to go next
- Install: adding
handoff-appto a workspace'spackage.jsonand Node requirements. handoff.config.*resolution: the config file lookup order, the full config shape, and the hooking architecture.- Directory conventions: the standard folder layout, component declaration formats, and patterns observed across real client workspaces.
.handoff/runtime state: what's cached locally and why it's gitignored.- Token pipeline: Figma → DTCG → compiled CSS/SCSS/Tailwind.
- CLI reference: every command, grouped, with real flags.
- Local preview: the edit → preview → push loop.