✨ 一套让 AI 在生成前端时遵守设计规范的指令系统。
- 🌐 网页：landing page、产品页、作品集
- 📝 HTML 报告：调研报告、白皮书、分析文档（图文并茂，支持打印）
- 📽️ HTML PPT：演示幻灯片（全屏翻页、键盘/触摸控制）
Vibe Coding：用自然语言让 AI 生成前端代码的开发方式。
AI 能写出能跑的前端代码，但产出的页面在设计层面高度不稳定。具体表现为五个可观察、可复现的现象：
🌐 跨模型漂移 同一句需求给不同模型，出来的页面完全不一样。Claude 做的和 GPT 做的风格对不上。
💨 上下文蒸发 同一个模型在长对话中，前面定好的设计方向会被后面的内容冲掉。第 5 轮还好，第 20 轮就开始跑偏。
💥 Agent 碰撞 多个 AI agent 各做一个 section，拼在一起不像同一个页面。Hero 是极简风，Feature 变成了 SaaS 模板，Footer 又是另一种风格。
🪄 迭代意外修改 用户说"把标题改大一点"，模型改了标题，顺手把间距、配色、按钮样式也改了——用户没要求这些改动。
🎲 模糊需求随机产出 用户说"高端一点""科技感"，每次出来的结果都不一样，因为这些词没有确定性的设计映射。
AI 能执行设计（写 CSS、排布局），但在执行之前没有经过设计决策。它没有一个独立于对话上下文的、跨模型通用的设计规则文件来约束它。
💡 代码能力够了，设计约束缺失了。
一套在 AI 工作流中注入设计约束的指令系统，让 AI 生成的前端页面：
🤖 不靠"猜"——把模糊词（高端/科技感）翻译成具体 token 值
🔗 不漂移——换模型/换工具/换 session，规则始终一致
🛡️ 有门槛——设计决策在前，代码生成在后
📋 可审计——每次修改都出影响评估，HTML 不会悄悄乱改
使用流程分成两条线：设计工作流和本地工具流。
┌─────────────────────────────────────────────────────────────┐
│ 触发 Preflight 确认类型 需求摄入 PRD确认 │
│ ↓ ↓ ↓ ↓ ↓ │
│ /htmlcraft 扫描项目 🌐网页 一轮收齐 你确认后 │
│ 交付物 📝报告 11项信息 才进下一步 │
│ 情况 📽️PPT │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 参考依据确认 视觉论点锁定 Hero原型确认 │
│ ↓ ↓ ↓ │
│ 有图→拆解分析 给出2~3个候选 archetype是哪种 │
│ 无图→明确告知 最终收敛为1个 第一屏感受什么 │
│ 三轮确认 主论点 CTA强还是轻引导 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 设计系统确认 生成规格文件 │
│ ↓ ↓ │
│ Group A: 排版+色彩 5个核心交付物 │
│ Group B: 组件+动效 ┌──────────────────────────┐ │
│ ↓ │ design-tokens.css 📌 │ │
│ 先过设计律令核对 │ design-tokens.json │ │
│ (字体/颜色槽/ │ design-spec.md │ │
│ 按钮高度/ │ html-handoff.md │ │
│ 图标规则/…) │ .htmlcraft.md │ │
│ └──────────────────────────┘ │
│ ↓ │
│ 确认后进入构建 ←←←←←←←←←←←←←←←←←←← │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ HTML 映射 修改影响评估 审计回执 │
│ ↓ ↓ ↓ │
│ 引token.css 改什么/影响多大 本轮通过了吗 │
│ 搭shell→Hero→ 触不触设计系统 Hero偏没偏 │
│ Section→CTA→ 改token还是 Token漂没漂 │
│ Footer→Polish token+HTML一起改 连续3轮加审 │
│ ↓ ↓ │
│ HTML里不允许硬编码 ←←←←←←←←←←←←←←←← 最终审计通过 │
│ 颜色/间距/圆角/字体 才算交付 │
└─────────────────────────────────────────────────────────────┘
读 design-tokens.css → .htmlcraft.md → design-spec.md →
html-handoff.md → index.html → 直接出审计结果
如果要改：审计 → 评估 → 修改 → 回执 → 复核
┌──────────┐ ┌────────────────────┐ ┌───────────────┐
│ 第一步 │ → │ 第二步 │ → │ 第三步 │
│ 进入根目录 │ │ 运行 start-dashboard │ │打开 localhost │
│ │ │ 检查Node/npm/python3 │ │ :3000 │
│ cd html- │ │ 检查端口，必要时安装 │ │ │
│ craft/ │ │ dashboard依赖 │ │ 🌐 浏览器 │
└──────────┘ └────────────────────┘ └───────────────┘
↓
┌───────────────┐
│ 第四步 │
│ Dashboard监听 │
│ 文件变化自动 │
│ 更新状态+触发 │
│ Python审计 │
└───────────────┘
Dashboard 是用来"看"的，不是用来"做"的。
🆕 新项目：需求 → PRD → 参考图 → 视觉论点 → 设计系统 → 规格文件 → HTML → 审计
📦 老项目：读交付物 → 审计 → 修改 → 再审计
每个项目生成 5 个文件：
| 📄 文件 | 🎯 作用 |
|---|---|
design-tokens.css |
第一真值。所有颜色、间距、字体变量。HTML 只能引用变量，不能硬编码 |
design-tokens.json |
机器可读镜像，供工具链消费 |
design-spec.md |
完整设计规格，人读版本 |
html-handoff.md |
实现交接文档，约束 HTML 映射方式 |
.htmlcraft.md |
项目上下文入口。新会话、新模型读这一个文件就能接手，不用重走设计流程 |
htmlcraft/
├── SKILL.md # 主规则文件（AI agent 读取入口）
├── references/
│ ├── universal-rules.md # 通用设计基本法（底层规则）
│ ├── philosophy-guide.md # 视觉论点生成指南
│ ├── homepage-layout-library.md # Hero 原型库
│ ├── typography-system.md # 字体系统规范
│ ├── cross-model-consistency.md # 跨模型一致性协议
│ ├── verification-playbook.md # 构建后验证清单
│ └── ... # 其他专项参考文件
├── scripts/
│ ├── audit-html.sh # HTML 审计脚本
│ └── html_design_report.py # 设计报告生成
├── dashboard/ # 可视化审计面板
└── agents/ # 各 AI 工具的 agent 配置
├── claude.yaml
├── cursor.mdc
├── openai.yaml
└── ...
在任何支持 Skill 的 IDE 或 AI 编码工具中，通过以下任一命令激活：
/htmlcraft
/using htmlcraft
激活后，HTMLCraft 会引导你完成：PRD 确认 → 参考依据 → 视觉论点锁定 → 设计系统确认 → 规格文件生成 → HTML 构建 → 审计交付。
支持的环境包括但不限于：OpenClaw、Cursor、Claude Code，以及所有兼容 Skill 机制的 AI 编码工具。
字体家族 最多 2 个
颜色命名槽 恰好 5 个：primary / accent / bg / fg / muted
按钮高度 全页统一，最小 44px
卡片定义 shadow 或 border，二选一，不能混用
图标 SVG only，一个 family，尺寸只用 16/20/24px
正文行长 最多 70ch
正文最小字号 16px
间距基数 8px
对比度 正文 ≥ 4.5:1（WCAG AA）
完整律令见 SKILL.md。
本项目的规则体系参考了以下 Skill 和设计规范：
- Anthropic frontend-design — 设计质量标准与前端构建原则
- UI/UX Pro Max — UI/UX 设计系统生成与色彩规范
- Vercel Web Design Guidelines — 间距、排版、动效与交互标准
- Impeccable — 排版细节与可访问性规范
- Pretext — 文本测量与布局算法（@chenglou/pretext）
WeChat：Eimy10