lanhu-design-to-html

name	lanhu-design-to-html
description	从蓝湖设计稿链接获取设计信息并还原为HTML页面。Invoke when user provides a lanhuapp.com link, asks to analyze/restore a Lanhu design mockup, or needs to extract design specs from Lanhu.

Lanhu Design to HTML

从蓝湖设计稿链接自动获取设计数据、分析图层结构、提取元素样式，并还原为 HTML 页面。

When to Use

当用户提供 lanhuapp.com 链接，或要求分析/还原蓝湖设计稿时调用此 skill。

Prerequisites

• playwright-cli 已安装（运行 npx --no-install playwright-cli --version 检查）
• Node.js 已安装（用于解析设计数据）

Workflow Overview

蓝湖链接 → 打开浏览器 → 获取Sketch JSON → 解析图层/样式 → 下载切图到本地 → 分析结构 → 生成HTML → 验证效果

核心原则：切图本地化（必须遵守）

所有切图必须下载到本地 assets/images/ 目录，HTML 中只引用本地相对路径，禁止使用蓝湖 CDN 链接（如 lanhu.oss-cn-beijing.aliyuncs.com、alipic.lanhuapp.com）。原因：

• CDN 链接可能因权限/防盗链/链接失效导致图片无法显示
• 本地化后页面可离线运行、便于部署、加载更稳定
• 切图通过 download-images.js 统一下载，并生成 image-map.json（URL → 本地路径映射），生成 HTML 时按映射表替换为本地路径

Quick Start

Step 1: 打开蓝湖设计稿（含登录检测）

# 1. 以持久化模式打开浏览器（默认 headless，高效）
playwright-cli open --persistent

# 2. 导航到蓝湖链接（URL含&时必须用双引号包裹）
playwright-cli goto "https://lanhuapp.com/web/#/item/project/detailDetach?pid=XXX&image_id=XXX&project_id=XXX&fromEditor=true&type=image"

# 3. 等待页面加载后检测登录状态
Start-Sleep -Seconds 3
playwright-cli eval "document.querySelector('.layers_item, .image-wrapper, canvas') ? 'logged-in' : 'NOT-logged-in'"

关键点：

• URL 中的 & 在 PowerShell 中会被解释为命令分隔符，必须用双引号 "..." 包裹整个 URL
• 使用 --persistent 保持登录状态（蓝湖需要登录才能查看设计稿）
• 等待 3-5 秒让页面完全加载

未登录处理（自动切换 headed 模式）

如果 Step 3 返回 NOT-logged-in，说明用户未登录蓝湖。此时关闭 headless 浏览器，切换到 --headed 模式，让用户在可见的浏览器窗口中手动登录：

# 1. 关闭 headless 浏览器
playwright-cli close

# 2. 以 headed + persistent 模式重新打开浏览器（窗口可见，用户可操作）
playwright-cli open --persistent --headed

# 3. 重新导航到蓝湖设计稿链接
playwright-cli goto "https://lanhuapp.com/web/#/item/project/detailDetach?pid=XXX&image_id=XXX&project_id=XXX&fromEditor=true&type=image"

# 此时浏览器窗口可见，页面显示蓝湖登录界面
# 提示用户：请在弹出的浏览器窗口中登录蓝湖（支持扫码 / 账号密码登录）

# 4. 轮询检测登录是否完成（每 3-5 秒重复执行，直到返回 logged-in）
playwright-cli eval "document.querySelector('input[type=password], .login-form, .login-container') ? 'waiting' : 'logged-in'"

# 5. 登录完成后，重新导航到设计稿链接（登录后页面会跳转到蓝湖首页）
playwright-cli goto "https://lanhuapp.com/web/#/item/project/detailDetach?pid=XXX&image_id=XXX&project_id=XXX&fromEditor=true&type=image"
Start-Sleep -Seconds 3

注意：

• --headed 让浏览器窗口可见，用户可在页面上操作登录（扫码、输入账号密码等）
• --persistent 确保登录状态保存到磁盘，下次运行自动保持登录（headless 即可）
• 登录完成后必须重新导航到设计稿链接，因为登录后页面会跳转到蓝湖首页
• 登录只需一次，后续运行会自动保持登录状态

Step 2: 获取 Sketch JSON 设计数据

蓝湖页面加载时会通过 API 请求获取完整的 Sketch JSON 数据，包含所有图层、样式、切图信息。

# 查看网络请求，找到 SketchJSON URL
playwright-cli requests

# 找到包含 "SketchJSON" 或 "alipic.lanhuapp.com" 的请求编号
# 获取响应体（文本类型直接显示，二进制保存到文件）
playwright-cli response-body <request-number>

识别 Sketch JSON 请求：

• URL 通常包含 alipic.lanhuapp.com 或 SketchJSON
• Content-Type 为 application/json 或 application/octet-stream
• 文件较大（通常 100KB+）

Step 3: 解析设计数据

使用辅助脚本解析 Sketch JSON，提取所有图层信息。

# 将响应体文件路径传给解析脚本
node .trae/skills/lanhu-design-to-html/scripts/parse-design.js <response-file-path>

脚本会生成：

• design-analysis.txt - 人类可读的图层分析报告
• design-layers.json - 结构化的图层数据（供 HTML 生成使用）

Step 4: 下载切图到本地（必做）

生成 HTML 之前，必须先把所有切图下载到本地。 解析脚本会在控制台末尾打印下载命令，直接复制执行即可：

# 将 design-layers.json 中的所有切图下载到本地 assets/images/
node .trae/skills/lanhu-design-to-html/scripts/download-images.js <design-layers.json> <output-dir>

脚本会：

• 读取 design-layers.json，按优先级 SVG > PNG > DDS 收集所有切图 URL
• 下载到 <output-dir>/assets/images/ 目录（文件名取自图层名，自动去重）
• 生成 image-map.json — 原始 URL 到本地相对路径的映射表（如 {"https://lanhu.../SketchPngxxx": "./assets/images/apeman.png"}）
• 失败的切图单独记录到 image-download-failures.json，可重试

生成 HTML 时，所有 <img src> 必须查 image-map.json 替换为本地路径，不得直接写蓝湖 CDN 链接。

Step 5: 分析图层结构

根据解析结果，识别页面的组成结构：

1. 画板信息：尺寸、名称
2. 文本图层：内容、字体、字号、颜色、对齐方式、行高
3. 图片/切图图层：图片 URL、尺寸、位置
4. 形状图层：填充色、圆角、边框、阴影
5. 分组图层：层级关系

重点：检查切图可用性。解析报告会为每个图层标注 ⭐ 切图可用 字段，并在末尾汇总"切图实现建议"。凡是标记为"是"的图层，说明设计稿已提供切图，必须直接用 <img> 实现，不要用 CSS 还原。

Step 6: 生成 HTML

使用 generate-html.js 自动生成 HTML 文件，遵循"切图优先"原则：

# 自动生成 index.html（切图优先 + Flexbox 布局 + 切图本地化校验）
node .trae/skills/lanhu-design-to-html/scripts/generate-html.js <design-layers.json> <image-map.json> [output.html]

脚本会：

• 读取 design-layers.json 与 image-map.json，自动构建图层树
• 按 SVG > PNG > DDS 优先级选取切图，用 <img> 引用本地路径（从 image-map.json 查找）
• 无切图的文本用 CSS 文字样式还原，无切图的形状用 CSS div 还原
• 对同组元素进行布局分析，优先使用 Flexbox 排列（自动检测行/列、计算 gap）
• 生成 375×812px 容器的自包含 index.html（CSS 内嵌于 <style>）
• 自动校验 HTML 中是否残留蓝湖 CDN 链接，发现则警告

生成原则（脚本已内置，无需手动处理）：

• 画板尺寸作为容器（通常 375x812px，对应 750x1624rpx）
• 使用绝对定位或 Flexbox 布局

⭐ 切图优先原则（最重要）：

• 凡有切图的元素，直接用 <img> 实现，不要用 CSS 还原。 切图能 100% 还原设计稿视觉效果，CSS 还原常有偏差。
• 切图来源优先级：image.svgUrl（SVG 矢量，最清晰）> image.imageUrl（PNG）> ddsImage.imageUrl（DDS 渲染图）
• 适用所有图层类型，包括：
  • 文本图层有切图（如特殊字体标题）→ 用切图，不用 CSS 文字
  • 形状图层有切图（如带边框的按钮）→ 用切图，不用 CSS div
  • 分组图层有切图（如整组编组导出的复合元素）→ 用整组一张切图，不要拆分实现
  • 图标有切图 → 用切图，不用 CSS/SVG 手绘
• 仅当元素没有切图时，才用 CSS 实现（文本用 CSS 文字样式，形状用 background/border/border-radius）

⭐ 切图本地化（硬性要求）：

• <img src> 一律使用 image-map.json 中的本地相对路径（如 ./assets/images/apeman.png）

• 严禁在 HTML 中出现蓝湖 CDN 链接（lanhu.oss-cn-beijing.aliyuncs.com、alipic.lanhuapp.com、SketchPng、SketchSvg 等）

• 若某切图下载失败，需手动下载补齐后再引用本地路径，不得回退到 CDN 链接

• 无切图的文本样式完整还原（字体、字号、颜色、行高、对齐）

• 无切图的形状使用 CSS 实现（border-radius, background, box-shadow 等）

Step 7: 验证效果

# 启动本地 HTTP 服务器（file:// 协议被浏览器阻止）
python -m http.server 8765

# 在浏览器中打开 HTML
playwright-cli goto "http://localhost:8765/<html-file>"

# 调整视口为移动端尺寸
playwright-cli resize 375 812

# 截图对比
playwright-cli screenshot --filename=preview.png

Platform Switching (微信小程序)

蓝湖支持多平台样式切换。在设计稿标注视图中：

1. 点击任意设计元素，右侧弹出样式信息面板
2. 面板顶部有平台切换器，点击展开下拉菜单
3. 选择 "微信小程序" (rpx) — 所有尺寸自动转为 rpx 单位
4. 不要切换到"代码"视图，保持在"标注"视图

平台选项：

• iOS (pt)
• Android (dp)
• Web (px)
• 微信小程序 (rpx) — 1px = 2rpx
• 像素 (px)

Detailed References

• 蓝湖设计稿分析工作流 — 详细的操作步骤和技巧
• 设计数据解析指南 — Sketch JSON 结构和解析方法
• HTML 实现指南 — 设计稿还原的最佳实践