fal-redesign

What this skill does

# fal-redesign

> **Runtime:** Self-contained Node runtime under `runtime/` (`runtime/bin/fal-site.mjs`). Does things genmedia CLI cannot (puppeteer screenshotting, multi-vision pipeline, file orchestration). First-time setup: `cd runtime && npm install`. Override the runtime path with `FAL_SITE_RUNTIME=/abs/path`.

`fal-redesign` turns "I coded a site, make it look amazing" into a concrete, implementable design pass.

```
your index.html → screenshot (1920×1200)
screenshot + brand → opus-4.7 writes a redesign prompt
screenshot + prompt → fal-ai/gpt-image-2/edit → after.png
after.png → opus-4.7 writes Markdown build-spec + tokens.json
 → returned to Claude Code / Codex
```

The agent reads `after.png` + `changes.md` + `tokens.json`, applies the spec to the real HTML, refreshes, optionally runs `iterate` for a residual pixel-fix pass.

## When to invoke

- User has a local `index.html` or a running dev server and asks to improve the design, make it world-class, redesign, polish, or run a design review.
- User describes a brand/product in freeform text and asks for a fresh site (greenfield mode → `generate`).

Do NOT invoke for:
- Copy-only edits (the skill is visual-design focused).
- Backend, build config, or infra tasks.

## Commands

All four modes are subcommands of the Node runtime. Invoke directly:

### `upgrade`: redesign a coded site
```bash
node runtime/bin/fal-site.mjs upgrade --target <path-or-url> [--context "..."] [--variants N] [--out <dir>]
```

Pass `--variants N` (2-8) to fan out into N distinct design directions in parallel. You get `after-01-<slug>.png`, `after-02-<slug>.png`, plus a `gallery.html` to compare them side-by-side. Pick one, then run `describe` on the chosen PNG to produce its build-spec.

Outputs in `<out>/`:
- `before.png`: current-site screenshot.
- `after.png`: redesigned reference image.
- `edit-prompt.txt`: transformation prompt fed to gpt-image-2.
- `changes.md`: Markdown build-spec with a leading "Hard constraints" section (also echoed to stdout).
- `tokens.json`: design tokens (colors, typography clamps, grid, buttons).

### `describe`: re-run the build-spec on an existing `after.png`
Useful if the first spec was noisy or if you want to iterate on the spec without regenerating the image.
```bash
node runtime/bin/fal-site.mjs describe --after <path/to/after.png> [--out <dir>]
```

### `iterate`: residual pixel-fix pass
After the agent has implemented the spec, screenshot the live site and emit a delta-spec vs the reference.
```bash
node runtime/bin/fal-site.mjs iterate --target <path-or-url> --reference <path/to/after.png> [--out <dir>]
```
Outputs `current.png` + `delta.md`.

### `generate`: greenfield (brief → site)
```bash
node runtime/bin/fal-site.mjs generate --context "<freeform context>" [--variants 4] [--out <dir>]
```

## Required environment

```bash
export FAL_KEY=... # https://fal.ai/dashboard/keys
```

Models used:
- `anthropic/claude-opus-4.7`: via `openrouter/router` and `openrouter/router/vision` (overridable with `FAL_SITE_MODEL`).
- `fal-ai/gpt-image-2`: greenfield hero + mockup renders.
- `fal-ai/gpt-image-2/edit`: screenshot-to-redesign transformation.

## Usage pattern for agents

1. **Check `FAL_KEY`.** If unset, ask the user to export it and stop.
2. **Pick the mode.**
 - If the user references a file path that exists or a URL (`http://localhost:...`) → `node runtime/bin/fal-site.mjs upgrade`.
 - Otherwise → `node runtime/bin/fal-site.mjs generate`.
3. **Run the script.** Each `upgrade` pass takes 60–180s (1 screenshot + 2 vision calls + 1 image-edit). Emit a brief status to the user before calling.
4. **Surface the result.**
 - Open `after.png` (Read tool) so the user sees the new design.
 - Paste `changes.md` in the chat (or the highlights).
 - Ask: "Want me to implement these changes in `<file>` now?"
5. **If yes, implement.** Read the current file. Apply the spec section by section, obeying the `Hard constraints` verbatim and pulling exact values from `tokens.json`. For imagery in the result grid, look at `after.png` directly and either use `<img>` placeholders at the matching aspect ratio or source stock that matches the mood.
6. **Optional iterate.** After implementation, offer `node runtime/bin/fal-site.mjs iterate --target <file> --reference <after.png>` for a residual delta-spec. Apply deltas, refresh.

## Model notes

- Opus 4.7 handles multi-image reasoning and produces precise design specs. For 3× cheaper runs with near-parity on this task, set `FAL_SITE_MODEL=anthropic/claude-sonnet-4.6`.
- `gpt-image-2/edit` is the right primitive because it edits an existing screenshot while preserving legible in-image text, avoid substituting other image models here.

## Runtime details

The skill ships a small Node 18+ runtime under `runtime/` (`puppeteer`, `@fal-ai/client`, `sharp`). First-time setup: `cd runtime && npm install`. Override the runtime path with `FAL_SITE_RUNTIME=/abs/path`.