UI Replica

Overview

这个 skill 用来把“看图写页面”约束成一条可校正的工程流程：先拆页面骨架和规格，再决定哪些内容应该原生实现、哪些应该矢量重建、哪些才值得裁切成素材，最后基于固定尺寸截图对比逐轮修正。目标不是做一个风格类似的页面，而是尽量精确复刻设计图，同时保持实现策略合理、可维护。

When To Use

在下面这些场景触发：

• 用户明确要求“精准还原”“像素级还原”“按设计图实现”。
• 输入里包含设计稿截图、登录页视觉稿、活动页参考图、APP 页面截屏。
• 任务重点是布局、尺寸、位置、颜色、圆角、阴影、透明度、层级、留白的精确还原。
• 任务重点是还原不规则边框、科技感描边、HUD 外框、异形卡片轮廓。
• 任务需要从截图中提取图标、按钮标识、品牌标识或小型 UI 素材，并转成可复用透明背景资源。
• 需要先输出结构化规格稿，再开始写代码。

下面这些情况不要优先用这个 skill：

• 用户只要一个大致风格相似的页面。
• 用户主要诉求是交互逻辑、接口联调、状态管理，而不是视觉还原。
• 设计信息严重缺失，且用户也不接受不确定项标记。

Core Workflow

0. Choose The Least Distorting Strategy

在开始写代码前，先判断实现策略，不要默认“全手绘”或“全裁切”。

默认优先级：

1. 原生布局与文本：适合标题、段落、按钮、输入框、导航、页脚、卡片、列表、表格等语义明确、后续可能调整的区域。
2. 原生 SVG / CSS 几何：适合简单线性图标、网格点阵、切角边框、单色小符号、规则装饰线。
3. 截图裁切素材：只用于原生实现成本明显更高、且还原误差明显更难控制的小型视觉资产。

必须避免两个极端：

• 不要为了追求“纯代码”去手画本来就应该复用的微型系统控件、品牌 Logo 或复杂质感图标。
• 不要为了省事把本应原生实现的大块语义区域直接裁成位图，比如整组按钮、整段导航、页脚整行、主卡片、主要文本块。

当你拿不准时，先问这三个问题：

• 这个对象是否承载真实语义或排版职责？
• 这个对象是否可以用普通文本、布局、圆角、边框、阴影稳定复现？
• 这个对象裁成素材后，是否会明显损害可维护性、可缩放性或后续状态扩展？

只要前两个问题有一个答案是“是”，默认就不该先裁切。

1. Read The Design Before Coding

先读取设计图基础信息，再开始任何代码实现：

• 记录设计图尺寸。
• 判断页面主体范围，剔除设备边框、状态栏、拍摄背景等非页面主体内容。
• 先拆一级结构，不要一上来细拆按钮和图标。

任务开始时必须先输出：

• 设计图尺寸
• 页面主体范围判断
• 一级结构拆分结果
• 真实布局元素清单
• 纯视觉元素清单

2. Produce A Structured Spec

编码前必须先给出结构化规格稿，至少包含：

• 画布尺寸
• 一级结构划分
• 关键容器边界框
• 文本节点样式
• 主要装饰资源
• 布局方式
• 全局颜色 token
• 全局圆角 token
• 全局阴影 token

对关键元素优先记录这些字段：

• name
• role
• parent
• x
• y
• width
• height
• z_index
• layout_type
• gap
• padding
• margin
• background
• border
• border_radius
• shadow
• blur
• opacity
• font_family
• font_size
• font_weight
• line_height
• color
• text_align
• asset_ref

如果某个值无法精准判断，明确写“待确认”，不要脑补一个看起来合理的数值。

3. Separate Layout From Decoration

元素必须分成两类：

• 真实布局元素：参与排版、影响留白和对齐、承载文本或交互、后续需要维护。
• 纯视觉元素：背景图、插画、光效、漂浮装饰、纯氛围层。

实现时采用两层结构：

• 骨架层：优先用 flex、grid、普通文档流完成主结构。
• 装饰层：只放纯视觉装饰，允许绝对定位。

不要把真实布局元素全部写成绝对定位，也不要把纯视觉内容拆成大量无意义 DOM。

4. Implement In Maintainable Files

默认优先使用免构建的原生 HTML + CSS + ES Modules。

• HTML 只保留薄壳。
• 页面结构、组件结构、样式、资源引用分别拆分。
• 不要把结构、样式、行为混在一个超大文件里。
• 不要用一整段 innerHTML 字符串充当主要架构。

推荐结构：

• index.html
• main.js
• pages/
• components/
• styles/
• assets/

如果页面明显包含多个独立区域，就拆组件；如果只是静态片段，再考虑是否保持为局部片段。

5. Handle Irregular Borders As Vector Reconstruction

当用户要还原的是不规则边框、科技感外框、异形描边，而不是普通矩形卡片时，不要急着用 border-radius、clip-path 或大量绝对定位去猜。

应改用“坐标提取 + SVG 绘制”的流程：

• 先确认最终只需边框本体，还是边框加整页布局。
• 记录参考图原始尺寸，SVG viewBox 默认和原图一致。
• 先拆成 outer frame、inner frame、accent lines、corner chips 这类轮廓层，不要把整张图一次性塞成单一路径。
• 可以先用脚本做阈值筛选、边缘采样、行列扫描来找大致锚点，但最终交付的坐标必须是可读、可改、可复核的显式数组。
• 当局部存在折线、缺口、切角、短刻线时，优先用多个 polyline / path 组合，而不是强行压成单个复杂 clip-path。
• 如果用户明确要求白底展示，就先在白底下把边框本体做准，不要附带额外卡片和说明文案。

涉及这类任务时，继续细化的执行细则见 [references/ui-replication-workflow.md](references/ui-replication-workflow.md) 中的“不规则边框与 SVG 坐标还原”。

6. Use Screenshot Assets Only When Native Reconstruction Is Not Worthwhile

当设计图里的图标不是现成 icon font / lucide 图标，且原生 SVG / CSS 近似后会明显失真时，才考虑把它提取成素材。

素材提取不是默认动作，而是最后一层策略。只有下面情况成立时才应优先提取：

• 品牌 Logo、品牌图标、特殊字标，曲线和配色必须精确保留。
• 图标很小，但视觉风格很强，手绘近似后会明显“看着不对”。
• 图标包含渐变、复杂高光、材质、阴影、半透明边缘，原生复刻成本高且仍不稳。
• 对象后续不需要复杂交互、动态状态或响应式重排。

下面这些内容默认不要先裁成素材：

• 按钮正文、导航文本、页脚链接、表单标签、列表项文本。
• 普通按钮、输入框、卡片、页脚、导航栏等大块语义区域。
• 可以用普通文本、边框、圆角、阴影稳定还原的标准组件。
• 仅仅因为“截图里已经有”就整块裁下来的布局块。

图标提取按“分析目标 -> 定位裁剪 -> 处理透明背景 -> 提取主体 -> 观察复核 -> 固化配置”的流程执行：

• 先识别图标类型：圆形按钮、圆角方形 App 图标、单色线性图标、复杂品牌图标、背景氛围中的小装饰。
• 对圆形按钮优先用 Hough 圆检测或人工确认圆心半径，再做圆形 alpha mask。
• 对白色或单色标识优先用亮度阈值、饱和度约束、连通域过滤和形态学开闭运算提取主体。
• 同时保留完整按钮版和主体标识版，方便后续分别用于“按原图复刻”和“重组到新背景”。
• 每次提取都保留 debug 裁剪图、预览图和配置文件，避免素材来源变成不可复现的手工操作。

涉及这类任务时，继续细化的执行细则、函数清单和参数策略见 [references/icon-extraction-workflow.md](references/icon-extraction-workflow.md)。

7. Reserve Crops For Small High-Fidelity Controls

当参考图本身包含桌面应用外壳、系统级窗口按钮、会话工具栏小图标、滚动条、禁用态按钮、极小的分隔符或状态指示器时，可以优先判断这些内容是不是更适合复用原图素材，而不是默认全部重画。

优先直接裁切复用的典型对象：

• 左上角图钉、窗口控制按钮、会话操作区小图标
• 细滚动条、禁用态发送按钮、微小状态徽标
• 已经足够清晰且后续不会交互变化的底部工具栏小图标组

采用裁切复用时要遵守这些约束：

• 只对高还原收益、低维护成本的小型控件使用，主体布局和主要文案仍应用正常结构实现。
• 在规格稿中记录裁切框、输出尺寸、是否保留背景、是否允许缩放。
• 如果一组小图标共享同一深色背景，优先整组裁切，避免逐个重画后出现风格不统一。
• 如果裁切对象后续需要交互、响应式适配或状态切换，再退回矢量/布局实现。

明确禁止把下面内容整块裁切充当主要实现：

• 整个页脚、整条导航、整组普通按钮、整段语言提示、整块搜索框或整个内容卡片。
• 任何会因为文本变化、宽度变化、hover/selected 状态变化而立刻失效的语义组件。
• 本质上应由布局和文本驱动的区域，只因为截图现成就被裁下来复用。

8. Validate By Screenshot Diff

第一版页面目标是骨架正确、主元素齐全、位置关系正确、样式方向正确，不要为了第一版就堆过量细节代码。

完成后必须按设计图基准尺寸截图对比，重点检查：

• 整体布局比例
• 卡片位置
• 标题位置
• 输入框高度
• 按钮尺寸
• 留白
• 对齐方式
• 圆角
• 阴影
• 透明度
• 装饰层位置

修正时必须给出具体偏差，例如“右侧卡片偏窄 24 像素”，不能只说“再优化一下”。

如果截图结果与页面结构明显不符，先排查是不是截图链路的问题，再判断是不是页面代码问题。常见排查点：

• 无头浏览器的 window-size 是外窗尺寸，不是内容视口尺寸。
• 浏览器可能在脚本尚未完成渲染时提前截图。
• 本地文件协议、跨平台浏览器路径、系统缩放和滚动条策略会影响截图结果。

当无头浏览器无法稳定得到精确视口时，允许：

• 提高截图窗口尺寸后再按设计图尺寸裁切。
• 增加 virtual-time-budget 或等价等待，确保脚本和资源加载完成。
• 先验证 DOM 和资源是否正确加载，再继续怀疑布局。

9. Audit By Functional Areas Before The Second Repair Pass

当首版已经接近原图，但仍有多个局部偏差时，不要继续“整体看着改”。应先把页面拆成功能区，再逐区核对。

推荐功能区粒度：

• 窗口外框区
• 标题信息区
• 标题操作区
• 消息内容区
• 输入编辑区
• 底部工具栏区

逐区核对时至少检查：

• 元素是否缺失
• 元素顺序是否一致
• 是否用了错误的近似图标
• 区域内留白和对齐是否偏移
• 当前偏差更适合“改布局”还是“替换素材”

第二轮及之后的修正，优先基于这类功能区审计清单推进，而不是重新生成整页。

Output Contract

完整输出顺序固定为：

1. 设计图尺寸、主体范围、一级结构、真实布局元素、纯视觉元素
2. 结构化规格稿
3. 实现方案、文件结构、页面实现文件；只有在用户要求纯文本交付时才输出完整代码
4. 截图对比结论、当前仍存在的偏差、下一轮修正点

Hard Rules

• 禁止跳过结构化规格稿直接写页面。
• 禁止在缺失信息时私自补设计。
• 禁止把布局问题全部用 absolute 糊过去。
• 禁止把纯视觉资源拆成大量无意义 DOM。
• 禁止为了省事忽略局部重构需求。
• 禁止使用“逻辑兜底”“防御性处理”“大概类似”这类模糊说法。

Reference

完整工作流细则和字段说明见 [references/ui-replication-workflow.md](references/ui-replication-workflow.md)。图标提取、透明背景处理、截图素材沉淀见 [references/icon-extraction-workflow.md](references/icon-extraction-workflow.md)。当任务需要更细的约束、验收顺序、禁止事项或不确定项处理方式时，再读取对应 reference。