lanhu-design

name

lanhu-design

description

Use this skill when working with Lanhu UI design drafts: get UI design image lists, analyze UI design images, read design HTML/CSS specs, extract design tokens, get slice/icon/asset download information, batch download slices, or implement UI from Lanhu design handoff. Trigger on Chinese or English requests mentioning 蓝湖, Lanhu, UI设计稿, 设计图, 视觉稿, 切图, 图标, 素材, design handoff, design slices, or Lanhu design tools.

Lanhu Design

概览

通过内置脚本直接调用蓝湖 HTTP API，读取 UI 设计稿、分析设计规格、获取切图信息，并把切图落到当前项目的资源目录。

需要详细工具契约、返回结构和还原规则时，读取 references/lanhu-design-tools.md。 需要设计还原实现规则（CSS 值保真、DOM 结构映射、切图命名策略、目录选择、倍率指引）时，读取 references/design-implementation-rules.md。

前置条件

所有脚本依赖 LANHU_COOKIE 环境变量。蓝湖没有公开 API 或 OAuth，脚本通过浏览器会话 Cookie 模拟登录用户请求。Cookie 缺失或过期时，脚本调用报认证错误。

获取 Cookie 的步骤：

1. 在浏览器打开 https://lanhuapp.com 并登录。
2. 按 F12（macOS 为 Cmd+Option+I）打开开发者工具，切换到 Network 标签页。
3. 刷新页面，在请求列表中点击任意 lanhuapp.com 请求。
4. 在 Request Headers 中找到 Cookie 字段，复制完整值（通常 200–500 字符）。
5. 将该值设置为环境变量 LANHU_COOKIE。

注意事项：

• Cookie 会过期（通常数天到数周），出现认证错误时需重新获取。
• Cookie 是敏感凭据，不要提交到版本控制或输出给用户。
• 所有脚本需要 Node.js >= 18（使用原生 fetch）。

脚本列表

脚本	用途
scripts/get_designs.mjs	列出蓝湖项目的设计图
scripts/get_design_specs.mjs	获取设计规格 HTML+CSS（主路径：DDS Schema；降级：Sketch JSON）
scripts/download_design_images.mjs	下载设计图原图到本地目录（视觉校验用）
scripts/get_design_slices.mjs	获取单个设计图的切图/素材元数据
scripts/download_slices.mjs	从切图 JSON 批量下载切图文件
scripts/lanhu-client.mjs	共享 HTTP 客户端模块（被上述脚本引用，不直接运行）
scripts/design-converter.mjs	纯转换模块（被 get_design_specs.mjs 引用，不直接运行）

工作流

0. 确认 LANHU_COOKIE 环境变量已设置。如果首次运行脚本返回认证错误，提示用户检查 Cookie 是否已配置且未过期，参考上方「前置条件」重新获取。不要在认证失败后继续调用其他脚本。
1. 先判断用户给的是蓝湖 UI 设计项目链接，而不是需求文档链接。UI 设计项目通常是 https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=xxx，必须有 pid，tid 可选；不要把带 docId 的 PRD 链接当设计稿处理。
2. 运行 node scripts/get_designs.mjs <url> 获取设计图列表。后续分析和切图都以这个列表里的 index、name、id 为准。
3. 如果设计图很多，先让用户指定范围；如果用户已经明确说"全部"，再用 all。不要默认一次分析大量设计图。
4. 【还原 UI 的强制前置步骤】查看或实现 UI 前，必须先下载并用 Read 工具查看设计图原图：运行 node scripts/download_design_images.mjs <url> --designs <names> --output <dir> 下载原图，--designs 支持序号（逗号分隔）、精确名称或 all，下载后用 Read 工具实际查看。不要跳过看图直接基于 HTML 规格还原——原图是布局、层级、视觉效果的最终核对依据，source="sketch" 降级时更是布局结构的主力参考。 4.5. 获取设计规格 HTML+CSS：运行 node scripts/get_design_specs.mjs <url> --design <name_or_index> 获取规格。返回的 source 字段决定数据权威性，必须先判断：
   • source="dds"：从 DDS Schema 生成的高精度 flex 布局 HTML+CSS，html 字段是颜色、字号、间距、渐变、圆角、布局等所有参数的权威来源，直接复用、不得主观修改；原图用于核对布局是否错位。
   • source="sketch"：降级路径，html 仅为绝对定位的元素清单，不可当作布局权威。此时以原图视觉为布局主力参考，以 design_tokens / sketch_annotations 的原始数值为精确数值来源。
   • source="sketch" 时，HTML 元素带 data-css，返回还包含 design_scale 和 layer_css_annotations，用于逐图层核对路径、文本、切图和 CSS 标注。
   • image_url_mapping 列出需要下载的图片资源映射表。若返回 dds_error，说明已降级到 sketch，应更依赖原图。
   • 返回的 source_guidance 字段是针对当前 source 的数据权威性指引，直接按它执行。
   • 加 --output <dir> --download-images 可在保存 HTML 的同时自动把引用图片下载到 <dir>/assets/slices/，使保存的 HTML 可直接在浏览器渲染核对。
5. 下载切图、图标、图片素材时，运行 node scripts/get_design_slices.mjs <url> --design <name> 获取切图 JSON。单次只传一个设计图名称或序号。
6. 下载前确认平台和倍率偏好。用户不指定时推荐 Web 2x，但仍要明确说明选择；常用键包括 1x、2x、3x、ios_1x、ios_2x、ios_3x、android_mdpi、android_hdpi、android_xhdpi、android_xxhdpi、android_xxxhdpi。除 2x 可回退到 download_url 外，其它倍率必须由切图 JSON 的 scale_urls 提供，不要复制同一文件伪造成多倍率资源。
7. 将步骤 5 的切图 JSON 输出保存为文件，然后运行 node scripts/download_slices.mjs <json_file> --output <dir> --scale <scale> 批量下载。识别当前项目资源目录和命名风格，执行后核对文件数量和失败列表。

设计还原规则

完整规则见 references/design-implementation-rules.md。以下是必须遵守的核心要求。

数据来源优先级（按 get_design_specs.mjs 返回的 source 分级）

还原前必须先看 source 字段，不同来源的权威性完全不同：

source="dds"（高保真，HTML 权威）：

1. html 字段：颜色、尺寸、间距、字体、圆角、渐变、定位、布局结构的权威来源。直接复制精确的 CSS 属性值，不得修改。
2. design_tokens 字段：补充 HTML 中可能被合并的高风险视觉信息（复合渐变、非均匀圆角、阴影、opacity<100）。
3. 设计图原图：用于核对布局是否错位、元素是否齐全，不覆盖 HTML 数值。
4. 切图元数据（get_design_slices.mjs）：补充 fills、borders、opacity、rotation、text_style、shadows、border_radius。

source="sketch"（降级，原图为布局主力）：

1. 设计图原图：布局结构、层级关系、视觉效果的主力参考。html 是扁平的绝对定位元素清单，不能当作布局权威，仅用于核对元素是否齐全。
2. design_tokens / sketch_annotations 字段：颜色、字号、间距、圆角、阴影等精确数值的权威来源。
3. html 字段：仅作元素清单和绝对定位参考，布局意图需结合原图重建。
4. 切图元数据：同上，补充视觉细节。

禁止修改 CSS 值

• 不要转换色值格式（rgba() ↔ hex 保持原样）。
• 不要四舍五入或简化数值（如 0.30000001192092896 保持原样）。
• 不要把 linear-gradient 简化成纯色。
• 不要调整 font-family 顺序或删除 fallback 字体。
• 不要把 margin/padding 取整为"干净"的数字。
• 不要用 SVG、CSS shape、emoji 或占位图替换切图。
• 不要省略任何可见的设计元素。
• 不要在最终代码中保留蓝湖远程 CDN URL。

DOM 结构映射

HTML 的 class 名称表达布局意图，需转译为目标框架组件，同时保持 CSS 值不变：

• flex-row → 水平排列（React: display:flex，Flutter: Row()，SwiftUI: HStack）
• flex-col → 垂直排列（React: flex-direction:column，Flutter: Column()，SwiftUI: VStack）
• justify-between → 两端对齐（space-between / MainAxisAlignment.spaceBetween）
• relative / absolute → 定位层叠（Flutter: Stack + Positioned，SwiftUI: ZStack）

详细映射表见 references/design-implementation-rules.md。

框架检测与代码生成

实现 UI 前先检测项目类型（读取 package.json、pubspec.yaml、build.gradle、Podfile 等），生成匹配框架的代码（React JSX、Vue SFC、Flutter Widget、SwiftUI View、Android Compose 等）。CSS 属性需按平台做单位映射（px→dp/pt），但不能改变数值精度。未检测到框架时默认生成纯 HTML。各框架的 CSS 属性映射表和资源引用方式见 references/design-implementation-rules.md。

生成后保真审计

代码生成后必须逐属性对照设计规格 HTML+CSS 执行保真检查，覆盖 10 项：尺寸约束、裁剪、色值、渐变、绝对定位、字体、间距、图片资源、元素完整性、无远程 URL。对每个差异标注是平台适配还是错误，错误必须修正后交付。完整清单见 references/design-implementation-rules.md。

切图下载

从 get_design_slices.mjs 保存返回结果为 JSON 后，可运行：

node scripts/download_slices.mjs slices.json --output ./src/assets/images/slices/home --scale 2x

常用参数：

• --scale 2x：下载 Web 2x，文件名后缀默认 @2x。
• --scale ios-all：下载 iOS 1x/@2x/@3x。
• --scale android-all：下载 Android 全套并放入 mipmap-* 子目录。
• --name-map names.json：提供 {slice_id_or_name_or_layer_path: "semantic_name"}，覆盖自动文件名。
• --referer https://lanhuapp.com/：需要带 Referer 时使用。

脚本只负责稳定下载和基础去重。语义化命名应优先结合当前项目已有命名规范处理。 全套倍率依赖 scale_urls 中的真实多倍率地址；缺失时脚本会报错而不是复制 download_url。

切图下载前置步骤

下载切图前，按以下顺序准备：

1. 识别项目类型：检查 package.json、pubspec.yaml、*.xcodeproj、build.gradle 等标志文件，判断 React/Vue/Flutter/iOS/Android。
2. 确定输出目录：用户指定 > 项目已有资源目录 > 通用默认路径。详细规则见 references/design-implementation-rules.md。
3. 确认倍率：用户不指定时推荐 Web 2x，但必须明确告知选择。
4. 准备命名映射：根据切图的 layer_path、parent_name 生成语义化英文文件名（icon_、bg_、btn_ 等前缀），沿用项目已有命名风格。命名策略详见 references/design-implementation-rules.md。

完成检查

交付前确认：

• 已先运行 get_designs.mjs 并基于列表匹配目标设计图。
• 还原 UI 前已下载并用 Read 工具实际查看过设计图原图。
• UI 实现已按 source 分级核对：dds 以 HTML+CSS 为权威，sketch 以原图布局 + design_tokens 数值为主，没有用设计截图主观改 DDS 的精确值。
• 已执行生成后保真审计（10 项清单），所有错误已修正，仅保留合理的平台适配差异。
• 生成代码匹配检测到的项目框架，遵循项目已有约定（命名、目录、样式方案）。
• 所有远程图片/切图已下载为本地资源，代码中没有蓝湖 CDN URL。
• 图片资源使用目标框架约定的引用方式（如 React import、Flutter AssetImage）。
• 切图下载数量、失败数量、输出目录已向用户说明。
• 工作流中未出现认证错误。如果出现过，已引导用户刷新 Cookie 并重试。