专门设计、生成和修改可直接在浏览器中打开的 HTML 页面。交付物以独立 .html 文件为主，可包含内联或本地 CSS、JavaScript，支持页面布局、视觉样式、交互效果、响应式适配、组件设计和内容展示。适用于静态网页、单页展示、活动页、原型页、HTML 模板及页面片段。不处理前后端工程、应用框架、服务端接口、数据库、用户系统、构建部署或运营数据。
Scanned 9/12/2026
Install to Claude Code
Skills Directorynpx -y skills add ahang1598/doubao-workbuddy-qwenwork-skills --skill html --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Html?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/ahang1598-html)More formats (shields.io, HTML) on the badges page.
---
name: html
description: 专门设计、生成和修改可直接在浏览器中打开的 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 放在目录里，图片素材放进 `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">`，不写绝对路径。省掉上传这一步，交付更快。
- **云电脑**：交付前跑 `python3 <SKILL_DIR>/scripts/embed.py <html_path>` 把图以 Base64 内嵌，确保用户下载后直接可用。产物是同目录的 `<原文件名>_embed.html`，自检和交付都用这个产物；改动只改原始 HTML，改完重新跑一遍 embed。
- **数据文件（JSON / CSV / TXT）不适用**：`file://` 页面里 `fetch` 和 `XMLHttpRequest` 都会被浏览器拒绝。优先从 URL 运行时取，取不到才固化进 JS。
- **图片路径应静态写在 HTML 属性里，禁止经 JS 生成**：推荐使用 `<img src="assets/img1.jpg">`，发布与 `embed.py` 依赖静态扫描，使用 JS 拼接会导致最终发布产物裂图。
- **分批写入**：一次写入过长的文件会让用户等待焦虑，最好一次 Write 10k token 内，简单向用户同步进度后，再继续分批写入。
- **注意响应式适配，宽屏窄屏电脑手机都要能看**。
**交付**：用 `present_files` 这类交付工具给用户交付 HTML，**同一个产物只交付一个 `.html` 文件**——按运行环境选定一种图片引用方式就够了，不要再额外附一份 Base64 自包含版「以防万一」，用户拿到两份不知道该打开哪个。交付说明如实写清：没实现的功能、用的是示例数据、做不了的能力。本地电脑下页面依赖同目录 `assets/` 时，要简单提醒用户转发时连目录一起发。
**改产物**：直接改任务目录里的原文件。
- **要有退路**：修订前先把当前版本复制到 `_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 所在目录>/_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 等事实对象、生成会失真造假时才用。
网络图片需要先下载到本地并**用读图能力实际看过**——内容对得上、清晰完整、无水印、不是防盗链占位图，确认通过才上传引用；看不了或不符的换图或改用生成。
**来源偏好**：尽量使用用户提供的图片、项目已有的图片、以及搜索到的真实相关的图片，而不是工具生成的图片；假设这些图片不够时，你可以使用生图生成的图片进行补充
**裁切与呈现**：用 `cover` 或固定高度前，先确认任务要求看见的主体、文字、标签不落在裁切区——竖图放横框时先用 `object-position` 把主体框住，主体横跨整张图、怎么调都保不住时才改用自然比例或 `contain`。hero、banner、纯背景用 `cover` 填满即可。
## 内容要求
**数据保真**：用户给了源数据时，每个数字和结论都要从源数据实际算出、可追溯，不目测、不凑整、不编造。
**数据附件要获取下来并分析**，但**不要把数据转成** `const RAW_DATA = [...]` **固化进 JS**——那样用户换一份文件页面纹丝不动。数据能从 URL 取到就运行时取，确实取不到时才固化，并在交付说明里讲清。
**内容取舍**：不加与目标无关或没有依据的内容；内容不足以成页时合并、重构或要材料，不靠放大留白撑页。当有大量信息需要展示时，主要信息和次要信息需要重点鲜明，一个逻辑连贯的模块闭合在一屏内是更好的选择，必要时添加筛选与搜索能力。
**硬性规格逐条对照**：页数、画幅、必含模块，交付前自查。
**时间演进优先用时间轴**：涉及阶段、演进、里程碑、前后对比、路线图的内容，默认使用时间轴，而非项目符号列表或纯段落；每个节点承载：时间、事件名、一句话说明（可选）、（可选）关键指标或图标，让单个节点即可独立传达信息，注意时间轴节点与连线应该适当对齐。时间轴和附着在其上的图标（比如圆点或方块）的中心必须实现像素级对齐（0px误差）。并且额外注意时间轴的文字和轴线、文字和图标不要重叠。
推荐用 **grid 三列（时间 / 轴 / 内容）** 的形式实现时间轴：圆点用真元素放中列、`justify-self:center` 交给布局引擎居中，轴线用 `calc()` 从列宽变量推出（横向时间轴同理，三列换三行、用 `align-self:center`），确保节点与轴线对齐，且无需手算坐标。
**图表优先于文字**：能用图表表达的关系不用文字复述；文字与图表并存时，文字只写图表未直接呈现的解读或判断，禁止把图表标签照抄一遍。遇到数据可视化任务多图表组合的看板是更好的选择，图表的生成首选 Echart，当 Echart 无法满足要求时，再考虑手写 SVG
**可用图表类型对照**（按内容意图选择，禁止凭美观随机选型）：
- 时间轴（Timeline）：阶段演进、路线图、里程碑、事件序列
- 桑基图（Sankey）：资源/流量/预算在多个环节间的分配与流转
- 流程图（Flowchart）：有明确顺序与分支判断的步骤
- 树形图 / 组织架构图：层级归属、分类拆解、问题树
- 四象限 / 矩阵图：两个维度交叉的定位与分类（如重要性×紧急性）
- 对比表（Comparison Table）：≥3 个对象在同一组维度上的并列对比
- 漏斗图（Funnel）：逐级收窄的转化、筛选、决策过程
- 关系网络图（Network）：多对多关系、生态位、利益相关方
- 甘特图（Gantt）：任务在时间维度上的并行与依赖
- 堆叠条 / 百分比堆叠：构成占比随类别或时间的变化
- 折线图：连续变量的趋势与拐点
- 柱状图：离散类别的量级对比
- 散点图 / 气泡图：两至三个变量的相关性与分布
- 热力图：二维矩阵上的密度或强度分布
- 地图：地理维度的分布与流向
选型判断顺序：先问"要表达什么关系"（演进 / 流转 / 层级 / 对比 / 构成 / 趋势 / 分布），再选图表；禁止先选图表再往里塞数据。
**扩展图表类型（弦图 / 力导向 / 旭日 / 雷达 / 日历热力 / Bump / Waffle / Slope / Small multiples 等）、图表红线（饼图 > 5、双 Y 轴、3D 图、词云、蛛网雷达等几乎总是错的陷阱）、库选型（D3 / Observable Plot / Rough.js / Deck.gl 等 ECharts 覆盖不到的场景）、数据叙事模式（scrollytelling、annotated chart、linked views）见 `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/frontend-design.md` 确立视觉方向：有品牌或既有 UI 就对齐它的视觉语言，从零起步就从主题和材料里立一个契合的方向。已给参考图、品牌体系、设计规范或媒介 reference 时以它们为准。方向实在推不出、项目又是从零起的，先问清调性、受众、颜色、情绪——**在推不出方向时硬选，slop 就是这么来的**。
字体选少量但与主题匹配的，层级靠字号、字重、行长和语义断行建立，不靠堆字体数量。背景与配色不局限于纯黑纯白，可以按内容属性和叙事节点变化，但一致性要来自共享色板和明确的颜色关系，不是逐页随机换色；强调色数量克制、同属一个体系。视觉丰富度服务内容：既不堆无信息价值的装饰，也不把「克制」做成大量留白加同一种构图。
**禁止无意义留白与失衡布局**：页面各区块须在视觉上均衡分布，禁止出现大面积无内容留白、单侧堆积、上重下空或下重上空等失衡结构；留白是用来服务于分组、呼吸或强调，不得用于填充版面。特殊布局设计除外，在特殊设计当中可以豁免。卡片组恰好 4 张时排成 2 × 2 或一行 4 个，别留 3 + 1。
**避免 AI slop**：滥用渐变、圆角＋左边框强调容器、被用滥的字体（Inter、Roboto、Arial、Fraunces）。
**做 hero / signature element / 复杂动效 / Canvas / WebGL / 进阶排印 / 材质纹理 / 地图 / 音频 / 音画同步 / 数学公式时先读 `references/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/3d-design.md`**，掌握材质、阴影、光照、运镜的设计方法。
**不用 emoji**：尽可能不要使用任何 emoji，也不作图标、不作装饰、不放进数据，除非用户品牌资产明确包含。需要图标体系时用内联 SVG（`<svg viewBox="0 0 24 24">`）建立风格连贯的图标语言。
在既有 UI 上增补时，先理解并遵循它的视觉语汇：文案风格、配色、hover 状态、卡片布局、密度。
**最终给用户的回复不要过长**：最重要的产物是你最终生成的 html 产物，而不是给用户的最终回复，所以在交付了 html 产物后的最终回复不应该太长，**不能超过300字，也不能超过 8 行**，只需要简单介绍一下你生成的 html 产物即可Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
