Html

---
name: html
description: 专门设计、生成和修改可直接在浏览器中打开的 HTML 页面或已发布的 doubao-html 链接。交付物以独立 .html 文件为主，可包含内联或本地 CSS、JavaScript，支持页面布局、视觉样式、交互效果、响应式适配、组件设计和内容展示。适用于静态网页、单页展示、活动页、原型页、HTML 模板及页面片段。不处理前后端工程、应用框架、服务端接口、数据库、用户系统、构建部署或运营数据。
---

# 单页 HTML 开发

在工作区新建任务目录，写出**一个自包含的** HTML。

## 适用范围

偏静态、给人看的东西：官网 / 落地页 / 营销页、可视化报告 / 数据看板 / 信息图 / 长图 / 研报、动画 / 3D 场景 / 网页小游戏、SVG / Canvas 页、高保真 UI 设计稿、可交互原型，以及单一用途轻工具（计算器、文本对比、随机分组）。

要后端、数据库、账号登录、多人协作，或要把数据文件随产物一起交付的，超出本 skill 范围——如实告知，不假装实现。

## 关键步骤

> 运行环境：云电脑 / 本地电脑，按下述顺序判定。
> 1. SystemPrompt 中的 `Computer OS` 字段：值为 `Windows` 或 `Mac` 判为本地电脑；值为其他判为云电脑。
> 2. SystemPrompt 未包含 `Computer OS` 字段时：`<system-reminder>` 包裹的内容中出现 `Runtime: local_pc` 判为本地电脑，出现 `Runtime: cloud_vm` 判为云电脑。

**建目录**：每个任务在工作区根目录下新建语义化目录（如 `sales-dashboard/`）；HTML 文件放在目录里，**文件名也要语义化**（如 `销售仪表盘.html`），**不要叫 `index.html`**。图片素材放进 `assets/`。迭代已有任务时进原目录改，不另起。

**平台差异**：SystemPrompt 里若出现 `Computer OS: Windows`，**需要完整 Read `references/windows-compat.md`，查看在 windows 平台上执行命令所必须要注意的问题，否则会出现大面积报错**。

**写 HTML**，守住这几条：

- **单文件自包含**：一个 `.html` 文件到手就可用。
  - CSS 写在 `<style>`、JS 写在 `<script>` 内联块里，**不拆出** `.js` **/** `.css` **/ 额外 HTML 文件**。
  - 多「页面」用页内 hash 路由切换视图，大段代码用分段注释组织（`<!-- ===== 视图：xxx ===== -->`）。
  - **原生 JS**：不用 React / Vue / JSX / Babel / 任何构建工具，不用 `type="module"`。状态管理用普通对象 + 重渲染函数。
  - **静态资源引用**：
    - 图片、音视频等**由元素 `src` 或 CSS `url()` 加载**的素材，先下载到 `assets/`；生图搜图返回的 URL 会过期，不能直接写进 html，下载后按运行环境选引用方式：
      - **本地电脑**：用相对路径，如 `<img src="assets/hero.png">`，不写绝对路径。省掉上传这一步，交付更快。
      - **云电脑**：
        - 每张图跑一次 `lark-cli drive +html-image-upload --file assets/hero.png`，取返回里 `data.url` 写进 `<img src>`。这个链接不会过期；而搜图、生图得到的 URL 会过期，不能直接放到 html中。
        - 此场景下**严禁使用 `FileBatchUpload` 工具**，必须使用 `lark-cli drive`，否则图片也会过期。
    - **数据文件（JSON / CSV / TXT）不适用**：`file://` 页面里 `fetch` 和 `XMLHttpRequest` 都会被浏览器拒绝。优先从 URL 运行时取，取不到才固化进 JS。
    - **图片路径只能写在 `src` 属性或 CSS `url()` 里**：推荐 `<img src="assets/img1.jpg">`。发布链路只静态扫描这两个位置——写在 JS 代码里的任何形式（含 `const imgs = ['assets/a.jpg']` 这样的常量数组）、以及 `data-src` / `srcset` / `poster` 等其它属性，发布后都会裂图。
- **分批写入**：一次写入过长的文件会让用户等待焦虑，最好一次 Write 10k token 内，简单向用户同步进度后，再继续分批写入。在首次写入时, 留下短小且独特的占位，例如 `<!-- something todo -->`，为后续 Edit 提供定位锚点。

- **注意响应式适配，宽屏窄屏电脑手机都要能看**。

- **交付与发布**：
  - 当用户没有明确的发布需求时：用 `present_files` 这类交付工具给用户交付 HTML，**同一个产物只交付一个 `.html` 文件**——按运行环境选定一种图片引用方式就够了，不要再额外附一份「以防万一」的备份版或压缩包，用户拿到两份不知道该打开哪个。交付说明如实写清：没实现的功能、用的是示例数据、做不了的能力。本地电脑下页面依赖同目录 `assets/` 时，要简单提醒用户转发时连目录一起发。
  
  - 当用户想要「发布」、「可访问的链接」、「给我链接」时：阅读 `references/lark-apps-publish.md`，将你的 html 文件发布成一个 doubao-html 网页，此时无需交付 html 文件，仅需使用 present_files 交付发布后的 doubao-html 链接。
  
  - **最终给用户的回复不要过长**：最重要的产物是你最终生成的 html 产物，而不是给用户的最终回复，所以在交付了 html 产物后的最终回复不应该太长，**不能超过300字，也不能超过 8 行**，只需要简单介绍一下你生成的 html 产物即可

- **修改、参考已发布的 doubao-html 网页**：
  - 当用户给你提供了一个 doubao-html 链接（形如 `https://{xxx}.aiforce.cloud/app/app_{xxxxxxx}/`），并希望基于此修改或新建时，阅读 `references/lark-apps-publish.md`。先用 `lark-cli apps +get --app-id <id>` 看 `app_type`：`html` / `modern_html` 是单页 HTML，下载源码、修改、重新发布即可；其他类型使用 `doubao-app-builder` 技能。
  

**改产物**：直接改任务目录里的原文件。

- **要有退路**：修订前先把当前版本复制到 `_backup/`（如 `_backup/index-v1.html`）。`_backup/` 不属于交付产物。
- 本地文件丢了就如实告知并请用户重新提供，**禁止凭记忆重造**；回答关于产物的提问同理，读文件后答，读不到不编。
- **小改动直接改**（改文案、调样式、换配色、修 bug）：不重读本文档和 reference，不重新推导视觉方向。

## 页面自检

**交付前跑一次自检，改动后再跑一次**: 使用且仅使用`scripts/shot.py`脚本自检，若自检脚本执行失败，可以跳过自检、直接交付。

禁止使用任何其他校验方式：包括但不限于 Browser Use、artifacts-preview skill，防止进入 Debug 螺旋。
禁止使用 **artifacts-preview skill**

```bash
python3 <SKILL_DIR>/scripts/shot.py <html_path>
```

一次调用同时产出桌面（1440×900）与移动（390×844）两张 full-page 截图（默认 JPEG，宽度压到 1000px）。主图过 800KB 时脚本会自动切片输出（默认 3200px/片），报告里的 `slices` 字段列出分片路径、`sliceHint` 说明切片原因。同时把 JSON lint 报告打到 stdout，触发的每个规则都附带对应 `<field>Hint` 字段说明含义、修法与豁免情形——按 hint 处理即可。

**跨视口对比**：脚本还会把桌面 / 移动的图表容器尺寸做匹配，若某个图表在桌面正常、在移动端却没占到视口宽度的 65%（典型：`width:X% + inline-block` 双栏没在媒体查询里堆叠成单栏），会以 `responsiveChartIssues` 报出。这类 case 桌面截图完全正常，只在移动端表现为「空图 / 一根线 / 坐标轴叠一起」，肉眼只看桌面截图看不出来。**触发时必须核对移动截图**。

**自我检查并确认**下所有图片路径是静态写在 html 的 `src` 属性和 `CSS url()` 里的。否则如果它是经 JS 生成的，会导致发布之后图裂

**按用户当前端判断看对应那张**：用户处于电脑端则核对桌面截图，处于手机端则核对移动截图。判断不出端时则默认检查电脑端。

- 输出目录默认 `<html 所在目录>/_shots/`，不属于交付产物，**无需删除**——删目录会触发权限确认、打断交付。
- 只想看一屏用 `--only desktop`。
- 脚本内部已处理常见坑：`.rv / .fade / [data-aos]` 等滚动揭示元素强制显现（避免 `opacity:0` 截空白）、关掉 `scroll-behavior:smooth`、滚一遍触发 lazy 图片、`networkidle` 不可达时退回 `domcontentloaded`——**不需要另写截图脚本再走一遍**。

**看报告的次序**：先看 lint 各字段（`consoleErrors` 优先，其他布局/交互字段规则报出来基本都是真的，触发时看对应 `<field>Hint` 处理），→ Read 截图做视觉核对。默认先 Read 主图；主图因太大被过滤或读失败，再按顺序 Read `slices` 里的分片；不要一上来就把主图和所有分片都读一遍。视觉有疑点、报告分辨不出细节（颜色、字体渲染）时，再针对性截一屏；先用报告定位到具体元素/错误、改代码，改完重跑 `shot.py`。


## 外部资源

**JS 库统一走 jsDelivr**：`https://cdn.jsdelivr.net/npm/<包名>@<版本>/…`。故障时的备用镜像是 **cdnjs**（`https://cdnjs.cloudflare.com/ajax/libs/<lib>/<ver>/…`，Cloudflare 官方运营，同版本文件字节一致）。**禁止** bootcdn、staticfile、polyfill.io（均有供应链投毒历史），unpkg 不作首选。

**字体走自托管镜像** `https://miaoda.feishu.cn/fonts/css2?family=…`：查询语法与 Google Fonts 的 `css2` 端点完全一致，返回的 `@font-face` 也指向自托管 CDN，两跳都不经过 Google。**不直连** `fonts.googleapis.com` **/** `fonts.gstatic.com`（部分地区不可达）。多字族就重复写多个 `family=`，例如 `<link rel="stylesheet" href="https://miaoda.feishu.cn/fonts/css2?family=Noto+Serif+SC:wght@400;600;700;900&family=Noto+Sans+SC:wght@300;400;500;700&display=swap">`。每个 `font-family` 都要带完整的系统字体 fallback 栈，字体加载失败时页面仍然成立。

## 图像素材

图片素材能显著提升产物美观度，不要默认用纯 CSS / SVG 撑起全部视觉。

**载体选型**：图标、状态标记、导航符号、简单示意图、数据图表属于符号 / 信息型，用内联 SVG 或 CSS。人物、角色、动物、具体物体、产品情境、真实场景、hero 主视觉、章节题图、叙事插画属于具象 / 氛围型，**必须用真实图片**——除非用户明确要矢量插画，禁止用手写 SVG 或 CSS 几何图形代替依赖形象可信度的具象画面。「简单图表优先使用 Echart 来进行生成，而无需使用 SVG」只适用于数据可视化，不得扩展到人物、场景和插画。

**来源按序**：① 用户提供和项目已有的素材，始终第一优先，不要擅自用生成图替换；② 图片生成能力，没有可用素材时的默认选择，prompt 写清风格、构图、配色，使产出与视觉方向一致；③ 外部检索，仅当要忠实呈现真实人物、产品、地点、Logo 等事实对象、生成会失真造假时才用。

网络图片需要先下载到本地并**用读图能力实际看过**——内容对得上、清晰完整、无水印、不是防盗链占位图，确认通过才上传引用；看不了或不符的换图或改用生成。

**来源偏好**：尽量使用用户提供的图片、项目已有的图片、以及搜索到的真实相关的图片，而不是工具生成的图片；假设这些图片不够时，你可以使用生图生成的图片进行补充

**使用图片的比例控制在 3:4 ~ 21:9**（竖版到宽条形）：Banner / Hero 用 16:9 或 21:9，章节题图 3:2，方形插图 1:1。更极端的比例（1:5 长条、9:16 竖屏）可能会导致图片在不同设备上显示不全或出现大片空白区域。

**裁切与呈现**：用 `cover` 或固定高度前，先确认任务要求看见的主体、文字、标签不落在裁切区——竖图放横框时先用 `object-position` 把主体框住，主体横跨整张图、怎么调都保不住时才改用自然比例或 `contain`。hero、banner、纯背景用 `cover` 填满即可。

## 内容要求

**数据保真**：用户给了源数据时，每个数字和结论都要从源数据实际算出、可追溯，不目测、不凑整、不编造。

**数据附件要获取下来并分析**，但**不要把数据转成** `const RAW_DATA = [...]` **固化进 JS**——那样用户换一份文件页面纹丝不动。数据能从 URL 取到就运行时取，确实取不到时才固化，并在交付说明里讲清。

**内容取舍**：不加与目标无关或没有依据的内容；内容不足以成页时合并、重构或要材料，不靠放大留白撑页。当有大量信息需要展示时，主要信息和次要信息需要重点鲜明，一个逻辑连贯的模块闭合在一屏内是更好的选择，必要时添加筛选与搜索能力。

**硬性规格逐条对照**：页数、画幅、必含模块，交付前自查。

**时间演进优先用时间轴**：涉及阶段、演进、里程碑、前后对比、路线图的内容，默认使用时间轴，而非项目符号列表或纯段落；每个节点承载：时间、事件名、一句话说明（可选）、（可选）关键指标或图标，让单个节点即可独立传达信息，注意时间轴节点与连线应该适当对齐。时间轴和附着在其上的图标（比如圆点或方块）的中心必须实现像素级对齐（0px误差）。并且额外注意时间轴的文字和轴线、文字和图标不要重叠。
推荐用 **grid 三列（时间 / 轴 / 内容）** 的形式实现时间轴：圆点用真元素放中列、`justify-self:center` 交给布局引擎居中，轴线用 `calc()` 从列宽变量推出（横向时间轴同理，三列换三行、用 `align-self:center`），确保节点与轴线对齐，且无需手算坐标。

**表格要显式给列宽**：多列表格加 `table-layout: fixed`，并给**每一列**都写宽度、加起来正好 100%（`<colgroup><col style="width:25%">` 或写在 `th` 上）。漏写一列，`auto` 布局就会把它压到一字宽、中文逐字折行，行高被撑到半屏高，同行其余列跟着变成大片空白。

## 图表及其交互设计方法

**图表服务于内容理解与判断**：依据任务和数据决定图表类型、数量与组合。图表呈现关系与证据，文字只写图表未直接呈现的解读或判断，**禁止把图表标签照抄一遍**。图表首选 ECharts；仅当其无法满足所需表达或交互时，再使用 D3 或 SVG。

**设计图表及其交互前，统一从 [references/chart/atlas.md](references/chart/atlas.md) 开始**：先确定图表选型与信息组织，再按其中的指引选读图内交互或多视图体验参考。

## 网页交互设计

**禁止僵尸按钮**：视觉上像能点的元素——按钮、导航项、卡片入口——必须有真实的 click handler、跳转或占位反馈（如 toast 提示"演示中"）。禁止 `<button>` 无 `onclick`/`addEventListener`、`<a>` 无 `href`（或 `href="#"` / `href="javascript:void(0)"` / `href="javascript:;"` 却没实际 handler）、`<div class="nav-item">` 只挂 `cursor:pointer` 却什么都不绑——这些是原型页里最高频的 slop，要么给每个入口挂真实切页/toast，要么不做这个按钮，**宁愿不要按钮也不做僵尸按钮**

## 视觉设计

**先认媒介，别默认做成网页**：HTML 只是载体，产物形态各不相同——信息图、长图、研报、看板、设计稿、动画、游戏各有各的表达惯例。只有真在做网页时才用网页那套语汇（顶部导航、hero、footer、等宽卡片栅格、底部 CTA 区）；其余形态套上网页壳子就是最典型的 slop。先想清楚这次的媒介是什么、那个领域的行家会怎么排它，再往下走。

需要在既有色板上扩色时用 oklch 派生——固定 hue 调 lightness / chroma，或沿同一 L / C 轴换 hue——不要凭空发明一个新 hex 塞进去。

动手前读 `references/design/frontend-design.md` 确立视觉方向：有品牌或既有 UI 就对齐它的视觉语言，从零起步就从主题和材料里立一个契合的方向。已给参考图、品牌体系、设计规范或媒介 reference 时以它们为准。方向实在推不出、项目又是从零起的，先问清调性、受众、颜色、情绪——**在推不出方向时硬选，slop 就是这么来的**。

字体选少量但与主题匹配的，层级靠字号、字重、行长和语义断行建立，不靠堆字体数量。背景与配色不局限于纯黑纯白，可以按内容属性和叙事节点变化，但一致性要来自共享色板和明确的颜色关系，不是逐页随机换色；强调色数量克制、同属一个体系。视觉丰富度服务内容：既不堆无信息价值的装饰，也不把「克制」做成大量留白加同一种构图。

**禁止无意义留白与失衡布局**：页面各区块须在视觉上均衡分布，禁止出现大面积无内容留白、单侧堆积、上重下空或下重上空等失衡结构；留白是用来服务于分组、呼吸或强调，不得用于填充版面。特殊布局设计除外，在特殊设计当中可以豁免。卡片组在**每个断点**的列数都不能让最后一行只剩 1 个（`N % C == 1`）——4 张走 4 → 2 → 1、跳过 3 列，别留 3 + 1。

**避免 AI slop**：滥用渐变、圆角＋左边框强调容器、被用滥的字体（Inter、Roboto、Arial、Fraunces）。

**做 hero / signature element / 复杂动效 / Canvas / WebGL / 进阶排印 / 材质纹理 / 地图 / 音频 / 音画同步 / 数学公式时先读 `references/design/visual-techniques.md`**——里面有动效工具链（IntersectionObserver / GSAP / Lottie / View Transitions / Scrollama / CSS scroll-timeline）、Canvas/WebGL 选型（three.js / p5.js / matter.js）、进阶排印（variable font / background-clip / SVG textPath / feTurbulence）、材质纹理层（grain / duotone / halftone）、地图（Leaflet / MapLibre / D3-geo / Deck.gl + 免费瓦片源）、Web Audio（Tone.js / 原生 AudioContext / sonification）、动画+声音协同（音频主时钟、三种协同模式、user gesture 门槛、mute 与 reduced-motion 双通道）、KaTeX 数学公式，以及每一层对应的 slop 红线（毛玻璃、glow border、粒子网背景、data-aos 全站铺、Leaflet 蓝大头针、Mercator 全球图、rainbow 色板、音频自动播放、音乐可视化跳舞背景等）。

**设计 3D 场景读 `references/design/3d-design.md`**，掌握材质、阴影、光照、运镜的设计方法。

**不用 emoji**：尽可能不要使用任何 emoji，也不作图标、不作装饰、不放进数据，除非用户品牌资产明确包含。需要图标体系时用内联 SVG（`<svg viewBox="0 0 24 24">`）建立风格连贯的图标语言。

**要有 favicon**：用 SVG 或 AI 生图，为产物搭配一个合适的 icon，内联进 HTML。

在既有 UI 上增补时，先理解并遵循它的视觉语汇：文案风格、配色、hover 状态、卡片布局、密度。

## 参考文档地图

### `references/`

| 文档 | 何时读 |
| --- | --- |
| [`lark-apps-publish.md`](references/lark-apps-publish.md) | 用户要「发布」「可访问的链接」，或给了 doubao-html 链接要基于它改 |
| [`windows-compat.md`](references/windows-compat.md) | SystemPrompt 出现 `Computer OS: Windows`——**必须完整 Read**，否则大面积报错 |

### `references/design/`

| 文档 | 何时读 |
| --- | --- |
| [`frontend-design.md`](references/design/frontend-design.md) | **动手前必读**，确立视觉方向 |
| [`visual-techniques.md`](references/design/visual-techniques.md) | hero / signature element / 复杂动效 / Canvas / WebGL / 进阶排印 / 材质纹理 / 地图 / 音频 / 音画同步 / 数学公式 |
| [`3d-design.md`](references/design/3d-design.md) | 设计 3D 场景（材质、阴影、光照、运镜） |

### `references/chart/`

| 文档 | 何时读 |
| --- | --- |
| [`atlas.md`](references/chart/atlas.md) | **做图表与图表交互的统一入口**：先定选型与信息组织，再按其中指引选读下面两份 |
| [`reading-interactions.md`](references/chart/reading-interactions.md) | 常规读图、固定比较、总览查看某个对象的明细（由 atlas 分流，不单独作入口） |
| [`experience-examples.md`](references/chart/experience-examples.md) | 从同一批记录筛群体做多维比较，或明确的教学实验（同上） |