--- name: mockup-html description: "Use before creating or revising HTML fragments or multipage flows 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 ``, ``, `
`, or ``. - Each option is one single screen (`html`) or one navigable flow (`pages`, 2 to 12 pages, each `{ id, label?, html }`). - Supply one to four options with stable IDs; page IDs stay stable and unique within their option. - 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. - 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. Previews block fragment network requests, so self-contained fragments also preview reliably. - Preserve semantic controls, labels, keyboard focus, readable contrast, and zoom. When animation exists, provide a useful `prefers-reduced-motion: reduce` state. ## Shorter, semantic HTML - Fragments inherit font, colors, and `color-scheme` from the review frame; write no `:host { color-scheme; font }` boilerplate and add `:host` rules only to change defaults. - Use the frame design tokens directly: `--bg --panel --text --muted --line --soft --accent --bad`. - A `:focus-visible` outline is provided automatically; do not re-add it. - Prefer semantic elements (`header nav main section form table ul dialog`) and native controls over div soup. - One ` ``` ## Flows - Pages render as tabs with ordinal labels ("1 ยท Cart") plus prev/next buttons with arrow, Home, and End keyboard support; all pages are mounted, one visible. - Page scripts query their own page via `document.currentScript.mockupPage`; `mockupRoot.querySelector` would hit page 1 or frame elements. - Cross-page control: `mockupRoot.showPage(id | index | 'next' | 'prev')`; existing page IDs take precedence over direction aliases. `mockupRoot.page` reads the active page id; stash shared data on `mockupRoot` directly. - Listen for `mockup:pagechange` on `mockupRoot`; the event detail carries `{ page, previous }`. - Measure layout only inside `pagechange` handlers because hidden pages have zero geometry. - Element ids must be unique across all pages of one option; scope author selectors because a bare `button {}` also styles the frame's nav. - Frame classes are `mkup`-prefixed; avoid them. - Pins attach per page, and annotations record which page was pinned. ```js mockup({ title: "Checkout flow", question: "Does the three-step flow feel right?", options: [ { id: "flow", label: "Three steps", pages: [ { id: "cart", html: cartHtml }, { id: "address", html: addressHtml }, { id: "payment", html: paymentHtml, // reads mockupRoot.checkout, button calls mockupRoot.showPage("next") }, ], }, ], }); ``` ## Self-review before presenting - Call the mockup tool with `preview: true` to render headless screenshots of every option and page that only you see. - Fix layout and content problems, then repeat the preview if needed. - Present the interactive review only once the previews satisfy you. - Fragments stay self-contained because previews block fragment network requests. ## 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 mockups model cells, monospace metrics, and keyboard navigation, never blur, freeform overlap, or pointer-only controls. Web mockups stay responsive at representative narrow and wide widths. Mobile mockups use a named narrow viewport with touch targets and safe areas, never hover. Desktop mockups name the operating system and window size and follow its conventions. ## 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.