3 +description: "Use before creating or revising HTML fragments for the mockup tool's browser review."
8 +Create decision-focused fragments that make the current visual or interaction question cheap to answer.
9 +Prefer one representative state with realistic content over a broad product tour.
10 +State the target platform, viewport, input assumptions, and any intentional fidelity limits in the option description or visible mockup.
12 +##
Authoring contract 14 +- Return an HTML fragment, never `<!doctype>`, `<html>`, `<head>`, or `<body>`.
15 +- Supply one to four options with stable IDs.
16 +- One option is enough to review a single design; use multiple options only when comparison helps the decision.
17 +- Preserve the review frame's selection, notes, annotation, iterate, accept, and stop controls; the fragment supplies only the design under review.
18 +- Use realistic labels, data, lengths, empty/error states, and constraints relevant to the decision.
19 +- Rich interactions, scripts, and animations are allowed when they help answer the question.
20 +- Avoid frameworks and large boilerplate by default, not useful interaction.
21 +- Prefer self-contained HTML, CSS, assets, and data.
22 + Do not call external services unless the human approved that dependency.
23 + The runtime does not claim to sandbox or block fragment network access.
24 +- Preserve semantic controls, labels, keyboard focus, readable contrast, and zoom.
25 + When animation exists, provide a useful `prefers-reduced-motion: reduce` state.
29 +Each option is rendered in its own open `ShadowRoot`, not an iframe.
30 +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.
31 +Do not query the review page globally.
32 +Use classic inline scripts and wrap each script in an IIFE.
33 +The runtime executes revived scripts in the page with a per-script `mockupRoot` reference to their fragment's ShadowRoot.
34 +Capture `document.currentScript.mockupRoot` synchronously before callbacks, then query only within that root.
35 +This avoids relying on `document.currentScript` inside a shadow tree, where it is null.
36 +Scripts are revived after insertion, including scripts added during revisions.
39 +<section class="counter">
41 + :host { color-scheme: light dark; font: 14px/1.4 system-ui, sans-serif; }
42 + .counter { display: flex; align-items: center; gap: 0.75rem; }
43 + button:focus-visible { outline: 3px solid currentColor; outline-offset: 2px; }
45 + <button type="button">Increment</button>
46 + <output aria-live="polite">0</output>
49 + const root = document.currentScript.mockupRoot;
50 + const button = root.querySelector("button");
51 + const output = root.querySelector("output");
52 + button.addEventListener("click", () => {
53 + output.value = String(Number(output.value) + 1);
62 +For other targets, identify actual display, input, and layout constraints first.
63 +HTML is the presentation medium, not permission to invent unsupported behavior.
67 +Model cells and columns rather than browser pixels.
68 +Use monospace metrics, realistic terminal widths, keyboard navigation, and only colors and glyphs supported by the target terminal.
69 +Do not imply blur, freeform overlap, pointer-only controls, proportional typography, or other effects the terminal cannot render.
73 +Use responsive layout at representative narrow and wide widths.
74 +Keep semantic HTML, native controls, keyboard operation, and content reflow visible in the fragment.
75 +Do not fake platform behavior that the intended browser cannot provide.
79 +Review at a named narrow viewport and account for touch targets, safe areas, software-keyboard pressure, and one-handed reach where relevant.
80 +Do not rely on hover.
81 +Test long content and compact widths without silently converting the design into a desktop page.
85 +Name the target operating system and representative window size.
86 +Follow its window, menu, dialog, shortcut, focus, keyboard, and pointer conventions.
87 +Show resize behavior when it affects the decision.
91 +Ask one exact visual or interaction question.
92 +On `iterate`, apply the selected option, notes, and annotations without discarding useful behavior or target assumptions, then submit revised fragments.
93 +On `accept`, continue with the accepted direction unless the feedback explicitly requires another review.
94 +Do not ask the human to repeat feedback already captured by the review frame.