🚀 [기능개선][디자인] 디자인 시스템 재확립 및 대형 화면 분해 (전면 표준화 Phase 3)

[Cassiiopeia]

📝 현재 문제점

Phase 2까지 코드 구조와 게임 진행 정합성을 정리했습니다. 이 이슈는 눈에 보이는 부분을 다룹니다.

실패했을 때 사용자가 아무것도 알 수 없습니다

착수 전 점검에서 발견한 두 건입니다. API 호출이 실패했을 때의 화면입니다.

프로필 화면 — 검은 화면만 표시됩니다

데이터를 못 받으면 에러도, 로딩 표시도, 안내도 없이 배경만 보입니다. 사용자는 왜 아무것도 안 나오는지 알 수 없고, 앱이 멈춘 것으로 오해합니다.

랭킹 화면 — 영문 원본 에러가 그대로 노출됩니다

Request failed with status code 403

useRankingData가 error.message를 그대로 화면에 표시합니다. 준비된 한국어 폴백 문구는 message가 비어 있을 때만 쓰이므로 사실상 동작하지 않습니다.

디자인 토큰이 있지만 쓰이지 않습니다

src/styles/theme.js(194줄)에 색상·간격·z-index가 정의돼 있으나 src/ 전체에서 4개 파일만 import합니다. 나머지는 rgba(...)를 컴포넌트에 직접 씁니다.

같은 연보라색이 colors.primary로도, 하드코딩된 rgba(200, 182, 226, 0.9)로도 존재합니다. 한 곳을 바꿔도 다른 곳은 그대로 남습니다.

토큰에 "이 색을 언제 쓰는가"가 정의돼 있지 않은 것도 문제입니다. 새 컴포넌트를 만들 때 참조할 기준이 없어 결국 눈대중으로 값을 적게 됩니다.

파일이 너무 큽니다

파일	줄 수
src/pages/Home.jsx	2193
src/pages/Board.jsx	1043
src/components/ImageGallery.jsx	611
src/pages/Profile.jsx	513

Home.jsx는 styled 정의 1100여 줄에 더해 로그인·회원가입·MBTI 폼·성별 선택·생년월일·크레딧 모달·음악 컨트롤·갤러리 진입이 한 파일에 들어 있습니다. 이 크기에서는 스타일 정리 자체가 불가능합니다.

인라인 스타일과 styled-components가 섞여 있습니다

인라인 style={{}}이 36곳에 있습니다. 대부분 정적 값이라 재사용도 테마 적용도 안 됩니다.

styled-components 경고

랭킹 화면에서 unknown prop "progress" is being sent through to the DOM 경고가 발생합니다. transient prop($ 접두사)으로 정리해야 합니다.

🛠️ 해결 방안 / 제안 기능

캡처 없이 추측으로 고치지 않습니다

먼저 전 화면을 3해상도에서 캡처해 문제 목록을 만들고, 그 목록을 근거로 작업합니다. 수정 후 동일 해상도에서 재캡처해 before/after를 비교합니다.

구분	해상도
데스크톱	1440 × 900
태블릿	768 × 1024
모바일	390 × 844

토큰을 2계층으로 재설계합니다

• 원시 토큰 — 팔레트 원색, 간격 스케일, 폰트 크기, 반경, 그림자
• 의미 토큰 — surface.glass, text.primary, action.primary 등 용도 기반 이름

컴포넌트는 의미 토큰만 참조합니다. 그래야 "언제 쓰는 색인지"가 이름에 담깁니다.

분해와 토큰 적용은 함께 진행합니다

파일이 크면 스타일 정리가 불가능하고, 토큰이 없으면 분해해도 값이 흩어집니다. 두 작업은 분리할 수 없습니다.

⚙️ 작업 내용

1. 실패 화면 처리 (선행 — 사용자 영향이 가장 큼)

• 프로필: 로딩 상태와 실패 안내 추가. 검은 화면 제거
• 랭킹: 영문 원본 대신 한국어 안내 표시. 원본은 로거로만
• 두 화면의 재시도 동선 확인

2. 전수 점검

• dev 서버 기동 후 3해상도 캡처
• 대상: 홈(로그인 전/후), 로그인·회원가입·크레딧 모달, 갤러리, 인트로, Main1~5, 결과, 엔딩 4종, 게임오버, 랭킹, 프로필, 404
• 문제 목록을 docs/DESIGN-SYSTEM.md에 기록

3. 토큰 재설계

• 원시 토큰 / 의미 토큰 2계층 정의
• 브레이크포인트 하드코딩을 media 헬퍼로 교체

4. 대형 화면 분해

• Home.jsx → pages/Home/index.jsx + components/(AuthModal, CreditsModal, MusicControl 등) + *.styled.js
• Board.jsx → 리스트 / 아이템 / 헤더 / 무한스크롤 분리
• ImageGallery.jsx, Profile.jsx 동일 원칙
• 목표: 각 파일 300줄 이하

5. 스타일 통일

• 하드코딩된 rgba 값을 의미 토큰으로 교체
• 인라인 스타일 36곳 흡수 (동적 계산값은 예외)
• unknown prop 경고 해소 (transient prop)

6. 검증

• 3해상도 재캡처 후 before/after 비교
• 분해된 컴포넌트 테스트 (모달 개폐, 폼 검증, 랭킹 아이템 렌더)
• 커버리지 게이트 유지

완료 기준

• lint · test:ci · format:check · build 전부 통과
• 3해상도 전 화면에서 레이아웃 깨짐 0
• Home.jsx · Board.jsx 각 300줄 이하
• API 실패 시 모든 화면이 사용자에게 상황을 알린다
• docs/DESIGN-SYSTEM.md 확정

위험 요소

대형 파일 분해는 회귀 위험이 큽니다. Home.jsx에는 로그인·회원가입 폼이 들어 있어 잘못 분해하면 인증 자체가 깨집니다. 분해 전후로 동일 해상도 캡처를 비교하고, 실제 로그인 동선을 확인합니다.

관련 문서

• 설계 스펙: docs/superpowers/specs/2026-07-27-codebase-standardization-design.md (4.3절)
• 현황 기록: docs/DESIGN-SYSTEM.md
• 선행 이슈: 🚀 [기능개선][품질체계] 코드 품질 체계 및 문서 구조 확립 (전면 표준화 Phase 0) #91 (Phase 0), 🚀 [기능개선][품질체계] 인증/API 레이어 통일 및 레거시 제거 (전면 표준화 Phase 1) #94 (Phase 1), 🚀 [기능개선][게임진행] 게임 라우팅 및 진행 상태 정합성 수정 (전면 표준화 Phase 2) #97 (Phase 2)

🙋‍♂️ 담당자

• 프론트엔드: Cassiiopeia

[github-actions]

Guide by SUH-LAB

브랜치

20260727_#100_기능개선_디자인_디자인_시스템_재확립_및_대형_화면_분해_전면_표준화_Phase_3

커밋 메시지

디자인 시스템 재확립 및 대형 화면 분해 전면 표준화 Phase 3 : feat : 변경 사항에 대한 설명 https://github.com/bagle-ggul/Bagel-Frontend/issues/100

[Cassiiopeia]

정정 및 1차 작업 완료

정정 — 프로필 "검은 화면"은 오판이었습니다

이슈 본문에 "프로필 화면이 검은 화면만 표시된다"고 적었으나 사실과 다릅니다.

ProfileWrapper의 1초 페이드인 애니메이션 도중에 캡처된 것이었고, 충분히 기다린 뒤 재캡처하니 스켈레톤 로딩 UI가 정상 표시됩니다.

다만 실제 문제는 실재했습니다: catch 블록이 비어 있어 조회 실패 시에도 에러 상태가 없고, !profile 조건이 계속 참이라 스켈레톤이 영원히 표시됩니다. 사용자는 계속 로딩 중이라고 여기고 기다리게 됩니다.

1차 작업 완료 (PR #101)

• 프로필: 에러 상태 + 안내 화면 + 재시도 버튼 추가
• 랭킹: 영문 원본(Request failed with status code 403) 대신 한국어 안내 표시. 원본은 로거로만
• Phase 1에서 놓친 Profile.jsx의 수동 Authorization 헤더 제거 (auth.js를 경유해 린트 룰에 걸리지 않았음)

403 상황을 재현해 두 화면 모두 정상 안내가 뜨는 것을 확인했습니다.

남은 작업

• 3해상도 전 화면 캡처 및 문제 목록 작성
• 디자인 토큰 2계층 재설계
• Home.jsx(2193줄) · Board.jsx(1043줄) 분해
• 인라인 스타일 36곳 흡수
• unknown prop "progress" 경고 해소

[Cassiiopeia]

진행 상황 (v1.4.11까지 배포 완료)

완료

항목	결과	PR
API 실패 시 사용자 안내	프로필·랭킹 두 화면 수정	#101
Home.jsx styled 분리	2190줄 → 1155줄	#103
Board.jsx styled 분리	1045줄 → 531줄	#103
unknown prop "progress" 경고	해소 (transient prop)	#103
모달 3종 분리	Home.jsx 1155줄 → 913줄	#105
문서 동기화	분해 결과·품질 기준 반영	#107

분해된 구조:

src/pages/
├── Home.jsx            # 913줄
├── Home.styled.js
├── Home/
│   ├── CreditsModal.jsx
│   ├── LoginModal.jsx
│   ├── LoginRequiredModal.jsx
│   └── PasswordField.jsx   # 로그인·회원가입 공유
├── Board.jsx           # 531줄
└── Board.styled.js

남은 작업

• 회원가입 모달 분리 — Home.jsx에 남은 가장 큰 덩어리(약 335줄)
  • 상태 13개가 얽혀 있음: MBTI 4 + 생년월일 3 + 폼 4 + 성별 + 에러
  • 접근 제안: 모달 전체를 한 번에 빼기보다 하위 선택 컴포넌트부터 분리
    • MbtiSelect — 4개 상태를 하나의 객체 prop으로
    • BirthDateSelect — 연/월/일
    • GenderSelect — 단일 값
  • 그다음 남은 폼 본체를 SignupModal로
• 디자인 토큰 2계층 재설계 — 원시 토큰 / 의미 토큰 분리. 현재 theme.js는 값의 나열이라 "언제 쓰는 색인지"가 없음
• 인라인 스타일 34곳 흡수
• 3해상도 전수 캡처 (1440·768·390) 및 문제 목록 작성

회귀 위험 안내

Home.jsx의 회원가입 모달에는 실제 가입 폼이 들어 있습니다. 분해 시 분해 전후 캡처 비교와 실제 가입 동선 확인을 반드시 포함해야 합니다.

지금까지 분해한 모달 3종은 모두 브라우저에서 열어 동작을 확인했습니다.