impeccable

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.

设计并迭代生产级前端界面。提供可运行的真实代码、明确的设计选择、精湛的工艺。

Setup

准备工作

Before any design work or file edits:

Load context (PRODUCT.md / DESIGN.md) via the loader script.
Identify the register and load the matching register reference (brand.md or product.md).
If the user invoked a sub-command (e.g.
craft
,
shape
,
audit
), load its reference file too. This is non-negotiable:
```
craft
```
without
```
craft.md
```
loaded means you'll skip the shape-and-confirm step the user expects.

Skipping these produces generic output that ignores the project.

在进行任何设计工作或文件编辑之前：

通过加载器脚本加载上下文（PRODUCT.md / DESIGN.md）。
确定注册类型并加载对应的参考文件（brand.md或product.md）。
**如果用户调用了子命令（如
```
craft
```
、
```
shape
```
、
```
audit
```
），也要加载其对应的参考文件。**这是硬性要求：如果未加载
```
craft.md
```
就执行
```
craft
```
，会跳过用户预期的塑造与确认步骤。

跳过这些步骤会生成忽略项目特性的通用输出。

1. Context gathering

1. 上下文收集

Two files, case-insensitive. The loader looks at the project root by default and falls back to

.agents/context/

and

docs/

if the root is clean. Override with

IMPECCABLE_CONTEXT_DIR=path/to/dir

(absolute or relative to cwd).

PRODUCT.md: required. Users, brand, tone, anti-references, strategic principles.
DESIGN.md: optional, strongly recommended. Colors, typography, elevation, components.

Load both in one call:

bash

node {{scripts_path}}/load-context.mjs

Consume the full JSON output. Never pipe through

head

tail

grep

, or

jq

. The output's

contextDir

field tells you where the files were resolved from.

If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran

{{command_prefix}}impeccable teach

{{command_prefix}}impeccable document

(they rewrite the files), or the user manually edited one.

{{command_prefix}}impeccable live

already warms context via

live.mjs

. If you've run

live.mjs

, don't also run

load-context.mjs

this session.

If PRODUCT.md is missing, empty, or placeholder (

[TODO]

markers, <200 chars): run

{{command_prefix}}impeccable teach

, then resume the user's original task with the fresh context. If the original task was

{{command_prefix}}impeccable craft

, resume into

{{command_prefix}}impeccable shape

before any implementation work.

If DESIGN.md is missing: nudge once per session ("Run
{{command_prefix}}impeccable document
for more on-brand output"), then proceed.

两个文件，大小写不敏感。加载器默认在项目根目录查找，如果根目录为空，则会回退到

.agents/context/

和

docs/

目录。可通过

IMPECCABLE_CONTEXT_DIR=path/to/dir

（绝对路径或相对于当前工作目录的路径）覆盖默认目录。

PRODUCT.md：必填。包含用户群体、品牌、风格基调、反参考案例、战略原则。
DESIGN.md：可选，但强烈推荐。包含颜色、排版、层级、组件等信息。

一次性加载两个文件：

bash

node {{scripts_path}}/load-context.mjs

使用完整的JSON输出结果。切勿通过

head

、

tail

、

grep

或

jq

进行管道处理。输出中的

contextDir

字段会告知文件的解析路径。

如果输出结果已存在于当前会话的对话历史中，请勿重新运行。以下情况需要重新加载：你刚执行了

{{command_prefix}}impeccable teach

或

{{command_prefix}}impeccable document

（它们会重写文件），或者用户手动编辑了其中一个文件。

{{command_prefix}}impeccable live

已通过

live.mjs

预加载上下文。如果已运行

live.mjs

，当前会话无需再运行

load-context.mjs

。

如果PRODUCT.md缺失、为空或为占位内容（包含

[TODO]

标记，内容少于200字符）：执行

{{command_prefix}}impeccable teach

，然后使用新的上下文继续用户的原始任务。如果原始任务是

{{command_prefix}}impeccable craft

，在开始任何实现工作前，先切换到

{{command_prefix}}impeccable shape

流程。

如果DESIGN.md缺失：每个会话提示一次（"执行
{{command_prefix}}impeccable document
以获得更贴合品牌的输出"），然后继续后续工作。

2. Register

2. 注册类型

Every design task is brand (marketing, landing, campaign, long-form content, portfolio: design IS the product) or product (app UI, admin, dashboard, tool: design SERVES the product).

Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3)

register

field in PRODUCT.md. First match wins.

If PRODUCT.md lacks the

register

field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run

{{command_prefix}}impeccable teach

to add the field explicitly.

Load the matching reference: reference/brand.md or reference/product.md. The shared design laws below apply to both.

每个设计任务分为品牌类（营销页、着陆页、活动页、长内容页、作品集：设计即产品本身）或产品类（应用UI、后台管理、仪表板、工具：设计为产品服务）。

设计前需确定类型。优先级：(1) 任务本身的提示（"着陆页" vs "仪表板"）；(2) 聚焦的界面（页面、文件或路由）；(3) PRODUCT.md中的

register

字段。匹配到第一个即可。

如果PRODUCT.md缺少

register

字段（旧版本），从其"用户群体"和"产品目标"部分推断一次，然后在会话中缓存该推断值。建议用户执行

{{command_prefix}}impeccable teach

来显式添加该字段。

加载对应的参考文件：reference/brand.md 或 reference/product.md。以下共享设计规则适用于两种类型。

Shared design laws

共享设计规则

Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. {{model}} is capable of extraordinary work. Don't hold back.

适用于所有设计任务，两种注册类型均需遵守。实现复杂度需与美学愿景匹配：极简主义需要精准的代码，极繁主义需要精细的实现。创造性地解读规则，不同项目采用不同的设计选择，切勿趋同。{{model}}具备出色的工作能力，无需受限。

Color

颜色

Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish.
Never use
```
#000
```
or
```
#fff
```
. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
Pick a color strategy before picking colors. Four steps on the commitment axis:
- Restrained: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
- Committed: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
- Full palette: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
- Drenched: the surface IS the color. Brand heroes, campaign pages.
The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.

使用OKLCH颜色模式。当亮度接近0或100时降低色度；极端亮度下高色度会显得俗气。
切勿使用
```
#000
```
或
```
#fff
```
。所有中性色都需向品牌色调微调（色度0.005–0.01即可）。
选择颜色前先确定色彩策略。按投入程度分为四个层级：
- 克制型：微调后的中性色 + 一种强调色（占比≤10%）。产品类默认策略；品牌类极简风格。
- 投入型：一种饱和色占据界面30–60%的面积。品牌类品牌驱动页面的默认策略。
- 全色系：3–4个明确功能的颜色角色，每个颜色都有特定用途。品牌类活动页；产品类数据可视化。
- 沉浸型：界面本身即为颜色。品牌类核心展示区、活动页。
"一种强调色≤10%"仅适用于克制型策略。投入型/全色系/沉浸型策略可故意打破该规则。切勿习惯性地将所有设计都归为克制型。

Theme

主题

Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."

Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does.

"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.

深色与浅色主题绝非默认选择。不要因为"工具深色看起来很酷"就选深色，也不要为了"安全"就选浅色。

选择主题前，先写一句话描述使用场景：谁在使用、在哪里使用、环境光线如何、处于什么情绪状态。如果这句话无法确定主题，说明不够具体。补充细节直到能明确主题为止。

"可观测性仪表板"无法确定主题。"SRE在凌晨2点的昏暗房间里，盯着27英寸显示器查看事件严重性"则可以。依据场景描述而非类别来选择主题。

Typography

排版

Cap body line length at 65–75ch.
Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.

正文行长度限制在65–75ch。
通过字号+字重对比（层级间比例≥1.25）构建视觉层次。避免扁平化的字号体系。

Layout

布局

Vary spacing for rhythm. Same padding everywhere is monotony.
Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
Don't wrap everything in a container. Most things don't need one.

通过变化间距营造韵律感。所有元素使用相同内边距会显得单调。
卡片是偷懒的选择。仅当卡片确实是最佳交互载体时才使用。嵌套卡片绝对不可取。
不要给所有元素都套上容器。大多数元素不需要容器。

Motion

动效

Don't animate CSS layout properties.
Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.

不要为CSS布局属性添加动画。
使用指数曲线实现淡出效果（ease-out-quart / quint / expo）。禁止弹跳或弹性动画。

Absolute bans

绝对禁用项

Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.

Side-stripe borders.
```
border-left
```
or
```
border-right
```
greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
Gradient text.
```
background-clip: text
```
combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.
Glassmorphism as default. Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
The hero-metric template. Big number, small label, supporting stats, gradient accent. SaaS cliché.
Identical card grids. Same-sized cards with icon + heading + text, repeated endlessly.
Modal as first thought. Modals are usually laziness. Exhaust inline / progressive alternatives first.

识别并拒绝以下设计。如果即将编写此类元素，需重构为不同的结构。

侧边条纹边框。在卡片、列表项、提示框或警告框上使用宽度大于1px的
```
border-left
```
或
```
border-right
```
作为彩色强调。绝对禁止。可改用完整边框、背景色微调、前置数字/图标，或不添加任何装饰。
渐变文字。
```
background-clip: text
```
结合渐变背景。仅为装饰性，无实际意义。使用单一纯色。通过字重或字号实现强调效果。
默认使用毛玻璃效果。将模糊和毛玻璃卡片用作装饰。仅在特定场景下使用，否则禁用。
核心指标模板。大数字、小标签、辅助统计数据、渐变强调。SaaS行业陈词滥调。
相同尺寸的卡片网格。重复排列相同尺寸的卡片，包含图标+标题+文本。
优先使用模态框。模态框通常是偷懒的选择。先尝试内联/渐进式替代方案。

Copy

文案

Every word earns its place. No restated headings, no intros that repeat the title.
No em dashes. Use commas, colons, semicolons, periods, or parentheses. Also not
```
--
```
.

每个字都要有存在的意义。不要重复标题内容，不要添加与标题重复的引言。
禁止使用破折号。使用逗号、冒号、分号、句号或括号。也禁止使用
```
--
```
。

The AI slop test

AI劣质设计测试

If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.

Category-reflex check. Run at two altitudes; the second one catches what the first one misses.

First-order: if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
Second-order: if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's reflex-reject aesthetic lanes list catches the currently-saturated families.

如果有人看到这个界面能毫无疑问地说"这是AI做的"，则测试失败。跨注册类型的失败项为上述绝对禁用项。注册类型特有的失败项在各自的参考文件中。

类别思维定式检查。从两个层面进行检查；第二个层面能发现第一个层面遗漏的问题。

第一层面：如果有人仅通过类别就能猜出主题+配色（"可观测性→深蓝色"、"医疗→白色+蓝绿色"、"金融→深蓝色+金色"、"加密货币→黑色背景+霓虹色"），这是受训练数据影响的第一重思维定式。重新编写场景描述和色彩策略，直到无法通过领域类别直接推断出设计方案。
第二层面：如果有人能通过类别+反参考案例猜出美学风格（"非SaaS浅色调的AI工作流工具→排版主导的编辑风格"、"非深蓝色+金色的金融科技→终端原生深色模式"），这是更深一层的陷阱。虽然避免了第一重思维定式，但仍陷入了第二重。重新设计直到无法通过这两种方式推断出设计方案。品牌类的reflex-reject aesthetic lanes列出了当前过度饱和的风格类别。

Commands

命令

Command	Category	Description	Reference
`craft [feature]`	Build	Shape, then build a feature end-to-end	reference/craft.md
`shape [feature]`	Build	Plan UX/UI before writing code	reference/shape.md
`teach`	Build	Set up PRODUCT.md and DESIGN.md context	reference/teach.md
`document`	Build	Generate DESIGN.md from existing project code	reference/document.md
`extract [target]`	Build	Pull reusable tokens and components into design system	reference/extract.md
`critique [target]`	Evaluate	UX design review with heuristic scoring	reference/critique.md
`audit [target]`	Evaluate	Technical quality checks (a11y, perf, responsive)	reference/audit.md
`polish [target]`	Refine	Final quality pass before shipping	reference/polish.md
`bolder [target]`	Refine	Amplify safe or bland designs	reference/bolder.md
`quieter [target]`	Refine	Tone down aggressive or overstimulating designs	reference/quieter.md
`distill [target]`	Refine	Strip to essence, remove complexity	reference/distill.md
`harden [target]`	Refine	Production-ready: errors, i18n, edge cases	reference/harden.md
`onboard [target]`	Refine	Design first-run flows, empty states, activation	reference/onboard.md
`animate [target]`	Enhance	Add purposeful animations and motion	reference/animate.md
`colorize [target]`	Enhance	Add strategic color to monochromatic UIs	reference/colorize.md
`typeset [target]`	Enhance	Improve typography hierarchy and fonts	reference/typeset.md
`layout [target]`	Enhance	Fix spacing, rhythm, and visual hierarchy	reference/layout.md
`delight [target]`	Enhance	Add personality and memorable touches	reference/delight.md
`overdrive [target]`	Enhance	Push past conventional limits	reference/overdrive.md
`clarify [target]`	Fix	Improve UX copy, labels, and error messages	reference/clarify.md
`adapt [target]`	Fix	Adapt for different devices and screen sizes	reference/adapt.md
`optimize [target]`	Fix	Diagnose and fix UI performance	reference/optimize.md
`live`	Iterate	Visual variant mode: pick elements in the browser, generate alternatives	reference/live.md

Plus two management commands:

pin <command>

and

unpin <command>

, detailed below.

命令	分类	描述	参考文件
`craft [feature]`	构建	先塑造，再端到端构建一个功能	reference/craft.md
`shape [feature]`	构建	编写代码前规划UX/UI	reference/shape.md
`teach`	构建	设置PRODUCT.md和DESIGN.md上下文	reference/teach.md
`document`	构建	从现有项目代码生成DESIGN.md	reference/document.md
`extract [target]`	构建	将可复用的令牌和组件提取到设计系统中	reference/extract.md
`critique [target]`	评估	带有启发式评分的UX设计评审	reference/critique.md
`audit [target]`	评估	技术质量检查（可访问性、性能、响应式）	reference/audit.md
`polish [target]`	优化	上线前的最终质量检查	reference/polish.md
`bolder [target]`	优化	增强保守或平淡的设计	reference/bolder.md
`quieter [target]`	优化	弱化过于激进或刺激的设计	reference/quieter.md
`distill [target]`	优化	提炼核心内容，移除冗余复杂度	reference/distill.md
`harden [target]`	优化	适配生产环境：错误处理、国际化、边缘情况	reference/harden.md
`onboard [target]`	优化	设计首次使用流程、空状态、激活引导	reference/onboard.md
`animate [target]`	增强	添加有目的性的动画和动效	reference/animate.md
`colorize [target]`	增强	为单色UI添加策略性色彩	reference/colorize.md
`typeset [target]`	增强	优化排版层次和字体	reference/typeset.md
`layout [target]`	增强	修复间距、韵律和视觉层次	reference/layout.md
`delight [target]`	增强	添加个性化和令人难忘的细节	reference/delight.md
`overdrive [target]`	增强	突破常规设计限制	reference/overdrive.md
`clarify [target]`	修复	优化UX文案、标签和错误提示	reference/clarify.md
`adapt [target]`	修复	适配不同设备和屏幕尺寸	reference/adapt.md
`optimize [target]`	修复	诊断并修复UI性能问题	reference/optimize.md
`live`	迭代	视觉变体模式：在浏览器中选择元素，生成替代方案	reference/live.md

另外还有两个管理命令：

pin <command>

和

unpin <command>

，详情如下。

Routing rules

路由规则

No argument: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
First word matches a command: load its reference file and follow its instructions. Everything after the command name is the target.
First word doesn't match: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.

Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke

{{command_prefix}}impeccable

If the first word is

craft

, setup still runs first, but reference/craft.md owns the rest of the flow. If setup invokes

teach

as a blocker, finish teach, refresh context, then resume the original command and target.

无参数：将上述表格作为面向用户的命令菜单，按分类分组展示。询问用户想要执行的操作。
第一个单词匹配命令：加载对应的参考文件并遵循其说明。命令名称后的所有内容为目标对象。
第一个单词不匹配命令：通用设计调用。执行准备步骤、应用共享设计规则和已加载的注册类型参考文件，将完整参数作为上下文使用。

此时准备步骤（上下文收集、注册类型）已完成加载；子命令无需重新调用

{{command_prefix}}impeccable

。

如果第一个单词是

craft

，仍需先执行准备步骤，但后续流程由reference/craft.md主导。如果准备步骤要求先执行

teach

，则完成

teach

后刷新上下文，再继续执行原始命令和目标对象。

Pin / Unpin

Pin creates a standalone shortcut so

{{command_prefix}}<command>

invokes

{{command_prefix}}impeccable <command>

directly. Unpin removes it. The script writes to every harness directory present in the project.

bash

node {{scripts_path}}/pin.mjs <pin|unpin> <command>

Valid

<command>

is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.

Pin用于创建独立快捷方式，使

{{command_prefix}}<command>

可直接调用

{{command_prefix}}impeccable <command>

。Unpin用于移除该快捷方式。脚本会写入项目中所有存在的工具目录。

bash

node {{scripts_path}}/pin.mjs <pin|unpin> <command>

有效的

<command>

为上述表格中的任意命令。简洁地报告脚本执行结果。成功时确认新快捷方式已创建，失败时直接返回标准错误信息。