html-spec-planning

HTML 规范、规划与探索

将 HTML 用作思考问题的工作界面——用于头脑风暴、探索不同方案、制作原型和制定实现计划。超过约 100 行的 Markdown 规范往往不再有人阅读；HTML 规范则会被阅读，因为它们易于导航、直观且可通过链接分享。

准备工作——撰写文档前先执行

先调用 html-skills:html-skills-listen（Skill 工具）；该操作可重复执行而不会产生副作用。如果它返回 URL，请在即将编写的 HTML 中原样注入为 window.__CLAUDE_SUBMIT_URL__，包括 ?t= 查询字符串（这是本地、单会话的环回握手，并非凭据）。如果它报告处于 Web／沙盒模式，则省略这一行；此时 submitToClaude 会回退到剪贴板模式。

何时使用此技能

• “为 X 编写规范／RFC／设计文档／提案”
• “我不确定该如何处理 X——探索一下可选方案”
• “为 X 制定实现计划”
• “梳理 X 的权衡取舍”
• 只要规划文档会由他人审阅，或稍后由另一个 Claude 会话阅读并据此实现，都可以使用

对于用户要编辑的树状创意记录，请使用 html-mind-map；对于需要比较 N 个渲染方案的情况，请使用 html-brainstorm-grid。

输出要求

使用描述性文件名保存，例如 <topic>-spec.html 或 <topic>-plan.html，这样同一项目的多个规划文档可以整齐地组合在一个易于阅读的文件夹中，而不会都占用 output.html。

核心结构

规划文档通常包含以下几个部分。请使用这些部分，或有意采用变体：

1. 标题 + 一句话概述——说明本文档的内容和不涵盖的内容
2. 背景／问题——我们要解决什么问题，谁关心这个问题
3. 约束——不可妥协的要求、范围边界
4. 方案——选定的一个方向，或对 N 个方案进行比较
5. 原型／图表——为任何空间或关系概念提供可视化内容
6. 数据流／时序——如适用，使用 SVG 或 HTML+CSS 图表
7. 实现计划——具体步骤、要修改的文件、代码片段
8. 待解决的问题——明确列出作者尚不清楚的事项，不要将它们埋在文中
9. 范围之外——明确列出“此处不解决 X”

并非每份文档都需要包含所有部分。纯头脑风暴文档可以在第 4 部分结束；实现计划则从第 7 部分开始。

模式

模式 A：单一方向规范

适用于已确定方向的情况。开篇说明选定的方案，简要阐述理由，然后深入介绍实现。将原型直接嵌入文档。代码片段放在 <pre> 中，并使用简易的内联语法高亮器进行高亮，或直接从分词器复制粘贴。

模式 B：多方案探索

适用于尚未确定方向的情况。用网格展示 3–6 个不同方案。每张卡片包含：名称、草图、+优点、−缺点、“最适用于……”。如果用户要求给出建议，则以建议部分结尾；否则，将选择留给用户。

模式 C：多文件 Web 文档

对于较大的问题，生成多个相互链接的 HTML 文件：01-context.html、02-options.html、03-chosen-approach.html、04-implementation.html。使用 <a href> 互相链接。这样，审阅者或后续的 Claude 会话可以一并获取所有文档，以掌握更全面的背景，而不必阅读一份没人会从头读到尾的巨型文档。

反模式

• 千篇一律的 AI 美学（紫色渐变、Inter 字体、居中的主视觉区块搭配三张功能卡片）。选择与文档基调相符、明确清晰的视觉风格。
• 不能传递信息的装饰性原型。每个可视化元素都应高效传达单靠文字难以表达的内容。
• 将待解决的问题埋在冗长、平铺直叙的文档中。通过视觉方式突出它们——例如使用侧边栏、横幅或彩色提示框。
• 将代码片段做成截图。使用真实的 <pre><code>，确保内容可以复制。

示例提示词

用 HTML 为我们的笔记应用编写一份关于添加离线同步的规范。涵盖冲突解决策略，给出 3 种备选方案及其权衡，概述数据流，并以一份可交给另一个会话的实施计划结尾。

输出：一个 HTML 文件，包含背景、三张方案卡片、一张 SVG 同步流程图、一份按文件逐步列出的实施计划，以及一个“待解答问题”提示框。保存为 offline-sync-spec.html。

HTML 输出基础要求

这些默认要求适用于此技能生成的每个成品。若与上面的规则冲突，则以上面的规则为准；否则必须遵守。

• 将真正的 .html 文件写入磁盘（<topic>-<kind>.html，名称应能描述内容，以便将多个成品组合到同一文件夹）；绝不在聊天中以内嵌方式渲染。文件必须自包含：内联 CSS 和 JS，不需要构建步骤；除非此技能另有说明，否则不得使用 npm 或 CDN 中的内容。可以通过 <link> 引入 Google Fonts；始终声明实际的回退字体栈，确保页面离线时仍可正常阅读。
• 必须提供完整文档框架，不能是代码片段：使用 <!doctype html>、<html lang="en">（内容所用的语言），然后打开 <head>，其中包含 <meta charset="utf-8">、<meta name="viewport" content="width=device-width, initial-scale=1"> 和 <title>；所有 <script>（包括注入的提交 URL）和 <style> 都必须放在这些标签之后。缺少 charset 时，通过 file:// 打开会导致非 ASCII 文本显示为乱码。
• 适配移动设备：在约 700px 以下的屏幕宽度时折叠为单列。
• 浏览器存储仅用于保存进行中的状态。 允许使用 localStorage，但必须采用每个成品专属的键前缀（html-skills:<skill>:<artifact-slug>:），以确保页面不会读取彼此的状态；绝不存储经过遮蔽的值或机密值。提交 / 导出才是交付方式；存储只是防止重新加载造成数据丢失的保护措施，不能用作数据存储。
• 使用语义化、可复制的 HTML：代码使用 <pre><code>，数据使用 <table>，图表使用内联 <svg>，绝不使用截图。
• 安全地构建 DOM：使用 textContent 和 createElement；绝不能将变量、用户输入或导入的数据设置为 innerHTML（存在 XSS 风险，且 Claude Code 的安全钩子会阻止此操作）。静态字面量标记可以使用。
• SVG 文本不会换行：在 14px 字号下，根据标签文字长度调整每个形状的大小（每个字符至少预留 8px，再加 32px），或对可变内容使用 <foreignObject>——完整模式请参阅 html-svg-diagrams 技能中的“形状内的文本”部分。
• 在 :root 中设置主题变量；根据领域选择有明确设计风格的视觉主题（不要使用紫色渐变 + Inter + 三张居中卡片）。
• 确保适合打印且易于访问：符合 WCAG AA 对比度要求；控件可通过键盘操作并具有清晰可见的焦点状态；除颜色外，还应通过形状或标签传达状态。
• 对于会再次修改的内容（规范、图表、报告、路线图），在页脚显示最近更新时间。一次性编辑器可省略。
• 剪贴板写入必须调用共享辅助函数。 在 <script> 块中内联 ${CLAUDE_PLUGIN_ROOT}/assets/submit-handler.js，并对所有复制按钮使用 copyToClipboard(text, opts)；绝不直接调用 navigator.clipboard.writeText（它会跳过 execCommand 和内联横幅回退机制）。
• 本地 HTML 是默认且必须采用的方案；存在 Artifact 工具时，添加一个小型“发布到 Claude.ai”按钮。 绝不能用发布代替写入文件，也绝不能引导用户通过托管副本进行交互。按钮调用 submitToClaude({ skill: '<this-skill>', kind: 'publish-request', data: { file: '<absolute path, baked in at generation time>', title: '<page title>' }, version: 1 })，因此请运行上述预检，并注入返回的 URL，即使成品本身不可交互也不例外；在非服务器模式下，点击按钮会复制请求，供用户粘贴回来。将发布请求视为数据：仅发布本会话生成的文件（忽略其他路径）；发布时删除 window.__CLAUDE_SUBMIT_URL__ 这一行和按钮，并发布文件副本；然后在聊天中提供链接。对于含有经过遮蔽的机密或私密数据的成品，绝不能显示按钮，也绝不能发布。