ux-specification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UX Spec

Turn product requirements into concrete flows, screens, and interactions that coding agents can implement.

将产品需求转化为可被编码Agent实现的具体流程、页面和交互内容。

Why This Exists

设计初衷

Bridges the gap between product requirements and implementation by defining how the product looks and behaves.

它通过定义产品的外观和交互行为，填补了产品需求和落地实现之间的鸿沟。

Input Requirements

输入要求

This skill expects:

PRD (from
```
prd-generation
```
or user-provided)
Any existing sketches, wireframes, or references (optional)
Design preferences or constraints (optional)

本技能需要以下输入：

PRD（来自
```
prd-generation
```
生成或者用户自行提供）
任何已有的草图、线框图或者参考材料（可选）
设计偏好或者约束条件（可选）

Workflow

工作流程

Step 1: Ingest PRD

步骤1：提取PRD内容

Extract from the PRD:

User stories (especially Must Have)
Features and acceptance criteria
Target user characteristics
Technical constraints

从PRD中提取以下信息：

用户故事（尤其是必备项）
功能和验收标准
目标用户特征
技术约束

Step 2: Map User Flows

步骤2：梳理用户流程

For each core user story, define the flow:

Questions to answer:

Where does the user start?
What's the happy path?
What are the decision points?
Where does the user end up?
What can go wrong?

为每个核心用户故事定义对应流程：

需要明确的问题：

用户从哪里进入？
正常流程是怎样的？
有哪些决策节点？
用户最终会到达哪里？
可能出现哪些异常？

Step 3: Define Screens

步骤3：定义页面

For each screen in the flows:

What's the purpose?
What components are needed?
What data is displayed?
What actions are available?
What states exist?

针对流程中的每个页面，明确：

页面的用途是什么？
需要哪些组件？
要展示什么数据？
有哪些可执行的操作？
存在哪些状态？

Step 4: Specify Interactions

步骤4：明确交互规则

For key interactions:

What triggers the action?
What feedback does the user get?
What changes on screen?
How long does it take?

针对核心交互，明确：

操作的触发条件是什么？
用户会得到什么反馈？
页面上会发生什么变化？
整个过程耗时多久？

Step 5: Clarify Gaps

步骤5：澄清信息缺口

Ask targeted questions if needed:

"Should this be a modal or a new page?"
"What happens if the list is empty?"
"How does the user know it's loading?"
"Any specific layout preference—sidebar, tabs, single page?"

如有必要可提出针对性问题：

"这个应该用弹窗还是新开页面？"
"如果列表为空时应该展示什么？"
"用户如何感知内容正在加载？"
"有没有特定的布局偏好？比如侧边栏、标签页、单页？"

Output Format

输出格式

Automatically save the output to
design/06-ux-spec.md
using the Write tool while presenting it to the user.

markdown

undefined

向用户展示输出内容的同时，使用Write工具自动将输出保存到

design/06-ux-spec.md

。

markdown

undefined

UX Spec: [Project Name]

Overview

[Brief summary of the product and primary user goal]

Information Architecture

Navigation Structure

[App Name]
├── [Primary Nav Item 1]
│   ├── [Sub-item]
│   └── [Sub-item]
├── [Primary Nav Item 2]
└── [Primary Nav Item 3]

[App Name]
├── [Primary Nav Item 1]
│   ├── [Sub-item]
│   └── [Sub-item]
├── [Primary Nav Item 2]
└── [Primary Nav Item 3]

Key User Paths

[Path Name]: [Start] → [Step] → [Step] → [End]
[Path Name]: [Start] → [Step] → [End]

[Path Name]: [Start] → [Step] → [Step] → [End]
[Path Name]: [Start] → [Step] → [End]

User Flows

Flow 1: [Flow Name]

Trigger: [What initiates this flow] User goal: [What they're trying to accomplish]

[Start State]
    ↓
[Action/Decision]
    ↓
[Screen/State] ──→ [Alternative path if applicable]
    ↓
[End State]

Steps:

User [action]
System [response]
User [action]
System [response]
User reaches [end state]

Error paths:

If [condition]: [what happens]
If [condition]: [what happens]

Trigger: [What initiates this flow] User goal: [What they're trying to accomplish]

[Start State]
    ↓
[Action/Decision]
    ↓
[Screen/State] ──→ [Alternative path if applicable]
    ↓
[End State]

Steps:

User [action]
System [response]
User [action]
System [response]
User reaches [end state]

Error paths:

If [condition]: [what happens]
If [condition]: [what happens]

Flow 2: [Flow Name]

[Same structure]

Screens

Screen: [Screen Name]

URL/Route:

/path

Purpose: [What the user accomplishes here] Entry points: [How users get here]

URL/Route:

/path

Purpose: [What the user accomplishes here] Entry points: [How users get here]

Layout

┌─────────────────────────────────┐
│ [Header/Nav]                    │
├─────────────────────────────────┤
│                                 │
│ [Main Content Area]             │
│                                 │
│ [Component]     [Component]     │
│                                 │
├─────────────────────────────────┤
│ [Footer/Actions]                │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│ [Header/Nav]                    │
├─────────────────────────────────┤
│                                 │
│ [Main Content Area]             │
│                                 │
│ [Component]     [Component]     │
│                                 │
├─────────────────────────────────┤
│ [Footer/Actions]                │
└─────────────────────────────────┘

Components

Component	Description	Behavior
[Name]	[What it displays]	[How it behaves]
[Name]	[What it displays]	[How it behaves]

Component	Description	Behavior
[Name]	[What it displays]	[How it behaves]
[Name]	[What it displays]	[How it behaves]

States

State	Appearance	Trigger
Default	[Description]	Initial load
Loading	[Description]	Data fetching
Empty	[Description]	No data exists
Error	[Description]	Request failed
Success	[Description]	Action completed

State	Appearance	Trigger
Default	[Description]	Initial load
Loading	[Description]	Data fetching
Empty	[Description]	No data exists
Error	[Description]	Request failed
Success	[Description]	Action completed

Actions

Action	Trigger	Result
[Action]	[Click/tap/etc.]	[What happens]
[Action]	[Trigger]	[Result]

Action	Trigger	Result
[Action]	[Click/tap/etc.]	[What happens]
[Action]	[Trigger]	[Result]

Screen: [Screen Name]

[Same structure]

Components

Component: [Component Name]

Used in: [List of screens] Purpose: [What it does]

Props/Inputs

Prop	Type	Description
[name]	[type]	[what it controls]

Prop	Type	Description
[name]	[type]	[what it controls]

Variants

[Variant 1]: [Description]
[Variant 2]: [Description]

[Variant 1]: [Description]
[Variant 2]: [Description]

States

Default: [Description]
Hover: [Description]
Active: [Description]
Disabled: [Description]

Default: [Description]
Hover: [Description]
Active: [Description]
Disabled: [Description]

Component: [Component Name]

[Same structure]

Interactions

Interaction: [Name]

Trigger: [User action] Response: [System behavior] Duration: [Instant / 200ms / async] Feedback: [What user sees/feels]

Interaction: [Name]

[Same structure]

Responsive Behavior

Breakpoints:

Mobile: < 768px
Tablet: 768px - 1024px
Desktop: > 1024px

Key adaptations:

[Component/layout]: [How it changes]
[Component/layout]: [How it changes]

Breakpoints:

Mobile: < 768px
Tablet: 768px - 1024px
Desktop: > 1024px

Key adaptations:

[Component/layout]: [How it changes]
[Component/layout]: [How it changes]

Design Notes

[Optional — any specific visual direction, references, or constraints]

Style: [Minimal / Dense / Playful / etc.]
Reference: [Any inspiration or similar products]
Constraints: [Accessibility, brand, etc.]

undefined

[Optional — any specific visual direction, references, or constraints]

Style: [Minimal / Dense / Playful / etc.]
Reference: [Any inspiration or similar products]
Constraints: [Accessibility, brand, etc.]

undefined

Adaptation Guidelines

适配指南

Simple project (1-3 screens):

Skip Information Architecture
Combine Flows and Screens
Minimal Components section
Skip Responsive Behavior

Medium project (4-8 screens):

Full structure as shown
Focus on core flows, not edge cases

Complex project (10+ screens):

Add screen-by-screen detail
Document all component variants
Include edge case flows
Add Design Notes section

简单项目（1-3个页面）：

跳过信息架构部分
合并流程和页面模块
简化组件部分
跳过响应式行为部分

中等项目（4-8个页面）：

使用如上完整结构
聚焦核心流程，无需覆盖边缘case

复杂项目（10个以上页面）：

补充每个页面的详细信息
记录所有组件变体
包含边缘case流程
添加设计说明模块

Writing Guidelines

编写规范

ASCII layouts are sufficient — Don't overcomplicate, just show structure
States are critical — Loading, empty, error states prevent agent guesswork
Be specific about triggers — "Click" vs "hover" vs "focus" matters
Name things consistently — Use same component names across screens

ASCII布局已经足够 —— 不要过度复杂化，仅展示结构即可
状态定义非常关键 —— 加载、空态、错误状态可以避免Agent自行猜测
明确触发条件 —— 区分「点击」「悬停」「聚焦」非常重要
命名保持统一 —— 跨页面使用相同的组件名称

Handoff

交付流程

After presenting the UX spec, ask:

"Ready to generate prompts.md with
/prompt-export
, or want to refine any screens first?"

Note: File is automatically saved to

design/06-ux-spec.md

. This feeds into development prompts.

展示完UX规范后，向用户询问：

"是否准备好通过
/prompt-export
生成prompts.md，还是要先调整部分页面内容？"

注意： 文件会自动保存到

design/06-ux-spec.md

，该文件会用于后续生成开发提示。