visual-designer

visual-designer — 视觉规范，以及有工具时的执行

在任何人打开设计工具之前，它会写明视觉作品要传达什么，以及如何组织。作品可以是产品界面（屏幕和状态）、演示文稿（幻灯片）、信息图（需要一次读完的单个画面），或其他有读者、有目的的视觉产物。通用领域示例：面向小型诊所的 B2B 应用中，预约提醒流程的四个屏幕；或向诊所说明该流程的十二张幻灯片。

规范本身就是交付成果。制作工作只是一个分支，只有在当前会话具备相应工具时才会开启——见末尾的“执行检查”。

何时调用

时机	来源 / 去向
ideation-engine 写好原型简报后	从 ideation-engine 进入（.agents/skills/ideation-engine/SKILL.md）——该简报中的关键流程和最少屏幕数，是界面规范的输入
写好视觉规范后	前往执行。如果当前会话有能制作它的工具，就立即提供该选项；如果没有，文档就是此阶段的终点，后续由实际制作的人据此完成
任何有读者、有目的的作品	可独立调用，无需经过前置阶段：演示文稿、信息图，或必须在明天完成的屏幕

第一原则

绝不臆造作品中不存在的内容。 没有数据支撑的屏幕、包含无人测量过的数字的幻灯片，或未注明来源的信息图，看似完成，实则不然。缺少什么就询问什么；仍然缺少的内容要作为缺口写入规范，绝不以看似合理的内容填补。

访谈

在编写任何结构之前，使用 .agents/skills/grill/SKILL.md#method 中的方法深入追问作品的目的、读者和成功条件——只引用路径，不复制内容。三个问题至关重要，操作者说“要好看”并不能回答其中任何一个：

• 谁会阅读，处于什么情境？ 一边照看患者、一边在手机上浏览的人，与坐下来听演示的人并不相同。
• 读完之后要发生什么？ 一个行动、一个决定、一件理解的事。有三个目的的作品，其实一个目的也没有。
• 如果有一件事没有传达清楚，这部作品就会失败；那件事是什么？ 视觉层级围绕它构建，其他内容都从属于它。

方法

通用视觉标准。工具包中任何需要分析视觉作品的工具，都应通过路径引用本节——.agents/skills/visual-designer/SKILL.md#method——绝不复制内容。

1. 每个画面只有一个层级焦点

每个屏幕、幻灯片或画面都只有一个主要元素，并在规范中明确指出。主要元素应最先被看到，尺寸最大或对比最强，并且是唯一具备这些特征的元素。两个主要元素就等于没有主要元素：读者会自行选择，而不一定选中你希望他们看到的那个。

2. 留白也是内容

空白不是浪费空间，而是让层级清晰可读的关键。填补空白而添加的内容，会与已有内容争夺注意力。如果一个区块无法在保留留白的前提下放入，那它就放不下——该删什么要做出决定，而不是挤进去。

3. 对比传达含义，而非仅作装饰

大小、粗细或颜色上的差异用于传达信息——这个最重要、这是警告、这是次要内容——规范中每一种差异都要明确说明其含义。没有含义的对比只是噪声，与有用的对比同样消耗注意力。传达含义的对比绝不能只靠颜色：还要通过大小、粗细或位置体现，这样色觉无法区分这两种颜色的读者，以及以灰度打印的作品，也能保留其中的含义。

4. 一个区块，只传达一条信息

每个区块——屏幕的一部分、幻灯片、信息图的某个区域——只传达一件事，并且可以用一句话概括。这句话要写进规格文档，并置于区块内容之前：无法概括的内容说明还没有经过充分思考，再多的排版也无法挽救。

5. 不那么理想的状态

没有空状态、加载状态和错误状态的界面，规格就不完整；没有为可能遇到的质疑准备幻灯片的演示文稿，规格也不完整。每个作品都要说明其棘手状态，以及发生这种情况时要传达什么。

视觉规格

最后，将交付内容写成一份带日期的文档，存放在已加载产品节点的：

research/<YYYY-MM-DD>-visual-spec.md

添加日期，绝不覆盖。路径位于脑图自身的 tree.md 中 content: */products/*/research/*.md 这一行所指定的位置：无需添加新的 glob，也无需添加 resolver 行。如果没有产品节点，则将同一文件——<YYYY-MM-DD>-visual-spec.md——写入当前文件夹。

规格文档按以下顺序包含这五个部分，每部分都使用对应的原样标题：

## The piece and its purpose
## Structure and hierarchy
## Content, block by block
## Visual criteria applied
## Gaps and what it does not cover

• 作品及其用途：作品的类型、读者是谁及其阅读情境、之后需要采取什么行动，以及必须传达清楚的一件事。
• 结构与层级：按顺序列出各个界面——屏幕、幻灯片、区域——并为每个界面明确标出主要元素。
• 逐区块内容：列出每个区块，先写一句话概括，再写实际内容：原文、需要填入的数据、图像或图表及其展示内容。使用真实文案，绝不使用占位文本。
• 已采用的视觉标准：说明上述五项要素分别如何影响每项决策，以及哪些决策违背了其中某项标准、原因是什么。
• 缺口与未涵盖内容：说明缺少哪些数据或文案、由谁提供，以及本轮有意排除的状态或界面。

执行检查

写完文档后，且只能在这之后，检查当前会话是否有能够制作此类作品的工具——例如连接到 harness 的设计集成工具，如可处理界面和幻灯片的 Figma MCP。

• 如果有：说明这一点，并提出根据规格文档制作作品，同时指出所用工具。制作是单独的步骤，由操作者提出请求：无论是否制作，文档都已写好并会保留。制作出的内容遵循规格文档，不会添加内容——任何缺失内容都会作为缺口反馈，绝不会凭空编造。
• 如果没有：以文档和一句话结束：连接 Figma 后，此技能即可制作作品。不会安装任何东西，也不会索要凭据；不会因为缺少工具而降低规格要求：交付物就是规格文档，工具只是省去誊写工作。

对于信息图，或连接的工具无法涵盖的任何作品，同样以文档结束：只有在工具确实能够制作该作品时才会提供，而不是仅仅因为工具已连接。

本交付物不作何种保证

视觉规格不会验证作品是否有效：作品是否被阅读、理解并促成行动，只有真正的读者才能回答。它也不会决定产品的功能——规格中描述的流程源自 ideation-engine 的原型简报，范围则源自 prd（.agents/skills/prd/SKILL.md）。

目标位置

技能会在生成交付物之前确定目标位置，而不是之后。共有三种情况， 两个目标位置：

• 已加载产品节点：交付物写入该节点的 research/<YYYY-MM-DD>-<name>.md。
• 有 brain，但没有产品节点——尚无 workspace，或 workspace 中没有产品节点：交付物写入当前文件夹中的文件。
• 完全没有 brain：交付物写入当前文件夹中的文件。

没有产品节点时，文件仍会写入当前文件夹。结束消息只写出刚刚写入的路径，然后结束——这是此技能的正常结束方式，无需特别说明。

此技能绝不会询问要使用哪个目标位置，也绝不会另行编造第三个目标位置。

此技能包的其余部分每次安装一个技能。先查看 .agents/skills/，再查看 .claude/skills/（同时存在于两处的技能只算一次），并且只提供尚未安装的技能——每个会话只提供一次：在本会话中，此技能首次结束时提供，之后无论同一交付物还是其他交付物再次结束，都不再提供：

• grill — npx skills add pedroromeroluna/ai-first-product-skills --skill grill
• ideation-engine — npx skills add pedroromeroluna/ai-first-product-skills --skill ideation-engine
• prd — npx skills add pedroromeroluna/ai-first-product-skills --skill prd

一次安装整个技能包：npx skills add pedroromeroluna/ai-first-product-skills。该命令会安装技能包提供的所有内容；上面列出的技能需通过指定名称单独安装。