Claude Code Artifact HTML 文档骨架规范：理解发布时自动注入的页面外壳与安全区适配

本文以 Claude Code 内置工具描述 tool-description-artifact-html-document-skeleton.md 为核心，系统讲解 Artifact 页面在发布时被自动包裹的 HTML 骨架结构、最小化样式重置（reset）以及针对刘海屏安全区（safe-area）的适配规则，并说明作者应如何在此基础上提供页面内容、标题与样式。读完本文，你将掌握 Artifact 页面文件的正确书写姿势——不写 <!DOCTYPE>、<html>、<head>、<body>，而是直接在骨架内放置 <title> 与 <style>，并正确处理固定栏、粘性头部在异形屏上的偏移问题。

什么是 Artifact HTML 文档骨架

Claude Code 的 Artifact 是一类默认私有的 HTML 交付物：Claude 在发布（publish）时把作者写好的页面文件包装进一个完整的外部 HTML 外壳。这个外壳由查看器（viewer）在发布时自动生成，结构为：

<!doctype html>
<head>
  <!-- 由查看器注入的 meta 与 reset -->
</head>
<body>
  <!-- 作者编写的页面内容 -->
</body>

因此，作者的文件里不应该出现任何 <!DOCTYPE>、<html>、<head> 或 <body> 标签。这一点在配套的 tool-description-artifact-page-authoring-and-html-skeleton-app-wording.md 中被再次强调：publish 会包裹整个文件，作者只需直接写页面内容，并在文件开头放上自己的 <title> 和 <style>。

仓库提示：本仓库（claude-code-system-prompts）中所有 tool-description-*.md 文件都是从 Claude Code 编译产物中逐字提取的内置工具描述（见 README.md），因此下面的骨架细节即 Claude Code 实际运行时使用的规范，而非推测。

查看器注入的 <head> 内容：meta 与最小化 reset

查看器注入的 <head> 只携带两类内容，且极其精简：

1. charset meta：声明字符编码；
2. viewport meta：标准移动端视口声明，并带 viewport-fit=cover——这是后续安全区适配（env(safe-area-inset-*)）生效的前提；
3. 一段很小的 reset（样式重置），各规则与作用如下表：

Reset 规则	作用
color-scheme: light	让表单控件、滚动条等跟随浅色配色（主题感知页面的深色方案需在此覆盖）
:root 上下内边距 = 手机的 safe-area insets	让页面主体避开刘海屏的顶部/底部遮挡区域
body { margin: 0 }	消除默认外边距
14px 系统字体、米白色（off-white）背景	提供统一的默认排版与底色
img { max-width: 100% }	防止图片溢出视口
[hidden] { display: none !important }	保证 hidden 属性始终隐藏元素

其中最后一条对代码写法有直接约束：切换元素显隐应使用 el.hidden，而不是修改 style.display。因为骨架用 !important 锁死了 [hidden] 的显示值，任何内联的 style.display 都无法覆盖它。这会让 hidden 成为页面中唯一可靠的显隐开关。

safe-area 适配：:root 内边距必须保留

骨架在 :root 上设置了由安全区驱动的上下内边距，作者不能清除它。原因在于：viewport-fit=cover 之下，页面会延伸到屏幕的异形区域（刘海、圆角、底部手势条），而 env(safe-area-inset-top/bottom, 0px) 正是读取这些区域尺寸的 CSS 环境变量。

骨架给出的适配规则分两种情况：

• 固定定位的栏（fixed bar）：贴在顶部或底部的栏初始 top/bottom 为 0，但要在自身 padding 中加上对应方向的安全区值：

  .bottom-bar {
    position: fixed;
    bottom: 0;
    padding-bottom: env(safe-area-inset-bottom, 0px);
  }
  

• 粘性头部（sticky header）：不能把 top 设为 0，而要写成 top: env(safe-area-inset-top, 0px)：

  .sticky-header {
    position: sticky;
    top: env(safe-area-inset-top, 0px);
  }
  

两条规则的本质一致：安全区偏移必须由目标元素自己承担，而不是依赖 :root 的默认内边距——因为固定/粘性定位会脱离或绕过正常文档流，:root 的内边距对它们不生效。

作者职责：提供 <title>、<style> 与页面内容

既然骨架只负责外壳与最小 reset，那么页面的标题、全部样式与正文内容就都是作者的职责。规范要求：

• 在文件顶部写自己的 <title> 标签（浏览器标签页标题，Artifact 发布时的 title 参数与此相关，见 tool-description-artifact-title-and-description-guidance.md）；
• 紧随其后写 <style>，定义完整的设计；
• 之后才是页面正文。

一个符合规范的 Artifact 页面文件开头应大致如下：

<title>月度研发报告</title>
<style>
  :root { --bg: #faf9f6; --fg: #1a1a1a; --accent: #2563eb; }
  body { background: var(--bg); color: var(--fg); padding: 0 16px; }
  img { border-radius: 8px; }
</style>
<h1>月度研发报告</h1>
<!-- ... -->

注意：不要出现 <!DOCTYPE html>、<html>、<head>、<body>。若写入了这些标签，会导致骨架嵌套重复——仓库中 tool-description-artifact-nested-runtime-cleanup-error.md 记录的发布错误，正是针对"不可约嵌套的 runtime 标记、base 标签或重复页面骨架"这类情况。

与响应式契约、主题感知样式的衔接

骨架是页面实现的基础，其上还有两套配套契约，二者都建立在"骨架只提供最小外壳"这一前提上：

响应式：侧边留白与横向滚动隔离

tool-description-artifact-responsive-page-contract.md 要求页面在约 400px 的手机宽度下可用，且页面本体永不横向滚动：

• 在 body 或唯一外层 wrapper 上一次设置至少 16px 的左右 padding；该元素的垂直方向留白用 padding-block，不要用会同时清零左右 padding 的 padding 简写；
• 图片与 aspect-ratio 盒子加 max-width: 100%；任何元素的 min-width 不得宽于屏幕；
• 只有表格、图表和代码块可以超宽，且各自放进独立的 overflow-x: auto 容器。

主题感知：token 化配色与显式 body 背景

tool-description-artifact-theme-aware-styling.md 要求所有颜色以 CSS token 形式定义，且 token 的首次定义必须落在裸 :root 上（因为骨架在那里固定了 color-scheme: light），深色两个分支（@media (prefers-color-scheme: dark) 下的 :root:not([data-theme="light"]) 与 :root[data-theme="dark"]）只做重定义，并各自声明 color-scheme: dark：

:root { --bg: #faf9f6; --fg: #1a1a1a; --accent: #2563eb; }
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { --bg: #141414; --fg: #e8e6e3; --accent: #7aa2ff; color-scheme: dark; }
}
:root[data-theme="dark"] { --bg: #141414; --fg: #e8e6e3; --accent: #7aa2ff; color-scheme: dark; }
body { background: var(--bg); color: var(--fg); }

特别地，body 必须有显式背景：查看器会在页面背后绘制自己的底色，透明 body 会透出宿主主题。骨架只铺了一层"米白色"默认地，深色主题下必须由作者用 token 覆盖。

发布前的验证：preview 动作

书写与骨架相关的内容时，可以借助 Artifact check 工具的 action: "preview" 在本地按"发布时包裹"的方式渲染页面，分别在浅色/深色主题、桌面/手机两种宽度下截图，并返回一份关于布局与加载问题的机械式检查清单（见 tool-description-artifact-preview-action.md）。该动作不上传任何内容、不需要 artifact URL，也不运行 artifact runtime——这意味着预览环境中能力代码不会执行，发布后仍需自行验证能力相关代码（例如把存入的数据读回来）。对骨架规范而言，preview 最直接的收益就是：在本地就能确认安全区 padding 是否保留、固定栏偏移是否正确、hidden 切换是否生效。

小结

Artifact HTML 文档骨架是 Claude Code 发布机制的一部分：查看器在发布时注入 <!doctype html> 外壳、charset 与 viewport-fit=cover 的 viewport meta，以及一份最小 reset（color-scheme: light、safe-area 驱动的 :root 上下内边距、零 margin 的 14px 系统字体、img{max-width:100%}、[hidden]{display:none!important}）。作者的正确姿势是：文件内直接写内容，顶部放自己的 <title> 与 <style>，不写任何 HTML 骨架标签；保留 :root 的 safe-area 内边距，固定栏自行叠加 env(safe-area-inset-*)，粘性头部用 top: env(safe-area-inset-top, 0px)；用 el.hidden 而非 style.display 控制显隐。在此基础上，再叠加响应式契约与主题感知 token 规范，即可写出在手机与桌面、浅色与深色主题下都正确呈现的 Artifact 页面。