nomadcode/agent-ops/rules/domain/web/ui-shell/rules.md

ui-shell

목적 / 책임

앱 진입점, 라우터, 전체 레이아웃, 공통 UI 원자, 전역 스타일을 담당한다. 사용자가 Agent, Projects, Settings 화면 사이를 일관되게 이동할 수 있는 shell을 유지한다.

포함 경로

• src/main.tsx : React app mount 진입점
• src/app/ : QueryClient, RouterProvider, route tree
• src/layout/ : activity bar, top bar, mobile nav, agent sidebar 배치
• src/components/common/ : 여러 화면에서 공유하는 Button, Card, EmptyState
• src/styles/global.css : 전역 토큰, layout, component class style
• index.html, vite.config.ts : Vite app shell 설정

제외 경로

• src/routes/AgentPage.tsx, src/components/agent/, src/stores/agentStore.ts : agent-workspace
• src/routes/ProjectsPage.tsx, src/components/projects/, src/stores/projectStore.ts : project-workspace
• src/api/, src/components/settings/, src/routes/SettingsPage.tsx : backend-integration

주요 구성 요소

• App : TanStack Query와 Router provider 조립
• router : root/index/agent/projects/settings route 정의
• AppShell : 주요 layout과 agent sidebar context 연결
• ActivityBar, MobileNav, TopBar : primary navigation과 shell action
• Button, Card, EmptyState : 반복 UI primitive

유지할 패턴

• 새 route는 src/app/router.tsx에 추가하고 shell navigation과 store 상태 동기화를 함께 점검한다.
• 공통 컴포넌트는 도메인 데이터를 알지 않도록 유지한다.
• 화면별 스타일은 기존 class naming 흐름 안에서 global.css에 모으되, 큰 UI 경계가 생기면 별도 스타일 분리를 검토한다.
• 버튼에는 가능한 한 lucide icon을 함께 사용하고 기존 size/variant 체계를 확장한다.

다른 도메인과의 경계

• agent-workspace: shell은 agent sidebar를 배치하지만 메시지 생성과 agent context 의미는 agent-workspace가 맡는다.
• project-workspace: shell은 현재 route와 선택된 프로젝트 정보를 전달할 뿐 프로젝트 목록 조작은 project-workspace에 둔다.
• backend-integration: 연결 상태 표시는 shell에서 보여줄 수 있으나 API base URL, fetch, health check 구현은 backend-integration에 둔다.

금지 사항

• 공통 컴포넌트에 특정 페이지의 mock 데이터나 API 호출을 넣지 않는다.
• route 변경과 navigation 표시 상태를 서로 다른 곳에서 중복 정의하지 않는다.
• dist/ 생성물을 기준으로 UI를 수정하지 않는다.