system_prompts_leaks 中的 artifact-design 技能解读：Claude Code 生成 Artifact 的完整设计系统提示词

本文解读 artifact-design 技能文档——一份随 Claude Code 系统提示词泄露捕获、随其一同下发的"Artifact 设计规范"。读完你会掌握：Claude Code 在发布任何 Artifact 页面之前被强制加载的完整设计判断流程（如何为请求校准"设计力度"）、一套可直接迁移到自身设计系统提示词的基础法则（三态主题 token 结构、字体加载通道、反"AI 味"审美清单、命名与信息设计规则），以及它与 dataviz、artifact-capabilities 等姊妹技能在主提示词中的协作关系。

一、它是什么：一份被主提示词"强制加载"的设计规范

artifact-design/SKILL.md 是 Claude Code（CLI/agent harness）技能包中的一个 skill 文件，按仓库 Anthropic/README.md 的说明，claude-code/ 目录存放的就是 Claude Code 组件的提示词捕获。该文件的 YAML frontmatter 声明了它的元信息：

name: artifact-design
description: Design guidance and fundamentals for Artifacts.
when_to_use: Load before writing any artifact, including a skill-instructed Markdown one - Markdown is never a shortcut past the design pass.

when_to_use 字段点明了它的定位：写任何 Artifact 之前必须加载，包括被其他 skill 指示以 Markdown 形式发布的页面——"Markdown 绝不是绕开设计环节（design pass）的捷径"。这并非一句口号，而是被各版本主系统提示词硬性执行的。以 claude-code-fable-5.1.md 为例：

• 技能注册表（#L241）逐字复述了上述 when_to_use 描述；
• Artifact 工具章节（#L354）写明："Before writing the file — a skill-instructed .md included — you MUST load the artifact-design skill"，先加载它校准这次请求值得投入多少设计力度，然后把内容写入文件再调用 Artifact 工具发布。同一措辞也出现在 claude-code-opus-5.md、claude-code-opus-4.8.md、claude-code-sonnet-4.6.md 等多个版本捕获中，说明这条"先读设计规范再动笔"的约束是长期稳定的行为要求；
• 该文件还规定了唯一的豁免：来自 workshop skill 的工作坊文档自带设计，此时跳过 artifact-design、改加载 artifact-diagramming。

另一个值得注意的解耦是：格式决策与设计决策被明确分开。主提示词（#L350）规定默认以 .html 撰写页面、只有被加载的 skill 明确指示时才发布 .md，而 artifact-design 文档开宗明义："Calibrate treatment, not whether to design"（校准的是处理方式，而不是要不要设计）——"Format is not part of this read"。也就是说，无论最终交付物是 HTML 还是 Markdown，设计投入的标准是一致的，格式只是设计被交付的载体。

二、第一步：读请求，校准"设计力度"

文档开篇把 Agent 的角色设定为"一家以多面手著称的小工作室的设计负责人，给每个客户一个配得上该任务实际要求的视觉识别"。核心动作是 treatment 校准：

• 文档值得与落地页同等的工艺——变化的只是工艺被交付的方式。一份计划、一份备忘录、一个演示（"a plan, a memo, a demo"）属于实用主义（utilitarian）处理：要有真实的排版层级、考究的间距和得体的调色板，但避免过度设计，"大多数页面不需要炫目的巨型 hero"，装饰性手法要克制；
• 落地页、游戏、用户会长期保留或分享的 App/工具则属于编辑级（editorial）处理，文档后半部分（见第六节）只在此类请求下运行；
• 拿不准时的裁决原则："一个构图良好的页面从来不是错误答案；过度设计的视觉识别有时才是"（a well-composed page is never the wrong answer; an over-designed visual identity sometimes is）。

这一节的价值在于把"设计投入"从一个二值开关变成了一个连续光谱，并给出了偏向"宁可朴素、不可浮夸"的默认值。

三、适用于每个 Artifact 的设计基础

这是文档的主体——十条基础法则，原文标题为 "Fundamentals for every artifact"。

3.1 尊重已有的设计体系

动笔前先找现成的设计系统：CLAUDE.md、tokens 或主题文件、既有组件样式。找到就应用，文档里其余一切内容"只填补缺口，绝不覆盖"。优先级永远是三层：用户自己的话 → 项目既有体系 → Agent 自己的选择（#L23）。

3.2 扎根主题，用真实内容构建

如果主题还不清晰，先把它钉死：一个具体主题、它的受众、页面的单一职责。有辨识度的选择来自"主题自己的世界——它的材料、器具、行业惯例"（its materials, instruments, vernacular）。全程使用真实内容构建，"never lorem"（永远不用 lorem ipsum 占位）。

3.3 字体配对：CSP 之下唯一开放的字体通道

这是与 Artifact 运行环境强相关的一条硬约束（#L27）：

• Google Fonts 是 Artifact CSP（内容安全策略）唯一认可的字体托管方，必须直接以 <link> 引入：<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=...&display=swap">；
• 来自任何其他来源的字面必须以 @font-face data URI 内联，否则"会静默回退"（falls back silently）；
• 无论如何都要声明真实的 fallback 字体栈。

这条规则在仓库中有直接的一手证据：主提示词的 CDN 白名单章节（#L372）规定外部样式表只能来自 fonts.googleapis.com、字体文件只能来自 fonts.gstatic.com，其余一切主机（包括 unpkg 和 esm.sh）以及非脚本资源一律被阻断，且"没有可见错误"——静默失败。这解释了为什么 skill 要特别警告"silent font fallback"：字体加载失败在 Artifact 查看器里是不可见的。

排版细则同样具体：正文行宽保持在 65 字符附近；设定字级比例（type scale）并始终遵守；标题加 text-wrap: balance；正文留出呼吸空间；全大写字母标签（uppercase labels）加一点字距（letter-spacing）。

3.4 中性色要"选"出来，而不是"默认"下来

"纯中灰读起来像没经过思考；带一点朝页面主色倾向的灰调则读起来像被选择过。"纯白与近黑在适合主题时是合格的地基——要点在于中性色是被选中的，而不是被继承的。

3.5 设计两套主题：三态主题 token 结构

这是全文信息密度最高的一节（#L31），它描述的是 Artifact 查看器的真实渲染模型，值得逐点拆解：

1. 查看者有三个主题状态，不是两个：显式选择时，根元素会被盖上 data-theme="dark" 或 data-theme="light" 的戳；默认的"跟随系统"则什么都不盖——大多数查看者看到的是未盖章的文档，此时只有 prefers-color-scheme 能区分明暗。

2. token 层的三层结构（示意性 CSS，按 skill 规则整理）：

   /* 第 1 层：裸 :root 定义完整浅色调色板（刻意深色优先的设计则在此整体交换明暗） */
   :root {
     --ground: #fafaf8;
     --ink: #1a1a18;
     --accent: #2f6f4f;
   }
   /* 第 2 层：媒体查询只重定义 token，且必须加守卫，使显式选浅色能压过深色系统 */
   @media (prefers-color-scheme: dark) {
     :root:not([data-theme="light"]) {
       --ground: #16181a;
       --ink: #ecece8;
       --accent: #6fae8e;
     }
   }
   /* 第 3 层：显式选深色时同样重定义，使手动切换在反方向也生效 */
   :root[data-theme="dark"] {
     --ground: #16181a;
     --ink: #ecece8;
     --accent: #6fae8e;
   }
   /* 组件只消费 token，永不把颜色写死在媒体查询或 [data-theme] 块内部 */
   .card { background: var(--ground); color: var(--ink); }
   

3. 组件样式只走 token，绝不在媒体查询或 [data-theme] 块内直接写颜色——"只定义在 [data-theme] 背后的颜色在未盖章状态下永远不生效，页面会渲染成一种主题的文字压在另一种主题的地基上"（one theme's text on the other theme's ground）。

4. 发布前自检：扫描整个样式表，找出任何只在媒体查询或 [data-theme] 块内声明的颜色——"这是经典的不可读 Artifact 缺陷"。

5. 两条配套规则保证每个主题作为整体解析：Artifact 是叠在查看器按其主题涂色的地基上合成的，所以 body 必须用 token 显式设置 background——透明的 body 会悄悄借走宿主的地基；任何设置颜色的元素都必须取"其背后表面"同一 token 集的颜色，绝不用只在单一主题下成立的字面量。

6. 第二主题要配得上第一主题：不是机械反色，保持对比可读、主色在两种地基上都成立。

7. 单主题豁免是选择而非遗漏：刻意押注单一视觉世界的设计（霓虹街机屏、凸版印刷请柬）可以跳过媒体查询和主题戳，但仍要显式涂背景、显式给每个颜色——"让它在任何宿主机地基上都站得住；让它成为一个选择，而不是一次省略"。

3.6 让布局承担间距

兄弟元素组用 flex/grid 加 gap 排版，而不是逐元素 margin（后者会静默折叠或叠加成倍）；宽内容（表格、代码、图表）在自己的容器上加 overflow-x: auto，"页面 body 永远不产生横向滚动"——这一点与主提示词的 Responsive 章节（#L378）完全互相印证；凡是数字成列排布的地方（对账表、KPI），用 font-variant-numeric: tabular-nums 对齐。

3.7 避开"AI 生成设计"的审美聚类

文档罕见地直接点名列举了当时 AI 生成设计聚类成的几种"脸"（#L35）：

• 暖米色（#F4F1EA）配衬线展示字与赤陶色点缀；
• 近黑底加单一荧光绿或朱红爆点；
• 报纸式发丝线（hairline rules）配密集分栏；
• 白底上的紫到蓝渐变 hero；
• 把 Inter 或 Space Grotesk 当"安全牌"字体；
• emoji 充当章节标记；
• 一切居中；
• 到处 rounded-lg；
• 圆角卡片上加装饰性色条/侧轨（accent bar/rail）。

并给出两条配套裁决：用户指明了视觉方向就精确服从——用户的话永远获胜，包括用户主动点名这些脸；什么都没指定时，不要把自由额度花在这些默认值上。

3.8 干净构建与 CSS 特异性

警惕重叠元素、级联冲突、静默字体回退——"视觉 bug 藏在源码与输出之间的缝隙里"。具体工程纪律：闭合所有非空元素、属性值双引号、键盘焦点要有可见状态、尊重 prefers-reduced-motion；生成式或装饰性图形优先用 Canvas/WebGL，而不是手写长 SVG 路径数据。CSS 章节单独警告选择器特异性：生成类与类之间的互相抵消很容易发生——比如基于类型命名的 .section 和基于元素命名的 .cta 为区块间的 padding/margin 打架——"要把级联结构组织好，让它不会悄悄撤销你的间距"。

3.9 文案也是设计材料

"Words are design material, not decoration"。从用户那一侧的屏幕写：用人们认识的名字命名事物，而不是系统内部结构（用户管理的是"通知"，不是"webhook 配置"）；主动语态；控件文案精确说明会发生什么（按钮叫 "Publish"，点完后的 toast 说 "Published"）；错误说明发生了什么、怎么修——不道歉、不含糊；"具体胜过聪明"。

3.10 给页面命名：像产品，不像图注

<title> 是 Artifact 在画廊和浏览器标签页里的名字，"它奠定读者对用心程度的第一印象"。规则链（#L43）：

• 给页面一个真实的名字：短名词短语，通常两到四个词，对主题具体；对"只为回答一个问题而存在的页面"，那个问题本身就是名字；
• 停在名字为止——名字后面跟破折号或冒号再带一段解释，读起来就是生成的填充物；
• 名字必须在众多 Artifact 中可辨识：画廊里它和几十个其他 Artifact 并排，任何页面都能贴的泛类别标签，与附加的解释语一样不合格；
• 当候选标题是"名字 + 泛词"（问候语、类别、页面类型标签）的组合，留名字那一半，丢掉泛词那一半——反过来修剪只会造出"能贴在任何一个页面上"的标题；
• 规则只删解释语、不强制简短：已经读起来像一个具体名字的多词标题就是完成了的，再削只会变泛；
• 解释的去处是发布时的单句 description——画廊会把它显示在标题正下方。

仓库里主提示词给出了这条规则对应的平台机制（#L356）：只扫描文件前 8KB 找 <title>；title 参数仅在文件里找不到标签时兜底，且永不覆盖标签；"Keep the title stable across redeploys"（重部署时保持标题稳定）。skill 的设计规则与平台的解析行为在这里精确咬合。

3.11 结构即信息

编号、眉标（eyebrows）、分隔线、标签这类结构装置应当编码关于内容真实成立的信息，而不是装饰内容。很多泛化设计爱用 01 / 02 / 03 编号标记，"但只有当内容真的是一个序列——真正的流程、顺序承载读者所需信息的类型化时间线——时才合适。采用编号标记之前先问自己它是否真的说得通"。

3.12 当它是 UI 而不是文档

仪表板或工具是"被扫读和被操作"的，不是被从头读到尾的，工艺重心从排版转向信息设计：摘要先于细节；用形态编码状态（药丸 pill、芯片 chip、严重度色条 severity stripe），让需要关注的事一眼可辨；语义色（good / warning / critical）独立于主色相，不算你的 accent；sparkline 和图表与字体同等认真地对待（面积填充、浅色网格、强调端点）；可交互的东西要看起来可交互。

文档在这一节末尾留了一个 HTML 注释锚点 <!-- dataviz-callout -->（#L49）。从源码结构看，这是一个为 dataviz 技能 预留的挂载点：dataviz 是另一套完整技能，规定了图表形态选择、颜色公式、可运行的调色板校验脚本与交互规则，其 frontmatter 要求"在生成任何图表之前先读它"。两篇文档分工明确：artifact-design 管页面的整体设计判断，dataviz 接管其中"图表"这一子域。

四、写代码之前：一份 30 秒设计计划

文档的 "Process" 一节要求，在写代码之前先画一份简短的设计计划——一套紧凑的 token 系统：

• 颜色：把调色板描述为 4–6 个带名称的 hex 值；
• 字体：2 个以上角色的字面——一个有个性但克制的展示面（display face）、一个互补的正文面、必要时一个用于图注/数据的工具面；
• 布局：一两句的布局概念。

然后构建时严格跟随这份计划，"每一个颜色与字体决策都从它推导出来"（deriving every color and type decision from it）。这套"先定 token、再写代码"的流程，本质上是把设计决策前置成可审查的中间产物，避免颜色与字体在实现中逐处即兴。

五、当请求是"编辑级"的：立场切换与审美风险

"当请求是编辑级"时，立场整体切换：客户已经否决过所有模板感方案，"正在为一个有辨识度的观点付费"。要求是：做有主见的判断，并在服务作品的前提下承担一次真实的审美风险。

流程上多一道自检：构建之前把设计计划对着主题复审——任何读起来像"你会为任何相似页面产出的通用默认值"的部分，改掉它，并记下改了什么、为什么；只有在确认计划具备独特性之后才写代码，且严格按修订后的计划执行。

随后的原则清单：

• Hero 就是论点：开场即主题世界里最有特征性的东西——标题、图像、活体演示、交互瞬间；
• 字体承载页面个性：展示面与正文面的配对要有意图，"不是你会在任何其他项目中都伸手去拿的同一族字体"；字级要有刻意的字重、宽度、间距；让字体处理本身成为设计里难忘的一部分，而不是内容的中性运载工具；
• 动效是有意的：想清楚动画在哪里、是否为主题服务——页面加载序列、滚动触发显现、悬停微交互、环境氛围感；"编排过的一刻通常比零散的效果更有冲击力"；但有时少即是多，额外的动画会加重'这是 AI 做的'的感觉——这句把第五节的动效建议与 3.7 的反 AI 审美清单直接勾连了起来；
• 复杂度匹配愿景：极繁方向需要繁复执行，极简方向需要间距、字体与细节上的精度；"优雅就是把选定的愿景执行好"；
• 把大胆花在一个地方，周围一切保持安静；如果主色与地基打架，把它移向类似色或降低饱和度，而不是替换它。

六、放到 Claude Code 的 Artifact 管线里看

把这份 skill 放回它所处的提示词系统（以 claude-code-fable-5.1.md 的 Artifact 章节为准），可以看到规范条款与平台机制的逐条对应关系：

• 发布机制：页面内容写入文件后调用 Artifact 工具，文件在发布时被包进 <!doctype html>…<head>…</head><body> 骨架，因此作者不写 <!DOCTYPE>/<html>/<head>/<body>；骨架的 head 只带 charset、viewport 和极小的 reset（color-scheme、body 零边距配 14px 系统字体、img{max-width:100%}、[hidden] 规则），所以自己的 <title> 和 <style> 要放在文件顶部——这正是 3.10 节"命名页面"规则得以落地的物理位置；
• CDN 白名单（#L372）：脚本只能来自 cdnjs.cloudflare.com（首选）、cdn.jsdelivr.net/npm/、cdn.tailwindcss.com、code.jquery.com，其余内联；"静默失败"的行为印证了 skill 里"静默回退"类警告的工程必要性；
• 体积上限：渲染页必须 ≤ 16MB，data: URI 也计入（#L376）——这是 3.3 节"字体必须内联为 data URI"的代价边界；
• 存储：localStorage 可用但每查看者私有、可能为空甚至抛异常，须 try/catch 包裹（#L374）——对应 skill 里"干净构建"的容错要求；
• 运行时能力：页面若需"记住用户行为"（投票、清单、可保存新版本的页面）等静态 HTML 做不到的行为，则由 artifact-capabilities 技能 描述的 capabilities: {artifact: {}} 等声明提供，与 artifact-design 的正交分工（它管"页面长什么样"，capabilities 管"页面能做什么"）；
• 姊妹技能版图：同一技能注册表里，design（多画板设计画布）、dataviz（图表）、artifact-diagramming（图表绘制）与 artifact-design 构成一组"视觉产出"技能，各自 frontmatter 的 when_to_use 定义了互不重叠的触发域。

七、小结：这份提示词可迁移的方法论

抛开 Artifact 平台本身，artifact-design 技能文档 展示了一种可借鉴的"设计系统提示词"写法，其要点在仓库内均可复核：

1. 触发条件写进 frontmatter 并由主提示词强制执行（"MUST load"），而不是依赖模型自觉；
2. 把设计投入校准为连续量（treatment，而非 design/no-design 二值），并给出拿不准时的裁决偏置；
3. 规则尽量可机检：发布前扫"只在主题块内声明的颜色"、8KB 内找 <title>、16MB 上限——让自检有确定判据；
4. 反模式直接点名（含具体 hex 值的"AI 审美"清单），比抽象的"要有品味"更可执行；
5. 先产出 token 层的设计计划，再写实现，使每个决策可溯源、可复审。

对阅读 system_prompts_leaks 的开发者而言，这份文件的独特价值正在于此：它不是某次对话的输出，而是产品方为约束自家 Agent 的视觉产出质量而预先编写的、可审计的完整规范——从主题三态渲染模型到"给页面命名像产品而非图注"，每一条都能直接迁移到你自己的设计系统提示词或前端交付规范中。