hayatosc/html-artifacts

HTML Artifacts

交付一个可从磁盘打开且离线工作的人用 .html 文件。使用打包的日本数字机构设计系统（DADS）文档适配器，而非CDN或框架。保持面向Agent的源文件为Markdown格式。这是一个非官方的文档适配器，并非DADS所有组件的完整实现。

步骤

1. 了解读者和源信息

在选择结构之前，先确定主题、受众、目的和证据。对于计划，保留目标、完成证据、约束条件、检查点和风险。包含一个描述性标题、简短的定位说明以及来源/日期出处。仅在必要时添加目录；不要强制规定章节数量或图表。

从零开始解释：先描述具体情境和主题的功能，然后介绍技术名称。首次使用专业术语时进行定义，每个步骤只传达一个想法，仅当图片比文字更能清晰说明时使用带标注的图片。仅在类比与其联系和局限性明确时使用；保持成人化、直接的口吻，除非为儿童写作。新人应能理解发生了什么、为什么以及接下来该做什么。

2. 机械构建——不要重新输入CSS

阅读 build.md。从当前文件所在位置解析技能目录，而不是当前项目的working目录。使用Python 3.10+：

python /absolute/path/to/html-artifacts/scripts/build.py /absolute/path/to/output.html --title "Subject"

构建器读取 assets/template.html，嵌入 所有 assets/dads.css 和 assets/print.js，并插入离线内容安全策略（CSP）。它拒绝覆盖已有文件。无需下载、软件包安装、服务器、打包工具或相邻的静态资源文件夹。在此仓库中，也可使用其Python运行器（uv run python 同样适用）。

3. 编辑内容，而非基础

编辑生成的文件。替换初始的解释性内容、出处和目录；删除不需要的章节。保持 style#dads-css、script#dads-print、CSP、字符集、视口和 only light 颜色方案元数据完好无缺。

• 仅使用内联SVG和嵌入的光栅图像。不能有远程/本地样式表、脚本、字体、图像、iframe、import、fetch或分析依赖。普通的源超链接可以指向网络；将本地源文件标记为文本，而非断开的相对链接。
• 使用语义化HTML和打包的类/令牌。阅读 dads.md 了解类API、官方来源和本地适配。不要将此适配器的修改器与上游的 data-type/data-size API混用。
• 在添加SVG之前使用 diagrams.md。为每个有意义的图表提供标题、描述、标签和文字替代。将宽图表放在带标签、键盘可聚焦的 .dads-diagram-scroll 区域内。
• 使用已安装的字体回退；缺失Noto时必须不隐藏文本。将 lang 与内容匹配。正文为1rem/1.7（默认设置下16px）。保留浏览器的缩放和重排功能。
• 默认使用链接和原生折叠面板。保持折叠面板初始状态为 open，以便无脚本打印时保留内容；打包的脚本也会在打印时打开任何被读者折叠的折叠面板，并在打印后恢复原状。不要添加选项卡、死按钮、任意JavaScript或事件处理器属性。
• 在深色操作系统设置中保持浅色：此适配器没有经过验证的官方深色调色板。不要仅反转页面背景或发明一套深色令牌集。尊重forced colors和reduced motion。
• 优先使用现有组件。如果必要，将少量文档特定的规则放在单独的内联 <style> 中；新类必须为 artifact-* 并在其中定义。使用已知令牌，切勿重新定义或修改打包的CSS。在浏览器中检查这些规则；静态验证不是CSS解析器或对比度审计工具。

4. 最终自检——在交付前修复问题

在最后一次编辑后运行：

python /absolute/path/to/html-artifacts/scripts/check.py /absolute/path/to/output.html

然后在浏览器中检查实际文件，尽可能禁用网络：

1. 内容： 初始模板文字/占位符已删除；请求的证据、来源、日期和后续操作保留。独立阅读图表描述；它们必须传达含义。
2. 离线： 没有资源请求、失败的资源、CSP违规或控制台错误。源超链接是导航，而非嵌入的依赖。
3. 移动端/桌面端： 检查390px和1280px下的截图；另外检查320px/200%文本大小下的重排。没有页面级水平溢出；仅带标签、可聚焦的代码/表格/图表区域可以滚动。检查实际的日文字形和长URL。
4. 键盘/状态： 跟随跳过链接和目录，Tab键切换到滚动区域，切换折叠面板，并检查可见的焦点以及按钮-链接对比度（包括已访问/悬停状态）。没有仅靠颜色传达的信息。
5. 深色/打印： 模拟深色偏好（页面必须保持可读的浅色模式），在折叠面板关闭的情况下打印，验证其正文内容打印成功，并检查宽表格/代码和分页。通过让折叠面板初始为打开状态，不依赖JavaScript保留内容。

检查器强制执行打包的资源/策略契约、已知的类/令牌以及保守的离线资源规则。它不验证CSS语法、布局、对比度、无障碍性或任意HTML的正确性。如果浏览器不可用，说明哪些视觉/交互检查尚未验证；切勿仅凭静态检查结果声称截图。

5. 交付

保存在源文件旁边或工作目录中，根据主题命名（例如计划文件为 PLAN.html）。返回构件链接和材料限制，而非文档副本或第二个通用自审结果。

对于SSH/其他设备，请遵循 remote-preview.md。远程路径或 xdg-open 不是可用的查看交付方式。仅提供隔离副本，仅对授权公开共享的内容使用公共隧道，否则使用SSH转发/访问控制，并提供清理说明。保持原始HTML离线安全。

资源

• assets/template.html、assets/dads.css、assets/print.js：机械嵌入的源文件。
• scripts/build.py、scripts/check.py：标准库构建和最终契约检查。
• build.md：编辑模式和故障排除。
• dads.md：官方出处、令牌、适配器组件API。
• diagrams.md：可读的内联SVG模式。
• remote-preview.md：安全的远程交付。

从零开始解释的方法受 ELI5技能 启发。