进阶 impeccable.style 2026-11-22 15:26:08 · 2 阅读

第31章 Agent 缺失的设计词汇表

上下文文件 保存 Agent 需要了解的项目信息。 本页共 6 个部分 大多数 Agent 使用 /impeccable。在 Codex 中请使用 $impeccable。 缺失或模糊的上下文会导致更平庸的设计。Impeccable 能读取你的代码,但也需要了解你的用户、他们的目标,以及你想保留的决策。把这些知识随项目一起保存,以便指导后续工作。 关于保持页面一致性的实操指南,请参阅使用设计系统。本页介绍上下文记录及其解析方式。 从产品开始 在 Agent 聊天中运行: /impeccable init Impeccable 会读取项目、询问缺失的上下文,并把确认后的细节保存到 PRODUCT.md。检查它写的内容。你可以自己编辑该文件,或让 Impeccable 修正。 重点说明产品服务的人群、他们需要完成什么,以及设计必须满足的要求。一个有用的回答会把用户的具体场景与决策关联起来:

人们在外出时用手机查看服务中断情况。他们需要看到哪些功能受影响,以及是否有人在处理。

初始化时不需要指定配色或字体。 记录现有视觉系统 如果你的项目已有想保留的视觉风格,运行: /impeccable document Impeccable 会把现有的颜色、排版、布局规则和组件记录到 DESIGN.md。使用它指导后续工作前先阅读一遍,修正任何偶然产物或过时的决策。 只在需要这份记录时单独运行 document;init 保存产品上下文但不创建 DESIGN.md。新项目可以通过构建新东西来确立视觉方向。 内容放哪里

文件 应包含的内容 示例

PRODUCT.md 受众、目标、平台、约束、术语,以及已确认的品牌承诺。 "客户在手机上重复订购耗材。"

DESIGN.md 共享视觉系统:颜色、排版、组件和设计规则。 "主要操作使用现有的主按钮。"

.impeccable/surfaces/*.md 单个页面或路由的决策,例如其目的和选定的设计方向。 "定价页应帮助买家对比方案。"

.impeccable/design.json 工具链使用的生成设计元数据。用 document 刷新,不要手动编辑。 组件预览及额外的 token 信息。

Markdown 文件由你审阅和编辑。document 会把 design token 存储在 DESIGN.md 的 frontmatter 中,并在记录现有系统时生成额外的配套元数据。 说明你正在处理的页面 /impeccable polish the marketing homepage /impeccable audit the billing settings 首页帮助用户判断产品是否满足需求,账单设置则帮助他们完成任务。说出页面名称后,Impeccable 就能采用合适的方式,而不是对所有部分一概而论。

Impeccable 如何选择页面的处理方式 Impeccable 根据用户到该页面的目的,使用四种模式:

说服:决策并行动。落地页、营销活动和定价页。 操作:完成任务。仪表盘、设置、编辑器及其他应用界面。 阅读:理解内容。文档、指南和帮助页面。 体验:探索作品本身。作品集、画廊和展示页。

模式由页面决定。开发者工具的落地页可以用"说服",其文档则用"阅读"。如果页面目的不明确,请说明访客应在此做什么。 解析出的模式会与该页面的简要说明一起记录在 .impeccable/surfaces/ 下。

保持文件有效 项目变化时更新上下文:

变化内容 应采取的操作

受众、目标、平台或产品需求变化 编辑 PRODUCT.md,或运行 /impeccable init 重新梳理相关细节。

视觉系统变化 运行 /impeccable document,从实现中更新记录。

页面目的或设计方向变化 更新 .impeccable/surfaces/ 下对应的简要说明。

不确定哪些内容过时了 运行 /impeccable doctor。关于 Doctor。

如果结果显得平庸或未切中用户需求,先检查上下文。补齐缺失内容、修正过时信息,然后告诉 Agent 还需要改进什么。好的上下文能提升它的判断力;反馈则帮助它打磨结果。

在还没有代码时创建 DESIGN.md 你可以让 document 为新项目确立视觉方向。它需要产品上下文和第一个具体要设计的页面,然后与你一起选定方向。 生成的 DESIGN.md 会标记为种子。它记录选定的方向,未确定的实现细节留空,也暂不生成设计元数据文件。等有代码后再运行 document,以捕获实际的 token 和组件。

如需为检测规则设置有意的例外,请参阅配置与忽略。 参考细节

原生应用:iOS、Android 和自适应 PRODUCT.md 在 ## Platform 下记录平台。init 会从项目中推断,证据不明确时会询问。缺失时默认为 web。

取值 适用场景 设计指引

web 网站和 Web 应用,包括移动端 Web。 Web 界面。 ios 原生 iPhone 和 iPad 应用。 Apple Human Interface Guidelines。 android 原生 Android 应用。 Material Design 3。 adaptive 一套代码库,界面随操作系统自适应。 同时遵循 iOS 和 Android 指引。

原生支持处于 alpha 阶段。audit 和 adapt 会针对屏幕阅读器、触摸目标和平台惯例应用原生指引。Live Mode、浏览器检测器和设计钩子不会检查原生界面。 Flutter、React Native 或 Kotlin Multiplatform 可以支持自适应界面,但仅凭框架不能决定取值。移动端 Web 仍属于 web,包括在原生壳中显示的网站。

上下文文件的存放位置(包括 monorepo 场景) 把 PRODUCT.md 和 DESIGN.md 一起放在项目根目录。Impeccable 也支持 .agents/context/ 和 docs/:它会按此顺序从根目录开始,使用第一个包含上下文的位置。 在 monorepo 中,每个应用可以有自己的上下文。应用自身的文件优先;缺失时回退到仓库根目录。产品上下文和设计上下文分别解析。 例如,下面这个商店共享产品的受众和目标,但拥有自己的视觉系统: repo/ ├── PRODUCT.md 共享受众和目标 ├── DESIGN.md 共享视觉系统 └── apps/ └── store/ ├── DESIGN.md 商店自己的视觉系统 └── src/

在 apps/store/ 中工作时,Impeccable 读取

产品上下文 repo/PRODUCT.md 设计上下文 repo/apps/store/DESIGN.md

如果商店还需要不同的产品上下文,就添加自己的 PRODUCT.md。 项目边界来自 package-workspace 声明或 .impeccable/config.json 中的 projectRoots。配置的模式可以覆盖其匹配路径的包边界。示例和优先级规则见项目边界。 生成的设计元数据放在 .impeccable/design.json。旧的 DESIGN.json 文件仍作为后备被识别;用 document 生成当前格式。

上下文与代码不一致时怎么办

每种记录回答不同的问题:

PRODUCT.md:产品服务谁、承诺什么,以及哪些要求和品牌承诺必须成立。 DESIGN.md:共享的视觉选择、组件和交互规则。 页面简要说明:该页面需要达成什么,以及为它选定的方向。

实现本身也是证据。当既有惯例比文档更新时,Impeccable 应当保留它们。 例如,如果代码已使用你批准的新字体,而 DESIGN.md 还写着旧字体,就更新记录。如果代码引入了意外的字体变更,就修正代码。当证据无法裁定时,说明哪个决策是当前有效的。 用 document 刷新现有视觉系统的记录,或用 doctor 检查过时或不兼容的上下文。

检测器对照设计系统检查什么

当 DESIGN.md 可用时,检测器和设计钩子可以检查是否偏离文档中的值:

规则 检查内容

design-system-font 文档排版体系之外的字体。 design-system-color 调色板及配套文件色阶之外的字面颜色。 design-system-radius 文档规格之外的圆角半径。 design-system-font-size 文档字号规格之外的字面字号。

这些检查需要对应的设计值。文件的存在本身不等于完整的系统。用 document 保持 DESIGN.md 及其生成的配套文件最新。 当 DESIGN.md 不存在、配置已禁用、或扫描使用 --no-design-system 时,会跳过设计系统检查。其他检测器检查仍可运行。扫描选项见 Detector CLI,有意的例外见配置与忽略。

从旧的 brand/product register 升级 模式取代了旧的 brand/product register。Brand 对应"说服",product 对应"操作"。"阅读"和"体验"覆盖以学习或探索为目的的页面。 模式属于页面的简要说明。PRODUCT.md 中旧的 ## Register 部分不再使用。doctor 会标记它并提议删除,以免后续读者误认为它仍是当前设置。

评论 (0)