usability

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/usability — Usability-First Design Enforcement

/usability — 可用性优先设计规范

Every design, plan, and implementation MUST be intuitive, forgiving, and self-documenting. Whether the consumer is an end user clicking a button or a developer calling an API, the experience MUST minimize confusion, surprise, and frustration.

Why this matters: Systems that are hard to use don't get used — or they get used wrong. Poor usability causes support tickets, workarounds, data entry errors, and abandonment. The most technically correct system is worthless if nobody can figure out how to use it.

When to invoke: During PLANNING (after brainstorming, before or alongside writing-plans) and during REVIEW (as part of code review criteria). This skill applies to user interfaces, APIs, CLIs, configuration files, error messages, and documentation.

所有设计、规划和实现都必须具备直观性、容错性和自说明性。无论使用者是点击按钮的终端用户还是调用API的开发者，体验都必须最大程度减少困惑、意外和挫败感。

为什么重要： 难用的系统要么没人用，要么会被错误使用。糟糕的可用性会导致客服工单激增、用户自行找变通方案、数据录入错误和用户流失。哪怕技术实现再完美，如果没人会用，系统也毫无价值。

适用场景： 规划阶段（头脑风暴后，撰写方案时或之前）和评审阶段（作为代码评审标准的一部分）。本规范适用于用户界面、API、CLI、配置文件、错误提示和文档。

The Rules

规则

Rule 1: Principle of Least Surprise

规则1：最小惊讶原则

Everything MUST behave as users expect. If a user predicts what will happen before they act, the design is working.

Name things by what they do, not how they do it.
```
calculateTotal()
```
not
```
runAlgorithm3()
```
.
Follow platform conventions. If every other CLI uses
```
--verbose
```
, don't use
```
--detailed-output
```
.
Be consistent. If
```
getUser()
```
returns a user object,
```
getOrder()
```
returns an order object — not a tuple.
Side effects are surprises. If a function does more than its name suggests, rename it or split it.

Test: Can a new team member predict what this function/button/endpoint does from its name alone? If not, rename it.

所有功能的行为都必须符合用户预期。如果用户在操作前就能预判到结果，说明设计是合格的。

根据功能命名，而非实现逻辑，比如用
```
calculateTotal()
```
而不是
```
runAlgorithm3()
```
。
遵循平台惯例，如果其他所有CLI都用
```
--verbose
```
表示输出详细信息，就不要自定义成
```
--detailed-output
```
。
保持一致性，如果
```
getUser()
```
返回用户对象，那
```
getOrder()
```
就应该返回订单对象，而不是元组。
副作用属于意外行为，如果函数的实际功能超出了名称的表意范围，就重命名或者拆分函数。

测试方法： 新团队成员仅通过名称就能预判函数/按钮/接口的作用吗？如果不能，就重命名。

Rule 2: Error Messages That Help

规则2：有指导意义的错误提示

Every error MUST tell the user three things:

What happened — factual description of the error.
Why it happened — the condition that triggered it.
What to do about it — specific action to fix it.

Bad	Good
"Error 500"	"Failed to save your changes because the database is temporarily unavailable. Your changes are saved locally and will sync when the connection is restored."
"Invalid input"	"Email address must contain @ and a domain (e.g., name@example.com)."
"Permission denied"	"You need the 'editor' role to modify this document. Contact your workspace admin to request access."
"Something went wrong"	"We couldn't load your dashboard because the analytics service is slow. Retrying in 5 seconds..."

Never show raw exceptions, stack traces, or error codes to end users. Log them for developers; show human-readable messages to users.

所有错误提示都必须告知用户三个信息：

发生了什么——对错误的客观描述
为什么发生——触发错误的条件
该怎么处理——解决问题的具体操作

错误示例	正确示例
"Error 500"	"保存更改失败，因为数据库暂时不可用。你的更改已保存在本地，连接恢复后将自动同步。"
"Invalid input"	"邮箱地址必须包含@和域名（例如：name@example.com）。"
"Permission denied"	"你需要'编辑者'角色才能修改此文档，请联系工作区管理员申请权限。"
"Something went wrong"	"无法加载仪表盘，因为分析服务响应较慢，5秒后自动重试..."

永远不要向终端用户展示原始异常、栈追踪或错误码。这些信息只需要记录下来供开发者排查，向用户展示人类可读的提示即可。

Rule 3: Progressive Disclosure

规则3：渐进式信息披露

Start simple. Reveal complexity only when needed.

Defaults first. Every config option has a sensible default. The "zero-config" experience works.
Simple API, advanced API. The common case takes 1-3 parameters. Advanced use cases take more.
Layered documentation. Quick start → Usage guide → API reference → Advanced topics.
Guided workflows. Multi-step processes show progress and allow going back.

Layer	Content	When shown
1. Essential	Core functionality, required inputs	Always
2. Common	Frequently used options	On request or contextually
3. Advanced	Power user features, edge case config	Behind "Advanced" or docs
4. Expert	Internal tuning, debugging, raw access	Documentation only

从简单易用开始，只在需要时才展示复杂内容。

优先提供默认值，所有配置项都要有合理的默认值，保证「零配置」就能正常使用。
区分简单API和高级API，常见场景仅需1-3个参数，高级场景才需要更多参数。
分层级文档，快速上手→使用指南→API参考→高级主题。
引导式工作流，多步骤流程展示进度，且支持回退操作。

层级	内容	展示时机
1. 核心层	核心功能、必填输入	始终展示
2. 常用层	高频使用选项	用户主动请求或上下文触发
3. 高级层	高阶用户功能、边缘场景配置	隐藏在「高级」选项后或仅在文档中说明
4. 专家层	内部调优、调试、原始访问	仅在文档中说明

Rule 4: Forgiveness and Recovery

规则4：容错与恢复机制

Users make mistakes. The system MUST make recovery easy:

Undo for every destructive action (or confirmation before the action).
Autosave for long-form input (drafts, forms, editors).
Graceful handling of back button, refresh, duplicate submission.
Clear escape hatches — users should always know how to cancel, go back, or start over.
No data loss from navigation, timeout, or accidental action.

"Are you sure?" dialogs are a last resort, not a design pattern. Better: make the action reversible.

用户难免会犯错，系统必须让恢复操作足够简单：

所有破坏性操作都支持撤销（或操作前二次确认）。
长文本输入支持自动保存（草稿、表单、编辑器）。
对返回按钮、刷新、重复提交做兼容处理。
清晰的退出路径——用户随时都知道如何取消、返回或重新开始。
不会因为导航、超时、误操作导致数据丢失。

「你确定吗？」弹窗是最后手段，不是设计模式，更好的做法是让操作可撤销。

Rule 5: Feedback and Responsiveness

规则5：反馈与响应性

Every user action MUST produce visible feedback:

Action timing	Required feedback
<100ms	Immediate state change (no loader needed)
100ms - 1s	Loading indicator (spinner, skeleton, progress)
1s - 10s	Progress bar with estimate
>10s	Background processing with notification on completion

No silent failures. If an action fails, the user MUST know — immediately and clearly.

No mystery states. The user should always be able to answer: "What is the system doing right now? What do I do next?"

所有用户操作都必须给出可见反馈：

操作耗时	所需反馈
<100ms	立即展示状态变化（无需加载动画）
100ms - 1s	加载提示（旋转图标、骨架屏、进度提示）
1s - 10s	带预估时间的进度条
>10s	后台处理，完成后发送通知

不允许静默失败，如果操作失败，必须立即清晰告知用户。

不允许未知状态，用户随时都能明确知道：「系统现在在做什么？我接下来要做什么？」

Rule 6: Accessibility by Default

规则6：默认支持无障碍访问

Usability includes EVERYONE:

Requirement	Implementation
Keyboard navigation	All interactive elements reachable via Tab, usable via Enter/Space
Screen reader support	Semantic HTML, ARIA labels, alt text for images
Color contrast	WCAG AA minimum (4.5:1 text, 3:1 large text)
No color-only indicators	Use icons, patterns, or text alongside color
Responsive design	Works on mobile through desktop
Focus management	Visible focus indicators, logical tab order

Accessibility is not optional. It's a legal requirement in many jurisdictions and a moral one everywhere.

可用性面向所有人群：

要求	实现方式
键盘导航	所有可交互元素都可通过Tab键访问，可通过Enter/空格键触发
屏幕阅读器支持	语义化HTML、ARIA标签、图片alt文本
颜色对比度	最低符合WCAG AA标准（普通文本4.5:1，大文本3:1）
不只用颜色做标识	除了颜色外，同时使用图标、图案或文字说明
响应式设计	适配从手机到桌面的所有设备
焦点管理	可见的焦点指示器、合理的Tab切换顺序

无障碍访问不是可选项，在很多司法辖区是法律要求，在所有地区都是道德义务。

Rule 7: Consistent Patterns

规则7：统一的设计模式

The entire system MUST use consistent patterns:

Same action = same interaction everywhere. If "delete" is a red button in one place, it's a red button everywhere.
Same data = same format everywhere. If dates are "March 31, 2026" in one view, they're not "2026-03-31" in another.
Same terminology everywhere. If it's a "workspace" in the UI, it's a "workspace" in the API and docs — not "organization" or "team."
Same layout for similar pages. List views look alike. Detail views look alike. Forms look alike.

整个系统必须使用统一的模式：

相同的操作交互方式一致，如果「删除」在一个地方是红色按钮，那所有地方都要是红色按钮。
相同的数据展示格式一致，如果一个视图里日期显示为「2026年3月31日」，其他视图就不要显示为「2026-03-31」。
相同的概念术语统一，如果UI里叫「工作区」，那API和文档里也要叫「工作区」，不要换成「组织」或「团队」。
相似页面布局统一，列表页风格一致，详情页风格一致，表单风格一致。

Applying This Skill

规范的应用

During Planning (brainstorming / writing-plans)

规划阶段（头脑风暴/撰写方案）

During Implementation (executing-plans)

实现阶段（执行方案）

As you write code:

Write the error message BEFORE writing the happy path. If you can't explain the error clearly, you don't understand the requirement.
Add loading states for every async operation.
Test keyboard navigation after building any interactive component.
Use semantic HTML (button for buttons, a for links, input for inputs).
Follow the existing naming patterns in the codebase.

写代码时：

先写错误提示，再写正常流程的代码。如果你没法清晰说明错误，说明你还没理解需求。
为所有异步操作添加加载状态。
开发完任何可交互组件后，测试键盘导航是否正常。
使用语义化HTML（按钮用button标签，链接用a标签，输入框用input标签）。
遵循代码库现有的命名模式。

During Review (code-review / receiving-code-review)

评审阶段（代码评审/接收代码评审）

Verify these as part of every code review:

Error messages are human-readable and actionable
Loading/feedback states exist for async operations
Naming is clear and consistent with the rest of the system
Accessibility attributes present (ARIA, alt text, semantic elements)
No silent failures or mystery states
Destructive actions have undo or confirmation

每次代码评审都要验证以下内容：

错误提示是人类可读且可操作的
异步操作有加载/反馈状态
命名清晰，和系统其他部分保持一致
有无障碍属性（ARIA、alt文本、语义化元素）
没有静默失败或未知状态
破坏性操作有撤销或二次确认机制

When Modifying Existing Code

修改现有代码时

If existing code violates these rules:

You are NOT required to fix all usability issues in unrelated UI.
You ARE required to not make usability worse.
If adding a new error case, write a helpful message (not "Error occurred").
If adding a new interactive element, ensure keyboard accessibility.

如果现有代码违反了这些规则：

你不需要修复不相关UI的所有可用性问题
你必须保证不会让可用性变得更差
如果新增错误场景，要写有指导意义的提示（不要只写「发生错误」）
如果新增可交互元素，要保证支持键盘导航

Anti-Patterns

反模式

Pattern	Problem	Fix
"Error: null"	User has no idea what happened	Structured error with action
Modals on modals	User trapped in dialog hell	Inline editing or single modal
Hidden functionality	Users can't find features	Progressive disclosure, not hiding
Jargon in UI	Users don't speak developer	Use domain language, not technical terms
Disabled buttons without explanation	User doesn't know why they can't proceed	Tooltip or inline text explaining the condition
Inconsistent terminology	"Save" vs "Submit" vs "Confirm" for same action	Pick one term, use it everywhere

反模式	问题	修复方案
"Error: null"	用户完全不知道发生了什么	结构化错误提示，包含解决方法
弹窗上叠加弹窗	用户陷入弹窗地狱	使用内联编辑或单个弹窗
隐藏功能	用户找不到功能	用渐进式披露，不要完全隐藏
UI里用技术黑话	用户看不懂开发术语	使用业务领域语言，不要用技术术语
禁用按钮不说明原因	用户不知道为什么无法继续操作	用 tooltip 或行内文本说明原因
术语不统一	同一个操作一会叫「保存」一会叫「提交」一会叫「确认」	选定一个术语，全系统统一使用

Rationalization Prevention

拒绝合理化借口

Excuse	Reality
"Power users will figure it out"	Power users hate bad UX too. They just suffer silently.
"The docs explain it"	Nobody reads docs for something that should be intuitive.
"We'll improve UX in v2"	v2 UX debt is twice as expensive. Get it right now.
"It's technically correct"	Technically correct + unusable = useless.
"Accessibility is a nice-to-have"	It's a legal requirement and moral obligation.
"We're not designers"	Usability is engineering, not art. Follow the rules.

借口	现实
"高阶用户会搞懂的"	高阶用户也讨厌糟糕的UX，他们只是默默忍受而已
"文档里有说明"	本就应该直观的东西，没人会去查文档
"我们会在v2版本优化UX"	v2还UX债务的成本是现在的两倍，现在就做好
"技术实现是对的就行"	技术正确+不好用=毫无价值
"无障碍是锦上添花的功能"	它是法律要求，也是道德义务
"我们不是设计师"	可用性是工程问题，不是艺术问题，遵守规则即可