mcpField
D
design-to-code

design-to-code

github.com/atharvsinh-codez设计与 UI143124 次安装2 周前更新
代码仓库

关于 design-to-code

design-to-code 是指导将网站视觉参考还原为可维护前端代码的技能,适用于网站重建、视觉设计与界面修复。它强调依据参考证据确定设计,并涵盖响应式实现、交互还原和渲染对比。

主要功能

  1. 01选择参考模式与界面类型
  2. 02分析视觉来源与项目结构
  3. 03制定视觉规范与资源计划
  4. 04实现响应式界面与交互
  5. 05通过渲染对比验证结果

适用场景

  1. 01依据截图重建网页
  2. 02扩展现有视觉规范到新页面
  3. 03修复响应式或视觉回归问题

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/atharvsinh-codez/skills --skill design-to-code

安装后在 Claude Code 中输入/design-to-code确认已加载。

包含的文件

除 SKILL.md 外,安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
art-direction.md
evaluations.md
interface-craft.md
motion.md
reference-forensics.md
typography-and-fonts.md
verification.md

详细介绍

从设计到代码

重建或进行艺术指导,打造网站,然后将其实现为真实、易于维护的前端代码。

  • **是:**视觉来源选择、设计取证、必要时的艺术指导、自适应实现、生产级素材制作、交互还原,以及渲染结果对比。
  • **不是:**把截图贴在页面背景后面、将界面压平成一张图片、在用户要求实现时只提供审查报告,或擅自将权威参考改成自己偏好的品牌风格。

产品行为决策、长篇文案策略、深入 SEO 工作,以及独立的动效或字体审查,都应限定在请求范围内。实现必要部分,但不要悄悄把视觉重建扩展成无关的产品策略。

行动前先分流

选择一种来源模式和一种界面类型。在工作笔记中记录两者。

来源模式
模式适用情形真相来源
参考重建截图、画面、模型图或实时状态定义了目标可观察到的参考证据
从零开始的艺术指导没有精确的构图,且视觉质量是重点已批准的需求说明和生成的设计参考
混合扩展参考定义了视觉语言,但缺少所需的版块、路由、状态或断点参考中不变的要素,以及生成的缺失界面
变体探索用户要求先提供选项,再做选择内容和约束相同的受控替代方案
改造或修复任务涉及自适应修复、深色模式、组件清理或视觉回归修正现有实现和目标证据
语义骨架用户明确只要求无样式的结构可见内容和原生语义

在参考重建模式中,绝不要生成替代页面概念。只有在从零开始或明确授权的混合工作中,生成的概念才能成为权威依据。

界面类型
  • **营销或品牌:**优化层级、叙事、品牌识别、佐证内容和一条清晰的转化路径。
  • **产品或运营:**优化任务完成效率、可扫读性、稳定的控件、清晰适度的信息密度、状态覆盖范围,以及可靠的数据交互。
  • **混合产品:**将面向公众的获客页面视为营销界面,将经过身份验证的工作界面视为产品界面。不要把营销装饰混入仪表板。

参考和用户的明确要求优先于界面类型的默认规则。

加载条件式操作指南

仅阅读适用的参考文档,且每份文档都直接从本文件中读取:

  • 对于从零开始的艺术指导、混合扩展、变体探索,或没有权威构图时要求打造全新 Awwwards 级视觉方向的任务,请阅读 art-direction.md。
  • 对于需要系统提取信息并建立证据清单的截图、Figma、实时网站、多视口或视觉修复工作,请阅读 reference-forensics.md。
  • 对于所有涉及识别、获取、选择、替换或加载字体的构建工作,请阅读 typography-and-fonts.md。
  • 对于任何添加、匹配、调整或移除交互与动效的构建工作,请阅读 motion.md。
  • 对于非简单的营销或产品界面、自适应重组、深色模式、组件或状态设计、字体排印、材质或复杂控件,请阅读 interface-craft.md。
  • 对于所有非简单的构建工作,以及任何声称输出精准、像素级接近、可用于生产或达到 Awwwards 级别的情况,请阅读 verification.md。
  • 仅在测试或改进此技能时阅读 evaluations.md,不要在常规项目执行期间阅读。

进度清单

复制并维护此清单,用于非简单任务:

Design-to-code progress:
- [ ] Select source mode and surface track
- [ ] Confirm scope, rights, routes, states, and target viewports
- [ ] Inspect every reference and the existing project
- [ ] Record observed, inferred, and substituted decisions
- [ ] Lock the visual system, content map, and asset plan
- [ ] Lock the font plan: identify, license, substitute, or use the Geist Serif default
- [ ] Enforce SVG-only iconography and remove every emoji
- [ ] Implement semantic structure and major geometry
- [ ] Integrate final assets, responsive rules, states, and motion
- [ ] Run accessibility, performance, and functional checks
- [ ] Complete rendered comparison and correction passes
- [ ] Run project validation and issue a readiness verdict

权威性与证据优先级

按以下顺序解决冲突:

  1. 用户明确提出的要求和更正。
  2. 经授权提供的内容和素材。
  3. 权威参考中可观察到的像素和行为。
  4. 其他视口、状态、路由、主题或动效参考。
  5. 现有产品设计系统、行为和代码库约定。
  6. 模式和界面轨道的默认设置。
  7. 最小且可撤销的推断。

对重要决策标注:

  • 观察所得: 直接可见或可测量。
  • 推断所得: 缺乏证据时,根据关联关系或约定推导。
  • 替代处理: 因权利限制、素材缺失、字体不可用、无障碍要求或技术限制而有意替换。

不要将推断或替代处理说成完全匹配。

明确任务

确定:

  • 目标路由、组件、区块或路由集合。
  • 参考文件、URL、视口、设备像素比、主题、区域设置和可见状态。
  • 桌面、平板、移动端、短视口高度和超宽视口下的必要表现。
  • 所需的表单、菜单、对话框、轮播、导航、数据和滚动行为。
  • 提供的文案、徽标、字体、图标、图像、视频、数据和设计系统基础组件。
  • 现有框架、交付环境、浏览器支持、SEO、无障碍和性能限制。
  • 哪些元素必须具备实际功能,而不只是视觉呈现。
  • 是否已获授权,可精确复现第三方品牌、文案、图像和交互。

只有当答案会影响架构、权利、核心行为或权威来源时,才提出一个聚焦的问题。否则,选择保守且可撤销的默认方案并继续。

对于登录、结账、付款、账户恢复、身份验证或其他敏感流程,只实现获授权的行为。绝不创建具有欺骗性的凭据收集界面或冒充界面。除非用户提供了获授权的后端,否则提交操作应保持为无实际作用或明确模拟的状态。

编辑前检查项目

  • 阅读代码库说明并检查工作区。保留无关的现有修改。
  • 检查清单文件、锁文件、脚本、框架配置、路由、布局、共享组件、样式系统、设计令牌、字体、图标、素材、测试和构建流程。
  • 优先复用已有基础组件,再创建新组件。
  • 在可行时运行当前预览或基线检查,以便区分已有故障。
  • 除非确有必要,否则保留现有框架、包管理器、锁文件、渲染模型和约定。
  • 只有在比现有代码或浏览器原生功能更能满足实际需求时,才添加依赖。
  • 使用项目实际提供的命令;不要臆造通用验证命令。

如果存在 .openai/hosting.json,请阅读并遵循 sites-building 技能。按其要求完成检出、预览、检查点和验证流程。

对于新项目,遵循用户指定的技术栈。若未指定,则选择能够支持所需路由和交互的最简易维护方案。

编码前检查视觉参考

使用可用的图像查看功能检查每张提供的图片。切勿仅凭文件名、OCR、替代文本或文字摘要进行判断。

对于公开的实时参考,请阅读并遵循 control-browser 技能。捕捉可见行为,但不要复制专有源代码,也不要导入脚本、跟踪器、Cookie、分析数据、机密或私有数据。切勿绕过身份验证、付费墙、反机器人机制或访问限制。

至少提取以下信息:

  • 视口、画布、首屏边界、容器、页边距、列、分区边界、对齐锚点、重叠、裁切和层级顺序。
  • 字体系列、实际字重和样式、字号、行高、字距、文本宽度、换行、视觉对齐和回退行为。使用 typography-and-fonts.md 识别字体系列。
  • 色彩角色、渐变、边框、圆角、阴影、纹理、模糊、透明度、材质和纵深。
  • 图片用途、宽高比、裁切、焦点、蒙版、边框、留白和响应式处理方式。
  • 页眉、导航、内容层级、控件、表单、卡片、列表、页脚、粘性区域和可见状态。
  • 动效触发条件、时长、缓动、延迟、方向、顺序、中断方式和减少动态效果时的行为。

将一张截图视为某条路由、某个视口、某种状态、某个主题和某个滚动位置的单次采样,而非完整规范。

对于复杂项目,使用 reference-forensics.md 创建证据台账和参考清单。

锁定保真度约定

深入实现前,记录以下内容:

  • 一句话视觉主旨。
  • 规范文案和内容层级。
  • 语义区域和组件映射。
  • 容器、网格、断点和分区节奏规则。
  • 字体级别、字体方案、间距网格、圆角、边框、纵深和语义色彩角色。
  • 资源清单、版权、生产路径、裁切和生成需求。
  • 各分区的响应式转换方式。
  • 交互、状态和动效要求。
  • 已观察到的事实、推断的行为、替代方案、风险和阻碍。

精确重建时,根据证据制定此约定。全新项目中,使用 art-direction.md 有意制定此约定。

尽早为重复使用的颜色、字体排版、间距、容器、圆角、边框、阴影、层级和动效创建设计令牌。保留有意为之的独特艺术指导数值,不要强行将每个尺寸都纳入通用尺度。

在两个不同角色中使用 imagegen

当缺少的自定义栅格图像会对设计产生重大影响时,请阅读并遵循 imagegen 技能。

  • 艺术指导参考图: 一幅临时使用、尺寸较大且清晰易读的构图,用于确定或检查布局、层级、字体关系、间距、媒体处理方式和节奏。
  • 生产资源: 一幅可独立使用且适合随项目交付的图像,例如主视觉艺术、摄影、插画、纹理、产品渲染图、氛围背景或透明底抠图。

艺术指导参考图可以呈现完整版块,但绝不能作为页面、扁平化 UI 或整页背景随项目交付。生产资源不得包含页面文案、按钮、导航、界面框架、浏览器/设备边框、徽标或水印,除非这些元素确实属于作品内容。

在绿地模式下,先确定规范文案,再生成图像。生成的文字仅作为空间布局参考;经批准的文案应以真实 HTML 呈现。

对于每个生成的生产资源:

  • 定义用途、宽高比、最大渲染尺寸、裁剪方式、焦点、留白、配色以及响应式变体。
  • 检查结果,并每次针对一个不匹配之处进行迭代。
  • 先将选定资源以稳定且描述性明确的名称保存在项目中,再引用它。
  • 优化交付方式,并预留固有尺寸。
  • 记录来源或生成状态、使用权、尺寸、焦点、裁剪方式和替代文本决策。

优先使用现有的授权资源。普通图标、徽标、图表、简单几何图形和仓库原生 SVG 系统应以代码实现。不得仿冒受保护的标志,也不得使用生成图像虚假呈现真实人物、产品、地点、事件或结果。

关于绿地版块参考图的生成和一致性规则,请遵循 art-direction.md。

严格要求仅使用 SVG 图标,并且禁止使用 emoji

这是所有网站实现的严格要求,包括精确还原参考设计:

  • 所有设计界面中的图标都必须以 SVG 呈现。优先使用项目现有的 SVG 图标库;否则创建匹配的内联 SVG、导入 .svg、精灵图符号或 SVG 组件。
  • 网站输出的任何位置都不得使用 emoji,包括文案、导航、按钮、标题、项目符号、标签、徽章、状态、提醒、空状态、占位符、光标、元数据或装饰。
  • 不得使用 Unicode 象形文字或符号、图标字体、文本字形、CSS 伪元素字形、PNG/JPG/WebP 图标或生成的栅格图像来代替图标。
  • 如果权威参考或提供的文案中包含 emoji,请用语义最贴切的 SVG 图标或清晰的纯文本替换。即使因此与参考产生细微的视觉差异,也必须记录这项必要的替换。
  • 不得使用 imagegen 生成图标。图标几何形状应以代码实现,保持清晰、可主题化且可复用。
  • 统一图标系列的视图框、视觉尺寸、描边/填充风格、粗细、端点、连接方式和方向性。图标应继承状态或主题颜色时,请使用 currentColor。
  • 对辅助技术隐藏装饰性 SVG。仅包含图标的控件应在控件上设置无障碍名称,不得只用 SVG 的 <title> 作为标签。
  • 宣布就绪前,请确认渲染的路由中不再包含 emoji、Unicode 图标替代符、图标字体或栅格图标。

此规则适用于图标,不适用于普通摄影作品或获准使用的非图标品牌图像。

由宏观到微观地实现

  1. 确定路由、语义地标、文档顺序、背景、页面外壳、容器、网格和主要区块的几何布局。
  2. 匹配页眉、首屏、主视觉、内容层级和主要操作。
  3. 匹配字体、字形指标、内容宽度和换行。
  4. 使用现有基元构建重复组件和功能状态。
  5. 集成最终素材,并调整裁剪、焦点、遮罩和边框。
  6. 添加表面、边框、层次感、图标、细节和有意设计的装饰。
  7. 添加响应式变换、交互和动效。
  8. 完成首屏以下的内容、次要状态、验证和清理。

使用语义化 HTML、原生元素、自然文档流、网格、弹性布局和内在尺寸。仅在确实需要叠加层和艺术指导层时使用绝对定位。切勿将整个页面实现为坐标图、巨型 SVG 描摹、画布位图或一堆绝对定位元素。

将排版视为几何布局。参阅 typography-and-fonts.md 识别或选择字体;找不到合适字体时,使用 Geist Serif(或在需要清晰的无衬线或等宽字体时使用 Geist Sans/Mono),而不是框架默认字体。在添加偏移或脆弱的 <br> 元素之前,先确定字体系列、实际可用的字重和样式、可变字体轴、回退字体指标、宽度、行高和字距。对于会变化的计数、价格和指标,在视觉抖动很重要时使用等宽数字。

将营销页面参考中的嵌入式产品截图、设备边框、浏览器模型、图表和仪表板视为媒体,除非请求的目标范围明确包括重建其内部界面。

保持组件和状态完整性

  • 为重复结构、行为负责人或稳定的视觉基元提取组件,而不是为每个包装元素都提取组件。
  • 在调用位置保留外部边距和页面布局。
  • 在可复用视觉组件上支持项目常用的类名或样式覆盖机制。
  • 标签、计数、悬停样式、验证或加载文案发生变化时,保持尺寸稳定。
  • 出现可恢复的错误时保留输入值。
  • 防止意外重复提交和过时的异步更新。
  • 在对话框和破坏性操作确认后恢复焦点。
  • 为乐观操作和破坏性操作提供回滚或明确的恢复方式。
  • 视情况涵盖默认、悬停、焦点、按下、选中、禁用、加载、空、错误、成功、权限、离线、破坏性操作、长内容、本地化和 RTL 状态。

详细的营销/产品、表面、排版、响应式、状态和特定功能规则,请参阅 interface-craft.md。

以响应式方式重新组织

将移动端视为经过精心设计的布局,而不是按比例缩小的桌面版。

  • 在内容或布局无法正常呈现的位置选择断点。
  • 为每个区块定义其变换方式:保留、重排、折叠、调整顺序、裁剪、简化或隐藏。
  • 尽量使用一套逻辑 DOM;没有语义上的理由时,不要重复桌面端和移动端的 DOM 树。
  • 适当使用流式容器、clamp()、内在尺寸和组件级容器查询。
  • 将侧边栏和密集导航折叠为易于访问的移动端模式,而不是挤压各列。
  • 保持焦点位置、内容优先级、逻辑阅读顺序和实用的触控目标。
  • 在每个断点的前后立即进行测试,并消除意外的水平溢出。
  • 应用 interface-craft.md 中的移动平台层:viewport meta、svh/dvh、安全区域、16px 输入框、受限悬停和无点击闪烁。

先验证提供的确切宽度,然后验证有代表性的窄屏、平板、桌面、中间尺寸、短高度和超宽视图。遵循 interface-craft.md 中的详细工程规则。

匹配交互与动效

对于任何添加、匹配、调整或移除动效的构建,请阅读 motion.md。

  • 优先匹配观察到的行为,不要凭空添加效果。只有在证据不足时才采用默认设置。
  • 判断是否确实需要动画:键盘触发的操作或每天发生 100 次以上的操作绝不添加动画;每个动画都必须有明确目的。
  • 使用成本最低的工具:状态变化使用 CSS transitions,进入效果使用 @starting-style,页面繁忙时的动效使用 CSS 或 WAAPI;只有手势、布局和退出动画才使用弹簧库。
  • 对 transform 和 opacity 添加动画。绝不使用 transition: all 或 scale(0) 入场效果。
  • 进入和退出使用 ease-out,绝不在 UI 上使用 ease-in。产品 UI 动效时长控制在 300ms 以内,且退出速度要快于进入。
  • 弹出层和菜单的 transform-origin 应设在触发点;模态框应保持居中。
  • 仅在 (hover: hover) and (pointer: fine) 条件下启用悬停动效,并为触屏提供 :active 反馈。
  • 即使动画设置或 JavaScript 失效,也要确保初始内容可见。
  • 为减少动态效果提供更柔和而非完全取消的方案。

仅当自定义光标、视差、平滑滚动、WebGL、磁性控件和页面转场有参考依据或视觉设计理念支持,且符合性能预算时,才添加这些效果。

保障无障碍、性能和 SEO 基础

  • 在适用情况下以 WCAG 2.2 AA 为目标:地标、标题、原生控件、标签、无障碍名称、合乎逻辑的焦点顺序、可见焦点、对比度、缩放/重排、触控、减少动态效果,以及有意义的替代方案。
  • 不要仅通过颜色、悬停、动画或图像来传达信息。
  • 预留媒体尺寸,尽量减少布局偏移,优化响应式图像,并优先加载可能最大的内容绘制(LCP)资源。
  • 仅加载所需的字体系列、实际字重、样式和子集;避免伪粗体/斜体以及造成干扰的字体切换。
  • 避免不必要的客户端 hydration、阻塞脚本、超大媒体文件和持续消耗大量资源的效果。
  • 为公开路由保留标题、元数据、标题层级、链接、可抓取内容、深层链接,以及错误页面的健壮性。
  • 确保控制台没有新增的运行时错误、hydration 警告、缺失的 key 或加载失败的本地资源。

执行强制渲染验证

不要仅凭构建成功就宣告完成。

对于每个权威目标:

  1. 固定路由、视口、设备像素比、浏览器、缩放比例、字体、区域设置、主题、数据、状态、滚动位置和动画。
  2. 在与参考相同的条件下捕获实现效果。
  3. 并排比较整页和重要组件的裁剪图。
  4. 在可用时使用叠加、闪烁或图像差异证据。
  5. 按以下顺序修复差异:内容/状态、几何布局、排版、主要资源、间距、颜色/材质、细节、交互、动效。
  6. 先修复根本原因,再处理局部症状,然后重新捕获。
  7. 对每个非简单重建至少完成两轮有针对性的修正。
  8. 验证响应式插值、状态、键盘、触控、减少动态效果、控制台/网络,以及生产构建。

请阅读 verification.md,了解比较清单、功能门槛、浏览器矩阵、就绪判定和证据要求。

反合理化关卡

走捷径的想法必须采取的措施
“截图一目了然”以足够清晰的细节检查截图,并在编辑前记录证据。
“用图像生成就能提升质感”仅在全新设计/混合模式下生成概念稿;绝不替换权威参考。
“做一张完整长图更快”如果文字、控件或间距变得难以辨认,就拆分成较大的分区参考图。
“这个裁剪已经够好了”可用裁剪图进行检查;如果某个区域不清晰,应重新渲染该区域,再将其作为权威参考。
“构建通过了”渲染、比较、修正并留存证据。
“移动端直接堆叠就行”为每个区块定义并测试有意设计的转换方式。
“用卡片分组更方便”使用满足需求的最轻量边界;每张卡片都必须有合理依据。
“这个字体已经够接近了”在参考视口下比较换行位置,并记录替代方案。
“动效能让它显得更有质感”先通过频率和用途关卡;无法说明用途的动效一律移除。
“设备模拟里的效果看起来没问题”除非在真实设备上测试,否则应将仅限硬件的行为标记为未经验证。
“这个素材只是装饰”仍须验证性能、对比度、响应式裁剪、动效和无障碍处理。

拒绝常见问题

  • 用截图充当页面、将文字扁平化、使用整页栅格图或坐标映射布局,或通过隐藏溢出掩盖缺陷。
  • 通用模板、重复的区块公式、卡片堆叠、嵌套方框、巨大的圆角容器、装饰性胶囊标签和伪造的系统标签。
  • 默认的蓝紫色光晕样式、不加区分地使用玻璃拟态、虚构指标、编造的用户评价、合作伙伴标志或产品声明。
  • 占位文案、通用的转型措辞、无关的图库图片、网站输出中的任何 emoji、非 SVG 图标替代品和无效控件。
  • 未经许可从线上网站复制字体文件、未经选择就采用框架默认字体、键盘操作时触发动效,以及每个区块滚动进入时都淡入。
  • 静默替换字体、随意换行、随机设置断点、遗漏状态、仅悬停可用且无法访问的交互,以及没有减少动效方案的动效。
  • 用拥挤的实现节奏取代参考中的宽松节奏,或将有辨识度的区块简化成通用行布局。

仅当用户或权威参考没有要求采用这些模式时,才应用这些反通用规则。

就绪判定

最终只能给出以下一种判定:

  • READY: 所需的还原度、行为、响应式设计、无障碍、检查和证据均通过。
  • READY WITH SUBSTITUTIONS: 所有关卡均通过,但仍存在已记录且获准的替代方案。
  • NOT READY: 仍有必需的路由、状态、交互或检查未完成,或存在明显的视觉差异。
  • UNVERIFIED: 实现已完成,但无法进行浏览器比较或获取其他必需的证据来源。

未经验证的结果绝不能称为像素级完美或完全一致。

交付说明

开头先呈现可运行的结果。报告以下内容:

  • 来源模式、界面轨道、路由和主要组件。
  • 已实现的视觉系统和响应式转换方式。
  • 生成或编辑的素材、其项目路径及替代方案。
  • 比较过的参考目标、视口、状态和浏览器。
  • 实际运行的验证命令及其结果。
  • 就绪判定和明确的剩余差异。

交付说明应简洁。具体细节应由实现和证据体现。

评论

支持 Markdown