---
name: mockup-html
description: "Use before creating or revising HTML fragments for the mockup tool's browser review."
---

# Mockup HTML

Create decision-focused fragments that make the current visual or interaction question cheap to answer.
Prefer one representative state with realistic content over a broad product tour.
State the target platform, viewport, input assumptions, and any intentional fidelity limits in the option description or visible mockup.

## Authoring contract

- Return an HTML fragment, never `<!doctype>`, `<html>`, `<head>`, or `<body>`.
- Supply one to four options with stable IDs.
- One option is enough to review a single design; use multiple options only when comparison helps the decision.
- Preserve the review frame's selection, notes, annotation, iterate, accept, and stop controls; the fragment supplies only the design under review.
- Use realistic labels, data, lengths, empty/error states, and constraints relevant to the decision.
- Rich interactions, scripts, and animations are allowed when they help answer the question.
- Keep fragments concise because mockup execution waits for the complete HTML arguments; avoid frameworks and large boilerplate by default, not useful interaction.
- Prefer self-contained HTML, CSS, assets, and data.
  Do not call external services unless the human approved that dependency.
  The runtime does not claim to sandbox or block fragment network access.
- Preserve semantic controls, labels, keyboard focus, readable contrast, and zoom.
  When animation exists, provide a useful `prefers-reduced-motion: reduce` state.

## Runtime boundary

Each option is rendered in its own open `ShadowRoot`, not an iframe.
Pi previews use a fixed 680 CSS-pixel outer width and a shared content-aware outer height from 304 to 720 CSS pixels; content beyond that bound is visibly reported as cropped.
Scope styles to the fragment and use `:host` for root defaults; document-level selectors such as `html`, `body`, and `:root` do not describe the fragment host.
Do not query the review page globally.
Use classic inline scripts and wrap each script in an IIFE.
The runtime executes revived scripts in the page with a per-script `mockupRoot` reference to their fragment's ShadowRoot.
Capture `document.currentScript.mockupRoot` synchronously before callbacks, then query only within that root.
This avoids relying on `document.currentScript` inside a shadow tree, where it is null.
Scripts are revived after insertion, including scripts added during revisions.

```html
<section class="counter">
  <style>
    :host { color-scheme: light dark; font: 14px/1.4 system-ui, sans-serif; }
    .counter { display: flex; align-items: center; gap: 0.75rem; }
    button:focus-visible { outline: 3px solid currentColor; outline-offset: 2px; }
  </style>
  <button type="button">Increment</button>
  <output aria-live="polite">0</output>
  <script>
    (() => {
      const root = document.currentScript.mockupRoot;
      const button = root.querySelector("button");
      const output = root.querySelector("output");
      button.addEventListener("click", () => {
        output.value = String(Number(output.value) + 1);
      });
    })();
  </script>
</section>
```

## Target fidelity

For other targets, identify actual display, input, and layout constraints first.
HTML is the presentation medium, not permission to invent unsupported behavior.

### Terminal and TUI

Model cells and columns rather than browser pixels.
Use monospace metrics, realistic terminal widths, keyboard navigation, and only colors and glyphs supported by the target terminal.
Do not imply blur, freeform overlap, pointer-only controls, proportional typography, or other effects the terminal cannot render.

### Web

Use responsive layout at representative narrow and wide widths.
Keep semantic HTML, native controls, keyboard operation, and content reflow visible in the fragment.
Do not fake platform behavior that the intended browser cannot provide.

### Mobile

Review at a named narrow viewport and account for touch targets, safe areas, software-keyboard pressure, and one-handed reach where relevant.
Do not rely on hover.
Test long content and compact widths without silently converting the design into a desktop page.

### Desktop

Name the target operating system and representative window size.
Follow its window, menu, dialog, shortcut, focus, keyboard, and pointer conventions.
Show resize behavior when it affects the decision.

## Review loop

Ask one exact visual or interaction question.
On `iterate`, apply the selected option, notes, and annotations without discarding useful behavior or target assumptions, then submit revised fragments.
On `accept`, continue with the accepted direction unless the feedback explicitly requires another review.
Do not ask the human to repeat feedback already captured by the review frame.