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.

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 and semantic tokens;
• 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 call_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.

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.

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.

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.

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.