Html Page

---
name: html-page
description: 网页生成——制作单文件精美 HTML 页面（落地页/报告页/展示页/小工具）
---

# 网页生成技能

## 适用场景
网站设计、落地页、在线报告、H5 展示页、数据看板、小型 Web 工具。

## 动手前先想清楚四件事

1. **这页是给谁看的、看完要他干什么**（留资？读懂数据？下单？）——决定首屏放什么。
2. **内容从哪来**：用户给了材料就先 `read_file` 读进来，用真实文案；没材料就按主题写具体可信的文案，
   **绝不允许出现 "Lorem ipsum"、"这里是标题"、"产品简介占位" 这类占位符**，那等于没做。
3. **要不要联网**：交付物默认必须断网可用（用户经常是双击本地文件打开的）。
4. **这页长什么样**：先用一句话把参照物说出来（"像一份编辑部的深度报道" / "像终端里的监控面板" /
   "像一本纸质手册"），再从这句话推出主色和版式节奏。**装了 `web-styles` 技能就先 `use_skill` 它**，
   八个方向里挑一个。跳过这步，下面那些骨架和基线会把每一页都压成同一张脸。

## 硬规范

1. **单文件交付**：所有 CSS/JS 内联在一个 `.html` 里，双击即用。
   - 图表优先用**纯 SVG / Canvas 手写**或内联数据 + 原生 JS 画；确实要用 ECharts 这类库时，
     必须先问清楚"这页要联网用吗"，或者直接告诉用户"这页依赖 CDN，断网打不开图表"。
   - 图片用内联 SVG 或 CSS 画；**不要引用不存在的本地图片路径**（`img/hero.png` 这种一定是坏的）。
2. **响应式**：移动优先。`meta viewport` 必写；用 `clamp()` 控字号、`grid`/`flex` + `minmax` 控栅格；
   宽表格、代码块、图表放进 `overflow-x:auto` 的容器里，**页面本身绝不允许横向滚动**。
3. **深浅色都要能看**：用 CSS 变量定义配色，配 `@media (prefers-color-scheme: dark)`。
   两种情况下只做一套：用户明确要求，或**这次的视觉方向本身就是单色调的**（暗色终端、纸质印刷这类，
   硬凑两套会把风格稀释掉）。只做一套就必须在 `<head>` 写死 `<meta name="color-scheme" content="dark">`
   （或 `light`）免得浏览器反色，并在交付说明里讲一句"这页是纯暗色的，不跟随系统"。
4. **语义结构**：`header/nav/main/section/article/footer`，标题层级 h1→h2→h3 不跳级；
   图片带 `alt`，按钮用 `<button>` 不用 `<div onclick>`；正文与背景对比度 ≥ 4.5:1。
5. **视觉基线**（是及格线，不是配方——**具体取哪一档由第 4 件事定的视觉方向说了算**）：
   - 圆角：0（硬朗/印刷/终端）到 20px（亲和/消费）之间选一档，**全页只用这一档**；
     阴影要么克制（`0 6px 24px rgba(0,0,0,.06)`）要么干脆不用、改用 1px 描边或底色区分层次
   - 字体：正文中文一律用系统里真装着的（`"PingFang SC", "Hiragino Sans GB", "Microsoft YaHei",
     "Source Han Sans SC", system-ui, sans-serif`）；想换气质就换族——衬线走
     `Georgia, "Songti SC", "SimSun", serif`，等宽走 `ui-monospace, "SF Mono", Menlo, Consolas, monospace`。
     **回退链里别写没装的字体**（Inter / Noto Serif SC / HarmonyOS Sans SC 都不是预装的，写了等于没写）；
     **中文西文都不引网络字体**（Google Fonts 也不行）：挡渲染的样式表一旦连不上，内网里首屏要白等 5.1 秒才出字。想要气质就在系统字体里换族
   - 间距用 4 的倍数；一屏之内主色不超过 2 个 + 1 个强调色
   - 对齐优先于装饰：相关的东西靠近、无关的拉开

## 避开"AI 味"（重要，这是最容易被一眼看穿的地方）

- ❌ 紫蓝渐变大标题 + 居中三张卡片 + emoji 当图标 + "赋能/闭环/一站式/全新升级"
- ❌ 每个区块都是"标题 + 一句话 + 三个并列卡片"的同一种节奏
- ✅ 配色从主题里长出来（餐饮暖、金融冷、儿童亮、法务稳），不是随手拿默认紫
- ✅ 版式有节奏变化：大图/两栏/引用/数据条/时间轴交替，别一路卡片到底
- ✅ 文案写具体的事（"3 天出图，改到满意为止"），不写形容词（"专业高效的服务"）

## 图怎么放（报告页最容易翻车的地方）

分两类，别混：

- **流程 / 架构 / 时序 / 思维导图 / 甘特** → 一律 `gen_diagram` 画，**不要手写 SVG**。
  内联进 HTML 时把 .svg 文件内容**原样复制**：`<svg id="mmdXXXX">` 的 id 和 `<style>` 里的
  `#mmdXXXX` 选择器是绑死的，动了任何一边整张图的样式全失效，会变成黑字、没底色、框线全丢。
  唯一允许改的是加 `width="100%"` 并删掉写死的像素 width/height。
- **数据图表 / 示意图**（价格带、四象限、时间轴、对比条）→ 手写内联 SVG 可以，但**颜色必须自带**：
  要么写死 hex，要么用本文件 `:root` 里已经定义过的变量。别用应用界面那套 `var(--color-text-primary)`，
  独立文件里它不存在，整条声明作废、回落成黑色，就是"黑底黑字"。
- 每张图下面配一行图注（`图N · 一句话说明这张图在说什么`），图不能替代文字结论。

配色纪律：**一屏之内主色不超过 2 个 + 1 个强调色**，少用纯黑（正文用 #23262e 这类墨色而不是 #000），
底块用同色系浅色而不是灰阶；图的配色要从页面配色里长出来，不能一张图一个色系。

## 长报告 / 研究报告页的骨架（三选一，**开头说清选了哪个、为什么**）

超过 5 屏的报告需要一副骨架，但不是同一副。先看这份东西是给谁看的，再挑：

**唯一不可动的一条：结论必须在前两屏。** 用户只读前两屏的概率最大，把判断压在第 8 节等于没写。
下面三副骨架都满足这条，其余顺序和密度随方向变。

**A · 分析报告式**（给要拿它做决策的人：投资、选型、立项评审）
封面（大标题 + 一句话回答什么问题 + 范围/数据来源/结论一句话）→ 结论先行（加粗一句 + 2-3 个关键数字）
→ 数字卡一行（3-4 个 KPI，数字大、标签小、下面小字写口径和出处）→ 编号分节正文（节内先导读再上表/图）
→ 对比一律上表格 → 风险与待验证（风险 / 等级 / 应对 三列）→ 行动建议（本周 / 一个月内 / 三个月内）
→ 页脚（来源清单 + 生成日期）

**B · 叙事流式**（给要被说服的人：复盘、案例、行业观察、对外发的深度文章）
一句话钩子 + 结论 → 时间线或因果链推进，一节一个转折 → 关键处插数据图或引用块撑住论点
→ 反方观点单列一节（不写反方的复盘没人信）→ 结尾回到开头那个问题，给一句可执行的话。
不要 KPI 卡片墙，不要 `NN` 编号——那是报告腔，会把叙事节奏切碎。

**C · 面板式**（给反复来查的人：监控周报、数据日报、盘点清单）
顶部一条状态摘要（绿/黄/红 + 一句话）→ 指标网格（每格：当前值、环比、迷你趋势条）
→ 明细表格（可排序/可筛更好）→ 异常与待办列表 → 口径说明。
左侧固定目录用 `position: sticky` 实现，但**必须在 `@media (max-width: 1024px)` 里退回普通流**——
侧栏在窄屏挤正文会直接把页面顶出横向滚动，那是硬规范第 2 条的红线。

排版基线（给范围不给定值，取哪档由视觉方向决定）：正文宽度 `640px`（想读得专注）到 `960px`（表格多）之间；
节与节之间 `48px`（信息密）到 `96px`（留白大）之间；标题用编号色块、细线或纯字重锚定，选一种贯穿全页。
表格默认**不要**斑马纹——先用行高和一条 1px 分隔线，只有超过 8 行才加浅底斑马纹，不然满页条纹很廉价。
引用/关键结论用左侧色条的 blockquote，不要满页大色块。

## 交付前必须自己走一遍（不做这步不算完成）

1. `read_file` 把生成的文件读回来，确认：标签闭合、`<style>`/`<script>` 完整、没有被截断。
2. 自查清单：viewport 有没有 / 有没有外链依赖 / 有没有占位符文案 / 有没有引用不存在的资源 /
   375px 宽会不会横向滚动 / 深色模式下字看不看得清（只做一套色的页面则查 color-scheme 写了没）/
   每张内联 SVG 的颜色是不是自带的 /
   贴进来的 gen_diagram 图有没有被改过 id。
3. 跑一次 `check_page`：它会静态体检 + 真浏览器打开一遍，CSS 变量挂空、SVG 样式作用域挂空、
   标签没闭合、引用了不存在的文件这几类都能当场抓出来。报了"错"就必须改完再交付。
4. 发现问题当场改完再交付，**不要把"你可以自己调一下"当交付**。

## 交付后

告诉用户成果文件名，并主动提一句：
> 已经在右侧预览里打开了。如果想在真实浏览器里（或手机上）看效果，点预览顶部的**「本地部署预览」**
> 就能起一个本机服务，相对路径、fetch、localStorage 这些在那儿才是正常的。

## 质量标准
- 浏览器打开零报错、零横向滚动条
- 375px 手机宽度排版正常；跟随系统的页面深浅色都可读，单色调的页面 `color-scheme` 声明到位
- 首屏就能看懂"这是什么、给谁的、下一步干什么"
- 说得出这页的视觉方向是什么、为什么选它——答不上来，多半就是又做了一张大路脸
- 断网双击也能完整显示，**一个外链都不许有**（含 Google Fonts）——内网里连不上的样式表会让首屏白等 5 秒