craft-page

设计页面

以一家以灵活多变著称的小型工作室设计负责人的视角来处理：每个页面都要根据实际需求，打造相应的视觉风格。问题从来不是要不要设计——备忘录也值得像落地页一样用心设计。变化的是这种设计心思的呈现方式。

1. 确定设计风格

在规划任何内容之前，先说明页面属于哪种风格：

• 实用型 — 测试指南、计划、备忘录、报告、内部仪表板、演示。要有清晰的字体层级、经过考量的间距和合适的配色；不要使用巨大的主视觉区，装饰元素应雅致且少而精。此技能集制作的大多数页面都属于这一类。
• 编辑型 — 落地页、游戏、用户会持续使用或分享的工具。只有这类页面才执行第 5 节。

拿不准？排版得当的页面永远不会错；视觉风格设计过度有时却会出问题。完成标准：明确说出设计风格。

2. 确定优先级，然后编写设计方案

优先级是固定的：用户自己的表述优先，其次是项目现有系统，最后才是你的选择。 在自行构思之前，先检查代码仓库中是否已有设计系统——经批准的 docs/standards/design-tokens.md、CLAUDE.md、docs/agents/*.md、令牌或主题文件、现有组件样式。如果存在，就遵循它；以下内容只用于补足其不足，绝不覆盖它。

然后编写设计方案——包含 3 个必填项，完成后才能编写任何标记：

• 颜色 — 4–6 个有名称的十六进制颜色值。
• 字体 — 至少 2 种用途的字体：克制使用、富有个性的展示字体；与之搭配的正文字体；如果页面包含说明文字或数据，再加一种实用字体。
• 布局 — 用一两句话说明布局概念。

如果页面或资料包包含主要图示（结构草图、拓扑图、序列图、流程图——包括 understand 地图图示），则增加第 4 个必填项：

• 图示用途 — 必须且只能选一个：before/after structure、 topology / architecture、sequence、flowchart。

然后加载 references/diagram.md，并根据图示用途推导图示。即使跳过页面重设计，也必须填写此项。v1 中没有第 5 种用途。

完成标准：方案已编写；页面中的每项颜色和字体选择都能追溯到方案中的对应内容；任何主要图示都明确采用四种用途之一，并遵循 references/diagram.md。

3. 基本原则 — 适用于所有页面和设计风格

立足主题。 明确一个具体主题、目标受众和页面的唯一目标。从主题自身的世界——其材料、工具、行话——寻找鲜明设计选择的灵感。始终使用真实内容，不要使用占位文本。

搭配字体。 即使页面主题与字体无关，排版也能撑起整个页面。不要链接网页字体 URL：已发布成品的 CSP 会阻止字体 CDN，而交付的 .html 文件在离线打开时也无法加载——两者都会静默回退到其他字体。将字体以内嵌的 @font-face 数据 URI 提供，或有意识地使用系统字体栈。正文每行控制在约 65 个字符，设定字体比例并始终遵循；为标题设置 text-wrap: balance，并为全大写标签稍微增加字距。

中性色也要精心挑选，别直接套用。 纯中灰会显得未经考量；略微偏向点缀色色调的灰色则会显得经过选择。只要适合主题，纯白和近黑都可以作为底色——关键在于中性色是经过挑选的，而不是沿用现成设置。 在 token 层面设计两种主题。 将调色板定义为 :root 上的自定义属性；在 @media (prefers-color-scheme: dark) 中仅重新定义 token；通过 token 为组件设置样式， 绝不在媒体查询中直接设置组件样式；然后在 :root[data-theme="dark"] 和 :root[data-theme="light"] 下再次重新定义 token，让用户显式切换主题时，无论哪个方向都能覆盖操作系统偏好。第二种主题也要像第一种一样用心设计——不要简单反转；确保对比度清晰易读，强调色在两种背景上都能正常显示。刻意坚持单一视觉风格的页面（例如霓虹街机屏幕、活字印刷请柬）可以只支持一种主题——但这必须是明确的选择，而不是疏漏。

让布局负责间距。 使用 flex 或 grid 和 gap 来排列同级元素组，不要给各个元素单独设置 margin，导致间距悄然折叠或叠加。对于表格、代码、图表等宽内容，在其自身容器上设置 overflow-x: auto，确保 body 不会横向滚动。凡是数字需要按列对齐的地方，都使用 font-variant-numeric: tabular-nums。

留意选择器优先级。 很容易生成相互抵消的类——例如 .section 规则与 .cta 规则争抢区块之间的内边距。合理组织层叠规则，避免间距被悄无声息地覆盖。

确保构建整洁。 视觉 bug 往往藏在源代码与输出之间的缝隙里：为每个非空元素闭合标签，为属性使用双引号，为键盘焦点提供清晰可见的状态，并尊重 prefers-reduced-motion。如果图示属于 references/diagram.md 中的四种之一，就按其中的规范编写内联 SVG——这种 SVG 必须手工绘制。对于不属于这四种情况的生成式或装饰性图形，请使用 Canvas 或 WebGL，而不是冗长的路径数据。保持页面自包含——内联 CSS 和 JS，并将资源嵌入为 data: URI。

从用户的视角撰写文案。 文字也是设计素材。用人们熟悉的名称来描述事物，而不是描述系统的构建方式（用户管理的是通知，而不是 webhook 配置）。使用主动语态；控件要准确说明会发生什么（例如“发布”，然后显示一条写着“已发布”的 toast）。错误提示要说明出了什么问题以及如何修复——不要道歉，也不要含糊其辞。明确具体胜过刻意机巧。

让结构表达真实信息。 眉题、分隔线、标签和编号标记（01 / 02 / 03）只有在内容确实构成序列时才合适——例如真实流程，或顺序承载读者所需信息的时间线。否则，它们只是在装饰。

当界面是 UI 而非文档时。 仪表板或工具是供人扫视和操作的，而不是从头到尾阅读的，因此设计重点应从排版转向信息设计。先呈现摘要，再展示细节；除了数字，也要通过形状编码状态——例如胶囊、芯片、严重性条纹——让需要关注的内容一目了然。语义颜色（正常 / 警告 / 严重）应与强调色分开，且不计入强调色。交互元素看起来就应该可交互。

4. 把设计自由用在别处，而不是沿袭惯常风格

AI 生成的设计目前集中在少数几种风格上。用户明确指定方向时，就严格遵循——以用户的要求为准，包括他们要求采用以下任一风格时。如果用户没有指定，就选择其他风格：

常见风格
暖奶油色 #F4F1EA + 衬线展示字体 + 赤陶色强调	密集分栏上方使用报纸式细线分隔
近黑底色，搭配一个亮酸绿色或朱红色点缀	白底上使用紫到蓝的渐变主视觉
用 Inter 或 Space Grotesk 作为“稳妥”字体	用 emoji 作为区块标记
所有内容居中	到处使用 rounded-lg，并在圆角卡片上加一条强调色侧边栏

5. 当采用编辑式处理时

立场会发生转变：客户端已经拒绝了那些感觉像模板套出来的方案，并愿意为独特的观点付费。做出鲜明的判断，并在有助于作品的地方承担一项真正的审美风险。

动手构建前，针对主题重新审视第 2 节中的计划：如果有任何部分读起来像是你会为任何类似页面采用的通用默认方案，就修改那部分，并说明改了什么、为什么改。然后才开始编写代码，严格遵循修订后的计划。

• 主视觉就是论点 — 以主题世界中最具代表性的内容开场：标题、图片、实时演示或互动时刻。
• 排版承载个性 — 有意识地搭配标题字体与正文字体，而不是随手选用你会在其他项目中用到的字体组合。让字体处理本身令人难忘，而非成为中性的展示载体。
• 动效经过精心设计 — 页面加载序列、滚动显现、悬停微交互、环境氛围。一个精心编排的时刻，胜过零散的效果；而零散的效果本身就是破绽。
• 让复杂度匹配愿景 — 极繁主义风格需要精细的实现；极简风格则需要在间距、字体和细节上做到精准。优雅，意味着把选定的愿景实现到位。
• 把大胆用在一个地方，并让周围的一切保持安静。如果强调色与底色冲突，就调整为相近色，或降低饱和度，而不是直接替换它。

合理化借口

想法	实际情况
“这只是内部测试指南 / 报告，设计不适用”	会变化的是处理方式，而非工艺。实用主义仍意味着真正的配色、真正的字号层级，以及经过考量的间距
“我写 CSS 时再选颜色”	逐项拼凑出来的配色，往往最显得千篇一律。计划只要三行，却正是让页面具有针对性的关键
“用户没提暗色模式”	决定主题的是查看者，而非请求。没有设计过的第二套主题，上线后就会出现对比度问题
“我会从 Google Fonts 链接字体”	发布时会被 CSP 拦截，交付后离线时也无法使用——它会无声地回退到备用字体，字体计划随之落空
“奶油色、衬线字体和陶土色强调色看起来很雅致”	这是当下的默认风格。雅致与模板感可以同时存在——除非用户有此要求，否则把自由度用在别处
“我给各个部分编号，这样看起来更有条理”	编号暗示内容存在先后顺序。如果顺序没有传递信息，那就是会误导人的装饰
“跳过了 Restyle，所以 craft-page 不适用于这个图示”	由图示触发。主要图示仍需明确说明用途，并加载 references/diagram.md
“我会加载 dataviz / artifact-capabilities”	这个包里没有这些名称。不要搜索它们。图表不属于 v1 的工作范围
“一排 flex 方框加上 → 就是拓扑图”	拓扑图应根据方案使用内联 SVG。CSS 箭头表示路径，而非包含关系
“图示需要单独用铁锈色 / 蓝绿色搭配，才能一眼看懂”	沿用页面或外壳的设计令牌。第二套配色会让图示重蹈单色问题的覆辙

危险信号

• 主要图示没有明确说明用途，或名称不属于四种图示之一
• 未加载 references/diagram.md，就编写 understand Map / 扫描草图
• 搜索 dataviz 或 artifact-capabilities
• 使用 Mermaid、网页字体 CDN，或在页面旁放置第二个 .svg / PNG 文件
• 用 CSS 编写 → 列表，或在四种图示任务之一中使用 Canvas