Working with your agent

Your agent does the production labor; you set the goal, judge the alternatives, and decide what ships. The strongest Velloo sessions are not “generate a page” prompts. They are short design loops with a visible baseline, distinct directions, and a clear moment when exploration turns into implementation.

Set Velloo up for the app first

When the design is for an existing app, the first thing to ask for is setup: /velloo:setup in Claude Code, or “set Velloo up for my app” in any agent. The first task velloo init’s setup page gives your agent already opens with it.

Setup is done once per design, before the first screen. The agent matches the app’s theme and real fonts, gets the app’s own components rendering, checks every one of them in a single render, and proposes a design language. It leaves behind:

• a theme that is the app’s, with what could not be imported named rather than guessed;
• a preview entry (preview.tsx) when your components need providers or global CSS;
• a note on the board, or a reply when there is no board yet, listing what is exact, what is adapted, what is unverified, and what will go stale; and
• the design’s intent and its Do’s and Don’ts in guidance.md, for you to review on the canvas under Design language.

Run it again when the app’s design language changes. Skip it for a design with no app to match. Port an existing page walks through the steps.

Start with the context the job needs

For a new design, the goal, audience, component system, and product constraints may be enough to begin. When evolving something that already exists, have the agent read the relevant host app and inspect the Velloo folder before it creates anything. It should understand:

• the screen or component being changed and the target viewport;
• the selected provider, its component catalogue, and styling channel;
• the current theme, semantic tokens, and the followed DESIGN.md reported by get_theme.designSystem.path;
• existing boards, screens, snippets, and useful extensions; and
• the product goal and constraints that make a direction successful.

On the default guided MCP surface, the agent calls these native discovery operations through read_velloo and uses operation_schema when it needs an exact contract. Full-surface clients see the native names directly.

Recreate when redesigning

When an existing page is in scope, first capture or faithfully rebuild it at the same viewport. This is a calibration step, not busywork: it proves the agent understands the component system and gives you a visual baseline for every proposed change.

Start the app yourself when a live reference is needed; Velloo does not run it. Match its fonts and theme, and recreate the whole page, top to bottom, as editable parts. Placing the entire app or page as one repository component or extension may look accurate but prevents meaningful edits; screen/opaque warns about that.

Use velloo capture <url> for a live page. Ask the agent to compare the recreation with the source and fix material differences before exploring directions.

Explore in meaningful branches

Put alternatives side by side on a board. Each direction should test a different hierarchy, interaction idea, information density, or visual system, not a shuffled heading and another accent color.

Use one screen in several frames when reviewing the same design across breakpoints or contexts. Use separate screens when the underlying structure should diverge. Snippets are useful for repeated structures such as pricing tiers or navigation rows, but do not abstract a one-off composition prematurely.

Draw the flow, not only the screens

When the work is a sequence, such as a sign-up or a checkout, ask for the board as a flow. The agent joins the frames with arrows: transitions between steps, and the loading, empty, and error states of each step. You can draw and relabel arrows yourself on the canvas.

A flow makes the missing parts visible. The agent’s read of the board names frames no arrow touches and any step that loads but has no error state. Treat those as questions to settle before implementation, not details to fix in code.

Work in big strokes, then focus

A good agent builds coherent subtrees, uses bulk patches or a plan for related changes, and assigns stable node ids to anything it expects to revisit. Numeric tree paths can shift when siblings move; stable ids keep later edits and annotations attached to intent.

The agent composes with the JSX it would write for the app: data in a const, a list as a .map, small components, or a whole page file read straight from the repo. It can read a screen back in the same form, edit it, and send it again. Nothing in that JSX executes; it is read as data and written out as elements.

Prefer semantic theme tokens so light and dark modes remain connected. Mutation, screenshot, and emit results carry diagnostics: invalid Tailwind classes, raw colors that bypass the theme, components that failed to render. Treat them and component prop warnings as a request to self-correct in the same turn.

Verify the render

The canvas is evidence. Ask the agent to:

• capture screenshots at the review viewport;
• compare light and dark modes;
• inspect a rendered node when props or layout are ambiguous;
• act on the diagnostics returned with each edit; and
• respond to node-level annotations, then mark the work resolved.

Diagnostics are triage signals, not a substitute for looking. A structurally valid tree can still be a weak design.

Implement only after a decision

Velloo designs are static compositions. Once you choose a direction, the agent can emit the screen’s structured code representation and implement it in the host app’s conventions. Routing, state, data, accessibility behavior, and business logic are still application work.

A flow’s arrows are a spec for that work, not behaviour. Nothing is emitted for them. The agent reads the board, emits each step’s and state’s screen, and writes the routing and state handling itself.

Run the application and compare the implementation with the chosen frame. The loop is complete when the shipped UI, not only the design JSON, matches the decision.