> For the complete documentation index, see [llms.txt](https://docs.nimbalyst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimbalyst.com/visual-editors-powered-by-ai/mockups.md).

# Mockups

Build HTML mockups in Nimbalyst using your docs, code, and sessions as context, then hand the same mockups to your agent to implement.

A mockup is a visual design for a screen, stored as a real HTML file (`.mockup.html`) in your project. Because your agent builds mockups with your docs, code, and sessions as context, and the result is plain HTML and CSS, the same file works for designing a feature and for implementing it. No copy/paste between a design tool and your codebase.

See the [mockups feature page](https://nimbalyst.com/features/mockups/) for how mockups feed back into implementation, and [UI mockups](https://nimbalyst.com/use-cases/ui-mockups/) for a full example.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-2ca4495fef111b14ae972e1b230a21bc7d3e1ea6%2FCreate%20and%20Edit%20Mockups.gif?alt=media" alt=""><figcaption><p>Creating a mockup from the agent chat with the /mockup command, using the open document as context.</p></figcaption></figure>

### Create a Mockup

1. Select **New > New Mockup**, or type `/mockup` in the chat.
2. In the agent chat, describe the mockup you want created.
3. Reference documents with **@**, and paste images or screenshots into the chat for the agent to work from.

### Edit the Mockup

Click a `.mockup.html` file to open it in the mockup editor.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FSPJYNzOb4qnYSrEffLzO%2F2.png?alt=media&amp;token=33b72743-0c51-4ea7-bac9-6f6e1545bc3b" alt=""><figcaption><p>The mockup editor showing a sign-up form mockup with a hand-drawn red annotation circling two fields, drawing tools in the toolbar, and the agent chat on the right.</p></figcaption></figure>

Edit it in three ways:

* Directly in the HTML
* By selecting an element and asking the AI to modify it
* By drawing annotations on the mockup and then asking the AI to make the change you marked

### Multi-Screen Flows

Put multiple mockup screens on a [Project Canvas](/visual-editors-powered-by-ai/canvas.md) to design a complete flow: checkout, onboarding, settings, or anything else that spans more than one screen.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-0043861b4b2fd392b0a03d0f76a641ddb670c597%2FMockup%20Projects%20Canvas.png?alt=media" alt=""><figcaption><p>A mockup project canvas holding four screens connected by labelled arrows, with Add Screen and Auto Layout buttons in the toolbar.</p></figcaption></figure>

On the canvas:

* Drag screens around to arrange them spatially
* Draw connections between screens to show navigation flow, and label them (click, hover, navigate)
* Add existing `.mockup.html` files as live file cards
* Ask the agent to create the screens and arrange them for you
* Click into a card to edit the mockup in place

Project boards are stored as `.canvas` files. Older `.mockupproject` files open in a compatibility view that can convert them to the current Canvas format.

### Insert a Mockup into a Markdown Document

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2F3UWY1k5rh9Vo7t3k9XgN%2FInsert%20mockup%20into%20a%20document%20(1).gif?alt=media&amp;token=401af74d-34c8-433a-ac60-6d56fa65645e" alt=""><figcaption><p>A markdown document with a mockup embedded inline, edited alongside the agent chat.</p></figcaption></figure>

Type **/** in a document and insert a mockup. Click the embedded mockup to edit it in place.

### File Type and Storage

Mockups are `.mockup.html` files. By default new mockups are saved under `nimbalyst-local/mockups/` in your project, but you can keep them anywhere.

## Working with the AI

### Tips for Better Results

* **Be specific about layout**: "Two-column layout with 30% sidebar" beats "add a sidebar"
* **Reference known products**: "Style it like the Stripe dashboard" gives the AI a clear design reference
* **Describe interactions**: "When hovering over a row, show a blue highlight and a delete icon on the right"
* **Iterate in small steps**: make one change at a time so you can evaluate each iteration

### What the AI Sees

When you ask the AI to edit a mockup, it:

1. Captures a screenshot of the current rendered mockup
2. Reads the HTML source code
3. Sees any annotations you've drawn
4. Understands which element you've selected (if any)

This multi-modal context means you can say "make the thing I circled bigger" and the AI knows what you mean.

### Design-to-Code Workflow

Mockups are real HTML and CSS, which makes them a useful bridge between design and implementation:

1. **Design in mockups**: iterate on the visual design with AI assistance
2. **Review with stakeholders**: share the rendered mockup for feedback
3. **Extract patterns**: use the mockup's HTML/CSS as a reference when implementing the production UI
4. **Maintain alongside code**: keep mockups updated as the product evolves

## File Format

Mockups use standard HTML with inline CSS. No build tools or frameworks required.

```html
<div style="font-family: system-ui, sans-serif; max-width: 800px; margin: 0 auto;">
  <header style="padding: 16px; border-bottom: 1px solid var(--nim-border);">
    <h1 style="color: var(--nim-text);">Settings</h1>
  </header>
  <main style="display: flex; gap: 24px; padding: 24px;">
    <nav style="width: 200px;">
      <!-- Sidebar content -->
    </nav>
    <section style="flex: 1;">
      <!-- Main content -->
    </section>
  </main>
</div>
```

Using `var(--nim-*)` CSS variables ensures your mockup adapts to light and dark themes automatically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nimbalyst.com/visual-editors-powered-by-ai/mockups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.