voidmatcha/ui-clone-skills
GitHub: voidmatcha/ui-clone-skills
一个 Claude Code 插件，通过提取真实计算样式和 JS bundle 数据，将任意在线网站高精度逆向为 React + Tailwind 组件。
Stars: 2 | Forks: 0
# ui-clone-skills — 将任何网站克隆为 React + Tailwind 组件
一个 [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) 插件，可将任何在线网站逆向工程为可用于生产环境的 React + Tailwind 组件。
- **直接使用原始 CSS** — 下载样式表，保留原始 class 名称。无需从提取的值中重新实现。
- **验证时视觉 token 消耗接近于零** — 使用 AE/SSIM 图像差异对比代替 LLM 读取截图。视觉 token 仅在阶段 E（最终 LLM 审查）期间使用，此时自动化检查已通过但需要进行语义验证。
- **从 JS bundle 中提取真实值** — GSAP timeline、Framer Motion spring、Lenis 滚动参数、滚动驱动关键帧。告别盲目猜测。
- **当 CSS 被混淆（Tailwind，CSS-in-JS）时，回退到 `getComputedStyle`**。自动检测网站类型。
## 设计原则
这些决策塑造了插件的结构。旨在保持 agent 会话专注且有界。
- **真实值，非猜测。** 每一个数值——font-size、easing curve、scroll offset、stagger delay——均来自 `getComputedStyle`、原始 CSS 或 JS bundle grep。该插件拒绝交付近似值。
- **对比时视觉 token 消耗接近为零。** AE 和 SSIM CLI 工具处理像素差异——LLM 绝不并排阅读参考图与实现图的截图。视觉 token 仅在以下情况使用：(1) 在 AE/SSIM 失败时读取单张差异图像，(2) 阶段 E 最终语义审查（约 44K token，强制执行）。
- **渐进式子文档。** 每个 SKILL.md 仅包含 pipeline 和核心规则（3 个 skill 总计约 5.9K token）。详细过程位于 37 个聚焦的子文档中，仅在相应步骤运行时才加载。常用路径保持精简；特殊路径按需展开。
- **过渡效果的唯一事实来源。** `transition-spec.json` 仅在 bundle 分析时生成一次。实现阶段读取该规范，绝不重新 grep bundle——避免浪费工作以及选错条件分支的风险。
- **自动化优于自省。** Python 门控（`python -m ui_clone.gate`、`python -m ui_clone.pipeline`、`auto-verify.sh`）决定一个步骤是否完成。Agent 不能自我证明“看起来足够好了”。
- **无主观判断，仅凭数据。** 每一个决策必须有提取的数据、截取的屏幕截图或脚本输出的支持。“可能”、“差不多了”和“只是内容上的差异”被严格禁止——每种情况都有记录在案的失败案例。
## 技能
| 技能 | 目的 |
|---|---|
| **`ui-reverse-engineering`** | 完整流水线：URL → DOM/CSS/JS 提取 → React + Tailwind 组件。包含 Webflow IX2 检测（步骤 W）、过渡效果覆盖率审计（步骤 6d）、canvas/WebGL/Three.js 提取。 |
| **`ui-capture`** | 基准屏幕截图 + 过渡效果捕获 + 对比页面。自动检测自定义滚动（Lenis, Locomotive）。按触发类型对效果进行分类。 |
| **`visual-debug`** | 在单一技能中实现所有视觉对比。快速模式（AE/SSIM 批处理）、完整验证（阶段 A→E 及自愈循环）、区块级别对比和过渡行为差异对比。 |
## 环境要求
```
# one-liner (macOS)
brew install imagemagick dssim ffmpeg && npm i -g agent-browser && curl -LsSf https://astral.sh/uv/install.sh | sh
```
`uv` 在首次运行时会自动创建虚拟环境并安装 `scikit-image` + `Pillow` ——无需手动执行 `pip install`。
## 安装
```
# npx skills (推荐)
npx skills add voidmatcha/ui-clone-skills
# 或直接 clone
mkdir -p ~/.claude/skills
git clone https://github.com/voidmatcha/ui-clone-skills.git ~/.claude/skills/ui-clone-skills
```
### Pipeline 钩子（自动）
钩子在插件安装时通过 `hooks/hooks.json` 自动注册——无需手动设置。所有钩子通过单个 `hooks/shim.sh` 进行路由，当 `tmp/ref/` 目录不存在时会快速跳过。
| Hook 模块 | 事件 | 目的 |
|------|-------|---------|
| `ui_clone.hooks.pre_generate` | `PreToolUse` (Write/Edit) | 在提取完成之前阻止组件写入 |
| `ui_clone.hooks.post_verify` | `PostToolUse` (Bash) | 如果验证尚未运行，在完成信号时发出警告 |
| `ui_clone.hooks.devtools_errors` | `PostToolUse` (Bash) | 在每次 Bash 调用后检查浏览器 devtools 的控制台错误 |
| `ui_clone.hooks.section_gate` | `Stop` | 如果区块对比未通过，则阻止完成 |
### 门控系统
`ui_clone/` 包（Python 3.11+，由 `uv` 管理）提供 pipeline 门控、依赖跟踪（基于 DAG 的过期检测）、多尺度 SSIM 比较和基于视口的 CSS 严重性评分。
```
# Gate 验证
python -m ui_clone.gate [--json]
# Gates: reference | extraction | bundle | spec | pre-generate | post-implement | section-compare | all
# 退出: 0=PASS 1=BLOCKED 2=usage error
# Pipeline 状态
python -m ui_clone.pipeline status [--json]
```
## 快速开始
安装后（参见[安装说明](#installation)），给 Claude 一个 URL 和一个目标：
```
Clone the hero section from https://stripe.com/payments into React + Tailwind. Output to ./out/
```
流水线会自动运行。`python -m ui_clone.pipeline` 会检测当前阶段并打印下一步操作；您无需手动调用各个阶段。
**执行流程：**
1. 参考图捕获 → `tmp/ref/payments-hero/{full,desktop,tablet,mobile}.png` + 滚动视频
2. DOM/CSS/JS 提取 → `tmp/ref/payments-hero/{structure,styles,assets}.json` + `transition-spec.json`
3. 组件生成 → `./out/PaymentsHero.tsx`（CSS 优先，保留原始 class 名称）
4. 视觉验证 → `auto-verify.sh` → D0 布局健康度 + AE/SSIM 差异对比
如果验证失败，pipeline 最多迭代 3 轮（阶段 H 自愈循环）然后才会请求人工审查。
**钩子已在安装时通过** `hooks/hooks.json` **注册**——它们会自动阻止过早的写入并在未验证的完成信号时发出警告。
## `ui-reverse-engineering` — 网站 → React 组件
将任何在线网站转换为 React + Tailwind 组件。对于 URL 输入，会提取真实值。截图和视频输入将回退到 Claude Vision 进行近似估算。
**用法：**
```
Clone this site: https://example.com
Copy the hero section from https://example.com
Replicate this UI (attach screenshot)
Turn this screen recording into a working component
```
**流水线：**
```
0. Load existing analysis — re-invoked? load transition-spec.json + bundle-map.json
R. Capture reference — static screenshots + scroll video
1. Open & snapshot — DOM tree, full-page screenshot. Session reuse for splash sites
W. Webflow IX2 detection — MANDATORY if contains "Webflow".
Extract hide-rule selector list + IX2 timeline JSON.
⛔ gate: webflow-detection.json, webflow-hide-rule.json, webflow-ix2.json
2. Extract structure — HTML hierarchy, component boundaries, hidden elements
2.5 Extract assets — CSS files, fonts, images, SVGs, videos, head metadata
2.5b SVG-as-text detection — find headings rendered as SVG not fonts → svg-text-elements.json
2.6p Dual-snapshot (splash) — pre/post-splash DOM state → dom-state-diff.json.
Auto-detects splash completion (no hardcoded waits)
2.6 Catalog init styles — GSAP-baked inline styles, state coupling
3. Extract styles — computed CSS, design tokens, em-conversion (viewport-scaled).
Merge runtime-injected transitions from dual-snapshot diff
4. Detect responsive — 2-pass viewport sweep + multi-viewport sizing → sizing-expressions.json
5. Detect interactions — hover/click/scroll. Extract ALL :hover CSS from live stylesheets
(incl. inline