WEB FE Repository

FE 작업 순서 (Material UI + 일반 Webapp 기준)

조금씩 차근차근 2025. 10. 3. 19:33

0) 킥오프 · 요구사항 정리

화면 목록/유스케이스/권한/네비게이션 플로우 확정
API 스펙 합의(가능하면 OpenAPI/Swagger 문서로 고정)
디자인 산출물(Figma) 수령 및 컴포넌트 카탈로그 확정

1) 디자인 → 디자인 토큰화 (MUI 테마 맵핑)

브랜드 컬러/중립 컬러 → theme.palette
타이포 시스템(폰트/크기/행간) → theme.typography
라운드/간격 → theme.shape.borderRadius, spacing 스케일
브레이크포인트 → theme.breakpoints
→ 산출물: “디자인-토큰 치환표(맵핑표)” 1장

토큰이란, 색상, 글꼴, 크기, 간격, 그림자 같은 디자인 속성들을 재사용 가능한 변수로 추상화한 것을 의미한다.

const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' }, // 색상 토큰
  },
  typography: {
    h1: { fontSize: '2rem', fontWeight: 700 }, // 타이포 토큰
  },
  spacing: 8, // 기본 간격 단위 (1 = 8px)
  shape: {
    borderRadius: 4, // 모서리 라운드 값
  },
});

2) 프로젝트 부트스트랩

프레임워크/번들러: Next.js(+Vite) or CRA 대체
패키지 설치: @mui/material @emotion/react @emotion/styled @mui/icons-material
- 필요 시 @mui/x-data-grid, @mui/x-date-pickers
기본 세팅: <ThemeProvider>, <CssBaseline />, Emotion 캐시(SSR 시 필수)
폴더 구조: app|pages/, components/, features/, hooks/, styles/, lib/api/, types/

3) 전역 테마 설계 & 팀 규칙 주입

createTheme()로 토큰 정의
theme.components에 공통 규칙 일괄 주입
(예: MuiButton textTransform: 'none', defaultProps.disableElevation = true)
라이트/다크 모드 토글 설계(palette.mode, 컨텍스트/스토어로 제어)
국제화/i18n, 날짜 로캘(@mui/x-date-pickers + AdapterDayjs + koKR)

원칙: 규칙은 테마에, 예외는 컴포넌트에 넣는다.

4) 레이아웃/라우팅 스켈레톤

공통 레이아웃(Header/Sidebar/Footer) Container/Grid/Stack/Box로 구성
라우팅 트리 구성(권한 가드까지 포함)
반응형 파운데이션: sx + breakpoints로 패딩/그리드 베이스라인 확정

5) UI 컴포넌트 조립 → 페이지 구축

조립 우선: MUI 기본 컴포넌트로 80% 구현
커스터마이즈: 반복되는 패턴은 variants/styleOverrides, 단발성은 sx
피드백/대화형 패턴: Snackbar/Alert/Dialog/Backdrop/Skeleton 즉시 도입
접근성(a11y): 라벨, aria-*, 포커스 트랩(모달) 확인

6) 상태관리 & API 연동(백엔드: Spring)

클라이언트: OpenAPI로 타입/클라이언트 코드 생성(가능하면)
서버상태: TanStack Query(캐시/로딩/에러 표준화)
폼: react-hook-form + Controller + TextField/Select + 검증(zod/yup)
에러/로딩/권한 공통 처리(인터셉터, 에러 바운더리, 토스트 정책)
보안/세션: 토큰 저장소 전략(localStorage vs cookie), 만료 처리 플로우

7) 기능 고도화 · 품질 보강

반응형 마감(모바일/태블릿/데스크탑)
테이블/필터/정렬/페이지네이션(DataGrid) 확정
접근성 점검(키보드 탭 순서, 콘트라스트, 스크린리더 라벨)

8) 성능 최적화

코드 스플리팅/라우트 레벨 Lazy
이미지/아이콘 최적화(SVG sprite or 아이콘 패키지 사용, 이미지 WebP/AVIF)
MUI 렌더 비용: memo, useCallback 최소화, sx 남용 구간 점검
번들 분석(webpack-bundle-analyzer/Next.js 분석 툴)

9) 테스트 & 모니터링

유닛/스냅샷: React Testing Library(역할·라벨 기반)
E2E: Playwright/Cypress로 핵심 시나리오
로깅·APM: Sentry/Datadog, 사용자 이벤트(Analytics) 최소 세트

10) 빌드 & 배포

환경변수 체계(.env.*), CI/CD(빌드 캐시, 린트·테스트 게이트)
정적 에셋 CDN 캐시, 폰트 woff2 + display=swap
릴리즈 노트 & 롤백 전략

산출물/완료 기준(DoD) 예시

디자인-토큰 치환표, 전역 테마 파일
공통 레이아웃 + 라우팅 가드
페이지별 스켈레톤 + 로딩/에러 UX
OpenAPI 기반 타입 안전 API 클라이언트
폼 검증/에러 메시지 일관 정책
성능 기준(First Load JS, LCP 목표치 등) 충족
a11y 최소 기준(콘트라스트, 키보드 내비) 통과
테스트 커버리지/핵심 E2E 통과
배포 자동화 + 롤백 확인

흔한 함정 & 회피법

토큰 미정·산발적 스타일 → 초기에 테마/variants로 규칙 고정
sx 과다 사용으로 일관성 저하 → 반복 패턴은 컴포넌트 변형(variants)로 승격
폼-상태-API 중복 로직 → RHF + Query로 역할 분리(클라이언트 상태 vs 서버 상태)
접근성·반응형 후순위 → 스켈레톤 단계에서 기본 대응 넣고 진행