html
专门设计、生成和修改可直接在浏览器中打开的 HTML 页面。交付物以独立 .html 文件为主，可包含内联或本地 CSS、JavaScript，支持页面布局、视觉样式、交互效果、响应式适配、组件设计和内容展示。适用于静态网页、单页展示、活动页、原型页、HTML 模板及页面片段。不处理前后端工程、应用框架、服务端接口、数据库、用户系统、构建部署或运营数据。
Source facts
- Repository
- locusyuri/Study
- Last source activity
- September 11, 2026 at 11:31
- Detected SKILL.md language
- Chinese
- Stars
- 0
- Forks
- 0
Install options
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Review the source files
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
File Explorer
8 filesShowing SKILL.md
SKILL.md
Source instructions · Read-only preview- 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 产物即可
View on GitHub