visualize

visualize — 精美且符合品牌形象的 HTML 成品

根据已解析的视觉上下文，按照 templates/*/template.md 中的约定生成独立的 HTML 成品。项目的 DESIGN.md、PRODUCT.md 和附属的 tokens.css 提供默认设定；下方的成品主题则允许使用用户批准范围内的参考系统。共享模式配方位于 patterns/，仅在所选模板和用户要求相关时读取；只有模板声明 shell: <slug> 时，才会自动加载外壳机制。

在辅助命令中，$SKILL_DIR 表示此安装版 SKILL.md 所在目录的绝对路径。请从宿主的技能目录中解析该路径；在 shell 中设置该变量并加上引号（"$SKILL_DIR"），或直接替换为加引号的绝对路径。宿主不一定会导出此变量。

设计判断

明确读者的任务，并让重要差异一目了然，同时保留解读所需的证据和限定条件。选择呈现方式之前，先找出源材料的组织关系、对比、顺序、决策或对象；让它塑造开篇、章节节奏和解释性元素。如果这些因素都没有帮助，就采用克制的阅读体验，而不要刻意制造组织思路。

成品模式描述的是内容的使用方式，而非美学风格：document 不必意味着编辑出版，canvas 也不必带有图表外框。构图、排版、信息密度、空间节奏、图像、交互或色彩都可以赋予成品表现力。不要仅仅为了让成品显得经过设计，就添加色调、装饰或组件。

回复反馈之前，请结合成品的读者、目的、源材料以及已批准的需求（如有），评估反馈意见。区分实现缺陷、不符合现有要求的设计，以及表明需求或假设已发生变化的证据。当前构图只是一个解决方案，而非约束。

直接在现有需求范围内进行已获授权的修正。如果反馈意味着要改变既定要求，而用户尚未批准，则先说明拟议的变更并取得同意，再进行编辑。当仍有多个合理的结构或视觉方向时，建议在其支持范围内使用 explore artifact。方向明确时，则使用常规的创建或优化工作流。遵循该工作流的审批要求；小幅修正无需重新探索。

结合读者的任务，整体评估拟议的修复方案。不要把每条批评都变成新增内容，也不要认为差异较小就代表方向合理。在现有审查或任务记录中保留与决策相关的待处理意见。

命令

/visualize 接受命令或主题／路径。

默认（不带命令的主题／路径）： 使用模板和已解析的上下文创建自包含的 HTML。阅读 reference/create.md；预检和用户批准的形式须先于代码。由 Agent 编写的简报不能自行批准。

命名命令：

类别	命令	参数	功能	参考文档
构建	teach	无	初始化（或刷新）品牌档案。在项目根目录写入 DESIGN.md + PRODUCT.md。	reference/teach.md
构建	explore	artifact|system <topic-or-path>	对比单个作品的设计处理方式，或新的／替代项目系统；应用前进行审核。	reference/explore.md
优化	simplify	<path>	移除没有价值的装饰。之后交由 polish 处理。	reference/simplify.md
优化	bolder	<path>	增强安全／通用作品的视觉冲击力。之后交由 polish 处理。	reference/bolder.md
优化	quieter	<path>	减少过度装饰，但避免变得通用。之后交由 polish 处理。	reference/quieter.md
优化	animate	<path>	添加有目的的动效，并遵循 prefers-reduced-motion。之后交由 polish 处理。	reference/animate.md
优化	polish	<path>	最终质量检查——逐项检查各个维度，并分别报告结果。其他优化命令均会交由此命令处理。	reference/polish.md
评估	review	<path>	检测器给出确定性结果 + 大模型判断。只报告，不修改文件。	reference/review.md
发布	publish	<path>	通过 MCP／CLI／HTTP 级联方式将作品推送到 display.dev。	reference/publish.md

示例：/visualize polish ./report.html。在不支持斜杠命令的平台上，以自然语言表达意图为主要入口。

路由规则

1. 无参数：按类别分组，将上方的命令表呈现为面向用户的菜单，并询问用户想做什么。
2. 首个词与命令匹配：先加载相应参考文档，再执行操作；命令表不是操作流程。命令名称之后的所有内容均为目标。
3. 自然语言意图：对比设计方案的请求加载 reference/explore.md；记录或协调项目身份的请求加载 reference/teach.md。其他情况下，创建内容或明确要求重新设计现有作品时加载 reference/create.md。指定的主题按下方的作品主题处理；无需进行探索环节。
4. 创建过程中的关系图路由：预检首次判断可能需要绘制关系图时，在展示形式审核关卡前，加载 reference/diagram.md 以及该图所需的一个暂定非空间类型参考文档。对于包含多张图的作品，每个不同的暂定类别都加载一个参考文档：reference/diagram-flow.md、reference/diagram-system.md、reference/diagram-sequence.md、reference/diagram-state.md 或 reference/diagram-hierarchy.md。空间图仅使用 reference/diagram.md。如果批准后图的类型发生变化，在创作前加载替换类型的参考文档；不要加载无关类别。
5. 创建过程中的图像生成路由：如果批准的形式需要生成位图图像，在选择或调用路由前加载 reference/image-generation.md。只能使用当前可调用资源清单或明确选定的 API 适配器。绝不能根据密钥、可执行文件、挂载项或模型声明推断路由；尝试结果不明确时，绝不能重试或回退到其他方案。
6. Explore 范围：explore 始终加载 reference/explore.md，其中区分作品设计处理方式与项目系统创建或明确替换。对比单个作品的设计处理方式，无需先创建项目设计系统。系统 Explore 使用其选择加入的权限分类，而不是将渲染回退方案视为现有身份。

交接输出格式

执行 simplify / bolder / quieter / animate 后，以对话式 Markdown 汇报：动词和目标、从参考文档的“应呈现内容”列表中提取的改动、差异百分比，以及适当的后续操作。成功的优化默认进入 polish，其输出格式见 reference/polish.md。

变体规则：

• 回退上下文： 点明一次来源（项目说明、README/文档、种子内容或 Clean），并引导使用 /visualize teach。遵循 Brand profile 的回退层级。
• 差异 >40%： 停止，报告范围，并根据 Design judgment 判断方向尚未确定时建议探索，或方向已明确时建议重新创作。不要继续进行优化。
• 不应执行该动词： 使用参考文档中的拒绝条件；用简短理由和适当的替代方案取代标准摘要。

对于 animate：当品牌声明 motion: none 时，还需应用第五种变体，详见 reference/animate.md。

先说明改动，根据读者调整措辞，并避免使用围栏代码块摘要、大写强调或 <Verb> pass complete · 横幅。

绝对禁止项

匹配并拒绝。适用于每条命令和默认创作流程。这些规则禁止的是特定模式，而非美学风格或语体。品牌可以指定看起来不寻常的字体、色调或布局，但不能将这些模式声明为品牌特色来规避禁令。明确的 .visualize-detect.json 跳过项只能豁免有具体规则 ID 的检测器禁令；这属于项目策略，而非运行时品牌抑制，且不能豁免 Layer-2 禁令。

BAN 1 — Gradient text on metrics or headings
  PATTERN:   background-clip: text + gradient background on <h*>, [class*="metric"], [class*="kpi"]
  INCLUDES:  -webkit-background-clip: text; CSS `background-image: linear-gradient(…)` + `color: transparent`
  WHY:       AI-essay register tell; reads as 2023-template "make the number pop"
  REWRITE:   Solid `--primary` (or `--foreground`) at one weight up; emphasis through weight + size, not gradient

BAN 2 — Side-stripe callout (border-left as accent)
  PATTERN:   `.callout`, `.tldr`, `.note`, `.tip` with border-left ≥ 3px in --primary / --warning / --destructive
  INCLUDES:  border-inline-start, border-l-4 utility class, ::before pseudo with positioned bar
  WHY:       Notion / Confluence template tell; reads as productivity-app default
  REWRITE:   Full thin border (1px var(--border)), background tint at 4–8% chroma, or no chrome — just a label heading

BAN 3 — Triple-feature-card grid
  PATTERN:   3-column grid of <h3>adjective + noun</h3> + one paragraph + one icon each
  INCLUDES:  4-column variants, "Why us" sections with identical card-icon-heading-blurb shape
  WHY:       AI-landing canonical pattern; the surest "AI generated this" tell on the visualize corpus
  REWRITE:   Asymmetric — one hero claim with two supporting facts, OR a numbered list with body prose, OR a single comparison table

BAN 4 — Hero-metric template
  PATTERN:   Centered <h1 class="…huge…">N×</h1> + <p class="…small…">supporting label</p> + 3 stat tiles below
  INCLUDES:  "10× faster", "99.9% uptime", "1M requests/day" hero blocks with the same shape
  WHY:       SaaS-landing cliché; the most-copied AI-marketing-page shape in 2024-2026
  REWRITE:   Specific claim in body prose with the number inline; data tiles only when the artifact is actually a dashboard

BAN 5 — Ornamental icon-tile section markers
  PATTERN:   Repeated icon tiles on section headings add chrome without identifying meaningful content distinctions
  INCLUDES:  Rounded-square, circle, coloured-pill, and gradient-tile variants serving only as decoration
  WHY:       Repeated chrome makes different sections look alike and competes with their content
  REWRITE:   Remove ornamental markers; retain useful recognition cues under reference/cognitive-load.md's Cognitive offloading guidance

BAN 6 — Imperative tricolon
  PATTERN:   Three short imperative sentences ending in periods, in the same paragraph or hero
  INCLUDES:  "Ship faster. Build smarter. Scale forever." / "Move fast. Stay safe. Be bold." (any topic)
  WHY:       AI-copywriting cliché — the structure is identical across thousands of generated landing pages
  REWRITE:   One specific claim with the verb in the right tense, OR a sentence that names the actor and the action

BAN 7 — Sycophant / AI-attribution footer
  PATTERN:   "I hope you find this useful", "Let me know if you have questions", "Best, Claude", "Generated by AI", "As an AI…"
  INCLUDES:  Footer-line variants, comment-line variants in the HTML source
  WHY:       The artifact is the work; the model is invisible. Sycophant footers contaminate the artifact register
  REWRITE:   No footer of this shape. A real footer carries metadata (date, version, source-of-truth link) or is absent

如果你准备创建这些模式中的任何一种，请停下来，用替代方案重写该元素。此列表适用于创作、每个 Refine 动词以及 polish。

特定模型的操作规则

这些不是品牌美学，而是观察到的模型惯性，并附有必须采取的纠正措施。在通用禁令之后应用这些规则，尤其是在不带品牌的全新创作中。

Codex 专属规则：

• 边框加大阴影： 避免在同一张卡片或同一个按钮上同时使用 1px 边框和模糊的大投影。选择清晰的边缘或轻微的立体效果。
• 圆角过大的容器： 普通卡片、区块、输入框和面板的圆角通常应保持在 12-16px。更大的圆角需要明确的品牌理由。
• 装饰性条纹背景： 不要将 repeating-linear-gradient(...) 用作页面或区块的填充。应使用有意设计的纹理／线条系统，或保持背景纯净。
• 粗糙的 SVG 替代方案： 不要因为没有可用的真实素材就绘制粗糙的 SVG 场景。应使用生成的位图图像、几何示意图，或不使用插图。
• 过度压缩的展示字体： 展示标题的字间距应 ≥ -0.04em，最大字号应 ≤ 6rem，除非模板属于明确需要更大字号的幻灯片／海报类型。
• 元话语式对比文案： 避免使用“X 的表演”、“实际上是 X”以及“不只是 X，而是 Y”这类表达。直接说明作品实际做了什么。
• 颜色判断： 使用 reference/color.md 评估色彩的特性、关系、角色、分布和实际搭配。没有任何色相、色相组合、中性色调或强调色数量是普遍适用的审美门槛。保留已获批准的品牌识别和明确的作品例外。
• 用调色板替代构图： 在形状门控中分配语义色彩角色，并保持一致使用，但不要仅为制造视觉趣味而添加强调色轨道。当构图、字体、密度、图像或交互能够体现设计立场时，中性色表面加一种强调色也是合理的。如果开篇缺少表现维度，就应修改；不要因为色相太少而修改。

Gemini 专属防护规则：

• 不要在悬停时为 <img> 元素添加动画。如果卡片需要悬停反馈，应为卡片的边框、背景或操作控件添加动画。

元数据／目录防护规则： 静态文档的上下文需要明确标签，不能使用无说明的圆角标签。按照 create.md 的文档上下文指南 放置文档上下文；右侧栏、封面分栏信息或独立元数据面板通常会让上下文变成与内容争夺注意力的装饰。真正篇幅较长的文档可以使用目录栏，但应以辅助导航为目的，而不是主导开篇。移动端目录必须保持为可导航的列表或经过设计的网格，绝不能变成自由换行的词云。如果创作中包含这些结构，请阅读 patterns/metadata.md 或 patterns/toc.md。

表格防护规则： 表格是阅读工具，不是主视觉区块。应区分标题、表头、正文、行键和数值的角色；等宽字体仅用于定宽数值。如果作品包含密集的对比信息或证据，请阅读 patterns/table.md。

交互状态指引： 如果创作中包含功能性控件或原位状态变化，请阅读 patterns/interactive-states.md。

AI 套话检测（两个层次）

运行两项检测：

• 第一层： 仅凭主题是否就能预测模板和调色板？检查缺乏依据的刻板印象，而不是已获批准的品牌识别；色相名称不是禁令。
• 第二层： 主题加上反向参考是否就能预测美学类型？避免换成另一种过度饱和的惯性风格，例如在来源和文体不支持时采用奶油色／Georgia／边注式编辑风、等宽字体／网格／粗边框终端风，或全大写／无衬线哥特体／网格瑞士海报风。

重新调整缺乏依据的默认选择，直到两项检测都无法预测设计处理方式；保留已获批准的品牌识别。

品牌档案

每次渲染都会读取项目根目录中可用的 DESIGN.md（视觉识别／令牌）、PRODUCT.md（语气／受众／风格）和 tokens.css。teach 会将具体项目令牌写入 Stitch 格式的 DESIGN.md 及其 CSS 配套文件，而不是写入 theme: <name> 指针；其架构和推导流程见 reference/teach.md。

**权威来源：**持久化的 DESIGN.md 和 tokens.css 决定视觉令牌；PRODUCT.md 决定语气和受众。项目说明用于补充缺失信息，除非用户在当前请求中明确另有要求，否则不得覆盖持久化令牌。锁定上下文前，先应用 Artifact 主题中获准的例外。

品牌权威范围限定于身份。如果请求指定了某个具名身份，但解析出的项目配置文件显然属于另一款产品，请勿替换、重新标注或近似模拟该身份。在形状门槛检查或任何 Artifact 编辑之前停止，并请求提供匹配的权威依据，或明确许可仅对 Artifact 覆盖。

design-systems/ 软件包为 teach、System Explore 和 Artifact 主题提供指导、令牌和预览。

已安装的技能包含目录索引和 Clean 回退方案。使用 node $SKILL_DIR/scripts/catalog.mjs <slug> 解析所选参考，并读取返回的文件路径；仅在检查预览时添加 --previews。其他软件包从 design-systems/catalog-source.json 中发布的修订版本获取，并缓存在本地。软件包链接根据返回的源 URL 解析；共享工作流仍使用此已安装技能。如果解析失败，请报告该参考不可用，不要编造其指导内容，也不要悄悄替换用户明确选择的内容。VISUALIZE_CATALOG_CACHE_DIR 可用于更改缓存位置。

不存在 DESIGN.md 时的回退方案：

1. 如果有获准的 Artifact 参考，在缺少项目指导时将其保留为基准；不要用种子方案或 Clean 替代。
2. 否则，阅读可用的项目说明（AGENTS.md、CLAUDE.md、README、docs），了解定位、视觉方向、反向参考和设计原则。将可用指导视为有约束力的品牌上下文，包括具名字体、调色板角色、标志／标记规则、密度／风格和反向参考，而非可有可无的氛围描述。近似文本描述之前，先遵循其中引用的令牌、样式表、标志组件和指南。具名字体和调色板角色优先于 Clean 的值；反向参考则排除对应的回退风格。Clean 提供语义令牌表面，不提供其字体、单色调色板或暖色／奶油色默认值。
3. 只有在没有可用视觉方向时，才运行 node $SKILL_DIR/scripts/palette.mjs --from "<topic-or-project-name>"。根据种子方案和简述组合临时的主色、背景、前景、强调色、图表和状态令牌，并使用其 derived 对比度数值、色度预算以及明／暗阶梯。不要估算这些值，也不要原样复制 Clean。如果种子方案与简述冲突，请使用 --not <zone,...> 或 --vary <n> 重新运行，并在形状门槛检查中注明否决项。使用 node $SKILL_DIR/scripts/palette.mjs --check <tokens-or-html> --strict 验证组合后的令牌；在渲染前修复错误（退出码 2）。

使用回退上下文时，每个会话中提示一次 /visualize teach。

缺少持久化品牌文件时的改进动词：simplify／bolder／quieter／animate／polish 使用与创建相同的回退层级。项目说明、README／docs 或其他已加载的上下文可以作为有效的定性品牌依据。只有在不存在可用项目指导时，Clean 默认值才是依据。每当使用回退来源时，都要提及该来源一次，并提示 /visualize teach，以便将回退方案转为真实品牌配置。 优化带有 ≥3 条绝对禁令的制品中的动词：bolder / quieter / animate / polish 会拒绝执行并引导后续操作。在运行摘要中说明："REFUSED — N 条绝对禁令（已列出）。此制品需要先进行结构清理，才能应用 <verb>。建议先运行 /visualize simplify <path>（移除禁令模式），然后重新评估。"``Simplify 将带有禁令的输入作为核心使用场景；其他优化动词假定基线干净，不得用于禁令繁多的制品。

制品主题

主题是应用于单个制品的参考设计系统，不是新存储的对象，也不是项目范围的采用方案。默认使用项目系统；在借鉴前，先明确具有约束力的选择、获批例外和未定维度。具名参考或要求增加表现力，不会悄然覆盖具有约束力的选择。对于未解决的冲突，应先澄清；明确的替换许可仅适用于指定的制品和维度。项目未规定之处，不要擅自添加约束。

通过 Brand profile 的目录流程解析所选套件。若返回结果中包含 README.md，请先阅读，然后再阅读 DESIGN.md 和 tokens.css。DESIGN 负责确定适用性、身份特征和适配方式。预览用于展示处理效果，并非必需布局。当用户需要备选方案时，提供少量相关候选项；不要加载整个目录。缺少 README 不代表套件不可用。

通过创建或修订来应用设计处理方式；通过 explore artifact 比较尚未确定的处理方式。两者都不需要新布局或项目配置。根据源内容和读者任务推导新结构。除非用户要求更改，否则保留现有内容、顺序、资产和行为。大范围重设样式时，应使用 reference/create.md 并明确指定范围，不要超出优化动词的差异保护范围。现有审批关卡仍然适用；若明确请求涵盖拟议更改，则无需再次确认。

除了调色板和字体，还应转换层级、间距、表面效果和组件处理方式。保留未被覆盖的项目选择。在制品中嵌入已解析的令牌，并支持浅色、明确指定的深色和操作系统深色模式；不要替换项目的令牌来源。应依据已解析的制品上下文进行验证，而非依据被覆盖的值。准确说明部分借鉴的内容和保留的约束。在现有任务备注或简短的制品注释中记录获批例外及其范围，以便后续优化；未作说明的偏离不代表已获批准。

项目范围的采集或推导使用 teach；比较新的系统或明确要求替换的系统时使用 explore system。两者都不是应用制品主题的前置条件。

通用准则

适用于每条命令、每个模板、每条提示词。这些准则优先于上下文相关的风格判断，但不优先于与上下文无关的正确性约束：

1. 已确定的上下文和语气优先于上下文相关的风格规则。 仅仅与已批准的语体冲突的发现，属于类别错误。上下文不能掩盖未跳过的绝对禁令、遗留产物或占位符、无障碍要求，也不能掩盖诚信或数据真实性问题。获准完善某项产物，并不代表可以更改项目的品牌档案或共享令牌源。除非用户已授权，否则应单独提出对这些权威来源所做的必要修改。
2. 命令负责解读，而非重新生成。 迭代命令应返回有针对性的差异，而不是全新草稿。如果差异超过产物的 40%，则命令执行有误。
3. 阻止发布的问题与风格判断不同。 必须修复无障碍和对比度问题；风格判断则可以协商。
4. 严重程度取决于上下文，包括问题的总体影响。 info 规则累积起来也可能阻止发布；只有当 error 规则取决于上下文，且品牌白名单允许时，它才可能只是风格判断。第 1 条中的无上下文约束不应降低严重程度。
5. 不要为了规避问题而把产物剥离得面目全非。 命令运行后，产物仍应牢牢扎根于已确定的上下文。
6. 读者才是评判者。 每项发现都应回答：这会让读者更难完成任务，还是只是在满足规则？
7. 检测器输出是缺陷证据，而非完成证据。 detect.mjs 检测结果干净，并不能证明产物质量出色，只能证明它通过了机械层面的最低要求。检测器能捕捉正则表达式可识别的问题；其余问题则需通过文字审查处理。不要因为检测结果干净就宣布完成。
8. 以手机上的实际呈现为准，而非桌面端的设想。 在桌面端表现出色、但在手机上只是简单堆叠的版式，仍可能不如朴素的文档。应将手机上前两个屏幕视为完整的阅读状态来评估：标题字号、元数据换行、目录位置、卡片装饰和正文节奏，在窄屏上都应显得经过精心设计。
9. 元数据应能自我说明。 像 display.dev strategy 或 Updated May 29, 2026 这样的裸标签会迫使读者猜测字段含义。优先使用明确的标签：Memo type / display.dev strategy、Updated / May 29, 2026、Input / method, vision, competitor refresh。应根据 create.md 的文档上下文指南放置带标签的上下文；并非每项元数据都应放在开头。
10. 整洁还不够。 机械正确性和视觉润色并不能保证读者理解。视觉产物需要经过精心编排，以帮助读者理解其来源。除了开头，还要评估首屏之后的重要说明；遵循具体性与理解度检查。只要能满足读者需求，常见的版式安排就是合理的；只有在确实存在不足时才应调整结构，而不是仅仅为了避免常见版式。