# Velloo documentation for LLMs

> Velloo is a local-first design canvas for AI coding agents. Use it to create and evolve the visual parts of products with real component-based interfaces, review the result, and carry the work into the host application. It is open source under Apache-2.0 and published to npm as `velloo`.

Human documentation: https://velloo.design/docs/
Source: https://github.com/velloo-design/velloo
Package: https://www.npmjs.com/package/velloo

## Product boundary

- The source of truth is a local design folder of ordinary JSON. It can live inside the application repository or elsewhere, and Git is optional.
- Velloo designs are static interface compositions. Implement routing, data flow, event handlers, and application logic in the host app.
- The local design loop needs no account. Velloo Cloud is optional and used for sharing, comments, teams, and hosted asset generation.

## Install and initialize

```bash
npm install -g velloo
cd /path/to/app
velloo init
velloo run --open
```

The npm package works on macOS, Linux, and Windows with Node.js 18 or newer and bundles its own Bun runtime. On macOS and Linux, `curl -fsSL https://get.velloo.design/install.sh | bash` is an alternative standalone installer.

`velloo upgrade` updates the installation first, then migrates every design associated with the current checkout using the new binary and refreshes installed agent skills. Pass a design name or path to migrate only that design. `--check` and `--dry-run` preview, `--binary-only` and `--design-only` run one half, and `--no-skills` skips the skills refresh. Updates follow the channel that installed Velloo (npm or the standalone installer). Outside a checkout or design it only updates the installation.

`velloo init` is goal-first. When it finds a host application, it offers Redesign a screen, Redesign a component, Custom request, the Elsewhere welcome sample, or Blank. When there is no UI code to read, it offers Design from a live site (the agent starts a capture session so the user can log in), the Elsewhere welcome sample, or Blank. The Elsewhere sample is a travel app with imagery, dark mode, and a `theme/default.json` built from the `elsewhere` preset. Init asks whether the design lives in the repo (normally `velloo/`) or outside it, in Velloo-managed storage under `~/.velloo/designs` (`--external`) or a custom path. A design outside the repository is a local design: recorded only on this machine, never in `velloo.json` or the checkout, not version-controlled, and wired to agents through global configs only. Velloo never commits or reverts design files and does not require Git; a plain directory with no repository works. It can scan routes and themes, configure the component provider, create the design folder, register an in-repo folder in the repo-level `velloo.json`, and wire installed agents.

Supported providers are shadcn/ui, Material UI v6, Ant Design v5, Chakra UI v2, and a no-library primitive set. Preserve the selected provider's styling idiom: Tailwind `className`, `sx`, or inline styles as appropriate.

The provider is not the whole catalogue. The host app's own components — from a package it depends on (Mantine, NextUI, a private design system) or from its own source — are **repository components**: discovered from what the app renders, mounted for real on the canvas from the app's own install, and emitted with their exact imports. A library with no adapter is still rendered natively; do not approximate one with primitives. See "Repository components" below.

## A flexible workflow

1. **Design with the user.** Start from a new idea, a fresh screen, or an interface they want to evolve. Read only the product context needed for that job.
2. **See, decide, and iterate.** Show the rendered result, invite direction, respond to annotations, and explore alternatives when that helps the decision.
3. **Implement.** Once the user is ready, use Velloo's emitted structure as guidance and write production code in the host application's conventions.

When evolving existing UI, first calibrate against the host app and capture or faithfully recreate the current screen. Compare at the same viewport so the baseline is trustworthy. This extra step applies to redesign work; it is not required when creating something new.

## Mental model

- **Design folder:** one local design workspace with config, screens, boards, snippets, themes, assets, and cache.
- **Screen:** the reusable component tree being designed.
- **Board:** a review surface that arranges frames and annotations.
- **Frame:** a placement of a screen at a viewport. Several frames can point to the same screen and stay in sync.
- **Node:** an element in a screen tree. Stable ids allow focused edits, inspection, and annotations.
- **Snippet:** a saved composition that can be reused in screens.
- **Repository component:** one of the host app's own components, discovered rather than registered, carrying a `$repo` identity and rendering from the app's own install.
- **Extension:** a hand-registered host-app component for the cases discovery cannot serve — typically a dynamic leaf that needs a bundled live island.

The repo root may contain `velloo.json`, whose current shape lists in-repository paths in `designs` and can select a `defaultDesign` by name. Each design's `.design/config.json` carries its required `name` and runtime settings; external designs are associated with the checkout only on the local machine. Current designs use schema version 4; use `velloo upgrade` instead of manually imitating an older schema.

## Agent connection and MCP surfaces

`velloo connect` writes MCP configuration for Claude Code, Cursor, Codex, Continue, Claude Desktop, opencode, Droid, Cline, Gemini CLI, Windsurf, and VS Code/GitHub Copilot. It also installs agent guidance: a Claude Code plugin marketplace at `~/.velloo/claude-plugins` (enabled in `~/.claude/settings.json`), `.agents/skills/` copies for opencode, Droid, Cline, Gemini CLI, and Codex, a Gemini extension at `~/.velloo/gemini-extension`, and `.cursor/rules/velloo.mdc` for Cursor. `--no-skill` writes only MCP configuration. Manual stdio configuration follows the common shape:

```json
{ "mcpServers": { "velloo": { "command": "velloo", "args": ["mcp"] } } }
```

Project-scoped configuration normally uses plain `velloo mcp`, so moving or renaming a design does not leave a stale path in the client. In a checkout with several designs, the session instructions identify the current design and agents can call `list_designs`. A stdio session can use `switch_design`; an HTTP client must reconnect with `velloo mcp --http <name>`. If resolution is ambiguous, Velloo opens the first design by name and tells the agent to confirm before changing anything.

The default MCP surface is `guided`. It advertises three compact tools:

- `call_velloo`: invoke one native Velloo operation.
- `run_velloo_plan`: run a planned sequence of operations.
- `operation_schema`: retrieve the exact schema for an operation before calling it.

Use the runtime operation catalogue and schemas rather than guessing arguments; every input is strict, so an unknown argument is rejected. Native operations cover discovery, restricted-JSX composition, focused node edits, lifecycle, themes, captures, inspection, annotations, and code emission. The core verbs:

- `list_components`: the component catalogue — the app's own components (`kind: "repo"`), library components, extensions, and snippets (`kind: "snippet"`).
- `preview_status` / `set_preview_entry`: check and write the preview entry the app's own components render inside. Run `preview_status` before the first screen in any folder whose app has components.
- `compose`: build or replace a screen subtree from restricted JSX; snippets are placed by their PascalCase tag, stable ids come from the `vellooId` attribute, and a prop may take an element (`leftSection={<Icon name="Plus" />}`).
- `update_props`: focused prop patches; styling is the patch's `style` field (a className string on shadcn/Tailwind).
- `update_snippet_instance`: change a placed snippet's arguments or inner props.
- `set_theme`: tokens, presets, seed colors, fonts, typesets, and custom CSS in one operation.
- `screenshot`, `inspect`, `compare_to_url`, and `emit_code`: verification and handoff.

There is no separate audit or class-validation tool: mutation, screenshot, and emit results carry `diagnostics` (invalid classes, raw colors, render failures) to fix in the same turn. A failed guided call returns the corrective schema when possible.

Clients that work better with conventional function schemas can start the bridge with `velloo mcp --surface full`. The equivalent environment variable is `VELLOO_MCP_SURFACE=full`. Both surfaces invoke the same operations and share the same daemon state.

Useful runtime guides are exposed as `velloo://guide/*` MCP resources.

## Repository components

The host app's own components appear in `list_components` on Repo shelves, grouped by source. Compose them by id like any other tag; compound parts and qualified names are dotted tags (`Tabs.List`, `Mantine.Button`). Prefer them over rebuilding the same component from primitives.

- **Discovery** reads the app's entries and routes, follows local imports and barrels, and records the JSX elements it finds. It never executes repository code and never walks `node_modules`, so a package contributes only the components the app actually renders from it. Modules an adapter owns are left to that adapter. `hostApp.components.include/exclude` bounds the scan.
- **Extraction** reads `<Name>Props`, literal unions, `@default` and JSDoc from the host's own declarations, compound parts from `staticComponents` and usage, and preview `states` from Storybook args and real call sites. Entries carry `provenance` (where the app uses it) and `dataSources` (hooks it calls for itself — a component that reads a store will not be filled by props alone). `repo-components.json` in the design folder overrides inference and reports stale keys.
- **Identity** is `$repo` on the node — `{ importPath, exportName, member?, app?, proxy? }` — while `$ref` stays the JSX name. A collision with a provider component is qualified. Never look a `$repo` node up in a provider manifest by `$ref`.
- **The preview entry** supplies the providers and global CSS the components need: `preview.tsx` in the design folder (`preview.<app>.tsx` for a named host app), else a built-in framework recipe, else nothing. Its default export receives `{ children, colorScheme, theme, recipeTheme }`. Write it with `set_preview_entry`; keep it free of network calls and credentials.
- **Recipes** are the built-in form of a preview entry for a popular library — wrapper, stylesheet, token-to-native theme mapping, overlay adaptations, and a stylesheet probe. Mantine is the first. A recipe is not an adapter and does not need to become one.
- **Fidelity** is per component, not per screen: each one falls back alone to its proxy snippet or a labelled frame, leaving the rest of the screen real. `component_status` reports `exact`, `adapted`, `unstyled`, `proxy`, `fallback`, `unavailable`, or `unknown`, with a stable `code` (`missing-provider`, `render-threw`, `missing-export`, `compile-failed`, `server-only`, `resolve-failed`, `unstyled`) and a `remedy`. Check it before claiming a component renders exactly; `unstyled` in particular looks fine and is not exact.
- **Emit** prints a repository component as itself with its exact import. Nothing is translated into another styling system.
- **Trust boundary:** repository code runs only in the user's local browser. Publishing uploads locally captured PNGs; the cloud renders design JSON with proxies and never executes app code.

## Local architecture and files

Velloo runs one persistent local canvas daemon per design folder. The browser canvas and every connected agent share that state and mutation layer. `velloo run` stays attached in an interactive terminal; press `o` to open, `b` to leave it in the background, or `q` to stop. In a non-interactive shell it starts in the background automatically. A daemon shuts down after 5 minutes with no canvas tab or agent connected.

Ports are sticky: a folder reuses the port recorded in `.design/cache/port.json`, otherwise tries 7300, then a port in 7310–7399 derived from the folder path. `--port` overrides. Do not assume 7300; use the URL Velloo prints.

Typical design-folder contents:

- `.design/config.json`: schema, providers, viewports, board organization, codegen, host apps
- `screens/`: reusable screen trees
- `boards/`: frames, layout, and review context
- `snippets/`: reusable component compositions
- `theme/`: design tokens, named themes, typesets (`typography.typesets`), and optional `custom.css`
- `assets/`: images and other local assets used by screens
- `preview.tsx`: optional preview entry — providers and global CSS for the app's own components
- `repo-components.json`: optional corrections to discovered app components
- `.design/cache/` and `.velloo/`: generated runtime state; do not commit unless the folder says otherwise

Use the MCP lifecycle operations or the canvas for routine edits. Keep JSON valid and preserve stable ids when a focused edit will do.

## CLI map

- Start and organize: `velloo init`, `velloo design`, `velloo upgrade`
- Run and connect: `velloo run`, `velloo connect`, `velloo mcp`, `velloo status`, `velloo stop`
- Capture existing UI: `velloo capture`, `velloo browser`
- Produce artifacts: `velloo export`, `velloo emit`, `velloo theme export`, `velloo render`
- Optional cloud: `velloo login`, `velloo publish`, `velloo logout`
- Shell integration: `velloo completions`

Run `velloo <command> --help` for the installed build's flags. An action is a verb (`velloo publish`) and managing a set is a noun plus verb (`velloo publish list`); flags never switch the operation. A design is the argument where it is the subject (`velloo run web`) and `--design` where the argument is something else (`velloo emit home --design web`). Important distinctions:

- `capture` opens a headed browser on a live page; `c` captures the page, `t` only its theme. `capture list` and `capture delete <id|all>` manage stored captures; `--design` picks the design.
- `browser install` installs the screenshot browser (`--full`, `--with-deps`).
- `export` creates a screen, frame, or board as PNG, PDF, or standalone HTML.
- `emit` prints the structured screen output used to implement it in the app.
- `render` is a lower-level screen renderer, mainly useful to developers and automation.
- `design list` numbers the designs associated with a checkout; other design commands can use `--id <number>` to disambiguate. `design remove` deletes an in-repo design from disk; an external design is forgotten but keeps its content unless `--delete-content` is passed. It needs `--yes` without a terminal. Other subcommands include `add`, `move`, `rename`, `upgrade`, `bind`, and `set-app-root`.
- `status` lists running canvases and cloud sign-in; it does not validate config. `velloo run` does.

## Velloo Cloud

Cloud is opt-in. `velloo login` authenticates the CLI and `velloo publish` creates an external review link (`--boards`, `--new`/`--update`, `--public`/`--private`/`--password`, `--team`, `--team-only`, `--public-comments`; `publish list` and `publish remove <url>` manage links). When the account can publish to more than one team, publish asks which (or needs `--team` without a terminal). Links can be public, password protected, private to the organization, or (Business) limited to one team; private and password links need a Team or Business plan. Roles are owner, admin (optionally with purchasing), member (publishes, paid seat) and reviewer (comments, free); guests are invited to one board by email and need no account. Reviewers never publish. Public commenting is a per-board switch, off by default. Hosted `generate_asset` spends image-generation credits. Review comments can sync back to the local canvas for resolution. Organizations, invitations, roles, Team and Business plan mechanics, usage/storage controls, and hosted image/SVG generation belong to the cloud layer; the design source remains local.

## Human reference

- Quickstart: https://velloo.design/docs/quickstart/
- Core concepts: https://velloo.design/docs/concepts/
- Repository components: https://velloo.design/docs/concepts/repository-components/
- Working with an agent: https://velloo.design/docs/agent/
- Agent connection: https://velloo.design/docs/agent/connect/
- CLI: https://velloo.design/docs/reference/cli/
- MCP overview: https://velloo.design/docs/reference/mcp/
- Config: https://velloo.design/docs/reference/config/
- Cloud: https://velloo.design/docs/cloud/
- Roles and permissions: https://velloo.design/docs/cloud/permissions/