# ADR-001: v4 제약조건 기반 레이아웃 채택

**날짜**: 2026-02-03  
**상태**: 채택됨  
**의사결정자**: 프로젝트 담당자

---

## 배경

v3에서는 4개 모드(tablet_landscape, tablet_portrait, mobile_landscape, mobile_portrait)에 대해 각각 컴포넌트 위치를 설정해야 했습니다.

**문제점**:
1. 같은 컴포넌트를 4번 배치해야 함 (4배 작업량)
2. 모드 간 일관성 유지 어려움
3. 새 모드 추가 시 또 다른 배치 필요

---

## 결정

**"단일 소스 + 자동 적응" 방식 채택**

Figma, Framer, Flutter, SwiftUI에서 사용하는 업계 표준 접근법:
- 하나의 레이아웃 정의
- 제약조건(constraints) 설정
- 모든 화면에 자동 적응

---

## 핵심 규칙 3가지

### 1. 크기 규칙 (Size Rules)

| 모드 | 설명 | 예시 |
|------|------|------|
| fixed | 고정 px | 버튼 높이 48px |
| fill | 부모 채움 | 입력창 100% |
| hug | 내용 맞춤 | 라벨 = 텍스트 길이 |

### 2. 배치 규칙 (Layout Rules)

- 스택 방향: horizontal / vertical
- 줄바꿈: wrap / nowrap
- 간격: gap (8/16/24px)
- 정렬: start / center / end / stretch

### 3. 반응형 규칙 (Responsive Rules)

```typescript
{
  direction: "horizontal",
  responsive: [
    { breakpoint: 768, direction: "vertical" }
  ]
}
```

---

## 구현 방식

**Flexbox 기반** (CSS Grid 아님)

이유:
- 1차원 배치에 최적화
- 자동 크기 계산 (hug)
- 반응형 전환 간단

---

## 대안 검토

### A. 기존 4모드 유지 (기각)

장점: 기존 코드 변경 없음  
단점: 근본 문제 해결 안 됨

### B. CSS Grid 기반 (기각)

장점: 2차원 배치 가능  
단점: hug 구현 복잡, 학습 곡선

### C. 제약조건 기반 (채택)

장점: 업계 표준, 1회 설계  
단점: 기존 v3와 호환성 고려 필요

---

## 영향

### 변경 필요

- 타입 정의 (PopLayoutDataV4)
- 렌더러 (Flexbox 기반)
- 디자이너 UI (제약조건 편집)

### 호환성

- v3 레이아웃은 기존 방식으로 계속 작동
- v4는 새로운 레이아웃에만 적용
- 점진적 마이그레이션 가능

---

## 참조

- Figma Auto Layout: https://help.figma.com/hc/en-us/articles/5731482952599-Using-auto-layout
- Flutter Flex: https://docs.flutter.dev/development/ui/layout
- SwiftUI Stacks: https://developer.apple.com/documentation/swiftui/hstack

---

## 관련

- rangraph 검색: "v4 constraint", "layout system"
- SPEC.md: 상세 규칙
- PLAN.md: 구현 로드맵