> 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/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 (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 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-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에서 디자인으로

* 명확한 요구사항 문서
* 주석이 달린 사용자 흐름
* 복잡한 상호작용을 위한 상태 다이어그램
* 분석 이벤트 명세

### 디자인에서 개발로

* dev mode가 활성화된 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 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-ko/contributor-guides/ui-1/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.