Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/mockup/guidance/mockup-html/SKILL.md

Raw
Rendered preview

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 <!doctype>, <html>, <head>, or <body>.
  • 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 <style> per option covers all its pages; scripts are IIFEs capturing mockupRoot.

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 capture at most eight option/page screenshots per call. 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; in a flow, document.currentScript.mockupPage refers to the script's own page. 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.

<section class="counter">
  <style>
    .counter { display: flex; align-items: center; gap: 0.75rem; }
  </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>

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.
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.

---
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 `<!doctype>`, `<html>`, `<head>`, or `<body>`.
- 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 `<style>` per option covers all its pages; scripts are IIFEs capturing `mockupRoot`.

## 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 capture at most eight option/page screenshots per call.
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; in a flow, `document.currentScript.mockupPage` refers to the script's own page.
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>
    .counter { display: flex; align-items: center; gap: 0.75rem; }
  </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>
```

## 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.