UI preview

Apply the common work contract within this task’s scope. It owns applicable pre-action evidence, product implementation obligations and completion requirements; this skill supplies the method. Current common guidance already delivered or read may be reused.

Run this skill for requests to design or change visible UI or user interactions, including the preview shell or generator itself, even without an explicit preview command. Show a rendered, interactive proposal before implementing the UI change; a code diff or prose description alone is insufficient. Feature and spec are not prerequisites. A preview does not require a saved spec or a new approval of settled requirements.

The main session creates the disposable prototype and checks, captures and compares previews directly. Use preview on its own or within a task playbook. A standalone prototype request ends with the checked proposal; product implementation proceeds on the user's authorization under the common product-change obligations, using appropriate implementation methods.

The goal is speed: the user sees and touches the idea before anyone writes product code. Preview code is disposable.

Read ui-design before designing the preview, and apply its Do and Check guidance when building and inspecting the rendered result.

Steps

1. Identify the behavior. Read the user's request, supplied references and the relevant screen in the application. Identify the screens, states and interactions the preview must show, and what the variants differ in. Decide whether the subject is a whole screen or a component before choosing its dimensions. Present connected elements together in one interactive preview. Let the user start an interaction on the requested component, follow its state transitions and inspect the immediate visible result, including dismissal or return when applicable. For example, hover a row, move into its menu, select an item and see the result on the row. Parent components and surrounding screens supply only the context needed to understand and operate that behavior; do not expand into their unrelated behavior or redesign. Simulate external effects such as server writes with sample data. Separate state views may supplement the connected flow, but must not replace it.
2. Pick the medium. Name the medium in one line and proceed; ask only when the user's words point both ways.
   • Throwaway prototype (default). One self-contained HTML file with a lightweight comparison shell, outside the repository, with fake data. Serve its directory with a local static server and open it at http://localhost:<port>/<task>.html. Use it for layout, animation and interaction choices.
   • Illustrative widget. A static or lightly interactive picture rendered inline. Use it when the user asks for one or a still image answers the question. Do not pick it to save effort when motion or interaction is the point.
   • Running application. Use it only when the user asks, or when the choice depends on real data, state or integration that fake data cannot stand in for. Say which dependency made you switch.

3. Build it fast. For a throwaway prototype:

   • Create the file with node <tools>/preview-scaffold.mjs --out <dir>/<task>.html --title "<title>" --variants "A,B" --states "Empty,Loaded". Use the session's scratch or temp directory; use <notesDir>/previews/ only when the user wants to keep it. The tool refuses paths inside a git work tree. The tools folder is two levels above this skill; resolve notesDir from ~/.haechi/user.json.
   • The file has a top bar with variant and state switchers, a side-by-side toggle and a short "Sample data" disclosure. Start with fake data per state in STATES, one render(data, root) per variant in VARIANTS, and the prototype style block. The shell is a starting point, not a visual standard: adapt its markup, styles and layout to the request. Preserve working variant/state selection, comparison, and the fake-data disclosure when changing the shell; update selectors and handlers together if its structure changes.
   • For a few variant/state controls and a comparison toggle, use a compact header and leave the canvas available to the subject. Use a sidebar only when the controls need enough hierarchy or space to justify it, or when requested.
   • Use one set of controls: when moving navigation into a sidebar or another layout, remove the original controls instead of duplicating them. Open directly into the preview; do not add a landing page, gallery or separate entry screen unless requested. Use English for preview-shell labels and guidance. Use compact pill-shaped badge buttons in a black-and-white shell: light gray at rest, black with white text when selected, no persistent borders, and a visible keyboard-focus indicator. Keep any product-specific colors confined to the previewed subject when the brief requires them. Keep visible copy to the task title, useful action/state labels and a short sample-data disclosure; omit scaffold branding, variant counts and disposable-prototype explanations. Use Pretendard consistently for the shell, controls and sample content; the scaffold embeds the font for offline use.
   • Match the preview size to its subject. Tooltips, popovers, menus, buttons and small dialogs keep realistic intrinsic or reference dimensions and appear with just enough surrounding context (such as their trigger) to explain placement. Do not stretch them to fill a comparison cell or add a minimum height to fill the canvas. Pages, dashboards and full-screen flows use the intended viewport width and height. Keep component dimensions consistent across single and side-by-side views; reflow or scroll the comparison layout rather than scaling up the component. The generated variant root defaults to intrinsic width; explicitly set its width to 100% for a whole-screen preview.
   • Choose the visual direction from the user’s brief and application references. Do not carry the shell’s typography, colors or framing into the product UI by default, or reproduce an unrelated design system unless requested. When alternatives concern visual direction, vary hierarchy, composition, density or typography meaningfully; for a narrow behavior comparison, keep the surrounding design consistent.
   • Spend no time on architecture, tests, error handling or repository conventions. Plain DOM and CSS are enough; copy markup, colors or tokens from the application when that gets closer to the real look faster.
   • Use synthetic fake data, just enough to show the states. No real records.
   • Start a local static server for the directory containing the generated HTML, using a free port and respecting devServer.forbiddenPorts. Open its http://localhost:<port>/<task>.html URL in a browser and check that every variant renders in every state. Exercise each relevant connected flow from trigger through transitions to its immediate result, rather than checking only isolated states. Share the verified localhost URL with the user only after that check.

   For a running-application preview, start its development server, check the requested state in a real render, and provide only URLs whose content you checked. Separate variants there may need separate worktrees: record the source branch used for each variant, run configured setup, use free ports and avoid devServer.forbiddenPorts.

   Changes to application source follow the common work contract's tests, rendered design comparison and code review, including component reuse checks. This applies when the request is called a preview too; the throwaway-prototype shortcuts apply to the disposable HTML file.

   If execution, browser access or URL exposure is unavailable, report the limitation and the alternatives; never present a prototype or widget as the real app.

4. Compare. One variant is fine unless the user asked for several. For several variants, open in side-by-side comparison by default and let the user select a variant to inspect it alone. Say what each one changes against the stated criteria; the prototype's side-by-side toggle shows them together. For running-application variants, open each variant's checked URL and inspect the same screens and states directly.
5. Carry over the direction, not the code. Record which variant was chosen and what about it matters (layout, timing, interaction). Retain screenshots of the selected screens and the relevant interaction criteria so they remain usable after prototype cleanup. Reuse that reference when implementation is requested; repeat preview work only for requirements or states the existing reference does not cover. Product implementation follows the common work contract and repository conventions. Copying prototype code into the application is a separate decision; state it when you make it.
6. Clean up. Keep preview servers, including the prototype's static server, up while the user reviews, then stop the servers you started and delete the prototype file unless the user wants to keep it. Before removing variant worktrees, run node <tools>/cleanup-merged.mjs <variant branch> --base <source branch> --discard to show the removal list. Resolve a missing source branch from the task context or repository settings before proceeding. Keep the same --base when adding --yes, and do so only when deletion is authorized. Never use git worktree remove --force by hand.

Evidence

Report the medium, where the preview lives (including the localhost URL and file path for a throwaway prototype), the states and interactions you checked in a browser, and checks you could not run. A running process or open port alone does not prove the preview works.