config.json

.design/config.json describes one design folder: its schema version, component providers, viewports, board organization, code generation, and host applications. It is validated when Velloo loads the folder.

Minimal shape

{
  "schemaVersion": 4,
  "toolVersion": "<installed version>",
  "name": "product",
  "libraries": {
    "app": {
      "id": "shadcn-upstream",
      "version": "<resolved version>",
      "source": "in-repo",
      "componentsPath": "../src/components/ui"
    }
  },
  "defaultLibrary": "app",
  "viewportPresets": [
    { "name": "Desktop", "w": 1440, "h": 900 }
  ]
}

Let velloo init write real version and path values. The supported provider ids are shadcn-upstream, none, html, mui, antd, and chakra; a library source is binary, cache, or in-repo.

What belongs here

Area	Fields	Purpose
Identity	schemaVersion, toolVersion, name, folderId	Format gate, writing version, design name, and optional stable cloud identity
Providers	libraries, defaultLibrary	Named provider entries and the fallback used by screens
Canvas	viewportPresets, defaultScreen, defaultBoard	Initial focus and useful viewport sizes
Board organization	boardOrder, boardGroups	Sidebar order and higher-level areas of work
App output	codegen, styling	Component locations/aliases and the CSS channel
Design guidance	designSystem.path	The app-relative design-system document agents follow
Theme provenance	themeSource	Where velloo init imported the theme from
Host integration	hostApp, hostApps, extensions	Resolve app-specific components in one app or a monorepo

defaultLibrary must name a key in libraries. Screens can select another registered key. codegen.componentsDir records where the app’s UI components live; codegen.componentsAlias preserves the import prefix used in emitted code.

hostApp covers a typical single application. hostApps names several roots in a monorepo; an extension can select the app whose imports and dependencies it needs.

A design recorded at a monorepo’s root resolves the app’s packages through the workspaces the root declares, when the members agree on one copy. To point the design at the workspace itself, use velloo design set-app-root, which rewrites hostApp.root and the values relative to it. See the CLI reference.

Repository components

A host app entry carries two optional fields governing repository components:

"hostApp": {
  "root": "../apps/web",
  "preview": "preview.web.tsx",
  "components": {
    "include": ["src/design-system"],
    "exclude": ["src/components/internal"]
  }
}

• preview points at the preview entry, resolved from the design folder root. Omit it and Velloo looks for preview.{tsx,jsx,ts,js} in the design folder (preview.<appKey>.* for a named host app), then a built-in framework recipe, then no wrapper at all. You rarely set this by hand: set_preview_entry writes the conventional filename.
• components.include / components.exclude bound discovery beyond what the app’s entries and routes import. include adds component roots — files or directories, relative to the host root — for a design system the routes don’t reach yet; exclude drops matching specifiers or paths. Both are optional, and a folder normally needs neither.

The required name is the design’s identity in the CLI, canvas title, and agent session. It lives with the design so it survives a move. For a design outside the repository, an app:<relative-path> value resolves from the application root recorded in its machine-local binding.

HTML stylesheets

For an HTML design, hostApp.stylesheets is a list of root-relative app URLs or HTTPS URLs, in cascade order (for example ["/static/site.css"]). The preview serves stored copies under assets/host/, rather than fetching the running app. Use store_host_files to populate or refresh the copies and update the list.

Written design guidance

designSystem: { "path": "DESIGN.md" } selects a document relative to the host app root. Absolute paths and .. segments are rejected. Velloo reads the current document, identifies it in get_theme and agent instructions, and leaves the source untouched.

A design with no repository document to follow keeps its own guidance.md in the design folder. That is the one guidance file Velloo writes: the canvas’s Design language stage and set_design_language save its Overview and Do's and Don'ts sections there. A repository DESIGN.md is only ever read.

Without an explicit path, Velloo looks for a design-system DESIGN.md or design.md in the app root, repository location, and design folder, then for guidance.md in the design folder. Automatic discovery requires design-token frontmatter or at least two visual-design sections, so an architecture document with the same filename is ignored. See Theme your design.

Where the theme came from

velloo init records the source of the design’s theme:

"themeSource": { "kind": "mantine", "files": ["src/theme.ts"] }

kind is stylesheet, design-md, mantine, mui, library-defaults (with library, such as "Mantine") or preset. files are relative to the host app root, the file kind names first, then any stylesheets it imports, the Tailwind config and the modules that load its fonts. An agent on an app themed in JavaScript is told to compare get_theme with that file instead of importing a stylesheet. Applying import_theme to the default theme updates it. A design without the field behaves as before.

What does not belong here

Repo-wide design discovery lives in velloo.json at the repository root. It lists in-repository design paths and may select a default by name:

{
  "$schema": "<optional schema URL>",
  "designs": ["design/product", "design/marketing"],
  "defaultDesign": "product",
  "feedback": { "enabled": true }
}

Every entry is a path to a design inside the repository; an entry pointing outside it is refused, because a repository you cloned must not be able to aim Velloo elsewhere. defaultDesign must match the name in one listed design’s .design/config.json. The pre-v4 projects / defaultProject shape is read for migration and rewritten by velloo upgrade.

A design kept outside the repository, whether in Velloo-managed storage (velloo init --external) or a directory you chose, never appears here. It is recorded only on your machine under ~/.velloo/designs/.locations/, and commands run inside the checkout see it alongside the velloo.json designs. Use velloo design bind <design folder> to attach one to a moved or cloned checkout. An older { "managed": … } entry is refused with the same instruction: remove it, then bind the folder.

feedback.enabled is the repo-level decision about whether the send_feedback tool exists. velloo init’s setup page writes it when you answer the feedback question on its Cloud step, which it asks only once you’re signed in and only while the field is unset. Personal contact consent stays on the machine in ~/.velloo. Older folder-level feedback fields can still be read during migration but should not be copied into new configs.

What is not in config

Some newer parts of a design are stored beside the config, not in it: a board’s flow arrows (edges in boards/<id>.json), a frame’s fit, named themes (theme/<name>.json), and the design’s written rules (guidance.md). The design folder describes each. None of them changed the config schema, so a design needs no migration for them.

Editing guidance

Use velloo design add, the canvas, or MCP lifecycle operations for routine changes. A running canvas validates and reloads hand-edited config, including provider and stylesheet changes. An invalid edit is reported while the last valid config stays active. If the canvas is stopped, run velloo run to validate the file. velloo status only lists running canvases and cloud sign-in; it does not validate config.