diff --git a/.agents/skills/impeccable/SKILL.md b/.agents/skills/impeccable/SKILL.md index eb0ba0589..b9e85282a 100644 --- a/.agents/skills/impeccable/SKILL.md +++ b/.agents/skills/impeccable/SKILL.md @@ -1,6 +1,6 @@ --- name: impeccable -description: "Design fluency for frontend interfaces. Build distinctive, production-grade web components, pages, artifacts, posters, and applications with high design quality. Also handles: critique/review/evaluate designs, audit accessibility/performance/responsive, polish finishing touches, improve typography/fonts/readability, fix layout/spacing/hierarchy, add animation/transitions/motion, adapt for mobile/tablet/responsive, simplify/declutter/distill, amplify bland/generic/safe designs, tone down loud/overwhelming designs, add color to gray/monochromatic interfaces, improve UX copy/labels/error messages, harden for production with edge cases/i18n/errors, design onboarding/first-run/empty states/activation flows, optimize slow/laggy performance, plan UX before coding, extract design tokens, or push boundaries with shaders/physics/scroll effects. Commands: craft, teach, extract, pin, audit, critique, polish, shape, adapt, animate, bolder, quieter, colorize, clarify, delight, distill, harden, onboard, layout, optimize, overdrive, typeset." +description: "Design fluency for frontend interfaces. Build distinctive, production-grade web components, pages, artifacts, posters, and applications with high design quality. Also handles: critique/review/evaluate designs, audit accessibility/performance/responsive, polish finishing touches, improve typography/fonts/readability, fix layout/spacing/hierarchy, add animation/transitions/motion, adapt for mobile/tablet/responsive, simplify/declutter/distill, amplify bland/generic/safe designs, tone down loud/overwhelming designs, add color to gray/monochromatic interfaces, improve UX copy/labels/error messages, harden for production with edge cases/i18n/errors, design onboarding/first-run/empty states/activation flows, optimize slow/laggy performance, plan UX before coding, extract design tokens, push boundaries with shaders/physics/scroll effects, or visually iterate on elements in the browser with live variant mode. Commands: craft, teach, extract, live, pin, audit, critique, polish, shape, adapt, animate, bolder, quieter, colorize, clarify, delight, distill, harden, onboard, layout, optimize, overdrive, typeset." version: 3.0.0 user-invocable: true argument-hint: "[command] [target]" @@ -329,6 +329,9 @@ This skill supports sub-commands. Parse the first word of the argument string to > `/impeccable adapt [target]` - Adapt for different devices and screen sizes > `/impeccable optimize [target]` - Diagnose and fix UI performance > +> **Iterate** +> `/impeccable live` - Visual variant mode: pick elements in the browser, generate alternatives +> > **Manage** > `/impeccable pin ` - Create a standalone shortcut (e.g., pin audit creates /audit) > `/impeccable unpin ` - Remove a pinned shortcut @@ -362,6 +365,7 @@ When a sub-command is matched, load the linked reference and follow its instruct | `clarify` | [clarify](reference/clarify.md) | Improve UX copy, labels, error messages, and microcopy | | `adapt` | [adapt](reference/adapt.md) | Adapt designs across screen sizes, devices, and platforms | | `optimize` | [optimize](reference/optimize.md) | Diagnose and fix UI performance issues | +| `live` | [live](reference/live.md) | Interactive visual variant mode: pick elements, generate alternatives in the browser | --- diff --git a/.agents/skills/impeccable/reference/live.md b/.agents/skills/impeccable/reference/live.md new file mode 100644 index 000000000..30b5076ca --- /dev/null +++ b/.agents/skills/impeccable/reference/live.md @@ -0,0 +1,198 @@ +Launch interactive live variant mode: select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via the dev server's HMR. + +## Prerequisites + +- A running development server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser +- The impeccable CLI installed (`npm i -g impeccable`) + +## Start the Server + +1. Read `.impeccable.md` if it exists. Keep the design context in mind for variant generation. +2. Start the live variant server: + ```bash + npx impeccable live & + ``` +3. Note the **port** and **token** printed to stdout. + +## Inject the Browser Script + +Find the project's main HTML entry point. This varies by framework: + +| Framework | Typical file | +|-----------|-------------| +| Plain HTML | `index.html` | +| Vite / React | `index.html` (project root) | +| Next.js (App Router) | `app/layout.tsx` (add a ` + +``` + +**JSX / TSX (React, Next.js):** +```jsx +{/* impeccable-live-start */} + +{/* impeccable-live-end */} +``` + +Place it before the closing `` or at the end of the layout component. Save the file. The dev server will reload and the element picker will activate. + +If browser automation tools are available, also navigate to the page so the user can see it. + +## Enter the Poll Loop + +Run a blocking poll loop. On each iteration, wait for a browser event and respond: + +``` +LOOP: + Run: npx impeccable poll + Read the JSON output. Dispatch based on the "type" field: + + TYPE "generate": + → See "Handle Generate" below + + TYPE "accept": + → See "Handle Accept" below + + TYPE "discard": + → See "Handle Discard" below + + TYPE "exit": + → Break the loop + + TYPE "timeout": + → Continue (re-poll) + +END LOOP +``` + +## Handle Generate + +The event contains: `{id, action, freeformPrompt, count, element}`. + +### Step 1: Find the source file + +Use `element.tagName`, `element.id`, `element.classes`, `element.textContent`, and `element.outerHTML` to locate the element in the project source. Search for matching markup across the codebase. + +### Step 2: Create the variant wrapper + +Wrap the original element in a variant container. Use the comment syntax appropriate for the framework: + +**HTML / Vue / Svelte:** +```html + +
+
+ +
+
+ +``` + +**JSX / TSX:** +```jsx +{/* impeccable-variants-start SESSION_ID */} +
+
+ {/* move the original element here */} +
+
+{/* impeccable-variants-end SESSION_ID */} +``` + +Replace SESSION_ID with `event.id` and COUNT with `event.count`. + +`display: contents` makes the wrapper layout-transparent, preserving the original element's relationship with its parent (flex/grid child, etc.). + +### Step 3: Generate variants one by one + +For each variant (1 through COUNT): + +1. **Load the design command's reference file.** If `event.action` is "bolder", load `reference/bolder.md`. If "impeccable" (the default), use the main design principles from this skill without loading a sub-command reference. + +2. **Generate a complete replacement** for the original element. Each variant is a full HTML+CSS rewrite, not a patch. Consider the element's context (computed styles, parent structure, CSS custom properties from `event.element`). + +3. **Diversify across variants.** Each variant should take a distinctly different approach. For "bolder", one might focus on type weight, another on color saturation, another on spatial scale, another on structural change. Do NOT generate 4 variations on the same idea. + +4. **If a freeform prompt was provided** (`event.freeformPrompt`), use it as additional guidance for all variants. + +5. **Write the variant** into the wrapper in the source file: + ```html +
+ +
+ ``` + The first variant should NOT have `style="display: none"` (it should be visible by default). + +6. **Write scoped CSS** if the variant needs styles beyond inline: + ```css + /* impeccable-variants-css-start SESSION_ID */ + @scope ([data-impeccable-variant="N"]) { + :scope { /* styles for the variant root */ } + .child-class { /* styles for children */ } + } + /* impeccable-variants-css-end SESSION_ID */ + ``` + Place the CSS in a `