ui-mockup-variants

name	ui-mockup-variants
description	Before implementing any user-facing UI/visual change, proactively offer design mockup variants for the user to pick from — via a single multiple-choice prompt. Use whenever a task asks to add, change, redesign, restyle, or improve any UI element (panel, button, badge, layout, dashboard, indicator, color, spacing, look-and-feel). Ask once (do mockups? how many? what fidelity?), build a self-contained HTML gallery from the app's REAL CSS tokens, let the user choose a variant, then implement it. Don't jump straight to component code.
keywords	ui change, ui improvement, ui modification, redesign, restyle, mockup, mockups, design variant, design variants, design exploration, visual change, look and feel, layout, panel, button, badge, icon, dashboard, indicator, animation, css, styling, frontend, ux, choose a design, which design, show me variants, pick a design
related	playwright-e2e-patterns, rfc-iterative-review, requirements-engineering

UI Mockup Variants — design exploration before implementation

When a task involves a user-facing UI/visual change, do NOT skip straight to editing components. First offer the user a quick design-exploration round so they pick the look from real, viewable variants. This skill makes that the default — the user shouldn't have to ask for mockups; you propose them.

When to use (and when to skip)

Use it for any task that adds, changes, redesigns, restyles, or improves something the user sees: a new indicator/animation, a panel layout, a button treatment, badges, spacing, a dashboard section, color/theme work, "make X look better / clearer / nicer".

Offer briefly but lean toward skipping when the change is unambiguous and has no real design space: a copy/text fix, a one-line color token swap a designer already specified, reverting to a known prior look, or the user explicitly says "just implement it, no mockups". Even then, a one-line "I'll just implement this directly — want variants instead?" is cheap insurance.

If you're unsure whether the work is "UI enough", it is. Offer.

Step 1 — Offer the menu (one AskUserQuestion call)

Ask all of this in a single AskUserQuestion call (it supports multiple questions) so the user answers once and you proceed. Pre-select the recommended defaults so a fast user can accept everything in a couple of clicks:

1. Explore mockups first? — Yes — show me variants to pick (Recommended) / No — just implement your best version.
2. How many variants? — 4–5 (Recommended) / 3 / 2 / 1 (your best).
3. Fidelity? —
   • HTML gallery (Recommended) — a standalone HTML file reusing the app's real CSS, openable in a browser. Fast, no dev server required.
   • Rendered screenshots of the real app — launch the app and capture each variant against the live UI. Highest fidelity, slower, needs the server up.
   • Quick ASCII sketches — inline text layout sketches only. Fastest, lowest fidelity; good for coarse layout decisions or when no styling exists yet.

If the user picks No on Q1, implement directly (still consider a before/after visual check at the end — see Step 5).

Step 2 — Ground the mockups in the real UI

The whole point is that variants look like this app, not generic HTML. Before building anything:

• Locate the real component(s) the change touches (search the frontend for the feature's markup/classes).
• Read the app's actual design tokens — the stylesheet(s) and the real class names, colors, fonts, spacing, radii, and dark/light theme variables. Reuse them verbatim in the mockups. Copy the real DOM structure/class names so a variant is a faithful preview, not an approximation.
• Note any real data shapes the UI renders (states, counts, labels) so the mockups show realistic content, not lorem ipsum.

Step 3 — Build the variants

HTML gallery (default)

Write one self-contained HTML file at the repo root, e.g. <feature>-mockups.html. Inside it:

• Inline the app's real CSS tokens (or <link>/@import the real stylesheet if practical) and match the app's background/theme so cards look in-context.
• Render each variant in its own labeled card, laid out side by side or stacked, using the real class names and realistic content.
• Give each variant a short name and a one-line characterization (e.g. "most informative", "most minimal", "closest to current").

This file is a throwaway preview artifact — leave it untracked; do not commit it. Serve it, don't just hand back a file:// path. Start a lightweight local static server at the repo root (e.g. python3 -m http.server <port>, or the project's dev server) and give the user a http://localhost:<port>/<feature>-mockups.html URL — because the browser often runs on a different host than the repo (WSL2, SSH, containers, remote dev), where a file:// path to a repo-local file simply won't open. Fall back to a file:// path only when a server genuinely isn't practical, and say so. Either way, also report the file's absolute path.

Rendered screenshots (if chosen)

Launch the app the way the project documents (its run/dev workflow or the dev script in package.json), then drive a headless browser (Playwright) to screenshot each variant — either the gallery cards or, better, the variant applied behind a flag. For small elements (< ~100px), zoom the page (document.body.style.zoom) and take a clipped screenshot so pixel-level differences are actually visible; a 36px icon in a full-viewport shot is too small to judge. Read each PNG back inline so the user sees them in chat. Be honest about non-deterministic states you can't reliably capture (e.g. an agent caught mid-action) — substitute a faithful static preview rather than claiming a live shot you didn't take.

ASCII sketches (if chosen)

Inline labeled text sketches of each layout, one per variant, with the same short-name + characterization treatment.

Step 4 — Present and let the user pick

Regardless of fidelity, also give an inline numbered list in chat: each variant on one line — N. <name> — <one-line characterization> — plus the artifact path / images. Then make the choice a clean multiple-choice with a final AskUserQuestion (header Variant, single-select). Offer the obvious combinations as options too when they make sense (e.g. "2 + 3 combined") — users often want the best of two. Let them pick before you write component code.

Step 5 — Implement the chosen variant

Once chosen:

• Create a worktree/branch for the change (per the project's contribution rules).
• Implement the picked variant into the real component(s) — not the mockup file. Reuse the exact tokens/markup you previewed.
• Add or update tests for the new UI behavior.
• Run the project's pre-PR review / quality gate.
• Visually verify the real result before reporting done: screenshot the before/after in the running app, zooming/clipping small elements. Only declare it done when the rendered result matches the chosen mockup. Leave the user a working inspection path (running URL or artifact path), don't tear it down.

Delete or leave-untracked the throwaway *-mockups.html preview; it isn't part of the change.

Worked example (Kookr activity-panel "working" indicator → PR #717)

The reference run for this skill:

1. Request: "suggest 4 or 5 mockup variants in html format that I can visualize" for an indicator showing the agent is actively working in the activity panel.
2. An agent located ActivityPanel.tsx; the real dark-theme tokens and .activity-panel / .act-msg-* classes were read from the stylesheet.
3. One file activity-working-indicator-mockups.html rendered 5 variants (typing bubble, live tool row, sticky working bar, footer status strip, frontier glow) using the real tokens — opened via file://.
4. Presented inline as a numbered list, each tagged ("most informative", "minimal"); AskUserQuestion (header Variant) offered four build candidates including a "3 + 2 combined" option. User picked "live tool row".
5. Implemented into the real ActivityPanel.tsx in a worktree, added tests, ran reviewer specialists, visually checked, opened the PR.

The improvement this skill encodes: the user had to ask for the mockups and the count. Now you offer the menu first, so they just answer multiple choice and you build.