单页 HTML 开发
在工作区新建任务目录,写出一个自包含的 HTML。
适用范围
偏静态、给人看的东西:官网 / 落地页 / 营销页、可视化报告 / 数据看板 / 信息图 / 长图 / 研报、动画 / 3D 场景 / 网页小游戏、SVG / Canvas 页、高保真 UI 设计稿、可交互原型,以及单一用途轻工具(计算器、文本对比、随机分组)。
要后端、数据库、账号登录、多人协作,或要把数据文件随产物一起交付的,超出本 skill 范围——如实告知,不假装实现。
关键步骤
运行环境:云电脑 / 本地电脑,按下述顺序判定。
- SystemPrompt 中的
Computer OS字段:值为Windows或Mac判为本地电脑;值为其他判为云电脑。- 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或 CSSurl()加载的素材,先下载到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 拼接会导致最终发布产物裂图。
- 图片、音视频等由元素
- CSS 写在
分批写入:一次写入过长的文件会让用户等待焦虑,最好一次 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
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 产物即可