Design a screen before building it
4 minute read · Chats & Local Agents
Sketch a page as a static design, look at it beside the chat and refine it before any app code changes. Use /design with Claude Code, or let any connected agent offer a design when a new screen or larger visual change needs one.
- Start a design with Claude Code
- Read the canvas
- Where designs are saved
- Let agents offer designs
- Keep design and build separate
Start a design with Claude Code
- Open a chat in a local project and choose Claude Code.
- Type /design, or choose Design from the commands. A Design chip appears above the message box with the hint Result opens on the canvas.
- Describe the screen: “A sign-up page for Small Stories with a short form, a testimonial and a dark header.”
- Send. Claude writes the design and the Design canvas opens beside the chat when the file is saved.
Send more messages to refine the same design. By default the chat continues its most recent design file in that project. Select the chip to show the canvas again, and Exit design to return to ordinary messages.
Design mode needs a local project folder in the chat. Without one, Vortex asks you to choose it before sending. It is not available in a message that starts with an @project mention. The @design work step is different: it guides the current agent's next answer and does not open the canvas.
Read the canvas
| Control | What it does |
|---|---|
| Design file | Switches between the designs in this chat, shown as Design 1, Design 2 and so on. Designs saved in another project of the same workspace open from that project and show its name, so you do not need to switch projects. |
| Fit / Mobile / Desktop | Shows the design scaled to the panel, at 390 px or at 1280 px wide. |
| Refresh design | Reloads the saved file. While the agent is working, the visible canvas refreshes every few seconds. |
| Open design source | Opens the HTML file in the editor. |
| Saved time | The time of the last saved version. |
The footer says Static preview · scripts and external resources are not run. The canvas removes scripts, frames, links and event handlers and blocks network access, so buttons and links do not navigate. Use it to judge layout, colour, type and content, then ask the agent to build the real page and check it in Preview.
Where designs are saved
Each design is one self-contained HTML file in the project, at designs/vortex-<name>.html, below 2 MiB. Styles and images are inline. The agent is asked to leave the app's source unchanged while designing.
Design files are ordinary project files. They follow the chat's access mode, appear in Files and Source Control, and are committed if you include them. Add designs/ to .gitignore or delete the files when you do not want to keep them.
Let agents offer designs
Open Settings → General → Conversations → Agent designs:
| Choice | Behaviour |
|---|---|
| Off | Agents are not offered the design tool. |
| Ask | When a new screen or larger visual change would benefit, the agent asks in one sentence whether to make a design first and waits for your answer. |
| Auto | The agent decides when a design helps. It skips small fixes, copy changes, backend work and refactors. This is the default. |
When an agent saves a design, a card with a thumbnail, the title, HTML design · saved time and Open canvas appears in the chat. The canvas opens only when you select the card or ask the agent to show the design. The setting applies to local agents connected to Vortex tools in a chat with a project folder. It does not apply to SSH-hosted runs or generation models.
Keep design and build separate
A design is a reference, not a working feature. After you agree on it, ask for the implementation in a normal message: “Build this sign-up page in the app, using the saved design.” The agent should save a revised design after each complete change, then implement. Review the result in Preview and the diff in Files and Source Control.
In Plan, agents are instructed not to write files, so ask for a design after switching to Build. See access modes.