Image-first Frontend

Generate the design first, approve it, then build it.

先生成设计，确认后再实现。

中文 | English

---

中文

image-first-frontend 是一个面向 Codex 的前端设计 Skill。它先通过可自定义的 GPT Image 兼容 API 生成前端参考图，把版本化预览保存在项目目录中，等待用户批准、修改或重做，然后才根据最终批准的图片实现可运行、响应式的前端页面。

它不会把截图直接当作页面背景。目标是在参考视口下尽可能忠实地还原设计，同时保留真实组件、交互、语义结构和响应式行为。

核心能力

• 通过自定义 /images/generations 兼容端点生成第一版前端设计
• 将预览保存到项目内的 design-previews/<page>/reference-vNN.png
• 在编写前端代码前强制进入用户批准关卡
• 通过自定义 /images/edits 兼容端点和上一版图片进行定向修改
• 支持可选的图片编辑遮罩 --mask
• 用户要求重做时返回 generations 流程，不把旧设计作为输入
• 保留全部预览版本，并在 API 调用前拒绝覆盖已有输出
• 批准后才提取布局规格、实现页面并进行同尺寸截图比对
• 仅使用 Python 标准库，无额外 Python 依赖

工作流程

1. Codex 读取项目结构、现有样式、内容约束和目标视口。
2. Skill 调用 generations 端点生成 reference-v01.png。
3. Codex 在对话中展示图片，并给出项目内路径。
4. 用户选择批准、指定修改或重做。
5. 指定修改使用当前图片调用 edits 端点，输出下一个版本。
6. 重做使用新的视觉方向再次调用 generations 端点。
7. 只有明确批准后，Codex 才开始实现页面并进行视觉比对。

项目结构

image-first-frontend/
├── SKILL.md
├── README.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── generate_reference.py

环境要求

• Python 3.10 或更高版本
• 支持自定义 Skills 的 Codex 环境
• 一个兼容的图片生成端点
• 若需要基于图片修改，还需要兼容的图片编辑端点

脚本不要求连接 OpenAI。两个 URL 都可以指向你自己的网关、代理或其他兼容服务。

安装

将整个目录放入 Codex Skills 目录，并保持文件夹名为 image-first-frontend。

macOS / Linux：

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R ./image-first-frontend "${CODEX_HOME:-$HOME/.codex}/skills/image-first-frontend"

Windows PowerShell：

$skills = if ($env:CODEX_HOME) { "$env:CODEX_HOME\skills" } else { "$HOME\.codex\skills" }
New-Item -ItemType Directory -Force -Path $skills | Out-Null
Copy-Item -Recurse -Force .\image-first-frontend "$skills\image-first-frontend"

安装后启动一个新的 Codex 会话，使 Skill 元数据被重新发现。

配置 API

编辑 scripts/generate_reference.py 顶部的常量：

GENERATIONS_API_URL = "https://api.example.com/v1/images/generations"
EDITS_API_URL = "https://api.example.com/v1/images/edits"
API_KEY = "REPLACE_WITH_YOUR_API_KEY"
MODEL = "gpt-image-2"

• GENERATIONS_API_URL：用于从文字生成新设计。
• EDITS_API_URL：用于把上一版预览作为图片输入进行修改。
• API_KEY：通过 Authorization: Bearer ... 发送。
• MODEL：由你的兼容服务支持的模型名称。

不要把真实密钥提交到 Git。公开仓库应始终保留占位符；本地配置可以放在未提交的副本中。

在 Codex 中使用

$image-first-frontend 为我的开发者工具设计一个 1536x1024 的分析仪表盘，先给我看参考图，批准后再实现。

预览后可以直接回复：

批准这个版本。

保留当前布局和排版，把强调色改成绿色，主图区域更紧凑。

重做，换成更克制的企业级视觉方向。

直接使用辅助脚本

以下命令从 Skill 目录执行。

生成第一版：

python scripts/generate_reference.py \
  --brief "A focused analytics dashboard for a developer observability product" \
  --output "./design-previews/dashboard/reference-v01.png" \
  --size "1536x1024"

基于上一版进行修改：

python scripts/generate_reference.py \
  --input-image "./design-previews/dashboard/reference-v01.png" \
  --brief "Preserve: layout and typography. Change: use green accents and reduce hero height." \
  --output "./design-previews/dashboard/reference-v02.png" \
  --size "1536x1024"

使用可选遮罩：

python scripts/generate_reference.py \
  --input-image "./design-previews/dashboard/reference-v02.png" \
  --mask "./design-previews/dashboard/mask.png" \
  --brief "Change only the highlighted chart area." \
  --output "./design-previews/dashboard/reference-v03.png"

只检查请求摘要，不调用 API：

python scripts/generate_reference.py \
  --input-image "./design-previews/dashboard/reference-v01.png" \
  --brief "Preserve the layout. Change the accent color to green." \
  --output "./design-previews/dashboard/reference-v02.png" \
  --dry-run

--dry-run 不会输出 API 密钥，也不会写入目标图片。

命令行参数

参数	说明
--brief TEXT	产品需求或修改说明
--brief-file PATH	从 UTF-8 文件读取较长需求，与 --brief 二选一
--output PATH	新图片的输出路径，必填且不能已存在
--input-image PATH	要修改的上一版图片；省略时走 generations
--mask PATH	可选编辑遮罩，必须与 --input-image 一起使用
--size SIZE	请求尺寸，默认 1536x1024
--quality VALUE	请求质量，默认 high
--timeout SECONDS	HTTP 超时，默认 180 秒
--dry-run	输出不含密钥的请求摘要，不调用 API

兼容 API 契约

Generations 请求使用 JSON，包含：

• model
• prompt
• n
• size
• quality

Edits 请求使用 multipart/form-data，包含：

• 文件字段 image
• 可选文件字段 mask
• 文本字段 model、prompt、n、size、quality

响应可以在顶层或 data、images、output 数组中返回以下任一字段：

• Base64：b64_json、image_base64、b64
• URL：url、image_url

如果你的服务使用不同字段名或 multipart 结构，需要调整辅助脚本。

安全设计

• 输出路径已存在时，在 API 请求前失败，避免覆盖和不必要计费。
• API 错误正文中的密钥会被替换为 [REDACTED]。
• 跨域 HTTP 重定向会移除 Authorization 和 Proxy-Authorization。
• 远程图片只接受 http、https 或内嵌 data:image/...。
• file: 等本地文件 URL 会被拒绝。
• 跨域图片 URL 默认不携带 API 密钥。

如果服务依赖跨域重定向后继续转发认证头，请改用最终 API URL；脚本不会为了兼容而泄露密钥。

“1:1” 的含义

“1:1” 指在参考图片的目标视口下实现高视觉保真，并在其他视口提供合理的响应式行为。它不表示：

• 把整张参考图设置成页面背景
• 把截图切片伪装成交互界面
• 为了像素一致而牺牲真实内容、可访问性或功能

Skill 会优先匹配整体几何、字体换行、间距、图片、颜色、边框和阴影，然后验证交互与响应式布局。

常见问题

提示配置 GENERATIONS_API_URL 或 EDITS_API_URL

检查对应 URL 和 API_KEY 是否仍是占位符。只有修改已有图片时才需要 edits URL。

提示 Output already exists

不要覆盖旧图。把输出文件名增加到下一个版本，例如从 reference-v02.png 改为 reference-v03.png。

提示 No image found in the API response

服务响应结构与当前兼容契约不一致。检查响应是否包含受支持的 Base64 或 URL 字段。

重定向后返回 401

跨域重定向会主动移除认证头。把配置 URL 改成最终端点，或让服务使用同源重定向。

修改结果偏离上一版

在 --brief 中明确写出 Preserve: 和 Change:。不要在修改路径失败时自动回退到纯文字生成。

贡献

欢迎提交 Issue 和 Pull Request。修改时请遵守以下原则：

• 保持辅助脚本仅依赖 Python 标准库，除非新增依赖有明确收益
• 为 generations 和 edits 两条路径提供本地模拟测试
• 不在测试、日志、截图或提交记录中放入真实密钥
• 保留预览批准关卡，不允许在用户批准前实现页面
• 对重定向、URL 方案和文件写入相关改动补充安全回归测试

本仓库不是 OpenAI 官方项目，也不代表任何兼容 API 服务商。

---

English

image-first-frontend is a frontend design Skill for Codex. It generates a visual frontend reference through configurable GPT Image-compatible APIs, stores versioned previews inside the project, waits for the user to approve, revise, or redo the design, and only then implements the approved image as a functional responsive page.

It does not use the screenshot as the page background. The goal is high visual fidelity at the reference viewport while retaining real components, interactions, semantic structure, and responsive behavior.

Key features

• Generate the first design through a custom /images/generations-compatible endpoint
• Store previews at design-previews/<page>/reference-vNN.png
• Enforce an explicit user approval gate before frontend implementation
• Revise the previous preview through a custom /images/edits-compatible endpoint
• Support an optional image-edit mask with --mask
• Return to generations without the old image when the user requests a full redo
• Preserve every preview version and reject an existing output before the API call
• Extract layout measurements, implement the page, and compare same-size screenshots after approval
• Use only the Python standard library

Workflow

1. Codex inspects the project structure, existing styles, content constraints, and target viewport.
2. The Skill calls the generations endpoint and creates reference-v01.png.
3. Codex displays the image and provides its project-local path.
4. The user approves it, requests specific changes, or asks for a full redo.
5. A targeted revision sends the current image to the edits endpoint and creates the next version.
6. A redo calls generations again with a materially different direction.
7. Codex starts implementation and visual comparison only after explicit approval.

Repository structure

image-first-frontend/
├── SKILL.md
├── README.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── generate_reference.py

Requirements

• Python 3.10 or newer
• A Codex environment with custom Skills support
• A compatible image-generation endpoint
• A compatible image-edits endpoint for image-conditioned revisions

The helper does not require an OpenAI connection. Both URLs may point to your own gateway, proxy, or another compatible service.

Installation

Place the complete directory in your Codex Skills directory and keep the folder name image-first-frontend.

macOS / Linux:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R ./image-first-frontend "${CODEX_HOME:-$HOME/.codex}/skills/image-first-frontend"

Windows PowerShell:

$skills = if ($env:CODEX_HOME) { "$env:CODEX_HOME\skills" } else { "$HOME\.codex\skills" }
New-Item -ItemType Directory -Force -Path $skills | Out-Null
Copy-Item -Recurse -Force .\image-first-frontend "$skills\image-first-frontend"

Start a new Codex session after installation so the Skill metadata is rediscovered.

API configuration

Edit the constants near the top of scripts/generate_reference.py:

GENERATIONS_API_URL = "https://api.example.com/v1/images/generations"
EDITS_API_URL = "https://api.example.com/v1/images/edits"
API_KEY = "REPLACE_WITH_YOUR_API_KEY"
MODEL = "gpt-image-2"

• GENERATIONS_API_URL creates a new design from text.
• EDITS_API_URL revises a previous preview supplied as an image.
• API_KEY is sent as Authorization: Bearer ....
• MODEL is the model identifier supported by your provider.

Never commit a real key. Keep placeholders in the public repository and configure credentials only in an uncommitted local copy.

Use from Codex

$image-first-frontend Design a 1536x1024 analytics dashboard for my developer tool. Show me the reference first and implement it only after I approve it.

After seeing the preview, reply with an approval, revision, or redo request:

Approve this version.

Keep the current layout and typography, change the accent to green, and make the hero more compact.

Redo it with a quieter enterprise visual direction.

Use the helper directly

Run these commands from the Skill directory.

Generate the first version:

python scripts/generate_reference.py \
  --brief "A focused analytics dashboard for a developer observability product" \
  --output "./design-previews/dashboard/reference-v01.png" \
  --size "1536x1024"

Revise the previous version:

python scripts/generate_reference.py \
  --input-image "./design-previews/dashboard/reference-v01.png" \
  --brief "Preserve: layout and typography. Change: use green accents and reduce hero height." \
  --output "./design-previews/dashboard/reference-v02.png" \
  --size "1536x1024"

Use an optional mask:

python scripts/generate_reference.py \
  --input-image "./design-previews/dashboard/reference-v02.png" \
  --mask "./design-previews/dashboard/mask.png" \
  --brief "Change only the highlighted chart area." \
  --output "./design-previews/dashboard/reference-v03.png"

Inspect a request without calling the API:

python scripts/generate_reference.py \
  --input-image "./design-previews/dashboard/reference-v01.png" \
  --brief "Preserve the layout. Change the accent color to green." \
  --output "./design-previews/dashboard/reference-v02.png" \
  --dry-run

--dry-run does not print the API key or write the output image.

CLI reference

Argument	Description
--brief TEXT	Product brief or revision request
--brief-file PATH	Read a longer brief from a UTF-8 file; mutually exclusive with --brief
--output PATH	Required new output path; must not already exist
--input-image PATH	Previous preview to edit; omit it to use generations
--mask PATH	Optional edit mask; requires --input-image
--size SIZE	Requested image size; defaults to 1536x1024
--quality VALUE	Requested quality; defaults to high
--timeout SECONDS	HTTP timeout; defaults to 180 seconds
--dry-run	Print a secret-free request summary without calling the API

Compatible API contract

Generation requests use JSON with:

• model
• prompt
• n
• size
• quality

Edit requests use multipart/form-data with:

• File field image
• Optional file field mask
• Text fields model, prompt, n, size, and quality

Responses may provide one of these fields at the top level or inside data, images, or output:

• Base64: b64_json, image_base64, or b64
• URL: url or image_url

Adjust the helper if your provider uses a different schema or multipart field names.

Security behavior

• Existing output paths fail before the API request, preventing overwrite and unnecessary billing.
• API keys found in error bodies are replaced with [REDACTED].
• Cross-origin HTTP redirects remove Authorization and Proxy-Authorization.
• Remote images are limited to http, https, or inline data:image/... values.
• Local schemes such as file: are rejected.
• Cross-origin image URLs do not receive the API key by default.

If your provider depends on forwarding credentials across origins, configure the final endpoint URL instead. The helper will not weaken credential handling for compatibility.

What “1:1” means

“1:1” means high visual fidelity at the reference viewport with intentional responsive behavior elsewhere. It does not mean:

• Using the complete reference image as a page background
• Slicing the screenshot into a fake interactive interface
• Sacrificing real content, accessibility, or functionality for pixel similarity

The Skill matches macro geometry, text wrapping, spacing, imagery, color, borders, and shadows before validating interaction and responsive layout.

Troubleshooting

The helper asks you to configure GENERATIONS_API_URL or EDITS_API_URL

Check that the corresponding URL and API_KEY are not placeholders. The edits URL is needed only when revising an existing image.

Output already exists

Do not overwrite the previous preview. Increment the version, for example from reference-v02.png to reference-v03.png.

No image found in the API response

Your provider returned a schema that the helper does not recognize. Confirm that the response contains a supported Base64 or URL field.

A redirect ends with HTTP 401

Cross-origin redirects intentionally lose the authorization header. Configure the final endpoint directly or use a same-origin redirect.

The revision drifts too far from the previous version

Use explicit Preserve: and Change: sections. Do not silently fall back to text-only generation when the edits path fails.

Contributing

Issues and pull requests are welcome. Please follow these constraints:

• Keep the helper standard-library-only unless a dependency has a clear benefit
• Cover both generations and edits with local mocked tests
• Never include real credentials in tests, logs, screenshots, or commits
• Preserve the preview approval gate before frontend implementation
• Add security regression coverage for redirect, URL-scheme, and file-writing changes

This is an independent community project. It is not an official OpenAI project and is not affiliated with any compatible API provider.