lanhu-design

Lanhu Design

概要

UI デザインを読み取り、デザイン仕様を分析し、画像アセット情報を取得して、画像アセットを現在のプロジェクトのリソースディレクトリに配置する際は、lanhu CLI を優先して使用します。CLI がインストールされていない場合は、組み込みスクリプトを引き続き使用します。Skill は単独でも実行できます。

実行方法の選択

作業を開始する前に、lanhu コマンドの有無を確認します。

command -v lanhu

• コマンドが存在する場合：まず lanhu auth status --json を実行します。その後は lanhu designs、lanhu image、lanhu specs、lanhu slices、lanhu download、lanhu export を優先して使用し、Agent から呼び出す場合は --json を付けます。
• コマンドが存在しない場合：LANHU_COOKIE を確認し、以下の scripts/*.mjs 互換エントリーポイントを使用します。
• Agent のワークフロー内で CLI を独自にグローバルインストールしないでください。インストールするかどうかは、ユーザーまたはホスト環境が決定します。
• 業務コマンドでブラウザーを自動スキャンしないでください。認証が必要な場合は、ユーザーに lanhu auth の明示的な実行を案内します。制限のあるブラウザー環境では lanhu auth import を使用します。

ツールの詳細な契約、戻り値の構造、再現ルールが必要な場合は、references/lanhu-design-tools.md を読み込みます。 デザイン再現の実装ルール（CSS 値の忠実な保持、DOM 構造のマッピング、画像アセットの命名方針、ディレクトリの選択、倍率のガイドライン）が必要な場合は、references/design-implementation-rules.md を読み込みます。

前提条件

組み込み互換スクリプトは、環境変数 LANHU_COOKIE に依存します。CLI ユーザーは lanhu auth を使用してユーザーレベルの認証情報を管理できます。蓝湖にはこの CLI 向けの公開 OAuth がありません。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.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 をブラウザーで直接レンダリングして照合できるようになります。
4. 画像アセット、アイコン、画像素材をダウンロードする場合は、node scripts/get_design_slices.mjs <url> --design <name> を実行して画像アセット JSON を取得します。一度に指定するデザイン画像名または番号は 1 つだけにしてください。
5. ダウンロード前に、プラットフォームと倍率の希望を確認します。ユーザーが指定しない場合は 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 で提供されている必要があります。同じファイルを複製して複数倍率のリソースに見せかけないでください。
6. 手順 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。

若项目根目录存在 DESIGN.md（或同等职责的设计系统文档），解析规格与落盘代码前必须先读取并遵守其令牌、排版、组件与命名约定；图层级具体数值仍以规格数据为准，冲突时以规格数值保证当前屏还原度并向用户说明取舍。详见 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。 Photoshop 稿（设计 JSON 根节点 type=ps）的切图登记在 assets[]，脚本会自动按图层 id 提取 png_xxxhd/svg 地址并推导多倍率（PS 稿图层像素尺寸为 @2x 基准）。

切图下载前置步骤

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

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）。
• 切图下载数量、失败数量、输出目录已向用户说明。
• 中间产物已按 references/design-implementation-rules.md 的「临时文件清理规则」处理：先列出候选路径并检查引用，取得用户明确确认后再删除；仅保留被代码引用的切图文件。用户未确认时保留文件并报告路径。
• 工作流中未出现认证错误。如果出现过，已引导用户刷新 Cookie 并重试。

交付输出

最终回复简要列出：处理的设计图和 source、新增或修改的代码/资源路径、切图下载成功与失败数量、执行的验证及结果、仍需用户处理的认证或平台适配事项。不要输出 Cookie、带认证参数的完整请求头或不必要的远程资源 URL。