页面区块包

---
name: section-kit
description: 做好的页面区块，由智能体粘贴到对方现有网站里再修改，不用从空白画布开始设计。共 17 个区块（6 个首屏、6 个客户评价、事实条、价格表、常见问题、页脚行动号召、可选页眉），每个都有纯 HTML 和 CSS、React 组件、Vue 单文件组件三种版本，全部由两到四个品牌色统一换色。当有人想给已有网站加首屏、客户评价、价格、常见问题或收尾区块，技术栈是纯 HTML、React 或 Vue，手上有真实文案，或者点名要用这个包时使用。
version: 1.0.0
---

# 页面区块包

17 个做好的区块，风格是平涂的剪纸花砖。你要做的是：选区块，用一条命令拷进项目，把样例换成对方的真实文案，再跑检查器。不用设计，也不用改写 CSS。

粘贴之后，源码就是对方自己的：文件读得懂，没有要不断升级的依赖。视觉规范全部写在一个文件里，就是 `tokens.css`。页面用的是 `sections/` 里的那份，所以所有修改都改那里，不要改包里的 `assets/`。改 token 之前先读 `references/style.md`。

## 需要问清楚的信息

简报里没写的，一次问完，放在一条消息里。

必须有：
1. 技术栈：纯 HTML、React 还是 Vue。
2. 这门生意做什么、面向谁，用对方自己的话。
3. 想要哪些区块，或这个页面的目标。对方不知道的话，按下面的表提建议。
4. 主按钮通向哪里：网址、邮箱或电话。

只有用到相应区块时才需要：
5. 真实的客户原话，包括姓名、对方同意具名，以及每句话的来源。
6. 真实的数字，以及每个数字的来源。
7. 真实的价格，以及每个方案包含什么。
8. 客户真正会问的问题，以及确认过的答案。
9. 对方自己的照片，本地文件。可选：没有照片时，每个区块用绘制图也是完整的。

## 诚实规则

区块绝不虚构证据，你也一样。对方没给过的引语、姓名、头衔、数字、价格、客户、奖项、成果，一概不写。整理真实引语只能删字，不能加字。

每处样例都有三重标记：文案里写着“示例”或 Sample，区块上有可见的提示条，区块带有 `data-sample` 属性。`scripts/check.mjs` 看到任何一种都不会放行；样例句子即使去掉了标记，也一样拒绝。

每条证据都要带 `source`（HTML 里是 `data-source`）：谁给的、什么时候给的，例如 `Ana 的邮件，2026 年 3 月 3 日`。它不显示在页面上。说不出来源的证据就不能用。

**虚构页面。** 只有页面上有带 `data-sk-fictional` 属性的可见元素，文字说明页面是虚构的，`source: fictional` 才能通过。例如：`<p data-sk-fictional>虚构示例。这家面包房是编出来的。</p>`。真实页面绝不能用，要停下来问真实来源。

**真实引语旁默认不放头像。** 真实姓名旁边的绘制头像，会被当成这个人的画像，而对方并没有同意。所以真实引语的 `portrait` 字段留空，不显示头像，`quote-portrait` 这时显示花砖图。有本人照片就设 `portrait: photo` 并填 `image`；只有本人同意或页面标注虚构时，才设 `portrait: drawn`。样例用的是 `portrait: sample`，检查器会拒绝。

**绝不凑数。** 条目数量是上限，不是目标。简报只有两条事实，常见问题就只有两问，一问也可以。绝不为了填满版面加条目，也绝不把一句话拿去回答它其实没回答的问题。如果区块的下限比你手上的多（比如一条引语放进 `quotes-grid`），就换一个区块。

### 缺什么时用什么替代

| 对方没有 | 不要用 | 改用 |
|---|---|---|
| 客户评价 | `quotes-grid`、`quotes-mosaic`、`quote-single`、`quote-portrait`、`quotes-fan`、`case-note` | `proof-row` 写对方能证实的朴素事实，再加 `faq` |
| 连可核实的事实也没有 | `proof-row` | 只用 `faq`，并在报告里说明页面暂时没有证据 |
| 一个真实数字 | `hero-stat` | `hero-poster` 或 `hero-arch` |
| 有事实的客户故事 | `case-note` | `proof-row` |
| 真实的步骤名称 | `hero-steps` | `hero-poster` |
| 确定的价格 | 编造价格 | `pricing-table` 写“询价”，或用 `faq` |
| 自己的照片 | 下载图库照片 | 保留绘制图。它们是抽象人物，不代表任何真人 |

## 步骤

1. 从目录里选区块。一页只用一个首屏。两个客户评价区块不要挨着放。
2. 拷进项目：
   ```
   node scripts/scaffold.mjs --stack html --blocks hero-poster,proof-row,faq --out ./site
   ```
   其他技术栈用 `--stack react` 或 `--stack vue`。它会生成 `sections/` 文件夹和可运行的用法示例：纯 HTML 是 `index.html`，其他是 `SectionsExample.jsx` 或 `SectionsExample.vue`。加 `--app` 会多生成一个可以马上运行的小 Vite 应用（`npm install`，然后 `npm run dev`）。`--theme` 选主题。
3. 粘贴到真实网站：
   - 纯 HTML：把 `<section>` 放到该放的位置。在 `<head>` 里依次引入 `tokens.css`、`base.css` 和区块自己的 CSS。如果区块有 `.js`，放在 `</body>` 之前。
   - React 或 Vue：在应用入口处引入一次 `tokens.css`，再引入 `base.css`，都要在组件之前。
4. 按下面的字段表，把所有样例换成真实文案。
   - 纯 HTML：改带 `data-slot` 的标签里的文字、带 `data-slot-href` 的链接，以及每个 `data-source`。上限就写在每个位置旁边。删掉 `data-sample` 和带 `data-sk-flag` 的那一段。
   - React 或 Vue：改组件顶部的 `COPY` 对象，或者通过 `copy` 属性传入。删掉 `sample: true` 和 `flag`。
   - 可选元素没有真实内容可写时就删掉。在 React 和 Vue 里，空字符串会把它隐藏。绝不留凑数的内容。
   - 给每个区块设置 `lang`，例如 `zh-CN`。一个区块只用一种语言，按钮文字和 `aria-label` 也算。
5. 如果要换色，用一条命令，见“换色”一节。想用现成主题，就在区块或任意祖先元素上设 `data-sk-theme`。如果这些区块放进已有的网站，先读“衔接宿主页面”。
6. 反复跑检查器直到通过，然后实际操作页面：
   ```
   node scripts/check.mjs site/index.html
   node scripts/check.mjs src/sections --url http://localhost:5173/
   node scripts/drive.mjs site/index.html --shots ./shots
   ```
   第二种写法用于 React 和 Vue：先读源码文件夹，再渲染正在运行的应用。
7. 亲眼看每个选用的区块，在 1280、768、390 像素宽度下，用实际要交付的主题。操作脚本会存下这些截图。检查器能抓到很多问题，但它没有审美。

## 目录

**首屏**

| 区块 | 组件 | 什么时候用 | 条目数 | 字段 |
|---|---|---|---|---|
| `hero-steps` | HeroSteps | 业务有两到四个清楚的步骤，展示步骤比一句口号更说得清。 | 2-4 | `eyebrow` `title` `lead` `cta` `cta_href` `steps_label` `label` `text` |
| `hero-angled` | HeroAngled | 有很多东西值得看：场地、产品、作品。最好用对方自己的照片。 | 4-6 | `eyebrow` `title` `lead` `cta` `cta_href` `cta2` `cta2_href` |
| `hero-stat` | HeroStat | 对方有一个说得出来源的真实数字，而且这个数字本身就是故事。 | 无 | `eyebrow` `stat` `stat_label` `stat_source` `title` `lead` `cta` `cta_href` |
| `hero-contact` | HeroContact | 本地或服务型生意，下一步就是打电话、写邮件或到店。 | 2-4 | `eyebrow` `title` `lead` `contact_label` `contact_value` `contact_href` |
| `hero-poster` | HeroPoster | 信息很少，没有图、数字和引语。一句话，非常大。最稳妥的首选。 | 无 | `eyebrow` `title` `lead` `cta` `cta_href` `cta2` `cta2_href` |
| `hero-arch` | HeroArch | 主角是一个地方或一个人：一张图，旁边一条事实。 | 无 | `eyebrow` `title` `lead` `cta` `cta_href` `note_label` `note` |

**客户评价：只用真实引语**

| 区块 | 组件 | 什么时候用 | 条目数 | 字段 |
|---|---|---|---|---|
| `quotes-grid` | QuotesGrid | 两到六条长度相近的真实引语。只用于真实引语。还没有就改用 proof-row 或 faq。 | 2-6 | `eyebrow` `title` `lead` `quote` `name` `role` `portrait` |
| `quotes-mosaic` | QuotesMosaic | 三到五条长短不一的真实引语，要一个响亮多彩的证明区。只用于真实引语。还没有就改用 proof-row 或 faq。 | 3-5 | `eyebrow` `title` `quote` `name` `role` `portrait` |
| `quote-single` | QuoteSingle | 只有一条，但足够好，值得占满整个区块。只用于真实引语。还没有就改用 proof-row 或 faq。 | 无 | `quote` `name` `role` `portrait` |
| `quote-portrait` | QuotePortrait | 一位具名人士的真实引语，深色、郑重。没有本人照片时显示花砖图。只用于真实引语。还没有就改用 proof-row 或 faq。 | 无 | `eyebrow` `quote` `name` `role` `portrait` |
| `quotes-fan` | QuotesFan | 两到五条真实引语，空间有限时用。像一叠牌，读者一张张翻。只用于真实引语。还没有就改用 proof-row 或 faq。 | 2-5 | `eyebrow` `title` `lead` `prev_label` `next_label` `quote` `name` `role` `portrait` |
| `case-note` | CaseNote | 一个有前后对比的真实客户故事，像一份工作笔记。需要真实事实，没有就改用 proof-row。 | 无 | `eyebrow` `title` `client` `before_label` `did_label` `after_label` `before` `did` `after` `stat` `stat_label` `quote` `name` `role` `portrait` |

**其他**

| 区块 | 组件 | 什么时候用 | 条目数 | 字段 |
|---|---|---|---|---|
| `site-header` | SiteHeader | 可选。宿主没有页眉，或者网站主人同意替换不协调的页眉时用。一条小横栏：名称、链接和一个按钮。 | 0-5 | `brand_name` `brand_href` `nav_label` `link` `link_href` `cta` `cta_href` |
| `proof-row` | ProofRow | 没有客户评价、也没有客户标志时的诚实替代：谁都能核实的朴素事实。 | 2-4 | `title` `value` `fact_label` `fact_source` |
| `pricing-table` | PricingTable | 有两三个真实方案。价格没定就写“询价”。只有一种价格就删掉切换开关。 | 2-3 | `eyebrow` `title` `lead` `period_a` `period_b` `plan` `blurb` `price` `price_alt` `per` `per_alt` `featured` `featured_label` `cta` `cta_href` `feature` |
| `faq` | Faq | 客户真正会问的问题，一个也可以。不需要 JavaScript，也是没有评价时诚实的替代。 | 1-8 | `eyebrow` `title` `lead` `q` `a` |
| `footer-cta` | FooterCta | 页面最后一屏：最后一个邀请，然后是链接和版权信息。 | 0-6 | `eyebrow` `title` `lead` `cta` `cta_href` `cta2` `cta2_href` `link` `link_href` `legal` |

每个区块都在 `assets/blocks/<id>/`，包括 `<id>.html`、`<id>.css`、React 的 `.jsx`、Vue 的 `.vue`，有交互的还有 `<id>.js`。有交互的区块：`hero-steps`（步骤切换）、`quotes-fan`（翻牌）、`pricing-table`（价格切换）。`faq` 用原生 `<details>`，不需要脚本。`example/gallery.zh.html` 展示全部区块。

## 字段

上限的单位是“单位”：一个拉丁字母、数字或空格算 1，一个中日韩文字算 2。检查器会强制执行。所有字段都在这里，包括含义和信息太少时怎么办。

| 字段 | 上限 | 含义 | 信息太少时 |
|---|---|---|---|
| `lang` | 8 | 这个区块的语言，例如 zh-CN、en。一个区块只用一种语言。 | 用对方写给你的语言。 |
| `anchor` | 30 | 可选，这个区块的 id，让 #contact 这样的链接能跳到这里。只在有链接指向时才加。 | 除非页面上有链接指向这个区块，否则不加。 |
| `featured` | 5 | true 表示用品牌色突出这个方案，false 表示不突出。 | 除非对方确实推荐某个方案，否则都用 false。 |
| `seam` | 8 | 可选。区块和宿主页面怎么衔接：gap、rule 或 card。见“衔接宿主页面”。留空就是通栏。 | 整页都用这个包时不加。放进宿主页面时先试 gap。 |
| `heading` | 2 | 只用于首屏。默认 h1。宿主页面已有 h1 时用 h2，让整页只有一个 h1。 | 宿主有 h1 就设为 h2，不动宿主。 |
| `portrait` | 6 | 真实引语旁的头像。默认留空：不显示头像。photo 用 image 里的照片。drawn 显示绘制头像，只有本人同意或页面标注虚构时才能用。检查器拒绝 sample。 | 留空。真实姓名旁的绘制头像会被当成本人画像。 |
| `brand_name` | 32 | 页眉里的商家名称。 | 用对方给的名称，绝不编造。 |
| `brand_href` | 200 | 名称链接到哪里，通常是首页。 | 不知道首页就写 #contact 并列入假设。 |
| `nav_label` | 40 | 给读屏软件的导航名称。 | 写“主导航”。 |
| `flag` | 60 | 可见的示例提示。样例换完后连它一起删掉，不要改写。 | 交付的页面上绝不能留。 |
| `eyebrow` | 32 | 标题上方的小标签：栏目名或面向谁。 | 用商家名或对方自己用的品类词；都没有就删掉。 |
| `title` | 64 | 大标题：一句对方自己也会这样说的大白话。 | 复述对方自己描述业务的话，不加对方没说过的最高级，并列入“推断的文字”。 |
| `lead` | 180 | 一两句话，说明接下来会怎样、面向谁。 | 只复述已有事实；没有就删掉。 |
| `cta` | 24 | 主按钮文字：动词加事情。 | 用“联系我们”，并配上真实的联系方式。 |
| `cta_href` | 200 | 主按钮链接：网址、mailto:、tel: 或页内锚点。 | 没有真实链接就写 #contact 并列入假设。不能只写 #。 |
| `cta2` | 24 | 次按钮文字。 | 没有第二个动作就删掉这个按钮。 |
| `cta2_href` | 200 | 次按钮链接，规则同主按钮。 | 随按钮一起删。 |
| `steps_label` | 40 | 给读屏软件的步骤列表名称。 | 写“步骤”。 |
| `label` | 28 | 这一步的短名称，最多三个词。 | 用对方自己说的步骤；没有就问，问不到就换一个首屏。 |
| `text` | 140 | 这一步发生什么，一句话。 | 只写对方讲过的。宁可删掉一步也不要编，两步也够。 |
| `art` | 20 | 显示哪张代码绘制的图：scene-1 到 scene-8，portrait-1 到 portrait-8。 | 保持默认。 |
| `image` | 200 | 可选，对方自己照片的本地路径。留空就显示绘制图。 | 留空。绝不下载或生成真人照片。 |
| `image_alt` | 120 | 照片内容的文字描述，给读屏软件。填了照片就必填。 | 只描述照片里确实有的东西。 |
| `stat` | 8 | 大数字，带单位。必须是对方的真实数字。 | 没有真实数字就不要用 hero-stat，改用 hero-poster 或 hero-arch。 |
| `stat_label` | 64 | 这个数字数的是什么，用大白话。 | 用对方的原话；不清楚就问。 |
| `stat_source` | 60 | 页面上显示的数字来源和时间。 | 写对方取数的地方。说不出来源就不用这个区块。 |
| `source` | 80 | 隐藏的来源记录：这条证据是谁、什么时候给的。只有页面上有带 data-sk-fictional 的可见元素、文字说明内容虚构时，才能写 fictional。 | 对方说不出来源，这条证据就不能用，换区块。 |
| `icon` | 12 | 联系方式图标：icon-phone、icon-mail、icon-pin、icon-clock。 | 按联系方式类型选。 |
| `contact_label` | 16 | 联系方式类型：电话、邮箱、地址、时间。 | 不知道具体内容就删掉这一格，两格也够。 |
| `contact_value` | 34 | 真实的电话、邮箱、地址或时间。 | 只写对方给的，绝不编造。 |
| `contact_href` | 200 | 这一格的 tel:、mailto: 或地图链接。 | 没有链接就写 #contact。 |
| `note_label` | 20 | 便签卡片上的小标签。 | 没有便签就连卡片一起删。 |
| `note` | 80 | 图片旁的一行事实：地点、时间、开业日期。 | 用对方给过的事实，否则删掉便签卡片。 |
| `quote` | 220 | 客户自己的原话，只能删减，不能改写。 | 没有真实引语就绝不代写。不要用任何引语区块，改用 proof-row 或 faq。 |
| `name` | 32 | 说这句话的人，用对方同意的称呼。 | 对方只同意用姓氏或昵称就照用。不知道是谁就不用这条引语。 |
| `role` | 48 | 对方的身份，或与商家的关系，以对方同意的为准。 | 不知道就删掉，绝不猜头衔。 |
| `prev_label` | 20 | 给读屏软件的“上一条”按钮名称。 | 写“上一条”。 |
| `next_label` | 20 | 给读屏软件的“下一条”按钮名称。 | 写“下一条”。 |
| `client` | 40 | 案例的主角，用对方同意的称呼。 | 可以写“利兹的一家家庭面包房”这样的真实描述。没有真实案例就改用 proof-row。 |
| `before_label` | 16 | 第一栏的小标题。 | 写“之前”。 |
| `did_label` | 16 | 第二栏的小标题。 | 写“我们做了什么”。 |
| `after_label` | 16 | 第三栏的小标题。 | 写“之后”。 |
| `before` | 160 | 之前的情况，只写事实。 | 只写对方讲过的。信息太少就不要用 case-note。 |
| `did` | 160 | 实际做了什么。 | 只写对方讲过的。 |
| `after` | 160 | 之后发生了什么变化，只写事实。 | 没有量化结果就写朴素的结果，并删掉数字格。 |
| `value` | 14 | 可核实的短事实：数字、年份或资质。 | 只用对方给的事实，两条就够。文字也行，比如“2009 年至今”“家庭经营”。 |
| `fact_label` | 64 | 这条事实是什么意思，用大白话。 | 用对方的话。 |
| `fact_source` | 48 | 别人可以到哪里核实。 | 没有地方核实就删掉。 |
| `period_a` | 14 | 第一种价格视图的名称，例如“按月”。 | 只有一种价格就删掉切换开关。 |
| `period_b` | 14 | 第二种价格视图的名称，例如“按年”。 | 随开关一起删。 |
| `plan` | 20 | 方案名称。 | 用对方自己的方案名。 |
| `blurb` | 80 | 这个方案适合谁，一行。 | 对方没说就删掉。 |
| `price` | 16 | 真实价格。还没定价可以写“询价”。 | 绝不估价，写“询价”。 |
| `price_alt` | 14 | 切换后显示的价格。 | 随开关一起删。 |
| `per` | 16 | 价格后的单位：每月、每节课。询价时可以留空。 | 用对方的单位。 |
| `per_alt` | 16 | 切换后价格的单位。 | 随开关一起删。 |
| `feature` | 44 | 这个方案包含的一项内容。 | 只写对方列出的，两行就够。 |
| `featured_label` | 18 | 被突出方案上的标签。 | 除非对方确实推荐某个方案，否则删掉。没有依据不要写“最受欢迎”。 |
| `q` | 80 | 客户真正会问的问题。 | 用对方真正听到过的问题。如果简报只给了事实，就写出这条事实所回答的朴素问题，并列入“推断的文字”。 |
| `a` | 320 | 答案，只用对方确认的事实。 | 只写已确认的。不知道就删掉这一组，一组也够。绝不用没有独立事实的问题来凑数。 |
| `link` | 20 | 页脚链接文字。 | 还不存在的链接就删掉。 |
| `link_href` | 200 | 页脚链接地址。 | 随链接一起删。 |
| `legal` | 90 | 商家名和版权信息。 | 只写商家名和当年年份。宿主页面有自己的页脚就删掉。 |

条目数量见目录。增减条目时：纯 HTML 整段复制或删除重复的元素；React 和 Vue 改数组。条目过多或过少都过不了检查器。

## 照片

纯 HTML：把 `data-slot-image` 元素里的 `<svg>` 换成 `<img src="photos/shop.jpg" alt="照片内容">`。React 和 Vue：在 `COPY` 里设置 `image` 和 `image_alt`，路径要是打包工具能访问到的（Vite 用 `public/` 文件夹）。照片存在本地，检查器会拒绝远程图片。只用对方拥有或有权使用的照片。

## 换色

不要手工改颜色。给两到四个品牌色，其余颜色由包自动推导，并计算每一组的对比度；达不到的组合会直接报错：

```
node scripts/recolour.mjs site/sections/tokens.css --brand "#1f4d36" --second "#f7c64f"
```

- `--brand`：主色，必填。
- `--second`：`hero-stat` 这类大色块用的第二色。不填就自动推导。
- `--paper`：页面底色，可选，深色就得到深色页面。衔接已有网站时用宿主自己的底色。
- `--ink`：文字颜色，可选。

要对页面实际引用的那份运行，通常是 `sections/tokens.css`；也可以把同样的参数传给 `scaffold.mjs`。它会删掉现成主题，因为页面不再用它们，之后检查器只测你的配色。检查器会按输入重新推导每个颜色。如果某个区块还显示品牌没有选的颜色（比如手工改了几个 token，留下现成的珊瑚色首屏），或者同一页的区块用了不同配色，就不通过。

每个彩色区域都有从自身推导的焦点环颜色。检查器会用真实键盘按 Tab 走遍页面，量每个焦点环和它背后实际颜色的对比度，至少 3:1。

## 衔接宿主页面

区块设计成不怕任何宿主样式，这也可能让它们看起来像是贴上去的。如果页面周围已经有网站，按顺序做这几步。

1. **颜色。** 把宿主的底色传给 `--paper`；宿主有可用的主色，就传给 `--brand`。
2. **字体，只在对方要求时改。** 这个包的标题字体是视觉的重要部分，除非网站主人想用自己的字体，否则保留。`--font host` 全部继承宿主字体。`--font host-body` 保留包的标题字体，只让正文继承。
3. **圆角和间距。** 量一下宿主的卡片。`--radius 12` 对齐圆角，`--space 24` 对齐纵向节奏，`--max 1100` 把 card 衔接的区块限制在宿主宽度内。对应 token：`--sk-join-radius`、`--sk-join-space`、`--sk-join-max`、`--sk-radius-sm`、`-md`、`-lg`、`--sk-max`。
4. **接缝。** 给每个挨着宿主内容的区块设 `seam`（纯 HTML 里是 `data-sk-seam`）：
   - `gap`：通栏，上下留空。先试这个。
   - `rule`：顶部一条线，适合紧贴朴素页眉的区块。
   - `card`：内缩的圆角面板，适合用卡片搭起来的宿主。
   区块彼此相邻时不要加，让它们连成一体。
5. **第一屏。** 页眉不太高时，首屏自己就能适应常见屏幕。如果检查器报告按钮掉到第一屏下面，就把 `--host-header` 设为它给出的数字。设了标题会变小，所以没有报告就不要设。
6. **只留一个 h1。** 宿主已有 h1 时，给首屏设 `heading: h2`（纯 HTML 里直接改标签），不要动宿主。页面有两个 h1 时检查器不通过。
7. **顺序。** 首屏放在宿主页眉下面，第一个。宿主自己的区块保持原有顺序，放在包的区块之间。宿主有自己的页脚时，`footer-cta` 作为最后的邀请保留，删掉它的 `legal` 和 `links`，免得两个页脚重复。

**什么时候改宿主页眉。** 只有网站主人同意才改，因为那是对方的网站。页眉严重不协调，或者高到首屏的按钮进不了第一屏时，就去问。然后要么用可选的 `site-header` 区块，名称和链接不变，要么保留原页眉，并在报告里说明衔接受它限制。绝不能悄悄改。包的样式放在宿主 CSS 之后，实测加载顺序没有影响。SLOT 注释和 `data-slot` 属性可以留着：它们对页面没有影响，检查器还要读。

## 遇到特殊情况

- **信息太少。** 只复述对方自己说过的事实。用 `hero-poster`、`proof-row` 或 `faq`，这几个区块内容少也站得住。按上表“信息太少时”一栏处理。把所有推断出来的文字列在报告里，让对方修改。
- **没有人能回答。** 只用不需要证据的区块，继续做，列出你的假设，把缺的东西写成报告里的问题。绝不用编造的说法填空。
- **没有真实链接。** 宿主页面上已有合适的锚点也可以用，并列入假设。否则用 `#contact`，并在要跳到的区块上加 `anchor: contact`（HTML 里是 `id="contact"`），或列入假设。绝不能只写 `#`。
- **还没定价。** 写“询价”，能过检查器，版面也放得下。
- **对方要不同的长度。** 上限是有原因的：每个区块都用达到上限的长文案和极短文案排过版。超了就删文案，不要改 CSS。很短的文案没有问题。
- **标题报“孤字”。** 改写标题。不要手动换行，换个宽度就错了。
- **宿主页面本身有外部脚本、字体或横向溢出。** 给检查器加 `--host-ok`，让它只评判区块。并在报告里提到这些请求。
- **按钮掉到第一屏下面。** 检查器用九种常见尺寸测第一个首屏，把它上方的内容也算进去。设置 `--host-header`，缩短标题或说明，或者问问宿主页眉能不能改。不要去缩 CSS。
- **宿主样式还是赢了。** 这个包能压住元素选择器和类选择器的规则，但带 `#id` 或 `!important` 的规则仍可能赢。检查器会报 `host css` 或颜色问题。把那条宿主规则去掉，或缩小它的范围。
- **窄栏。** 区块按容器宽度而不是窗口宽度响应，放进一栏也能用。700 像素以上效果最好。
- **同一页有两个 FAQ。** 给第二个的 `<details>` 换一个 `name`，否则两个区块共用一个展开状态。
- **对方要多种语言。** 每种语言一个区块版本，不要在一个区块里混用。

## 交付前检查

- [ ] `node scripts/check.mjs` 退出码为 0，没有用 `--allow-samples` 或 `--static`。
- [ ] `node scripts/drive.mjs` 通过，所有控件都在三种宽度、开启和减弱动效下真实点击过。
- [ ] 每个选用的区块，我都在 1280、768、390 像素宽度下看过。
- [ ] 每句引语、每个姓名、数字和价格都来自对方，每条证据都有真实的 `source`。
- [ ] 没有留下样例提示条或 `data-sample`，页面没有任何外部请求。
- [ ] 颜色来自 `scripts/recolour.mjs` 或现成主题，不是手工修改。
- [ ] 页面只有一个 h1，第一个首屏的按钮在第一屏内。
- [ ] 没有为填版面凑数，真实姓名旁没有未经同意的绘制头像。
- [ ] 报告里列出了推断的文字、假设，以及还在等真实目标的 `#contact` 链接。

## 什么时候不要用

- 从零做一个全新品牌或网站，视觉本身就是任务的时候。
- 网页应用的操作界面：表格、表单、仪表盘。这些区块是营销用的。
- 网站有严格的设计系统，区块必须完全贴合的时候。
- 对方证实不了的证据。这个包会拒绝。

## 环境要求

Node 18 或更高版本。静态检查和区块本身不需要别的东西。渲染检查和操作脚本需要 Playwright：`npm install playwright && npx playwright install chromium`，或把 `NODE_PATH` 指向装有它的 `node_modules`。没有 Playwright 时，`check.mjs` 退出码是 3 而不是 0，因为看得见的东西都没验证；`--static` 只查源码，并会说明这不算交付通过。检查器每页大约 20 秒，操作脚本跑完 17 个区块大约 30 秒。区块需要支持容器查询的浏览器（2023 年以后）。`--app` 里的 Vite 只用于示例。除了框架本身，任何区块都不需要别的依赖。