From f541717fe1f2b269eb62c2fdde92a6d9e650240d Mon Sep 17 00:00:00 2001 From: Antigravity Agent Date: Sun, 26 Apr 2026 13:53:50 +0900 Subject: [PATCH] feat: batch wikification of Skybound balance pass and scalable frontend architectures Processed 80+ files including Skybound playtest feedback, Monorepo strategies, and Modern Component Patterns. --- ...age_Pressure_and_Projectile_Visual_Pass.md | 123 +++++++++++ ...nd_HP_Scarcity_and_Module_Cache_Rewards.md | 172 +++++++++++++++ ...nvasion_Response_Stage_Difficulty_Curve.md | 133 ++++++++++++ ...d_Low_Level_First_Upgrade_Offer_Balance.md | 111 ++++++++++ ...Skybound_Player_Sprite_Path_Warning_Fix.md | 63 ++++++ ...bound_Skill_Slot_Limit_Weapon5_Passive5.md | 136 ++++++++++++ ...de_and_Weapon_Transform_Reconfiguration.md | 150 +++++++++++++ ..._Balance_Bomb_and_Visual_Diversity_Pass.md | 205 ++++++++++++++++++ .../Frontend_Mastery/Accessibility (A11y).md | 31 +++ .../Topics/Frontend_Mastery/Accessibility.md | 21 ++ .../Accessible UI Libraries.md | 28 +++ .../Topics/Frontend_Mastery/Atomic Design.md | 30 +++ .../Building Reusable UI Components.md | 33 +++ .../Topics/Frontend_Mastery/CSS Animations.md | 27 +++ .../Topics/Frontend_Mastery/CSS Variables.md | 28 ++- 10_Wiki/Topics/Frontend_Mastery/CSS-in-JS.md | 29 ++- .../Frontend_Mastery/Client Components.md | 22 ++ .../Frontend_Mastery/Component API Design.md | 22 ++ .../Component Library Architecture.md | 20 ++ .../Component-Based Design.md | 23 ++ .../Compound Components Pattern.md | 23 ++ .../Frontend_Mastery/Compound Components.md | 34 +++ .../Topics/Frontend_Mastery/Context API.md | 18 ++ .../Design System Architecture.md | 33 +++ .../Topics/Frontend_Mastery/Design Systems.md | 32 ++- .../Topics/Frontend_Mastery/Design Tokens.md | 32 +-- .../Domain-Driven Design (DDD).md | 19 ++ 10_Wiki/Topics/Frontend_Mastery/Downshift.md | 17 ++ .../Frontend_Mastery/Dynamic Theming.md | 18 ++ .../Feature-Sliced Design (FSD).md | 16 +- .../Frontend_Mastery/Feature-Sliced Design.md | 28 +++ .../Figma Design System Integration.md | 17 ++ .../Frontend_Mastery/Figma Integration.md | 18 ++ .../Frontend_Mastery/Figma Tokens Studio.md | 18 ++ .../GPU Acceleration (Compositing).md | 27 +++ .../Frontend_Mastery/Headless Components.md | 25 +++ .../Topics/Frontend_Mastery/Headless UI.md | 18 ++ 10_Wiki/Topics/Frontend_Mastery/Hydration.md | 25 +-- .../Large Frontend Projects.md | 29 +++ .../Frontend_Mastery/Layout Thrashing.md | 24 ++ 10_Wiki/Topics/Frontend_Mastery/MUI.md | 18 ++ .../Modern Scalable Frontend Architecture.md | 34 +++ .../Frontend_Mastery/Monorepo Architecture.md | 29 +++ .../Frontend_Mastery/Next.js 15 App Router.md | 18 ++ 10_Wiki/Topics/Frontend_Mastery/Next.js 15.md | 28 +++ .../Next.js App Router Migration.md | 24 ++ .../Frontend_Mastery/Next.js App Router.md | 25 ++- ... Modular and Scalable Project Structure.md | 27 +++ ...서의 UI 컴포넌트 스타일링 및 렌더링 최적화.md | 25 +++ .../Frontend_Mastery/Overrides Pattern.md | 26 +++ .../Performance Optimization.md | 28 +-- .../Topics/Frontend_Mastery/Prop Drilling.md | 18 ++ .../Topics/Frontend_Mastery/Public APIs.md | 18 ++ 10_Wiki/Topics/Frontend_Mastery/Radix UI.md | 18 ++ .../Frontend_Mastery/React Applications.md | 25 +++ .../React Component Architecture.md | 32 +++ .../React Component Library Architecture.md | 30 +++ .../React Component Patterns.md | 34 +++ .../Frontend_Mastery/React Context API.md | 18 ++ .../Topics/Frontend_Mastery/React Context.md | 18 ++ .../Frontend_Mastery/React Design Systems.md | 28 +++ .../Frontend_Mastery/React Design Tokens.md | 32 +++ .../React Frontend Architecture.md | 30 +++ .../React Server Components (RSC).md | 15 +- .../React Server Components.md | 19 +- .../Topics/Frontend_Mastery/Render Props.md | 18 ++ .../Reusable UI Component Libraries.md | 41 ++++ .../Scalable Design Systems.md | 31 +++ .../Scalable Frontend Design Systems.md | 29 +++ .../Scalable Frontend Systems.md | 32 +++ .../Frontend_Mastery/Server Components.md | 29 +++ .../Frontend_Mastery/Shopify Polaris.md | 19 ++ .../Frontend_Mastery/Style Dictionary.md | 24 +- .../Style Registry Pattern.md | 23 ++ .../Topics/Frontend_Mastery/Style Registry.md | 20 ++ .../Frontend_Mastery/Styled Components v6.md | 18 ++ .../Frontend_Mastery/Styled Components.md | 20 ++ 10_Wiki/Topics/Frontend_Mastery/Styletron.md | 18 ++ .../Tailwind CSS v4 CSS-first Architecture.md | 28 +++ .../Frontend_Mastery/Tailwind CSS v4.md | 26 +++ .../Topics/Frontend_Mastery/Tailwind CSS.md | 38 ++-- ...레이션 도구를 활용하는 대규모 조직의 React 시스템.md | 25 +++ .../Uber Base Web Design System.md | 19 ++ .../Topics/Frontend_Mastery/Uber Base Web.md | 19 ++ .../Frontend_Mastery/Utility-first CSS.md | 32 +-- .../Zero-Runtime CSS-in-JS.md | 30 +-- ...ructure UI components scalable frontend.md | 32 +++ 10_Wiki/Topics/Frontend_Mastery/shadcn-ui.md | 19 ++ .../styled-components v6.3+.md | 19 ++ .../Frontend_Mastery/styled-components.md | 18 ++ ...브러리를 보유한 엔터프라이즈 규모의 프론트엔드 환경.md | 32 +++ ...드 아키텍처(Large-Scale Frontend Architecture).md | 37 ++++ ...보수성이 요구되는 프런트엔드 모노레포 프로젝트.md | 28 +++ ... 시스템의 타이포그래피 토큰 확장 및 최적화.md | 31 +++ ...양한 디바이스 환경을 위한 반응형 레이아웃 구축.md | 31 +++ ...이션 (transition - keyframes) 성능 최적화.md | 27 +++ .../유지보수성(Maintainability).md | 28 +++ ...랫폼 UI 개발(Cross-Platform UI Development).md | 19 ++ .../확장 가능한 프론트엔드 아키텍처 구축.md | 26 +++ ...age_Pressure_and_Projectile_Visual_Pass.md | 123 +++++++++++ ...nd_HP_Scarcity_and_Module_Cache_Rewards.md | 172 +++++++++++++++ ...nvasion_Response_Stage_Difficulty_Curve.md | 133 ++++++++++++ ...d_Low_Level_First_Upgrade_Offer_Balance.md | 111 ++++++++++ ...Skybound_Player_Sprite_Path_Warning_Fix.md | 63 ++++++ ...bound_Skill_Slot_Limit_Weapon5_Passive5.md | 136 ++++++++++++ ...de_and_Weapon_Transform_Reconfiguration.md | 150 +++++++++++++ ..._Balance_Bomb_and_Visual_Diversity_Pass.md | 205 ++++++++++++++++++ .../Topics_Art/UI_UX_Assets/Atomic Design.md | 30 +++ .../Building Reusable UI Components.md | 33 +++ .../UI_UX_Assets/Client Components.md | 22 ++ .../UI_UX_Assets/Component API Design.md | 22 ++ .../Component Library Architecture.md | 20 ++ .../UI_UX_Assets/Component-Based Design.md | 23 ++ .../Compound Components Pattern.md | 23 ++ .../UI_UX_Assets/Compound Components.md | 34 +++ .../Design System Architecture.md | 33 +++ .../Topics_Art/UI_UX_Assets/Design Systems.md | 32 ++- .../Topics_Art/UI_UX_Assets/Design Tokens.md | 32 +-- .../Domain-Driven Design (DDD).md | 19 ++ .../Feature-Sliced Design (FSD).md | 18 ++ .../UI_UX_Assets/Feature-Sliced Design.md | 28 +++ .../Figma Design System Integration.md | 17 ++ .../UI_UX_Assets/Headless Components.md | 25 +++ .../UI_UX_Assets/Layout Thrashing.md | 24 ++ .../React Component Architecture.md | 32 +++ .../React Component Library Architecture.md | 30 +++ .../UI_UX_Assets/React Component Patterns.md | 34 +++ .../UI_UX_Assets/React Design Systems.md | 28 +++ .../UI_UX_Assets/React Design Tokens.md | 32 +++ .../React Server Components (RSC).md | 18 ++ .../UI_UX_Assets/React Server Components.md | 18 ++ .../Reusable UI Component Libraries.md | 41 ++++ .../UI_UX_Assets/Scalable Design Systems.md | 31 +++ .../Scalable Frontend Design Systems.md | 29 +++ .../UI_UX_Assets/Server Components.md | 29 +++ .../UI_UX_Assets/Styled Components v6.md | 18 ++ .../UI_UX_Assets/Styled Components.md | 20 ++ .../Tailwind CSS v4 CSS-first Architecture.md | 28 +++ .../UI_UX_Assets/Tailwind CSS v4.md | 26 +++ .../Topics_Art/UI_UX_Assets/Tailwind CSS.md | 34 +++ .../Uber Base Web Design System.md | 19 ++ 10_Wiki/Topics_Art/UI_UX_Assets/shadcn-ui.md | 19 ++ ...age_Pressure_and_Projectile_Visual_Pass.md | 123 +++++++++++ ...Skybound_Player_Sprite_Path_Warning_Fix.md | 63 ++++++ ..._Balance_Bomb_and_Visual_Diversity_Pass.md | 205 ++++++++++++++++++ .../Content_Strategy/Accessibility (A11y).md | 31 +++ .../Content_Strategy/Accessibility.md | 21 ++ .../Accessible UI Libraries.md | 28 +++ .../Building Reusable UI Components.md | 33 +++ .../Reusable UI Component Libraries.md | 41 ++++ ...nvasion_Response_Stage_Difficulty_Curve.md | 133 ++++++++++++ ...d_Low_Level_First_Upgrade_Offer_Balance.md | 111 ++++++++++ ..._Balance_Bomb_and_Visual_Diversity_Pass.md | 205 ++++++++++++++++++ ...d_Low_Level_First_Upgrade_Offer_Balance.md | 111 ++++++++++ ...bound_Skill_Slot_Limit_Weapon5_Passive5.md | 136 ++++++++++++ ...de_and_Weapon_Transform_Reconfiguration.md | 150 +++++++++++++ 156 files changed, 6543 insertions(+), 243 deletions(-) create mode 100644 10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Enemy_Motion_Damage_Pressure_and_Projectile_Visual_Pass.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_HP_Scarcity_and_Module_Cache_Rewards.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Invasion_Response_Stage_Difficulty_Curve.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Low_Level_First_Upgrade_Offer_Balance.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Player_Sprite_Path_Warning_Fix.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Skill_Slot_Limit_Weapon5_Passive5.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Skip_Upgrade_and_Weapon_Transform_Reconfiguration.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Stage1_to_3_Playtest_Balance_Bomb_and_Visual_Diversity_Pass.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Accessibility (A11y).md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Accessibility.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Accessible UI Libraries.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Atomic Design.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Building Reusable UI Components.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/CSS Animations.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Client Components.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Component API Design.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Component Library Architecture.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Component-Based Design.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Compound Components Pattern.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Compound Components.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Context API.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Design System Architecture.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Domain-Driven Design (DDD).md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Downshift.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Dynamic Theming.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Feature-Sliced Design.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Figma Design System Integration.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Figma Integration.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Figma Tokens Studio.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/GPU Acceleration (Compositing).md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Headless Components.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Headless UI.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Large Frontend Projects.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Layout Thrashing.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/MUI.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Modern Scalable Frontend Architecture.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Monorepo Architecture.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Next.js 15 App Router.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Next.js 15.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Next.js App Router Migration.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Next.js Modular and Scalable Project Structure.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Next.js 환경에서의 UI 컴포넌트 스타일링 및 렌더링 최적화.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Overrides Pattern.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Prop Drilling.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Public APIs.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Radix UI.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Applications.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Component Architecture.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Component Library Architecture.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Component Patterns.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Context API.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Context.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Design Systems.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Design Tokens.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/React Frontend Architecture.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Render Props.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Reusable UI Component Libraries.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Scalable Design Systems.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Scalable Frontend Design Systems.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Scalable Frontend Systems.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Server Components.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Shopify Polaris.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Style Registry Pattern.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Style Registry.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Styled Components v6.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Styled Components.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Styletron.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Tailwind CSS v4 CSS-first Architecture.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Tailwind CSS v4.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Turborepo 및 Nx와 같은 빌드 오케스트레이션 도구를 활용하는 대규모 조직의 React 시스템.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Uber Base Web Design System.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/Uber Base Web.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/best styling approach in React projects styled-components vs tailwind pros cons how to build reusable UI components React design tokens implementation example component library architecture React how to structure UI components scalable frontend.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/shadcn-ui.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/styled-components v6.3+.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/styled-components.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/다수의 React-Next.js 애플리케이션과 공통 UI 라이브러리를 보유한 엔터프라이즈 규모의 프론트엔드 환경.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/대규모 프론트엔드 아키텍처(Large-Scale Frontend Architecture).md create mode 100644 10_Wiki/Topics/Frontend_Mastery/대규모 확장성과 유지보수성이 요구되는 프런트엔드 모노레포 프로젝트.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/디자인 시스템의 타이포그래피 토큰 확장 및 최적화.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/모바일 퍼스트 및 다양한 디바이스 환경을 위한 반응형 레이아웃 구축.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/애니메이션 (transition - keyframes) 성능 최적화.md create mode 100644 10_Wiki/Topics/Frontend_Mastery/유지보수성(Maintainability).md create mode 100644 10_Wiki/Topics/Frontend_Mastery/크로스 플랫폼 UI 개발(Cross-Platform UI Development).md create mode 100644 10_Wiki/Topics/Frontend_Mastery/확장 가능한 프론트엔드 아키텍처 구축.md create mode 100644 10_Wiki/Topics/Skybound/2026-04-26-Skybound_Enemy_Motion_Damage_Pressure_and_Projectile_Visual_Pass.md create mode 100644 10_Wiki/Topics/Skybound/2026-04-26-Skybound_HP_Scarcity_and_Module_Cache_Rewards.md create mode 100644 10_Wiki/Topics/Skybound/2026-04-26-Skybound_Invasion_Response_Stage_Difficulty_Curve.md create mode 100644 10_Wiki/Topics/Skybound/2026-04-26-Skybound_Low_Level_First_Upgrade_Offer_Balance.md create mode 100644 10_Wiki/Topics/Skybound/2026-04-26-Skybound_Player_Sprite_Path_Warning_Fix.md create mode 100644 10_Wiki/Topics/Skybound/2026-04-26-Skybound_Skill_Slot_Limit_Weapon5_Passive5.md create mode 100644 10_Wiki/Topics/Skybound/2026-04-26-Skybound_Skip_Upgrade_and_Weapon_Transform_Reconfiguration.md create mode 100644 10_Wiki/Topics/Skybound/2026-04-26-Skybound_Stage1_to_3_Playtest_Balance_Bomb_and_Visual_Diversity_Pass.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Atomic Design.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Building Reusable UI Components.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Client Components.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Component API Design.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Component Library Architecture.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Component-Based Design.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Compound Components Pattern.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Compound Components.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Design System Architecture.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Domain-Driven Design (DDD).md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Feature-Sliced Design (FSD).md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Feature-Sliced Design.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Figma Design System Integration.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Headless Components.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Layout Thrashing.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/React Component Architecture.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/React Component Library Architecture.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/React Component Patterns.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/React Design Systems.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/React Design Tokens.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/React Server Components (RSC).md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/React Server Components.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Reusable UI Component Libraries.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Scalable Design Systems.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Scalable Frontend Design Systems.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Server Components.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Styled Components v6.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Styled Components.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Tailwind CSS v4 CSS-first Architecture.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Tailwind CSS v4.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Tailwind CSS.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/Uber Base Web Design System.md create mode 100644 10_Wiki/Topics_Art/UI_UX_Assets/shadcn-ui.md create mode 100644 10_Wiki/Topics_Art/Visual_Effects/2026-04-26-Skybound_Enemy_Motion_Damage_Pressure_and_Projectile_Visual_Pass.md create mode 100644 10_Wiki/Topics_Art/Visual_Effects/2026-04-26-Skybound_Player_Sprite_Path_Warning_Fix.md create mode 100644 10_Wiki/Topics_Art/Visual_Effects/2026-04-26-Skybound_Stage1_to_3_Playtest_Balance_Bomb_and_Visual_Diversity_Pass.md create mode 100644 10_Wiki/Topics_Blog/Content_Strategy/Accessibility (A11y).md create mode 100644 10_Wiki/Topics_Blog/Content_Strategy/Accessibility.md create mode 100644 10_Wiki/Topics_Blog/Content_Strategy/Accessible UI Libraries.md create mode 100644 10_Wiki/Topics_Blog/Content_Strategy/Building Reusable UI Components.md create mode 100644 10_Wiki/Topics_Blog/Content_Strategy/Reusable UI Component Libraries.md create mode 100644 10_Wiki/Topics_GD/Balancing/2026-04-26-Skybound_Invasion_Response_Stage_Difficulty_Curve.md create mode 100644 10_Wiki/Topics_GD/Balancing/2026-04-26-Skybound_Low_Level_First_Upgrade_Offer_Balance.md create mode 100644 10_Wiki/Topics_GD/Balancing/2026-04-26-Skybound_Stage1_to_3_Playtest_Balance_Bomb_and_Visual_Diversity_Pass.md create mode 100644 10_Wiki/Topics_GD/Core_Systems/2026-04-26-Skybound_Low_Level_First_Upgrade_Offer_Balance.md create mode 100644 10_Wiki/Topics_GD/Core_Systems/2026-04-26-Skybound_Skill_Slot_Limit_Weapon5_Passive5.md create mode 100644 10_Wiki/Topics_GD/Core_Systems/2026-04-26-Skybound_Skip_Upgrade_and_Weapon_Transform_Reconfiguration.md diff --git a/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Enemy_Motion_Damage_Pressure_and_Projectile_Visual_Pass.md b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Enemy_Motion_Damage_Pressure_and_Projectile_Visual_Pass.md new file mode 100644 index 00000000..2b503ac4 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Enemy_Motion_Damage_Pressure_and_Projectile_Visual_Pass.md @@ -0,0 +1,123 @@ +# Skybound Enemy Motion Damage Pressure and Projectile Visual Pass + +작성일: 2026-04-26 12:46 KST + +## 요청 요약 + +- Stage 1 적기의 이동이 어디에 낀 것처럼 바들바들 떨리는 문제를 개선한다. +- 적 공격 데미지가 사용자 Tac Level에 정비례해서 오르는 느낌이 아니라, 소폭만 상승하도록 조정한다. +- 사용자 기체의 일반 공격 탄환과 Gatling 탄환이 단순 렌더링 도형처럼 보여 아쉬운 문제를 개선한다. +- 스킬과 탄환의 비주얼을 Skybound의 Stylized Casual Magitech 톤앤매너에 맞춰 더 상품성 있게 다듬는다. + +## 핵심 문제 + +### 적 이동 떨림 + +Stage 1에서 보이는 적기의 떨림은 주로 추적형 AI가 플레이어 근처에서 목표점을 매 프레임 다시 계산하면서 발생했다. 목표를 향해 직선 이동하다가 너무 가까워지면 다음 프레임에 방향이 반대로 튀고, 여기에 회전값도 즉시 플레이어를 향해 바뀌면서 시각적으로 “끼어서 떠는” 것처럼 보였다. + +### 적 데미지 상승 + +적 데미지는 스테이지와 페이즈 압박에 따라 올라가야 하지만, 사용자 Tac Level과 동일한 폭으로 오르면 성장 보상이 무효화된다. 따라서 Tac Level은 적 데미지에 아주 작은 압박 보정만 주는 것이 맞다. + +### 플레이어 탄환 비주얼 + +기본 공격과 Gatling 탄환은 기존 Canvas 사각형/막대 형태가 남아 있어, 현재 게임의 마법공학 기체와 스킬 아이콘 퀄리티에 비해 완성도가 낮게 보였다. + +## 적용한 변경 + +### 적 회전 안정화 + +적기의 회전을 즉시 목표 각도로 바꾸지 않고 `smoothEnemyRotation`을 통해 보간한다. + +이제 적은 플레이어를 향해 부드럽게 회전하며, 근거리에서 회전값이 프레임마다 튀는 현상이 줄어든다. + +### 추적형 적 이동 안정화 + +`chase` 패턴에 속도 보간과 근거리 감속을 추가했다. + +- 목표점으로 바로 이동하지 않고 `vx`, `vy`를 보간한다. +- 플레이어와 너무 가까워지면 속도를 줄인다. +- 일정 거리 안으로 들어오면 살짝 밀려나며 겹침을 완화한다. + +### 적끼리 겹침 완화 + +`applyEnemySeparation`을 추가했다. 적이 서로 너무 가까이 붙으면 약하게 밀어내어, 여러 적이 한 점에 몰려 떨리는 문제를 줄인다. + +적 종류별 최소 거리도 다르게 적용한다. + +- 일반 적: 작은 거리 +- 엘리트: 중간 거리 +- 미니보스: 더 큰 거리 + +### 적 데미지 보정 완만화 + +기존에는 페이즈 난이도 배율이 탄속/데미지에 직접적으로 강하게 반영될 수 있었다. 이제 아래처럼 완만하게 조정했다. + +- 탄속은 페이즈 배율을 직접 곱하지 않고 작은 `phaseSpeedPressure`만 반영한다. +- 데미지는 스테이지 커브를 기본으로 하되 `phaseDamagePressure`를 제한적으로 적용한다. +- 사용자 Tac Level은 최대 `+18%`까지만 적 데미지에 반영한다. + +의도는 다음과 같다. + +- 플레이어가 성장해도 적이 완전히 무력해지지는 않는다. +- 하지만 플레이어 레벨이 올랐다고 적 데미지가 같은 폭으로 따라오지는 않는다. +- 성장 보상은 유지하고, 긴장감만 조금 보강한다. + +### 플레이어 탄환 비주얼 개선 + +기본 탄환, Gatling 탄환, Rayce 탄환, 드론 탄환에 `visualKind`를 부여했다. + +추가된 visualKind: + +- `arc_bolt` +- `gatling_round` +- `rayce_lance` +- `micro_missile` +- `arc_vulcan` +- `drone_shot` + +### Magitech Projectile Renderer 추가 + +`GameRenderer`에 `renderMagitechProjectile`을 추가했다. 기존 사각형 탄환 대신 아래 요소를 가진 발사체로 렌더링된다. + +- 밝은 코어 +- 마법공학 외곽 라인 +- 발사 방향 꼬리광 +- 글로우 +- 작은 룬/핀 라인 +- 기체/무기별 색상 차이 + +Gatling은 골드빛 짧은 고속탄, 기본 Falcon 탄은 시안 아크 볼트, Rayce는 마젠타 랜스형 탄환으로 보이게 했다. + +## 설계 의도 + +이번 변경은 조작감과 시각 품질을 동시에 개선하는 작업이다. + +적 이동은 “불안정한 버그처럼 보이는 흔들림”이 아니라, 의도된 추적/회피 압박처럼 보여야 한다. 또한 적 데미지는 플레이어 성장과 같은 폭으로 따라오면 안 된다. 플레이어는 강해져야 하고, 적은 그 강함을 무효화하지 않는 선에서 압박을 유지해야 한다. + +탄환 비주얼은 Skybound의 가장 자주 보는 이펙트이므로, 단순 도형이 남아 있으면 전체 완성도를 낮춘다. 이번 변경으로 기본 공격도 스킬과 같은 톤의 Magitech 무장처럼 보이게 했다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/CombatSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/GameRenderer.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ModularWeaponSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/PlayerSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/SpawnerSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/WeaponBehaviorEngine.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/types.ts` + +## 검증 + +- `npm run build` 성공 +- `/sprites/player.png` 경고 없음 +- 출력 디렉터리: `dist/23` + +## 후속 플레이테스트 체크 포인트 + +- Stage 1 일반 적이 플레이어 근처에서 바들바들 떨지 않는지 확인한다. +- 적이 겹칠 때 자연스럽게 분산되는지 확인한다. +- Tac Level이 올라가도 적 데미지가 과하게 따라오지 않는지 확인한다. +- Falcon 기본탄과 Gatling 탄환이 사각형 도형이 아니라 마법공학 발사체처럼 보이는지 확인한다. +- Rayce 탄환이 Falcon과 충분히 구분되는지 확인한다. +- 이후 스킬별 전용 Canvas/PNG 이펙트를 더 세분화할지 결정한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_HP_Scarcity_and_Module_Cache_Rewards.md b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_HP_Scarcity_and_Module_Cache_Rewards.md new file mode 100644 index 00000000..9786b8c6 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_HP_Scarcity_and_Module_Cache_Rewards.md @@ -0,0 +1,172 @@ +# Skybound HP Scarcity and Module Cache Rewards + +작성일: 2026-04-26 13:01 KST + +## 요청 요약 + +- Stage 1 플레이 중 하트 HP 회복 아이템이 너무 자주 드롭되어 위기감이 사라지는 문제를 개선한다. +- 초반에는 어느 정도 회복을 주되, 항상 충분하게 주기보다 “조금 아쉬운” 수준으로 조정한다. +- 전투 중 모듈이 자동 지급되어 획득 재미가 떨어지는 문제를 개선한다. +- 보물 상자 혹은 모듈 상자 이미지를 만들고, 사용자 인벤토리에 stacking되게 한다. +- 상자를 열었을 때 모듈 획득 이펙트와 연출을 추가한다. +- 일반 등급은 기본 연출, 상급 이상은 개봉 중 기대감을 줄 수 있는 힌트 연출을 제공한다. + +## 핵심 문제 + +기존 보상 구조는 적 처치 시 장비가 곧바로 `inventory`에 추가되는 방식이었다. + +이 구조는 기능적으로는 빠르지만, 사용자가 다음 감각을 느끼기 어렵다. + +1. 내가 무언가를 얻었다는 소유감 +2. 전투 후 보상을 확인하는 기대감 +3. 상자를 열 때 “이번에는 뭐가 나올까” 하는 가챠/루팅 재미 +4. 등급별 보상의 차이 + +또한 하트 드롭은 대량의 적 처치 수와 결합되면서 체력 결핍이 거의 발생하지 않는 상태를 만들었다. + +## 적용한 변경 + +### HP 회복 아이템 희소화 + +기존에는 적 처치 시 25% 확률로 필드 아이템이 나오고, 그중 일부가 HP 회복 아이템이었다. + +변경 후에는 체력 상태와 쿨다운을 기반으로 HP 드롭을 계산한다. + +- HP가 82% 이상이면 하트 드롭이 거의 발생하지 않는다. +- HP가 60% 미만일 때부터 하트 확률이 의미 있게 상승한다. +- HP가 35% 미만이면 긴급 회복 가능성을 열어둔다. +- 하트 드롭 후에는 기본 900프레임 쿨다운을 둔다. +- 위기 상황에서는 쿨다운을 480프레임으로 낮춰 완전한 운빨 사망은 줄인다. +- 엘리트와 미니보스는 회복/보상 드롭 가능성이 조금 더 높다. + +### 회복량 조정 + +하트 하나가 체력을 너무 크게 회복하지 않도록 회복량을 낮췄다. + +변경 전: + +- 필드 하트: 최대 HP의 20% +- 회복 에어드롭: 최대 HP의 40% + +변경 후: + +- 필드 하트: 최대 HP의 14% +- 회복 에어드롭: 최대 HP의 32% + +목표는 “살았다”는 안도감은 주되, 바로 100% 안정권으로 돌아가지 않게 만드는 것이다. + +### 자동 모듈 지급 제거 + +일반 적 처치 시 장비가 직접 지급되는 흐름을 제거했다. + +변경 후: + +- 일반 적은 장비/모듈 캐시를 지급하지 않는다. +- 엘리트, 미니보스, 보스 보상은 즉시 장비 지급이 아니라 `Module Cache`로 전환된다. +- 캐시는 격납고 인벤토리에 stacking된다. +- 실제 장비는 사용자가 캐시를 열 때 생성된다. + +이제 전투 중에는 “보상 상자를 회수했다”는 흐름이 되고, 장비 획득은 격납고에서 별도 개봉 경험으로 분리된다. + +### Module Cache 인벤토리 추가 + +`useGameStore`에 `moduleCaches` 상태와 액션을 추가했다. + +추가된 액션: + +- `addModuleCache(cache)` +- `openModuleCache(cacheId)` + +`openModuleCache`는 캐시의 등급과 클래스 정보를 기반으로 장비를 생성하고, 해당 장비를 `inventory`에 `isNew` 상태로 추가한다. + +### Module Cache 이미지 추가 + +톤앤매너에 맞춘 Stylized Casual Magitech 상자 SVG를 추가했다. + +특징: + +- 굵은 외곽선 +- 시안/라임 마력 코어 +- 블루 메탈 케이스 +- 골드 띠 장식 +- 상자 개봉 UI에서 재사용 가능한 벡터 에셋 + +추가 파일: + +- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/module_cache.svg` + +### 격납고 Module Cache UI 추가 + +`HangarOverlay`의 Loadout 탭에 `Module Caches` 섹션을 추가했다. + +UI 동작: + +- 같은 등급/클래스/출처의 캐시는 하나의 카드로 stacking 표시된다. +- 카드에는 `xN` 카운트가 표시된다. +- Elite Cache, Command Cache, Boss Cache 출처가 표시된다. +- 클릭하면 해당 캐시 1개를 개봉한다. + +### 등급별 개봉 연출 추가 + +캐시 개봉 시 별도 오버레이가 뜨도록 했다. + +연출 구성: + +- 어두운 배경 블러 +- 캐시 중심 이미지 +- 등급 색상 기반 발광 +- 회전하는 아케인 링 +- 작은 마력 스파크 +- 개봉 중 힌트 텍스트 +- 최종 모듈 이름/타입/스탯 공개 + +일반 등급은 짧은 기본 개봉으로 처리하고, GOOD 이상은 개봉 중 다음 힌트를 보여준다. + +- 모듈 타입 신호 +- 보상 출처 +- 등급 신호 안정화 문구 + +이를 통해 상급 이상 상자는 결과 공개 전 기대감을 주는 구조로 만들었다. + +## 설계 의도 + +이번 패스의 목표는 Stage 1의 생존 긴장감과 보상 기대감을 동시에 살리는 것이다. + +하트는 플레이어를 완전히 방치하지 않되, 항상 충분하게 주지 않는다. + +모듈은 자동 지급에서 상자 개봉으로 바꿔 다음 루프를 만든다. + +1. 전투에서 엘리트/보스 처치 +2. 모듈 캐시 획득 +3. 격납고로 복귀 +4. 캐시 stack 확인 +5. 캐시 개봉 +6. 모듈 획득 +7. 장착/합성/분해 선택 + +이 구조는 Vampire Survivors류의 런 성장과 Survivor.io류의 메타 보상 사이를 이어주는 역할을 한다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/public/sprites/module_cache.svg` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/store/useGameStore.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/CombatSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/StageDirectorSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/types.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HangarOverlay.tsx` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HangarOverlay.css` + +## 검증 + +- `npm run build` 성공 +- `/sprites/player.png` 경고 없음 +- 출력 디렉터리: `dist/24` + +## 후속 플레이테스트 체크 포인트 + +- Stage 1 초반 하트가 너무 부족해서 불합리하게 느껴지지 않는지 확인한다. +- Stage 1 중반 이후 체력이 즉시 100%로 복구되는 빈도가 줄었는지 확인한다. +- 엘리트/보스 처치 후 캐시 획득 문구가 보상처럼 느껴지는지 확인한다. +- 격납고에서 캐시 stack UI가 충분히 명확한지 확인한다. +- GOOD 이상 캐시 개봉 시 “뭐가 나올까” 하는 기대감이 생기는지 확인한다. +- 캐시 개봉 후 모듈이 `Module Storage`에 자연스럽게 추가되는지 확인한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Invasion_Response_Stage_Difficulty_Curve.md b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Invasion_Response_Stage_Difficulty_Curve.md new file mode 100644 index 00000000..70f46e40 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Invasion_Response_Stage_Difficulty_Curve.md @@ -0,0 +1,133 @@ +# Skybound Invasion Response Stage Difficulty Curve + +작성일: 2026-04-26 13:08 KST + +## 요청 요약 + +- Stage 8 보스가 지구를 침략한 핵심 적이라는 스토리 구조를 난이도 곡선에 반영한다. +- 초반에는 플레이어를 얕보고 소수의 적기만 보내는 느낌으로 시작한다. +- 스테이지를 클리어할수록 보스가 플레이어를 점점 더 위험하게 판단하고, 단계적으로 더 많은 적기를 투입한다. +- 적기의 수가 줄어든 구간은 너무 쉬워질 수 있으므로 적기의 공격력을 비례해서 보정한다. + +## 핵심 방향 + +이번 패스는 단순히 숫자를 올리는 밸런스가 아니라 “침공군의 대응 수위”를 만드는 작업이다. + +설계 기준은 다음과 같다. + +1. Stage 1: 정찰대. 적 수는 적지만 한 발은 무시할 수 없다. +2. Stage 2: 빠른 대응기 투입. 아직 소규모지만 반응 속도가 오른다. +3. Stage 3: 혼합 편대. 보스가 플레이어를 실제 변수로 인식한다. +4. Stage 4: 제압 작전. 십자/라인 압박이 본격화된다. +5. Stage 5: 전면 공격 승인. 적 수가 확실히 늘어난다. +6. Stage 6: 제거 함대. 빌드 완성도를 검증한다. +7. Stage 7: 예비 전력 투입. 물량과 엘리트 압박이 커진다. +8. Stage 8: 지구 침공 본대. 최대 물량과 최대 화력으로 압박한다. + +## 적용한 변경 + +### Stage Profile 재정렬 + +`SURVIVOR_STAGE_PROFILES`를 8단계 침공 대응 곡선으로 재배치했다. + +변경된 주요 축: + +- `diffBase` +- `capBase` +- `spawnTempo` +- opening wave density +- swarm density +- climax elite density +- comms 문구 + +### 초반 적 수 감소 + +Stage 1과 Stage 2는 보스가 플레이어를 얕보는 단계로 설정했다. + +Stage 1 변경: + +- `capBase: 18` → `12` +- `spawnTempo: 1.0` → `1.18` +- opening density: `8` → `4` +- swarm density: `18` → `12` +- climax elite density: `3` → `2` + +Stage 2 변경: + +- `capBase: 28` → `16` +- `spawnTempo: 0.86` → `1.02` +- opening density: `14` → `7` +- swarm density: `24` → `16` +- climax elite density: `4` → `3` + +초반에는 화면을 적으로 가득 채우기보다, 각 적기의 진입과 탄환을 플레이어가 인식할 수 있게 만들었다. + +### 중후반 적 수 증가 곡선 강화 + +Stage 5부터는 침공군이 실제로 플레이어 제거를 목표로 움직이는 느낌을 강화했다. + +후반 주요 변화: + +- Stage 5 `capBase: 40` → `34`, 대신 `diffBase: 1.42` → `1.54` +- Stage 6 `capBase: 46` → `42`, `diffBase: 1.58` → `1.74` +- Stage 7 `capBase: 52` → `50`, `diffBase: 1.76` → `1.96` +- Stage 8 `capBase: 58` → `60`, `diffBase: 1.96` → `2.22` +- Stage 8 swarm density: `60` → `68` +- Stage 8 climax elite density: `10` → `12` + +Stage 5-7은 성능과 가독성을 고려해 단순 물량만 폭증시키지 않고, 공격 위협을 함께 올렸다. + +### 공격력 보정 + +적 수가 줄어든 스테이지가 너무 쉬워지는 것을 방지하기 위해 `DAMAGE_CURVE`를 상향했다. + +변경 전: + +- `[0.95, 1.08, 1.24, 1.44, 1.68, 1.96, 2.28, 2.65]` + +변경 후: + +- `[1.08, 1.16, 1.32, 1.52, 1.78, 2.08, 2.44, 2.88]` + +의도는 “적 수가 적으면 회피 기회가 많아지는 만큼, 맞았을 때는 실수로 느껴지게 하는 것”이다. + +### Comms 서사 반영 + +스테이지 시작/주요 웨이브 문구를 침공 대응 서사에 맞게 수정했다. + +예시: + +- Stage 1: `Scout flight detected. The invader is probing our response.` +- Stage 2: `Stage 2: the invader is testing faster response craft.` +- Stage 4: `Stage 4: the invader is no longer probing. Suppression grid active.` +- Stage 8: `Stage 8: planetary invasion force confirmed. Survive the crush.` + +## 설계 의도 + +이번 변경의 핵심은 플레이어가 난이도 상승을 “게임이 갑자기 어려워졌다”가 아니라 “보스가 나를 점점 더 심각한 위협으로 보고 있다”라고 받아들이게 만드는 것이다. + +초반은 적 수가 줄어들었기 때문에 회피와 학습의 여유가 있다. + +하지만 공격력은 낮추지 않고 오히려 보정했기 때문에, 가만히 있어도 쉽게 깨지는 구조는 피한다. + +후반은 플레이어 빌드가 강해지는 것을 전제로, 적 수와 공격력이 함께 올라간다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/CombatTimeline.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/balance.ts` + +## 검증 + +- `npm run build` 성공 +- `/sprites/player.png` 경고 없음 +- 출력 디렉터리: `dist/25` + +## 후속 플레이테스트 체크 포인트 + +- Stage 1 초반이 “적이 적어서 심심한지” 또는 “소수지만 긴장감이 있는지” 확인한다. +- Stage 1에서 맞았을 때 피격이 의미 있게 느껴지는지 확인한다. +- Stage 2가 Stage 1보다 확실히 대응 수위가 올라간 것처럼 느껴지는지 확인한다. +- Stage 3-4에서 혼합 편대/제압 작전으로 플레이 양상이 달라지는지 확인한다. +- Stage 5 이후부터 물량 증가가 명확하게 느껴지는지 확인한다. +- Stage 8이 최종 침공군답게 가장 강한 물량과 화력을 보여주는지 확인한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Low_Level_First_Upgrade_Offer_Balance.md b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Low_Level_First_Upgrade_Offer_Balance.md new file mode 100644 index 00000000..ce64df7e --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Low_Level_First_Upgrade_Offer_Balance.md @@ -0,0 +1,111 @@ +# Skybound Low Level First Upgrade Offer Balance + +작성일: 2026-04-26 13:16 KST + +## 요청 요약 + +- 게임 플레이 중 Tactical Level Up으로 무기/스킬 업그레이드 후보가 나온다. +- 이미 많이 레벨업한 무기가 계속 후보에 자주 나오면 특정 무기 몰빵이 쉬워진다. +- 레벨이 낮은 무기/스킬이 다음 후보에 포함될 확률을 더 높인다. +- 레벨이 높은 무기/스킬은 낮은 레벨 스킬 대비 후보 포함 확률을 낮춘다. + +## 핵심 문제 + +기존 `ProgressionSystem.generateSkillCards()`는 이미 보유한 스킬과 near-max 스킬에 보너스를 주는 구조였다. + +기존 구조의 문제: + +1. 한 무기가 빠르게 고레벨까지 몰릴 수 있다. +2. Lv4 → Lv5 직전 스킬이 자주 후보에 떠서 성장 속도가 급격해진다. +3. 다양한 무기를 경험하기보다 가장 강한 무기 하나가 빠르게 완성된다. +4. Stage 1-2 중반부터 빌드가 너무 빨리 안정화될 수 있다. + +## 적용한 변경 + +### 후보 선택 방식 변경 + +기존에는 카테고리별로 후보를 고르고, 보유/시너지/near-max에 가중치를 더했다. + +변경 후에는 각 스킬마다 `offer weight`를 계산한다. + +가중치 기준: + +- 남은 레벨이 많을수록 가중치 증가 +- Lv0/Lv1 스킬은 상대적으로 더 자주 등장 +- Lv3 이상 스킬은 가중치 감소 +- max 직전 스킬은 강하게 가중치 감소 +- 시너지/EVO 보너스는 유지하되, 고레벨 스킬을 압도적으로 밀어주지는 않음 + +### 고레벨 몰빵 완화 + +Near-max 스킬은 기존에 오히려 보너스를 받았지만, 이제는 낮은 확률로만 나온다. + +적용 규칙: + +- `currentLevel >= maxLevel - 1`: 가중치 35%로 감소 +- `currentLevel >= maxLevel * 0.6`: 가중치 58%로 감소 + +예시: + +- Lv0/Lv1 스킬: 목록에 더 잘 등장 +- Lv3/Lv4 스킬: 등장 가능하지만 낮은 빈도 +- Lv4 → Lv5 완성: 운이 좋아야 뜨는 마무리 선택으로 변경 + +### 첫 선택 보정 + +아직 아무 스킬도 없는 첫 Tactical Level Up에서는 새 무기 후보를 우선 제공한다. + +목표는 첫 선택이 빌드 방향을 정하는 순간으로 작동하게 하는 것이다. + +### 새 무기 확장 선택 유지 + +이미 스킬을 보유한 이후에도 새 무기 후보가 완전히 사라지지는 않는다. + +변경 후: + +- 슬롯 여유가 있고 새 무기가 있으면 65% 확률로 하나의 build-expanding option을 제공한다. +- 나머지 후보는 전체 가중치 풀에서 선택한다. + +### Mini-boss Reward Cache 보정 + +미니보스 보상 카드도 가장 높은 레벨 무기를 무조건 우선하지 않도록 변경했다. + +변경 후에는 보유 무기 중에서도 낮은 레벨/남은 성장 여지가 큰 무기가 더 잘 선택된다. + +### UI fallback 보정 + +일반적으로 카드 후보는 엔진에서 생성되지만, 예외적으로 `LevelUpModal`에서 fallback 랜덤이 동작할 수 있다. + +이 fallback도 동일한 low-level-first 가중치 규칙을 따르도록 변경했다. + +## 설계 의도 + +이번 변경의 목표는 성장 속도를 늦추는 것만이 아니다. + +플레이어가 한 무기를 빠르게 완성해 “이미 빌드가 끝났다”라고 느끼는 시점을 뒤로 미루고, 여러 선택지 사이에서 더 오래 고민하게 만드는 것이 핵심이다. + +원하는 플레이 감각: + +1. 초반에는 새 무기와 낮은 레벨 무기가 자주 보인다. +2. 중반에는 빌드 방향을 넓히거나 약한 축을 보완하게 된다. +3. 고레벨 완성 선택은 자주 뜨지 않지만, 떴을 때 반갑다. +4. 특정 무기 하나가 너무 빨리 완성되어 난이도를 붕괴시키는 일이 줄어든다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ProgressionSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.tsx` + +## 검증 + +- `npm run build` 성공 +- `/sprites/player.png` 경고 없음 +- 출력 디렉터리: `dist/26` + +## 후속 플레이테스트 체크 포인트 + +- Stage 1에서 같은 무기가 너무 빠르게 Lv4/Lv5까지 올라가지 않는지 확인한다. +- 낮은 레벨 무기/패시브가 기존보다 자주 후보에 뜨는지 확인한다. +- 고레벨 완성 선택이 너무 안 떠서 답답하지 않은지 확인한다. +- EVO 경로가 완전히 막힌 느낌이 들지 않는지 확인한다. +- 미니보스 보상 카드가 여전히 보상답게 느껴지는지 확인한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Player_Sprite_Path_Warning_Fix.md b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Player_Sprite_Path_Warning_Fix.md new file mode 100644 index 00000000..e6bd1aa4 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Player_Sprite_Path_Warning_Fix.md @@ -0,0 +1,63 @@ +# Skybound Player Sprite Path Warning Fix + +작성일: 2026-04-26 12:11 KST + +## 요청 요약 + +- `npm run build` 시 반복되던 `/sprites/player.png referenced in /sprites/player.png didn't resolve at build time` 경고를 해결한다. +- 필요하다면 Skybound의 Stylized Casual Magitech 톤앤매너에 맞는 플레이어 기체 이미지를 새로 준비한다. + +## 원인 + +경고의 원인은 실제 플레이 중 사용되는 Canvas 렌더링이 아니라, 선택 화면 CSS에서 존재하지 않는 `/sprites/player.png`를 참조하고 있었기 때문이다. + +문제 위치는 `src/App.css`의 아래 클래스였다. + +- `.plane-preview.falcon` +- `.plane-preview.rayce` + +현재 프로젝트에는 `/sprites/player.png`가 없고, 실제 준비된 기체 에셋은 아래 파일이다. + +- `/sprites/Falcon.png` +- `/sprites/rayce.png` + +따라서 새 이미지를 생성하기보다, 이미 톤앤매너에 맞춰 준비된 실제 기체 에셋으로 경로를 정리하는 것이 적절했다. + +## 적용한 변경 + +### Falcon 미리보기 경로 수정 + +`/sprites/player.png`를 `/sprites/Falcon.png`로 교체했다. + +### Rayce 미리보기 경로 수정 + +Rayce도 같은 `player.png`에 `hue-rotate`를 걸어 임시로 표현하고 있었기 때문에, 실제 `/sprites/rayce.png`를 직접 사용하도록 바꿨다. + +또한 임시 색상 변환 필터를 제거했다. + +## 설계 의도 + +선택 화면은 사용자가 처음 기체의 정체성을 보는 곳이기 때문에, 존재하지 않는 공용 `player.png`나 임시 색상 변환보다 실제 기체별 에셋을 보여주는 편이 상품성 측면에서 낫다. + +이번 수정으로 다음 효과가 있다. + +- Vite 빌드 경고 제거 +- Falcon/Rayce 선택 화면 미리보기 정확도 개선 +- 임시 에셋 참조 제거 +- 기존 Stylized Casual Magitech 기체 에셋 재사용 + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/App.css` + +## 검증 + +- `npm run build` 성공 +- 기존 `/sprites/player.png` Vite 경고 사라짐 +- 출력 디렉터리: `dist/21` + +## 후속 작업 제안 + +- 선택 화면의 기체 미리보기를 정적 배경 이미지가 아니라, Canvas 렌더러와 동일한 축소 프리뷰 컴포넌트로 통일한다. +- Falcon/Rayce의 실제 플레이 성능 차이가 UI 문구와 정확히 대응되는지 점검한다. +- 선택 화면도 현재 게임 HUD/UI 톤과 완전히 맞도록 한 번 더 정리한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Skill_Slot_Limit_Weapon5_Passive5.md b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Skill_Slot_Limit_Weapon5_Passive5.md new file mode 100644 index 00000000..fb8645dc --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Skill_Slot_Limit_Weapon5_Passive5.md @@ -0,0 +1,136 @@ +# Skybound Skill Slot Limit Weapon 5 Passive 5 + +작성일: 2026-04-26 13:29 KST + +## 요청 요약 + +- 사용자가 획득할 수 있는 스킬 수량에 제한을 둔다. +- 총 10개 스킬을 보유할 수 있게 한다. +- 10개 중 5개는 무기, 5개는 패시브로 분리한다. +- 슬롯이 부족한 상태에서 새 스킬을 선택하려 하면 `슬롯이 부족합니다`에 해당하는 노티가 필요하다. +- 슬롯 제한 때문에 사용하지 못하는 스킬이 목록에 나올 수 있으므로 `Skip Upgrade` 선택지도 계속 필요하다. +- 5/5 구조가 적절한지 검토한다. + +## 판단 + +현재 Skybound에는 무기와 패시브 풀이 이미 넓고, 8스테이지까지 성장해야 한다. + +따라서 지금 시점에서는 `무기 5개 + 패시브 5개`가 적절하다. + +더 줄이는 선택지도 가능하지만, 아직은 권장하지 않는다. + +- 4/4는 빌드 정체성이 더 강해지는 대신 초반 선택 운 영향이 커진다. +- 5/5는 Survivor.io/Vampire Survivors류의 성장 폭과 전략성을 적당히 유지한다. +- 6/6 이상은 사용자가 거의 모든 것을 들고 가는 느낌이 강해져 빌드 선택 의미가 약해진다. + +그래서 이번 패스에서는 5/5를 기본값으로 적용했다. + +## 적용한 변경 + +### Skill Slot Limit 추가 + +`skills.ts`에 슬롯 제한 상수를 추가했다. + +```ts +export const SKILL_SLOT_LIMITS = { + WEAPON: 5, + PASSIVE: 5, +} +``` + +이제 시스템 전반에서 동일한 기준을 사용한다. + +### 후보 생성 필터링 + +`ProgressionSystem.generateSkillCards()`와 `generateMiniBossRewardCards()`에서 슬롯 제한을 반영했다. + +규칙: + +- 이미 보유한 스킬은 계속 레벨업 가능하다. +- 새 무기 획득은 무기 슬롯이 5개 미만일 때만 가능하다. +- 새 패시브 획득은 패시브 슬롯이 5개 미만일 때만 가능하다. +- 슬롯이 꽉 찬 타입의 새 스킬은 정상 후보 생성에서 제외한다. + +### 선택 시 슬롯 부족 방어 + +혹시 예외 경로로 선택 불가 카드가 들어오거나, UI/엔진 동기화 타이밍 문제로 새 스킬 선택이 들어올 수 있다. + +그래서 `ProgressionSystem.applySkillSelection()`에도 최종 방어를 추가했다. + +슬롯이 부족하면: + +- 스킬을 추가하지 않는다. +- 게임을 재개한다. +- 전투 화면에 `WEAPON SLOTS FULL` 또는 `PASSIVE SLOTS FULL` 텍스트를 띄운다. +- 보조 텍스트로 `Choose another module or skip`을 띄운다. + +### Store 레벨 방어 + +`useGameStore.addSkill()`에도 동일한 슬롯 제한 방어를 추가했다. + +이유: + +- UI나 엔진 외부에서 `addSkill()`이 호출되더라도 잘못된 스킬이 저장되지 않게 하기 위함이다. +- `__skip__`도 기존처럼 저장되지 않는다. + +### Level Up UI 슬롯 상태 표시 + +`LevelUpModal` 상단에 현재 슬롯 상태를 표시한다. + +표시: + +- `Weapons 0/5` +- `Passives 0/5` + +슬롯이 가득 차면 해당 배지가 붉은 톤으로 바뀐다. + +### SLOT FULL 카드 표시 + +정상 후보 생성에서는 사용 불가 카드가 거의 나오지 않지만, 예외적으로 pre-generated cards나 fallback 상태에서 들어올 수 있다. + +이 경우 카드에 다음 표시를 추가했다. + +- `SLOT FULL` 태그 +- `No empty weapon/passive slot` 설명 +- `WEAPON slots are full` 또는 `PASSIVE slots are full` + +사용자는 이때 새로 추가된 `Skip Upgrade`를 선택해 넘길 수 있다. + +## 설계 의도 + +슬롯 제한의 핵심은 빌드 선택을 더 전략적으로 만드는 것이다. + +제한이 없으면 사용자는 결국 대부분의 무기와 패시브를 다 들고 가게 되고, 선택의 의미가 약해진다. + +5/5 구조에서는 다음 판단이 생긴다. + +1. 무기 슬롯 하나를 새 무기에 쓸 것인가? +2. 기존 무기 레벨업을 기다릴 것인가? +3. 패시브 슬롯을 EVO 재료에 쓸 것인가? +4. 생존 패시브를 포기하고 공격 패시브를 가져갈 것인가? +5. 지금 후보가 별로면 스킵할 것인가? + +이번 변경은 `Skip Upgrade`의 존재 이유도 더 명확하게 만든다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/skills.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/store/useGameStore.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ProgressionSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.tsx` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.css` + +## 검증 + +- `npm run build` 성공 +- `/sprites/player.png` 경고 없음 +- 출력 디렉터리: `dist/28` + +## 후속 플레이테스트 체크 포인트 + +- 무기 5개를 보유한 상태에서 새 무기 후보가 정상 레벨업 목록에서 제외되는지 확인한다. +- 패시브 5개를 보유한 상태에서 새 패시브 후보가 정상 레벨업 목록에서 제외되는지 확인한다. +- 이미 보유한 무기/패시브는 슬롯이 가득 차도 레벨업 가능한지 확인한다. +- 예외적으로 `SLOT FULL` 카드가 보일 때 선택하면 슬롯 부족 노티가 뜨는지 확인한다. +- `Skip Upgrade`가 슬롯 제한 상황에서 자연스러운 탈출구로 작동하는지 확인한다. +- 5/5가 너무 넉넉하거나 너무 답답하지 않은지 확인한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Skip_Upgrade_and_Weapon_Transform_Reconfiguration.md b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Skip_Upgrade_and_Weapon_Transform_Reconfiguration.md new file mode 100644 index 00000000..f0e198a3 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Skip_Upgrade_and_Weapon_Transform_Reconfiguration.md @@ -0,0 +1,150 @@ +# Skybound Skip Upgrade and Weapon Transform Reconfiguration + +작성일: 2026-04-26 13:25 KST + +## 요청 요약 + +- Tactical Level Up 화면에서 마음에 들지 않는 업그레이드만 나올 수 있다. +- 이 경우 사용자가 강제로 원하지 않는 업그레이드를 고르지 않도록 `업글 안하기` 선택지를 추가한다. +- 새로운 무기가 장착되었을 때 사용자의 기체 외형도 그에 맞춰 변화해야 한다. +- 연출적으로는 트랜스포머처럼 기체가 재구성되고 무장이 전개되는 느낌을 표현한다. + +## 핵심 문제 + +기존 레벨업 화면은 반드시 하나의 스킬을 선택해야 했다. + +이 구조의 문제: + +1. 현재 빌드와 맞지 않는 선택지만 나와도 강제로 선택해야 한다. +2. 낮은 레벨 우선 후보 확률을 적용한 뒤에는 사용자가 원치 않는 저레벨/새 무기가 뜰 가능성도 생긴다. +3. 새 무기를 획득해도 기체가 실제로 바뀌는 느낌이 약하다. +4. 무기가 생긴 순간의 시각적 보상이 부족하다. + +## 적용한 변경 + +### Skip Upgrade 선택지 추가 + +`LevelUpModal`에 `Skip Upgrade` 카드를 추가했다. + +동작: + +- STARTER 첫 무기 선택에서는 스킵이 나오지 않는다. +- 일반 Tactical Upgrade, Supply, Command Cache에서는 스킵 가능하다. +- 스킵을 선택하면 스킬/무기 레벨이 증가하지 않고 전투로 복귀한다. + +표시 문구: + +- `HOLD UPGRADE` +- `Skip Upgrade` +- `No change this time` + +### Skip 안전 처리 + +`__skip__`이 실제 스킬처럼 저장되지 않도록 여러 지점에 방어를 추가했다. + +적용 지점: + +- `GameSceneRenderer` +- `ProgressionSystem` +- `useGameStore.addSkill` + +`__skip__`이 선택되면: + +- Zustand `skills`에 추가하지 않는다. +- 엔진 스킬 상태에도 추가하지 않는다. +- `TACTICAL UPGRADE HELD` 텍스트를 띄운다. +- 게임 pause를 해제하고 전투를 재개한다. + +### 새 무기 장착 감지 + +`ProgressionSystem.applySkillSelection()`에서 선택 직전 스킬 레벨을 확인한다. + +조건: + +- 선택한 스킬이 `WEAPON` 타입 +- 선택 직전 레벨이 0 + +이 조건을 만족할 때만 새 무기 장착 연출을 발동한다. + +기존 무기 레벨업이나 패시브 선택은 변신 연출을 발동하지 않는다. + +### Airframe Reconfiguration 상태 추가 + +`GameState`에 새 무기 장착 연출용 상태를 추가했다. + +추가 필드: + +- `weaponTransformStartFrame` +- `weaponTransformDuration` +- `weaponTransformSkillId` + +이 값은 렌더러가 현재 프레임 기준으로 변신 진행도를 계산하는 데 사용한다. + +### 기체 변신/무장 전개 연출 추가 + +`GameRenderer.renderPlayer()`에 새 무기 장착 연출을 추가했다. + +연출 요소: + +- 기체 중심에서 확장되는 아케인 스캔 링 +- 무기 색상별 발광 +- 좌우 장갑 패널이 바깥으로 접히듯 전개 +- 전방 무장 레일이 앞으로 돌출 +- 작은 locking spark +- `WEAPON LINK: 무기명` +- `AIRFRAME RECONFIGURING` +- 화면 흔들림과 파티클 + +무기별 액센트 컬러: + +- Gatling Gun: 골드 +- Missile Pod: 핑크/레드 +- Nova Burst: 시안 +- Energy Shield: 라임 +- Sweep Laser: 화이트/시안 +- Plasma Torpedo: 오렌지 +- Ion Storm: 전기 시안 +- Attack Drone: 라임 +- Gravity Mine: 퍼플 +- Plasma Fire: 오렌지/레드 +- Plasma Blade: 시안 + +## 설계 의도 + +이번 변경은 업그레이드 UX에 “선택하지 않을 권리”를 추가하는 작업이다. + +업그레이드는 항상 이득처럼 보여야 하지만, 빌드 방향과 맞지 않는 선택을 강제하면 사용자는 선택권을 잃었다고 느낄 수 있다. + +스킵 선택지는 다음 의미를 가진다. + +1. 원하지 않는 업그레이드를 강제로 먹지 않는다. +2. 빌드 순도를 유지할 수 있다. +3. 낮은 레벨 우선 후보 시스템의 부작용을 완화한다. +4. 선택 화면에서 사용자 판단 여지를 높인다. + +새 무기 변신 연출은 “새 기능이 생겼다”를 UI 문구가 아니라 기체 자체 변화로 전달하기 위한 장치다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/store/useGameStore.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ProgressionSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/GameRenderer.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/types.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/GameSceneRenderer.tsx` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.tsx` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.css` + +## 검증 + +- `npm run build` 성공 +- `/sprites/player.png` 경고 없음 +- 출력 디렉터리: `dist/27` + +## 후속 플레이테스트 체크 포인트 + +- 일반 레벨업 화면에서 `Skip Upgrade`가 명확하게 보이는지 확인한다. +- STARTER 첫 무기 선택에서는 스킵이 나오지 않는지 확인한다. +- 스킵 선택 시 게임이 정상 재개되는지 확인한다. +- 스킵 선택 후 `skills.__skip__` 같은 잘못된 값이 저장되지 않는지 확인한다. +- 새 무기를 처음 선택했을 때 기체 변신 연출이 충분히 눈에 띄는지 확인한다. +- 기존 무기 레벨업/패시브 선택 시 변신 연출이 과하게 반복되지 않는지 확인한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Stage1_to_3_Playtest_Balance_Bomb_and_Visual_Diversity_Pass.md b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Stage1_to_3_Playtest_Balance_Bomb_and_Visual_Diversity_Pass.md new file mode 100644 index 00000000..bfb623f0 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/2026-04-26-Skybound_Stage1_to_3_Playtest_Balance_Bomb_and_Visual_Diversity_Pass.md @@ -0,0 +1,205 @@ +# Skybound Stage 1 to 3 Playtest Balance Bomb and Visual Diversity Pass + +작성일: 2026-04-26 12:35 KST + +## 요청 요약 + +- Stage 1부터 Stage 3까지 실제 플레이 후 느낀 문제를 개선한다. +- Stage 1 초반 적 탄속이 부담스럽고, 중반 이후 성장하면 너무 쉬워지는 문제를 조정한다. +- Stage 2 시작 시 이미 Tac Level 6 정도로 강해져 적이 화면에 들어오기 전에 사망하는 문제를 완화한다. +- Space/X 폭탄의 비주얼 이펙트가 약하므로 톤앤매너에 맞는 폭탄 연출을 강화한다. +- 일반 적, 엘리트, 미니보스, 보스 외형 다양성을 확보한다. + +## 핵심 문제 + +플레이 피드백 기준으로 Skybound의 현재 문제는 초반과 중반의 난이도 감각이 반대로 작동한다는 점이었다. + +1. Stage 1 초반은 적 탄속이 빠르게 느껴져 부담스럽다. +2. Stage 1 중반부터 스킬이 붙으면 플레이어 화력이 너무 급격히 상승한다. +3. Stage 2에서는 적이 화면에 들어오기 전에 사망해 긴장감이 사라진다. +4. Tac Level 성장 속도와 무기 효율이 합쳐져 “이미 완성된 빌드”처럼 느껴진다. +5. 보스/적기 외형 반복으로 스테이지 진행감이 약하다. + +## 적용한 변경 + +### Stage 1 적 탄속 완화 + +`balance.ts`의 적 탄환 기본 속도와 스테이지별 탄속 커브를 낮췄다. + +변경 전: + +- `BULLET_BASE_SPEED: 3.75` +- `BULLET_SPEED_CURVE: [1.1, 1.28, 1.48, ...]` + +변경 후: + +- `BULLET_BASE_SPEED: 3.25` +- `BULLET_SPEED_CURVE: [0.82, 0.96, 1.12, ...]` + +Stage 1은 회피를 학습할 수 있는 속도로 낮추고, Stage 4 이후부터 탄속이 본격적으로 올라가도록 재배치했다. + +### 적 사격 템포 완화 + +초반 탄막 부담을 줄이기 위해 `FIRE_RATE_CURVE`도 조정했다. + +변경 후: + +- `[280, 248, 222, 198, 176, 154, 134, 116]` + +Stage 1-2는 더 읽을 수 있게 만들고, 후반 스테이지는 기존처럼 빠르게 압박하도록 유지했다. + +### Tac Level 성장 속도 완화 + +Tac Level이 Stage 1 중반에 너무 빨리 누적되지 않도록 조정했다. + +- 시작 요구 EXP: `80` → `100` +- 레벨업 후 초과 EXP carryover: `25%` → `15%` +- 레벨업 lockout: `360프레임` → `480프레임` +- 일반 적 Tac EXP: `2` → `1` +- 엘리트 Tac EXP: `10` → `8` +- 미니보스 Tac EXP: `30` → `24` + +목표는 Stage 2 시작 시 플레이어가 강해졌다는 느낌은 가지되, 이미 완성된 상태는 아니게 만드는 것이다. + +### 플레이어 무기 초중반 효율 완화 + +무기 업그레이드가 의미는 있지만, Lv1-3에서 화면 전체를 지우지 않도록 주요 피해량을 조정했다. + +- Gatling Gun 피해와 발사 효율 하향 +- Hyper Laser 피해 하향 +- Nova Burst 피해 하향 +- Missile Pod, Rocket Launcher, Ion Storm, Gravity Mine, Blade Orbit 등 데이터 기반 무기 피해 하향 +- EVO 무기도 일부 피해를 낮춰 Stage 2-3을 통째로 삭제하지 않게 조정 + +### 화면 밖 적 선삭제 방지 + +Stage 2에서 적이 화면에 나오기도 전에 사망하는 가장 큰 원인은 자동 조준/유도/빔/드론/오비트 무기가 `y < 0`에 있는 적까지 타겟팅하거나 피해를 주는 것이었다. + +그래서 플레이어 무기 타겟팅과 충돌 판정에 `TARGETABLE_Y = -35` 기준을 추가했다. + +적이 화면에 거의 진입하기 전까지는 다음 무기가 타겟팅하지 않는다. + +- 유도탄 +- 자동 조준 무기 +- 빔 +- 오비트 무기 +- 드론 +- 설치/장판 무기 +- 일반 플레이어 탄환 충돌 + +이제 적이 화면에 들어와 위협을 보여준 뒤 처치되는 흐름이 만들어진다. + +### Stage 2-3 압박 보강 + +Stage 2와 Stage 3은 이미 성장한 플레이어를 전제로 난이도를 다시 올렸다. + +Stage 2: + +- `diffBase: 1.02` → `1.12` +- `capBase: 23` → `28` +- `spawnTempo: 0.94` → `0.86` +- opening density: `10` → `14` + +Stage 3: + +- `diffBase: 1.14` → `1.28` +- `capBase: 28` → `34` +- `spawnTempo: 0.88` → `0.78` +- opening density: `12` → `16` + +### 적 HP 스케일링 보강 + +일반/엘리트 적이 스킬 몇 개에 바로 삭제되지 않도록 기본 HP 공식을 조정했다. + +추가 요소: + +- 스테이지별 HP 증가 +- 플레이어가 예상보다 높은 Tac Level일 때 적 HP 보정 +- 엘리트 HP 배율 상향 + +이 보정은 플레이어가 잘 성장했을 때도 적이 최소한 화면에 들어와 압박을 만들도록 하기 위한 안전장치다. + +### 폭탄 비주얼 개선 + +기존 폭탄은 얇은 원형 렌더링에 가까워 비주얼 피드백이 약했다. 이제 폭탄 사용 시 발동 위치를 저장하고, 그 지점에서 Magitech shockwave가 확장된다. + +추가된 연출: + +- 고정된 폭발 원점 +- 시안/라임/골드 3중 마법공학 링 +- 점선 링 회전 +- 중심 코어 플래시 +- 방사형 에너지 라인 +- 밝은 라디얼 플래시 + +Space/X를 눌렀을 때 “화면을 정리하는 기술”이라는 감각이 더 강해지도록 했다. + +### 적기 외형 다양성 개선 + +기존 적기 스프라이트 선택은 역할별 고정값이 많아 반복감이 컸다. 이제 역할과 스테이지, 약간의 랜덤 salt를 반영해 더 다양한 스프라이트를 선택한다. + +적용 대상: + +- 일반 적 +- 엘리트 적 +- 미니보스 + +미니보스는 패턴별로 크기와 발광색도 달라져 작은 보스전처럼 보이게 했다. + +### 보스 외형 다양성 개선 + +보스는 `spriteIdx`가 명시되지 않아 사실상 같은 보스 타일만 반복 사용되는 문제가 있었다. 이제 스테이지별 보스 비주얼 프로필을 갖는다. + +프로필 요소: + +- 보스 스프라이트 인덱스 +- 보스 크기 +- 보스 가로/세로 비율 +- 날개 포탑 위치 +- 하단 포탑 위치 +- 발광 액센트 색상 + +이제 Stage 1-8 보스는 같은 시스템을 쓰더라도 외형, 크기, 포탑 배치가 다르게 보인다. + +## 설계 의도 + +이번 패스의 핵심은 “초반은 읽기 쉽게, 중반은 무적감이 너무 빨리 오지 않게” 만드는 것이다. + +원하는 플레이 감각은 다음과 같다. + +1. Stage 1 초반: 탄을 보고 피하는 법을 배운다. +2. Stage 1 중반: 첫 빌드가 강해지는 재미를 느낀다. +3. Stage 1 후반: 미니보스와 보스로 빌드 검증을 한다. +4. Stage 2: 성장한 상태지만 적도 더 빨리/많이 들어와 다시 긴장감이 생긴다. +5. Stage 3: 단일 무기 강화만으로는 부족하고 광역/방어/관통 선택의 의미가 생긴다. + +## 수정 파일 + +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/CombatTimeline.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/balance.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/weaponBehaviors.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/store/useGameStore.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/CombatSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/GameRenderer.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ModularWeaponSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/PlayerSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ProgressionSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/SpawnerSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/StageDirectorSystem.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/WeaponBehaviorEngine.ts` +- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/types.ts` + +## 검증 + +- `npm run build` 성공 +- `/sprites/player.png` 경고 없음 +- 출력 디렉터리: `dist/22` + +## 후속 플레이테스트 체크 포인트 + +- Stage 1 첫 60초 탄속이 “부담스럽지만 불공정하지 않은지” 확인한다. +- Stage 1 후반 Tac Level이 대략 3-5 사이인지 확인한다. +- Stage 2 시작 시 적이 화면 안에 들어오기 전에 삭제되는 현상이 줄었는지 확인한다. +- Space/X 폭탄 사용 시 충분히 강한 시각 피드백이 있는지 확인한다. +- Stage 1-3 보스가 서로 다른 외형과 크기로 인식되는지 확인한다. +- Stage 2-3에서 피격 압박은 생겼지만, 갑자기 불합리하게 어려워지지는 않았는지 확인한다. diff --git a/10_Wiki/Topics/Frontend_Mastery/Accessibility (A11y).md b/10_Wiki/Topics/Frontend_Mastery/Accessibility (A11y).md new file mode 100644 index 00000000..0b6b7ec6 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/Accessibility (A11y).md @@ -0,0 +1,31 @@ +# [[Accessibility (A11y)]] + +## 📌 Brief Summary +접근성(Accessibility, A11y)은 스크린 리더, 키보드 네비게이션 등을 지원하여 모든 사용자가 차별 없이 UI를 이용할 수 있도록 하는 설계 원칙 및 기능입니다 [1, 2]. React 컴포넌트 아키텍처와 디자인 시스템에서 재사용성은 접근성과 뗄 수 없는 관계를 가지며, ARIA 속성 및 시맨틱 HTML 적용을 기본으로 합니다 [3, 4]. 잘 설계된 컴포넌트 라이브러리와 아키텍처 패턴은 개발자가 처음부터 접근성을 구현할 필요 없이, 접근성 테마 모드나 포커스 관리 등과 같은 내장된 접근성 지원을 제공합니다 [1, 5, 6]. + +## 📖 Core Content + +* **재사용 가능한 컴포넌트와 접근성 우선(Accessibility First) 원칙** + 재사용 가능한 컴포넌트를 설계할 때 접근성은 선택 사항이 아니라 필수 사항입니다 [2]. 키보드 탭 순서 관리, 화살표 키 탐색, 올바른 시맨틱 HTML 역할(Roles)과 레이블, 포커스 제어 및 오류 메시지 제공 등은 컴포넌트의 핵심 기능에 내장(Bake into the DNA)되어야 합니다 [2, 6]. 컴포넌트가 진화하더라도 접근성 역할, 레이블, 포커스 상태가 깨지지 않는지 확인하기 위해 지속적인 접근성 검사(Accessibility checks)가 필요합니다 [7]. + +* **아키텍처 패턴을 통한 접근성 구현** + * **Compound Components:** 부모 컴포넌트(예: Accordion)가 자식 컴포넌트들의 상태를 제어하는 방식은 접근성 구현을 단순하게 만듭니다. 컨텍스트를 통해 내부 상태를 공유하기 때문에, 사용자가 명시적으로 ID를 전달하지 않아도 `aria-controls`와 `aria-labelledby` 같은 속성을 자동으로 연결해 줄 수 있습니다 [8]. + * **Headless Components:** 이 패턴은 상태 관리, 로직, 그리고 접근성 기능(키보드 네비게이션, ARIA 역할 등)을 내장하여 제공하되, 스타일링은 개발자가 Tailwind CSS 등으로 자유롭게 구성하도록 맡기는 방식으로 현대적이고 접근성이 뛰어난 UI 구축에 활용됩니다 [9]. + +* **디자인 시스템 및 테마 기반 접근성** + 디자인 토큰을 기반으로 한 테마 시스템은 접근성 요구 사항을 유연하게 수용할 수 있습니다 [5, 10]. 예를 들어, 디자인 테마는 다크 모드뿐만 아니라 모든 요소를 더 눈에 띄게 만드는 고대비(High-contrast) 테마나 제한된 움직임(Limited movement)과 같은 사용자 기본 설정에 맞춰 동적으로 조정될 수 있습니다 [5, 10, 11]. + +* **주요 라이브러리 및 도구의 접근성 지원의 차이** + * Shopify의 Polaris와 Uber의 Base Web과 같은 최신 라이브러리는 키보드 내비게이션, ARIA 역할, 스크린 리더 호환성 및 WCAG 표준 준수를 기본 기능으로 제공합니다 [1, 3, 12, 13]. + * 반면 Tailwind CSS와 같은 유틸리티 우선 프레임워크는 스타일링에 특화되어 있어 자동으로 `aria-*` 속성이나 시맨틱 HTML 요소로 변경해주지 않습니다 [4]. 따라서 Tailwind CSS를 사용할 때는 개발자가 올바른 ARIA 속성과 시맨틱 마크업을 명시적으로 포함해야 합니다 [4]. + +* **대규모 접근성 문서화 및 관리 자동화** + Uber와 같은 대규모 환경에서는 VoiceOver, TalkBack, ARIA와 같은 3가지 접근성 API를 커버해야 하며, 각각 수백 개의 속성이 존재하기 때문에 수동으로 스펙을 관리하기 어렵습니다 [14]. 이를 해결하기 위해 AI 에이전트(Figma Console MCP 활용)를 도입하여 컴포넌트 트리를 스크랩하고 다중 플랫폼의 스크린 리더 및 접근성 속성을 단 몇 분 만에 포괄적인 스펙 문서로 자동 렌더링하는 자동화 파이프라인을 구축하여 접근성 기준을 유지합니다 [15-18]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Compound Components]], [[Headless Components]], [[Design Tokens]], [[Tailwind CSS]] +- **Projects/Contexts:** [[Uber Base Web]], [[Shopify Polaris]], [[React Component Library Architecture]] +- **Contradictions/Notes:** 컴포넌트 레벨에서의 접근성 내장 여부에서 프레임워크 간 차이가 발생합니다. Shopify Polaris나 Uber Base Web 등의 완전한 UI 컴포넌트 라이브러리는 ARIA 및 키보드 조작과 같은 접근성을 기본으로 제공하지만 [1, 3, 12], Tailwind CSS를 단독으로 사용할 경우 자동으로 접근성 태그를 부여하지 않으므로 개발자가 직접 시맨틱 마크업과 ARIA 속성을 챙겨야 한다는 명확한 한계(책임의 전가)를 지적하고 있습니다 [4]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/10_Wiki/Topics/Frontend_Mastery/Accessibility.md b/10_Wiki/Topics/Frontend_Mastery/Accessibility.md new file mode 100644 index 00000000..372ee2c6 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/Accessibility.md @@ -0,0 +1,21 @@ +# [[Accessibility]] + +## 📌 Brief Summary +접근성(Accessibility, A11y)은 장애 여부나 기기 환경에 관계없이 모든 사용자가 인터페이스를 원활하게 이용할 수 있도록 보장하는 핵심 설계 원칙이다 [1]. 확장 가능한 React 컴포넌트 아키텍처에서는 재사용성을 확보하기 위해 ARIA 역할(roles), 키보드 탐색, 포커스 관리, 화면 판독기(Screen-reader) 지원 등을 컴포넌트 단계에서 기본적으로 내장해야 한다 [1-3]. + +## 📖 Core Content +- **재사용 가능한 컴포넌트의 필수 조건**: 접근성은 디자인 완료 후 나중에 추가하는 것이 아니라 '최우선(First-Class)'으로 컴포넌트의 DNA에 내장되어야 한다 [1, 3]. 접근성을 나중에 덧붙이는 방식(afterthought)으로 처리하면 비용과 수고가 두 배로 든다 [4]. 상호작용 요소에는 적절한 시맨틱 태그, 역할(roles), 라벨, 포커스 관리 및 키보드 탐색(Tab, 화살표 키, Home/End 등) 기능이 필수적으로 포함되어야 한다 [1, 3, 5]. +- **디자인 토큰과 시스템을 통한 접근성 향상**: 디자인 토큰 기반의 테마 시스템을 적용하면 고대비(high-contrast) 모드나 모션 감소(limited movement)와 같이 다양한 사용자 선호도 및 접근성 요구 사항에 맞춰 인터페이스를 쉽게 조정할 수 있다 [6]. +- **스타일링 도구 및 아키텍처 패턴의 접근성 처리**: + - **Tailwind CSS**: 유틸리티 클래스를 통한 시각적 스타일링은 매우 빠르지만, ARIA 속성이나 시맨틱 HTML을 자동으로 추가해 주지 않는다는 단점이 있다 [7]. 따라서 개발자가 항상 적절한 ARIA 속성과 시맨틱 요소를 직접 추가하는 것이 주요 모범 사례(Best Practice)로 꼽힌다 [8]. + - **Headless UI 패턴**: Radix UI나 Headless UI와 같은 라이브러리는 복잡한 상태 관리와 접근성 기능을 기본적으로 제공하면서 스타일링 권한만 개발자에게 위임하므로, 브랜드 맞춤형이면서도 완벽한 접근성을 갖춘 UI 시스템을 구축하는 데 매우 유리하다 [9]. + - **복합 컴포넌트(Compound Components)**: 컴포넌트 내부 컨텍스트(Context)를 공유함으로써 사용자가 직접 ID를 조작하지 않아도 `aria-controls`나 `aria-labelledby`를 자동으로 연결하여 접근성 적용을 단순화할 수 있다 [10]. +- **대규모 엔터프라이즈의 접근성 관리 (Uber 및 Shopify 사례)**: Shopify의 Polaris 디자인 시스템과 Uber의 Base Web은 키보드 탐색과 화면 판독기 지원을 핵심 기능으로 제공한다 [2, 11, 12]. 특히 Uber는 VoiceOver, TalkBack, ARIA 역할 등 여러 접근성 API의 수백 가지 속성을 정확하게 유지하기 위해, AI 에이전트를 통해 Figma 디자인 파일에서 즉각적으로 스펙(Spec) 문서를 자동 생성하는 시스템을 구축해 규모의 한계를 극복했다 [13-16]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Headless Components]], [[Compound Components]], [[Design Tokens]], [[Tailwind CSS]] +- **Projects/Contexts:** [[Shopify Polaris]], [[Uber Base Web]], [[Radix UI]] +- **Contradictions/Notes:** 소스는 복합 컴포넌트(Compound Components) 패턴이 ARIA 속성 자동 연결 등을 통해 접근성을 개선해 주지만 [10], 사용자에게 너무 많은 유연성을 부여할 경우 하위 컴포넌트의 순서를 임의로 변경하거나 누락하여 오히려 접근성과 UX를 손상시킬 수 있다고 경고한다 [17]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/10_Wiki/Topics/Frontend_Mastery/Accessible UI Libraries.md b/10_Wiki/Topics/Frontend_Mastery/Accessible UI Libraries.md new file mode 100644 index 00000000..3af14b57 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/Accessible UI Libraries.md @@ -0,0 +1,28 @@ +# [[Accessible UI Libraries]] + +## 📌 Brief Summary +접근성(Accessibility, A11y)을 기본적으로 갖춘 UI 라이브러리는 스크린 리더 호환성, 키보드 내비게이션, ARIA 속성 등을 내장하여 모든 사용자가 포용적으로 사용할 수 있도록 설계된 컴포넌트 모음입니다 [1-3]. Shopify의 Polaris, Uber의 Base Web, Chakra UI, Headless UI(Radix UI 등) 등이 대표적이며, 이러한 라이브러리들은 확장 가능한 프론트엔드 환경에서 재사용 가능한 UI를 구축할 때 필수적인 역할을 합니다 [2, 4, 5]. 이들을 활용하면 팀이 처음부터 접근성 규칙을 구현하는 시간을 절약하고, 누구나 쉽게 접근 가능한 일관된 사용자 경험(UX)을 제공할 수 있습니다 [6-8]. + +## 📖 Core Content +* **주요 접근성 내장 UI 라이브러리 및 특징:** + * **Chakra UI:** ARIA 호환성을 기본적으로 갖추고 있으며, 키보드 내비게이션과 스크린 리더 사용을 완벽하게 지원하도록 설계되어 포용적인 애플리케이션을 구축하는 데 유리합니다 [2]. + * **Shopify Polaris:** WCAG 표준을 따르며 적절한 색상 대비, 키보드 내비게이션, 스크린 리더 호환성을 제공합니다 [9]. 또한 ARIA 라벨과 같은 접근성 기능이 사전 구축된 컴포넌트로 제공됩니다 [7]. + * **Uber Base Web:** 키보드 내비게이션이 안정적으로 작동하고 스크린 리더와 잘 호환되도록 보장하여, 개발자가 모든 방문자에게 적합한 제품을 구축할 수 있게 돕습니다 [1, 4]. + * **Foundation:** 기본적으로 접근성이 내장되어 있으며, 모든 코드 스니펫에 ARIA 속성이 포함되어 제공되므로 기기나 사용자의 능력에 관계없이 훌륭한 경험을 보장합니다 [3]. + * **Headless UI (Radix UI 등):** 복잡한 컴포넌트(드롭다운, 다이얼로그 등)에 대해 상태 관리 및 접근성 기능만 제공하고 스타일링은 개발자에게 완전히 일임합니다 [5]. Tailwind CSS와 결합하면 높은 접근성과 브랜드 특화된 UI 라이브러리를 구축하는 데 강력한 힘을 발휘합니다 [5]. + +* **재사용 가능한 UI 컴포넌트와 접근성(A11y)의 중요성:** + * 재사용 가능한 컴포넌트 설계 시 '접근성 우선(Accessibility First)'은 타협할 수 없는 필수 요소입니다 [10]. 탭(Tab) 순서, 의미 있는 포커스 관리, 올바른 시맨틱 역할(Roles)과 라벨링은 기본적으로 컴포넌트 DNA에 포함되어야 합니다 [10, 11]. + * 접근성이 확보된 컴포넌트는 팀이 접근성을 처음부터 다시 고민하지 않고도 자신 있게 소프트웨어를 출시할 수 있는 가속기(Accelerator) 역할을 합니다 [6]. + +* **규모에 따른 접근성 사양 유지의 과제와 자동화:** + * Uber와 같은 대규모 기업에서는 VoiceOver, TalkBack, ARIA 등 플랫폼별로 수백 개의 접근성 속성을 수동으로 유지·관리하는 데 한계가 있습니다 [12]. + * 이를 해결하기 위해 AI 에이전트와 Figma Console MCP를 연결하여 컴포넌트 구조를 스캔하고, 단 2분 만에 완벽한 스크린 리더 접근성 사양과 문서를 자동 생성하는 시스템(uSpec)을 구축하여 문서화 병목 현상을 해결했습니다 [13-15]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Headless Components]], [[Design Tokens & Theming]] +- **Projects/Contexts:** [[Shopify Polaris]], [[Uber Base Web]], [[Chakra UI]], [[Radix UI]] +- **Contradictions/Notes:** Tailwind CSS 자체는 강력한 유틸리티 기반 스타일링을 제공하지만, ARIA 속성이나 시맨틱 HTML을 자동으로 추가해주지는 않으므로 접근성을 간과하는 것이 흔한 함정(Pitfall)으로 지적됩니다. 따라서 Tailwind를 사용할 때는 반드시 시맨틱 요소를 직접 추가하거나, 접근성 기능이 내장된 Headless UI 라이브러리를 함께 사용하는 것이 권장됩니다 [5, 16]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/10_Wiki/Topics/Frontend_Mastery/Atomic Design.md b/10_Wiki/Topics/Frontend_Mastery/Atomic Design.md new file mode 100644 index 00000000..90133ca4 --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/Atomic Design.md @@ -0,0 +1,30 @@ +# [[Atomic Design]] + +## 📌 Brief Summary +Atomic Design(아토믹 디자인)은 브래드 프로스트(Brad Frost)가 고안한 디자인 방법론으로, 사용자 인터페이스(UI)를 응집력 있는 전체이자 부분의 집합으로 동시에 생각할 수 있게 해주는 멘탈 모델입니다 [1-3]. 이 방법론은 인터페이스를 원자(Atoms), 분자(Molecules), 유기체(Organisms), 템플릿(Templates), 페이지(Pages)라는 5개의 계층적 단계로 나누어 효과적이고 의도적인 디자인 시스템을 구축하도록 돕습니다 [4, 5]. React와 같은 모던 컴포넌트 아키텍처와 결합하여 일관성을 강제하고, 디자인 시스템의 재사용성을 높이며, 확장 가능한 폴더 구조를 구축하는 데 널리 활용됩니다 [6-8]. + +## 📖 Core Content +* **5단계의 컴포넌트 계층 구조**: + * **원자 (Atoms)**: 더 이상 쪼갤 수 없는 UI의 기본 구성 요소입니다 [1, 5]. HTML 태그(예: input, label, button)나 React의 기본 함수형 컴포넌트에 해당하며, 각기 고유한 속성을 가집니다 [9, 10]. + * **분자 (Molecules)**: 원자들의 결합으로 이루어진 비교적 단순한 UI 컴포넌트 그룹입니다(예: 라벨 + 입력창 + 버튼 = 검색 폼) [5, 10, 11]. 단일 책임 원칙(Single Responsibility Principle)을 장려하여 "한 가지 일을 잘 수행하도록" 함으로써 테스트와 재사용성을 용이하게 합니다 [12]. + * **유기체 (Organisms)**: 분자, 원자, 혹은 다른 유기체들로 구성된 복잡한 컴포넌트로, 인터페이스의 뚜렷한 독립적 섹션을 형성합니다(예: 웹사이트 헤더, 제품 그리드) [5, 10, 13, 14]. + * **템플릿 (Templates)**: 컴포넌트들을 레이아웃에 배치하고 디자인의 근본적인 콘텐츠 구조(뼈대)를 명확히 하는 페이지 레벨의 객체입니다 [5, 10, 15, 16]. 최종 콘텐츠보다는 기본 골격에 집중합니다 [16]. + * **페이지 (Pages)**: 템플릿에 실제 대표 콘텐츠를 주입한 구체적 인스턴스입니다. 최종 UI를 보여주고 기초 디자인 시스템의 효과와 복원력을 테스트하며 콘텐츠의 동적 변형(예: 데이터 길이에 따른 변화)을 명확히 합니다 [5, 10, 17-19]. + +* **Atomic Design의 핵심 이점 및 특징**: + * **맥락의 전환**: 추상적인 요소(원자)를 조작하는 동시에 그것들이 모여 구체적인 최종 결과물(페이지)에 미치는 영향을 빠르게 파악하고 테스트할 수 있도록 돕습니다 [20, 21]. + * **구조와 콘텐츠의 분리**: UI의 콘텐츠 구조 스켈레톤(템플릿)과 최종 콘텐츠(페이지) 사이의 깔끔한 분리를 제공하면서도 둘의 상호작용을 고려하게 합니다 [22, 23]. + * **보편적 적용성**: 웹 전용 기술(CSS, JavaScript 구조 등)에 국한되지 않으며, Instagram과 같은 네이티브 모바일 앱을 포함한 모든 소프트웨어 인터페이스 설계에 적용할 수 있습니다 [24-26]. + * **비선형적 접근**: 단순히 1단계에서 5단계로 순차적으로 진행하는 선형 프로세스가 아니라, 전체와 부분을 동시에 설계하기 위한 멘탈 모델로 접근해야 합니다 [1, 2]. + +* **React 확장성 및 아키텍처에서의 활용**: + * React의 컴포넌트 트리와 완벽하게 대칭을 이루어 디자인 시스템을 구축하는 근본적인 모델이 됩니다 [6]. + * 성공적인 엔터프라이즈 팀들은 원자 단위의 순수함과 재사용성을 유지하기 위해 UI 라이브러리 계층에는 Atomic Design을 활용하고, 비즈니스 로직이 들어가는 애플리케이션 코드에는 기능 분할 설계(Feature-Sliced Design, FSD) 등 기능 기반 구조를 혼합하여 설계합니다 [10, 27]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Component-Based Design]], [[Feature-Sliced Design (FSD)]], [[Compound Components]], [[Design Systems]] +- **Projects/Contexts:** [[React Frontend Architecture]], [[Reusable UI Component Libraries]] +- **Contradictions/Notes:** 소스에 따르면 Atomic Design은 시각적 일관성과 재사용성을 달성하는 데는 매우 강력하지만, 복잡한 비즈니스 로직을 가진 컴포넌트를 이 5가지의 엄격한 범주에 억지로 끼워 맞추려다 보면 어려움에 직면할 수 있다는 한계도 지적됩니다 [10]. 이에 대한 보완책으로 Headless UI나 Compound Components 패턴이 현대 프론트엔드 환경에서 함께 권장됩니다 [28, 29]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/10_Wiki/Topics/Frontend_Mastery/Building Reusable UI Components.md b/10_Wiki/Topics/Frontend_Mastery/Building Reusable UI Components.md new file mode 100644 index 00000000..4448880b --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/Building Reusable UI Components.md @@ -0,0 +1,33 @@ +# [[Building Reusable UI Components]] + +## 📌 Brief Summary +재사용 가능한 UI 컴포넌트는 여러 프로젝트와 위치에서 코드를 크게 수정하지 않고도 사용할 수 있는 독립적이고 이식성(Portable)과 예측 가능성(Predictable)이 뛰어난 UI 구성 요소입니다 [1]. 이는 단일 책임을 가지며 명확한 API(Props)와 접근성(Accessibility)을 갖추어 확장 가능하고 일관성 있는 디자인 시스템을 구축하는 핵심 역할을 합니다 [2, 3]. 최신 React 생태계에서는 복잡성을 줄이기 위해 단순한 Prop 전달을 넘어서, 컴파운드 컴포넌트나 헤드리스 컴포넌트와 같은 고급 합성 패턴을 활용하여 재사용성을 극대화합니다 [4, 5]. + +## 📖 Core Content +* **재사용 가능한 컴포넌트의 4가지 핵심 원칙 (Four Golden Rules)**: + * **단일 책임 (Single Responsibility):** 각 컴포넌트는 한 가지 기능만 잘 수행하도록 만들어 버그를 줄이고 재사용성을 높여야 합니다 [3]. + * **상속보다 합성 (Composition Over Inheritance):** 의견이 배제된(unopinionated) 기본 컴포넌트들을 블록처럼 조립하여 더 큰 컴포넌트를 구성해야 합니다 [3]. + * **명확한 계약 (Explicit Contracts):** 컴포넌트가 받는 값(Props)과 반환하는 이벤트(Callbacks)의 API를 명확히 정의하여 부작용을 방지해야 합니다 [3, 6]. + * **접근성 우선 (Accessibility First):** 키보드 내비게이션, ARIA 역할(Roles), 포커스 관리 등 스크린 리더 및 모든 사용자를 위한 접근성을 기본적으로 내장해야 합니다 [3, 7]. + +* **상태 관리 및 API 설계 (State Boundaries & API Design)**: + * Prop 기반의 API는 요구사항이 늘어날수록 수많은 상태 변수(Prop Soup)를 발생시켜 확장을 어렵게 만듭니다 [6, 8]. 의도에 맞는 Prop 이름을 사용하고 안전한 기본값(Defaults)을 설정해야 합니다 [6]. + * 툴팁 토글과 같은 로컬 UI 상태는 컴포넌트 내부에 유지하되, 필터링이나 데이터 호출과 같은 비즈니스 로직은 상위 부모 컴포넌트로 올려야(Push up) 재사용성이 높아집니다 [9]. + +* **재사용성을 극대화하는 고급 React 패턴 (Scalable Component Patterns)**: + * **컴파운드 컴포넌트 (Compound Components):** 아코디언(Accordion)이나 탭(Tabs)처럼 여러 하위 컴포넌트가 Context를 통해 암시적으로 상태를 공유하도록 구성하여, 소비자가 레이아웃을 유연하게 제어할 수 있게 합니다 [10-12]. + * **헤드리스 컴포넌트 (Headless Components):** 시각적인 마크업(UI) 없이 상태와 동작 로직만 제공하여, 디자인 시스템과 무관하게 접근성 높고 재사용 가능한 컴포넌트를 만들 수 있습니다 [13-15]. + * **렌더 프롭스 (Render Props):** 함수를 자식 요소로 전달하여 로직을 공유하고 렌더링에 대한 완전한 제어권을 사용자에게 부여합니다 [15, 16]. + * **슬롯 및 영역 (Slots / Regions):** 소비자가 직접 콘텐츠를 끼워 넣을 수 있는 의도적인 빈 공간(예: 헤더, 푸터)을 제공하여 Prop의 과부하를 막습니다 [14]. + +* **스타일링과 테마 적용 (Styling & Theming)**: + * 재사용 가능한 컴포넌트는 하드코딩된 스타일을 피하고, 색상이나 간격 등의 디자인 토큰(Design Tokens)을 기반으로 브랜드의 룩을 상속받아야 합니다 [17]. + * 구조를 캡슐화하면서도 클래스 이름이나 스타일 Prop을 주입할 수 있는 훅을 노출하여, 코드를 포크(Fork)하지 않고도 여러 제품 스킨이나 다크 모드 테마에 유연하게 대응하도록 설계해야 합니다 [17, 18]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Compound Components]], [[Headless Components]], [[Atomic Design]], [[Design Tokens]] +- **Projects/Contexts:** [[Shopify Polaris]] (재사용 가능한 컴포넌트와 접근성을 제공하여 일관된 앱 UI를 구축하는 쇼피파이의 디자인 시스템 [19, 20]), [[Uber Base Web]] (다양한 요구사항에 대응하기 위해 모든 하위 요소의 스타일과 기능을 제어할 수 있는 'Overrides' 패턴을 구현한 React 컴포넌트 라이브러리 사례 [21, 22]) +- **Contradictions/Notes:** 컴파운드 컴포넌트는 뛰어난 레이아웃 구성의 자유도를 제공하지만 [10], 지나친 자유도는 UX 일관성을 해칠 수 있으며, 단순하고 구조가 고정된 컴포넌트(예: 버튼, 아이콘)에 사용할 경우 불필요한 추상화와 유지보수 비용만 증가시키게 되므로 상황에 맞게 적용해야 합니다 [23-25]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/10_Wiki/Topics/Frontend_Mastery/CSS Animations.md b/10_Wiki/Topics/Frontend_Mastery/CSS Animations.md new file mode 100644 index 00000000..3b482f7b --- /dev/null +++ b/10_Wiki/Topics/Frontend_Mastery/CSS Animations.md @@ -0,0 +1,27 @@ +# [[CSS Animations]] + +## 📌 Brief Summary +CSS 애니메이션은 UI/UX에서 사용자와 시스템 간의 상호작용을 강화하고 시각적 피드백을 제공하며, 시스템 상태나 계층 구조를 명확히 하는 데 사용되는 기술이다 [1, 2]. 단순한 시각적 장식이 아닌 인지 부하를 줄이고 사용성을 높이는 기능적 목적을 가지며 [2-4], 실무적으로는 브라우저의 리플로우(Reflow)와 리페인트(Repaint)를 최소화하여 60FPS의 렌더링 성능을 유지하고 유지보수가 용이하도록 설계되어야 한다 [5, 6]. + +## 📖 Core Content + +* **애니메이션의 기능적 역할 및 UX 원칙** + 애니메이션은 단순히 화면을 꾸미는 것이 아니라, 사용자에게 즉각적인 피드백을 주고 주의를 유도하며 원인과 결과의 관계를 설명하는 기능적 도구이다 [1, 2, 4]. 호버(Hover) 효과, 버튼 클릭 시의 마이크로 인터랙션, 로딩 상태 진행 표시, 부드러운 화면 상태 전환 등에 주로 활용된다 [7-10]. 애니메이션의 지속 시간은 사용자 대기 시간을 줄이기 위해 200ms에서 500ms 사이로 짧게 유지하는 것이 좋으며, 기계적인 선형 움직임 대신 `ease-in-out`과 같은 이징(Easing) 함수를 활용해 물리 법칙에 기반한 자연스러운 움직임을 설계해야 한다 [11-14]. + +* **성능 저하를 유발하는 안티 패턴 (Reflow & Repaint)** + 프론트엔드 실전 설계에서 애니메이션 성능은 변경되는 CSS 속성에 크게 좌우된다 [15, 16]. `width`, `height`, `margin`, `padding`, `top`, `left` 등의 레이아웃 속성을 애니메이션 처리하면 브라우저의 리플로우(Reflow)와 리페인트(Repaint)가 지속해서 발생하여 애니메이션이 끊기는 현상(Jank)이 발생한다 [5, 6, 15, 17]. 또한 `box-shadow`, `filter`, `border-radius` 및 크고 복잡한 배경 이미지의 애니메이션은 렌더링 자원 소모가 크기 때문에 주의가 필요하다 [16, 18]. 동시에 너무 많은 요소를 애니메이션하거나 불필요한 무한 루프(`infinite`)를 적용하는 것도 브라우저 성능을 크게 저하하는 원인이 된다 [19, 20]. + +* **유지보수 가능하고 확장성 있는 성능 최적화 전략** + 부드럽고 렌더링 비용이 적은 애니메이션을 구현하기 위해서는 레이아웃에 영향을 주지 않는 `transform` (예: `translateZ()`, `scale()`)과 `opacity` 속성을 적극 활용해야 한다 [16, 21-23]. 이러한 속성들은 브라우저 렌더링 파이프라인에서 레이아웃과 페인트 단계를 건너뛰고 컴포지팅(Compositing) 단계만 거치게 되며, GPU 하드웨어 가속을 받아 모바일 기기에서도 뛰어난 성능을 보장한다 [16, 23, 24]. + 또한 `position: absolute`나 `position: fixed` 요소에 애니메이션을 적용하면 DOM 트리의 다른 요소에 미치는 리플로우 영향을 차단할 수 있다 [24-26]. 애니메이션이 확정된 요소에는 `will-change` 속성을 부여해 브라우저가 최적화를 미리 준비하도록 힌트를 줄 수 있으나, 과도하게 사용할 경우 오히려 성능을 저하시키므로 최소화하여 사용해야 한다 [27, 28]. + +* **접근성과 실무 환경에서의 제어** + 보이지 않는 요소의 무한 루프 애니메이션은 시스템 리소스를 고갈시키므로, `animation-play-state`를 사용해 화면 이탈 시 애니메이션을 일시 정지시키는 제어가 필요하다 [5, 20]. 아울러, 과도한 모션은 일부 사용자에게 어지러움을 유발할 수 있으므로 웹 콘텐츠 접근성 지침(WCAG)에 따라 `prefers-reduced-motion` 미디어 쿼리를 활용해 애니메이션을 선택적으로 줄이거나 제거할 수 있는 접근성 장치를 반드시 마련해야 한다 [11, 29, 30]. + +## 🔗 Knowledge Connections +- **Related Topics:** [[Reflow and Repaint]], [[Hardware Acceleration (GPU)]], [[Micro-interactions]], [[Accessibility (prefers-reduced-motion)]] +- **Projects/Contexts:** [[Large Frontend Projects]], [[Performance Optimization]] +- **Contradictions/Notes:** 무한 루프 애니메이션과 화려한 모션은 인터페이스에 활력을 줄 수 있지만 시스템 리소스를 크게 소모하며, 전정기관 장애가 있는 사용자에게 위험할 수 있습니다 [11, 20]. 따라서 실무 환경에서는 애니메이션 적용을 필수적인 기능과 마이크로 인터랙션으로 제한하고, 화면에서 벗어났을 때 정지시키거나(`animation-play-state`) 사용자의 환경 설정에 따라 모션을 줄이는(`prefers-reduced-motion`) 방어적 설계가 동반되어야 합니다 [20, 29, 30]. + +--- +*Last updated: 2026-04-26* \ No newline at end of file diff --git a/10_Wiki/Topics/Frontend_Mastery/CSS Variables.md b/10_Wiki/Topics/Frontend_Mastery/CSS Variables.md index 901e1463..43280208 100644 --- a/10_Wiki/Topics/Frontend_Mastery/CSS Variables.md +++ b/10_Wiki/Topics/Frontend_Mastery/CSS Variables.md @@ -1,27 +1,25 @@ # [[CSS Variables]] ## 📌 Brief Summary -CSS Variables(사용자 지정 속성, Custom Properties)은 JavaScript 없이도 동적인 스타일 제어를 가능하게 하는 모던 CSS의 표준 기능입니다. 과거 Sass와 같은 전처리기(Preprocessor)에 의존해야 했던 변수 기능을 CSS 자체에 내장하여, 런타임 오버헤드를 최소화하면서도 전역적인 테마(Theming) 관리 및 상태 기반 스타일링을 쉽게 만들어 줍니다. 특히 대규모 애플리케이션에서 디자인 토큰을 구현하고 유지보수하기 쉬운 아키텍처를 구축하는 데 핵심적인 역할을 수행합니다. +CSS Variables(사용자 지정 속성, CSS custom properties)은 React 및 최신 프론트엔드 프로젝트에서 디자인 토큰을 관리하고 동적 테마를 구현하는 데 사용되는 핵심 기반 기술입니다. 이 기술은 애플리케이션 전반에 걸쳐 하드코딩된 스타일 값을 대체하여 디자인의 일관성을 유지하고, 라이트/다크 모드와 같은 테마 전환을 쉽게 만듭니다. 특히 Tailwind CSS v4와 같은 최신 프레임워크나 styled-components와 같은 CSS-in-JS 환경에서 React Server Components(RSC) 호환성 및 런타임 성능 최적화를 달성하기 위한 필수적인 해결책으로 채택되고 있습니다. ## 📖 Core Content -* **모던 CSS 표준으로의 진화와 동적 스타일링:** - CSS 사용자 지정 속성은 과거 전처리기의 전유물이었던 변수 기능을 표준 CSS에 도입한 주요 개선 사항입니다 [1]. 이를 통해 JavaScript의 개입 없이도 동적인 스타일링이 가능해졌으며, 컨테이너 쿼리와 함께 순수 CSS의 부흥(Renaissance)을 이끄는 핵심 기술로 자리 잡았습니다 [2, 3]. +* **디자인 토큰과 동적 테마(Dynamic Theming)의 핵심:** + CSS 변수는 색상, 타이포그래피, 간격 등의 디자인 토큰을 중앙 집중화하여 관리하는 단일 진실 공급원(Single Source of Truth) 역할을 합니다 [1, 2]. Style Dictionary와 같은 도구를 사용해 JSON 형식의 디자인 토큰을 CSS 변수(예: `--color-primary`)로 변환하고 이를 `:root` 레벨에 정의하면, JavaScript의 개입 없이도 기본 테마나 라이트/다크 모드를 동적으로 전환할 수 있습니다 [3-6]. -* **디자인 토큰(Design Tokens) 구현의 핵심:** - 웹 환경에서 디자인 토큰을 코드로 구현할 때 CSS 변수가 적극적으로 활용됩니다 [4]. 효과적인 디자인 시스템을 구축하기 위해 CSS 변수는 주로 3단계 계층 구조를 가집니다 [5]. - 1. **글로벌 토큰 (Primitives):** 컨텍스트 없는 원시 값 (예: `--blue-500: #3b82f6`) - 2. **별칭/시맨틱 토큰 (Alias):** 의미와 목적을 부여한 값 (예: `--color-primary: var(--blue-500)`) - 3. **컴포넌트 토큰:** 특정 UI 요소에 종속된 값 (예: `--button-bg: var(--color-primary)`) - 이와 같이 변수를 참조 연결하는 방식을 통해, 시맨틱 토큰의 값만 교체하여 손쉽게 테마 변경(다크 모드 등)을 적용할 수 있습니다 [6]. +* **Tailwind CSS v4의 CSS 우선(CSS-first) 아키텍처:** + Tailwind CSS v4는 기존의 JavaScript 설정 파일(tailwind.config.js)을 제거하고 `@theme` 디렉티브를 사용하여 디자인 토큰을 기본 CSS 변수로 직접 노출합니다 [7-10]. 이를 통해 개발자는 JavaScript 구동 컨텍스트 업데이트 없이 런타임 테마 적용과 타입 안정성(Type Safety)을 확보할 수 있습니다 [10, 11]. 또한, 생성된 정규 CSS 변수는 인라인 스타일이나 임의의 값(arbitrary values)에서 참조할 수 있으며, JavaScript의 `getComputedStyle`을 통해서도 쉽게 접근이 가능합니다 [12-14]. -* **유지보수 가능한 모던 아키텍처와의 결합:** - 글로벌 단위에서 테마 변수를 CSS 사용자 지정 속성으로 관리하고, 개별 컴포넌트의 스타일은 CSS Modules를 통해 격리하는 하이브리드 아키텍처가 효율적인 실무 접근법으로 권장됩니다 [7, 8]. CSS 변수는 CSS Modules와 결합하여 런타임 오버헤드를 최소화하면서도 동적인 스코프 스타일링을 가능하게 합니다 [2]. - 또한 CSS Modules 단독으로는 JavaScript의 상태(State) 데이터를 스타일에 직접 주입하기 어렵다는 단점이 존재하는데, CSS 사용자 지정 속성을 인라인으로 전달함으로써 이 한계를 우회할 수 있습니다 [9]. 나아가 Linaria와 같은 Zero-Runtime CSS-in-JS 환경에서는 정적 CSS를 빌드 타임에 추출하고 동적 상태 제어는 CSS 변수에 위임하여 렌더링 성능을 최적화합니다 [10]. +* **styled-components 및 RSC 환경에서의 한계 극복:** + React Server Components(RSC) 환경에서는 React Context가 제공되지 않기 때문에, styled-components나 Emotion이 의존하던 `ThemeProvider`를 통한 동적 테마 주입이 작동하지 않습니다 [15-17]. 이를 해결하기 위해 styled-components v6.4+ 에서는 `createTheme` 함수를 도입하여 테마 객체의 모든 리프(leaf) 값을 CSS 변수 참조(`var(--prefix-path)`)로 변환합니다 [18]. 이 접근법을 사용하면 React 컨텍스트 없이도 클라이언트 컴포넌트와 RSC 모두에서 안정적으로 테마를 적용할 수 있습니다 [18]. + +* **컴포넌트 아키텍처 내에서의 유연한 결합:** + 정의된 CSS 변수는 인라인 스타일, CSS 모듈, 혹은 styled-components와 같은 CSS-in-JS 라이브러리 내부에서 모두 호환되어 사용 가능합니다 [19]. 이는 특정 스타일링 패러다임에 종속되지 않고 애플리케이션의 시각적 일관성을 유지할 수 있도록 도와줍니다 [19, 20]. ## 🔗 Knowledge Connections -- **Related Topics:** [[Design Tokens]], [[CSS Modules]], [[Zero-Runtime CSS-in-JS]] -- **Projects/Contexts:** [[Design Systems]], [[Frontend Architecture]] -- **Contradictions/Notes:** 소스에 따르면 CSS 사용자 지정 속성은 SCSS와 같은 기존 전처리기의 정적 변수나, 런타임 단계에서 스타일을 주입하는 기존 CSS-in-JS가 지닌 성능 저하 문제를 동시에 극복할 수 있는 이상적인 대안으로 평가받습니다 [1, 10]. +- **Related Topics:** `[[Design Tokens]]`, `[[Dynamic Theming]]`, `[[Tailwind CSS v4]]`, `[[React Server Components (RSC)]]`, `[[Styled Components]]` +- **Projects/Contexts:** `[[Next.js App Router]]` (RSC 환경 도입으로 인한 CSS-in-JS의 한계 및 CSS 변수를 활용한 테마 관리 체계로의 전환 맥락 [15-17]), `[[Figma Design System Integration]]` (Figma에서 정의된 토큰을 CSS 변수로 변환하여 자동화된 워크플로우를 구축하는 프로젝트 환경 [21-23]) +- **Contradictions/Notes:** 기존 CSS-in-JS 라이브러리(styled-components, Emotion)는 런타임에 JavaScript로 스타일을 생성하여 컴포넌트 수준의 강력한 동적 스타일링을 제공했으나 렌더링 성능과 RSC 호환성에서 단점이 존재했습니다. 최근에는 런타임 오버헤드가 없는 정적 빌드타임 CSS 변수(Tailwind CSS v4, vanilla-extract) 기반 접근법이 규모가 큰 프로덕션 환경에서 더욱 선호되는 추세입니다 [16, 17, 24-26]. --- *Last updated: 2026-04-26* \ No newline at end of file diff --git a/10_Wiki/Topics/Frontend_Mastery/CSS-in-JS.md b/10_Wiki/Topics/Frontend_Mastery/CSS-in-JS.md index ff0076f6..6113e21c 100644 --- a/10_Wiki/Topics/Frontend_Mastery/CSS-in-JS.md +++ b/10_Wiki/Topics/Frontend_Mastery/CSS-in-JS.md @@ -1,28 +1,25 @@ # [[CSS-in-JS]] ## 📌 Brief Summary -CSS-in-JS는 JavaScript 파일 내에서 CSS를 직접 작성하여 컴포넌트 단위로 스타일을 결합하는 모던 웹 스타일링 접근 방식입니다 [1, 2]. 기존의 전통적인 CSS가 가진 글로벌 스코프(Global Scope) 문제를 해결하고, 컴포넌트의 상태(State)나 프롭스(Props)에 기반한 동적 스타일링을 가능하게 합니다 [1, 3, 4]. 대표적인 라이브러리로는 styled-components와 Emotion이 있지만, 최근 런타임 성능 오버헤드와 프레임워크 호환성 문제로 인해 빌드 타임에 CSS를 추출하는 Zero-Runtime 방식으로 진화하고 있습니다 [5-8]. +CSS-in-JS는 JavaScript 파일 내에 직접 CSS를 작성하여 스타일과 컴포넌트를 같은 위치(co-location)에 배치하는 프론트엔드 스타일링 접근 방식입니다. 대표적인 라이브러리로 styled-components와 Emotion 등이 있으며, 템플릿 리터럴을 활용해 컴포넌트의 상태나 props에 기반한 동적 스타일링을 자연스럽게 지원합니다. 하지만 런타임에 CSS를 생성하고 주입하는 과정에서 발생하는 성능 오버헤드와 React Server Components(RSC)와의 호환성 문제로 인해 최근에는 Zero-runtime 방식이나 유틸리티 퍼스트 프레임워크(Tailwind CSS 등)와 비교되며 아키텍처적 재평가가 이루어지고 있습니다. ## 📖 Core Content -- **주요 장점:** - - **스코프 고립 및 충돌 방지:** 자동으로 고유한 클래스명을 생성하여 스타일의 충돌을 막아주며, BEM과 같은 복잡한 네이밍 컨벤션 없이도 캡슐화를 달성할 수 있습니다 [9, 10]. - - **동적 스타일링 및 테마 적용:** 컴포넌트의 프롭스(Props)와 애플리케이션 상태(State)에 직접 접근하여 스타일을 생성할 수 있어, 복잡한 테마(Theming) 시스템을 매끄럽게 구현할 수 있습니다 [3, 4, 8]. - - **응집도(Co-location):** 컴포넌트의 로직과 스타일이 한 파일에 위치하므로, 유지보수성이 높고 컴포넌트를 이동하거나 삭제할 때 스타일 코드가 버려지는(orphaned CSS) 문제를 방지합니다 [3, 4, 11]. - - **개발자 경험(DX):** TypeScript 통합을 통한 타입 안정성, 자동 완성, 자동 벤더 프리픽싱(Vendor prefixing) 등을 지원하여 버그를 줄이고 개발 시간을 단축시킵니다 [12, 13]. +* **주요 장점 및 특징:** + CSS-in-JS는 자바스크립트의 변수, 상태, props 등을 직접 활용해 동적인 스타일링을 손쉽게 구현할 수 있게 해줍니다 [1]. 컴포넌트와 스타일이 같은 파일에 공존하므로 컴포넌트 삭제 시 스타일도 함께 제거되어 유지보수가 용이하며, 과거 CSS의 전역 네임스페이스 충돌 문제나 스타일이 엇나가는 문제를 효과적으로 해결합니다 [1, 2]. 또한 내부적인 테마 프로바이더(Theme Provider)를 통해 라이트/다크 모드 등 다중 테마 관리가 수월하며, TypeScript를 통한 타입 안전성도 제공합니다 [1, 2]. -- **주요 단점 및 한계:** - - **런타임 성능 오버헤드:** 브라우저 런타임에서 CSS 문자열을 파싱하고 DOM에 주입해야 하며, 프롭스 변경 시 스타일을 재계산해야 하므로 렌더링 시간이 지연됩니다 [4, 12, 14, 15]. - - **번들 크기 증가:** styled-components(약 12.7kb~30kb)나 Emotion(약 7.9kb~12kb) 등의 라이브러리 자체가 JavaScript 번들에 추가되어 초기 로딩 및 실행에 부담을 줍니다 [7, 14]. - - **React Server Components (RSC) 호환성 문제:** React의 컨텍스트(Context)에 의존하는 런타임 CSS-in-JS 라이브러리들은 서버 환경에서 구동되는 React Server Components 환경과 근본적으로 호환되지 않아, 2024~2025년 이후 현대적인 프레임워크(예: Next.js App Router) 환경에서 큰 문제로 대두되었습니다 [7, 8, 16]. +* **런타임 성능 및 번들 사이즈 한계:** + 가장 큰 단점은 브라우저 런타임 시 자바스크립트를 실행하여 CSS 문자열을 생성하고 `