design-experience-interaction

Interaction Design — Interaction Design

Entry/Exit

Entry: software The task requires page, component, flow, state, or information architecture design
Exit: Key flows, page structure, state design, and interaction boundaries finalized
Points to: Need visual direction → design-visual-direction; after design approval → build-workflow-plan
Output path: build-content-writing or build-content-layout(downstream build skill)
Preload: CANON.md + design-workflow-design

When not to use

Pure backend, scripts, migrations
There is already an unmodifiable established interaction specification and this time only engineering implementation is done

Core principles

Path Before Pixels — First define how users complete the task, then talk about styling.
State Completeness — Default, loading, empty, error, and edge states must appear as a complete set.
One Primary Flow — A single design draft allows only one primary task path.
Mental Model Fit — Concepts and structure must be close to user expectations.
Interaction Is a Contract — Once implementation begins, flows and states become factual constraints.

Best practice input

First read references/design-best-practices.md and references/design-inspiration-catalog.md, and write interaction-related evidence into 02-design.md of Design References / Pattern Synthesis / Adopt / Reject。

Scan focus:

Enterprise Product Patterns: primary flows, navigation, forms, states, and completion confirmation patterns of similar products
Official Systems / Platform Rules: platform interaction specifications, component behavior, accessibility interaction rules
Methods / Theory / Style Schools: information architecture, mental models, progressive disclosure, error recovery methods
Anti-patterns / Verification: happy path-only, missing states, chaotic CTA priorities, dead-end flows
Local Project Truth: existing routes, component libraries, user permissions, data availability, and business boundaries; project root DESIGN.md(if it exists, as a reference for cross-feature interaction constraints)

When there is no traceable evidence, interaction flows must not be written as final decisions.

Process

Step 1: Define the user task

Who the user is
What the entry point is
What the target action is
How success is confirmed after completion
✅ Verification point: Can the user task be restated in one sentence without involving internal implementation concepts?

Step 2: Draw the primary path

Starting point
Decision point
Key action
Success exit
✅ Verification point: Is there only one primary path, with no alternative branches?

Step 3: Complete the states

loading
empty
error
edge cases
permission / disabled / conflict
✅ Verification point: Does every primary path node cover the 4 basic states (loading / empty / error / normal)?

Step 4: Define the page/component structure

Page hierarchy
Section relationships
Primary CTA
How secondary paths are de-emphasized
✅ Verification point: Does the page hierarchy have only one primary CTA, and are secondary paths explicitly de-emphasized?

Output contract

Write to 02-design.md：

User goal
Key flows
Page / component structure
State design
Adopt / Reject (interaction mode)
Not-to-do list

Validation failure handling

Failure scenario	Handling method
Main path unclear	Delete branches, keep only one main path for now
Missing states	Complete the state list before continuing
Page structure guessed from implementation	Write the structure first, then allow engineering implementation
User task unclear	Go back to the spec to clarify target users and success criteria
No evidence for interaction mode	Add a best-practice scan, write out Adopt / Reject clearly, then continue

Common excuses

Excuse	Reality	Consequence
"Interaction can be added later"	Later = rework in production.	Missing states and boundaries → after production, each added state averages 2-4 hours of rework, and missing error/empty states directly affects user retention
"Get the happy path working first"	A happy path without state design is not a real flow.	Only doing the happy path → 30%+ of users cannot complete actions when they encounter empty/error states, and customer complaint rates increase
"This component is small, it doesn't need interaction design"	Small components can also carry key decisions or error states.	Skipping interaction design → small components behave unpredictably under boundary conditions, and a single bug fix takes 1-3 hours

Good and bad examples

✅ Good: Evidence-driven interaction decisions

主路径: 用户从 Dashboard → 点击"新建任务" → 填写表单 → 看到确认页 → 返回列表

状态设计:
- Loading: 表单提交时按钮变灰 + Spinner
- Empty: "还没有任务，创建你的第一个" + 行动引导按钮
- Error: "网络异常，请重试" + 重试按钮（不是通用"出错了")
- Permission disabled: "需要管理员权限才能创建任务" + 申请入口

Adopt: 逐步披露表单（参考 Salesforce 模式，Pattern Synthesis 来源 #3）
Reject: 全屏 Modal 表单（与项目侧边栏导航冲突，来源: Local Project Truth）

❌ Bad: Abstract templates without evidence

主路径: 用户 → 页面 → 操作 → 结果

状态设计: (未写)
交互模式: 看项目情况决定
不做清单: (未写)
→ 没有 best-practice scan，没有 Adopt / Reject，没有具体页面结构

Output template

Interaction design output should be written into 02-design.md with the following structure:

## Interaction Design — [功能名称]

### 用户目标
- 目标用户: [角色]
- 进入点: [从哪里来]
- 成功标准: [完成后看到什么]

### 关键流程
1. [步骤 1] → [步骤 2] → [步骤 3] → [成功出口]
- 决策点: [分支描述]
- 次要路径: [降权描述]

### 状态设计
| 场景 | Loading | Empty | Error | Edge |
|------|---------|-------|-------|------|
| [主路径节点] | [具体 UI] | [具体 UI] | [具体 UI] | [具体 UI] |

### 页面 / 组件结构
- 页面层级: [层级描述]
- 主 CTA: [按钮文案和行为]
- 次要路径降权: [降权方式]

### Adopt / Reject（交互模式）
| 模式 | 来源 | 决定 | 理由 |
|------|------|------|------|
| [模式 A] | [来源层] | Adopt | [具体理由] |
| [模式 B] | [来源层] | Reject | [冲突点] |

### 不做清单
- [不做项 1]
- [不做项 2]

Red flags — STOP

Only a happy path, no state design
Missing interaction best-practice scan or Adopt / Reject
User goals written as internal implementation goals
Page structure and CTA priority unclear
Interaction design degenerates into an engineering task list

Validation checklist

User goals are clear
Main path is complete
State coverage is complete
Page / component structure is clear
Interaction decisions are traced back to source evidence or Local Project Truth
Written into 02-design.md