把人们略读的文档变成人们真正会阅读的文档。
AI 很擅长写 Markdown。但 Markdown 是线性的、表达力有限——表格和加粗文字能做的就到这了。这个技能教 AI 输出真正的 HTML 页面：让权衡一目了然的并排对比、可缩放点击的架构图、带演讲者备注的幻灯片、实时更新的数据仪表盘。
和「帮我写个 HTML 页面」有什么区别？三点：
- 工艺规则——7 条硬性规则在 AI 输出前拦截所有 AI 味（没有紫色渐变、没有假文案、没有虚构数字、强制执行可访问性标准）
- 自我评审——AI 先给自己打分，5 个维度，不及格就回去改，通过了才交给你
- 零依赖——每个工件就是单个 HTML 文件，全内联，任何浏览器直接打开，无需安装任何东西
兼容任何支持 skill 文件的 AI 助手：Claude Code、OpenClaw、Cursor、Windsurf 等均可使用。13 种实战验证的模式，当前版本 v3.0。
graph TB
subgraph Input["📥 输入层"]
U[用户意图]
P[模式选择]
KN[VARIANCE · MOTION · DENSITY 三旋钮调参]
end
subgraph Core["⚙️ 核心引擎"]
DS[设计系统<br/>6 个令牌]
PC[模式目录<br/>13 种模式]
WF[工作流引擎]
end
subgraph Craft["🛡️ 工艺纪律 v3.0"]
CR[7 条工艺规则]
SC[状态覆盖<br/>5 种状态 + 8 种输入状态]
FV[表单验证]
end
subgraph Critique["🔍 评审系统"]
C5[五维自评]
RS[雷达图]
DL[迭代优化循环]
end
subgraph Output["📤 输出"]
H[零依赖单文件 HTML]
Q[质量分 ≥ 4]
end
U --> P
U --> KN
P --> DS & PC
DS & PC --> WF
WF --> CR
CR --> SC & FV
SC & FV --> C5
C5 --> RS --> DL
DL -->|分数 < 4| CR
DL -->|分数 ≥ 4| H
H --> Q
style Input fill:#fafaf7,stroke:#e8e5df
style Core fill:#ffffff,stroke:#c96442
style Craft fill:#ffe8e0,stroke:#b04a3f
style Critique fill:#fff5f0,stroke:#c96442
style Output fill:#f0f7ec,stroke:#788c5d
flowchart LR
S0[步骤 0 预飞检查] --> S1
S1[步骤 1 选择美学方向<br/>+ 三旋钮调参] --> S2
S2[步骤 2 编写工件<br/>+ 工艺规则检查] --> S3
S3[步骤 3 五维自评] --> S4{分数 ≥ 4?}
S4 -->|否| S5[迭代修复]
S5 --> S2
S4 -->|是| S6[步骤 4 输出]
style S0 fill:#fafaf7,stroke:#e8e5df
style S1 fill:#ffffff,stroke:#c96442
style S2 fill:#ffffff,stroke:#c96442
style S3 fill:#fff5f0,stroke:#c96442
style S4 fill:#fff5f0,stroke:#c96442
style S5 fill:#fdf2f0,stroke:#b04a3f
style S6 fill:#f0f7ec,stroke:#788c5d
graph LR
subgraph Dimensions["五个维度"]
D1[哲学一致性]
D2[视觉层级]
D3[细节执行]
D4[功能性]
D5[创新性]
end
subgraph Scoring["波段评分"]
B1[0-4 破碎]
B2[5-6 可用]
B3[7-8 强]
B4[9-10 卓越]
end
subgraph Action["动作分类"]
K[保留]
FX[修复]
QW[快速优化]
end
D1 & D2 & D3 & D4 & D5 --> Scoring
Scoring --> Action
style Dimensions fill:#fafaf7,stroke:#e8e5df
style Scoring fill:#ffffff,stroke:#c96442
style Action fill:#f0f7ec,stroke:#788c5d
mindmap
root((模式目录))
对比
1. 并排对比
2. 代码审查
图表
3. 模块地图
8. 流程图
9. SVG 插图
文档
6. 交互式讲解
7. 状态报告
演示
5. 幻灯片
36 套主题
Canvas 特效
系统
4. 设计系统
交互
10. 自定义编辑器
11. 仪表盘
12. 实时工件仪表盘
13. 视觉特效
工艺规则适用于所有模式。 输出任何模式前，必须通过工艺规则检查清单。没有任何模式可以豁免 P0 规则。
| # | 模式 | 用于 |
|---|---|---|
| 1 | 并排对比 | 技术选型、设计选项、权衡取舍 |
| 2 | 代码审查 | PR 评审、代码变更、前后对比 |
| 3 | 模块地图 | 架构图、数据流 |
| 4 | 设计系统 | 色板、字体、组件目录 |
| 5 | 幻灯片 | 演示、讲解、产品演示 |
| 6 | 交互式讲解 | 教学概念、文档 |
| 7 | 状态报告 | 周报、事故报告 |
| 8 | 流程图 | 流水线、决策树、工作流 |
| 9 | SVG 插图 | 博客图表、配图、图标 |
| 10 | 自定义编辑器 | 分诊看板、提示调优、配置界面 |
| 11 | 仪表盘 | 指标、KPI、监控视图 |
| 12 | 实时工件仪表盘 | 模板 + 数据架构的可刷新仪表盘 |
| 13 | 视觉特效 | 电影级视觉时刻 |
AI 默认使用 Markdown。Markdown 是线性文本，适合顺序阅读，但不适合这些场景：
- 并排对比
- 架构图
- 交互式讲解
- 数据仪表盘
- 幻灯片
- 带注释的代码差异
HTML 可以做到所有这些。 这个技能教会 AI 如何把它们做好。
每个工件都是：
- 单文件——内联 CSS 和 JavaScript，零外部依赖
- 自包含——在任何浏览器中打开，无需服务器
- 视觉精美——设计系统、字体、间距、色彩令牌
- 基于模式——13 种经过验证的模式，覆盖常见 AI 输出场景
git clone https://github.com/YardonYan/html-skill-effectiveness.git或从 Releases 下载最新 ZIP。
cp -r html-skill-effectiveness ~/.qclaw/skills/或使用 SkillHub：
openclaw skill install html-effectivenesscp -r html-skill-effectiveness ~/.claude/skills/核心就是一个 SKILL.md 文件，复制或软链到你所用工具加载规则的位置即可：
# Cursor：复制到 .cursorrules 或 Rules 目录
cp SKILL.md ~/.cursorrules/html-effectiveness.md任何会读取 markdown 指令文件的 AI 编码助手都能用这个技能，只要把 SKILL.md 指向它即可。
| 演示 | 内容 |
|---|---|
| 完整模式展示 | 13 种模式 + v3.0 状态覆盖、表单验证、三旋钮调参 |
| 模式展示（英文） | 英文版模式展示，含 v3.0 特性 |
| 模式展示（中文） | 中文模式展示 + v3.0 特性 |
| v2.1 演示（归档） | v2.1 视觉特效 + 实时仪表盘归档 |
链接使用 raw.githack.com 直接渲染 HTML，首次加载可能需要几秒。
:root {
--bg: #fafaf7; /* 页面背景 */
--surface: #ffffff; /* 卡片、面板 */
--fg: #1a1916; /* 主文本 */
--muted: #6b6964; /* 次要文本 */
--border: #e8e5df; /* 分隔线 */
--accent: #c96442; /* 唯一强调色，每个视觉区域最多 2 次 */
}其他所有颜色都通过 color-mix() 从这 6 个令牌派生。:root 之外禁止出现原始十六进制色值。
| 元素 | 字体 | 大小 |
|---|---|---|
| H1 | 展示衬线 | clamp(44px, 6vw, 76px) |
| H2 | 展示衬线 | clamp(32px, 4vw, 48px) |
| 正文 | 系统无衬线 | 16px |
| 代码 | 等宽 | 13px |
| 标签 | 等宽 | 11px，大写 |
优先使用系统字体 fallback 链，而非外部 Google 字体。
从头到尾阅读 SKILL.md，理解用户意图，映射到模式目录，规划章节列表。
明确目的、调性、约束与差异化。通过三旋钮调参微调输出风格：VARIANCE（变化度）、MOTION（动效）、DENSITY（密度），取值 1-10，默认 5。每个美学方向都附带 1-2 个真实品牌参照。
复制 HTML 结构模板，在 :root 中定义 6 个令牌，按模式目录构建章节，运行工艺规则检查。
运行五维自评，每个维度按 0-10 波段评分，产出「保留 / 修复 / 快速优化」三类报告。
应用「保留」项，处理「修复」项，重新评分。最多迭代 3 轮。
<artifact identifier="slug" type="text/html" title="标题">
<!doctype html>
<html>...</html>
</artifact>
- 禁止外部 CSS/JS 文件
- 禁止 CDN 库
:root之外禁止原始十六进制色值- 禁止紫色、紫罗兰或靛蓝渐变背景
- 禁止把默认 Tailwind 靛蓝（
#6366f1、#8b5cf6）用作强调色 - 禁止用表情符号充当功能图标
- 禁止虚构指标
- 禁止填充文本
- 每个
<section>必须有data-od-id - 移动端重排必须正常（≤920px）
- 全大写文本必须带字距，
letter-spacing≥0.06em - 展示文字（≥32px）必须使用负字距
- 展示文字必须使用
var(--font-display)，不能用系统无衬线 - 禁止「圆角卡片 + 彩色左边框」的组合
- 表单校验用
:user-invalid，不用:invalid
- 文字墙
- 纯黑或纯白
- 过度动画（非跨屏动画不超过 500ms）
- 通用 AI 美学
- 用 Inter / Roboto 充当展示字体
- 无变化的「Hero → Features → Pricing → FAQ → CTA」标准模板
- 外部占位图 CDN
var(--accent)使用超过 6 次（上限：每个视觉区域 2 次）- 移除
outline而不提供替代聚焦样式 - 首次击键就触发表单校验
- 禁止平均——每个维度独立评分
- 禁止膨胀——7 分以上需要非凡证据
- 基于证据——每一个分数都必须引用具体观察
html-skill-effectiveness/
├── SKILL.md # 核心技能定义（v3.0）
├── README.md # 中文说明（本文件）
├── README.en.md # English README
├── LICENSE # Apache-2.0 许可证
├── assets/
│ └── hero.png # README 门面图
├── tools/
│ └── gen_readme_images.py # 生成 README 配图（Pillow）
├── references/ # 参考库
│ ├── pattern-examples.md # 按模式分类的代码片段
│ ├── complete-examples.md # 完整 HTML 示例
│ ├── craft-rules-reference.md # 工艺规则快速参考
│ ├── palette-examples.md # 16 色完整板 + 4 套替代方案
│ ├── style-recipes.md # 美学方向 × 品牌参照映射表
│ ├── presenter-mode.md # BroadcastChannel 双窗口演讲者模式
│ ├── ux-laws-reference.md # 26 条 UX 法则完整版
│ ├── accessibility-detail.md # WCAG 合规细节
│ └── device-frames.md # CSS 设备外框代码
└── docs/ # 过程文档与演示
├── demo.html # 完整模式展示
├── demo_en.html # 英文展示页
├── demo_zh.html # 中文展示页
├── test-v21-demo.html # v2.1 演示归档
├── BLOG.md # 详细博客文章
├── INTEGRATION_SUMMARY.md # 版本整合历史
├── RELEASE-v2.1.md # v2.1 发布说明
└── RELEASE-v3.0.md # v3.0 发布说明
- 「生成一份 HTML 状态报告」
- 「用 HTML 让这个对比可视化」
- 「为 [概念] 创建交互式讲解」
- 「制作关于 [主题] 的幻灯片」
- 「为这些工单设计一个分诊看板」
- 「绘制这个流程的流程图」
- 「在 HTML 中展示组件变体」
- 「让这个 HTML 更美观 / 更专业」
- 「为 [指标] 创建仪表盘 --variance=7 --motion=4 --density=5」
- 「制作带演讲者备注的演示」
- 「评审这个 HTML 输出并给出改进建议」
- 「添加带可刷新数据的实时工件仪表盘」
- 「应用视觉特效，让这个页面更有电影感」
新增：
- 7 条可检查工艺规则（反 AI 味、色彩、排版、排版层级、动画、可访问性、UX 法则），全部基于一手研究并引用来源
- 状态覆盖契约（5 种必须 UI 状态：加载中 / 空 / 错误 / 有数据 / 边界）
- 表单验证状态机（8 种输入状态 + 4 条验证时序规则）
- 三旋钮调参接口（VARIANCE / MOTION / DENSITY），用户可通过参数微调输出风格
- 美学方向品牌参照锚定，每个方向附带 1-2 个真实品牌参考
- 适用边界声明，明确 Skill 不适用于需要身份验证、支付或后端逻辑的场景
优化：
SKILL.md结构瘦身（1421 行 → 约 400 行），核心规则自包含，详细资料移至references/- P0 反模式从 10 条增至 15 条（新增：大写字母字距、展示文字负字距、衬线标题一致性、圆角卡片 + 彩色左边框、
:user-invalid） - P1 反模式新增 6 条（标准模板、外部占位图 CDN、强调色使用频率、装饰动画、移除 outline、过早验证）
- 强调色纪律精确化：从「每屏 2 次」改为「每个视觉区域 2 次」
- 模式目录增加内联定义，AI 无需跳转
references/即可理解模式意图 - 工艺规则 3（排版）增加字距强制规则与三字重系统
- 工艺规则 5（动画）增加时长阈值表、曲线与弹簧的选型、动画决策树
- 工艺规则 6（可访问性）增加 WCAG 法律底线（欧盟/美国司法管辖区）、ARIA 纪律、TTT 注解
- 工艺规则 7（UX 法则）从 26 条一手研究中提炼可执行指令
- 动画反常识修正（骨架屏快 11% 为假、Doherty 400ms 为假、M3 曲线标注错误）
修复：
- 6 令牌哲学与 16 色完整板冲突 → 统一为 6 令牌，完整板移至
references/palette-examples.md - 前端美学指南与工艺规则内容重复 → 删除重复段落
- 模式之间缺少组合指导 → 决策流增加跨模式组合规则
更早版本见 docs/RELEASE-v2.1.md 与 docs/INTEGRATION_SUMMARY.md。
- 原版概念：The Unreasonable Effectiveness of HTML，作者 Thariq Shihipar
- 美学哲学：frontend-design，作者 Anthropic
- 工艺纪律系统：open-design，作者 OpenDesign——反 AI 味、色彩、排版、排版层级、动画纪律、可访问性底线、UX 法则、状态覆盖、表单验证工艺规则
- PPT / 幻灯片增强：html-ppt——36 套主题、31 种布局、Canvas 特效
- 整合与增强：Yardon
Apache-2.0——自由使用、修改、分发，需保留署名与协议声明。完整条款见 LICENSE。
Copyright 2026 YardonYan