implement-design

name	implement-design
description	将设计稿、标注稿或视觉规格翻译为可上线的应用代码，并保持高保真视觉还原。在用户需要「实现设计」「按稿开发」「还原 UI/组件/页面」、提供设计链接/截图/标注文档，或要求按设计规格搭建界面时使用。若已连接腾讯设计 Ardot MCP，按下文「附录：Ardot MCP」拉取上下文与截图；若用户目标仅为在设计工具内改稿而非交付仓库代码，边界见技能说明。
disable-model-invocation	false

实现设计（Implement Design）

概述

本技能提供一套与设计工具无关的结构化流程：先把「设计意图与可验收的视觉基准」收齐，再映射到本仓库的技术栈与工程约定，最终交付可上线代码并做对照校验。设计可能来自腾讯设计 Ardot（含 MCP）、其它协作平台、导出的静态稿、产品文档中的截图与标注，或组合形式。

技能边界

• 使用本技能： 交付物为用户仓库中的前端代码（页面、组件、样式、资源落盘），且存在可对照的设计或规格依据。
• 不使用本技能： 仅在设计工具里改稿、新建画布节点、或「从代码反推设计稿」——应改用对应工具或团队专用 skill。
• 信息不足时： 先向用户索要画板/组件范围、最新效果图、标注或导出资源；避免在缺少尺寸与颜色的情况下凭想象实现。

设计来源与信息获取

实现前先判断主要设计来源，按需组合下列渠道（可多选）：

来源类型	典型输入	如何获取结构化信息
Ardot（含 MCP）	桌面端已打开的设计文件、用户选区或节点 ID	见下文「附录：Ardot MCP」
协作平台	蓝湖、MasterGo、Pixso、摹客等分享链接	从平台读取标注、切图、下载规范说明；无 API 时以页面标注与导出为准
静态稿	PNG/JPG/WebP、PDF、Sketch 导出	以图像为视觉基准；尺寸可用设计基准宽度（如 750）与标注对照
文档/原型	Axure/墨刀链接、飞书/Confluence 中的 UI 说明	提取文字规格、状态说明，并尽量索取对应效果图
口头描述	仅文字需求	要求补充截图或简单线框，并书面确认验收范围

原则： 能读官方/平台导出与标注就不猜；有 MCP 或开放接口则优先用结构化数据，否则以可下载资源 + 截图为权威组合。

必选工作流

请严格按顺序执行，不要跳过。 各步骤中的具体工具随「设计来源」替换（例如 Ardot 用 MCP，其它来源用导出文件与用户提供的链接）。

步骤 1：确认范围与标识

• 明确要实现的是整页、画板区块还是单个组件，以及是否有多状态（默认 / 悬停 / 禁用 / 空数据等）。
• 对可解析链接（协作平台分享链接等）提取文件 ID、画板 ID、节点 ID 等；Ardot 侧以 MCP 返回的编辑器状态与节点 ID 为准；对静态稿则记录文件名与版本。
• 若存在多个版本稿，以用户指定或标注为「最新」的一版为准。

步骤 2：拉取设计上下文

收集实现所需的结构化信息，包括但不限于：

• 布局（层级、对齐、尺寸、间距、是否弹性布局）
• 字体（家族、字号、字重、行高）
• 颜色与主题（含渐变、描边、阴影）
• 组件结构、变体与交互状态说明
• 响应式或适配规则（若有）

上下文过大或不完整时： 先缩小节点范围或分模块拉取（Ardot 可用 capture_layout 或 batch_read 控制深度后分批读取；其它来源按模块拆分标注或分张导出图）。

步骤 3：建立视觉验收基准

• 取得与实现范围一致的整屏或组件级效果图（截图、导出 PNG、或 MCP 返回的截图），作为后续对照的单一基准。
• 实现过程中应能随时打开该基准做并排比对。

步骤 4：获取并落盘资源

• 下载设计侧提供的图标、插图、SVG、位图；路径与命名遵循项目约定。
• 不要在未确认的情况下新增大型图标类依赖来「凑」视觉——优先使用设计交付的资源。
• 若设计方提供了临时或内网 URL，按项目规范转存到仓库合适目录（如 public 或约定 CDN 流程），避免硬编码易失效地址。

步骤 5：对齐项目规范

将「设计侧输出」转换为本项目的技术栈与约定（本仓库示例：React + Less/CSS Modules、设计稿基准宽度、禁止 gap/grid 等——以 AGENTS.md 与现有代码为准）。

核心原则：

• 设计工具或 MCP 生成的代码（例如部分场景下的 React + Tailwind）仅作结构与数值参考，不要当作本项目的最终代码风格。
• 使用项目偏好的样式方案、设计 token、已有组件（按钮、表单、列表等），避免重复造轮子。
• 路由、状态管理、请求层与错误处理与现有页面保持一致。

步骤 6：高保真还原

• 在尊重项目设计系统的前提下，尽量与验收基准图做到像素级或肉眼不可辨差异。
• 减少魔法数字：能映射到项目 token 的用 token；设计标注与项目 token 冲突时，优先体系统一，可对间距或尺寸做最小微调并可在注释中说明原因。
• 满足无障碍与业务必需的对比度、可点击区域等要求。

步骤 7：对照设计校验

完成前用步骤 3 的基准逐项核对：

• 布局（间距、对齐、宽高比）
• 排版（字体、字号、字重、行高）
• 颜色与渐变、描边、阴影
• 交互状态与空态/错误态（若设计中有）
• 多端或约定断点下的表现（若设计中有）
• 资源清晰、无错位拉伸
• 无障碍与项目 lint 要求

实现规则

组件组织

• 组件与样式文件放在项目规定目录，命名与文件风格与周边文件一致。
• 除非动态值确有必要，否则避免行内样式泛滥。

设计系统集成

• 始终优先复用项目内已有组件与 token。
• 将设计稿中的颜色、字号、间距映射到项目 design token；必要时扩展 token 而非散落硬编码。
• 若需新增可复用组件，放在合适层级并便于他人引用。

代码质量

• 提取重复常量为命名良好的常量或与设计对齐的 token。
• 保持组件可组合；为 props 提供准确 TypeScript 类型。
• 对导出组件按需补充简短说明（项目若普遍使用 JSDoc 则跟随）。

最佳实践

先收齐上下文再写代码

不要凭猜测实现。至少要有：范围 + 结构化规格或标注 + 一张可对齐的效果图。

增量对照

实现过程中多次对照基准图，而不是仅在最后做一次。

记录偏差

因无障碍、性能或技术限制必须偏离设计时，在代码或 PR 说明中简要记录原因。

复用优于重写

新建前先搜索是否已有同类组件；代码库一致性通常优于「脱离体系的逐像素抄稿」。

---

附录：Ardot MCP

当用户在设计侧使用 腾讯设计 Ardot，且编辑器侧已启用并连接 Ardot MCP Server 时，在通用工作流之上采用下列约定。官方文档随版本更新，以 Ardot MCP 简介 为准。

前置条件

• 使用支持 MCP 的 AI 编辑器（如 Cursor 等），并在 Ardot 内完成 MCP 配置与连接校验。
• 推荐在 macOS Ardot 桌面端打开目标设计文件（MCP 优先支持桌面端；Web 端能力以官方说明为准）。
• 用户需明确要实现的大致范围（画板 / 节点）；必要时先在 Ardot 中选中对应图层，便于 fetch_editor_state 与截图对齐。

设计稿转代码（推荐调用顺序）

与官方「设计稿转代码」场景一致，建议按序组合工具，映射到本技能步骤 1～3：

1. fetch_editor_state — 获取当前编辑器状态（活跃画布、用户选区、打开文件等），作为任务起点。
2. capture_screenshot — 对指定节点或区域截图，作为步骤 3 的视觉验收基准。
3. batch_read — 批量读取节点（支持按 name/type 正则、按节点 ID 精确查找；控制返回深度与详细程度），补齐步骤 2 的布局与属性。
4. fetch_variables（可选）— 读取文件中的设计变量（颜色、间距、字号等），便于映射到项目 token。
5. fetch_guidelines（可选）— 获取 Ardot 设计规范指引；若需贴近官方代码生成建议，可按文档选择主题（如 mobile-app、code 等），仍须在步骤 5 转换为本仓库技术栈，不可照搬为最终工程风格。

之后进入本技能步骤 4～7（资源落盘、对齐项目规范、还原与校验）。

其它常用工具（按需）

类别	工具	说明（摘自官方文档）
查询	capture_layout	布局结构树；可筛仅返回存在重叠、裁剪等布局问题的节点
设计系统	apply_variables	创建或更新设计变量集合（与「改稿」相关，注意本技能以代码交付为主）
编辑	batch_edit、locate_available_space	批量设计操作、查找空白区域；用于 AI 辅助改稿场景
辅助	get_available_fonts	当前环境可用字体列表
辅助	export_to_code	将节点导出为前端代码（文档标注即将推出，以官方进度为准）

batch_edit 注意： 单次建议不超过 25 个操作；Insert/Copy/Replace 等需按官方要求绑定名；不要对刚复制节点的子节点立即 Update（子节点 ID 会变化）。详见 Ardot MCP 文档。

截图异常

若 capture_screenshot 为空或不完整：确认 nodeId 对应节点在画布可见范围内，且 Frame 内有实际内容（空容器无意义截图）。仍以官方 FAQ 为准。

资源与代码风格

• 从 batch_read 与截图中识别图标、插图需求；落盘规则仍遵循本技能步骤 4，避免随意引入与稿面无关的图标依赖。
• Ardot 或 fetch_guidelines 给出的代码片段仅作结构与数值参考，必须经步骤 5 对齐本项目约定。

延伸阅读

• Ardot MCP Server 简介（工具列表、快速开始、常见问题与 Roadmap）

---

常见问题与处理

设计信息不完整

处理： 列出缺失项（尺寸、颜色、状态、资源），请用户补充链接、导出图或标注；缩小首期交付范围到已明确部分。

实现后与效果图不一致

处理： 与步骤 3 的基准并排对比；回到步骤 2 核对数值与层级，检查是否误用了旧稿。

资源无法加载或地址失效

处理： 确认是否需登录或内网；将资源按项目规范下载并提交到仓库或走发布资源流程。

设计标注与项目 token 不一致

处理： 优先使用项目 token 保持体系统一，必要时做最小视觉补偿并在注释或说明中注明。

Ardot MCP 连接失败或工具无响应

处理： 确认 Ardot 桌面端已打开并已加载设计文件；在 Ardot 内检查 MCP 配置与编辑器开关；重启 AI 助手以重建连接。详见 Ardot MCP 常见问题。

设计实现工作流的价值

对设计方：有明确验收基准，结果可预期。
对开发方：减少猜稿与返工。
对团队：产出风格统一，并维护设计系统与代码库的一致性。

遵循本工作流，可按不同设计来源用同一套节奏稳定落地界面。