| name | pixel-perfect-reference-ui-zh |
| description | 当 Codex 需要基于一张网页总设计图、image2 生成图、截图、Mockup、Figma 导出图或本地参考图集，对现有网站前端进行像素级复刻或视觉重构时使用。本 skill 强制遵守：总设计图是唯一视觉来源、只从参考图裁切素材、不自创设计元素、不使用外部素材、严格保留业务功能，并通过截图、素材边缘、遮挡、响应式、z-index 与回归检查确保网页尽量一比一复刻。 |
| metadata | {"short-description":"基于总设计图的像素级网页复刻"} |
总设计图像素级网页复刻
使命
当用户提供一张网页总设计图、image2 生成图、截图、Mockup、Figma 导出图或本地参考图文件夹，并要求把现有前端改成同款视觉效果时，使用本 skill。
核心心智模型必须非常明确：
- 参考图是唯一视觉真相。
- 当前应用是唯一业务行为真相。
- 你的任务是复制和实现，不是重新设计。
- 不要做“参考灵感风格”。要尽可能复刻参考图中的布局、素材、间距、颜色、比例和视觉语言。
本 skill 必须通用于不同项目。不要把某个具体项目名、品牌名、颜色、路由或装饰元素写死，除非它们来自当前用户给出的参考图。
绝对业务契约
改代码前，先识别业务边界，并全程保持不变：
- 不修改后端、API client、services、store、auth、permission、schema、validation、database、middleware 或业务路由逻辑。
- 不删除、不重命名、不隐藏、不禁用、不截图化、不伪造任何真实按钮、表单、表格、筛选器、弹窗、菜单、导航项或用户可执行操作。
- 不改变数据结构、请求参数、状态流转、表单字段、校验逻辑、排序、筛选、分页、登录退出或权限控制。
- 不减少已有功能、入口、步骤、键盘焦点和可访问性能力。
- 只修改展示层：CSS、主题 token、布局 wrapper、className、装饰节点、响应式样式、动效和来自参考图的静态素材。
- 如果必须调整组件结构，要保留 props、事件处理、ref、可访问语义和原有行为。
- 如果用户只要求局部替换，只改指定页面、区域或组件。除非用户要求全站改版，不要动全局样式。
真实功能 UI 必须仍然是 HTML/CSS/组件。不能把表单、表格、筛选器、弹窗、导航或按钮流程变成截图。
视觉来源契约
总设计图复刻的关键是素材纪律：
- 只使用用户提供的参考图，或用户提供的本地替换素材。
- 不使用图库、图标包、AI 生成替代图、外部下载装饰、外部模板或另一套设计系统。
- 不重画一个“差不多”的花、角色、logo、图标、背景、贴纸、按钮、头像或插画。
- 不新增参考图中不存在的装饰语言。
- 从参考图裁切出的素材可以作为 img、picture、CSS background-image、sprite、mask 或装饰层放入页面。除非是纯几何 UI 且更适合用 CSS 实现，否则不要手工重绘参考图里的视觉元素。
- 真实可交互 UI 不能直接把整张参考图当截图背景。例外：如果用户明确要求把整张图作为非交互背景铺满，可以把它作为背景，同时保留上层真实 UI。
必要输入
如果缺失，只有在安全时才推断；否则只问一次：
- 项目路径，以及用户正在查看的精确 URL、路由和端口。
- 参考图、截图、设计导出文件或本地参考素材文件夹。
- 目标页面、区域、组件，以及任务类型：整页复刻、单素材替换，还是修正上一轮问题。
- 如果用户说效果不对，需要用户当前看到的截图或浏览器上下文。
用户提供本地参考文件夹时，必须先检查真实文件名、尺寸和路径，不要凭记忆假设素材名称。
工作流
1. 确认运行目标
动手前，先确认用户实际看到的是哪个页面：
- 记录用户或浏览器上下文里的精确 URL 与端口。
- 如果同时存在多个 dev server，验证用户浏览器里的那个，不要只验证自己随手启动的端口。
- 找到该路由对应的页面组件和样式文件。
- 修改素材后，直接打开素材的实际 served URL，确认返回的是图片文件和正确 content-type，而不是 HTML fallback 或旧缓存。
- 如果热更新或缓存导致看不到新图，使用带 hash 的新文件名或更新 import 路径，然后重新在浏览器里检查。
2. 先划清业务边界
阅读目标页面和附近共享组件，识别：
- 页面组件、布局壳、共享导航、侧栏、按钮、卡片、输入框、弹窗。
- API 调用、store、路由链接、点击事件、提交事件和权限逻辑。
- 样式体系：CSS Modules、SCSS、Tailwind、styled-components、全局 CSS、UI 库等。
- 哪些元素是真实功能控件，哪些只是装饰。
明确哪些文件和逻辑不能碰。优先用展示层 wrapper 解决视觉问题，避免业务重构。
3. 把参考图当规格书审图
用视觉检查和脚本测量参考图：
3A. 先建立布局格局蓝图
像素级复刻最容易失败的地方，不是颜色和素材，而是页面看着相似，但没有遵守总设计图的大小格局分布。写 CSS 前，必须把总设计图转成可测量的布局蓝图：
- 记录参考图画布宽高、目标视口宽度，以及截图缩放比例。
- 从上到下识别所有横向 section：header、hero、功能区、产品网格、footer 等。测量每个 section 的 y 起点、高度，以及占整页高度的百分比。
- 识别全局页面容器：是否全宽、是否居中 max-width、左右 gutter、是否使用固定设计稿宽度。
- 测量主要布局列：左侧文字块、右侧媒体块、中间分割、卡片网格列数、gap、左右边距。像素值和百分比都要记录。
- 测量纵向锚点：logo/nav 基线、hero 标题顶部、hero 主视觉顶部和底部、CTA 基线、section 交界线、卡片顶线、footer 基线。
- 测量主要素材包围盒：x、y、宽、高、宽高比，以及该素材是设计图中有意裁切，还是必须完整显示。
- 测量文字块包围盒，而不是只看字号。先匹配换行、文本块宽度和垂直节奏，再微调字体。
- 从蓝图派生 CSS 变量，例如 --ref-width、--section-hero-h、--hero-left-x、--hero-media-w、--grid-gap。
当 CSS 实现和参考图冲突时，按这个优先级修正：
- 整体画布/页面宽度与左右 gutter。
- section 高度和 y 位置。
- 主要列宽与 x 位置。
- 素材包围盒和裁切策略。
- 文本块宽度和换行。
- 字体、阴影、颜色和微细节。
不要让响应式便利性改写桌面端构图。在参考图对应的桌面视口下，页面应保持相同的 section 占比和对象包围盒，除非真实业务内容导致无法做到。
建议生成蓝图文件：
{
"referenceCanvas": { "width": 1920, "height": 2880 },
"targetViewport": { "width": 1440 },
"scale": 0.75,
"sections": [
{ "name": "header", "y": 0, "height": 112, "heightPct": 0.039 },
{ "name": "hero", "y": 112, "height": 820, "heightPct": 0.285 },
{ "name": "feature-band", "y": 932, "height": 520, "heightPct": 0.181 }
],
"regions": {
"heroText": { "x": 120, "y": 310, "w": 420, "h": 430 },
"heroMedia": { "x": 760, "y": 250, "w": 890, "h": 620, "fit": "contain" }
},
"grid": { "containerX": 120, "containerW": 1680, "columns": 12, "gutter": 24 }
}
本 skill 提供 scripts/extract_layout_blueprint.py 作为起始辅助脚本。它会记录图片尺寸，并把手动传入的 section/region 包围盒写成 JSON。自动检测不可靠时，以人工截图测量的包围盒为准。
- 画布尺寸与目标视口。
- 布局网格、页边距、栏宽、间距、主区域大小、对齐关系和留白。
- 字体层级、行高、字重、字距、标题换行、按钮文字容纳情况。
- 圆角、边框透明度、阴影颜色与扩散、模糊和玻璃感。
- 从像素采样颜色，不凭感觉选色：背景、表面、主色、强调色、正文、弱文字、边框、阴影。
- 素材清单：logo、标记、图标、产品截图、卡片、媒体图、贴纸、线条、箭头、背景块、花叶/角色/物件、头像、按钮背景。
- 为每个素材标注语义：是有意义内容，还是纯装饰。纯装饰通常要 aria-hidden 且不影响交互。
根据采样值建立 token，不要凭空造色：
:root {
--color-bg: ...;
--color-surface: ...;
--color-primary: ...;
--color-primary-strong: ...;
--color-accent: ...;
--color-text-main: ...;
--color-text-muted: ...;
--color-border: ...;
--shadow-card: ...;
--motion-fast: 140ms;
--motion-normal: 240ms;
--motion-slow: 600ms;
--ease-soft: cubic-bezier(0.22, 1, 0.36, 1);
--ease-gentle: cubic-bezier(0.16, 1, 0.3, 1);
}
4. 高精度裁切素材
把裁切素材统一放到清晰目录，例如：
public/assets/reference-style/
src/assets/reference-style/
建立 manifest，保证每个素材可追溯：
{
"sourceReference": "absolute/or/user/provided/path.png",
"assets": {
"logo-main": {
"file": "/assets/reference-style/logo-main.png",
"sourceBox": [120, 44, 268, 92],
"role": "semantic"
},
"hero-flower-01": {
"file": "/assets/reference-style/hero-flower-01.png",
"sourceBox": [1460, 80, 1840, 620],
"role": "decorative"
}
}
}
优先使用脚本或图像工具做精确裁切。本 skill 提供 scripts/prepare_reference_asset.py，可在 Python 和 Pillow 可用时，用于裁切、透明处理、边缘羽化和生成检查报告。
严格裁切规则：
- 只从参考图或用户提供的本地替换素材裁切。禁止外部下载。
- 输出 PNG 或 WebP。需要透明背景的素材必须带 alpha 通道。
- 不保留白色矩形底、黑边、硬边、脏边、明显背景残留或错误 matte，除非参考图本身就是这个效果。
- 如果素材有白边、黑边、锯齿、光晕或背景残留，按顺序处理：
- 重新裁切，选择更完整或更干净的区域。
- 保守地移除连接到边缘的纯白、近白或近背景色区域。
- 对 alpha 边缘做 1px 到 2px 柔和羽化。
- 如果透明处理产生光晕，用页面真实背景色做 matte 融合。
- 只允许轻微调整亮度、饱和度或色温，让原始素材融入采样背景。
- 仍然无法解决时，从同一参考图集里换一个更干净的同类素材。
- 如果没有可用替代，说明限制。禁止自己画或生成替代素材。
- 不要把模糊、低清、被裁断或边缘损坏的素材放在主要视觉位置。
- 不要过度放大裁切素材。如果目标展示尺寸超过素材可用分辨率，重新从更大区域裁切或选更干净的源素材。
- 透明 PNG 在某些查看器里可能显示黑底。必须检查 alpha 和像素数据，不要在确认前误以为它真的有黑底。
素材最低 QA：
- 检查尺寸和宽高比。
- 检查需要透明的地方是否真的有 alpha。
- 检查边缘像素是否有白边、黑边或光晕。
- 通过浏览器打开最终素材的 served URL。
- 确认不是 HTML fallback，也不是旧缓存。
5. 按参考图实现布局
从大到小实现：
- 页面背景和整体框架。
- Header、导航、侧栏几何结构。
- Hero 或首屏主区域。
- 卡片、表格、表单、弹窗、列表、Dashboard。
- 真实控件与不同状态的视觉。
- 装饰层。
- hover、focus、active、loading、empty、error 状态。
- 响应式断点。
用稳定 CSS 约束，不要堆脆弱魔法数：
- max-width、grid tracks、aspect-ratio、clamp()、min()、max()。
- 对必须完整显示的插图使用 object-fit: contain。
- 对必须完整显示的背景图使用 background-size: contain。
- 只有当裁切是参考图本身要求或用户明确接受时，才使用 background-size: cover。
- 只有装饰 wrapper 需要时才使用 overflow: visible。
- 只有参考图里确实有裁切效果，或素材安全处于内边距中时，才使用 overflow: hidden。
装饰层规则：
.reference-decor {
pointer-events: none;
user-select: none;
-webkit-user-drag: none;
object-fit: contain;
max-width: 100%;
height: auto;
}
JSX/HTML 示例：
<img
className="reference-decor"
src="/assets/reference-style/decorative-asset.png"
alt=""
aria-hidden="true"
draggable={false}
/>
装饰层必须低于 popover、dropdown、modal、drawer、toast 和真实功能面板。如果菜单或功能 UI 被覆盖，修 z-index 和层级，不要通过隐藏菜单或降低可访问性来解决。
6. 替换图片式按钮时保留功能
如果参考图中的按钮像一张图片，但当前按钮是功能控件，必须保留原 button 和事件，只替换视觉层。
<button type="button" className="ref-image-button" onClick={onClick} aria-label={label}>
<img src="/assets/reference-style/button-bg.png" alt="" aria-hidden="true" draggable={false} />
<span className="ref-image-button__text">{label}</span>
</button>
.ref-image-button {
--button-aspect: 3.2 / 1;
position: relative;
width: clamp(144px, 14vw, 220px);
aspect-ratio: var(--button-aspect);
padding: 0;
border: 0;
background: transparent;
cursor: pointer;
display: inline-grid;
place-items: center;
overflow: visible;
}
.ref-image-button > img {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
object-fit: contain;
pointer-events: none;
user-select: none;
-webkit-user-drag: none;
}
.ref-image-button__text {
position: relative;
z-index: 1;
max-width: 78%;
overflow-wrap: anywhere;
}
使用导出素材真实宽高比。不要拉伸或裁切按钮背景。如果每个按钮文字不同，文字必须作为真实 DOM 覆盖在图片上。
7. 局部替换规则
当用户要求替换某个具体素材：
- 找到该位置当前真实使用的节点、class 或资源文件。
- 除非用户要求移动，否则在同一位置替换 source 或视觉层。
- 先保持原有位置和大致尺寸，再只做必要微调以避免裁切、重叠或对齐问题。
- 不要在其他地方新增一个重复素材。
- 不要改全局样式或其他页面。
- 替换后检查该区域是否还残留旧装饰层。
- 如果用户要求“去除上一步修改”，只撤销你上一轮针对该区域的改动。不要 reset 仓库，也不要移除已被用户接受的其他 UI 工作。
视觉 QA 清单
在相同视口尺寸下对照参考图检查：
- Header/nav：位置、logo 尺寸、激活态、按钮形状、间距。
- 主布局：区域宽度、垂直节奏、标题换行、卡片对齐、留白。
- 布局蓝图：页面宽度、左右 gutter、section 高度、y 起点、列比例和主素材包围盒在参考视口下匹配参考图。
- 区块分布：section 不应比参考图明显压缩或拉长，除非真实业务内容必须如此。
- 首屏折线：如果参考图首屏露出下一段内容，实现页在同视口下也应露出相近比例。
- 图片/装饰：素材完整可见，没有缺角、意外裁切或重复覆盖。
- 边缘：没有白边、黑边、硬矩形、脏背景、锯齿光晕或明显 matte 不匹配。
- 缩放：没有模糊放大；参考图里很大的素材不能被缩得过小。
- 文字：没有图标压字、首字被遮挡、按钮/卡片文字溢出或长文本被裁掉。
- 功能层级：dropdown、popover、panel、drawer、toast、modal 应位于背景和装饰层之上。
- 表单：label、placeholder、错误提示、focus ring、disabled/loading 状态仍可见。
- 列表/表格：筛选、排序、分页、hover、空状态仍正常。
- 视觉语言：不要混入无关的默认 Material、Bootstrap、Ant Design 风格；不要出现参考图没有的随意渐变、光斑或图标。
当用户提供截图或说“还是不对”时，用户截图是最高优先级事实。修复具体错位区域，不要扩展成大改版。
响应式 QA
至少验证参考图桌面宽度和常见断点：
- 1440px 或设计稿桌面宽度。
- 1200px。
- 1024px。
- 768px。
- 390px/375px。
移动端禁止：
- 丢失导航入口或真实操作。
- 裁切表单、卡片、按钮。
- 让装饰素材遮挡按钮、文字、输入框或菜单。
- 表单产生横向滚动。
- 隐藏 focus 状态。
如果能保持功能完整且符合参考图气质，装饰素材可以在小屏缩小、移动或隐藏。
动效
只有当参考图、用户或现有应用要求动效时才复刻动效。否则使用克制 CSS 动效，不引入新的设计语言：
- 页面/卡片进入：fade + translateY(8-14px)，240-700ms。
- hover：translateY(-2px 到 -4px)，阴影轻微变化。
- 装饰 idle：仅当参考风格允许，使用很小的 float、sway 或 opacity 变化，周期 4-8s。
- 不使用剧烈弹跳、旋转、霓虹光效、强视差或新的动画库，除非参考图和现有应用本身就是这样。
必须支持减少动态偏好：
@media (prefers-reduced-motion: reduce) {
.reference-decor,
.card-enter {
animation: none !important;
transition-duration: 0.01ms !important;
transform: none !important;
}
}
验证命令
实现后运行项目可用检查：
- 项目已有的 build、typecheck、lint、test。
- 在用户实际 URL 和端口上做浏览器截图检查。
- 直接打开 served asset URL。
- 点击被修改按钮和主要导航项。
- 打开和关闭被影响的 menu、dropdown、panel、modal、drawer、toast。
- 如果触及页面里有搜索、筛选、排序、分页，也要验证它们。
- 检查浏览器 console 是否有运行时错误。
除非用户明确授权，不要输入账号密码。
常见失败模式
必须避免：
- 根据审美重新设计，而不是复制参考图。
- 自己创造新图标、花朵、角色、logo、渐变、背景或装饰元素。
- 因为“看起来相似”就使用外部素材。
- 裁切按钮或装饰后强行拉伸适配文字。
- 用户要求“原位置替换”，却把素材移动到了别的位置。
- 为了解决重叠把素材缩得过小，导致不像参考图。
- 新旧装饰重复叠在一起。
- 用户需要整图完整显示时误用 cover。
- 没检查 alpha，就把透明预览黑底当成真实黑边。
- 改了错误的 localhost 端口或 stale build。
- 只匹配颜色和素材，却忽略参考图的页面宽度、section 高度和列宽分布。
- 让内容自适应布局把桌面端本该固定比例的 section 拉长或压扁。
- 使用常见 UI 习惯里的 max-width、padding、gap，而不是从设计图测量。
- 装饰层盖住菜单、按钮或功能面板。
- 为了视觉一致把真实 UI 截图化。
可复用提示词模板
整页复刻：
Use $pixel-perfect-reference-ui-zh。请将当前已有前端页面按我提供的总设计图尽可能一比一复刻。参考图路径：[path]。目标页面/URL：[url/page]。请把参考图视为唯一视觉来源，把当前应用视为唯一业务行为来源。必须完整保留业务行为：API、路由、store、auth、表单字段、校验、筛选、排序、分页、点击事件和用户流程都不能改变。所有视觉素材只能从我提供的参考图中裁切，不得使用外部素材，不得自己重画类似元素。功能 UI 必须仍然是真实 HTML/CSS/组件。完成后检查桌面端和移动端截图、布局蓝图比例、实际 served asset URL，以及项目可用的 build/lint/typecheck。最后报告修改文件、新增素材、检查命令、回归结果和无法完全复刻的原因。
单素材替换：
Use $pixel-perfect-reference-ui-zh。请只替换 [页面/区域/组件] 中的 [当前素材/按钮/装饰]，新素材来自 [path/name]。保留原有行为、点击事件、路由、表单逻辑、状态和附近布局。新素材必须按原始比例显示，不能拉伸、裁切或过度放大。除非我明确要求移动，否则保持原位置。若有白边/黑边，按重新裁切、透明处理、1-2px 羽化、matte 融合的顺序处理。不要改其他页面或组件。完成后验证没有截断、重叠、旧缓存或 UI 回归。
位置/大小修正：
Use $pixel-perfect-reference-ui-zh。请只调整 [页面/url] 上的 [素材/组件]。当前问题是：[太小/被裁切/重叠/边缘异常/对齐不准]。保持素材来源和整体视觉语言不变。只允许改尺寸、位置、z-index、object-fit/background-size 或 wrapper overflow，让它完整、对齐且不遮挡其他 UI。不要触碰业务逻辑或无关素材。请验证桌面端和移动端。
撤销错误视觉修改：
Use $pixel-perfect-reference-ui-zh。请只撤销你上一步针对 [素材/区域/组件] 的修改。不要 reset 仓库，不要移除其他已经被接受的 UI 工作。恢复该区域之前的素材来源、位置或样式，并确认没有残留重复素材、class 或装饰层。
