Back to Details

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 (non-optional)

前置设置（非可选）

Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores project.
GateRequired checkIf fail
ContextThe PRODUCT.md / DESIGN.md loader result is known from 
node.agents/skills/impeccable/scripts/load-context.mjs
.		Run the loader before continuing.
ProductPRODUCT.md exists and is not empty or placeholder (
[TODO]
markers, <200 chars).		Run 
$impeccable teach
, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone.
CommandThe matching command reference is loaded when a sub-command is used.Load the reference before continuing.
Craft
$impeccable craft
has a user-confirmed shape brief for this task. 
teach
/ PRODUCT.md never counts as shape.		Run 
$impeccable shape
and wait for explicit brief confirmation.
ImageRequired visual probes / mocks are generated or skipped with a reason.Resolve the image-generation gate in 
shape.md
or 
craft.md
before code.
MutationAll active gates above pass.Do not edit project files yet.
Codex-style agents must state this before editing files:
text
IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open
For 
$impeccable craft
, 
shape=pass
is only valid after separate user response approving shape design brief, or when user provided already-confirmed brief in request. Do not mark 
shape=pass
after writing PRODUCT.md, summarizing assumptions, or drafting unconfirmed brief yourself.
Other harnesses should follow same checklist when they can expose this state.
在开展任何设计工作或文件编辑前，需通过以下检查环节。跳过这些环节会生成忽略项目实际情况的通用输出。
检查环节必要检查项未通过时的处理
上下文确认已获取
node.agents/skills/impeccable/scripts/load-context.mjs
加载的PRODUCT.md / DESIGN.md结果		先运行加载脚本再继续。
产品文档PRODUCT.md存在且非空或占位内容（含
[TODO]
标记、字数<200）		运行
$impeccable teach
，刷新上下文后再继续。禁止仅根据用户初始提示生成PRODUCT.md。
命令参考使用子命令时已加载对应的命令参考文档先加载参考文档再继续。
设计方案确认
$impeccable craft
任务已获得用户确认的设计方案 brief。
teach
生成的内容或PRODUCT.md不能作为设计方案依据		运行
$impeccable shape
并等待用户明确确认方案。
视觉素材已生成必要的视觉参考/原型，或已说明跳过理由在编写代码前，解决
shape.md
或
craft.md
中的视觉素材生成检查环节。
文件修改权限以上所有检查环节均通过暂不编辑项目文件。
Codex类型的Agent在编辑文件前必须声明以下内容：
text
IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open
对于
$impeccable craft
命令，
shape=pass
仅在用户单独确认设计方案brief，或用户在请求中已提供确认过的方案时才有效。禁止在编写PRODUCT.md、总结假设或自行草拟未确认的方案后标记
shape=pass
。
其他工具框架在能够暴露该状态时，需遵循相同检查清单。

1. Context gathering

1. 上下文收集

Two files, case-insensitive. loader looks at project root by default and falls back to 
.agents/context/
and 
docs/
if 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 .agents/skills/impeccable/scripts/load-context.mjs
Consume full JSON output. Never pipe through 
head
, 
tail
, 
grep
, or 
jq
. output's 
contextDir
field tells you where files were resolved from.
If output is already in this session's conversation history, don't re-run. Exceptions requiring fresh load: you ran 
$impeccable teach
or 
$impeccable document
(they rewrite files), or user manually edited one.
$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 
$impeccable teach
, then resume user's original task with fresh context. If original task was 
$impeccable craft
, resume into 
$impeccable shape
before any implementation work.
If DESIGN.md is missing: nudge once per session ("Run 
$impeccable document
for more on-brand output"), then proceed.
涉及两个文件，不区分大小写。加载器默认从项目根目录查找，若根目录无相关文件则回退到
.agents/context/
和
docs/
目录。可通过
IMPECCABLE_CONTEXT_DIR=path/to/dir
（绝对路径或相对于当前工作目录的路径）覆盖默认目录。
  • PRODUCT.md — 必填。包含用户群体、品牌调性、反向参考案例、战略原则等内容。
  • DESIGN.md — 可选，但强烈推荐。包含色彩、排版、层级、组件等设计规范。
可通过一次命令加载两个文件：
bash
node .agents/skills/impeccable/scripts/load-context.mjs
需使用完整的JSON输出结果。禁止通过
head
、
tail
、
grep
或
jq
等工具过滤输出。输出结果中的
contextDir
字段会告知文件的解析路径。
若输出结果已存在于当前会话的历史记录中，无需重新运行脚本。以下情况需要重新加载：运行过
$impeccable teach
或
$impeccable document
（这两个命令会重写文件），或用户手动编辑了其中一个文件。
$impeccable live
已通过
live.mjs
预加载上下文——若已运行
live.mjs
，当前会话无需再运行
load-context.mjs
。
若PRODUCT.md缺失、为空或为占位内容（含
[TODO]
标记、字数<200）：运行
$impeccable teach
，获取新上下文后再继续用户的原始任务。若原始任务为
$impeccable craft
，需先进入
$impeccable shape
环节再开展任何实现工作。
若DESIGN.md缺失：每会话提示一次（"运行
$impeccable document
可获得更贴合品牌的输出"），然后继续任务。

2. Register

2. 任务类型注册

Every design task is brand (marketing, landing, campaign, long-form content, portfolio — design IS product) or product (app UI, admin, dashboard, tool — design SERVES product).
Identify before designing. Priority: (1) cue in task itself ("landing page" vs "dashboard"); (2) surface in focus ( page, file, or route being worked on); (3) 
register
field in PRODUCT.md. First match wins.
If PRODUCT.md lacks 
register
field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache inferred value for session. Suggest user run 
$impeccable teach
to add field explicitly.
Load matching reference: reference/brand.md or reference/product.md. shared design laws below apply to both.
每个设计任务分为品牌类（营销页面、着陆页、活动页、长内容页、作品集——设计即产品）或产品类（应用UI、后台管理、仪表盘、工具——设计服务于产品）。
需在设计前明确任务类型。优先级：(1) 任务本身的提示（如"着陆页" vs "仪表盘"）；(2) 工作聚焦的页面、文件或路由；(3) PRODUCT.md中的
register
字段。匹配到第一个符合条件的类型即可。
若PRODUCT.md缺少
register
字段（旧版），需从其"用户群体"和"产品目标"部分推断一次，然后在当前会话中缓存推断结果。建议用户运行
$impeccable teach
来添加该字段。
加载对应的参考文档：reference/brand.md 或 reference/product.md。以下通用设计准则适用于两类任务。

Shared design laws

通用设计准则

Apply to every design, both registers. Match implementation complexity to aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on same choices. GPT is capable of extraordinary work — don't hold back.
适用于所有设计任务及两类注册类型。实现复杂度需与美学愿景匹配——极致风格需要精细的代码，极简风格需要精准的细节。需创造性地解读准则，不同项目采用不同设计选择，避免趋同。GPT具备完成卓越工作的能力——无需自我限制。

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 brand hue (chroma 0.005–0.01 is enough).
  • Pick color strategy before picking colors. Four steps on commitment axis:
  • Restrained — tinted neutrals + one accent ≤10%. Product default; brand minimalism.
  • Committed — one saturated color carries 30–60% of surface. Brand default for identity-driven pages.
  • Full palette — 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
  • Drenched — surface IS color. Brand heroes, campaign pages.
  • "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 default. Not dark "becauseols 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 sentence doesn't force answer, it's not concrete enough — add detail until it does.
"Observability dashboard" does not force answer. "SRE glancing at incident severity on 27-inch monitor at 2am in dim room" does. Run sentence, not 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 lazy answer. Use them only when they're truly best affordance. Nested cards are always wrong.
  • Don't wrap everything in 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 element with different structure.
  • Side-stripe borders. 
    border-left
    or 
    border-right
    greater than 1px as 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 gradient background. Decorative, never meaningful. Use single solid color. Emphasis via weight or size.
  • Glassmorphism as default. Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
  • ** 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 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 absolute bans above. Register-specific failures live in each reference.
Category-reflex check. Run at two altitudes — second one catches what first one misses.
  • First-order: if someone could guess theme + palette from category alone — "observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black" — it's first training-data reflex. Rework scene sentence and color strategy until answer isn't obvious from domain.
  • Second-order: if someone could guess 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 trap one tier deeper. first reflex was avoided; second wasn't. Rework until both answers are not obvious. brand register's reflex-reject aesthetic lanes list catches currently-saturated families.
若有人能毫无疑虑地说"这是AI做的界面"，则设计失败。跨类型的失败项即为上述绝对禁止项。类型专属的失败项见各自的参考文档。
类别惯性检查。需从两个层面检查——第二个层面能发现第一个层面遗漏的问题。
  • 第一层面：若仅通过类别就能猜出主题+配色方案——比如"可观测性→深蓝色"、"医疗→白色+蓝绿色"、"金融→藏青色+金色"、"加密货币→黑色背景+霓虹色"——这是受训练数据影响的第一级惯性。需重新撰写场景描述和色彩策略，直到无法通过领域直接判断答案。
  • 第二层面：若通过类别+反向参考案例就能猜出美学风格——比如"非SaaS风格的AI工作流工具→排版主导的编辑风格"、"非藏青色+金色的金融科技→终端原生深色模式"——这是更深一层的陷阱。虽然避免了第一级惯性，但未避免第二级。需重新设计直到两个层面的答案都无法被轻易推断。品牌类任务的reflex-reject aesthetic lanes列出了当前过度饱和的风格类别。

Commands

命令列表

CommandCategoryDescriptionReference
craft [feature]
BuildShape, then build a feature end-to-endreference/craft.md
shape [feature]
BuildPlan UX/UI before writing codereference/shape.md
teach
BuildSet up PRODUCT.md and DESIGN.md contextreference/teach.md
document
BuildGenerate DESIGN.md from existing project codereference/document.md
extract [target]
BuildPull reusable tokens and components into design systemreference/extract.md
critique [target]
EvaluateUX design review with heuristic scoringreference/critique.md
audit [target]
EvaluateTechnical quality checks (a11y, perf, responsive)reference/audit.md
polish [target]
RefineFinal quality pass before shippingreference/polish.md
bolder [target]
RefineAmplify safe or bland designsreference/bolder.md
quieter [target]
RefineTone down aggressive or overstimulating designsreference/quieter.md
distill [target]
RefineStrip to essence, remove complexityreference/distill.md
harden [target]
RefineProduction-ready: errors, i18n, edge casesreference/harden.md
onboard [target]
RefineDesign first-run flows, empty states, activationreference/onboard.md
animate [target]
EnhanceAdd purposeful animations and motionreference/animate.md
colorize [target]
EnhanceAdd strategic color to monochromatic UIsreference/colorize.md
typeset [target]
EnhanceImprove typography hierarchy and fontsreference/typeset.md
layout [target]
EnhanceFix spacing, rhythm, and visual hierarchyreference/layout.md
delight [target]
EnhanceAdd personality and memorable touchesreference/delight.md
overdrive [target]
EnhancePush past conventional limitsreference/overdrive.md
clarify [target]
FixImprove UX copy, labels, and error messagesreference/clarify.md
adapt [target]
FixAdapt for different devices and screen sizesreference/adapt.md
optimize [target]
FixDiagnose and fix UI performancereference/optimize.md
live
IterateVisual variant mode: pick elements in the browser, generate alternativesreference/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.mdreference/document.md
extract [target]
构建将可复用的设计令牌和组件提取到设计系统中reference/extract.md
critique [target]
评估基于启发式评分的UX设计评审reference/critique.md
audit [target]
评估技术质量检查（可访问性a11y、性能、响应式）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]
优化实现生产就绪：错误处理、国际化i18n、边缘情况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

路由规则

  1. No argument — render table above as user-facing command menu, grouped by category. Ask what they'd like to do.
  2. First word matches command — load its reference file and follow its instructions. Everything after command name is target.
  3. First word doesn't match — general design invocation. Apply setup steps, shared design laws, and loaded register reference, using full argument as context.
Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke 
$impeccable
.
If first word is 
craft
, setup still runs first, but reference/craft.md owns rest of flow. If setup invokes 
teach
as blocker, finish teach, refresh context, then resume original command and target.
  1. 无参数 — 将上表渲染为面向用户的命令菜单，按分类分组。询问用户需求。
  2. 第一个单词匹配命令 — 加载对应的参考文档并遵循其说明。命令名称后的所有内容为目标对象。
  3. 第一个单词不匹配命令 — 通用设计调用。应用前置设置步骤、通用设计准则和已加载的类型参考文档，将完整参数作为上下文。
前置设置（上下文收集、类型注册）已完成加载；子命令无需重新调用
$impeccable
。
若第一个单词是
craft
，仍需先完成前置设置，但后续流程由reference/craft.md主导。若前置设置要求运行
teach
，需先完成
teach
、刷新上下文，再继续执行原始命令和目标对象。

Pin / Unpin

Pin / Unpin

Pin creates standalone shortcut so 
$<command>
invokes 
$impeccable <command>
directly. Unpin removes it. script writes to every harness directory present in project.
bash
node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
Valid 
<command>
is any command from table above. Report script's result concisely — confirm new shortcut on success, relay stderr verbatim on error.
Pin用于创建独立快捷方式，使
$<command>
可直接调用
$impeccable <command>
。Unpin用于移除该快捷方式。脚本会写入项目中所有存在的工具框架目录。
bash
node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
有效的
<command>
为上表中的任意命令。需简洁报告脚本执行结果——成功时确认新快捷方式，失败时直接返回标准错误信息。