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

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

after.png

changes.md

tokens.json

iterate

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

  ).

• Copy-only edits (the skill is visual-design focused).
• Backend, build config, or infra tasks.

Commands

upgrade

: redesign a coded site

node runtime/bin/fal-site.mjs upgrade --target <path-or-url> [--context "..."] [--variants N] [--out <dir>]

--variants N

after-01-<slug>.png

after-02-<slug>.png

gallery.html

describe

<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

node runtime/bin/fal-site.mjs describe --after <path/to/after.png> [--out <dir>]

iterate

: residual pixel-fix pass

node runtime/bin/fal-site.mjs iterate --target <path-or-url> --reference <path/to/after.png> [--out <dir>]

current.png

delta.md

generate

: greenfield (brief → site)

node runtime/bin/fal-site.mjs generate --context "<freeform context>" [--variants 4] [--out <dir>]

Required environment

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

• 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

  .

1. 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.
2. 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?"

1. 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.
2. 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

runtime/

puppeteer

@fal-ai/client

sharp

cd runtime && npm install

FAL_SITE_RUNTIME=/abs/path