# ADR-003: v5 CSS Grid 기반 그리드 시스템 채택

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

---

## 배경

### 문제 상황

v4 Flexbox 기반 레이아웃으로 반응형 구현을 시도했으나 실패:

1. **배치 예측 불가능**: 컴포넌트가 자유롭게 움직이지만 원하는 위치에 안 감
2. **캔버스 방식의 한계**: "그리듯이" 배치하면 화면 크기별로 깨짐
3. **규칙 부재**: 어디에 뭘 배치해야 하는지 기준이 없음

### 상급자 피드백

> "이런 식이면 나중에 문제가 생긴다."
> 
> "스크린의 픽셀 규격과 마진 간격 규칙을 설정해라.
> 큰 화면 디자인의 전체 프레임 규격과 사이즈 간격 규칙을 정한 다음에
> 거기에 컴포넌트를 끼워 맞추듯 우리의 규칙 내로 움직이게 바탕을 잡아라."

### 연구 내용

| 도구 | 핵심 특징 | 적용 가능 요소 |
|------|----------|---------------|
| **Softr** | 블록 기반, 제약 기반 레이아웃 | 컨테이너 슬롯 방식 |
| **Ant Design** | 24열 그리드, 8px 간격 | 그리드 시스템, 간격 규칙 |
| **Material Design** | 4/8/12열, 반응형 브레이크포인트 | 디바이스별 칸 수 |

---

## 결정

**CSS Grid 기반 그리드 시스템 (v5) 채택**

### 핵심 규칙

| 모드 | 화면 너비 | 칸 수 | 대상 디바이스 |
|------|----------|-------|--------------|
| mobile_portrait | ~599px | 4칸 | 4~6인치 모바일 |
| mobile_landscape | 600~839px | 6칸 | 7인치 모바일 |
| tablet_portrait | 840~1023px | 8칸 | 8~10인치 태블릿 |
| tablet_landscape | 1024px~ | 12칸 | 10~14인치 태블릿 (기본) |

### 컴포넌트 배치

```typescript
interface PopGridPosition {
  col: number;      // 시작 열 (1부터)
  row: number;      // 시작 행 (1부터)
  colSpan: number;  // 열 크기 (1~12)
  rowSpan: number;  // 행 크기 (1~)
}
```

### v4 대비 변경점

| 항목 | v4 (Flexbox) | v5 (Grid) |
|------|-------------|-----------|
| 배치 방식 | 흐름 기반 (자동) | 좌표 기반 (명시적) |
| 크기 단위 | 픽셀 (200px) | 칸 (colSpan: 3) |
| 예측성 | 낮음 | 높음 |
| 반응형 | 복잡한 규칙 | 칸 수 변환 |

---

## 대안 검토

### A. v4 Flexbox 유지 (기각)

- **장점**: 기존 코드 활용 가능
- **단점**: 상급자 지적한 문제 해결 안됨 (규칙 부재)
- **결과**: 기각

### B. 자유 배치 (절대 좌표) (기각)

- **장점**: 완전한 자유도
- **단점**: 반응형 불가능, 화면별로 전부 다시 배치 필요
- **결과**: 기각

### C. CSS Grid 그리드 시스템 (채택)

- **장점**: 
  - 규칙 기반으로 예측 가능
  - 반응형 자동화 (12칸 → 4칸 변환)
  - Material Design 표준 준수
- **단점**: 
  - 기존 v4 데이터 호환 불가
  - 자유도 제한 (칸 단위로만)
- **결과**: **채택**

---

## 영향

### 변경 필요

- [x] 타입 정의 (`PopLayoutDataV5`, `PopGridPosition`)
- [x] 렌더러 (`PopRenderer.tsx` - CSS Grid)
- [x] 캔버스 (`PopCanvas.tsx` - 그리드 표시)
- [x] 유틸리티 (`gridUtils.ts` - 좌표 계산)
- [x] 레거시 삭제 (v1~v4 코드, 데이터)

### 호환성

- v1~v4 레이아웃: **삭제** (마이그레이션 없이 초기화)
- 새 화면: v5로만 생성

### 제한 사항

- 컴포넌트는 칸 단위로만 배치 (칸 사이 배치 불가)
- 12칸 기준으로 설계 후 다른 모드는 자동 변환

---

## 교훈

1. **규칙이 자유를 만든다**: 제약이 있어야 일관된 디자인 가능
2. **상급자 피드백 중요**: "프레임 규격 먼저" 조언이 핵심 방향 제시
3. **연구 후 결정**: Softr, Ant Design 분석이 구체적 방향 제시
4. **과감한 삭제**: 레거시 유지보다 깔끔한 재시작이 나음

---

## 참조

- Softr: https://www.softr.io
- Ant Design Grid: https://ant.design/components/grid
- Material Design Layout: https://m3.material.io/foundations/layout
- GRID_SYSTEM_DESIGN.md: 상세 설계 스펙

---

## 관련

- [ADR-001](./001-v4-constraint-based.md): v4 제약조건 기반 (이전 시도)
- [CHANGELOG 2026-02-05](../CHANGELOG.md#2026-02-05): 작업 내역
- [sessions/2026-02-05](../sessions/2026-02-05.md): 대화 기록