> 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-ko/contributor-guides/ui-1/process-overview.md).

# 프로세스 개요

우리의 개발 프로세스는 설계된 것이 실제로 구현되도록 보장합니다. 작업은 각 단계마다 명확한 산출물과 책임을 두고 세 가지 뚜렷한 단계로 흐릅니다.

## 워크플로 단계

```mermaid
flowchart LR
    UX[UX 탐색] --> Figma[Figma 디자인] --> dApp[dApp 구현]
    
    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 (boolean)
- time_to_result (ms)
```

### 권장 산출물

#### 접근성 의도

**권장** 설명:

* **키보드 흐름** - 탭 순서와 단축키
* **포커스 순서** - 논리적인 포커스 진행
* **스크린 리더 레이블** - 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-ko/contributor-guides/ui-1/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 타이포그래피](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-ko/contributor-guides/ui-1/custom-components.md) 처리

***

## dApp 구현

개발자는 UI2 컴포넌트를 사용하고 우리의 [스타일링 및 테마](/contributor/contributor-ko/contributor-guides/ui-1/styling-and-theming.md) 표준을 따라 디자인을 구현합니다.

### 구현 체크리스트

* [ ] 사용 가능하면 UI2 컴포넌트로 시작
* [ ] UI2에 동등한 것이 없으면 Decentraland 테마가 적용된 MUI 컴포넌트 사용
* [ ] 따르기 [스타일링 및 테마](/contributor/contributor-ko/contributor-guides/ui-1/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 파일
* 컴포넌트 명세
* 반응형 동작 메모
* 색상 및 타이포그래피 토큰 매핑
* 접근성 주석
* UX 요구사항 링크

### 구현 중

* 디자이너와 개발자 간 정기적인 점검
* 기술적 제약에 대한 조기 피드백
* 주요 마일스톤에서 반복 검토
* 병합 전 최종 검토

***

## 다음 단계

* 배워보세요 [커스텀 컴포넌트](/contributor/contributor-ko/contributor-guides/ui-1/custom-components.md) 새로운 구성 요소를 만들기 위해
* 검토 [스타일링 및 테마](/contributor/contributor-ko/contributor-guides/ui-1/styling-and-theming.md) 구현 세부 사항을 위해
* 참고 [마이그레이션 가이드](/contributor/contributor-ko/contributor-guides/ui-1/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-ko/contributor-guides/ui-1/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.