feat: Knowledge Gardening Milestone 440 (Batch #22)

00_Raw/2026-04-26-Skybound_Hangar_Unified_Button_Legibility_System.md

@@ -0,0 +1,101 @@
+# Skybound Hangar Unified Button Legibility System
+
+작성일: 2026-04-26 17:38 KST
+
+## 요청 요약
+
+- Permanent Upgrade 화면의 `UPGRADE` 버튼 글씨가 잘 보이지 않는다.
+- 이 화면만 고치는 것이 아니라, 전체적으로 비슷한 사례가 있는지 확인하고 같은 패턴을 사용하도록 정리해야 한다.
+
+## 핵심 문제
+
+행거 UI 안에서 버튼 스타일이 여러 계열로 나뉘어 있었다.
+
+확인된 버튼 계열:
+
+- `upgrade-btn`
+- `craft-btn`
+- `coupon-btn`
+- `support-btn`
+- `pass-buy-btn`
+- `cache-confirm-btn`
+- `unequip-btn`
+- settings action/toggle 버튼
+
+특히 비활성 상태가 각각 다른 방식으로 표현되고 있었고, 일부는 배경과 글자 대비가 낮아 “비활성”이 아니라 “읽기 어려움”으로 느껴졌다.
+
+## 적용한 해결 방향
+
+행거 내부 버튼에 공통 버튼 대비 시스템을 추가했다.
+
+원칙:
+
+- 활성 버튼은 행동 가능한 CTA로 명확하게 보여야 한다.
+- 비활성 버튼도 읽을 수 있어야 한다.
+- 비활성은 낮은 채도/낮은 강조도로 표현하되, 글자 대비는 유지한다.
+- 위험/해제 버튼은 빨강 계열, 일반 실행 버튼은 cyan/lime 계열, premium/cosmic 계열은 gold 계열로 통일한다.
+
+## 적용한 변경
+
+### 공통 버튼 베이스 추가
+
+대상:
+
+- `craft-btn`
+- `upgrade-btn`
+- `coupon-btn`
+- `pass-buy-btn`
+- `support-btn`
+- `cache-confirm-btn`
+- `unequip-btn`
+- `settings-toggle`
+- `settings-action`
+
+변경:
+
+- 공통 font smoothing 적용
+- 공통 border radius, border, shadow, weight 적용
+- 버튼 텍스트를 uppercase + 굵은 weight로 통일
+- 기본 액션 버튼은 cyan/lime 계열로 통일
+
+### 비활성 버튼 대비 개선
+
+변경:
+
+- 비활성 버튼 글자색을 더 밝은 blue-white 계열로 변경
+- 어두운 네이비 배경 위에서도 읽히도록 text-shadow 적용
+- opacity를 과도하게 낮추지 않음
+- cursor는 `not-allowed`로 유지
+
+의도:
+
+- `UPGRADE` 같은 문구가 흐릿해서 안 보이는 문제를 해결한다.
+- 사용자는 버튼이 비활성이라는 사실과 버튼의 기능을 동시에 인지할 수 있다.
+
+### 행동 종류별 색상 통일
+
+변경:
+
+- 일반 실행/확인: cyan/lime
+- 위험/해제/무음 OFF: pink/red
+- cosmic/forge/premium/max: gold/orange
+
+의도:
+
+- 버튼마다 다른 디자인 언어를 쓰지 않고, 행동의 성격에 따라 같은 색상 규칙을 공유한다.
+
+## 수정 파일
+
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HangarOverlay.css`
+
+## 검증
+
+- `npm run build` 성공
+- 출력 디렉터리: `dist/44`
+
+## 후속 체크 포인트
+
+- Permanent Upgrade 화면에서 비활성 `UPGRADE` 텍스트가 읽히는지 확인한다.
+- Craft/Synthesis/Salvage/Forge/Pass 버튼의 활성/비활성 상태가 같은 규칙으로 보이는지 확인한다.
+- 위험 버튼과 일반 실행 버튼이 명확히 구분되는지 확인한다.
+- 버튼이 너무 강하게 보여서 비활성 상태가 활성처럼 오해되지 않는지 확인한다.

00_Raw/Frontend Folder Structure.md

@@ -0,0 +1,31 @@
+# [[Frontend Folder Structure]]
+
+## 📌 Brief Summary
+프론트엔드 폴더 구조(Frontend Folder Structure)는 리액트(React)를 비롯한 애플리케이션의 유지보수성, 확장성, 협업 효율성을 결정짓는 핵심 아키텍처 요소입니다 [1-3]. 과거의 파일 유형(File-Type) 중심의 구조에서 벗어나 비즈니스 기능(Feature) 및 도메인을 중심으로 모듈화하는 방식이 권장됩니다 [4, 5]. 이를 통해 코드 결합도를 낮추고 응집도를 높여 복잡한 시스템에서도 예측 가능성을 유지하고 기술 부채를 방지할 수 있습니다 [5-7].
+
+## 📖 Core Content
+- **폴더 구조의 중요성**: 체계적이지 않은 구조는 코드를 얽히게 만들고 디버깅과 테스트를 어렵게 하여 결과적으로 기술 부채를 유발합니다 [1, 8, 9]. 반면 잘 설계된 프로젝트는 UI 요소, 비즈니스 로직, 상태 관리를 명확하게 분리(Separation of Concerns)하여 모듈의 재사용성과 협업 효율성을 크게 높여줍니다 [3, 9].
+- **기존 폴더 구조 접근법과 한계**:
+  - **단일(Flat) 구조**: 소규모 애플리케이션에 적합하게 모든 파일을 루트 레벨 근처에 배치하는 방식으로, 프로젝트가 커지면 관리와 확장이 불가능에 가깝습니다 [10].
+  - **파일 유형 기반(File-Type Based)**: `components`, `hooks`, `services` 등 기술적 역할에 따라 폴더를 나누는 전통적 방식입니다(예: MVC 패턴). 기능이 복잡해질수록 하나의 기능을 수정하기 위해 여러 폴더를 넘나들어야 하므로 확장성이 현저히 떨어집니다 [4, 11, 12].
+- **기능 기반 구조(Feature-Based Structure)**: 2025년 기준 모던 프론트엔드 개발에서는 비즈니스 기능을 중심으로 폴더를 분리하는 방식이 권장됩니다 [5]. 예를 들어 `src/features/auth` 폴더 내부에 인증과 관련된 컴포넌트, 훅(Hooks), API 통신 로직, 타입을 모두 캡슐화하여 독립적인 모듈로 관리합니다 [13, 14].
+- **권장되는 하이브리드 디렉토리 구성** [5, 14-23]:
+  - `/assets`: 이미지, 폰트 등 정적 미디어 리소스.
+  - `/components`: 애플리케이션 전체에서 공유되는 재사용 가능한 UI 컴포넌트 (버튼, 모달 등).
+  - `/features`: 핵심 기능 및 도메인 로직이 응집된 독립 모듈.
+  - `/hooks` 및 `/utils`: 전역적으로 공유되는 커스텀 훅과 범용 유틸리티 함수.
+  - `/services` (또는 `/api`): 외부 서버와의 통신 및 서드파티 서비스 연동 로직.
+  - `/store` (또는 `/context`): Redux, Zustand 등을 활용한 전역 상태 관리 인프라.
+  - `/pages` 및 `/layouts`: 라우팅에 매핑되는 페이지 화면 및 공통 레이아웃 컴포넌트.
+- **FSD (Feature-Sliced Design) 방법론**: 기능 기반 설계를 한 단계 더 체계화한 아키텍처로, 프론트엔드 프로젝트를 `app`, `pages`, `widgets`, `features`, `entities`, `shared`라는 6가지 계층(Layer)으로 나눕니다 [24-26]. 
+  - 상위 계층이 하위 계층에만 의존해야 하는 '단방향 의존성' 규칙을 강제하여 순환 참조를 방지합니다 [24].
+  - 각 슬라이스(Slice)는 반드시 `index.ts`를 통해 정의된 퍼블릭 API(Public API)만 외부에 노출하여 내부 구현을 철저히 캡슐화하고 안전한 리팩토링을 보장합니다 [24, 27, 28].
+- **네이밍 컨벤션과 거버넌스(Naming & Governance)**: 구조화와 더불어 일관된 네이밍 규칙은 필수입니다. 파일 및 폴더 이름에는 운영체제 간 호환성을 위해 `kebab-case`를 사용하거나 리액트 컴포넌트에 맞춰 `PascalCase`를 주로 사용하며, 변수나 함수, 훅은 `camelCase`를 준수해야 합니다 [29-34]. 또한 ESLint와 같은 도구를 사용해 이러한 아키텍처 및 네이밍 규칙 위반을 자동 검사(Linting)하도록 설정하는 것이 모범 사례입니다 [30].
+
+## 🔗 Knowledge Connections
+- **Related Topics:** [[Feature-Sliced Design (FSD)]], [[Clean Code Principles]], [[State Management]]
+- **Projects/Contexts:** [[Scalable React Applications]], [[Next.js File Naming and Routing]]
+- **Contradictions/Notes:** 컴포넌트, 훅, 서비스 등의 파일 유형에 따라 그룹화하는 방식(File-Type Based)은 직관적이라 초기 개발이나 초보자가 접근하기는 쉽지만, 애플리케이션의 규모가 확장되고 도메인 로직이 복잡해질 경우에는 기능(Feature) 기반 구조에 비해 유지보수성과 생산성이 크게 떨어지며 스파게티 코드를 유발하는 원인이 됩니다 [7, 11, 12].
+
+---
+*Last updated: 2026-04-26*

00_Raw/Legacy React Code Refactoring.md

@@ -0,0 +1,26 @@
+# [[Legacy React Code Refactoring]]
+
+## 📌 Brief Summary
+레거시 React 코드 리팩토링은 기존 코드의 동작 방식을 그대로 보존하면서 애플리케이션의 구조, 가독성, 유지보수성을 향상시키는 체계적인 과정입니다 [1]. 이는 단순히 코드를 고치는(fixing) 작업이 아니라 점진적인 구조 개선을 목표로 하며, 테스트 작성을 통해 시스템을 보호하는 것에서 시작합니다 [1, 2]. 주요 접근법으로는 클래스 기반 컴포넌트의 함수형 컴포넌트 전환, 커스텀 훅(Custom Hooks)을 통한 로직 분리, 상태 관리 도구의 현대화 등이 있습니다 [3, 4].
+
+## 📖 Core Content
+* **테스트 기반의 리팩토링 시작**
+  리팩토링을 수행할 때 가장 우선시해야 할 작업은 단위 테스트(Unit test)를 작성하는 것입니다 [2]. 테스트를 작성하면 코드를 변경하는 과정에서 기존 기능이 망가지는 것을 즉각적으로 파악할 수 있으며, 기존 앱이 어떻게 동작하는지 강제로 학습할 수 있는 이점도 있습니다 [2, 5]. TypeScript로의 전환이나 라이브러리 업그레이드 시 UI 테스트 스위트를 작성하여 회귀(Regression) 오류를 방지해야 합니다 [6].
+* **구조 및 상태 관리 현대화**
+  * **점진적 마이그레이션:** 기존 기술(예: Context API)에서 새로운 도구(예: Zustand)로 전환할 때 한 번에 모든 것을 재작성(Rewrite)하는 것은 위험하므로, 알림 기능과 같은 단순한 유틸리티에서 시작해 점차 복잡한 영역으로 확장하는 점진적 접근이 필요합니다 [1].
+  * **클래스 컴포넌트 제거:** 기존 클래스 기반 컴포넌트들을 함수형 컴포넌트 및 훅(Hooks) 구조로 변경해야 합니다 [4].
+  * **상태 관리 도구 분리:** 불필요한 `useEffect` 사용을 제거하고, 서버 상태 관리에는 TanStack Query를 도입하여 기존의 복잡한 Redux 구현을 걷어낼 수 있습니다. 전역 클라이언트 상태는 Context나 Zustand로 관리하고, 로컬 상태는 해당 컴포넌트에만 국한하는 것이 좋습니다 [4].
+* **커스텀 훅을 활용한 로직 분리 및 책임 분배**
+  오래된 코드베이스의 큰 문제 중 하나는 단일 컴포넌트 안에 다양한 책임이 혼재되어 있다는 점입니다 [7]. 현대 React 리팩토링의 핵심 단위는 '커스텀 훅(Custom Hooks)'입니다 [3]. 방대한 컴포넌트에서 데이터 패칭이나 폼 핸들링과 같은 비즈니스 로직을 커스텀 훅으로 추출하면, UI와 비즈니스 로직이 분리되어 독립적으로 더 빠른 단위 테스트를 수행할 수 있게 됩니다 [3].
+* **클린 코드와 일관성 강제**
+  * **스타일링 표준화:** 인라인 스타일, 외부 CSS, sx 등 무분별하게 혼재된 CSS 적용 방식을 단일 표준(예: Plain CSS, CSS Modules 등)으로 통일해야 합니다 [8-10].
+  * **원칙 적용:** 'DRY(Don't Repeat Yourself)' 및 'YAGNI(You Aren't Gonna Need It)' 원칙을 바탕으로 코드를 개선하고, 변수 호이스팅과 돌연변이(Mutation)를 방지하며 명확한 변수명을 사용해야 합니다 [11].
+  * **거버넌스 도구 도입:** ESLint(특히 `eslint-plugin-react`, `eslint-plugin-react-hooks`)를 도입하여 개발 모범 사례를 강제함으로써 코드베이스 전체에 규칙을 일관되게 적용할 수 있습니다 [12].
+
+## 🔗 Knowledge Connections
+- **Related Topics:** [[Unit Testing]], [[Custom Hooks]], [[State Management Migration]], [[Clean Code Principles]]
+- **Projects/Contexts:** [[Frontend System Architecture]], [[Legacy Code Modernization]]
+- **Contradictions/Notes:** 일반적으로 전체를 한 번에 새로 짜는 것보다는 기존 기능 개발을 지속하면서 점진적으로 개선(Refactor)하는 것이 권장되지만 [1], 코드베이스의 규모가 매우 작을 경우에는 아예 처음부터 다시 작성하는 것이 더 쉬울 수도 있다는 의견도 존재합니다 [6].
+
+---
+*Last updated: 2026-04-26*

00_Raw/Team Collaboration and Code Governance.md

@@ -0,0 +1,23 @@
+# [[Team Collaboration and Code Governance]]
+
+## 📌 Brief Summary
+팀 협업 및 코드 거버넌스(Team Collaboration and Code Governance)는 프론트엔드 개발팀이 일관성 있는 코드를 작성하고 충돌 없이 효율적으로 협업하기 위한 규칙과 자동화 도구의 활용을 의미합니다 [1, 2]. 주요 요소로는 일관된 파일 명명 규칙, ESLint와 Prettier 등을 활용한 자동화된 린팅, 그리고 티켓 ID와 Pull Request(PR) 리뷰를 포함하는 효율적인 Git 브랜칭 전략이 있습니다 [3-5]. 이러한 표준화된 구조와 거버넌스는 대규모 프로젝트에서 인지적 부하를 줄이고, 코드 품질을 유지하며, 팀이 안전하게 확장할 수 있는 필수적인 기반을 제공합니다 [6-8].
+
+## 📖 Core Content
+*   **자동화된 코드 거버넌스와 린팅 (Automated Governance):** 현대의 프론트엔드 프로젝트에서는 코딩 표준을 수동으로 강제하는 대신 ESLint와 Prettier를 사용하여 위반 사항을 자동으로 감지하고 수정합니다 [3]. ESLint 규칙을 통해 특정 기능이 다른 기능으로부터 잘못된 임포트를 하는 것을 막아 아키텍처 경계를 강제할 수 있으며, Husky를 활용해 코드를 커밋하기 전에 린팅, 포맷팅, 타입 체킹을 실행하는 Git 훅(Git hooks)을 설정함으로써 고품질의 코드만 저장소에 병합되도록 보장합니다 [3, 9].
+*   **표준화된 명명 규칙 (Naming Conventions):** 일관된 명명 규칙은 협업 시 혼란을 줄이고 코드베이스 탐색을 돕습니다 [10]. 운영체제 간(Windows/macOS 대 Linux) 대소문자 구분 문제로 인한 CI/CD 파이프라인 빌드 실패를 방지하기 위해 파일 및 폴더 이름은 `kebab-case`를 사용하고, React 컴포넌트 이름은 `PascalCase`를 사용하는 것이 강력히 권장됩니다 [11-13]. 상수나 Enum은 `UPPER_SNAKE_CASE`를 사용합니다 [14].
+*   **소규모 팀을 위한 Git 브랜치 전략 (Git Workflow for Small Teams):** 2~5명의 소규모 팀에게는 무거운 Git Flow 대신 '보호된 main 브랜치가 있는 단순한 기능 브랜치 워크플로우(Feature-Branch Workflow)'가 가장 적합합니다 [15, 16].
+    *   **브랜치 생성 및 명명:** 항상 안정적이고 배포 가능한 상태인 `main` 브랜치에서 분기하여 작업마다 수명이 짧은 기능 브랜치를 생성합니다 [17, 18]. 추적성을 높이기 위해 `feature/PROJ-123-user-auth`와 같이 작업 유형, 티켓 ID, 짧은 설명을 포함하는 명확한 브랜치 이름 규칙을 적용합니다 [19-21].
+    *   **커밋 메시지 (Conventional Commits):** 코드는 의미 단위로 작게 자주 커밋해야 하며 [22, 23], `feat:`, `fix:`, `chore:`, `refactor:` 등의 접두사를 사용하는 관례적 커밋을 통해 변경 사항의 내용과 이유를 명확히 작성해야 합니다 [24, 25].
+    *   **풀 리퀘스트(PR)와 코드 리뷰:** 변경 사항을 머지하기 위해서는 반드시 PR을 열고 최소 1명 이상의 팀원에게 리뷰를 받아야 하며, CI 테스트 통과를 필수로 요구합니다 [22, 23, 26, 27]. PR은 리뷰어가 빠르고 꼼꼼하게 검토할 수 있도록 작게 유지하는 것이 중요합니다 [24, 26]. 
+    *   **병합 및 정리:** 머지 시에는 '스쿼시 머지(Squash Merge)'를 사용하여 main 브랜치의 히스토리를 깔끔하게 유지하고, 작업이 끝난 브랜치는 자동으로 삭제하도록 설정합니다 [23, 26, 28].
+*   **시각적 리뷰 (Visual Reviews):** Storybook과 Chromatic 같은 도구를 연동하여 UI 변경 사항을 자동으로 캡처하고 베이스라인과 비교함으로써, 의도치 않은 UI 회귀(Regression)가 운영 환경에 배포되는 것을 방지하는 시각적 PR 리뷰 프로세스를 구축하는 것이 권장됩니다 [29-31].
+*   **폴더 구조를 통한 협업 향상:** 팀의 모든 개발자가 기능 기반(Feature-based)과 같은 표준화된 폴더 구조를 따르면, 커뮤니케이션 비용이 감소하고 신규 개발자의 온보딩이 매우 빨라집니다 [8]. 또한 파일 작업 시 파일들이 분리되어 있어 개발자 간의 충돌을 최소화할 수 있습니다 [8].
+
+## 🔗 Knowledge Connections
+- **Related Topics:** [[Frontend Folder Structure]], [[Git Branching Strategies]], [[Clean Code Principles]], [[Feature-Sliced Design]]
+- **Projects/Contexts:** [[React Project Setup]], [[Small Team Workflow]], [[Continuous Integration/Continuous Deployment (CI/CD)]]
+- **Contradictions/Notes:** 소규모 팀(2~5명)의 경우 무거운 'Git Flow' 전략은 오버헤드가 커서 권장되지 않으며, 트렁크 기반(Trunk-based) 또는 짧은 수명의 기능 브랜치(Feature-branch) 워크플로우가 충돌을 방지하면서도 협업 효율성을 높이는 가장 실용적인 방법이라고 주장합니다 [15, 16, 32].
+
+---
+*Last updated: 2026-04-26*