> 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
flowchart LR
    UX[UX 发现] --> Figma[Figma 设计] --> dApp[dApp 实现]
    
    样式 UX 填充:#e3f2fd
    样式 Figma 填充:#fff3e0
    样式 dApp 填充:#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 | 大型桌面端 |

**Source**: [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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.