> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/process-overview.md).

# 流程概览

我们的开发流程确保设计内容最终会被构建出来。工作流分为三个明确阶段，每一步都有清晰的交付物和责任。

## 工作流阶段

{% @mermaid/diagram content="flowchart LR
UX\[UX Discovery] --> Figma\[Figma Design] --> dApp\[dApp Implementation]

```
style UX fill:#e3f2fd
style Figma fill:#fff3e0
style dApp fill:#e8f5e9" %}
```

每个阶段都建立在前一阶段之上，确保从概念到代码的一致性。

***

## UX 发现

UX 阶段为后续一切工作奠定基础。在此阶段明确需求可避免后续产生高昂的改动成本。

### 必需交付物

#### 目标与范围

**必须** 定义：

* **业务目标** - 我们要解决什么问题？
* **目标用户** - 这是为谁设计的？
* **成功指标** - 我们如何衡量成功？
* **约束条件** - 技术、时间或资源限制

**示例**:

```
目标：让用户能够高效浏览和筛选他们的地块
目标对象：拥有 10 个以上地块的土地所有者
成功标准：80% 的用户能在 10 秒内找到特定地块
约束：必须在移动端运行；不允许更改后端
```

#### 交互流程

**必须** 梳理端到端用户旅程：

* **所有使用场景** - 主要和次要用户路径
* **边缘情况** - 空状态、首次使用用户、错误
* **替代路径** - 实现目标的不同方式
* **视觉辅助** - 在有帮助时提供线框图或流程图

**示例**:

```
主要流程：
1. 用户点击“我的土地”
2. 系统加载地块
3. 用户应用筛选条件
4. 结果立即更新

边缘情况：
- 用户没有地块 → 显示带 CTA 的空状态
- 筛选后没有结果 → 显示“无结果”消息
- 加载时间超过 2 秒 → 显示骨架加载器
```

#### UI 状态

**应** 明确所有组件状态：

* **空闲** - 默认状态
* **加载中** - 数据获取或处理中
* **错误** - 操作失败
* **空** - 无可用数据
* **成功** - 操作成功
* **禁用** - 不可用操作

**应** 概述错误恢复：

* 发生错误时会怎样？
* 用户如何重试或解决？
* 用户需要哪些信息？

#### 分析跟踪

**必须** 在此阶段就达成跟踪一致：

* **事件** - 要跟踪哪些操作
* **属性** - 要捕获哪些数据
* **用户属性** - 相关的用户属性
* **转化目标** - 关键成功指标

**示例**:

```
事件：
- parcel_filter_applied { filter_type, filter_value }
- parcel_selected { parcel_id, source }
- parcel_transfer_initiated { parcel_id }

属性：
- user_parcel_count
- filter_used（布尔值）
- time_to_result（毫秒）
```

### 推荐交付物

#### 无障碍意图

**应** 描述：

* **键盘流程** - Tab 顺序和快捷键
* **焦点顺序** - 逻辑清晰的焦点推进
* **屏幕阅读器标签** - ARIA 标签和描述
* **替代内容** - 图像、图标、图表的文字说明

**示例**:

```
键盘导航：
- Tab：在筛选器之间导航
- Enter：应用所选筛选条件
- Escape：关闭筛选下拉菜单
- 方向键：浏览筛选选项

屏幕阅读器：
- “按以下方式筛选：所有者地址。输入以搜索或从列表中选择”
- “找到 3 个与筛选条件匹配的地块”
```

#### 无障碍可读性

**应** 确保：

* **颜色对比度** - 最低 WCAG AA 比例
  * 普通文本：4.5:1
  * 大号文本（18pt 及以上）：3:1
  * UI 组件：3:1
* **文字大小** - 在默认大小下可读
* **可交互目标** - 最小 44×44px 触控目标

#### UI 交互元素

**应** 为所有交互元素定义状态：

* **启用** - 默认交互状态
* **禁用** - 非交互状态
* **悬停** - 鼠标悬停（桌面端）
* **按下/激活** - 交互过程中
* **焦点** - 键盘焦点状态

**应** 明确用户反馈：

* 交互时的视觉变化
* 加载指示器
* 成功/错误消息
* 触觉反馈（移动端）

***

## Figma 设计

设计师必须从我们的 [Figma 组件库](https://www.figma.com/design/tsyaDSedcsVZ8iM9N0McT2/DCL-UI2)开始，它与 Material UI 组件保持一致，并使用 UI2 中定义的 Decentraland 主题。

{% hint style="warning" %}
不应使用特殊颜色、尺寸或样式。可以存在例外，但必须在规范中说明理由，并在评审中获得批准。
{% endhint %}

### 必需标准

#### 使用 Decentraland Figma 组件库

**必须** 当存在等效组件时使用 MUI 组件：

* 先检查 MUI 组件库
* 使用 Decentraland 变体和样式
* 不要为已有组件创建自定义版本

**如果所需的 UI 元素不存在：**

1. 检查是否可以由现有组件组合出来
2. 如果不行，提出自定义组件（见 [自定义组件](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/custom-components.md))
3. 在规范中记录理由
4. 在设计评审期间获得批准

#### 颜色

**必须** 将 Figma 颜色样式映射到 UI2 主题名称：

```tsx
import { dclColors } from 'decentraland-ui2';

// Figma “Rarity / Unique” → 代码
dclColors.rarity.unique

// Figma “Primary / Main” → 代码
theme.palette.primary.main

// Figma “Text / Secondary” → 代码
theme.palette.text.secondary
```

**唯一来源**: [colors.ts](https://github.com/decentraland/ui2/blob/master/src/theme/colors.ts)

#### 排版

**必须** 使用已定义的变体：

可用变体：

* `h1`, `h2`, `h3`, `h4`, `h5`, `h6` - 标题
* `subtitle1`, `subtitle2` - 小标题
* `body1`, `body2` - 正文
* `button` - 按钮文本
* `caption` - 说明文字
* `overline` - 上方附注文字

**参考**:

* [排版来源](https://github.com/decentraland/ui2/blob/master/src/theme/typography.ts)
* [MUI Typography](https://mui.com/material-ui/react-typography/)
* [Material Design 字体系统](https://m2.material.io/design/typography/the-type-system.html#type-scale)

**示例映射**:

```
Figma “H1” → <Typography variant="h1">
Figma “Body 1” → <Typography variant="body1">
Figma “Caption” → <Typography variant="caption">
```

#### 断点

**必须** 针对以下断点进行设计：

| 名称   | 宽度     | 典型设备 |
| ---- | ------ | ---- |
| `xs` | 768px  | 移动端  |
| `sm` | 991px  | 平板   |
| `md` | 1024px | 小型桌面 |
| `lg` | 1280px | 桌面端  |
| `xl` | 1500px | 大屏桌面 |

**来源**: [index.ts](https://github.com/decentraland/ui2/blob/master/src/theme/index.ts)

**最佳实践**:

* 移动优先设计（从 `xs`)
* 在 Figma 画板中显示关键断点
* 记录响应式行为
* 在视口边界处测试（767px、768px 等）

#### 圆角和调色板

**必须** 使用主题定义的值：

* 不要引入新的圆角值
* 不要创建新的调色板角色
* 例外需要在规范中说明理由并获得批准

**主题值**:

```tsx
theme.shape.borderRadius // 默认圆角
theme.palette.primary    // 主色
theme.palette.secondary  // 次色
theme.palette.error      // 错误色
theme.palette.text       // 文本颜色
theme.palette.background // 背景颜色
theme.palette.divider    // 分割线颜色
```

#### 配色方案

**如果屏幕支持多种配色方案：**

**必须** 提供：

* 适用哪种方案（见 [colorSchemes.ts](https://github.com/decentraland/ui2/blob/master/src/theme/colorSchemes.ts))
* 浅色模式预览
* 深色模式预览
* 关于在 Storybook 中切换方案的文档

**示例**:

```
支持的方案：浅色、深色
默认：系统偏好
切换：设置菜单 → 外观
Storybook：使用工具栏中的“Theme”控件
```

### 组件选择

**应** 复用已准备好的组件：

1. **先检查 MUI** - MUI 是否有这个组件？
2. **检查 UI2** - 是否有 Decentraland 变体？
3. **如有可能，进行组合** - 能否组合现有组件？
4. **最后才使用自定义** - 遵循 [自定义组件](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/custom-components.md) 处理

***

## dApp 实现

开发者使用 UI2 组件实现设计，并遵循我们的 [样式与主题](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/styling-and-theming.md) 标准。

### 实现检查清单

* [ ] 如果可用，先从 UI2 组件开始
* [ ] 如果没有对应的 UI2 组件，则使用带有 Decentraland 主题的 MUI 组件
* [ ] 遵循 [样式与主题](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/styling-and-theming.md) 标准
* [ ] 实现 UX 规范中的所有状态
* [ ] 按要求添加分析跟踪
* [ ] 在所有断点上测试
* [ ] 验证键盘导航
* [ ] 检查颜色对比度
* [ ] 使用屏幕阅读器测试
* [ ] 处理加载和错误状态
* [ ] 如果是可复用组件，则加入 Storybook

### 组件实现流程

```
1. 在 UI2 中查找组件
   ↓
2. 找到？→ 使用它
   ↓
3. 未找到？→ 检查 MUI
   ↓
4. 在 MUI 中找到？→ 使用 Decentraland 主题
   ↓
5. 需要定制？→ 查看自定义组件指南
   ↓
6. 按照样式标准实现
   ↓
7. 加入 Storybook（如果可复用）
```

### 质量门槛

在标记实现完成之前：

1. **视觉一致性** - 在关键断点与 Figma 像素级一致
2. **主题合规性** - 所有值均来自 UI2 主题
3. **状态已实现** - UX 指定的所有状态均可工作
4. **可访问性** - 键盘导航、焦点状态、ARIA 标签
5. **分析** - 事件按要求触发
6. **响应式** - 在所有断点均可正常工作
7. **性能** - 没有不必要的重新渲染
8. **测试** - 组件测试通过
9. **Storybook** - 已添加故事（如果可复用）
10. **代码评审** - 已由维护者批准

***

## 交接最佳实践

### 从 UX 到设计

* 清晰的需求文档
* 带注释的用户流程
* 复杂交互的状态图
* 分析事件规范

### 从设计到开发

* 启用开发模式的 Figma 文件
* 组件规范
* 响应式行为说明
* 颜色和排版 token 映射
* 无障碍注释
* UX 需求链接

### 在实现过程中

* 设计师和开发者之间定期沟通
* 尽早反馈技术约束
* 在关键里程碑进行迭代评审
* 合并前最终评审

***

## 下一步

* 了解 [自定义组件](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/custom-components.md) 用于创建新组件
* 复习 [样式与主题](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/styling-and-theming.md) 用于实现细节
* 参见 [迁移指南](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/migration.md) 如果使用 UI1 组件


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/contributor/contributor-zh/gong-xian-zhe-zhi-nan/web-ui-biao-zhun/process-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.