sam-react-prod/sam-docs/frontend/v1/13-mobile-patterns.md

13. 모바일 반응형 패턴

대상: 프론트엔드 개발자 최종 업데이트: 2026-03-20

---

목차

번호	항목
13.1	대상 디바이스
13.2	그리드 레이아웃
13.3	테이블 대응
13.4	모달/다이얼로그
13.5	버튼/액션
13.6	텍스트 처리
13.7	체크리스트

---

13.1 대상 디바이스

디바이스	너비	Tailwind 접두사
Galaxy Z Fold 5 (접힌)	344px	기본 (접두사 없음)
일반 모바일	375-430px	기본
커스텀 브레이크포인트	480px	xs:
태블릿	768px	md:
데스크탑	1024px+	lg:

커스텀 브레이크포인트 xs (480px)는 tailwind.config.ts에 정의:

// tailwind.config.ts
theme: {
  screens: {
    xs: '480px',
    // sm, md, lg, xl 기본값 유지
  }
}

---

13.2 그리드 레이아웃

모바일 퍼스트: 항상 grid-cols-1에서 시작, 위로 확장

// ✅ 올바른 패턴
<div className="grid grid-cols-1 xs:grid-cols-2 md:grid-cols-4 gap-4">

// ❌ 데스크탑 퍼스트
<div className="grid grid-cols-4 gap-4">

폼 레이아웃 예시

// 기본 정보 폼 (4컬럼 -> 모바일 1컬럼)
<div className="grid grid-cols-1 md:grid-cols-4 gap-4">
  <div>견적번호</div>
  <div>접수일</div>
  <div>수주처</div>
  <div>현장명</div>
</div>

---

13.3 테이블 대응

방법 1: IntegratedListTemplateV2 모바일 카드 (권장)

<IntegratedListTemplateV2
  renderMobileCard={(item) => (
    <MobileCard
      title={item.name}
      subtitle={item.code}
      fields={[
        { label: '수량', value: item.quantity },
        { label: '금액', value: formatNumber(item.amount) },
      ]}
    />
  )}
/>

방법 2: 가로 스크롤

<div className="overflow-x-auto">
  <Table className="min-w-[600px]">
    {/* 테이블 내용 */}
  </Table>
</div>

방법 3: 컬럼 숨김

<TableHead className="hidden md:table-cell">비고</TableHead>
<TableCell className="hidden md:table-cell">{item.memo}</TableCell>

---

13.4 모달/다이얼로그

// ✅ 모바일에서 화면 벗어나지 않게
<DialogContent className="max-w-[calc(100vw-2rem)] max-h-[calc(100vh-2rem)]">

모바일에서 모달 내 폼:

• 필드를 1컬럼으로 쌓기
• 하단 버튼은 flex-col 또는 flex-wrap

---

13.5 버튼/액션

// ✅ 모바일: 아이콘만, 태블릿+: 아이콘+텍스트
<Button size="sm" className="md:size-default">
  <Save className="h-4 w-4 md:mr-2" />
  <span className="hidden md:inline">저장</span>
</Button>

버튼 그룹 래핑:

<div className="flex items-center flex-wrap gap-1 md:gap-3">
  <Button>...</Button>
  <Button>...</Button>
</div>

---

13.6 텍스트 처리

상황	클래스
한 줄 말줄임	truncate
여러 줄 말줄임	line-clamp-2
줄바꿈 방지 (한글)	break-keep
긴 단어 강제 줄바꿈	break-all
반응형 폰트	text-sm md:text-base

---

13.7 체크리스트

새 페이지/컴포넌트 작성 시:

#	항목
1	그리드: grid-cols-1에서 시작하는가?
2	테이블: 모바일 카드 또는 가로 스크롤 적용했는가?
3	모달: max-w-[calc(100vw-2rem)] 적용했는가?
4	버튼: 모바일 아이콘만/데스크탑 아이콘+텍스트 패턴인가?
5	긴 텍스트: truncate 또는 line-clamp 처리했는가?
6	Galaxy Fold (344px) 너비에서 깨지지 않는가?
7	줌 방지: input font-size 16px 이상인가?