Design an HTML or htmx app

Velloo’s HTML + htmx provider designs with native elements, the app’s own CSS, and inline styles. It works with server-rendered templates and plain HTML sites. Screens remain editable, static compositions; the canvas does not execute htmx requests or server handlers.

Initialize from the app root

cd your-app
velloo init
velloo run

Init detects an HTML app when it finds server templates or a plain HTML site without a script UI framework. You can also choose HTML + htmx explicitly. For a non-interactive scan:

velloo init --library html --initial-content scan

The scan creates placeholder screens for discovered routes and copies linked stylesheets it can find in the app’s source into assets/host/. Your agent rebuilds those placeholders with compose { mode: "replace" }.

Keep the app’s styles and assets with the design

hostApp.stylesheets lists the app’s stylesheets in cascade order. Velloo serves copies stored in the design, including images and fonts referenced by those stylesheets or by nodes. To refresh them after the app changes:

{ "tool": "store_host_files", "args": { "from": "source", "stylesheets": ["/static/site.css"] } }

Use the app’s served paths, such as /static/site.css or /build/style.min.css, rather than its source directory paths. Omit stylesheets to retain the current list. The operation updates that list and stores the files it can resolve on disk.

If a stylesheet exists only in a built or running app, capture the page through start_capture_session or velloo capture <url>, then copy from the capture’s archive:

{ "tool": "store_host_files", "args": { "from": { "captureId": "<id from list_captures>" } } }

With no explicit list, this uses the stylesheets linked by the captured page. screenshot and compare_to_url report missing stylesheet copies as hostStyles, with a suggested repair call. Copy again after adding nodes that reference additional app assets.

The design preview uses these stored files without contacting the running app. Rendering, export, and publishing include the stored copies too.

Compose semantic HTML

Use Html with an as tag and native attributes. Lowercase tags in compose resolve to Html on this provider too:

{
  "tool": "compose",
  "args": {
    "screenId": "contacts",
    "mode": "replace",
    "jsx": "<main vellooId=\"contacts-page\" className=\"page\"><h1>Contacts</h1><form hx-post=\"/contacts\" hx-target=\"#contact-list\"><label htmlFor=\"contact-name\">Name</label><input id=\"contact-name\" name=\"name\" /><button type=\"submit\">Add contact</button></form><div id=\"contact-list\">No contacts yet.</div></main>"
  }
}

className becomes native class on emit, and htmlFor becomes for. Use classes defined by your app’s CSS; new classes need CSS authored in the app. Focused update_props styling takes a plain object on this provider, such as { "padding": "24px", "color": "var(--color-primary)" }.

Use literal content and representative states. Preserve real hx-* attributes for implementation, but show loading, success, and error states as separate design compositions. If you set a custom form hx-trigger, include submit when submitting must swap a response.

Recreate and compare a page

Start the application yourself for the initial capture. Capture the real page, sign in in the capture browser if needed, and read get_capture for the screenshot and structural outline. Rebuild the whole page into editable nodes, then compare against the stored reference:

{ "tool": "compare_to_url", "args": { "screenId": "contacts", "source": { "captureId": "<id from list_captures>" } } }

Fix the largest topMismatches first. The porting guide explains captures, authentication, and comparison in more detail.

Emit into your templates

velloo emit contacts --to contacts.html

Through MCP, emit_code returns { format: "html", html, classesUsed, hostRoutes, warnings } alongside the screen identity and any diagnostics. It preserves native attributes and hx-* requests. Integrate the markup into your server’s template language, replace sample content with data, and implement the routes in hostRoutes.

HTML snippets emit as template partials: emit_snippet returns markup with $name markers and a params list for your agent to translate into the app’s template variables.

If inline styles use theme variables, emit_theme writes velloo-theme.css and tokens.json; link the stylesheet from the app’s layout. The emitted markup relies on your existing app styles as well.