1---
2title: Iterate on UI with Live Mode
3tagline: "Pick an element, generate three variants, accept one. Canvas-like iteration without leaving your code."
4order: 2
5description: "Use /impeccable live to visually iterate on a real element in your dev server: pick, annotate, generate three variants, accept the one you want, and have it written back to source."
6---
7
8## What you'll build
9
10You will use `/impeccable live` on your dev server to iterate on a single piece of UI (a hero, a card, a section) and end with one of three AI-generated variants written back to source as real code. You'll see the canvas-style picking, annotation, and three-up cycling flow.
11
12Total time: about ten minutes. Most of that is picking what to iterate on.
13
14## Prerequisites
15
16- Impeccable installed (see [getting started](/tutorials/getting-started) if you have not). Run `/impeccable teach` first if you haven't yet: variants lean on `PRODUCT.md` and `DESIGN.md` for brand fit.
17- A running dev server with HMR (Vite, Next.js, SvelteKit, Astro, Nuxt, Bun) OR a static HTML file open in a browser.
18- A page with at least one piece of UI you'd like to iterate on. A newsletter card, a hero, a pricing tier, something small enough to hold in your head.
19
20## Step 1. Start live mode
21
22From your harness, run:
23
24```
25/impeccable live
26```
27
28The skill starts a small local helper server on port 8400 and injects a `<script>` tag into your dev entry file that loads the picker. If your project has a strict Content Security Policy, the first run detects it and offers a one-time, dev-only patch for `script-src` and `connect-src`. Accept the patch: it is guarded by `NODE_ENV === "development"` and you can revert any time.
29
30Open your dev server URL (not port 8400, that's the helper server, not the app). You'll see a dark pill at the bottom of the page with **Pick** highlighted.
31
32## Step 2. Pick an element
33
34<div class="docs-viz-step">
35 <div class="docs-viz-picker-row">
36 <div class="docs-viz-picker-target">
37 <span class="docs-viz-picker-pin">1</span>
38 Newsletter signup
39 <span class="docs-viz-picker-note">more playful</span>
40 </div>
41 </div>
42</div>
43
44Click the element you want to iterate on. A picker outline appears around it, and a light context bar pops up next to the selection with a command chip on the left and a freeform text field.
45
46A few things you can do before pressing Go:
47
48- **Click the command chip** (default is `impeccable`, the freeform action). Pick a specific action like `bolder`, `delight`, `layout`, or `typeset` to constrain the variants along one dimension.
49- **Type in the freeform field.** "More playful." "Less SaaS." "Feel like a newsletter from a magazine."
50- **Drop a comment pin** by clicking anywhere on the picked element. The pin's position matters: a comment near the title is about the title, not the whole element.
51- **Draw a stroke** by dragging across the element. Closed loop = "this part matters." Arrow = direction. Cross = "delete this." The skill reads strokes by shape, not by pixel content.
52
53When the brief feels clear, hit **Go**.
54
55## Step 3. Cycle through the three variants
56
57<div class="docs-viz-step">
58 <div class="docs-viz-variants">
59 <div class="docs-viz-variant docs-viz-variant--v1">
60 <span class="docs-viz-variant-badge">1 / 3</span>
61 <span class="docs-viz-variant-kicker">No. 04</span>
62 <p class="docs-viz-variant-title">Letters, <em>occasionally</em>.</p>
63 <span class="docs-viz-variant-btn">Send me one</span>
64 </div>
65 <div class="docs-viz-variant docs-viz-variant--v2 is-active">
66 <span class="docs-viz-variant-badge">2 / 3</span>
67 <span class="docs-viz-variant-kicker">Dispatch</span>
68 <p class="docs-viz-variant-title">Design notes, <br>every other<br>Thursday.</p>
69 <span class="docs-viz-variant-btn">Join →</span>
70 </div>
71 <div class="docs-viz-variant docs-viz-variant--v3">
72 <span class="docs-viz-variant-badge">3 / 3</span>
73 <span class="docs-viz-variant-kicker">Field Notes</span>
74 <p class="docs-viz-variant-title">A monthly letter, for people who still read email.</p>
75 <span class="docs-viz-variant-btn">Receive ✺</span>
76 </div>
77 </div>
78</div>
79
80You'll see a spinner ("Generating variants...") and within a few seconds, three variants hot-swap into the page in place. Not a preview, the actual rendered DOM on your actual dev server with your actual context.
81
82Use the arrow keys (or the prev / next buttons on the context bar) to cycle through them. A counter at the top right shows `1 / 3`, `2 / 3`, `3 / 3`.
83
84The three variants are designed to be **genuinely different**, not three riffs on one idea. Freeform variants anchor to three different design archetypes (broadsheet masthead, oversized-glyph poster, catalog-style spec rows, and so on). Action-specific variants vary along the dimension the action names: `colorize` gives you three hue families, `animate` gives you three motion vocabularies, `layout` gives you three structural arrangements.
85
86If two variants feel like they rhyme, that is the skill's "squint test" failure mode. You can tell the picker "try again, all three felt too similar" and get a fresh set.
87
88## Step 4. Accept one
89
90<div class="docs-viz-step" style="text-align:center">
91 <span class="docs-viz-accept-pill">Variant 2 written to source</span>
92</div>
93
94When you find the one you like, click **Accept** on the context bar (or press Enter). Three things happen:
95
961. The picked element is replaced with the accepted variant on the page.
972. The variant is written back to source: the same file your picker was injected into, or the component source if live detected a generated file during step 1.
983. If the accept touched CSS, the relevant rules are consolidated into your project's real stylesheet, not left inline.
99
100Discard all three (press Escape) and the original stays. No trace, no commented-out leftovers.
101
102## Step 5. Stop live mode
103
104When you are done iterating, stop the helper:
105
106- Say **"stop live mode"** in your harness chat, or
107- Click the **×** on the picker pill, or
108- Close the browser tab: the helper detects the dropped connection after eight seconds and exits cleanly.
109
110The stop also strips the `<script>` tag from your dev entry and stops the helper server on port 8400.
111
112## What to try next
113
114- Run `/impeccable live` on a different page after a `/impeccable polish` pass to A/B the polished version against two more directions.
115- Pair with [critique with the overlay](/tutorials/critique-with-overlay): run critique first, fix priority issues, then use live to explore redirections on the element critique flagged.
116- Reach for `/impeccable craft` when you want the shape-then-build flow (a new feature end-to-end, not a single element).
117
118## Common issues
119
120- **The picker never appears on the page.** Either the helper did not start (look for errors in the terminal) or CSP is blocking the inject. Re-run `/impeccable live` and let it re-check CSP. If you declined the patch on first run, delete the `cspChecked` line in `.impeccable/live/config.json` and re-run.
121- **"element lives in a generated file"** on Go. Live detected that the picked element is in a compiled output, not a source file. It routes the accept through a fallback path so the variant still lands in true source. Follow the hint; don't force-accept into the generated file.
122- **Variants don't feel brand-aligned.** Check that `PRODUCT.md` and `DESIGN.md` exist at the project root. Without them, live leans toward generic defaults. Run `/impeccable teach` and `/impeccable document` first.
123- **The helper port is in use.** Another live session left its server running. `npx impeccable live stop` releases the port.