ERP-node/popdocs/decisions/003-v5-grid-system.md

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인치 태블릿 (기본)

컴포넌트 배치

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 데이터 호환 불가
  • 자유도 제한 (칸 단위로만)
• 결과: 채택

---

영향

변경 필요

• 타입 정의 (PopLayoutDataV5, PopGridPosition)
• 렌더러 (PopRenderer.tsx - CSS Grid)
• 캔버스 (PopCanvas.tsx - 그리드 표시)
• 유틸리티 (gridUtils.ts - 좌표 계산)
• 레거시 삭제 (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: v4 제약조건 기반 (이전 시도)
• CHANGELOG 2026-02-05: 작업 내역
• sessions/2026-02-05: 대화 기록