📝 변경 이력
2026-03-01 — v0.3.0 컬러 테마 커스텀 프리셋 5종 추가 (슬랙 스타일). 와이어프레임 페이지 추가.
2026-03-01 — v0.2.1 탭뷰/섹션/필터 수치 스펙 추가. 납작한 탭뷰 문제 스크린샷 추가.
2026-03-01 — v0.2.0 디자인 레퍼런스 섹션 추가. 구조=WSPN Comm, 감각=wespichat. 컴포넌트 수치 스펙 정의.
2026-03-01 — v0.1.0 초안 작성. v1 최종 확정(v1.0.0 태그) 후 v2 시작.
2026-03-01 — v0.2.1 탭뷰/섹션/필터 수치 스펙 추가. 납작한 탭뷰 문제 스크린샷 추가.
2026-03-01 — v0.2.0 디자인 레퍼런스 섹션 추가. 구조=WSPN Comm, 감각=wespichat. 컴포넌트 수치 스펙 정의.
2026-03-01 — v0.1.0 초안 작성. v1 최종 확정(v1.0.0 태그) 후 v2 시작.
1. 왜 만드는가
AI 에이전트 4명(독술/코낄/고릴/호랑)과 일하면서 겪는 문제:
- 세션 연속성 없음 — 컴팩션/핸드오프 시 대화가 끊김. 새 토픽을 매번 열어야 함.
- 아티팩트 접근 불편 — 에이전트가 만든 대시보드/차트를 채팅에서 바로 못 봄.
- 파일 교환 불가 — 이미지/파일 첨부 안 됨.
- 진행 상황 불투명 — 에이전트가 뭘 하고 있는지 실시간으로 안 보임.
슬랙/텔레그램으로는 1번(세션 연속성)과 2번(아티팩트 인라인)이 구조적으로 불가능.
→ 직접 만드는 이유.
2. v1에서 바뀌는 것
| 영역 | v1 | v2 |
|---|---|---|
| 세션 연속성 | 없음 | /new 후 같은 채팅 이어가기 + 컴팩션 알림 |
| 아티팩트 연결 | UI만 | 세션별 아티팩트 실제 매칭 |
| 파일 업로드 | 스켈레톤 | R2 Worker 연동 완성 |
| 코드 구조 | chatStore 1,048줄 God Object | 관심사별 스토어 분리 |
안 바꾸는 것
- Glass UI 디자인 시스템
- 워크스페이스 레이아웃 (탭뷰/패널/분할)
- Gateway WebSocket 연결
- 사이드바 UX
- 모바일/데스크탑 반응형
🏗 UI 계층 구조
WSPN Comm의 모든 UI는 이 4계층으로 구성됩니다. 채팅이 주인공이고, 나머지는 채팅을 조직하고 보여주기 위한 구조입니다.
| 계층 | 이름 | 역할 | 비유 |
|---|---|---|---|
| ① | 채팅 (Chat) | 주인공. 하나의 대화 흐름. OpenClaw 세션에 해당하며, 핸드오프/컴팩션을 거치는 일련의 세션들을 하나의 채팅으로 연결함. | 문서 파일 |
| ② | 카드 (Card) | 채팅을 보여주는 UI 단위. 카드 내 멀티탭으로 하나의 카드 안에서 여러 채팅을 탭으로 전환 가능. | 에디터 창 |
| ③ | 패널 (Panel) | 여러 카드가 그리드 구조로 배치된 한 화면. 작업 맥락 단위. 사이드바에서 카드 리스트를 보여주는 이유는 패널 전환을 용이하게 하기 위함. | 데스크탑 배치 |
| ④ | 패널 탭 (Panel Tab) | 여러 패널을 탭으로 전환하면서 전체 화면을 활용. "재무 작업", "개발 작업" 등 맥락별 패널 세트. | 가상 데스크탑 |
핵심 분리: 채팅 = 데이터 단위 (세션 체이닝) / 카드 = UI 단위 (표시 방법)
→ 같은 채팅을 다른 카드에서 열 수도 있고, 하나의 카드에 여러 채팅을 탭으로 넣을 수도 있음.
→ 같은 채팅을 다른 카드에서 열 수도 있고, 하나의 카드에 여러 채팅을 탭으로 넣을 수도 있음.
④ 패널 탭: [🖥 개발작업] [📊 재무작업] [🎨 디자인]
└─ ③ 패널: 카드들의 그리드 (가로/세로 분할)
├─ ② 카드 A: [🐘 API수정] [🐘 배포] ← 멀티탭
│ └─ ① 채팅: 세션1 → 세션2 → 세션3 (체이닝)
└─ ② 카드 B: [🦅 재무분석]
└─ ① 채팅: 세션1 → 세션2 (체이닝)
└─ ③ 패널: 카드들의 그리드 (가로/세로 분할)
├─ ② 카드 A: [🐘 API수정] [🐘 배포] ← 멀티탭
│ └─ ① 채팅: 세션1 → 세션2 → 세션3 (체이닝)
└─ ② 카드 B: [🦅 재무분석]
└─ ① 채팅: 세션1 → 세션2 (체이닝)
3. 기능 명세
3.1 세션 연속성 ⭐ 최우선
문제: 에이전트 세션이 컴팩션되거나 리셋되면 대화 맥락이 끊김. 사용자는 같은 채팅에서 이어가고 싶음.
3.1.1 같은 채팅에서 세션 이어가기
- 하나의 "토픽"(채팅방)에 여러 Gateway 세션을 매핑
- IndexedDB:
topic_id ↔ session_key(1:N) - 새 세션 생성 시 같은 토픽에 새 session_key 추가
- 메시지 타임라인은 모든 세션의 메시지를 합쳐서 시간순 표시
- 세션 경계에 가벼운 구분선:
── 세션 리프레시됨 ──
3.1.2 컴팩션 감지 + 알림
- Gateway WebSocket에서 컴팩션 이벤트 감지 (또는 토큰 카운터 급감으로 추론)
- 채팅 내 시스템 메시지:
⚠️ 컨텍스트가 압축되었습니다 - "핸드오프 파일 읽기" 버튼 → 클릭 시 자동 전송
3.1.3 세션 히스토리 통합
- IndexedDB에 모든 세션의 메시지를 토픽 단위로 영구 저장
- Gateway 히스토리는 최신 세션만 → 이전 세션 메시지는 로컬 DB에서 로드
- 스크롤 시 이전 세션 메시지까지 연속으로 표시
3.2 아티팩트 연결 완성 P3
3.2.1 "이 채팅" 아티팩트 필터
- 현재 토픽에 매핑된 session_key들을 기준으로 아티팩트 필터
- ArtifactBrowser "이 채팅" 탭에서 정확한 결과 표시
3.2.2 아티팩트 인라인 카드 강화
[artifact:id]마커로 API 개별 조회 → 인라인 렌더링- 에이전트가 푸시한 아티팩트 자동 알림 (시스템 메시지)
3.3 파일 업로드 P4
3.3.1 업로드 플로우
- 📎 버튼 → 파일 선택 (멀티)
- 클립보드 이미지 붙여넣기 (Cmd+V)
- 드래그 앤 드롭 (채팅 영역)
- 멀티파일 프리뷰 바 → 전송
3.3.2 R2 Worker
- 엔드포인트:
wspn-comm-files.wespion.workers.dev - v1 이슈: GET 404 버그 해결 필요
3.4 코드 리팩터링 P1
3.4.1 스토어 분리
chatStore.ts(1,048줄) → chatStore + layoutStore + settingsStore + artifactStore
3.4.2 컴포넌트 분리
GridLayout.tsx(1,200줄) → WorkspaceLayout + PaneContainer + DropZone + PaneDivider
4. 와이어프레임
4.1 세션 연속성 UI
┌─────────────────────────────────────┐
│ 🐘 코낄 — WSPN API 수정 │
│─────────────────────────────────────│
│ │
│ [에이전트] v0.8.0 배포 완료했어요 │
│ │
│ ── 세션 리프레시됨 (03-01 14:30) ── │
│ │
│ [에이전트] 안녕하세요, 이어서 │
│ 진행하겠습니다. │
│ │
│ ⚠️ 컨텍스트 압축됨 │
│ [핸드오프 파일 읽기] ← 클릭 버튼 │
│ │
│ [나] 핸드오프 읽고 이어가줘 │
│ │
│─────────────────────────────────────│
│ 토큰: ████████░░ 72% │
│ [📎] [메시지 입력...] [전송] │
└─────────────────────────────────────┘
4.2 파일 업로드 UI
┌─────────────────────────────────────┐
│ ...채팅 메시지들... │
│ │
│─────────────────────────────────────│
│ ┌──────┐ ┌──────┐ │
│ │ 📷 │ │ 📄 │ ✕ 제거 │ ← 프리뷰 바
│ │img.png│ │spec │ │
│ └──────┘ └──────┘ │
│─────────────────────────────────────│
│ [📎] [메시지 입력...] [전송] │
└─────────────────────────────────────┘
4.3 아티팩트 "이 채팅" 탭
┌─ ArtifactBrowser ───────────────────┐
│ [이 채팅] [전체] [즐겨찾기] │
│ 🔍 검색... │
│─────────────────────────────────────│
│ 📊 매출 분석 차트 03-01 10:00 │
│ 📋 API 스펙 테이블 02-28 15:30 │
│ 📈 트래픽 대시보드 02-28 09:00 │
│ │
│ (이 채팅의 세션에서 생성된 것만) │
└─────────────────────────────────────┘
5. 마일스톤
| Phase | 내용 | 예상 | 상태 |
|---|---|---|---|
| P0 | PRD 확정 + 와이어프레임 리뷰 | 오늘 | ⏳ 리뷰 중 |
| P1 | 코드 리팩터링 (스토어 + 컴포넌트 분리) | 1일 | — |
| P2 | 세션 연속성 (핵심) | 1일 | — |
| P3 | 아티팩트 "이 채팅" 연결 | 반나절 | — |
| P4 | 파일 업로드 (R2 + UI) | 1일 | — |
| P5 | 통합 테스트 + 폴리싱 | 반나절 | — |
총 예상: 4~5일
6. 기술 결정
| 항목 | 결정 | 사유 |
|---|---|---|
| 프레임워크 | React + Vite (유지) | Tauri 불필요, PWA 충분 |
| 로컬 DB | IndexedDB (유지) | SQLite는 Tauri 전용이었음 |
| 배포 | CF Pages + PWA | 기존 인프라 |
| 파일 저장 | R2 Worker | 기존 Worker 재사용 |
| 상태 관리 | Zustand (분리) | God Object 해소 |
7. v1 교훈 → v2 원칙
- God Object 금지 — 스토어/컴포넌트 500줄 넘으면 분리
- 기능 이전 시 구버전 즉시 제거 — 중복 코드 방치 금지
- 드롭다운 배경 불투명 — Glass UI여도 메뉴 가독성 우선
- 모바일 전용 컴포넌트 —
isMobile분기 대신 별도 설계 - 커밋 단위 작게 — 기능 단위 커밋, 리팩터와 기능 추가 분리
- 변경 전 git commit — 작업 전 안전망 확보
🎨 디자인 레퍼런스
원칙: 구조는 WSPN Comm, 감각은 wespichat
| 영역 | 기준 | 출처 |
|---|---|---|
| 레이아웃 구조 | 탭뷰 → 패널 분할 → 채팅 탭, D&D, 캐스케이드 | WSPN Comm v1 |
| 사이드바 섹션 | 즐겨찾기, 탭뷰, 전체 채팅, 상태 표시 | WSPN Comm v1 |
| 단축키 체계 | Ctrl+Shift 조합, Cmd+B 등 | WSPN Comm v1 |
| 공간 활용 | 여유로운 여백, 요소를 우겨넣지 않음 | wespichat |
| 밀도 조절 | 사이드바 아이템 높이, 아바타 크기, 줄간격 | wespichat |
| 폰트 사이즈 | 충분히 크고, 계층이 명확 | wespichat |
| 레이어드 depth | 배경 → 사이드바 → 채팅 → 카드 → 콘텐츠 단계적 밝기 | wespichat |
| 아티팩트 카드 | 인라인 프리뷰 + "패널에서 보기" + 버전 셀렉터(v1/v2/v3) | wespichat |
레퍼런스 스크린샷
❌ WSPN Comm v1 — 밀도 문제
Glass UI 비주얼은 좋지만 요소를 우겨넣어서 숨이 막힘. 좌상단 헤더 영역이 특히 심함.
- 사이드바 아바타 ~20px → 거의 안 보임
- 채널명 다 잘려서 구분 불가
- 헤더에 필터 버튼 우겨넣음
- 아이템 간 줄간격 36~40px로 빽빽
✅ wespichat — 디자인 목표
공간 배분, 여백, 폰트 사이즈가 자연스러움. 이 감각을 v2에 적용.
- 아바타 36-40px, 색상으로 사용자 즉시 구분
- 메시지 간 간격 24-32px, 숨쉬는 공간
- 레이어드 depth: 사이드바(딥 네이비) → 채팅(약간 밝은) → 카드(더 밝은) → 콘텐츠(화이트)
- 인라인 아티팩트 카드 + 버전 셀렉터 + "패널에서 보기 →"
- 절제된 악센트 — 색상을 기능적으로만 사용
컴포넌트 수치 스펙 (v2 기준)
| 컴포넌트 | v1 (문제) | v2 목표 |
|---|---|---|
| 사이드바 폭 | 260-300px | 280px (최소), 자유 리사이즈 |
| 사이드바 아이템 높이 | 36-40px | 56px |
| 아바타 크기 | 20-24px | 36px |
| 사이드바 좌우 패딩 | px-4 (16px) | 16px (유지) |
| 헤더 영역 높이 | 우겨넣음 | 56px (여유 있게) |
| 메시지 간 간격 | 가변 | 24px |
| 메시지 본문 폰트 | 15px × scale | 15px (유지) |
| 타임스탬프 폰트 | 10px | 12px |
| 에이전트명 폰트 | 11px | 14px semi-bold |
| 토픽명 폰트 (사이드바) | 13px | 14px |
| 프리뷰 텍스트 (사이드바) | 11px | 13px |
| 입력창 높이 | 단일행 | 44px 최소, 멀티라인 확장 |
| 패널 헤더 높이 | ~30px | 48px |
| 인라인 아티팩트 카드 | 없음 (URL만) | ◆ 아이콘 + 제목 + 버전 + 프리뷰 |
| 탭뷰 탭 높이 | ~28px, 패딩 4px | 40px, 패딩 10px |
| 탭뷰 탭 폰트 | 13px | 14px semi-bold |
| 탭뷰 탭 바 배경 | 없음 (콘텐츠와 구분 안 됨) | 별도 컨테이너, glass bg + border-bottom |
| 섹션 헤더 (즐겨찾기/탭뷰) | 리스트와 구분 안 됨 | 12px uppercase + 16px 상단 마진 |
| 섹션 간 간격 | 4-6px | 16px |
| 필터 버튼 (전체/진행/대기/완료) | ~20px 높이 | 32px pill, 터치 타겟 44px |
❌ 탭뷰 현재 — 납작하고 구분 안 됨
- 탭 높이 28px, 패딩 4px — 누르기도 힘들고 읽히지도 않음
- 섹션 헤더(즐겨찾기/탭뷰)가 리스트 아이템과 구분 안 됨
- 필터 버튼(전체/진행/대기/완료) 너무 작음
- Chrome 탭이나 Slack 섹션과 비교하면 여백이 절반 이하
컬러 테마 커스텀 (신규)
슬랙처럼 프리셋 기반 컬러 테마 선택. 2~3개 핵심 색상 조합으로 전체 분위기 변경.
| 테마 | 사이드바 | Primary | Accent | 느낌 |
|---|---|---|---|---|
| 🌙 Midnight (기본) | #0f1019 | #5252FA | #BAFC27 | 현재 Glass UI |
| 🍇 Aubergine | #3F0E40 | #E01E5A | #ECB22E | 슬랙 클래식 |
| 🌊 Ocean | #0D1B2A | #0EA5E9 | #38BDF8 | 차분한 블루 |
| 🌿 Forest | #1A1F16 | #22C55E | #A3E635 | 자연 그린 |
| ☀️ Light | #F0F0F3 | #5252FA | #7C3AED | 밝은 모드 |
구현: CSS 변수 --c-sidebar, --c-primary, --c-accent 3개만 바꾸면 전체 테마 전환. 배경 블롭 색상도 primary 기반으로 자동 파생.
Glass UI 유지 사항
- 배경 블롭 애니메이션 (primary/violet/pink)
backdrop-filter: blur(24px) saturate(1.3)- 3 테마: dark / dim / light
- primary
#5252FA, accent#BAFC27 - 다만 밀도는 wespichat 기준으로 낮춤
8. 후순위 (v2 이후)
| 기능 | 사유 |
|---|---|
| 에이전트별 알림음 | nice-to-have |
| 인증 시스템 | 현재 성우님 혼자 사용 |
| 브라우저 Notification | PWA permission 필요 |
| Tauri 네이티브 앱 | 웹챗이 충분하면 불필요 |