L6-12：设计稿转代码 —— 把设计图变成能直接用的网页代码

🎯 学生产级设计实现：不是把设计图"看着差不多"地写成 HTML/CSS，而是用 Pretext 排版引擎实现真正的文本计算——文字在缩放时真实重排、高度自适应内容、卡片自定尺寸。 ⏱️ 预计时间：35 分钟

[!quote]- 📖 原Skill精要 技能名称：design-html 核心功能：设计最终化——生成生产级 Pretext 原生 HTML/CSS。配合 [[L6-11-设计方案散弹枪|design-shotgun]] 审批后的原型、[[L6-02-CEO战略评审|plan-ceo-review]] 的 CEO 计划、或全新描述使用。文字真实重排、高度计算精确、布局动态化。30KB 开销，零依赖。 所属体系：gstack 虚拟工程团队 协作关系：任何计划类 Skill 的后置实现步骤——拿到方案后一键转为生产代码

1. 课程概览

💡 白话小课堂：design-html 解决的是一道"最后一公里"难题——设计定了、方向批了，但把它变成可运行的网页代码，传统方式是"打开 Figma、手动量间距、手写 HTML/CSS、反复调"，这是体力活。design-html 把这个过程自动化：读入获选的设计方向、提取设计 token、选择正确的 Pretext 排版层级、生成语义化 HTML——而且文字是真的在正确排版的（不是 CSS 近似，是 Pretext 计算出的精确布局），最后启动实时预览让用户逐轮精细化，用 Edit（而非 Write）保留用户的手动文本编辑。

2. 为什么需要 Pretext？

3. 输入检测与智能路由

design-html 能接受多种输入上下文，并根据已有上下文智能路由：

4. Pretext 层级与 API 路由

不同的设计类型需要不同的 Pretext API。design-html 自动分析设计并选择正确的层级：

// 1. 准备（一次性，字体加载后）
const prepared = new Map()
for (const el of elements) {
  prepared.set(el, prepare(el.textContent, getComputedStyle(el).font))
}

// 2. 布局（廉价，每次 resize 调用）
function relayout() {
  for (const [el, handle] of prepared) {
    const { height } = layout(handle, el.clientWidth, lineHeight)
    el.style.height = `${height}px`
  }
}

// 3. 缩放感知
new ResizeObserver(() => relayout()).observe(document.body)

// 4. 可编辑内容
new MutationObserver(() => {
  prepared.set(el, prepare(el.textContent, font))
  relayout()
}).observe(el, { characterData: true, subtree: true })

5. 生成与优化循环

⚠️ 避坑指南： AI 生成 HTML 最常见的毛病是"lorem ipsum 占位"和"紫色渐变"。用真实内容填充——真实的产品名、真实的价格、真实的用户评价——你才能知道文字溢出在哪里、卡片会不会被长标题撑破。

6. 实时预览与精细化

🔑 核心秘诀：精细化循环用 Edit 而不是 Write——这是关键设计决策。

7. 设计 Token 提取与持久化

8. 结构拆解：设计稿转代码 Skill 模板

9. 电商 Skill 案例：设计稿转代码——活动落地页

🛒 实战案例：618大促前，某电商平台设计师在Figma中完成了"精华液专场"活动落地页的设计稿（移动端375px为主，含Hero顶图+3款主推商品卡片+限时倒计时条+底部固定CTA按钮）。设计总监确认了设计方案，现需将设计稿转为前端代码（Vue.js + Tailwind CSS），且必须像素级还原。

design-html从设计稿到可运行代码的完整流程：

• 输入检测：检测到approved.json存在（design-shotgun已确定"实验室解谜风"方向），自动读取DESIGN.md中的设计Token——展示字体DM Serif Display、数据字体IBM Plex Mono、主色#1A1A2E、强调色#00C9A7、背景#F7F7F2、间距基准8px、最大内容宽度960px。
• Figma解析：通过Figma API读取设计稿节点结构，识别出7个关键区域——Hero区（渐变背景+主打标题+CTA按钮）、倒计时条（红色#EF4444+等宽字体数字）、3张商品卡片（产品图+名称+核心成分标签+价格+已售数量）、底部固定CTA（"立即抢购 ¥299"按钮）。自动识别了6个设计Token与Figma节点的映射关系。
• Pretext自适应排版：商品标题和描述文本长度不一，使用Pretext引擎为每段文本预计算渲染高度——layout(handle, cardWidth=343px, lineHeight=1.5)→返回精确高度。确保3张商品卡片即使描述长度不同（48字/72字/35字），卡片整体高度仍然一致（340px），不会出现参差不齐。
• 响应式断点：375px移动端——单列纵向滚动，商品卡片全宽343px，Hero标题20px粗体；768px平板——双列商品卡片并排，Hero标题28px；1440px桌面——三列布局，最大内容宽度960px居中。三个断点的间距和内边距均基于8px基准缩放。
• 代码质量检查：生成的Vue.js组件自动通过了Pretext精确度验证（设计稿中标注的文本行数vs代码渲染行数偏差<2%）、颜色对比度验证（CTA按钮白色文字#FFFFFF在#1A1A2E背景上对比度12.6:1远超AA标准4.5:1）、无障碍检查（倒计时数字加了aria-label="距离结束还有2小时15分钟"）。

出码结果：1个Vue.js组件文件（197行）+ 1个Tailwind配置文件补充（15行）。设计还原度检查——使用design-review的像素对比工具，Figma设计稿vs浏览器渲染截图的像素差异率为0.7%（行业可接受标准<2%）。移动端Lighthouse性能评分93/100（图片使用WebP格式+懒加载），首屏渲染时间1.2秒。

🔑 启示：设计稿转代码最难的不是"把视觉还原"——而是处理文本长度不一致导致的卡片高度参差、响应式断点下的信息优先级变化、以及设计稿中的固定像素值在4K屏上变成蚂蚁字的问题。好的design-html流程在这些问题发生之前就通过Pretext和Token系统把它们解决了。

生成后自动提取并在 DESIGN.md 中补充：
  → 圆角值：图片 0px（直角），卡片 4px，按钮 4px
  → 阴影：卡片 box-shadow: 0 1px 3px rgba(26,26,46,0.08)
  → 过渡：all 150ms ease-out
  → 新增动效：hover 时卡片微微上浮（transform: translateY(-2px)）

精细化循环迭代

迭代 1：创始人反馈——"成分表像药瓶标签，太冷了"
  → Edit：成分表添加暖灰背景底色 + 微圆角
  → 从"实验室报告"调整为"有温度的实验室报告"

迭代 2：用户测试反馈——"移动端成分表太长，需要折叠"
  → Edit：默认展示前 5 个成分 + "查看全部 15 个成分"按钮
  → Pretext 重新计算展开/折叠后的高度

迭代 3：done ✓

***

## 10. 掌握检验

**Q1**：Pretext 库的 `prepare()` 和 `layout()` 解决了 CSS 的什么根本性局限？
- A) CSS 不支持 Google Fonts
- B) CSS 无法精确告诉你一段文字在特定宽度下会有多高
- C) CSS 不支持暗色模式
- D) CSS 不支持响应式布局

**Q2**：在 design-html 的输入检测中，如果 `approved.json` 存在但 `finalized.html` 也已经存在，Agent 应该怎么做？
- A) 直接覆盖 finalized.html
- B) 忽略 approved.json，重新开始
- C) 询问用户：在已有 finalized.html 上迭代还是重新生成
- D) 自动回退到 plan-driven 模式

**Q3**：以下哪个场景需要使用 Pretext 的 `prepareWithSegments() + walkLineRanges()` 层级（Pattern 2）？
- A) 产品详情页的描述文字
- B) 数据仪表盘中的统计卡片
- C) 聊天界面的气泡消息
- D) 博客文章的长文本排版

**Q4**：为什么精细化循环中必须用 Edit 而非 Write？请描述一个具体场景：如果用了 Write 替代 Edit 会发生什么灾难？

**Q5**："真实内容，绝不 lorem ipsum"不仅仅是审美要求。请从至少两个工程角度解释为什么用 lorem ipsum 填充内容会直接导致 Pretext 的精确排版失效。

**Q6**：design-html 的黑名单（绝不包含）中有"通用推荐区块"和"带阴影的圆角卡片作为默认组件"。请将这些反模式与 Pretext 的技术能力关联——为什么有了精确文本排版能力后，这些反模式变得更加不需要？

***

## 11. 答案

<details>
<summary>点击查看答案</summary>

**Q1**：**B** —— Pretext 解决的核心问题是文本布局的精确计算。

**Q2**：**C** —— 这是 evolve 模式。

**Q3**：**C** —— 聊天界面需要 Pattern 2（紧贴容器）。

**Q4**：如果用户在浏览器中通过 contenteditable 手动编辑了产品描述文本（改了几句话、调整了措辞），但设计上只需要修改一个按钮的颜色——这时如果用 Write 重写整个 HTML 文件，用户手动编辑的内容会全部丢失。用 Edit 只改按钮的颜色样式，保留用户在其他区域的所有手动修改。这就是"手术式修改"——只动需要动的部分。

**Q5**：①长度差异——lorem ipsum 的段落长度是固定的（"Lorem ipsum dolor sit amet..."），而真实的产品描述可能是 50 字也可能是 200 字。用 lorem ipsum 测不出文字在极限长度下的卡片表现（短文字卡片空洞？长文字卡片撑破？）。②词长和换行点——lorem ipsum 的词长分布是拉丁语的（长词居多），而真实中文的词长完全不同。Pretext 的 layout() 计算分行点依赖于真实字符流——lorem ipsum 换出的行数和位置与真实内容不同，Pretext 计算的精确高度也会失准。最终结果：上线时发现"测试时好好的"是因为"测试用的是假文字"。

**Q6**：这些反模式之所以流行，正是因为传统 CSS 无法精确控制文本与容器的关系——设计师用圆角阴影卡片来"包装"内容的不确定性（你不知道文字会溢出多少，所以给一个圆角卡片兜底），用通用推荐区块来"填满"无法精确排版的空间。Pretext 赋予了对文本的精确控制——你知道每个文字块的确切尺寸，可以用精确的间距和层级替代模糊的"卡片式包装"，用精确排版的数据展示替代"通用推荐区块"。有了精确排版能力，装饰性圆角卡片和通用区块就变成了不必要的设计遮盖，而非设计需要。

（5/6 通过）
</details>

***

## 延伸阅读
- [[L6-11-设计方案散弹枪|设计方案散弹枪 —— 一口气探索5个完全不同的设计方向]]
- [[L6-13-开发者体验审计|活网站开发者体验审计 —— 像用户一样体验你自己的API]]