docs(docs): 문서를 화면과 용도별 폴더로 재구성

docs/foundation/00_project_brief.md

@@ -0,0 +1,44 @@
+# 00. Project Brief
+
+## 프로젝트 목적
+
+VibeRoom Web은 ADHD와 프리랜서를 위한 premium focus service의 웹 제품을 설계하고 구현하는 프로젝트다.
+핵심 목표는 UX 흐름, 화면 구조, 상호작용 톤, core loop 계약을 실제 제품 품질로 안정적으로 끌어올리는 것이다.
+
+## 기술 스택
+
+- Next.js (App Router)
+- TypeScript
+- TailwindCSS
+- 상태: React state + local storage + 일부 shared store
+
+## 유지보수 역할 정의
+
+이 프로젝트에서 엔지니어의 역할:
+
+- FSD 구조를 지키며 화면/기능을 지속적으로 리팩터링한다.
+- View 계층을 조합 중심으로 유지하고 로직이 새지 않게 막는다.
+- 감성/저자극 톤을 유지하며 과한 강조 UI를 억제한다.
+- mock UI만 만드는 데 그치지 않고, core focus/session/review 흐름은 실제 계약과 연결한다.
+
+## 범위와 비범위
+
+범위:
+
+- 라우트/위젯/피처 단위 UI 개선
+- 더미 데이터 + 실제 계약 혼합 상태 표현
+- 모달, 토글, 탭, 선택, 토스트
+
+비범위:
+
+- 실시간 인원수/presence 정확도 보장
+- 오디오 DSP 수준의 고급 엔진
+- 운영 observability 완성
+- 모든 주변 기능의 production hardening
+
+## Definition of Done
+
+- 요구사항 화면이 동작하고, 기존 톤과 충돌하지 않는다.
+- FSD, 뷰 무로직, 500줄 분리 규칙을 지킨다.
+- `/app`, `/space` 등 관련 라우트에서 UX 흐름이 깨지지 않는다.
+- `docs/90_current_state.md`에 DONE/NEXT/RISKS/CHANGED FILES가 갱신된다.

docs/foundation/01_ui_guidelines.md

@@ -0,0 +1,133 @@
+# 01. UI Guidelines
+
+---
+
+## 목적 우선(Why-first)
+
+- UI를 추가/변경하기 전에 “이 변경이 해결하는 사용자 문제”를 1문장으로 고정한다.
+- 목적이 불명확하면 구현하지 않는다.
+- 한 UI 요소는 목적을 1개만 가진다(복수 목적이면 분리).
+
+---
+
+## 단일 정답 위치(Single canonical place)
+
+- 같은 일을 하는 진입점/버튼/칩을 여러 곳에 두지 않는다.
+- 불가피하게 2곳 이상이면 역할을 분리한다(예: Quick vs Browse).
+- 사용자가 “어디서 해야 하는지” 고민하게 만들면 실패다.
+
+---
+
+## 인지 부하 최소(Decision budget)
+
+- 한 화면에서 사용자가 “지금 결정해야 하는 것”은 최소로 제한한다.
+- 기본값을 제공하고, 추가 옵션은 접힘/팝오버/시트로 점진적으로 노출한다.
+- ‘변경’ 같은 버튼이 반복 노출되면 과밀/혼란 신호다(구조 재설계).
+
+---
+
+## 일관된 위계(Quiet hierarchy)
+
+- Primary CTA는 1개만 강하게.
+- Secondary/Tertiary는 가볍게(ghost/outline/link).
+- 강조는 “조용한 위계”로, 과한 대비/과한 시각효과 금지.
+
+---
+
+## 피드백 단일화(One feedback channel)
+
+- 같은 행동의 피드백은 한 채널에서만 보여준다.
+- 자주 발생하는 변경은 토스트 대신 “상태 변화”로 끝내는 것을 우선한다.
+- 피드백이 여러 곳에서 동시에 뜨면 어색함/저가 인상을 만든다.
+
+---
+
+## 겹침/충돌 방지(Overlap discipline)
+
+- 패널/시트/팝오버/토스트가 서로 겹치지 않게 우선순위를 정의한다.
+- 어떤 UI가 떠 있을 때 다른 UI는 이동/억제/병합 중 하나로 처리한다.
+- 전역 블러/전역 딤으로 문제를 덮지 않는다(필요 시 최소치).
+
+---
+
+## 무대 유지(Stage-first)
+
+- 배경/핵심 화면을 가리는 요소는 최소화한다.
+- 상시 UI는 “앵커(작고 확실한 표시)” 위주로 유지한다.
+- 큰 카드/대시보드형 UI가 상시 떠 있으면 감성이 깨진다.
+
+---
+
+## 모션은 이유가 있을 때만(Motion with meaning)
+
+- 애니메이션은 상태 변화를 이해시키는 목적이 있을 때만 사용한다.
+- 짧고 조용하게(과한 이징/번쩍임/바운스 금지).
+- Reduce Motion을 고려한다.
+
+---
+
+## 카피는 오해를 만들지 않게(Copy safety)
+
+- 초기 데이터가 비어도 어색하지 않은 카피를 기본값으로 둔다.
+- 실시간/확정처럼 보이는 표현은 신중히 사용한다.
+- 더미 동작은 (더미)로 명시한다.
+
+---
+
+## 접근성/상호작용 기본값(A11y baseline)
+
+- 아이콘 버튼은 sr-only 라벨 제공.
+- 포커스 링 유지.
+- 터치/클릭 타겟 충분히 확보.
+
+---
+
+## 품질 게이트(커밋 전 1분 체크)
+
+아래 중 하나라도 “No”면 커밋하지 않는다.
+
+- 중복 진입점이 생겼는가?
+- 한 화면에 결정/선택이 과도하게 보이는가?
+- 피드백이 두 군데 이상에서 나오나?
+- 겹침/가림/우선순위 문제가 있나?
+- 배경(무대)을 과도하게 가리나?
+- 톤/위계/카피가 01 가이드라인과 충돌하나?
+
+---
+
+## 디자인 톤
+
+- 기본 톤: 감성, 저자극, 차분함
+- 금지 톤: 과한 대비, 과한 번쩍임, 과도한 채도, 공격적인 카피
+- CTA는 명확하되 조용한 위계로 구성한다.
+
+## 컬러/표현 원칙
+
+- 다크 + 글래스 분위기를 유지한다.
+- 포인트 색상은 1차 액션에만 제한적으로 사용한다.
+- 2차/3차 액션은 outline/ghost/텍스트 링크로 무게를 낮춘다.
+
+## CTA 위계 규칙
+
+- Primary: 사용자 목표를 즉시 달성하는 액션 1개만 강조
+- Secondary: 대안 액션, 가시성은 유지하되 무게는 낮춤
+- Tertiary: 텍스트 링크 또는 작은 아이콘 액션
+- 데스크탑에서는 불필요한 풀폭 CTA를 지양한다.
+
+## 반응형 규칙
+
+- 모바일: 터치 우선, 충분한 높이/패딩, 필요 시 풀폭 CTA 허용
+- 데스크탑: 내용폭 기반 컴팩트 CTA 그룹 권장
+- 텍스트 길이에 따라 버튼 폭이 과도하게 늘어나지 않게 `min-w + px`를 사용
+
+## 마이크로카피 규칙
+
+- 실시간/확정처럼 보이는 문구를 신중히 사용한다.
+- 초기 데이터가 비어도 어색하지 않은 카피를 기본값으로 사용한다.
+- 숫자 기반 과장 표현보다 분위기/큐레이션 중심 문구를 우선한다.
+
+## 접근성/상호작용
+
+- 아이콘 버튼은 `sr-only` 텍스트를 제공한다.
+- 포커스 링을 유지한다.
+- 실제 미구현 기능은 토스트로 피드백하되, 실제 동작처럼 오해되지 않게 `(더미)`를 명시한다.

docs/foundation/02_arch_fsd_rules.md

@@ -0,0 +1,53 @@
+# 02. Architecture & FSD Rules
+
+## 레이어 구조
+
+```text
+src/
+  app/       # 라우트 진입점, 조합 전용
+  widgets/   # 화면 섹션 단위 조합
+  features/  # 사용자 액션/유즈케이스 단위
+  entities/  # 도메인 타입/더미 데이터
+  shared/    # 공용 UI/유틸
+```
+
+## 핵심 규칙
+
+1. `page.tsx`는 조합만 수행한다.
+2. 비즈니스 로직은 `features` 또는 `entities`로 이동한다.
+3. UI 상태(토글/선택)만 컴포넌트 내부에서 최소 허용한다.
+4. 파일 길이 500줄 이상이면 즉시 분리한다.
+5. 하위 레이어가 상위 레이어를 import하지 않는다.
+6. 전역 상태가 필요하면 먼저 해당 도메인 slice의 `model/` 안에 둔다.
+
+## Import 방향 규칙
+
+- `app` -> `widgets`, `features`, `entities`, `shared`
+- `widgets` -> `features`, `entities`, `shared`
+- `features` -> `entities`, `shared`
+- `entities` -> `shared`
+- `shared` -> 외부 의존성 또는 `shared` 내부
+
+금지:
+
+- `features` -> 다른 `features` 직접 참조 (강한 결합 유발)
+- `shared` -> `entities/features/widgets/app` 참조
+- `page.tsx`에 도메인 로직/세부 UI 구현 누적
+- 루트 전역 저장소를 관성적으로 추가하는 것
+
+## 구현 정책 (이 프로젝트 전용)
+
+- 실제 타이머/오디오/서버/DB 기능은 구현하지 않는다.
+- 기능 트리거는 토스트 또는 더미 상태 전환으로 표현한다.
+- 도메인 표시는 `entities` 데이터에서 읽고 뷰 하드코딩을 지양한다.
+- 인증/세션 같은 전역 상태도 가능하면 해당 도메인 `entities/*/model` 안에서 관리한다.
+
+## 파일 분리 기준
+
+- 조건:
+  - 파일 500줄 이상
+  - 하나의 파일에 2개 이상의 독립 관심사가 혼재
+- 분리 대상 예시:
+  - UI 파트 -> `ui/*`
+  - 상태/핸들러 -> `model/*`
+  - 타입 -> `model/types.ts`

docs/foundation/03_routes_map.md

@@ -0,0 +1,51 @@
+# 03. Routes Map
+
+## 라우트 개요
+
+- `/` -> `src/app/(landing)/page.tsx`
+- `/login` -> `src/app/(auth)/login/page.tsx`
+- `/app` -> `src/app/(app)/app/page.tsx`
+- `/space` -> `src/app/(app)/space/page.tsx`
+- `/stats` -> `src/app/(app)/stats/page.tsx`
+- `/settings` -> `src/app/(app)/settings/page.tsx`
+
+## 주요 라우트 조합
+
+### `/app` (허브)
+
+- Page: `src/app/(app)/app/page.tsx`
+- Core Widget: `src/widgets/focus-dashboard/ui/FocusDashboardWidget.tsx`
+- 주요 구성:
+  - `FocusDashboardWidget`
+  - paused `Resume Gate`
+  - no-session `Atmosphere Entry Shell` (기획 기준, 구현 예정)
+- 데이터 소스:
+  - current session: `features/focus-session`
+  - weekly review: `features/stats`
+  - atmosphere 선택 데이터: entry slice 구현 예정
+
+### `/space` (집중 화면)
+
+- Page: `src/app/(app)/space/page.tsx`
+- Core Widget: `src/widgets/space-workspace/ui/SpaceWorkspaceWidget.tsx`
+- 주요 구성:
+  - `SpaceTimerHudWidget`
+  - `SpaceFocusHudWidget`
+  - `SpaceSetupDrawerWidget`
+  - `SpaceToolsDockWidget`
+  - `features/restart-30s` (HUD 내 조합)
+
+## `/space` 쿼리 파라미터
+
+- `room`: 공간 id
+- `sound`: 사운드 preset id
+- `timer`: 타이머 라벨
+- `goal`: 목표 한 줄 (선택)
+- `resume`: `continue | refocus`
+
+## 변경 시 체크포인트
+
+- 라우팅 변경 시 `/app -> /space` 진입 흐름이 깨지지 않는지 확인
+- `running -> /space`, `paused -> /app` 재진입 정책 유지
+- query param 기본값 처리 유지
+- page 파일에 로직 누수 여부 확인

docs/foundation/04_coding_rules.md

@@ -0,0 +1,34 @@
+# 04. Coding Rules
+
+## 공통 코딩 규칙
+
+- TypeScript 타입을 명시하고 `any`를 피한다.
+- 명확한 이름 사용:
+  - 핸들러: `handle*`
+  - 훅: `use*`
+  - UI 컴포넌트: 역할이 드러나는 `*Widget`, `*Panel`, `*Card`
+- 중복 스타일 문자열은 공용 컴포넌트/유틸로 흡수한다.
+
+## React/Next 규칙
+
+- 클라이언트 컴포넌트는 필요한 곳에만 `'use client'` 선언
+- page는 조합 전용, 세부 구현은 widgets/features로 이동
+- URL 파라미터/검색 파라미터 파싱은 widget/model 레이어에서 처리
+
+## Tailwind 규칙
+
+- 하드코딩 hex 남발 금지
+- 클래스 길이가 길어지는 경우 의미 단위로 줄바꿈
+- hover/focus 상태는 기본 접근성 스타일과 함께 제공
+
+## 더미 기능 정책
+
+- 미구현 기능 트리거는 토스트로 피드백한다.
+- 토스트 제목에 `(더미)` 또는 설명으로 mock 상태를 명확히 전달한다.
+- 실데이터처럼 오해될 수 있는 숫자/실시간 문구 사용을 지양한다.
+
+## 검증 절차
+
+- 타입체크: `npx tsc --noEmit`
+- 빌드: `npm run build`
+- lint는 플러그인 누락 이슈가 있을 수 있으니 환경 상태를 먼저 확인한다.

docs/foundation/06_commit_convention.md

@@ -0,0 +1,55 @@
+# 06. Commit Convention
+
+## 목적
+
+세션이 끊겨도 커밋 이력만으로 복구 가능하도록, 메시지를 사람이 읽기 쉬우면서 기계적으로도 파싱 가능한 형태로 통일한다.
+
+## 기본 형식 (Conventional Commits)
+
+```text
+<type>(<scope>): <summary>
+```
+
+## 언어 규칙 (필수)
+
+- 커밋 제목의 `<summary>`는 한국어로 작성한다.
+- 커밋 본문도 한국어로 작성한다.
+- 영문 사용은 `type/scope`, 경로, 코드 식별자 같은 고유명사에 한정한다.
+
+예시:
+
+- `feat(app-hub): 데스크톱 CTA를 내용폭 버튼으로 조정`
+- `refactor(room): 인원 수 표시를 분위기 메타데이터로 전환`
+- `docs(session): 세션 복구 가이드와 템플릿 추가`
+
+## type 규칙
+
+- `feat`: 사용자 가시 기능 추가/변경
+- `fix`: 버그 수정
+- `refactor`: 동작 동일한 구조 개선
+- `style`: UI 스타일/카피 조정
+- `docs`: 문서 추가/수정
+- `chore`: 설정/스크립트/의존성 정리
+
+## 권장 본문 템플릿
+
+```text
+맥락:
+- 왜 이 변경이 필요한지
+
+변경사항:
+- 실제 변경 사항
+
+검증:
+- 실행한 검증 (예: npx tsc --noEmit)
+
+세션-상태: <현재 상태 한 줄>
+세션-다음: <다음 우선순위 한 줄>
+세션-리스크: <남은 리스크 한 줄>
+```
+
+## 커밋 크기 규칙
+
+- 1커밋 1의도 원칙
+- 화면 변경과 구조 변경이 모두 크면 분리 커밋
+- 대규모 리팩터링은 중간 checkpoint 커밋을 남긴다