How to use HTMX UI Platform

Projects

A project is one website. Create one from Projects with a name; it starts as a small working site (a home page and an about page) so the builder has something to reshape. Projects live in a workspace; you can have several workspaces and switch between them from the account menu.

Each project's Settings page lets you rename it, change its address, archive it (hide it without deleting anything) or delete it.

The workspace

Opening a project shows three areas, which you can resize or collapse:

• Chat on the left: your conversation with the builder.
• Files and editor in the middle: every page, style and image, with a code editor. Most people never need it, but it's always there.
• Preview on the right: your site, live, updating as files change.

The Code / Split / Preview switch at the top shows one side or both. Reset layout in the project menu puts everything back.

Talking to the builder

Describe what you want in plain words. The builder reads the pages it needs, makes the changes, and replies with what it did. While it works you see each step as a card ("Read partials/header.html", "Edited pages/index.html"), and you can open any of them to see the details. Press Stop at any time.

• Bigger jobs get a plan: a checklist it ticks off as it goes.
• When something is unclear it asks, with options you can click to answer.
• It checks its own work. After writing a page it renders it and checks links, images, icons and styles. Anything it couldn't fix is listed under the reply, linked to the exact line.
• It looks things up. Before using a component it hasn't used in your project, it reads that component's documentation.
• Regenerate asks again; Edit and resend puts an earlier message back in the box.

Each project can have several conversations, for example one for the homepage and one for the blog. Start one with the + next to the conversation name.

Pointing at elements

Click the pick button (the arrow in a box) in the preview or the chat box, then click any element on your page. It's attached to your next message as a chip, and the builder is told which file and line made it. Shift-click picks several; Esc stops picking.

"Make this bigger", "use our green here", "link this to the contact page": pointing makes short messages precise.

The preview

• Screen sizes: desktop, tablet and phone, from the screen icon.
• Navigation: back, forward, reload and an address bar, like a browser.
• Console: errors from your page show up here, with a count on the button.
• New tab: open the preview on its own. The link is private to people with access to your project.

If a page can't be shown because of a mistake in it, the preview says what went wrong and on which line.

Versions and undo

Every builder reply that changes files is saved as a version, and its reply has an Undo button that puts the files back as they were. Saving in the editor is kept too. Open Version history (the clock at the top) to see every version, what changed in it, and to restore any of them. Restoring and undoing are saved as new versions, so they can be undone as well.

Branches

A branch is a copy of the project you can change without touching the main version: perfect for a redesign or a risky idea. Create one from the branch menu at the top, or start a conversation on its own branch. When you like the result, merge it into main from the branch menu; if the same file changed on both sides, you choose which version to keep.

Project notes

Every project has a file called AGENTS.md, shown first in the file list. The builder reads it before every reply. The top part explains how the site is built; the bottom part, after the marker line, is yours: brand colours, tone of voice, pages to keep, things to avoid. The builder may add decisions there too, so it remembers them next time. Older projects without one can add it from the project menu.

Publishing and the gallery

Choose Publish to gallery… from the project menu. Give the site a title, a description and a category, and optionally pick an image as its cover. Publishing saves the current state as a version and puts it:

• at its own public address, which you can share with anyone, and
• in the gallery, where people can browse it, like it and see it on every screen size.

Visitors see exactly what you published. Keep working in private, then choose Update in gallery… to publish the new version. To take the site down, use Unpublish in the same dialog.

Remix: if you allow it, signed-in visitors can copy your published pages into a new project of their own and change it however they like. Your project is never touched; you just see the remix count go up.

Design system upgrades

Sites are built on htmx-ui, our component library, and each project remembers which version it uses. When a newer version comes out, the project's Settings page shows what upgrading would change. Upgrading happens on a new branch: the files are updated automatically, anything that needs a person is listed (or you can ask the builder to finish it), and you merge when the preview looks right.

Keyboard shortcuts

In the workspace (⌘ on a Mac, Ctrl elsewhere):