diff --git a/00_Raw/2026-04-26-Skybound_Combat_Safe_Micro_HUD_Pass.md b/00_Raw/2026-04-26-Skybound_Combat_Safe_Micro_HUD_Pass.md new file mode 100644 index 00000000..1ae82346 --- /dev/null +++ b/00_Raw/2026-04-26-Skybound_Combat_Safe_Micro_HUD_Pass.md @@ -0,0 +1,79 @@ +# Skybound Combat Safe Micro HUD Pass + +작성일: 2026-04-26 14:55 KST + +## 요청 요약 + +- 게임 화면 위에 정보 UI가 크게 떠 있어 전투 화면을 가린다. +- 현재 HUD 크기와 정렬이 정리정돈되어 보이지 않는다. +- 생존 슈터 플레이에서 UI가 전투 공간을 침범하는 것이 맞는지 재검토가 필요하다. + +## 핵심 문제 + +기존 HUD는 정보를 많이 보여주려는 방향으로 구성되어 있었다. + +하지만 Skybound는 세로형 탑다운 생존 슈터이기 때문에, 실제 플레이 중에는 전투 공간과 탄 회피 시야가 가장 중요하다. + +기존 HUD 문제: + +- HUD가 2줄 구조로 상단 전투 공간을 크게 덮었다. +- `Best Run`처럼 전투 중 즉시 판단에 필요하지 않은 정보도 상시 노출되었다. +- 버튼과 상태 카드가 커서 게임 화면보다 UI가 먼저 보였다. +- 정보 우선순위가 `생존 판단`보다 `상태판 노출`에 가까웠다. + +## 적용한 변경 + +### 한 줄 Micro HUD로 축소 + +플레이 HUD를 한 줄짜리 미니 상태바로 줄였다. + +남긴 정보: + +- Stage / Phase +- Tactical Level / EXP +- Hull Core +- Bombs +- Lock-On +- Fullscreen / Settings / Pause + +숨긴 정보: + +- Best Run + +의도: + +- 전투 중 바로 필요한 정보만 남긴다. +- 점수/기록 정보는 결과 화면이나 별도 화면에서 확인하는 것이 더 자연스럽다. +- 상단 UI가 보스, 적기, 탄막, 아이템을 가리지 않게 한다. + +### 카드 크기와 시각 무게 감소 + +HUD 카드의 높이, padding, border, button size를 모두 줄였다. + +변경: + +- HUD 높이 약 38px 기준으로 축소 +- 버튼 크기 축소 +- 카드 그림자와 외곽선 두께 완화 +- Reticle 장식 투명도 감소 + +의도: + +- 톤앤매너는 유지하되, 전투 화면의 주인공은 UI가 아니라 기체/적/탄막이 되게 한다. +- 사용자는 HUD를 “볼 수는 있지만 의식하지 않아도 되는” 수준으로 인지하게 한다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HUDOverlay.css` + +## 검증 + +- `npm run build` 성공 +- 출력 디렉터리: `dist/33` + +## 후속 플레이테스트 체크 포인트 + +- 상단 HUD가 전투 판단을 방해하지 않는지 확인한다. +- HP, Level, Bomb, Lock-On이 작아졌어도 읽히는지 확인한다. +- `Best Run`을 숨겨도 플레이 중 정보 부족이 느껴지지 않는지 확인한다. +- 브라우저 창과 전체화면 양쪽에서 HUD가 너무 작거나 겹치지 않는지 확인한다. diff --git a/00_Raw/2026-04-26-Skybound_Desktop_Side_Dock_HUD.md b/00_Raw/2026-04-26-Skybound_Desktop_Side_Dock_HUD.md new file mode 100644 index 00000000..4ef2f8d1 --- /dev/null +++ b/00_Raw/2026-04-26-Skybound_Desktop_Side_Dock_HUD.md @@ -0,0 +1,66 @@ +# Skybound Desktop Side Dock HUD + +작성일: 2026-04-26 14:58 KST + +## 요청 요약 + +- 플레이 화면에서 HUD가 전투 필드를 가려 불편하다. +- 현재 UI 배치가 게임 화면 안쪽에 있어 세로 슈터 플레이와 맞지 않아 보인다. +- HUD를 정리하면서도 전투 화면을 침범하지 않게 해야 한다. + +## 핵심 문제 + +이전 Micro HUD는 크기를 줄였지만 여전히 게임 필드 안쪽 상단에 배치되어 있었다. + +세로형 탑다운 슈터에서는 상단도 적기, 탄환, 보스, 아이템이 등장하는 실제 플레이 공간이다. + +따라서 HUD가 작더라도 필드 위에 올라가 있으면 다음 문제가 생긴다. + +- 상단에서 등장하는 적과 탄환을 가린다. +- 보스나 아이템이 HUD 뒤로 지나갈 때 인지가 늦어진다. +- 화면의 주인공이 전투가 아니라 UI처럼 보인다. + +## 적용한 변경 + +### Desktop Side Dock HUD + +데스크톱 화면에서는 HUD를 게임 필드 바깥 오른쪽 블랙 여백으로 이동했다. + +표시 구조: + +- Stage / Phase +- Hull Core +- Tactical Level / EXP +- Bombs / Lock-On +- Fullscreen / Settings / Pause + +의도: + +- 플레이 필드를 최대한 깨끗하게 유지한다. +- 전투 판단에 필요한 정보는 유지하되, 실제 전투 공간 위에 올리지 않는다. +- 데스크톱의 넓은 검은 여백을 UI 도크로 활용한다. + +### 좁은 화면 대응 + +화면 폭이 좁을 때는 오른쪽 여백이 부족할 수 있으므로 기존 Micro HUD 형태를 유지한다. + +의도: + +- 데스크톱에서는 전투 필드를 침범하지 않는다. +- 좁은 화면에서는 HUD가 화면 밖으로 잘리지 않도록 한다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HUDOverlay.css` + +## 검증 + +- `npm run build` 성공 +- 출력 디렉터리: `dist/34` + +## 후속 플레이테스트 체크 포인트 + +- 데스크톱에서 HUD가 게임 필드 오른쪽 바깥으로 빠지는지 확인한다. +- 상단에서 등장하는 적기와 탄환이 HUD에 가려지지 않는지 확인한다. +- 오른쪽 도크의 글씨가 너무 작거나 멀게 느껴지지 않는지 확인한다. +- 브라우저 폭을 줄였을 때 HUD가 화면 밖으로 잘리지 않는지 확인한다. diff --git a/00_Raw/2026-04-26-Skybound_Global_HUD_Result_UI_Tone_Unification.md b/00_Raw/2026-04-26-Skybound_Global_HUD_Result_UI_Tone_Unification.md new file mode 100644 index 00000000..862a410d --- /dev/null +++ b/00_Raw/2026-04-26-Skybound_Global_HUD_Result_UI_Tone_Unification.md @@ -0,0 +1,102 @@ +# Skybound Global HUD Result UI Tone Unification + +작성일: 2026-04-26 14:48 KST + +## 요청 요약 + +- 전체 게임 HUD/UI가 정리정돈된 느낌을 잃었다. +- 플레이 중 HUD가 패널 단위로 흩어져 보이고 사용자 친화적이지 않다. +- `MISSION_FAILED` 결과 화면이 이전 스타일을 사용하고 있어 현재 `Stylized Casual Magitech` 톤앤매너와 맞지 않는다. +- 누락된 구형 UI가 없도록 전체적으로 안정적이고 깔끔한 방향으로 맞춰야 한다. + +## 핵심 문제 + +이번 문제의 핵심은 UI 요소 자체의 색상보다 정보 구조였다. + +기존 플레이 HUD는 `Stage`, `Tactical Level`, `Hull Core`, `Bombs`, `Lock-On`, `Best Run`, 설정 버튼이 모두 같은 헤더 라인 안에서 밀집되어 있었다. + +그 결과: + +- 각 정보의 중요도가 잘 구분되지 않았다. +- 큰 반투명 배경판이 전투 화면 위를 덮어 정돈감보다 부피감이 커졌다. +- 작은 화면비나 Campaign 플레이 상황에서 모듈 간 간격이 불안정해 보였다. + +Mission Failed 화면은 더 큰 문제가 있었다. + +- `MISSION_FAILED`처럼 시스템 문자열에 가까운 표기였다. +- 결과 카드가 얇은 글래스모피즘/스티치 스타일에 가까워, 현재의 두꺼운 외곽선과 선명한 마지테크 UI와 맞지 않았다. +- 실패 상태에서 사용자가 다음에 무엇을 하면 되는지 안내가 약했다. + +## 적용한 변경 + +### Gameplay HUD 정리 + +HUD를 명확한 grid 영역으로 재정렬했다. + +구조: + +- 좌측: Stage / Phase +- 중앙 상단: Tactical Level / EXP +- 우측 상단: Hull Core +- 중앙 하단: Bombs / Lock-On +- 우측 하단: Best Run +- 최우측: Fullscreen / Settings / Pause + +변경 의도: + +- 큰 통합 배경판을 제거하고, 정보별 카드가 정확한 칸에 고정되도록 했다. +- 각 UI 모듈의 크기를 줄여 전투 화면을 덜 가리게 했다. +- `Stage`, `HP`, `Bomb`, `Lock-On`처럼 전투 판단에 필요한 정보가 빠르게 읽히도록 했다. +- 모든 HUD 카드에 동일한 진한 네이비, 두꺼운 외곽선, 시안/라임/골드 포인트를 적용했다. + +### Mission Result / Mission Failed 화면 통합 + +결과 화면을 현재 톤앤매너에 맞게 다시 스타일링했다. + +변경: + +- `MISSION_FAILED` → `MISSION FAILED` +- `MISSION_SUCCESS` → `MISSION CLEARED` +- `MISSION_COMPLETE` → `MISSION COMPLETE` +- 실패 시 `Recovery Beacon Received` 상태 문구 추가 +- 실패 시 `Hull core collapsed. Refit, upgrade, and redeploy.` 안내 추가 +- 결과 카드, 스탯 그리드, 버튼을 두꺼운 외곽선 기반의 마지테크 카드로 변경 +- 실패 상태는 오렌지/레드 계열, 성공 상태는 시안/라임 계열로 명확히 구분 + +의도: + +- 실패 화면도 게임 세계관 안의 결과 보고서처럼 보이게 한다. +- 사용자가 실패 후 바로 재도전 또는 복귀를 이해할 수 있게 한다. +- 성공/실패/완료 화면이 서로 다른 낡은 스타일로 보이지 않게 한다. + +### Boss Warning 전역 알림 통일 + +기존 보스 경고는 Tailwind class 기반의 붉은 경고 띠 2개로 출력되어 현재 UI 톤과 따로 놀았다. + +변경: + +- `WARNING` 반복 띠를 제거 +- `BOSS SIGNAL` 마지테크 경고 카드로 변경 +- 오렌지/레드 기반의 위협 색상은 유지하되, 두꺼운 외곽선과 카드형 구조로 통일 +- 보스 진입 시 사용자가 해야 할 행동을 짧게 안내 + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HUDOverlay.css` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/ResultCard.tsx` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/ResultCard.css` +- `/Volumes/Data/project/Antigravity/Skybound/src/App.tsx` +- `/Volumes/Data/project/Antigravity/Skybound/src/App.css` + +## 검증 + +- `npm run build` 성공 +- 출력 디렉터리: `dist/31` + +## 후속 플레이테스트 체크 포인트 + +- 플레이 HUD가 전투 화면을 과하게 덮지 않는지 확인한다. +- HUD 정보가 `Stage`, `Level`, `HP`, `Bomb`, `Lock-On` 순서로 자연스럽게 읽히는지 확인한다. +- Mission Failed 화면이 더 이상 옛날 스타일처럼 보이지 않는지 확인한다. +- 실패 후 사용자가 `Retry Mission`과 `Back to Title` 선택을 쉽게 이해하는지 확인한다. +- Boss Signal 경고가 위협적이면서도 현재 UI 톤에서 튀지 않는지 확인한다. diff --git a/00_Raw/2026-04-26-Skybound_Hangar_Upgrade_Scroll_and_Campaign_Footer_Stabilization.md b/00_Raw/2026-04-26-Skybound_Hangar_Upgrade_Scroll_and_Campaign_Footer_Stabilization.md new file mode 100644 index 00000000..5f369bc6 --- /dev/null +++ b/00_Raw/2026-04-26-Skybound_Hangar_Upgrade_Scroll_and_Campaign_Footer_Stabilization.md @@ -0,0 +1,93 @@ +# Skybound Hangar Upgrade Scroll and Campaign Footer Stabilization + +작성일: 2026-04-26 14:43 KST + +## 요청 요약 + +- Hangar의 `Permanent Upgrades` 목록 아래에 더 많은 항목이 있는 것처럼 보이지만 확인할 수 없다. +- 업그레이드 목록에는 스크롤 개념이 필요하다. +- Campaign 모드로 전환하면 HUD/UI가 무너지고, 하단 영역이 깔끔하게 정렬되지 않는다. +- 모드가 바뀌어도 기본적인 UI 크기와 구조는 흔들리지 않아야 한다. + +## 핵심 문제 + +이번 문제는 단순히 리스트 높이가 부족한 문제가 아니라, Hangar 화면 전체가 `상단 헤더 / 중앙 콘텐츠 / 하단 출격 영역`을 명확히 나누지 못해서 발생했다. + +기존 구조에서는 중앙 콘텐츠가 남는 높이를 안정적으로 계산하지 못했고, footer에는 Campaign 모드에서만 `Tactical Support`가 나타나면서 모드 전환 시 화면의 세로 배치가 흔들렸다. + +그 결과: + +- 업그레이드 리스트가 화면 아래로 잘려 보였다. +- footer의 Mission Mode, Tactical Support, Launch 버튼이 서로 가까워지거나 겹쳐 보였다. +- Campaign/Blitz 모드 전환이 화면 재배치처럼 느껴졌다. + +## 적용한 변경 + +### Hangar 전체 레이아웃 안정화 + +`hangar-inner`를 grid 기반의 3영역 구조로 고정했다. + +구조: + +- Header +- Main content +- Footer controls + +중앙 콘텐츠는 `minmax(0, 1fr)`로 남은 높이만 사용하게 했고, 전체 Hangar는 화면 밖으로 넘치지 않도록 `overflow: hidden`을 적용했다. + +의도: + +- 상단/중앙/하단 영역이 서로 침범하지 않게 한다. +- 화면 높이가 달라도 하단 버튼이 콘텐츠를 밀어내거나 겹치지 않게 한다. +- Campaign/Blitz 전환 시 기본 UI 크기가 변하지 않게 한다. + +### Permanent Upgrades 내부 스크롤 추가 + +`upgrade-list`에 내부 스크롤을 추가했다. + +변경: + +- `upgrade-shop`은 내부 콘텐츠를 감싸는 고정 영역이 된다. +- `upgrade-list`만 세로 스크롤된다. +- 스크롤바는 기존 Stylized Casual Magitech 톤에 맞춰 시안/라임 계열로 스타일링했다. +- 업그레이드 행 높이를 조금 줄여 한 화면에서 더 많은 항목을 볼 수 있게 했다. + +의도: + +- 목록이 길어져도 Hangar footer를 밀어내지 않는다. +- 아래 항목이 있는지 스크롤바로 명확히 알 수 있다. +- 사용자가 업그레이드 탭에서 항목을 잃어버렸다고 느끼지 않게 한다. + +### Campaign Footer 재정렬 + +footer를 `Mission Mode / Tactical Support / Launch` 3열 구조로 변경했다. + +변경: + +- 왼쪽: Mission Mode +- 중앙: Tactical Support +- 오른쪽: Ignite & Launch + +Blitz 모드에서는 Tactical Support 영역을 placeholder로 유지해, 모드가 바뀌어도 footer 높이와 버튼 위치가 흔들리지 않게 했다. + +의도: + +- Campaign 모드에서 Tactical Support가 나타나도 Launch 버튼과 겹치지 않는다. +- Blitz 모드에서도 동일한 UI 골격을 유지한다. +- 하단 조작 영역이 더 상품성 있는 런처 패널처럼 보이게 한다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HangarOverlay.css` + +## 검증 + +- `npm run build` 성공 +- 출력 디렉터리: `dist/30` + +## 후속 플레이테스트 체크 포인트 + +- `Permanent Upgrades` 목록에서 아래 항목까지 스크롤로 확인 가능한지 확인한다. +- Campaign/Blitz 전환 시 footer 높이와 Launch 버튼 위치가 흔들리지 않는지 확인한다. +- Tactical Support가 Campaign 모드에서만 보이더라도 화면 구조가 깨져 보이지 않는지 확인한다. +- 16:9, 16:10, 작은 노트북 높이에서 footer가 다시 중앙 콘텐츠를 침범하지 않는지 확인한다. diff --git a/00_Raw/2026-04-26-Skybound_LevelUp_Modal_Text_Fit_and_Card_Layout_Fix.md b/00_Raw/2026-04-26-Skybound_LevelUp_Modal_Text_Fit_and_Card_Layout_Fix.md new file mode 100644 index 00000000..fa324961 --- /dev/null +++ b/00_Raw/2026-04-26-Skybound_LevelUp_Modal_Text_Fit_and_Card_Layout_Fix.md @@ -0,0 +1,77 @@ +# Skybound LevelUp Modal Text Fit and Card Layout Fix + +작성일: 2026-04-26 14:52 KST + +## 요청 요약 + +- Tactical Upgrade 화면에서 카드 텍스트가 잘려 보인다. +- `Skip Upgrade` 설명이 카드 하단에서 잘린다. +- 카드 상단 배지와 설명 텍스트가 서로 겹쳐 보인다. +- 전체적으로 모달이 화면 안에 안정적으로 fit 되지 않는다. + +## 핵심 문제 + +레벨업 모달의 문제는 카드 높이와 텍스트 양의 불일치였다. + +기존 카드에는 다음 문제가 있었다. + +- `skill-card`가 `overflow: hidden`으로 설정되어 긴 설명이 카드 내부에서 잘렸다. +- `WEAPON`, `PASSIVE`, `SKIP` 태그가 absolute position으로 떠 있어 추천 사유 텍스트와 겹쳤다. +- `Skip Upgrade` 카드만 낮은 높이로 지정되어 설명 문장이 충분히 들어가지 않았다. +- 카드 목록 전체는 스크롤되지만, 개별 카드 내부 텍스트는 카드 안에서 잘리는 구조였다. + +## 적용한 변경 + +### 카드 내부 레이아웃 grid화 + +카드 구조를 3열 grid로 정리했다. + +구조: + +- 좌측: 스킬 아이콘 +- 중앙: 추천 사유, 스킬명, 레벨 변화, 설명 +- 우측: `WEAPON`, `PASSIVE`, `SKIP` 타입 태그 + +이제 타입 태그가 텍스트 위에 떠서 겹치지 않고, 카드 내부의 명확한 영역을 갖는다. + +### 텍스트 잘림 방지 + +개별 카드의 `overflow: hidden` 의존을 제거하고, 카드가 내용에 맞게 커지도록 조정했다. + +변경: + +- 일반 카드와 `Skip Upgrade` 카드 모두 내용 기반 높이 사용 +- 설명 텍스트는 카드 내부에서 잘리지 않게 처리 +- 카드 목록 영역만 스크롤 유지 +- 카드 간격과 폰트 크기 조정 + +의도: + +- 텍스트를 강제로 숨기지 않는다. +- 화면이 작으면 전체 목록을 스크롤해서 확인한다. +- 카드 하나하나의 정보는 카드 안에서 온전히 읽힌다. + +### 작은 화면 대응 + +화면 높이가 낮은 경우에는 추천 사유의 보조 설명을 숨기고 핵심 라벨만 남긴다. + +의도: + +- `New module`, 스킬명, 레벨 변화, 실제 효과 설명을 우선 노출한다. +- 작은 화면에서도 중요한 의사결정 정보가 잘리지 않게 한다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.css` + +## 검증 + +- `npm run build` 성공 +- 출력 디렉터리: `dist/32` + +## 후속 플레이테스트 체크 포인트 + +- `Skip Upgrade` 설명이 카드 안에서 잘리지 않는지 확인한다. +- `WEAPON`, `PASSIVE`, `SKIP` 태그가 추천 사유 텍스트와 겹치지 않는지 확인한다. +- 카드가 4개 이상일 때 목록 스크롤로 모든 항목을 확인할 수 있는지 확인한다. +- 작은 화면 높이에서도 핵심 정보가 잘 보이는지 확인한다. diff --git a/00_Raw/2026-04-26-Skybound_Stage1_Enemy_Reduction_and_UI_Readability_Pass.md b/00_Raw/2026-04-26-Skybound_Stage1_Enemy_Reduction_and_UI_Readability_Pass.md new file mode 100644 index 00000000..827aeb07 --- /dev/null +++ b/00_Raw/2026-04-26-Skybound_Stage1_Enemy_Reduction_and_UI_Readability_Pass.md @@ -0,0 +1,145 @@ +# Skybound Stage 1 Enemy Reduction and UI Readability Pass + +작성일: 2026-04-26 14:38 KST + +## 요청 요약 + +- Stage 1 기준으로 아직 적기 개체수가 많게 느껴진다. +- 현재보다 약 30% 적게 나오도록 조정한다. +- 레벨업/업그레이드 목록이 잘려 보이는 문제가 있다. +- Campaign 모드로 전환하면 UI가 달라지면서 목록이 더 잘린다. +- 모드가 바뀌어도 기본 UI 크기는 변경되지 않아야 한다. +- Gameplay HUD가 상품성 있는 UI라기보다 프로토타입처럼 보이고, 정보가 너무 많아 인지가 어렵다. + +## 핵심 문제 + +이번 피드백은 전투 밸런스와 UI 구조 문제가 같이 연결되어 있었다. + +1. Stage 1은 정찰대 컨셉으로 줄였지만 여전히 체감 물량이 많았다. +2. Level Up 화면은 `Skip Upgrade`와 슬롯 정보가 추가되면서 카드 수가 늘어났고, 화면 높이에 따라 목록이 잘릴 수 있었다. +3. Hangar는 Campaign 선택 시 `Tactical Support`가 나타나 footer 높이가 바뀌고, 중앙 목록 영역을 밀어내는 구조였다. +4. Gameplay HUD는 좌우 패널 정보량이 많고, 실제 플레이 중 중요한 정보보다 장식성 정보가 많았다. + +## 적용한 변경 + +### Stage 1 적기 수 30% 감소 + +Stage 1 `First Contact` 프로필의 개체수와 최대 동시 적 수를 줄였다. + +변경: + +- `capBase: 12` → `8` +- opening density: `4` → `3` +- swarm density: `12` → `8` +- climax elite density: `2` → `1` + +또한 Stage 1에만 phase cap add scale을 적용했다. + +Stage 1의 압박/스웜/클라이맥스 phase에서 추가되는 최대 적 수를 65%만 반영하도록 했다. + +의도: + +- Stage 1은 보스가 플레이어를 얕보는 정찰 단계로 유지한다. +- 적 수는 확실히 줄이되, 공격력/위협은 유지해 긴장감을 남긴다. +- 화면을 적으로 채우기보다 회피와 무기 이해에 집중하게 한다. + +### Level Up 목록 잘림 방지 + +`LevelUpModal`의 카드 목록 영역에 내부 스크롤을 추가했다. + +변경: + +- overlay는 화면 밖으로 넘치지 않게 처리 +- container는 `max-height`를 갖고 내부에서만 스크롤 +- card grid는 `overflow-y: auto` +- 4번째 카드 또는 `Skip Upgrade` 카드가 잘리지 않도록 높이 조정 +- 스크롤바도 톤앤매너에 맞춰 시안/라임 계열로 스타일링 + +이제 카드가 많아져도 모달 전체가 잘리는 대신 목록 내부에서 스크롤된다. + +### Campaign/Blitz 모드 전환 시 UI 높이 고정 + +Hangar footer에서 Campaign 모드일 때만 `Tactical Support`가 등장하며 레이아웃 높이가 바뀌던 문제를 수정했다. + +변경: + +- footer를 고정 grid row 구조로 변경 +- Tactical Support 영역을 항상 슬롯으로 확보 +- Blitz에서는 해당 영역을 placeholder로 숨김 처리 +- Launch 버튼 위치가 Campaign/Blitz 전환에 따라 출렁이지 않도록 고정 + +의도: + +- 모드가 바뀌어도 기본 UI 크기와 리스트 공간이 변하지 않게 한다. +- 사용자가 Campaign/Blitz를 바꿔도 화면이 재배치되는 느낌을 줄인다. + +### Gameplay HUD 정보 구조 개선 + +기존 HUD는 좌우 사이드 패널에 너무 많은 상태 정보가 있었고, 실제 플레이 중 필요한 정보보다 프로토타입성 정보가 강했다. + +이번 패스에서는 HUD를 상단 compact bar 중심으로 재구성했다. + +남긴 핵심 정보: + +- Stage / Phase +- Tactical Level / EXP +- Hull Core HP +- Bombs +- Lock-On +- Best Run +- Fullscreen / Settings / Pause buttons + +줄인 정보: + +- 좌측 대형 pilot/status panel +- 과한 nav item +- Chain Bonus 패널 +- 긴 세로 thrust meter +- 중복 장식성 텍스트 + +결과: + +- 시야 양옆을 덜 가린다. +- 주요 생존 정보가 한 줄에 모인다. +- HUD가 작아지고 읽기 쉬워졌다. +- 플레이 중 적/탄막 가시성이 좋아진다. + +## 설계 의도 + +이번 변경의 핵심은 “적게 보여주되 더 잘 읽히게” 만드는 것이다. + +게임 플레이 중 HUD는 세계관을 보여주는 장식판이 아니라, 사용자가 즉시 판단해야 하는 정보만 빠르게 읽게 해줘야 한다. + +그래서 다음 우선순위로 재배치했다. + +1. 지금 몇 스테이지인가? +2. 현재 페이즈가 위험한가? +3. HP는 안전한가? +4. 레벨업까지 얼마나 남았나? +5. Bomb/Lock-On을 사용할 수 있는가? + +나머지 정보는 플레이 중 상시 노출 우선순위에서 제외했다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/CombatTimeline.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HangarOverlay.tsx` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HangarOverlay.css` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HUDOverlay.tsx` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HUDOverlay.css` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.css` + +## 검증 + +- `npm run build` 성공 +- `/sprites/player.png` 경고 없음 +- 출력 디렉터리: `dist/29` + +## 후속 플레이테스트 체크 포인트 + +- Stage 1 초반 적 수가 약 30% 줄어든 체감이 드는지 확인한다. +- Stage 1이 너무 비거나 심심해지지는 않았는지 확인한다. +- Level Up 화면에서 4번째 카드와 `Skip Upgrade`가 잘리지 않는지 확인한다. +- Campaign/Blitz 전환 시 Hangar footer와 목록 영역 높이가 흔들리지 않는지 확인한다. +- 새 HUD가 실제 플레이 중 더 읽기 쉬운지 확인한다. +- HUD가 너무 작거나 필요한 정보가 빠졌다고 느껴지지 않는지 확인한다. diff --git a/00_Raw/App Router.md b/00_Raw/App Router.md new file mode 100644 index 00000000..a7c120c4 --- /dev/null +++ b/00_Raw/App Router.md @@ -0,0 +1,25 @@ +# [[App Router]] + +## 📌 Brief Summary +App Router는 React Server Components(RSC)를 핵심으로 도입하여 애플리케이션의 렌더링 방식을 재구성한 Next.js 15의 새로운 아키텍처 패러다임입니다 [1]. 전통적인 클라이언트 사이드 렌더링 방식과 달리, 서버 컴포넌트는 클라이언트에 JavaScript를 전송하지 않고 서버에서만 실행됩니다 [1, 2]. 이 아키텍처는 React 생태계의 스타일링 패러다임에 중대한 영향을 미치며, 특히 Styled Components와 같은 런타임 CSS-in-JS 라이브러리의 호환성 및 성능 최적화 전략에 근본적인 변화를 요구합니다 [3-5]. + +## 📖 Core Content +* **서버 및 클라이언트 컴포넌트의 명확한 분리:** + App Router 환경에서 컴포넌트는 기본적으로 서버 컴포넌트로 작동하며, 클라이언트로 전송되는 JavaScript 번들 크기를 최소화하여 성능을 향상시킵니다 [2, 6]. 상태 관리나 브라우저 API 호출, 이벤트 핸들러 등 상호작용이 필요한 영역에만 `'use client'` 지시어를 명시하여 클라이언트 컴포넌트로 선언하는 전략을 취합니다 [6, 7]. 하이드레이션(Hydration) 프로세스 역시 클라이언트 컴포넌트에 대해서만 발생합니다 [8]. + +* **기존 CSS-in-JS 스타일링 패러다임과의 충돌:** + App Router의 서버 컴포넌트 환경에서는 React Context를 사용할 수 없습니다 [4, 5]. 따라서 내부적으로 React Context에 의존하여 테마 등을 관리하는 런타임 CSS-in-JS 라이브러리(Styled Components, Emotion 등)는 본질적인 호환성 문제를 겪게 됩니다 [3, 4]. 이로 인해 Next.js App Router를 기반으로 하는 신규 프로젝트에서는 Tailwind CSS, CSS Modules, 또는 런타임 오버헤드 없이 빌드 타임에 정적 CSS를 생성하는 vanilla-extract 방식이 적극 권장됩니다 [4, 9]. + +* **App Router 내 런타임 CSS-in-JS(Styled Components) 통합 방법:** + Next.js 15 App Router 환경에서 부득이하게 Styled Components를 유지해야 하는 경우, 'Style Registry(스타일 레지스트리)' 패턴을 도입해야 합니다 [10]. 이는 렌더링 중에 CSS 규칙을 수집하고, `useServerInsertedHTML` 훅을 사용해 HTML 헤드에 주입한 뒤, 애플리케이션을 레지스트리를 제공하는 클라이언트 컴포넌트로 감싸는 방식입니다 [10]. + +* **테마 및 스타일 적용의 변화:** + 서버 컴포넌트에서는 `ThemeProvider` 컴포넌트가 작동하지 않고 단순히 통과(pass-through)하는 역할만 하게 됩니다 [11, 12]. 따라서 App Router(RSC 환경)에서 테마를 구현하기 위해서는 React Context 대신 순수 CSS 사용자 지정 속성(CSS 변수)과 `createTheme` 헬퍼 함수를 활용하여 컴포넌트에 변수를 직접 참조시키는 정적인 테마 방식으로 전환해야 합니다 [11-13]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[React Server Components]], [[Tailwind CSS]], [[Styled Components]], [[CSS-in-JS]] +- **Projects/Contexts:** [[Next.js 15]] +- **Contradictions/Notes:** 소스의 평가에 따르면, 기존 Pages Router에서 사용하던 방식의 Styled Components/Emotion 기반 아키텍처는 App Router 시스템으로 넘어오면서 서버 컴포넌트(Context 사용 불가)와의 구조적 불일치를 겪습니다 [3, 4]. 결과적으로 확장 가능하고 최적화된 프론트엔드를 구축하려면 Tailwind CSS 같은 제로 런타임(Zero-runtime) 또는 유틸리티 퍼스트 방식으로 전환하거나 [9, 14], Style Registry와 CSS 변수를 활용하는 복잡한 우회 패턴을 구현해야 합니다 [10, 12]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Atomic Styling.md b/00_Raw/Atomic Styling.md new file mode 100644 index 00000000..2a753fc4 --- /dev/null +++ b/00_Raw/Atomic Styling.md @@ -0,0 +1,26 @@ +# [[Atomic Styling]] + +## 📌 Brief 단락 +Atomic Styling(또는 Atomic CSS)은 단일 목적을 가진 작고 구체적인 유틸리티 클래스(Atomic classes)를 활용하여 마크업(HTML/JSX) 내에서 직접 UI를 구성하고 스타일링하는 접근 방식입니다 [1-3]. Tailwind CSS와 같은 프레임워크에서 주로 사용하는 이른바 '유틸리티 퍼스트(Utility-first)' 방법론과 맥락을 같이 하며, 개발자가 별도의 커스텀 CSS 파일을 작성할 필요를 없애줍니다 [4-6]. 이 방식은 디자인 시스템의 일관성을 유지하면서도 프로덕션 환경에서 매우 작은 CSS 번들 크기와 뛰어난 렌더링 성능을 제공하는 것이 핵심입니다 [2, 7, 8]. + +## 📖 Core Content +* **작동 원리 (How it works):** + Atomic Styling은 `flex`, `pt-4`, `text-gray-500`, `rounded-lg`와 같이 하나의 CSS 속성이나 아주 작은 단위의 시각적 속성만을 나타내는 저수준(low-level) 유틸리티 클래스들을 제공합니다 [2-4]. 개발자는 별도의 CSS 파일에 클래스 이름을 짓고 규칙을 작성하는 대신, HTML이나 React JSX 마크업 내에 이 클래스들을 직접 조합(compose)하여 원하는 디자인을 구축합니다 [2, 3, 5]. + +* **주요 장점 (Advantages):** + * **개발 속도 및 일관성:** HTML/JSX와 CSS 파일 간의 컨텍스트 전환 없이 바로 스타일링을 할 수 있어 빠른 프로토타이핑과 개발이 가능합니다 [2, 5, 9]. 또한 사전에 정의된 디자인 토큰(간격, 색상, 타이포그래피 등)을 강제하므로 프로젝트 전반에서 시각적 일관성을 유지하기 쉽습니다 [7, 9, 10]. + * **성능 및 작은 번들 크기:** Tailwind CSS와 같은 도구는 빌드 시 프로젝트를 스캔하여 실제로 사용된 클래스만 최종 CSS에 포함시키고 사용하지 않는 스타일은 제거(Purge)합니다 [7, 8]. 이를 통해 프로덕션 CSS 번들 크기를 5~20kb 수준으로 매우 작게 유지할 수 있으며, 런타임에 JavaScript로 스타일을 주입하는 CSS-in-JS와 달리 런타임 오버헤드가 없습니다 [7, 11-13]. + * **유지보수성 향상:** React에서 컴포넌트를 삭제할 때 해당 컴포넌트 마크업에 결합된 스타일도 함께 사라지므로, 코드베이스에 사용되지 않는 '고아(orphaned)' CSS가 누적되는 것을 방지합니다 [7, 13]. + +* **단점 및 한계 (Disadvantages and Limitations):** + * **장황한 마크업 (Verbose Markup):** 스타일을 마크업에 직접 적용하므로, 복잡한 컴포넌트의 경우 `className` 문자열이 매우 길어져 코드 가독성이 떨어질 수 있습니다 [7, 14]. + * **학습 곡선:** 방대한 유틸리티 클래스 이름과 구성 방식을 숙지해야 하므로 초기 학습에 시간이 필요합니다 [14, 15]. + * **컴포넌트 캡슐화의 부재:** 순수하게 Atomic 클래스만 사용할 경우 컴포넌트 수준의 스타일 캡슐화가 부족할 수 있으므로, 대규모 앱에서는 반복되는 유틸리티 패턴을 React 컴포넌트로 추출하여 재사용하는 방식이 필수적으로 동반되어야 합니다 [14, 16, 17]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Tailwind CSS]], [[CSS-in-JS]], [[Utility-first CSS]], [[Atomic Design]] +- **Projects/Contexts:** [[Next.js App Router]], [[Scalable Design Systems]], [[Component Library Architecture]] +- **Contradictions/Notes:** 소스 [7]와 [14]는 Atomic Styling이 마크업을 장황(Verbose)하게 만들어 가독성을 해칠 수 있다고 지적하지만, 소스 [16]은 이러한 문제를 극복하기 위해 `@apply`를 남용하기보다는 패턴을 React 컴포넌트로 추출(Component Abstraction)할 것을 권장합니다. 성능 측면에서는 런타임 주입 방식의 Styled Components보다 Atomic CSS 방식(Tailwind)이 월등히 유리하다고 여러 소스에서 공통으로 주장합니다 [12, 13]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Base Web.md b/00_Raw/Base Web.md new file mode 100644 index 00000000..9db99b9d --- /dev/null +++ b/00_Raw/Base Web.md @@ -0,0 +1,18 @@ +# [[Base Web]] + +## 📌 Brief Summary +Base Web은 수많은 내부 웹 애플리케이션의 일관성을 유지하기 위해 우버(Uber)에서 개발하고 2018년에 오픈소스로 공개한 React 컴포넌트 라이브러리이자 디자인 시스템입니다 [1-3]. 기기에 구애받지 않는 범용적인 기반을 제공하여, 프론트엔드 개발자들이 반복적인 UI 구축 작업을 피하고 안정적이며 접근성이 뛰어난 웹 애플리케이션을 빠르고 쉽게 만들 수 있도록 돕습니다 [2]. 특히 복잡한 컴포넌트의 커스터마이징 시 발생하는 속성(prop) 비대화 문제를 해결하기 위해 고유한 '오버라이드(Overrides)' 패턴을 사용하는 것이 핵심적인 특징입니다 [4, 5]. + +## 📖 Core Content +- **도입 배경 및 효율성 증대**: 우버는 사내 수백 개의 애플리케이션을 운영하면서 발생하는 개발 리소스 낭비와 UI 불일치를 줄이고자 공통된 디자인 언어를 담은 Base Web을 구축했습니다 [1, 6]. 내부 데이터에 따르면, 커스텀 컴포넌트를 구축하는 것에 비해 개발 속도는 3배 빠르고, 시각적 불일치는 4배 감소하며, 코드 양을 50%나 줄여주는 강력한 생산성 향상 효과를 보였습니다 [7]. +- **신뢰성(Reliability) 및 접근성(Accessibility) 보장**: 모든 React 컴포넌트에 시각적 회귀(visual regression) 테스트를 거치며, Puppeteer를 활용한 종단 간(E2E) 테스트를 수행하여 픽셀 단위의 정확성과 버그 없는 환경을 보장합니다 [8]. 또한 키보드 탐색과 화면 판독기(screen reader), ARIA 역할을 완벽히 지원하여 접근성 기준을 충족합니다 [9, 10]. 모바일 환경 및 네트워크가 열악한 사용자를 위해 Styletron을 적용, 아토믹(atomic) 스타일링으로 번들 크기를 최적화합니다 [9]. +- **확장 가능한 아키텍처: 오버라이드(Overrides) 패턴**: 재사용 가능한 UI 컴포넌트 설계 시 무수히 많은 속성이 누적되는 "prop soup" 현상을 방지하기 위해 Base Web의 모든 컴포넌트는 `overrides` prop을 노출합니다 [5, 11]. 이 패턴을 통해 개발자는 새로운 속성을 추가하지 않고도 컴포넌트 내부의 특정 하위 요소(sub-element)에 커스텀 속성이나 스타일을 주입할 수 있으며, 심지어 내부 컴포넌트 자체를 완전히 다른 프레젠테이션 컴포넌트로 교체할 수도 있습니다 [12-14]. 이는 최상위 API를 깔끔하게 유지하면서도 고도의 커스터마이징을 가능하게 합니다 [12]. +- **디자인 시스템 관측성(Observability)**: 우버는 대규모로 디자인 시스템의 채택을 장려하기 위해 'Base Counter'라는 도구를 도입했습니다 [15, 16]. 이는 화면의 뷰 트리를 분석하여 Base 컴포넌트와 일회성 커스텀 컴포넌트의 사용 비율을 결정론적으로 측정하며, 디자인 품질 지표를 엔지니어링 지표와 동일한 수준으로 관리하여 확장 가능한 프론트엔드 관리를 실현합니다 [15, 17, 18]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Design Systems]], [[Reusable UI Components]], [[Overrides Pattern]], [[Accessibility (A11y)]], [[Styletron]] +- **Projects/Contexts:** [[Uber's Internal Web Applications]], [[Scalable Frontend Architecture]] +- **Contradictions/Notes:** 컴포넌트 라이브러리 구축 시 확장성을 확보하는 방식에 관하여, 소스에서는 Base Web이 복잡한 엣지 케이스를 다루기 위해 [[Overrides Pattern]]을 사용하는 대표적 사례로 설명합니다 [5]. 이와 병행하여, 최근 React 생태계에서는 스타일링과 UI 로직을 완전히 분리하는 [[Headless Components]]나 컴포넌트를 여러 하위 구조로 쪼개어 상태를 공유하는 [[Compound Components]] 패턴도 뛰어난 재사용성 대안으로 함께 제시되고 있습니다 [19-21]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/CLS (Cumulative Layout Shift).md b/00_Raw/CLS (Cumulative Layout Shift).md new file mode 100644 index 00000000..f12bf768 --- /dev/null +++ b/00_Raw/CLS (Cumulative Layout Shift).md @@ -0,0 +1,35 @@ +# [[CLS (Cumulative Layout Shift)]] + +## 📌 Brief Summary +CLS(Cumulative Layout Shift)는 웹페이지가 로드되는 동안 발생하는 예기치 않은 레이아웃 이동의 총량을 측정하여 페이지의 시각적 안정성을 평가하는 Core Web Vitals의 핵심 지표입니다. 이 지표는 텍스트나 버튼이 갑자기 움직여 사용자가 잘못된 클릭을 하거나 방해받는 경험을 방지하는 데 중점을 둡니다. 2025년 기준, CLS는 사용자 경험(UX)과 검색 엔진 순위(SEO)를 결정짓는 중요한 요소로 평가되며, 우수한 웹 성능을 위해 필수적으로 최적화해야 합니다. + +## 📖 기Core Content +**CLS의 중요성 및 비즈니스 영향** +* CLS는 사용자의 화면 시각적 안정성을 평가하며, 웹 사용자 중 70%가 시각적 안정성을 브랜드 신뢰 구축의 핵심 요소로 꼽습니다 [1]. +* 페이지가 불안정하여 발생하는 예기치 못한 레이아웃 이동은 사용자의 불만을 야기하고 이탈률을 15%까지 증가시킬 수 있습니다 [2-5]. +* CLS 점수를 0.25에서 0.05 수준으로 개선하면 전환율이 평균 8% 상승하고, 이탈률은 10% 감소하며, 수익이 6% 증가하는 실질적인 비즈니스 효과를 기대할 수 있습니다 [6]. + +**2025년 기준 CLS 임계값** +* 기존의 '우수(Good)' 기준은 0.1 미만이었으나, 2025년 Google의 Core Web Vitals 업데이트에 따라 0.08 미만으로 25% 더 엄격해졌습니다 [7, 8]. +* 시각적 안정성을 위해 모든 최적화 작업 후 최종 CLS 수치를 0.08 미만으로 유지하는 것이 2025년의 필수 표준입니다 [9]. + +**CLS를 악화시키는 주요 원인** +* **크기가 지정되지 않은 미디어:** 이미지나 비디오에 명시적인 크기가 없으면 브라우저가 공간을 확보하지 못해 로딩 시 콘텐츠가 밀려납니다 [4, 5, 10]. +* **동적 콘텐츠 삽입:** 배너, 광고, 알림 등 기존 콘텐츠의 위쪽에 사용자의 상호작용 없이 동적으로 삽입되는 요소가 레이아웃을 밀어냅니다 [4, 5, 10]. +* **웹 폰트의 지연 로딩:** 폰트가 늦게 로드되면서 발생하는 FOIT(Flash of Invisible Text)나 FOUT(Flash of Unstyled Text) 현상이 텍스트 크기와 줄바꿈을 변경시켜 레이아웃을 뒤틀리게 합니다 [4, 5, 10]. +* **잘못된 애니메이션 속성 사용:** `transform`이 아닌 `top`, `left`, `width`, `height` 같은 레이아웃 속성을 변경하는 애니메이션은 렌더링 트리의 재계산을 유발하여 화면을 흔들리게 합니다 [10, 11]. + +**효과적인 CLS 최적화 및 개선 전략** +* **명시적 크기 및 비율 지정:** 모든 이미지, 비디오 요소에 `width`, `height` 속성을 부여하거나 CSS의 `aspect-ratio`를 설정하여 브라우저가 렌더링 전 공간을 할당하도록 합니다 [4, 8, 9, 12, 13]. +* **동적 요소의 공간 예약(Placeholder):** 광고 슬롯, 임베드 콘텐츠, 동적 댓글/리뷰 영역에는 `min-height`를 활용한 플레이스홀더를 적용하여 콘텐츠 로딩 전후의 레이아웃 변경을 방지합니다 [9, 12-14]. +* **CSS `transform` 활용:** 애니메이션을 구현할 때는 레이아웃 변경에 영향을 주지 않고 GPU 가속을 활용하는 CSS `transform`(예: `translateX`)을 사용해야 합니다 [8, 11, 15]. +* **폰트 로딩 최적화:** 웹 폰트 사용 시 CSS에 `font-display: swap` 또는 `font-display: optional`을 설정하여 텍스트의 구조적 변동을 최소화합니다 [4, 8, 9, 13, 15]. +* **레이아웃 격리(CSS Containment):** CSS의 `contain: layout style paint` 속성을 사용하여 특정 동적 위젯이나 카드의 레이아웃 변경이 부모나 형제 요소에 파급되지 않도록 차단합니다 [14]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Core Web Vitals]], [[SEO (Search Engine Optimization)]], [[LCP (Largest Contentful Paint)]], [[INP (Interaction to Next Paint)]], [[Web Performance Optimization]] +- **Projects/Contexts:** [[Google Page Experience 2025 Update]], [[Frontend Performance Checklist]] +- **Contradictions/Notes:** 많은 소스에서 여전히 일반적인 CLS의 우수(Good) 임계값을 0.1 미만으로 언급하고 있으나 [3, 4, 16, 17], 2025년 Google 업데이트를 세밀하게 다루는 최신 문서에서는 새로운 임계값이 0.08 미만으로 하향 조정(25% 더 엄격해짐)되었다고 명확히 강조합니다 [7, 8]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Client-Side Rendering (CSR).md b/00_Raw/Client-Side Rendering (CSR).md new file mode 100644 index 00000000..fd0bf1f2 --- /dev/null +++ b/00_Raw/Client-Side Rendering (CSR).md @@ -0,0 +1,20 @@ +# [[Client-Side Rendering (CSR)]] + +## 📌 Brief Summary +Client-Side Rendering (CSR)은 브라우저가 서버로부터 최소한의 빈 HTML 껍데기와 JavaScript 번들을 전달받은 후, 클라이언트 환경에서 JavaScript를 실행하여 동적으로 UI와 콘텐츠를 렌더링하는 웹 아키텍처 방식입니다 [1]. 전체 페이지 새로고침 없이 빠르고 매끄러운 단일 페이지 애플리케이션(SPA)을 구현할 수 있어 상호작용이 잦은 서비스에 적합하지만, 초기 로드 속도와 검색 엔진 최적화(SEO) 측면에서는 치명적인 한계와 취약점을 가집니다 [2-4]. + +## 📖 Core Content +- **작동 메커니즘:** 사용자가 웹페이지를 요청하면 서버는 콘텐츠가 거의 없는 빈 HTML 문서(예: `
`)를 반환합니다 [5, 6]. 브라우저가 해당 HTML에 포함된 JavaScript 파일을 모두 다운로드하고 구문 분석 및 실행을 완료한 후에야 비로소 실제 UI와 콘텐츠가 화면에 그려집니다 [1, 6, 7]. +- **주요 장점:** 서버의 렌더링 연산 부담을 브라우저로 분산시켜 서버 부하를 줄일 수 있습니다 [3]. 페이지를 넘길 때마다 전체를 새로고침할 필요 없이 고도로 상호작용적인 앱 유사(App-like) 인터페이스를 제공하므로, 검색 노출이 필요 없는 사용자 대시보드, 관리자 패널, 내부 도구 등의 환경에 최적화되어 있습니다 [1-3]. +- **성능 및 사용자 경험(UX) 한계:** JavaScript가 다운로드 및 실행되기 전까지 사용자는 빈 화면이나 로딩 화면만 보게 되므로 초기 로딩 속도가 느립니다 [3]. 특히, 무거운 JavaScript 번들의 크기와 하이드레이션(Hydration) 지연은 모바일 환경 등에서 Largest Contentful Paint (LCP)와 Interaction to Next Paint (INP) 같은 Core Web Vitals 지표에 치명적인 악영향을 미칠 수 있습니다 [8-11]. +- **SEO 및 인덱싱(크롤링) 문제:** 전통적인 검색 엔진 크롤러(예: Googlebot) 및 AI 에이전트는 초기에 반환된 빈 HTML만을 확인하여 콘텐츠가 없다고 판단하기 쉽습니다 [6, 12]. 크롤러가 JavaScript를 실행하는 두 번째 인덱싱 단계(Two-wave indexing)에 들어가더라도, 렌더링 대기열에서 며칠 또는 몇 주가 지연될 수 있으며, 시간 초과 오류로 콘텐츠가 아예 누락될 위험도 커 SEO 랭킹 하락과 유기적 트래픽 급감의 주원인이 됩니다 [4, 7, 13-15]. +- **보안의 복잡성:** 애플리케이션 로직이 클라이언트로 이동함에 따라, 부적절하게 처리된 동적 콘텐츠는 크로스 사이트 스크립팅(XSS) 공격에 노출되기 쉽습니다. 따라서 API 통신에 대한 안전한 인증과 강력한 콘텐츠 보안 정책(CSP) 헤더 적용이 필수적입니다 [16, 17]. +- **최적화 권장 사항:** CSR의 성능 문제를 최소화하기 위해 동적 임포트(Dynamic imports)와 라우트 기반 코드 스플리팅(Route-based code splitting)을 적용하여 초기 로딩에 필요한 JS 번들 크기를 줄여야 합니다 [18, 19]. 또한 SEO와 초기 성능이 중요한 퍼블릭 페이지의 경우 CSR을 단독으로 사용하기보다는 Server-Side Rendering (SSR)이나 Static Site Generation (SSG) 방식과 결합하는 하이브리드 아키텍처 채택이 적극 권장됩니다 [20-22]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Server-Side Rendering (SSR)]], [[Single Page Application (SPA)]], [[Search Engine Optimization (SEO)]], [[Core Web Vitals]] +- **Projects/Contexts:** [[React Router 기반의 중첩 라우트 및 코드 스플리팅 최적화 전략]], [[Next.js 또는 Remix를 활용한 E-commerce SEO 마이그레이션 적용 사례]] +- **Contradictions/Notes:** 소스 내에서 CSR은 서버 연산을 거치지 않아 정적 자산 로딩 시 "엄청나게 빠른(Lightning-fast) 첫 콘텐츠 페인트(FCP)와 매끄러운 TTI"를 제공할 수 있다고 언급되지만[23], 실제 프로덕션 환경의 무거운 JS 번들에서는 렌더링 블로킹 및 하이드레이션 지연으로 인해 오히려 FCP와 LCP 지표가 심각하게 저하된다고 경고하는 등 최적화 수준에 따라 성능 결과가 상충하게 나타납니다[11, 24]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Core Web Vitals.md b/00_Raw/Core Web Vitals.md new file mode 100644 index 00000000..516df515 --- /dev/null +++ b/00_Raw/Core Web Vitals.md @@ -0,0 +1,34 @@ +# [[Core Web Vitals]] + +## 📌 Brief Summary +Core Web Vitals는 웹사이트의 실제 사용자 경험을 객관적으로 측정하기 위해 Google이 설정한 표준화된 성능 지표입니다 [1]. 2025년 기준, 이 지표는 주로 페이지의 로딩 성능을 나타내는 LCP, 상호작용의 반응성을 측정하는 INP, 그리고 시각적 안정성을 평가하는 CLS로 구성됩니다 [1-3]. 이 지표들은 Google의 SEO(검색 엔진 최적화) 순위 알고리즘에 직접적으로 반영되며, 웹사이트의 전환율과 이탈률 등 핵심 비즈니스 성과에 막대한 영향을 미칩니다 [4-7]. + +## 📖 Core Content +* **핵심 지표 및 2025년 기준 임계값:** + * **LCP (Largest Contentful Paint):** 뷰포트 내에서 가장 큰 콘텐츠 요소(주로 히어로 이미지나 큰 텍스트 블록)가 화면에 표시되는 데 걸리는 시간을 측정합니다 [3, 8, 9]. 사용자가 페이지의 주요 내용을 인식하는 속도를 뜻하며, 일반적으로 2.5초 미만이어야 "좋음(Good)"으로 평가됩니다 [3, 10, 11]. + * **INP (Interaction to Next Paint):** 2025년에 기존의 FID(First Input Delay)를 공식적으로 대체한 지표로, 클릭이나 탭 등 사용자의 모든 상호작용부터 브라우저가 시각적 피드백(다음 프레임)을 렌더링하기까지의 전체 지연 시간을 포괄적으로 측정합니다 [2, 12, 13]. 일반적으로 200ms 미만을 유지해야 합니다 [10, 11, 13]. + * **CLS (Cumulative Layout Shift):** 페이지 로드 중 텍스트나 버튼 등이 예기치 않게 이동하는 현상을 측정하여 시각적 안정성을 평가합니다 [8, 14]. 0.1 미만의 점수를 받아야 사용자에게 쾌적한 경험을 제공하는 것으로 간주됩니다 [11, 14, 15]. + * **FCP (First Contentful Paint):** 첫 번째 텍스트나 이미지가 화면에 그려지는 시점을 측정하여 초기 로딩 체감 속도를 확인합니다 [16]. + +* **비즈니스 및 SEO에 미치는 영향:** + * Core Web Vitals는 Google의 페이지 경험(Page Experience) 알고리즘에서 약 25-30%의 순위 가중치를 가지는 강력한 SEO 랭킹 요소입니다 [6]. + * 성능이 "나쁨"에서 "좋음"으로 전면 개선될 경우, 평균 전환율이 25% 증가하고 이탈률이 35% 감소하며 사용자당 수익이 30% 향상되는 등 즉각적인 비즈니스 ROI를 창출합니다 [7, 17]. + * 페이지 로드가 1초 지연될 경우 전환율이 최대 7%까지 감소할 수 있으므로 강력한 최적화가 필수적입니다 [5, 18]. + +* **성능 최적화 전략 (Optimization Strategies):** + * **LCP 최적화:** WebP나 AVIF 같은 차세대 이미지 포맷을 사용하고, 정적 자산에 CDN을 활용하며, 서버 응답 시간(TTFB)을 단축해야 합니다 [8, 14, 19]. React와 같은 프레임워크를 사용할 경우 SSR(Server-Side Rendering)을 도입하여 브라우저에 완성된 HTML을 빠르게 전달해야 합니다 [20, 21]. + * **INP 최적화:** JavaScript 실행 시간 축소가 가장 중요합니다. 무거운 연산은 Web Workers로 오프로드하고, 메인 스레드를 차단하는 긴 작업(Long Tasks)은 50ms 이하의 작은 단위로 쪼개야 합니다 [12, 13, 22, 23]. 또한, 사용하지 않는 서드파티 스크립트를 제거하고 코드 스플리팅(Code Splitting) 및 지연 로딩(Lazy Loading)을 적용하는 것이 권장됩니다 [24, 25]. + * **CLS 최적화:** 모든 이미지와 동영상 요소에 명시적인 너비 및 높이(width/height) 속성을 지정하고, 동적 광고나 임베드 콘텐츠가 로드될 공간을 CSS로 미리 확보해야 합니다 [14, 16, 26]. 폰트 로딩 시 텍스트 깜빡임이나 레이아웃 이동을 방지하기 위해 `font-display: swap` 또는 `optional`을 사용하며, 애니메이션 시에는 레이아웃 재계산을 유발하지 않도록 `transform` 속성을 활용합니다 [27-29]. + +* **테스트 및 모니터링 도구:** + * 개별 페이지에 대한 빠른 실험실/필드 데이터 확인 및 최적화 추천을 받기 위해 Google PageSpeed Insights를 사용합니다 [30]. + * 개발 및 디버깅 목적으로는 Chrome DevTools에 내장된 Lighthouse 도구를 활용하여 병목 현상을 파악합니다 [31, 32]. + * 실제 사용자 모니터링(RUM)을 위해서는 Google Search Console의 Core Web Vitals 리포트를 통해 웹사이트 전체의 성능을 지속적으로 추적하고, GTmetrix나 Datadog RUM 등을 함께 활용할 수 있습니다 [32-34]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[LCP (Largest Contentful Paint)]], [[INP (Interaction to Next Paint)]], [[CLS (Cumulative Layout Shift)]], [[SEO]], [[Web Performance Optimization]], [[Server-Side Rendering (SSR)]] +- **Projects/Contexts:** [[Google Page Experience 2025]], [[React SEO Guide]] +- **Contradictions/Notes:** 2025년 기준 Core Web Vitals의 "좋음(Good)" 임계값과 관련하여 소스 간 의견 충돌이 존재합니다. 대다수의 소스는 기존 기준인 LCP < 2.5초, INP < 200ms, CLS < 0.1을 유지한다고 명시하지만 [1, 3, 10, 11, 13], 일부 소스는 2025년에 기준이 더욱 엄격해져 LCP < 2.0초, INP < 150ms, CLS < 0.08, FCP < 1.5초를 충족해야 한다고 주장합니다 [35]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Design-to-Code Workflow.md b/00_Raw/Design-to-Code Workflow.md new file mode 100644 index 00000000..8c79b909 --- /dev/null +++ b/00_Raw/Design-to-Code Workflow.md @@ -0,0 +1,19 @@ +# [[Design-to-Code Workflow]] + +## 📌 Brief Summary +Design-to-Code Workflow는 Figma와 같은 디자인 도구에서 정의된 디자인 결정(색상, 타이포그래피, 간격 등)을 React 등의 프론트엔드 환경에서 사용할 수 있는 실제 코드로 매끄럽게 변환하고 동기화하는 자동화 및 협업 파이프라인을 의미합니다 [1, 2]. 이 워크플로우는 디자인 토큰(Design Tokens)을 단일 진실 공급원(Single source of truth)으로 활용하여 디자이너와 개발자 간의 간극을 좁히고 수동 작업으로 인한 오류를 방지합니다 [3, 4]. 최신 프론트엔드 아키텍처에서는 코드 기반 컴포넌트 연동과 CI/CD 자동화 툴을 결합하여 디자인의 일관성을 보장하고 확장성을 극대화합니다 [5-7]. + +## 📖 Core Content +* **디자인 토큰(Design Tokens)의 추출 및 중앙 집중화:** 디자인 툴(예: Figma의 Tokens Studio 플러그인 등)에서 내린 디자인 결정은 JSON이나 YAML 형태의 토큰으로 구조화 및 추출됩니다 [2]. 이는 플랫폼과 독립적인 데이터로, 디자인 도구와 코드베이스가 소통할 수 있는 기계 가독형 포맷을 제공합니다 [2, 8]. +* **스타일 변환 및 테마 자동화 엔진:** Style Dictionary와 같은 도구는 플랫폼에 구애받지 않는 토큰 JSON을 읽어들여, React 애플리케이션을 위한 CSS 변수(CSS Variables)나 JavaScript/TypeScript 테마 객체(styled-components 등)로 자동 생성합니다 [9-11]. 이를 통해 라이트/다크 모드와 같은 동적 테마를 수동 코딩 없이 일관되게 구축할 수 있습니다 [10, 12]. +* **코드 기반 컴포넌트(Code-Backed Components) 활용:** 전통적인 핸드오프 방식의 한계를 극복하기 위해, UXPin Merge와 같은 도구를 활용하여 실제 코드 레포지토리(Git)에 있는 React 컴포넌트를 디자인 툴에서 직접 불러와 프로토타이핑을 진행합니다 [4, 6]. 디자인 도구 내에서 개발과 동일한 컴포넌트와 토큰을 사용하므로 100% 동기화가 유지됩니다 [6, 13]. +* **CI/CD를 통한 파이프라인 자동화:** 단일 진실 공급원인 토큰 저장소(Version Control)에 변경 사항이 커밋되면, CI/CD 파이프라인이 자동으로 플랫폼별 스타일 파일을 생성하고 회귀 테스트를 거쳐 스테이징/프로덕션 환경에 배포합니다 [7, 14]. +* **AI 및 에이전트 기반 스펙 생성:** Uber의 uSpec 시스템과 같은 사례에서는 AI 에이전트와 Figma Console MCP를 연동하여, 디자인 파일 내의 컴포넌트 계층, 토큰 매핑, 변수 모드를 분석해 개발용 스펙 문서를 단 몇 분 만에 자동 생성합니다 [15-17]. 이는 단순한 토큰 변환을 넘어 디자인 의도를 엔지니어링 구현 스펙으로 직결시키는 고도화된 워크플로우를 보여줍니다 [18, 19]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Design Tokens]], [[Style Dictionary]], [[Dynamic Theming]], [[Component-Based Design]] +- **Projects/Contexts:** [[React]], [[styled-components]], [[UXPin Merge]], [[Uber's uSpec]] +- **Contradictions/Notes:** 전통적인 디자인-개발 협업 방식에서는 디자이너가 목업을 만들고 개발자가 수동으로 값을 하드코딩하여 코드로 옮겼기 때문에 지속적인 디자인 드리프트(Design Drift)와 오류가 발생했으나, 최신 Design-to-Code 파이프라인은 디자인 토큰과 자동화를 통해 이러한 격차와 비효율을 원천적으로 제거합니다 [4, 20]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/E-commerce 랜딩 페이지 전환율 개선 및 이탈률 감소(CRO).md b/00_Raw/E-commerce 랜딩 페이지 전환율 개선 및 이탈률 감소(CRO).md new file mode 100644 index 00000000..49c01571 --- /dev/null +++ b/00_Raw/E-commerce 랜딩 페이지 전환율 개선 및 이탈률 감소(CRO).md @@ -0,0 +1,20 @@ +# [[E-commerce 랜딩 페이지 전환율 개선 및 이탈률 감소(CRO)]] + +## 📌 Brief Summary +E-commerce 랜딩 페이지의 전환율 최적화(CRO) 및 이탈률 감소는 명확성, 신뢰성, 그리고 전환에 집중된 사용자 경험(UX) 설계를 통해 이루어집니다. 2025년의 최신 웹 디자인 접근법은 주의를 분산시키는 요소를 제거하고 단일 콜투액션(CTA)에 집중하며, 로딩 속도와 모바일 환경을 최적화하는 데 중점을 둡니다. 여기에 AI 기반의 개인화, 마이크로 인터랙션, 그리고 강력한 신뢰 구축 요소(Trust Signals)를 결합하여 사용자의 구매 마찰을 줄이고 비즈니스 수익을 극대화할 수 있습니다. + +## 📖 Core Content +* **단일 목표와 전환 중심의 미니멀리즘:** 랜딩 페이지는 여러 경쟁적인 동작을 유도하기보다 단일하고 명확한 CTA에 집중할 때 전환율이 22% 더 높게 나타납니다 [1]. 풍부한 여백(Whitespace)을 활용하고 명확한 시각적 계층 구조를 갖춘 미니멀리스트 디자인은 복잡하고 밀집된 레이아웃보다 전환율에서 19% 더 우수한 성과를 보입니다 [2]. +* **성능 최적화 및 모바일 퍼스트 설계:** 랜딩 페이지 방문의 68% 이상이 모바일 기기에서 발생하므로 모바일에 최적화된 레이아웃은 필수적입니다 [3]. 1초의 페이지 로딩 지연은 전환율을 7% 감소시킬 수 있으며 [4, 5], 3초 이상의 로딩은 이탈률을 32% 증가시킵니다 [6]. 한 럭셔리 패션 브랜드(Allbirds)는 점진적 웹 앱(PWA) 기술을 도입하여 페이지 로딩 속도를 89% 개선했으며, 그 결과 장바구니 이탈률 43% 감소 및 모바일 전환율 156% 증가라는 성과를 거두었습니다 [7, 8]. +* **사용자 마찰 감소와 폼(Form) 간소화:** 다단계 결제 흐름에서 진행 표시기를 제공하고 인라인 유효성 검사를 통해 오류를 즉시 수정할 수 있게 하면 사용자의 불확실성을 줄일 수 있습니다 [9]. 특히 입력 폼의 필드를 하나 추가할 때마다 전환율이 약 11%씩 감소하므로, 반드시 필요한 정보만 요구하여 마찰을 최소화해야 합니다 [10]. +* **AI 기반 개인화(Personalization):** 사용자의 행동, 위치, 기기 유형 등에 따라 동적으로 제품 추천, 가격, 네비게이션을 조정하는 적응형 UX(Adaptive UX)를 적용할 수 있습니다 [11]. 예측 세분화(Predictive segmentation)를 활용한 AI 개인화 도구는 전환율을 최대 50%까지 향상시킬 수 있습니다 [12]. +* **신뢰 구축 요소(Trust Signals) 강화:** 결제 시 투명한 가격 정책(숨겨진 수수료 제거)과 SSL 인증서, 보안 배지 등을 제공하여 사용자의 의심을 제거해야 합니다 [13]. 실제 고객 리뷰, 고객 수, 파트너 로고 등의 사회적 증거(Social Proof)는 전환율을 34% 끌어올리고 인지된 신뢰도를 42% 증가시킵니다 [5]. +* **몰입형 시각 자료와 동영상 활용:** 360도 제품 사진이나 AR/VR 요소를 도입해 정적인 페이지를 역동적으로 만들 수 있습니다 [7, 14]. 짧은 모션 비디오나 애니메이션 히어로 섹션은 페이지 체류 시간을 27% 향상시킵니다 [2]. 또한, 모바일 사용자에게 적합한 틱톡(TikTok) 스타일의 세로형 숏폼 비디오나 라이브 비디오를 추가하면 더 높은 참여도를 유도할 수 있습니다 [15, 16]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Core Web Vitals 최적화]], [[모바일 퍼스트 디자인(Mobile-First Design)]], [[시각적 계층 구조(Visual Hierarchy)]], [[AI 개인화 및 적응형 UX]] +- **Projects/Contexts:** [[Allbirds PWA 기반 E-commerce 재설계 사례]], [[구독 박스 서비스의 이탈률 감소(Churn Mitigation) 사례]] +- **Contradictions/Notes:** 많은 기능과 콘텐츠를 한 화면에 욱여넣는 전통적인 '여행 가방 채우기(stuffing a suitcase)' 방식은 인지적 부하를 높여 전환율을 떨어뜨립니다. 현대 웹 아키텍처는 이를 지양하고, 전략적 여백과 명확한 헤딩을 사용하여 사용자를 논리적으로 안내하는 '빌보드(billboard)' 모델을 필수적으로 요구합니다 [17]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Explicit Contracts.md b/00_Raw/Explicit Contracts.md new file mode 100644 index 00000000..22d8aa66 --- /dev/null +++ b/00_Raw/Explicit Contracts.md @@ -0,0 +1,22 @@ +# [[Explicit Contracts]] + +## 📌 Brief Summary +명시적 계약(Explicit Contracts)은 재사용 가능한 React 컴포넌트를 설계할 때 지켜야 할 주요 원칙 중 하나로, 컴포넌트의 명확한 API를 정의하는 것을 의미합니다 [1]. 이는 컴포넌트가 입력으로 받는 것(props), 반환하는 것(이벤트/콜백), 그리고 절대 하지 말아야 할 행동(예: 부모 상태의 직접 변형)을 명시적으로 규정하는 것입니다 [1]. 이러한 강력한 계약은 애플리케이션 내에서 예기치 않은 동작을 방지하고 컴포넌트의 예측 가능성과 재사용성을 높이는 역할을 합니다 [1, 2]. + +## 📖 Core Content +- **컴포넌트 설계의 핵심 규칙:** 명시적 계약은 단일 책임(Single Responsibility), 상속보다 합성(Composition Over Inheritance), 접근성 우선(Accessibility First)과 함께 재사용 가능한 React 컴포넌트를 구축하기 위한 4가지 황금 법칙 중 하나로 강조됩니다 [1]. +- **명확한 API 설계 (Props & Events):** + - **Props (프로퍼티):** 컴포넌트의 API는 오용하기 어렵게 직관적으로 설계되어야 합니다. 구현 방식이 아닌 의도(intent)를 설명하는 용어로 프로퍼티를 명명해야 합니다(예: `showModalNow` 대신 `isOpen` 사용). 또한, 프로퍼티의 개수를 최소화하고 안전한 기본값을 제공하는 것이 좋습니다 [2]. + - **Events (이벤트):** 이벤트 역시 계약의 일부입니다. 컴포넌트가 외부로 상태를 전달해야 할 때(예: '사용자가 확인을 클릭함'), 잘 명명된 콜백을 사용하고 항상 일관되고 유용한 데이터를 페이로드로 전달해야 합니다 [2]. +- **상태의 경계와 성능:** 명확한 계약은 제어 컴포넌트(Controlled)와 비제어 컴포넌트(Uncontrolled)의 상태 소유권(state ownership)을 분명히 설정합니다 [2]. 명확하게 정의된 계약은 우발적인 리렌더링의 위험을 낮추기 때문에 성능 향상의 출발점이 되기도 합니다 [3]. +- **대규모 프론트엔드 아키텍처에서의 명시적 계약:** + - 모노레포(Monorepo)와 같이 확장 가능한 아키텍처에서 모듈 간의 의존성은 명시적 계약을 통해 한 방향으로만 흘러야 합니다 [4]. + - 기능 분할 설계(Feature-Sliced Design, FSD)에서도 슬라이스 경계마다 명시적인 공개 API(Public API)를 강제합니다. 이를 통해 내부 파일의 딥 임포트(deep import)를 막고 우발적인 결합(accidental coupling)을 크게 줄일 수 있습니다 [5, 6]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Reusable UI Components]], [[Component API Design]], [[Feature-Sliced Design]] +- **Projects/Contexts:** [[React Component Architecture]], [[Monorepo Architecture]] +- **Contradictions/Notes:** 소스에 명시적 계약의 개념이 컴포넌트 수준의 설계 원칙뿐만 아니라, 대규모 모노레포 환경에서의 패키지 간 의존성을 관리하는 아키텍처 원칙으로도 일관되게 적용됨을 보여줍니다 [1, 4]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Google Page Experience 2025.md b/00_Raw/Google Page Experience 2025.md new file mode 100644 index 00000000..b7233e5a --- /dev/null +++ b/00_Raw/Google Page Experience 2025.md @@ -0,0 +1,22 @@ +# [[Google Page Experience 2025]] + +## 📌 Brief Summary +Google Page Experience 2025는 검색 결과에서 웹사이트 순위를 매기는 방식을 재편하는 구글의 핵심 알고리즘 업데이트입니다 [1]. 이 업데이트의 중심에는 웹사이트의 로딩 속도, 시각적 안정성, 상호작용성을 측정하는 'Core Web Vitals'가 자리 잡고 있습니다 [1]. 특히 2025년 업데이트의 가장 큰 변화는 기존의 첫 입력 지연(FID) 지표를 공식적으로 폐지하고, 전반적인 상호작용성을 보다 포괄적으로 측정하는 INP(Interaction to Next Paint)를 도입한 것입니다 [1, 2]. 구글은 페이지 경험이 주요 랭킹 요소임을 강조하고 있으며, 이를 충족하는 사이트는 검색 가시성 향상과 더불어 방문자 전환율 및 만족도를 크게 높일 수 있습니다 [3, 4]. + +## 📖 Core Content +* **검색 랭킹 및 비즈니스에 미치는 영향:** 구글의 페이지 경험(Page Experience) 알고리즘은 경쟁이 치열한 검색어에 대해 Core Web Vitals(CWV)를 랭킹 가중치의 25~30% 수준으로 통합하여 반영합니다 [5, 6]. 이 기준을 통과하는 웹사이트는 검색 결과에서 8~15%의 가시성 향상을 경험할 수 있으며, 향상된 UX를 바탕으로 사용자 이탈률을 줄이고 전환율을 높일 수 있습니다 [4-6]. + +* **2025년 핵심 지표 (Core Web Vitals):** + * **[[INP (Interaction to Next Paint)]]:** 2025년 업데이트의 가장 중대한 변화로, 기존의 FID(First Input Delay)를 대체했습니다 [1, 2]. 사용자가 상호작용(클릭, 탭, 키보드 입력 등)을 시도한 후 브라우저가 다음 프레임을 표시할 때까지 걸리는 전체 지연 시간을 측정하여 웹사이트의 반응성을 평가합니다 [2]. + * **[[LCP (Largest Contentful Paint)]]:** 페이지의 기본 주요 콘텐츠가 사용자에게 온전히 표시되는 데 걸리는 로딩 성능을 측정합니다 [7]. + * **[[CLS (Cumulative Layout Shift)]]:** 페이지 로딩 중 이미지나 텍스트 등 시각적 요소가 예기치 않게 이동하는 정도를 측정하여 레이아웃의 시각적 안정성을 평가합니다 [8]. + +* **페이지 경험 최적화 전략:** 구글 페이지 경험 2025 표준에 부합하기 위해 기업과 개발자는 다방면의 기술적 조치를 취해야 합니다. 주요 이미지에 차세대 포맷(WebP, AVIF) 적용 및 압축을 진행하고, 서버 응답 시간을 개선해야 합니다 [9, 10]. 또한 INP 지표 개선을 위해 자바스크립트 실행 시간을 줄이거나 비핵심 스크립트 로드를 지연시키고, CLS 방지를 위해 이미지나 동영상에 고정된 크기(Dimensions)를 할당하는 조치가 필요합니다 [11, 12]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Core Web Vitals]], [[INP (Interaction to Next Paint)]], [[LCP (Largest Contentful Paint)]], [[CLS (Cumulative Layout Shift)]], [[Search Engine Optimization (SEO)]] +- **Projects/Contexts:** [[웹 성능 최적화 (Web Performance Optimization)]], [[프론트엔드 성능 최적화 (Frontend Performance Optimization)]], [[홈페이지 UX 개선]] +- **Contradictions/Notes:** 소스 간 2025년 Core Web Vitals의 '우수(Good)' 임계값에 대한 세부적인 수치 차이가 존재합니다. 일부 소스는 기존 구글 가이드라인을 인용하여 LCP 2.5초 이내, CLS 0.1 미만, INP 200ms 미만을 우수 기준으로 제시합니다 [2, 7, 8]. 반면, 다른 소스는 2025년에 임계값이 더욱 엄격해져 LCP는 2.0초 미만, CLS는 0.08 미만, INP는 150ms 미만을 충족해야 한다고 명시하고 있습니다 [13-15]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Hydration Mismatch.md b/00_Raw/Hydration Mismatch.md new file mode 100644 index 00000000..31c888dc --- /dev/null +++ b/00_Raw/Hydration Mismatch.md @@ -0,0 +1,24 @@ +# [[Hydration Mismatch]] + +## 📌 Brief Summary +Hydration Mismatch는 서버에서 렌더링된 HTML 콘텐츠와 클라이언트 측에서 기대하거나 생성하는 콘텐츠가 서로 다를 때 발생하는 오류 현상입니다 [1, 2]. 특히 React 서버 컴포넌트(RSC) 환경이나 CSS-in-JS(예: styled-components)를 사용할 때, 서버와 클라이언트 간에 다른 동적 데이터나 CSS 클래스 이름이 생성될 경우 흔하게 발생합니다 [2, 3]. 이를 방지하기 위해서는 서버와 클라이언트 경계에서 일관된 렌더링 결과물과 안정적인 해시 값을 생성하도록 구성해야 합니다 [3, 4]. + +## 📖 Core Content +- **Hydration의 원리 및 Mismatch 발생 조건** + React에서 Hydration은 서버에서 렌더링되어 전달된 정적 HTML에 이벤트 리스너와 상태(State)를 연결하여 상호작용 가능한 UI로 만드는 과정입니다 [1]. Next.js 15의 App Router와 같은 구조에서는 이 과정이 주로 클라이언트 컴포넌트(Client Components)에서만 발생합니다 [1]. Hydration Mismatch는 서버가 생성한 콘텐츠와 클라이언트가 렌더링 시 기대하는 콘텐츠가 다를 때 나타나며, 타임스탬프와 같이 서버와 클라이언트에서 각기 다르게 계산되는 동적 데이터가 대표적인 원인입니다 [2]. + +- **CSS-in-JS(Styled Components) 환경에서의 위험성** + Next.js App Router에서 Styled Components가 작동하도록 Style Registry 패턴을 사용할 경우, 서버와 클라이언트가 서로 다른 CSS 클래스 이름을 생성하면 Hydration Mismatch가 발생할 위험이 있습니다 [3]. 또한, 다크 모드와 라이트 모드 간에 테마를 전환할 때 안정적인 클래스 이름 해시(hash)가 유지되지 않으면 동일한 문제가 발생할 수 있습니다 [4]. + +- **해결 및 완화 전략** + - **동적 데이터 렌더링 처리:** 클라이언트와 서버에서 값이 달라질 수 있는 동적 요소는, 클라이언트에서 컴포넌트가 마운트된 이후에 렌더링되도록 처리하여 불일치를 피해야 합니다 [2]. + - **컴파일러 옵션 활용:** Styled Components를 사용할 경우 `next.config.js`에서 `styledComponents` 컴파일러 옵션을 활성화해야 합니다. 이는 서버와 클라이언트 경계에서 일관된 CSS 클래스 이름 생성을 보장하여 Hydration Mismatch를 완화합니다 [3]. + - **안정적인 테마 객체 전달:** 테마 전환 시 Hydration Mismatch를 방지하려면, `createTheme` 등을 활용하여 생성된 테마 객체를 `ThemeProvider`에 제대로 전달함으로써 테마 간 전환에도 클래스 이름 해시가 안정적으로 유지되도록 해야 합니다 [4, 5]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[React Server Components (RSC)]], [[Styled Components]], [[Next.js App Router]], [[CSS-in-JS]] +- **Projects/Contexts:** [[Next.js 15 기반 애플리케이션의 클라이언트 및 서버 렌더링 구성]], [[Styled Components의 글로벌 스타일 및 테마 구현]] +- **Contradictions/Notes:** 소스 간의 모순점은 없으며, 동적 렌더링이나 런타임 CSS 생성 시 발생하는 서버-클라이언트 불일치를 해결하기 위해 컴파일러 단의 설정(예: `styledComponents` 활성화)이나 정적이고 안정적인 클래스 네임 사용이 공통적인 해결책으로 제시됩니다 [2, 3]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/INP (Interaction to Next Paint).md b/00_Raw/INP (Interaction to Next Paint).md new file mode 100644 index 00000000..ce85b7df --- /dev/null +++ b/00_Raw/INP (Interaction to Next Paint).md @@ -0,0 +1,40 @@ +# [[INP (Interaction to Next Paint)]] + +## 📌 Brief Summary +INP(Interaction to Next Paint)는 사용자가 웹페이지와 처음 상호작용(클릭, 탭, 키보드 입력 등)한 시점부터 브라우저가 시각적인 반응(다음 프레임)을 화면에 표시할 때까지 걸리는 전체 상호작용 지연 시간을 측정하는 Core Web Vitals 지표입니다 [1, 2]. 2024~2025년을 기점으로 기존의 FID(First Input Delay)를 공식적으로 대체하였으며, 첫 입력 지연만 측정하던 FID와 달리 입력 지연(Input Delay), 처리 시간(Processing Time), 표시 지연(Presentation Delay)을 모두 포괄하여 측정하므로 실제 사용자 경험을 더 정확하게 반영합니다 [3-7]. + +## 📖 Core Content +**INP의 중요성 및 비즈니스 영향** +INP는 Google의 검색 순위 알고리즘(Page Experience)에 직접적인 영향을 미치는 핵심 성과 지표입니다 [4, 8, 9]. INP 기준을 충족하지 못해 사이트 상호작용이 지연될 경우 사용자 참여도가 23% 감소하며 검색 크롤링 우선순위와 검색 순위가 하락하게 됩니다 [8, 10]. FID가 INP로 교체됨에 따라, 2025년 웹 성능 최적화에서는 페이지 내의 모든 버튼, 스크롤, 탭 상호작용의 응답성을 개선하는 것이 필수적이 되었습니다 [11]. + +**평가 기준 (Thresholds)** +Google은 INP 성능을 평가하는 구체적인 임계값을 제공합니다. +* **Good (우수):** 200ms 이하 (일부 기준에서는 150ms 미만을 요구하기도 함) [5, 6, 11, 12]. +* **Needs Improvement (개선 필요):** 200ms ~ 500ms 사이 [6, 13]. +* **Poor (불량):** 500ms 초과 [5, 6]. + +**INP 저하의 주요 원인** +INP 점수가 나빠지는 주된 이유는 브라우저의 메인 스레드(Main thread)를 차단하는 요소들 때문입니다. +* **긴 JavaScript 작업:** 메인 스레드를 50ms 이상 차단하는 무거운 동기식 처리나 복잡한 계산 [7, 14]. +* **과도한 스크립트 실행:** 최적화되지 않은 타사(Third-party) 스크립트 실행이나 거대한 JavaScript 번들, 부족한 코드 분할(Code splitting) [7, 14, 15]. +* **무거운 애니메이션:** 레이아웃이나 페인트를 트리거하는 과도한 CSS 애니메이션 연산 [7, 14]. + +**INP 최적화 전략** +웹 애플리케이션의 INP를 향상시키려면 다음과 같은 기술적 최적화가 필요합니다. +* **작업 청크 분할:** `setTimeout` 등을 사용하여 50ms 미만의 청크로 긴 작업을 쪼개어 브라우저가 다른 렌더링 작업을 수행할 수 있도록 제어권을 양보(Yield)해야 합니다 [1, 5, 16, 17]. +* **Web Workers 도입:** 무거운 CPU 연산을 메인 스레드에서 분리하여 백그라운드(Web Worker)에서 처리하게 합니다 [1, 18]. +* **스크립트 지연 및 최소화:** 렌더링에 필수적이지 않은 타사 스크립트 로딩을 지연(defer)시키고 코드 분할(Code splitting)과 지연 로딩(Lazy loading)을 적용합니다 [1, 19, 20]. +* **이벤트 핸들러 최적화:** Debounce 및 Throttle 기법을 적용하여 이벤트 실행 빈도를 제어합니다 [1, 21]. +* **비핵심 작업 후순위 처리:** `requestIdleCallback`을 사용하여 중요하지 않은 작업은 브라우저 유휴 시간에 처리합니다 [22, 23]. +* **애니메이션 최적화:** 애니메이션 실행 시 브라우저 레이아웃을 다시 계산하지 않도록 GPU 가속을 활용하는 `transform` 및 `opacity` 속성만 사용합니다 [24, 25]. + +**측정 및 모니터링 도구** +INP를 비롯한 Core Web Vitals를 테스트하고 모니터링하기 위해 Google PageSpeed Insights(빠른 진단), Lighthouse(긴 JS 작업 등 기술적 디버깅에 유용), Google Search Console(실제 사용자 데이터 기반의 사이트 전체 성능 확인) 등의 도구가 권장됩니다 [9, 26-28]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Core Web Vitals]], [[FID (First Input Delay)]], [[LCP (Largest Contentful Paint)]], [[CLS (Cumulative Layout Shift)]], [[JavaScript Optimization]] +- **Projects/Contexts:** [[Google Page Experience 2025 Update]], [[Technical SEO]], [[Web Performance Optimization]] +- **Contradictions/Notes:** 2025년 기준 '우수한(Good)' INP 임계값에 대하여 소스 간 약간의 수치 차이가 존재합니다. 소스 [12]는 150ms 미만을 최적 기준으로 제시한 반면, 소스 [11], [5], [6], [29]에서는 200ms 이하를 우수한 기준으로 명시하고 있습니다. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Incremental Static Regeneration (ISR).md b/00_Raw/Incremental Static Regeneration (ISR).md new file mode 100644 index 00000000..482754ec --- /dev/null +++ b/00_Raw/Incremental Static Regeneration (ISR).md @@ -0,0 +1,27 @@ +# [[Incremental Static Regeneration (ISR)]] + +## 📌 Brief Summary +Incremental Static Regeneration (ISR)은 정적 사이트 생성(SSG)의 매우 빠른 속도와 서버 사이드 렌더링(SSR)의 최신성(freshness)을 결합한 하이브리드 웹 렌더링 전략입니다 [1]. 전체 사이트를 다시 빌드할 필요 없이 백그라운드에서 특정 정적 페이지를 런타임에 선택적으로 업데이트 및 재생성할 수 있게 해줍니다 [2-4]. 제품 카탈로그나 뉴스 사이트처럼 주기적으로 변경되는 콘텐츠를 빠르게 제공하는 데 이상적인 방식입니다 [1, 5]. + +## 📖 Core Content +**작동 프로세스** +ISR은 서버 부하를 최소화하면서도 사용자에게 빠른 페이지를 제공하기 위해 다음과 같은 단계로 작동합니다 [1]: +* 빠른 초기 제공: 캐시에서 정적 페이지를 즉시 제공하여 로딩 속도를 극대화합니다. +* 재검증(Revalidation): 설정된 재검증 기간(revalidation period)이 만료되었는지 확인합니다. +* 백그라운드 재생성: 재검증 기간이 지난 경우, 백그라운드에서 페이지를 새로 재생성(Regenerate)합니다. +* 업데이트된 페이지 제공: 재생성이 완료되면, 이후 들어오는 다음 요청부터는 업데이트된 페이지를 제공합니다. + +**성능 및 SEO 이점** +ISR 방식은 95-99%의 높은 캐시 적중률(Cache hit rate)을 보이며, 첫 바이트 도달 시간(TTFB)을 20-50ms 수준으로 단축할 수 있습니다 (전통적인 SSR의 경우 200-800ms) [1]. 서버 CPU 사용량은 백그라운드에서만 발생하므로 낮게 유지됩니다 [1]. +이러한 성능 향상은 검색 엔진 최적화(SEO) 및 코어 웹 바이탈(Core Web Vitals) 개선으로 직결됩니다 [1, 6]. 실제로 10,000개의 제품을 가진 전자상거래 사이트를 CSR에서 Next.js ISR로 마이그레이션한 사례에서는 TTFB가 50ms로 단축되고 LCP가 'Good(1.8s)' 등급으로 향상되었으며, 오가닉 트래픽이 70% 증가하는 결과를 얻었습니다 [7, 8]. + +**사용 사례 및 구현** +ISR은 매시간 또는 매일 업데이트되는 반정적(semi-static) 콘텐츠(예: 제품, 기사)에 가장 적합한 전략입니다 [5, 9]. Next.js와 같은 프레임워크를 통해 쉽게 구현할 수 있으며, 이 기능은 하이브리드 렌더링 아키텍처의 핵심을 이룹니다 [2, 8]. 실시간 데이터가 필수적인 환경이 아니라면, 인프라 비용과 로딩 시간을 절감할 수 있는 훌륭한 대안입니다 [10]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Static Site Generation (SSG)]], [[Server-Side Rendering (SSR)]], [[Time to First Byte (TTFB)]], [[Core Web Vitals]] +- **Projects/Contexts:** [[Next.js Framework]], [[E-commerce Migration Case Study]] +- **Contradictions/Notes:** 소스에 특별한 모순점은 없으나, 주의할 점으로 콘텐츠 최신화가 설정된 재검증 주기(revalidate period)만큼 지연된다는 점이 명시되어 있습니다. 따라서 주식 가격, 실시간 채팅과 같은 '완전한 실시간(Real-time)' 반영이 필요한 데이터의 경우에는 ISR보다 [[Server-Side Rendering (SSR)]] 방식이 적합합니다 [1, 11]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Kiwi.com Migration.md b/00_Raw/Kiwi.com Migration.md new file mode 100644 index 00000000..4cf3a083 --- /dev/null +++ b/00_Raw/Kiwi.com Migration.md @@ -0,0 +1,24 @@ +# [[Kiwi.com Migration]] + +## 📌 Brief Summary +Kiwi.com Migration은 웹사이트의 프론트엔드 성능을 최적화하기 위해 기존의 `styled-components`에서 `Tailwind CSS`로 스타일링 방식을 전환한 대규모 리팩토링 프로젝트입니다 [1, 2]. 긴 실행 시간(long tasks)을 최적화하는 과정에서 `styled-components`가 주요 병목 현상임을 발견한 것이 전환의 핵심 계기가 되었습니다 [1]. 이 마이그레이션을 통해 첫 입력 지연(FID) 및 상호작용 속도(INP)와 같은 코어 웹 바이탈(Core Web Vitals) 지표가 획기적으로 개선되었으며, 서버의 처리 지연 시간(Latency)을 크게 단축하는 성과를 거두었습니다 [3-6]. + +## 📖 Core Content +* **마이그레이션 배경 및 도구 선정:** 성능 병목 현상을 해결하기 위해 Griffel, Linaria 등 여러 대안을 검토했으며, 문서 품질, 성능, 커뮤니티 크기, SSR 지원 여부 등을 종합적으로 평가하여 유틸리티 우선(utility-first) 접근 방식을 제공하는 Tailwind CSS가 최종 선정되었습니다 [7, 8]. 도입 전 실시한 Lighthouse 오딧에서 특정 컴포넌트의 로드 속도가 약 26% 빨라진다는 것을 확인했습니다 [9]. +* **초기 설정 및 모노레포(다중 팀) 과제:** Kiwi.com의 리포지토리에는 두 개의 개별 팀이 각각 다른 프로젝트를 진행하고 있었습니다 [10]. 서로의 CSS 번들 크기를 부풀리지 않기 위해 PostCSS를 활용해 두 개의 별도 Tailwind 구성을 세팅했습니다 [10]. 이는 VS Code의 Tailwind CSS IntelliSense 및 Prettier 플러그인 설정에 어려움을 주었지만, 실험적 기능(`tailwindCSS.experimental.configFile`)을 통해 해결했습니다 [11, 12]. +* **마이그레이션 실행 및 크로스 브라우저 호환성:** 컴포넌트를 변환하는 과정에서 브라우저 캐싱을 활용해 페이지 로드 속도를 높이기 위해 내부(Internal) CSS에서 외부(External) CSS 방식으로 변경했습니다 [13]. 그러나 Safari iOS 14.5 미만 버전에서 flexbox의 `gap` 속성이나 `inset` 속성을 지원하지 않는 호환성 문제가 발생했습니다 [14]. 이를 해결하기 위해 Tailwind의 `matchUtilities()` 헬퍼 함수를 사용하여 `safe-inset`, `safe-space-x`와 같은 커스텀 유틸리티 플러그인을 개발해 우회 적용했습니다 [14, 15]. +* **핵심 성능 개선 결과:** + * **코어 웹 바이탈 (Core Web Vitals):** 모바일 홈페이지 기준 첫 입력 지연(FID)이 75.9% 감소했고, 다음 페인트에 대한 상호작용(INP)이 58.4% 감소했습니다 [3, 4]. 데스크톱 환경에서도 각각 37.1%, 49.7%의 감소율을 보였습니다 [3, 4]. + * **서버 CPU Wall Time (지연 시간):** Tailwind는 스타일링에 JavaScript 실행을 의존하지 않으므로 서버의 스타일 연산에 드는 CPU 처리 시간이 10.19초에서 4.79초로 52.91% 대폭 감소했습니다 [5]. +* **발견된 단점 및 한계 (Drawbacks):** + * 두 라이브러리(`styled-components`와 `Tailwind`)가 동시에 존재하는 마이그레이션 과도기에는 생성된 CSS 코드의 중복으로 인해 초기 번들 크기가 눈에 띄게 증가했습니다 [16]. + * 캡슐화된 `styled-components`와 달리 유틸리티 클래스가 여러 요소에 분산되어 있어 디버깅이 더 까다로워졌습니다 [16]. + * Tailwind는 클래스 선언 순서에 의존하므로, 동적인 클래스 구성을 관리하기 위해 `clsx` 같은 부가적인 JavaScript 라이브러리를 사용해야 하는 복잡성이 더해졌습니다 [6]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Tailwind CSS]], [[Styled Components]], [[CSS-in-JS]], [[Core Web Vitals]] +- **Projects/Contexts:** [[Kiwi.com]], [[React Performance Optimization]] +- **Contradictions/Notes:** 소스에 따르면 Tailwind CSS 도입은 전반적인 성능(Core Web Vitals 및 서버 지연 시간)과 개발 속도 향상에 크게 기여했지만 [3-6, 17], 동시에 디버깅 난이도를 높이고 특정 클래스 구성 도구(`clsx`)에 대한 의존도를 높이는 트레이드오프(단점)를 수반한다고 지적합니다 [6, 16]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/LCP (Largest Contentful Paint).md b/00_Raw/LCP (Largest Contentful Paint).md new file mode 100644 index 00000000..09a3001f --- /dev/null +++ b/00_Raw/LCP (Largest Contentful Paint).md @@ -0,0 +1,20 @@ +# [[LCP (Largest Contentful Paint)]] + +## 📌 Brief Summary +LCP(Largest Contentful Paint)는 웹페이지에서 히어로 이미지, 비디오, 큰 텍스트 블록 등 가장 큰 주요 콘텐츠 요소가 사용자의 화면에 표시되는 데 걸리는 시간을 측정하는 성능 지표입니다 [1-4]. 사용자가 페이지의 로딩 속도를 체감하는 주요 척도이며, 구글의 코어 웹 바이탈(Core Web Vitals)에서 시각적 로딩 속도와 SEO 검색 순위를 결정하는 핵심 요소로 기능합니다 [4-7]. 최적의 사용자 경험과 전환율을 유지하기 위해 2025년 기준 LCP는 2.0초(일부 기준 2.5초) 이내에 로드되어야 합니다 [1, 2, 8, 9]. + +## 📖 Core Content +- **성능 기준 및 2025년 업데이트**: 2025년 코어 웹 바이탈 업데이트에서 구글은 LCP의 '우수(Good)' 임계값을 기존 2.5초에서 2.0초 미만으로 더욱 엄격하게 조정했습니다 [1, 8, 9]. 반면, 일부 소스에서는 여전히 2.5초 이하를 적정 기준으로 안내하기도 합니다 [2, 4, 10]. LCP가 4.0초를 초과하면 '나쁨(Poor)'으로 간주되며 [10], LCP 로딩 속도가 2.0초를 넘어가면 전환율이 7% 감소하고 검색 순위에 악영향을 미칩니다 [11]. 반대로 LCP를 1초 단축하면 전환율을 15% 상승시키고 이탈률을 20% 줄일 수 있습니다 [12]. +- **주요 병목 원인(Bottlenecks)**: LCP가 지연되는 주요 원인으로는 렌더링을 차단하는 리소스(동기식으로 로드되는 CSS 및 JavaScript), 느린 서버 응답 시간(TTFB), 최적화되지 않은 대용량 이미지 포맷(500KB 이상의 PNG/JPEG 등), 그리고 클라이언트 측 렌더링(CSR) 앱에서의 하이드레이션(Hydration) 및 무거운 JavaScript 번들 처리 지연 등이 있습니다 [13, 14]. +- **LCP 최적화 전략**: + - **이미지 및 미디어 최적화**: WebP나 AVIF와 같은 차세대 이미지 포맷을 사용하여 파일 크기를 크게 줄여야 합니다 [1, 15-17]. 특히 LCP 측정 대상이 되는 첫 화면의 히어로 이미지에는 지연 로딩(Lazy Loading)을 적용하지 말고, `loading="eager"` 및 `fetchpriority="high"` 속성을 사용하여 우선적으로 로드(Preload)해야 합니다 [9, 16, 18-21]. + - **서버 응답 속도 및 리소스 전송 향상**: 글로벌 트래픽 환경에서는 CDN(콘텐츠 전송 네트워크)을 사용하여 정적 자산을 전송하고, 브라우저 및 서버 수준의 캐싱을 활성화하여 로딩 시간을 단축해야 합니다 [1, 16, 22, 23]. + - **코드 및 렌더링 최적화**: 렌더링 차단 스크립트와 중요하지 않은 자바스크립트는 지연(Defer)시키고 중요한 CSS는 인라인(Inline)으로 배치해야 합니다 [14, 24, 25]. 또한, React와 같은 프레임워크에서는 클라이언트 사이드 렌더링(CSR)에 따른 지연을 피하기 위해 서버 사이드 렌더링(SSR)이나 정적 사이트 생성(SSG)을 적용하여 완성된 HTML을 즉시 브라우저에 제공하는 것이 좋습니다 [26-28]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Core Web Vitals]], [[Server-Side Rendering (SSR)]], [[Client-Side Rendering (CSR)]], [[INP (Interaction to Next Paint)]], [[SEO (Search Engine Optimization)]] +- **Projects/Contexts:** [[Web Performance Optimization]], [[React SEO Guide]] +- **Contradictions/Notes:** 구글의 2025년 코어 웹 바이탈 업데이트를 다룬 소스에서는 LCP의 '우수' 임계값이 2.5초에서 2.0초 미만으로 강화되었다고 명시하고 있으나 [1, 8, 9], 일부 분석 및 지침 소스에서는 여전히 기존 기준인 2.5초를 목표치로 제시하고 있어 기준에 대한 혼재가 있습니다 [2, 7, 29]. 또한 비판적 콘텐츠 최적화 방식에 대해, 지연 로딩(Lazy Loading)은 전체 사이트 속도를 높이는 좋은 기법이지만 첫 화면(Above-the-fold)의 메인 콘텐츠에 적용할 경우 오히려 LCP 점수를 심각하게 훼손한다는 주의 사항이 반복적으로 강조됩니다 [18, 19, 21]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Modern Frontend Engineering Architecture.md b/00_Raw/Modern Frontend Engineering Architecture.md new file mode 100644 index 00000000..d901c157 --- /dev/null +++ b/00_Raw/Modern Frontend Engineering Architecture.md @@ -0,0 +1,33 @@ +# [[Modern Frontend Engineering Architecture]] + +## 📌 Brief Summary +현대의 프론트엔드 엔지니어링 아키텍처는 React 환경에서 개발자 경험(DX)과 브라우저의 런타임 성능 간의 균형을 맞추기 위해 지속적으로 진화하고 있습니다 [1]. 이를 위해 Tailwind CSS와 같은 빌드 타임 기반의 유틸리티 퍼스트 프레임워크와 Styled-components 같은 런타임 CSS-in-JS 패러다임이 각자의 장단점을 바탕으로 경쟁하고 있습니다 [1, 2]. 더 나아가 확장 가능하고 유지보수가 용이한 UI를 구축하기 위해 체계화된 디자인 토큰(Design Tokens) 시스템, 컴포넌트 합성(Compound Components) 패턴, 그리고 모노레포와 결합된 기능 분할 설계(Feature-Sliced Design)가 핵심적인 기반 아키텍처로 채택되고 있습니다 [3-6]. + +## 📖 Core Content + +* **스타일링 패러다임: Styled-components vs Tailwind CSS** + * **Styled-components (CSS-in-JS):** 컴포넌트와 스타일을 함께 배치하는 방식(Co-location)으로 훌륭한 모듈화와 개발자 경험을 제공합니다 [7-9]. props를 통해 동적인 스타일링이 매우 용이하다는 장점이 있으나 [10], 브라우저 런타임에 JavaScript를 통해 CSS를 생성 및 주입해야 하므로 성능 오버헤드가 발생할 수 있습니다 [7, 11]. 특히 React Server Components(RSC) 기반의 Next.js App Router 환경에서는 Context API를 사용할 수 없어 호환성 문제가 생길 수 있으며, 이를 해결하기 위해 Style Registry 패턴을 사용해야 합니다 [12, 13]. + * **Tailwind CSS:** 유틸리티 퍼스트(Utility-first) 접근 방식을 취하며, 빌드 타임에 실제로 사용된 CSS만 정적으로 생성하여 런타임 오버헤드가 전혀 없다는 것이 가장 큰 강점입니다 [14-16]. 실제 마이그레이션 테스트에 따르면 Styled-components에서 Tailwind CSS로 전환 시 모바일 환경에서 First Input Delay(FID)와 Interaction to Next Paint(INP) 지표가 절반 이상 대폭 감소하는 성능 개선을 보였습니다 [17-19]. 최신 v4 버전에서는 JavaScript 기반 설정을 벗어나 `@theme` 디렉티브를 사용하는 CSS-first 아키텍처로 진화했으며, Rust 기반 엔진을 도입해 빌드 속도가 10배 이상 향상되었습니다 [20-22]. + +* **확장 가능한 디자인 토큰(Design Tokens) 파이프라인** + * 디자인 토큰은 애플리케이션 전반의 시각적 속성(색상, 타이포그래피, 간격 등)을 하드코딩하지 않고 재사용 가능하도록 중앙 집중화한 데이터입니다 [23, 24]. + * 성공적인 토큰 시스템 관리를 위해서는 **세 가지 계층**으로 분리하는 것이 중요합니다. 문맥 없이 원시 값을 갖는 **기본 토큰**(Primitive Tokens, 예: `--color-blue-500`), 목적과 의도를 나타내는 **시맨틱 토큰**(Semantic Tokens, 예: `--color-primary`), 특정 컴포넌트에 한정된 **컴포넌트 토큰**으로 나눕니다 [25-27]. + * 이러한 토큰들은 Figma와 같은 디자인 툴에서 JSON 포맷으로 추출되며, Style Dictionary 등의 도구를 거쳐 플랫폼에 맞는 CSS 변수(Variables) 등으로 자동 변환되어 적용됩니다 [28-32]. + +* **재사용 가능한 UI 컴포넌트 설계 패턴** + * **아토믹 디자인(Atomic Design):** UI를 원자(Atoms), 분자(Molecules), 유기체(Organisms), 템플릿, 페이지 단위로 추상화 및 조립하여 재사용성을 높이는 기초적인 멘탈 모델입니다 [33-37]. + * **합성 컴포넌트(Compound Components):** `Accordion.Item`, `Accordion.Header`처럼 관련된 하위 컴포넌트들이 React Context를 통해 암시적으로 상태를 공유하는 패턴입니다 [4, 38, 39]. 단일 컴포넌트에 수십 개의 prop이 집중되는 문제(Prop soup)를 방지하고 사용자가 레이아웃 구조를 자유롭게 구성하도록 돕습니다 [40-43]. + * **헤드리스 컴포넌트(Headless Components):** 접근성과 동작 논리(상태 관리, 키보드 네비게이션 등)만 제공하고 마크업 및 스타일링은 전적으로 소비자에게 위임하는 패턴으로, 확장성과 유연성이 매우 높습니다 [43-45]. + * **오버라이드 패턴(Overrides Pattern):** 단일 요소의 내부 깊은 구조까지 외부에 개방하여, 사용자가 특수한 상황에 맞게 스타일이나 렌더링 컴포넌트를 완전히 대체(override)할 수 있도록 허용하는 API 패턴입니다 [46-48]. + +* **대규모 프론트엔드를 위한 모노레포와 아키텍처 (FSD)** + * 조직과 애플리케이션이 성장함에 따라 단일 레포지토리 내에서 다수의 앱과 공유 패키지 간의 의존성을 관리하는 모노레포(Monorepo) 구성이 필수적입니다. pnpm workspaces, Turborepo, Nx 등의 도구를 통해 빌드 캐싱과 파이프라인 최적화를 이룰 수 있습니다 [5, 49-51]. + * 아키텍처 관점에서는 **기능 분할 설계(Feature-Sliced Design, FSD)**가 각광받습니다. 코드베이스를 Shared, Entities, Features, Widgets, Pages, App 등으로 나누고 의존성(Dependency)이 한 방향으로만 흐르도록 엄격히 통제하여 복잡한 시스템에서도 결합도를 낮추고 모듈성을 유지합니다 [6, 52, 53]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Utility-first CSS]], [[React Server Components]], [[Design Tokens]], [[Atomic Design]], [[Compound Components]], [[Feature-Sliced Design]], [[Monorepo]] +- **Projects/Contexts:** [[Uber Base Web]] (대규모 사내 웹 애플리케이션들을 통합하기 위해 오버라이드 패턴을 광범위하게 도입한 디자인 시스템 [46, 48, 54]), [[Shopify Polaris]] (상거래 애플리케이션의 높은 접근성, 일관된 UI 제공 및 국제화(i18n) 처리를 위해 도입된 디자인 시스템 및 폼 컴포넌트 생태계 [55-58]), [[Next.js App Router]] (최신 React 아키텍처로 렌더링 방식의 차이로 인해 런타임 스타일링의 기술적 한계를 드러낸 컨텍스트 [12, 13]). +- **Contradictions/Notes:** Tailwind CSS는 압도적인 속도와 번들 크기 최소화라는 퍼포먼스적 장점을 가지지만, 마크업 내부에 길고 복잡한 클래스 문자열(Class soup)을 유발하여 가독성을 떨어뜨린다는 한계를 지닙니다 [59-61]. 반대로 Styled-components는 깔끔한 컴포넌트 레벨 캡슐화와 뛰어난 개발자 경험을 보장하지만 [9, 10], 동적 스타일을 런타임에 렌더링하므로 퍼포먼스 오버헤드가 크고 Server Component 렌더링 구조와 잘 맞지 않아 프로젝트 규모나 성격에 따라 두 도구 사이의 명확한 트레이드오프가 존재합니다 [7, 11, 12]. 두 진영은 현재 CSS variables를 적극 차용하거나(Tailwind v4의 `@theme`), 서버사이드 Style Registry를 구성(Styled-components v6)하는 방향으로 최신 생태계 요구에 적응 중입니다 [4, 13, 62]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Modular Monolith.md b/00_Raw/Modular Monolith.md new file mode 100644 index 00000000..b66e626c --- /dev/null +++ b/00_Raw/Modular Monolith.md @@ -0,0 +1,19 @@ +# [[Modular Monolith]] + +## 📌 Brief Summary +모듈러 모놀리스(Modular Monolith)는 단일 배포 애플리케이션(모놀리스) 내부에 엄격한 경계를 가진 모듈을 결합하는 프론트엔드 아키텍처 접근법입니다 [1]. 마이크로 프론트엔드처럼 여러 개의 독립된 앱을 운영하는 대신, 하나의 React 셸(Shell) 앱을 유지하면서 주문이나 결제 같은 기능(Feature)별로 모듈을 분리합니다 [2]. 각 모듈은 고유한 UI, 상태 관리, 라우팅 및 API 계층을 독립적으로 소유하므로, 런타임 복잡성 없이도 명확한 관심사 분리와 기능 소유권을 제공합니다 [2, 3]. + +## 📖 Core Content +* **단일 셸 애플리케이션과 플러그인 구조:** 하나의 컨테이너 애플리케이션이 인증, 전역 라우팅, 레이아웃 등 핵심 공통 관심사만 처리합니다. 개별 기능은 이 셸 앱에 등록되는 모듈로서 작동하며, 각 모듈은 자체적인 내부 라우팅과 도메인 API 상호작용을 완전히 책임집니다 [3, 4]. +* **수직적 슬라이스(Vertical Slice) 아키텍처 결합:** 각 모듈은 UI부터 데이터베이스 및 API 연결 계층까지 아우르는 수직적 슬라이스 형태로 구성됩니다. 이를 통해 각 도메인 기능 내의 응집도를 높이고 독립적인 개발을 가능하게 합니다 [1, 5]. +* **엄격한 경계 및 의존성 관리:** 서로 다른 기능 모듈 간의 직접적인 교차 임포트(Cross-domain import)는 엄격히 금지됩니다 [1, 3]. 컴포넌트나 로직을 공유해야 할 경우, 모든 모듈이 소비할 수 있는 공통 패키지(예: core 또는 foundations 폴더)로 분리하여 관리해야 합니다 [3, 6]. +* **도구와 모노레포(Monorepo) 활용:** 이러한 깨끗한 모듈 분리는 Turborepo, Nx, Vite 등과 같은 모노레포 구조 및 빌드 도구를 사용하여 구조적으로 강제할 수 있습니다 [2]. 특히 Nx 같은 도구를 활용하면 모듈 경계 규칙을 적용하여, 잘못된 교차 임포트 발생 시 이를 코드 리뷰 전에 빌드 타임 에러로 잡아낼 수 있습니다 [3]. +* **마이크로 프론트엔드(Micro-frontends) 대비 이점:** 모듈러 모놀리스는 모듈 페더레이션(Module Federation), 중복된 React 인스턴스 로드, 분산된 E2E 테스트 및 배포 결합 등 마이크로 프론트엔드의 전형적인 오버헤드와 런타임 복잡성을 피하면서도 명확한 소유권 경계를 달성할 수 있게 해줍니다 [2, 7, 8]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Micro-frontends]], [[Vertical Slice Architecture]], [[Monorepo]], [[Feature-Sliced Design]] +- **Projects/Contexts:** [[Scalable React Architecture]], [[Turborepo/Nx Workspace]] +- **Contradictions/Notes:** 마이크로 프론트엔드 아키텍처는 가장 높은 수준의 결합도 분리(Decoupling)를 제공하지만 유지보수와 배포의 오버헤드가 매우 큰 반면, 모듈러 모놀리스는 완전한 독립성을 일부 포기하는 대신 단일 앱 환경에서 훨씬 적은 복잡성으로 유사한 확장성 및 격리 효과를 얻을 수 있다는 명확한 트레이드오프가 존재합니다 [2, 9]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Monorepo.md b/00_Raw/Monorepo.md new file mode 100644 index 00000000..8f5098b5 --- /dev/null +++ b/00_Raw/Monorepo.md @@ -0,0 +1,22 @@ +# [[Monorepo]] + +## 📌 Brief Summary +모노레포(Monorepo)는 단일 Git 저장소 내에 여러 프론트엔드 애플리케이션, 공유 UI 컴포넌트 라이브러리, 디자인 토큰 및 공통 도구들을 함께 포함하여 관리하는 버전 관리 전략입니다 [1, 2]. 이는 단순히 코드를 한곳에 모아둔 모놀리식(Monolith) 구조가 아니라, 명확한 의존성 그래프와 공개 API(Public API)를 통해 패키지 간의 결합도를 낮추고 재사용성을 극대화하는 확장 가능한 프론트엔드 아키텍처입니다 [2-4]. + +## 📖 Core Content +- **구조 및 주요 특징:** 모노레포는 여러 앱(예: 웹, 관리자 앱, 모바일 웹)과 재사용 가능한 패키지(예: UI 키트, 디자인 토큰, API 클라이언트)가 하나의 공유된 히스토리와 일관된 의존성 그래프를 갖는 구조를 의미합니다 [1, 5]. 잘 구성된 모노레포는 높은 응집도(high cohesion)와 낮은 결합도(low coupling)를 갖춘 격리된 패키지 단위로 코드를 유지합니다 [2, 5]. +- **도입의 장점:** 단일 저장소를 사용하면 UI 원시 컴포넌트(primitives), 디자인 토큰, 라우팅 규칙 등의 코드를 여러 앱에서 손쉽게 공유할 수 있습니다 [1, 6]. API 변경 시 해당 API를 소비하는 모든 앱의 업데이트를 한 번의 커밋으로 처리하는 원자적 리팩토링(atomic refactors)이 가능합니다 [1]. 기존처럼 코드를 공유하기 위해 여러 저장소에 걸쳐 다수의 풀 리퀘스트(PR)를 생성해야 하는 문제를 해결하여 개발 속도를 크게 향상시킵니다 [7]. +- **필수 도구 생태계 (Tooling):** 2025년 기준 모노레포 환경을 지탱하는 주요 도구로는 `pnpm workspaces`, `Turborepo`, `Nx`, `Lerna` 등이 있습니다 [8, 9]. + - `pnpm workspaces`: 빠르고 공간 효율적이며 `workspace:*` 프로토콜을 통해 엄격하고 올바른 로컬 의존성 연결을 보장합니다 [10]. + - `Turborepo`: 증분 빌드(incremental builds)와 파이프라인 관리, 원격 캐싱 기능을 통해 로컬 개발 및 CI(지속적 통합) 속도를 비약적으로 높여줍니다 [11]. + - `Nx`: 강력한 프로젝트 그래프를 기반으로 코드 변경에 '영향을 받는(affected)' 프로젝트만 빌드 및 테스트하도록 최적화하며, 아키텍처 정책 강제성이 뛰어납니다 [12, 13]. +- **확장성을 위한 경계(Boundaries) 규칙:** 성공적인 모노레포는 규율이 필요합니다. 내부 파일 경로로 직접 접근하는 '깊은 경로 임포트(deep imports)'를 엄격히 금지하고, 각 패키지가 `src/index.ts`와 같은 단일 진입점(Public API)을 통해서만 모듈을 노출하도록 구성하여 파일 간의 결합을 막아야 합니다 [4, 14]. +- **아키텍처 방법론과의 결합:** 모노레포 내의 단일 공유 폴더(`shared/`)가 잡동사니 코드로 채워지는 문제를 방지하기 위해 Feature-Sliced Design (FSD)와 같은 방법론이 권장됩니다 [15-17]. FSD의 계층 구조(layers)를 모노레포의 패키지와 앱 내부에 적용하여, 어떤 모듈이 재사용 가능한지, 도메인 경계가 어디인지 예측할 수 있게 만듭니다 [16-20]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Turborepo]], [[Nx]], [[Feature-Sliced Design (FSD)]], [[Public APIs]] +- **Projects/Contexts:** [[Scalable Frontend Architecture]], [[Component Library Architecture]] +- **Contradictions/Notes:** 모노레포는 코드 통합 비용(integration cost)을 줄이고 원자적 변경을 가능하게 하지만, 경계 규칙 설정이나 CI 전략 같은 높은 규율이 요구됩니다. 반면, 앱들이 완전히 독립적인 릴리스 주기를 가지거나 컴플라이언스상 엄격한 보안 분리가 필요한 조직에서는 폴리레포(polyrepo) 접근 방식이 더 적합할 수 있습니다 [21, 22]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/00_Raw/Next.js App Router 환경에서의 확장 가능한 프론트엔드 스타일링 및 UI 컴포넌트 아키텍처 설계.md b/00_Raw/Next.js App Router 환경에서의 확장 가능한 프론트엔드 스타일링 및 UI 컴포넌트 아키텍처 설계.md new file mode 100644 index 00000000..ef1b1af4 --- /dev/null +++ b/00_Raw/Next.js App Router 환경에서의 확장 가능한 프론트엔드 스타일링 및 UI 컴포넌트 아키텍처 설계.md @@ -0,0 +1,33 @@ +# [[Next.js App Router 환경에서의 확장 가능한 프론트엔드 스타일링 및 UI 컴포넌트 아키텍처 설계]] + +## 📌 Brief Summary +Next.js App Router 환경에서는 React Server Components(RSC)의 도입으로 인해 컨텍스트(Context)에 의존하는 런타임 CSS-in-JS 방식보다 빌드 타임에 정적 CSS를 생성하는 Tailwind CSS나 CSS Modules, vanilla-extract의 사용이 성능 및 호환성 면에서 적극 권장됩니다 [1-3]. 확장 가능한 UI를 구축하려면 디자인 토큰(Design Tokens)을 활용해 중앙 집중식 스타일링을 적용하고, Atomic Design, Compound Components, Headless Components 등의 패턴을 조합하여 유지보수성과 레이아웃의 유연성을 높여야 합니다 [4-8]. 또한, 대규모 프로젝트에서는 Feature-Sliced Design(FSD)과 같은 아키텍처 방법론을 모노레포(Monorepo)와 결합하여 모듈 간의 결합도를 낮추고 예측 가능한 코드베이스 구조를 설계하는 것이 필수적입니다 [9, 10]. + +## 📖 Core Content + +* **Next.js App Router와 스타일링 패러다임 변화** + * Next.js 15의 App Router는 브라우저로 JavaScript를 전송하지 않고 서버에서 독점적으로 실행되는 **React Server Components(RSC)를 기본으로 사용**합니다 [11]. + * 이로 인해 기존 React Context에 의존하던 런타임 CSS-in-JS(예: Styled Components, Emotion)는 RSC 환경에서 작동 제약과 서버 직렬화 오버헤드가 발생할 수 있습니다 [1, 2, 12, 13]. + * 따라서 App Router 환경에서는 런타임 비용이 없고 정적 CSS를 생성하는 **Tailwind CSS, CSS Modules, 또는 vanilla-extract가 가장 적합한 방식**으로 평가받고 있습니다 [3, 14, 15]. + * Styled Components v6 이상은 RSC를 지원하여 별도의 지시어 없이 `