Back to Details

visual-designer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

visual-designer — the visual spec, and its execution when there is a tool

visual-designer — 视觉规范及工具可用时的执行流程

It writes what a visual piece has to say and how it has to be organized, before anyone opens a design tool. The piece can be a product interface (screens and states), a presentation (slides), an infographic (one surface that has to be read in one pass), or another visual artifact that has a reader and a purpose. Generic domain example: the four screens of the appointment-reminder flow of a B2B app for small clinics, or the twelve slides that explain that flow to the clinics.
The specification is the deliverable. Building it is a branch that only opens if the session has a tool for it — see "The execution check" at the end.
它会在任何人打开设计工具之前，明确视觉作品所要传达的信息以及组织方式。作品可以是产品界面（屏幕及状态）、演示文稿（幻灯片）、信息图（需一次性浏览的单页内容），或是其他有目标受众和明确用途的视觉产物。通用场景示例：面向小型诊所的B2B应用中预约提醒流程的4个界面，或是向诊所讲解该流程的12页幻灯片。
规范本身就是交付成果。只有当会话中具备对应的制作工具时，才会开启制作分支——详见末尾的「执行检查」部分。

When it is invoked

调用时机

WhenFrom / to
The prototype brief from 
ideation-engine
is written		Entry from 
ideation-engine
(
.claude/skills/ideation-engine/SKILL.md
) — the key flow and the minimum screens of that brief are the input of the interface spec
The visual spec is writtenExit: execution. If the session has a tool able to build it, it is offered right there; if not, the document is the end of the station and whoever builds it builds it from there
Any piece with a reader and a purposeInvocable on its own, with no prior station: a deck, an infographic, a screen that has to exist tomorrow
时机来源/去向
ideation-engine
生成原型 brief 后		从
ideation-engine
接入（
.claude/skills/ideation-engine/SKILL.md
）——该brief中的核心流程和最小化界面是界面规范的输入
视觉规范撰写完成后输出：执行环节。若会话中有可制作该作品的工具，则直接提供制作选项；若无，则文档即为流程终点，后续制作需基于该文档完成
任何有目标受众和明确用途的作品可独立调用，无需前置流程：比如演示文稿、信息图、次日需完成的界面

Rule number one

核心规则

It never invents content that the piece does not have. A screen with no data behind it, a slide with a number nobody measured or an infographic whose source is not written down are specifications that look finished and are not. What is missing is asked for; what stays missing is written as a gap in the spec, never filled in with something plausible.
绝不凭空捏造作品中不存在的内容。没有数据支撑的界面、包含未测算数值的幻灯片、未标注信息来源的信息图，这类看似完整的规范实则无效。缺失的内容会被提出询问；若仍无法获取，则会在规范中明确标注为空白，绝不会用看似合理的内容填充。

The interview

需求确认环节

The purpose, the reader and the success condition of the piece are pressured with the method of 
.claude/skills/grill/SKILL.md#method
—cited by path, never copied— before any structure gets written. Three questions carry the weight, and none of them is answered by the operator saying "it has to look good":
  • Who reads it, and in what situation? Someone scrolling on a phone between patients is not someone sitting through a presentation.
  • What has to happen after they read it? One action, one decision, one thing understood. A piece with three purposes has none.
  • What is the one thing that, if it does not get across, makes the piece a failure? That is what the hierarchy is built around, and everything else is subordinate to it.
在撰写任何结构内容之前，会通过
.claude/skills/grill/SKILL.md#method
方法（仅引用路径，不复制内容）明确作品的目的、受众和成功标准。以下三个问题是核心，且不能用「看起来好看」这类回答应付：
  • 谁会阅读它？阅读场景是什么？ 在患者间隙用手机浏览的用户，和坐着看演示的用户需求完全不同。
  • 阅读完成后需要达成什么结果？ 一个动作、一个决策、一个明确的认知。一个有三个目标的作品等于没有目标。
  • 如果哪一点没传达到位，会导致作品彻底失败？ 整个层级结构都会围绕这一点构建，其他所有内容都要从属于此。

Method

方法准则

The shared visual criteria. Any tool of the pack that needs to reason about a visual piece cites this section by path —
.claude/skills/visual-designer/SKILL.md#method
— and never copies it.
通用视觉标准。套件中任何需要对视觉作品进行逻辑推导的工具，都会引用本节路径——
.claude/skills/visual-designer/SKILL.md#method
——而非复制内容。

1. One hierarchy per surface

1. 每个页面一个核心层级

Every screen, slide or surface has one primary element, and it is named in the spec. What is primary is read first, is the largest or the most contrasted, and is alone in that condition. Two primary elements are zero primary elements: the eye chooses, and it does not choose the one you wanted.
每个屏幕、幻灯片或页面都有一个核心元素，并在规范中明确标注。核心元素是最先被阅读的，尺寸最大或对比度最高，且唯一具备此属性。两个核心元素等于没有核心元素：用户的注意力会自行选择，而未必是你期望的那个。

2. Air is content

2. 留白也是内容

Empty space is not room going to waste: it is what makes the hierarchy readable. Anything that gets added by filling a hole competes with what was already there. If a block does not fit without removing air, the block does not fit — what gets cut is decided, not squeezed.
空白空间不是浪费的区域：它是让层级结构清晰可读的关键。为填补空白而添加的任何内容，都会与原有内容争夺注意力。如果一个模块无法在不压缩留白的情况下容纳，那它就不适合放在这里——需要决定删减内容，而非强行挤压。

3. Contrast carries the meaning, never decoration alone

3. 对比度承载意义，而非单纯装饰

Difference in size, weight or color is used to say something —this comes first, this is a warning, this is secondary— and every difference in the spec carries what it means next to it. Contrast that means nothing is noise, and it costs the same attention as the useful kind. Contrast that carries meaning is never carried by color alone: it also has size, weight or position, so it survives a reader who does not distinguish the two colors and a piece printed in grayscale.
尺寸、字重或颜色的差异是用来传递信息的——比如这是首要内容、这是警告、这是次要信息——规范中每个差异都会附带其对应的意义。无意义的对比度是噪音，会消耗和有用信息同样多的注意力。承载意义的对比度绝不能仅依赖颜色：还需结合尺寸、字重或位置，这样即使是色盲用户或作品被打印成灰度，信息依然能被识别。

4. One block, one message

4. 一个模块，一个信息

Every block —a section of a screen, a slide, an area of an infographic— says one thing and can be summarized in one line. That line goes into the spec, written before the content of the block: what cannot be summarized has not been thought through, and no amount of typography saves it.
每个模块——界面的一个区域、一张幻灯片、信息图的一块区域——只传达一个信息，且能用一句话概括。这句话会先写在规范中，再写模块的具体内容：无法被概括的内容说明还未思考透彻，再好的排版也无法挽救。

5. The state that is not the happy one

5. 非理想状态的覆盖

An interface with no empty, loading and error state is half specified; a deck with no slide for the objection it will get is half specified. Every piece declares its uncomfortable state, and what it says when it happens.
未包含空状态、加载状态和错误状态的界面规范是不完整的；未包含异议应对幻灯片的演示文稿规范也是不完整的。每个作品都要明确其非常规状态，以及这些状态下的显示内容。

The visual spec

视觉规范文档

It closes by writing the deliverable as a dated document of the loaded product node, in:
context/<YYYY-MM-DD>-visual-spec.md
Dated, never overwritten. The path falls inside 
content: orgs/*/products/*/context/*.md
of 
tree.md
: no new glob and no resolver row are needed.
The spec carries these five sections, in this order, each with its literal heading:
undefined
最终会生成一份带日期的产品节点文档，路径为：
context/<YYYY-MM-DD>-visual-spec.md
带日期，永不覆盖。该路径位于
tree.md
的
content: orgs/*/products/*/context/*.md
下：无需新增glob规则或解析器行。
规范包含以下五个固定顺序的章节，每个章节使用指定标题：
undefined

The piece and its purpose

作品及目的

Structure and hierarchy

结构与层级

Content, block by block

模块内容明细

Visual criteria applied

应用的视觉标准

Gaps and what it does not cover

空白内容与未覆盖范围


- **The piece and its purpose**: what kind of piece it is, who reads it and in what situation, what
  has to happen after, and the one thing that cannot fail to get across.
- **Structure and hierarchy**: the surfaces in order —screens, slides, areas— and for each one its
  primary element, named as primary.
- **Content, block by block**: every block with its one-line message first and its actual content
  after: literal text, what data goes in, what image or diagram and what it shows. Real copy, never
  filler text.
- **Visual criteria applied**: which of the five ingredients above governed each decision, and where
  a decision went against one and why.
- **Gaps and what it does not cover**: what data or copy is missing, who provides it, and the states
  or surfaces left out of this round on purpose.

- **作品及目的**：说明作品类型、受众及阅读场景、阅读后需达成的结果，以及必须传达到位的核心信息。
- **结构与层级**：按顺序列出所有页面——屏幕、幻灯片、区域——并为每个页面标注核心元素。
- **模块内容明细**：每个模块先写一句话概括的信息，再写具体内容：包括确切文本、需填充的数据、图片或图表及其展示内容。使用真实文案，绝不使用占位文本。
- **应用的视觉标准**：说明每个决策遵循了上述哪一条准则，以及若有决策违背准则的原因。
- **空白内容与未覆盖范围**：说明缺失的数据或文案、提供方是谁，以及本次规范刻意忽略的状态或页面。

The execution check

执行检查

After writing the document, and only then, it checks whether the session has a tool able to build this kind of piece — a design integration connected to the harness, such as the Figma MCP, which covers interfaces and slides.
  • If there is one: it says so and offers to build the piece from the spec, naming the tool. Building is a separate step that the operator asks for: the document is already written and stays written either way. What gets built follows the spec and does not add content — anything missing comes back as a gap, never as an invention.
  • If there is none: it closes with the document and one line: connect Figma and this same skill builds it. It does not install anything, does not ask for credentials, and does not degrade the spec because there is no tool: the specification is the deliverable, and the tool only saves the transcription.
An infographic, or any piece the connected tool does not cover, closes with the document as well: a tool is offered when it can actually build that piece, not because it is connected.
只有在文档撰写完成后，才会检查当前会话是否有可制作该类作品的工具——比如与系统集成的设计工具，如Figma MCP，可支持界面和幻灯片制作。
  • 若存在对应工具：会告知用户并提供基于规范制作作品的选项，同时指明工具名称。制作是独立的步骤，需用户主动发起：无论是否制作，文档都会保留。制作过程严格遵循规范，不会新增内容——任何缺失的内容都会返回为空白，绝不凭空捏造。
  • 若不存在对应工具：仅输出文档，并附加一行提示：连接Figma后，该技能即可完成制作。不会安装任何工具、不会索要凭证，也不会因无工具而降低规范质量：规范本身就是交付成果，工具只是节省转录时间。
对于信息图或其他已连接工具不支持的作品，同样仅输出文档：只有当工具确实能制作该作品时，才会提供制作选项，而非仅因工具已连接就提供。

What this deliverable does not claim

交付成果的局限性

The visual spec does not validate that the piece works: that it gets read, understood and acted on is something only its real reader answers. And it does not decide what the product does — the flow it specifies comes from the prototype brief of 
ideation-engine
, and the scope from 
prd
(
.claude/skills/prd/SKILL.md
).
视觉规范不验证作品是否有效：作品是否被阅读、理解并产生行动，只有真实受众才能给出答案。同时，它也不决定产品功能——规范的流程来自
ideation-engine
的原型brief，范围来自
prd
（
.claude/skills/prd/SKILL.md
）。

Standalone use

独立使用方式

Without a brain, the deliverable is written to a file in the current folder: the process is the same, but nothing is filed into a node, a backlog or a resolver, and no session scan brings it back later. Inside AI First OS the destinations named above are the real ones and this section does not apply.
The rest of the pack installs one skill at a time. Look at 
.claude/skills/
first and offer only the ones that are not there — inside AI First OS they are all installed already, so nothing here gets offered:
  • 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
The whole pack at once: 
npx skills add pedroromeroluna/ai-first-product-skills
.
The system these skills come from is AI First OS — 
github.com/pedroromeroluna/ai-first-os
— where they run over a brain instead of over the current folder.
若未接入AI First OS，交付成果会写入当前文件夹的文件中：流程与接入系统时一致，但不会归档到节点、待办或解析器中，后续会话也无法检索到。在AI First OS中，上述存储路径为默认路径，本部分不适用。
套件中的其他技能需逐个安装。先查看
.claude/skills/
目录，仅提供未安装的技能——在AI First OS中所有技能已预装，因此无需提供以下安装选项：
  • 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
。
这些技能源自AI First OS系统——
github.com/pedroromeroluna/ai-first-os
——在该系统中，技能基于核心大脑运行，而非当前文件夹。