ui-craft

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UI Craft

UI 精雕准则

A user interface is a contract with a real person. Slop is what breaks it: visual sameness, weak hierarchy, fake interactivity, half the states missing, raw hex outside the token system, "Welcome!" copy nobody asked for. AI-generated UI fails these same ways every run. This skill is the floor that stops it — every visible state explicit, every value from the design system, every interactive element reachable by keyboard, every word earning its place.

用户界面是与真实用户的契约。劣质产物就是破坏这份契约的元凶：视觉同质化、层级混乱、伪交互状态、缺失半数状态、脱离令牌系统的原始十六进制颜色、无人需要的“欢迎！”文案。AI生成的UI每次都会犯同样的错误。本技能就是阻止这类问题的基准线——每个可见状态都明确清晰，每个取值都来自设计系统，每个交互元素都支持键盘操作，每个文字都有存在的价值。

Frame the surface before generating

生成前先框定界面范围

Lock these before any pixel. They apply to every change — a one-line tweak, a new variant, a full page. "It's just a small change" is the most common slop excuse.

Read the brand authorities (normative — quote them, never re-invent):
```
DESIGN.md
```
(root, or
```
packages/ui/
```
,
```
apps/web/
```
,
```
docs/
```
,
```
.ai/
```
), token files (
```
tokens.css
```
,
```
theme.ts
```
,
```
tailwind.config.*
```
), frontend conventions (
```
web/CLAUDE.md
```
,
```
.cursorrules
```
), copy authority (
```
COPY.md
```
). None present → fall back to
```
references/visual-craft.md
```
defaults and record a finding: "No DESIGN.md / token system; recommend scaffolding before further UI work." Don't bootstrap DESIGN.md as a side effect.
State the job in one user-perspective sentence ("The user opens this dialog to confirm irreversible deletion of a project"). More than one job → split the surface.
Write the scene sentence (below).
Pick the register — Product or Brand (below).
Declare the dials — VISUAL_VARIANCE, MOTION_INTENSITY, INFORMATION_DENSITY (below).

在绘制任何像素之前，先确定以下内容。它们适用于所有修改——哪怕是一行代码的微调、一个新变体、一整个页面。“这只是个小改动”是最常见的劣质产物借口。

查阅品牌规范文件（规范性文件——直接引用，绝不重新发明）：
```
DESIGN.md
```
（根目录，或
```
packages/ui/
```
、
```
apps/web/
```
、
```
docs/
```
、
```
.ai/
```
）、令牌文件（
```
tokens.css
```
、
```
theme.ts
```
、
```
tailwind.config.*
```
）、前端约定（
```
web/CLAUDE.md
```
、
```
.cursorrules
```
）、文案规范（
```
COPY.md
```
）。若以上文件均不存在，则 fallback 到
```
references/visual-craft.md
```
的默认规则，并记录发现：*“无DESIGN.md/令牌系统；建议在进一步UI工作前搭建相关规范。”*不要将搭建DESIGN.md作为附带操作。
用用户视角的一句话描述界面用途（例如：“用户打开此对话框以确认项目的不可逆删除”）。若存在多个用途，则拆分界面。
撰写场景描述句（见下文）。
选择风格定位——产品型或品牌型（见下文）。
声明可调参数——VISUAL_VARIANCE（视觉差异度）、MOTION_INTENSITY（动效强度）、INFORMATION_DENSITY（信息密度）（见下文）。

Scene sentence

场景描述句

Physical context that forces the visual answer: who uses this, where, under what ambient light, in what mood. A category ("observability dashboard", "marketing landing") points at a thousand average answers; a scene forces one.

✅ "SRE glances at incident severity on a 27" monitor at 2am in a dim room — every element competes with a paged-alert sound."

If the scene doesn't force the decision, add detail until it does. Most weak visual calls come from a missing scene. (Adapted from
impeccable
, pbakaus/impeccable.)

能明确视觉方案的物理场景：谁使用此界面、在哪里、处于何种环境光下、什么心情。一个类别（“可观测性仪表盘”、“营销落地页”）指向数千种平均方案；而场景描述则会锁定唯一方案。

✅ “SRE在凌晨2点的昏暗房间里，瞥了一眼27英寸显示器上的事件严重程度——每个元素都要与告警提示音竞争注意力。”

如果场景描述无法决定设计方案，就添加细节直到可以为止。大多数薄弱的视觉决策都源于缺失场景描述。（改编自

impeccable

，pbakaus/impeccable。）

Register: Product or Brand

风格定位：产品型或品牌型

Pick one; switching mid-surface is the source of half of all "this feels off" reactions. If undecidable, it is almost always Product — Brand is the exception.

Register	Lives in	Color	Type	Motion
Product	App shells, dashboards, settings, forms, lists	Restrained: tinted neutrals + 1 accent ≤10%	System fonts ok; fixed rem scale	150–250ms state feedback only; no decoration
Brand	Landing pages, heroes, onboarding, marketing	Committed: 1 saturated color carries 30–60%	Display + body pairing	Full orchestration; entrance reveals welcome

Recurring task by a known user → Product. First/deliberate impression or campaign → Brand. (Adapted from
impeccable
.)

二选一；中途切换风格是导致“感觉不对劲”的主要原因之一。若无法确定，几乎总是选择产品型——品牌型是例外情况。

风格定位	适用场景	色彩风格	字体风格	动效风格
产品型	应用外壳、仪表盘、设置页面、表单、列表	克制：带色调的中性色 + 1种强调色占比≤10%	系统字体即可；固定rem比例	仅150–250ms状态反馈；无装饰性动效
品牌型	落地页、首屏横幅、引导流程、营销页面	鲜明：1种饱和色占比30–60%	展示字体+正文字体搭配	完整动效编排；入场动效传递欢迎感

已知用户的重复任务→产品型。首次/刻意的印象或营销活动→品牌型。（改编自

impeccable

。）

Tunable dials

可调参数

Declare values before generating; pin them in the deliverable so review can re-anchor. Translate "more bold / calmer / tighter / looser" to a dial move — don't re-derive every choice.

Dial	Default	Low (1–3)	High (8–10)
`VISUAL_VARIANCE`	6	System-aligned, closest familiar pattern	Breaks the category template (bento, asymmetric, branded color)
`MOTION_INTENSITY`	4	80–150ms utility feedback only	Up to 500ms entrances, layered materials (blur/mask/clip-path) at ≥7
`INFORMATION_DENSITY`	5	Spacious, marketing-leaning	Dense/dashboard: tabular-nums, keyboard-first, tight spacing ramp

(Dial pattern adapted from
taste-skill
, Leonxlnx.)

生成前先声明参数值；在交付成果中固定这些值，以便评审时重新锚定。将“更大胆/更平和/更紧凑/更宽松”转化为参数调整——不要每次都重新推导选择。

参数	默认值	低（1–3）	高（8–10）
`VISUAL_VARIANCE`	6	贴合系统，采用最熟悉的模式	打破类别模板（网格布局、不对称设计、品牌色应用）
`MOTION_INTENSITY`	4	仅80–150ms实用反馈动效	最长500ms入场动效，≥7级时使用分层材质（模糊/遮罩/裁剪路径）
`INFORMATION_DENSITY`	5	宽松，偏向营销风格	紧凑/仪表盘风格：等宽数字、键盘优先、紧凑间距梯度

（参数模式改编自

taste-skill

，Leonxlnx。）

The operating loop

操作流程

Run every task through these steps in order; each ends on a checkable bar. The one-line bar is the floor — the linked file is the full contract, and you must read it in full before generating or reviewing that dimension (loaded just-in-time, never all at once). The inline bar is not a substitute for the file.

Usability filter. Run the surface through Nielsen's 10 heuristics + the load-bearing Laws of UX (Jakob, Hick, Miller, Fitts, Tesler); fix the one or two that most threaten this surface. → Novel or audited surface: read
references/usability-foundations.md
. Bar: no unjustified heuristic violation (visible system status, reversible exits, recognition over recall).
Accessibility floor (WCAG 2.2 AA, the floor not the ceiling). Bar: text contrast ≥4.5:1 (≥3:1 large / non-text / state indicators);
```
:focus-visible
```
≥2px and ≥3:1 on every interactive element; full keyboard reach + operation; target ≥24×24 (≥44×44 touch);
```
prefers-reduced-motion
```
honored; color never the sole carrier of meaning. → Any interactive widget: read
references/accessibility-floor.md
for the ARIA patterns (dialog, combobox, menu, tabs, slider, listbox) and verification recipes. A floor item that can't be met is a blocker, not a trade-off.
Visual craft — draw every value from the system. Type from the scale, color from semantic tokens (
```
--color-bg-danger-subtle
```
, never raw hex), spacing snapped to the scale, radius/elevation/motion from their scales. → No token system, or a scale needs extending: read
references/visual-craft.md
. A real gap → propose a token (step 7), never inline-invent. → Extending DESIGN.md / tokens / shadcn-Radix: read
references/design-system-integration.md
.
State matrix — every state, designed at once. Fill
```
assets/state-matrix.md
```
for the component: default, hover, active, focus-visible, disabled, loading, empty, selected, error, success, plus domain states. → Any button/input/dialog/nav/table/card/dropdown/tabs/popover/toast: read
references/component-patterns.md
. A listed-but-undesigned state is
```
StateMatrixHoles
```
.
Anti-slop scan. Match the surface against the 14 patterns (scorecard below) and the literal blocklist. Then the two-level slop test: could a stranger guess the aesthetic from the category alone (first-order default), or from category + your anti-references (second-order — brutalist mono is still a default)? Both are trapped; escape by re-deriving from the scene. → Auditing AI-generated UI: read
references/ai-slop-patterns.md
(before/after + remediation) and
references/anti-defaults.md
(17 artifacts to refuse on sight). Every hit is stop-and-fix.
Microcopy — every word earns its place. Bar: CTAs are verb + object (
```
Delete project
```
, not
```
OK
```
); errors say what happened + why + how to recover, no blame; empty states explain what lives here + the one action; no AI vocabulary (
```
seamless
```
,
```
delve
```
,
```
elevate
```
,
```
unleash
```
), no empty greetings, no filler (
```
Please
```
,
```
In order to
```
). → Any user-visible text: read
references/microcopy-quality.md
.
Verify, then document deltas. Visually confirm at supported breakpoints; force each state and screenshot the non-trivial ones; keyboard-test the full interaction; contrast-check rendered values; toggle
```
prefers-reduced-motion
```
. New token/variant/pattern → append it to
```
DESIGN.md
```
in the same change set (silent drift otherwise). Run
```
assets/pre-ship-checklist.md
```
as the binary gate. → Per-ARIA verification recipes in
references/accessibility-floor.md
; if CWV/fonts/images are in scope, read
references/performance.md
. A surface that can't be rendered for verification is not "done" — say so.

Branch-specific pointers, loaded when the branch applies:

Animation / transitions:
```
references/motion-patterns.md
```
(duration bands, easing curves, CSS/Framer/
```
@starting-style
```
code, reduced-motion templates).
Dark theme:
```
references/dark-mode.md
```
(surface-lightness elevation, accent desaturation, dangerous pairs).
AI / agent surface (chat, streaming, citations, approvals):
```
references/human-ai-ux.md
```
(Microsoft 18 + IBM 4 pillars).
"We need a [Linear/Notion]-like X" / reinventing a primitive:
```
references/archetypes.md
```
(7 signature contracts).
Reviewing an existing surface: deliver findings in the
```
assets/ui-audit-template.md
```
format.

按顺序执行以下步骤；每个步骤都有可检查的基准线。单行基准线是最低要求——关联文件是完整契约，在生成或评审对应维度前必须完整阅读（按需加载，无需一次性全部阅读）。单行基准线不能替代文件内容。

可用性过滤。将界面通过尼尔森十大可用性原则 + 核心UX法则（雅各布定律、希克定律、米勒定律、菲茨定律、特斯勒定律）进行校验；修复对当前界面威胁最大的1-2个问题。→ 全新界面或需审计的界面：阅读
references/usability-foundations.md
。基准线：无不合理的原则违反（可见的系统状态、可撤销的退出操作、识别优于回忆）。
无障碍基准线（WCAG 2.2 AA，是最低要求而非最高标准）。基准线：文本对比度≥4.5:1（大文本/非文本/状态指示器≥3:1）；每个交互元素的
```
:focus-visible
```
样式≥2px且对比度≥3:1；完整的键盘可达性+可操作性；目标区域≥24×24（触摸区域≥44×44）；遵循
```
prefers-reduced-motion
```
设置；颜色不能作为唯一的信息载体。→ 任何交互组件：阅读
references/accessibility-floor.md
获取ARIA模式（对话框、组合框、菜单、标签页、滑块、列表框）和验证方法。无法满足的基准线项是阻塞问题，而非可权衡项。
视觉精雕——所有取值均来自系统。字体采用系统字号、颜色采用语义化令牌（
```
--color-bg-danger-subtle
```
，绝不用原始十六进制）、间距对齐系统刻度、圆角/阴影/动效均来自对应系统刻度。→ 无令牌系统，或需扩展刻度：阅读
references/visual-craft.md
。若存在真实缺口→提议新增令牌（步骤7），绝不要内联自定义。→ 扩展DESIGN.md/令牌/shadcn-Radix：阅读
references/design-system-integration.md
。
状态矩阵——一次性设计所有状态。为组件填写
```
assets/state-matrix.md
```
：默认、悬停、激活、焦点可见、禁用、加载、空、选中、错误、成功，以及领域特定状态。→ 任何按钮/输入框/对话框/导航/表格/卡片/下拉菜单/标签页/弹出框/提示框：阅读
references/component-patterns.md
。已列出但未设计的状态属于
```
StateMatrixHoles
```
问题。
劣质产物扫描。将界面与14种模式（见下方评分卡）和明确的黑名单进行匹配。然后执行两级劣质产物测试：陌生人能否仅通过类别猜出设计风格（一阶默认），或通过类别+反参考猜出（二阶——极简单色风格仍属于默认）？若两者均符合，则需重新从场景描述推导方案以跳出默认。→ 审计AI生成的UI：阅读
references/ai-slop-patterns.md
（前后对比+修复方案）和
references/anti-defaults.md
（17种需直接拒绝的设计产物）。每发现一个问题都必须立即修复。
微文案——每个文字都有存在的价值。基准线：CTA文案为动词+宾语（
```
Delete project
```
，而非
```
OK
```
）；错误文案说明发生了什么+原因+如何恢复，无指责；空状态文案说明此处用途+核心操作；禁用AI常用词汇（
```
seamless
```
、
```
delve
```
、
```
elevate
```
、
```
unleash
```
），无空泛问候，无冗余填充（
```
Please
```
、
```
In order to
```
）。→ 任何用户可见文本：阅读
references/microcopy-quality.md
。
验证，然后记录差异。在支持的断点下进行视觉确认；触发每个状态并截图非平凡状态；键盘测试完整交互流程；检查渲染值的对比度；切换
```
prefers-reduced-motion
```
设置。新增令牌/变体/模式→在同一变更集中追加到
```
DESIGN.md
```
（否则会导致无声漂移）。运行
```
assets/pre-ship-checklist.md
```
作为最终放行 gate。→ ARIA验证方法见
references/accessibility-floor.md
；若涉及CWV/字体/图片，阅读
references/performance.md
。无法渲染验证的界面不算“完成”——需明确说明。

分支特定指引，当分支适用时加载：

动画/过渡效果：
```
references/motion-patterns.md
```
（时长区间、缓动曲线、CSS/Framer/
```
@starting-style
```
代码、简化动效模板）。
深色主题：
```
references/dark-mode.md
```
（表面亮度层级、强调色降饱和度、危险配色组合）。
AI/Agent界面（聊天、流式传输、引用、审批）：
```
references/human-ai-ux.md
```
（微软18条+IBM4条核心原则）。
“我们需要类似Linear/Notion的X”/重新设计基础组件：
```
references/archetypes.md
```
（7种标志性契约）。
审查现有界面： 以
```
assets/ui-audit-template.md
```
格式交付审查结果。

Reference router

参考资料导航

Every row whose trigger applies is mandatory reading before generating that dimension, not an appendix.

When	File	Covers
Designing a novel surface / auditing usability	`references/usability-foundations.md`	Nielsen 10, Laws of UX, progressive disclosure, mental models
Any interactive widget (dialog, menu, combobox, tabs, slider)	`references/accessibility-floor.md`	WCAG 2.2 AA non-negotiables, ARIA patterns, verification recipes
Buttons/inputs/dialogs/nav/tables/cards/dropdowns/tabs/toasts	`references/component-patterns.md`	States, keyboard contract, a11y, and slop per component
Writing or reviewing user-visible text	`references/microcopy-quality.md`	Banned vocabulary, per-surface tone, error/empty/CTA templates
Auditing AI-generated UI	`references/ai-slop-patterns.md`	Before/after + remediation for the 14 patterns, detection prompts
A choice feels like a category-average default	`references/anti-defaults.md`	17 literal artifacts to refuse on sight
Building an AI/agent surface	`references/human-ai-ux.md`	Microsoft 18 + IBM 4 pillars, streaming/citation/confidence UI
Reading/extending DESIGN.md, tokens, shadcn/Radix, codegen rules	`references/design-system-integration.md`	DESIGN.md sections, token discipline, Figma/Code Connect
No token system, or extending a scale	`references/visual-craft.md`	Type/color/spacing/radius/elevation/motion defaults
Adding or reviewing animation	`references/motion-patterns.md`	Duration bands, easing, CSS/Framer/ `@starting-style` , reduced-motion
Implementing or reviewing dark mode	`references/dark-mode.md`	Surface-lightness elevation, accent desaturation, dangerous pairs
Unprofiled ship, CWV regress, heavy dep on a hot route	`references/performance.md`	CWV floors, 80ms threshold, font zero-CLS, pre-ship gate
"We need a [Linear/Notion]-like X"	`references/archetypes.md`	7 archetypes, each a six-slot signature contract

所有触发条件匹配的行都是对应维度生成前的必读内容，而非附录。

触发场景	文件路径	涵盖内容
设计全新界面/审计可用性	`references/usability-foundations.md`	尼尔森十大原则、UX核心法则、渐进式披露、心智模型
任何交互组件（对话框、菜单、组合框、标签页、滑块）	`references/accessibility-floor.md`	WCAG 2.2 AA非协商要求、ARIA模式、验证方法
按钮/输入框/对话框/导航/表格/卡片/下拉菜单/标签页/提示框	`references/component-patterns.md`	组件状态、键盘契约、无障碍、劣质产物排查
撰写或审查用户可见文本	`references/microcopy-quality.md`	禁用词汇、界面特定语气、错误/空状态/CTA模板
审计AI生成的UI	`references/ai-slop-patterns.md`	14种模式的前后对比+修复方案、检测提示
设计方案感觉是类别平均默认值	`references/anti-defaults.md`	17种需直接拒绝的设计产物
构建AI/Agent界面	`references/human-ai-ux.md`	微软18条+IBM4条核心原则、流式/引用/置信度UI
阅读/扩展DESIGN.md、令牌、shadcn/Radix、代码生成规则	`references/design-system-integration.md`	DESIGN.md章节、令牌规范、Figma/代码联动
无令牌系统，或需扩展刻度	`references/visual-craft.md`	字体/颜色/间距/圆角/阴影/动效默认规则
添加或审查动画	`references/motion-patterns.md`	时长区间、缓动曲线、CSS/Framer/ `@starting-style` 、简化动效
实现或审查深色模式	`references/dark-mode.md`	表面亮度层级、强调色降饱和度、危险配色组合
未优化的上线版本、CWV退化、核心路由依赖过重	`references/performance.md`	CWV基准线、80ms阈值、零CLS字体、上线前检查 gate
“我们需要类似Linear/Notion的X”	`references/archetypes.md`	7种原型，每种包含6项标志性契约

Anti-slop scorecard

劣质产物评分卡

Match every surface. Hits are not nits; severity drives the response. Full symptom/fix per pattern lives in

references/ai-slop-patterns.md

(by number) and

references/anti-defaults.md

Critical — blocks merge (accessibility, broken keyboard/focus contract, missing states).
Serious — blocks review approval (training-data defaults, design-system drift, weak hierarchy).
Moderate — polish later, unless ≥3 stack on one surface → treat as Serious.

#	Pattern	Severity	#	Pattern	Severity
1	VisualSameness	Moderate	8	GenericIllustration	Serious
2	WeakHierarchy	Serious	9	DesignSystemDrift	Serious
3	TextOverflow	Serious	10	StateMatrixHoles	Critical
4	FakeInteractivity	Critical	11	CenteredEverything	Moderate
5	EmojiSpam	Moderate	12	RandomRadii	Moderate
6	GradientCrutch	Serious	13	GhostFocus	Critical
7	GlassmorphismAbuse	Moderate	14	MagicNumbers	Moderate

匹配所有界面。发现的问题不是小瑕疵；严重程度决定响应方式。每种模式的完整症状/修复方案见

references/ai-slop-patterns.md

（按编号）和

references/anti-defaults.md

。

严重 —— 阻塞合并（无障碍问题、键盘/焦点契约失效、缺失状态）。
较严重 —— 阻塞评审通过（训练数据默认值、设计系统漂移、层级混乱）。
中等 —— 后续优化，除非同一界面出现≥3个此类问题→升级为较严重。

#	模式名称	严重程度	#	模式名称	严重程度
1	VisualSameness（视觉同质化）	中等	8	GenericIllustration（通用插图）	较严重
2	WeakHierarchy（层级混乱）	较严重	9	DesignSystemDrift（设计系统漂移）	较严重
3	TextOverflow（文本溢出）	较严重	10	StateMatrixHoles（状态矩阵缺失）	严重
4	FakeInteractivity（伪交互）	严重	11	CenteredEverything（全居中布局）	中等
5	EmojiSpam（表情滥用）	中等	12	RandomRadii（随机圆角）	中等
6	GradientCrutch（渐变依赖）	较严重	13	GhostFocus（幽灵焦点）	严重
7	GlassmorphismAbuse（毛玻璃滥用）	中等	14	MagicNumbers（魔法数值）	中等

Scripts

脚本工具

```
scripts/check-contrast.mjs
```
— WCAG AA/AAA + APCA Lc for a foreground/background pair; hex/rgb/oklch, zero-dependency. Wire into CI on token changes.
```
scripts/detect-token-drift.mjs
```
— scan source for raw hex/rgb/hsl/oklch outside token paths; reports
```
file:line
```
+ suggestion. Must exit 0 to ship.
```
scripts/validate-metadata.py
```
— validate this skill's frontmatter against the agentskills.io spec (author tooling).

```
scripts/check-contrast.mjs
```
—— 检查前景/背景色对的WCAG AA/AAA + APCA Lc对比度；支持hex/rgb/oklch格式，零依赖。在令牌变更时接入CI流程。
```
scripts/detect-token-drift.mjs
```
—— 扫描源码中令牌路径外的原始hex/rgb/hsl/oklch颜色；报告
```
file:line
```
+ 建议。必须返回0才能上线。
```
scripts/validate-metadata.py
```
—— 验证本技能的前置元数据是否符合agentskills.io规范（作者工具）。

Edge cases

边缘情况

Tokens conflict between DESIGN.md and a token file → trust DESIGN.md; flag the divergence as a finding.
State matrix exceeds the surface → prune to states the surface supports, justifying each pruning; never silently drop.
User insists on shipping a known hit → name the anti-default, run the scene sentence with them; if no scene emerges, record the override as acknowledged slop debt. Never invent a justification for it.

令牌冲突：DESIGN.md与令牌文件冲突→以DESIGN.md为准；标记差异作为发现项。
状态矩阵超出界面范围→裁剪为界面支持的状态，为每个裁剪操作提供理由；绝不静默删除。
用户坚持上线已知问题→明确指出反默认设计，与用户一起重新梳理场景描述；若无法形成有效场景，则将此覆盖记录为已确认的劣质产物债务。绝不为其编造理由。