image-first-frontend

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 密钥，也不会写入目标图片。

命令行参数

兼容 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: