feat: Tailwind 마이그레이션 및 FSD 아키텍처 리팩토링 (#373)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: sumi <sumi@sumiui-MacBookAir.local>

Author: 3 people

.cursor/rules/web-fsd-architecture.mdc

@@ -0,0 +1,107 @@
+---
+description: apps/web 프로젝트 코드 작성 시 FSD-inspired 하이브리드 아키텍처 규칙을 적용합니다.
+globs:
+  - apps/web/src/**/*.ts
+  - apps/web/src/**/*.tsx
+alwaysApply: false
+---
+
+# apps/web FSD 아키텍처 규칙
+
+## 레이어 구조와 의존성
+
+apps/web은 FSD-inspired 하이브리드 아키텍처를 사용합니다.
+
+```
+src/
+├── app/          # 라우팅 + 조합 (Next.js App Router)
+├── widgets/      # 독립적 대규모 UI 블록
+├── features/     # 사용자 액션 기능
+├── entities/     # 비즈니스 엔티티
+├── shared/       # 범용 기반 코드
+├── components/   # [레거시] 새 파일 추가 금지
+└── middleware.ts
+```
+
+의존성 규칙: `app/ → widgets/ → features/ → entities/ → shared/`
+
+## 핵심 규칙
+
+1. **상위 레이어는 하위 레이어만 import 가능**
+   - features/는 entities/와 shared/만 import
+   - entities/는 shared/만 import
+   - shared/는 외부 패키지만 import
+
+2. **같은 레이어 슬라이스 간 import 금지**
+   - entities/persona/에서 entities/guild/ import 불가
+   - features/auction/에서 features/feedback/ import 불가
+
+3. **components/ 디렉토리에 새 파일 추가 금지**
+   - 새 코드는 반드시 적절한 FSD 레이어에 배치
+   - 도메인 무관 UI → shared/ui/
+   - 도메인 관련 UI → entities/*/ui/
+   - 기능 UI → features/*/ui/
+   - 대규모 조합 블록 → widgets/
+
+4. **각 슬라이스는 barrel index.ts 제공**
+   ```typescript
+   // entities/persona/index.ts
+   export * from './ui';
+   export * from './model';
+   ```
+
+## 새 코드 배치 기준
+
+| 코드 유형 | 배치 위치 | 예시 |
+|---|---|---|
+| 라우트 전용 UI | `app/[locale]/*/_components/` | 페이지별 폼, 섹션 |
+| 범용 UI (도메인 무관) | `shared/ui/` | Modal, Button |
+| 엔티티 UI | `entities/*/ui/` | PersonaItem, GuildCard |
+| 엔티티 쿼리/로직 | `entities/*/model/` | useGetAllPersona |
+| 사용자 액션 | `features/*/model/` | useRegisterProduct |
+| API 호출 함수 | `features/*/api/` 또는 `shared/api/` | github.ts |
+| 독립 대규모 블록 | `widgets/*/` | GNB |
+| 유틸리티 | `shared/utils/` | image.ts, string.ts |
+| 상수/설정 | `shared/config/` | env.ts, route.ts |
+| hooks (범용) | `shared/hooks/` | usePagination |
+
+## 슬라이스 내부 구조
+
+```
+features/auction/
+├── api/                    # API 호출 함수
+├── model/                  # hooks, 상태, 비즈니스 로직
+├── ui/                     # UI 컴포넌트
+└── index.ts                # public API (barrel export)
+```
+
+## import 스타일
+
+```typescript
+// 외부 패키지
+import { useQuery } from '@tanstack/react-query';
+import { getAllPersona } from '@gitanimals/api';
+
+// FSD 레이어 (절대경로 @/)
+import GNB from '@/widgets/gnb/GNB';
+import { AnimalCard } from '@/entities/persona';
+import { getPersonaImage } from '@/shared/utils/image';
+
+// 같은 슬라이스 내 (상대경로)
+import { useGetAllPersona } from './useGetAllPersona';
+```
+
+## `@gitanimals/*` 패키지
+
+모노레포 패키지는 외부 shared 계층으로 취급합니다.
+entities, features에서 직접 import 허용:
+
+```typescript
+import { getAllPersona } from '@gitanimals/api';        // OK
+import { cn } from '@gitanimals/ui-tailwind';           // OK
+import { userQueries } from '@gitanimals/react-query';  // OK
+```
+
+## 상세 가이드
+
+전체 아키텍처 가이드는 `apps/web/ARCHITECTURE.md`를 참조하세요.

.github/workflows/chromatic.yml

@@ -0,0 +1,44 @@
+name: Chromatic - UI Storybook
+
+on:
+  push:
+    branches:
+      - dev
+    paths:
+      - 'packages/ui/tailwind/**'
+
+env:
+  DEFAULT_NODE_VERSION: '20.11.0'
+  PNPM_VERSION: '9.0.6'
+
+jobs:
+  chromatic:
+    name: Publish Storybook
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+          run_install: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.DEFAULT_NODE_VERSION }}
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run Chromatic
+        uses: chromaui/action@latest
+        with:
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          workingDir: packages/ui/tailwind
+          exitOnceUploaded: true

CLAUDE.md

@@ -21,13 +21,32 @@ GitAnimals is a monorepo that allows users to raise virtual pets through GitHub
 - `packages/util/*` - Utility packages (common, typescript)
 
 **Key Technologies:**
-- **Styling:** PandaCSS with Shadow Panda preset for component styling
-- **State Management:** Tanstack Query v5 (server state), Jotai & Zustand (client state)  
+- **Styling:** Tailwind CSS (migrating from PandaCSS)
+- **State Management:** Tanstack Query v5 (server state), Jotai (client state)
 - **Authentication:** NextAuth.js (web), token-based auth (webview)
-- **UI Components:** Radix UI primitives + custom PandaCSS components
+- **UI Components:** Radix UI primitives + `@gitanimals/ui-tailwind`
 - **Package Manager:** pnpm v9.0+ with workspace configuration
 - **Build System:** Turborepo for orchestration
 
+**Web App Architecture (FSD-inspired Hybrid):**
+
+apps/web은 FSD(Feature-Sliced Design) 기반 하이브리드 아키텍처를 사용합니다.
+상세 가이드: [`apps/web/ARCHITECTURE.md`](apps/web/ARCHITECTURE.md)
+
+```
+src/
+├── app/          # Next.js App Router (라우팅 + 조합, FSD app+pages 역할)
+├── widgets/      # 독립적 대규모 UI 블록 (GNB 등)
+├── features/     # 사용자 액션 기능 (auction, auth, feedback 등)
+├── entities/     # 비즈니스 엔티티 (persona, guild, user, product)
+├── shared/       # 범용 기반 코드 (api, config, hooks, i18n, lib, store, utils)
+├── components/   # [레거시] 점진적으로 shared/ui/ 또는 entities/*/ui/로 이전
+└── middleware.ts
+```
+
+의존성 규칙: `app/ → widgets/ → features/ → entities/ → shared/`
+상위 레이어는 하위 레이어만 import 가능. 같은 레이어 슬라이스 간 import 금지.
+
 ## Development Commands
 
 **Root-level commands (run from project root):**
@@ -68,20 +87,23 @@ pnpm --filter @gitanimals/ui-panda storybook # Start Storybook
 
 ## Code Patterns & Conventions
 
-**Component Architecture:**
-- UI components in `packages/ui/panda/src/components/`
-- Each component has: `Component.tsx`, `Component.stories.tsx`, `index.ts`
-- PandaCSS styling with design tokens from `packages/ui/token`
+**Component Architecture (apps/web):**
+- FSD 레이어 구조: `shared/ → entities/ → features/ → widgets/ → app/`
+- 각 슬라이스는 `ui/`, `model/`, `api/` 세그먼트와 barrel `index.ts`로 구성
+- 라우트 전용 UI는 `app/[locale]/*/_components/`에 코로케이션
+- 도메인 무관 공유 UI는 `shared/ui/` 또는 `components/`(레거시)
 
 **Import Patterns:**
 - Workspace dependencies use `workspace:*` protocol
-- UI components imported from `@gitanimals/ui-panda`
+- UI components imported from `@gitanimals/ui-tailwind`
 - Shared utilities from `@gitanimals/util-common`
+- Web app 내부는 `@/` alias 사용 (→ `src/`)
+- FSD 의존성 규칙 준수: `@/shared/`, `@/entities/`, `@/features/`, `@/widgets/`
 
 **State Management:**
-- Server state: Tanstack Query v5 with `queryOptions` pattern in `src/apis/`
-- Client state: Jotai for atomic state, Zustand for stores
-- Auth state managed through NextAuth.js
+- Server state: Tanstack Query v5 in `entities/*/model/` 및 `features/*/model/`
+- Client state: Jotai atoms in `shared/store/`
+- Auth state managed through NextAuth.js (`shared/api/auth.ts`)
 
 **Tanstack Query v5 Best Practices:**
 - Always use `queryOptions` factory pattern for reusable query definitions
@@ -120,7 +142,7 @@ pnpm --filter @gitanimals/ui-panda storybook # Start Storybook
 
   // Usage in component
   import { useQuery } from '@tanstack/react-query';
-  import { userQueryOptions } from '@/apis/user/queries';
+  import { userQueryOptions } from '@/entities/user/model/queries';
 
   function UserProfile({ userId }: { userId: string }) {
     const { data: user } = useQuery(userQueryOptions.getUser(userId));
@@ -139,10 +161,10 @@ pnpm --filter @gitanimals/ui-panda storybook # Start Storybook
   - No need for custom hooks unless adding extra logic
 
 **Styling Approach:**
-- PandaCSS with `styled-system` generation
-- Shadow Panda preset for enhanced component styling
-- Responsive design using PandaCSS conditions (mobile/desktop)
-- Design tokens centralized in `packages/ui/token`
+- Tailwind CSS (migrating from PandaCSS)
+- `@gitanimals/ui-tailwind` 디자인 시스템 컴포넌트
+- Responsive design using Tailwind breakpoints
+- `cn()` utility for conditional class merging
 
 ## Testing & Quality
 
@@ -155,7 +177,7 @@ pnpm --filter @gitanimals/ui-panda storybook # Start Storybook
 
 - `turbo.json` - Build pipeline configuration
 - `pnpm-workspace.yaml` - Workspace definition
-- `apps/*/panda.config.ts` - PandaCSS configuration per app
+- `apps/web/ARCHITECTURE.md` - **FSD 아키텍처 상세 가이드 (필독)**
 - `packages/ui/panda/src/theme/` - Design system tokens and styles
 
 ## Build Pipeline Dependencies
@@ -167,7 +189,9 @@ The build system has specific dependency chains:
 
 ## Notes for Development
 
-- Always run `panda codegen` after theme changes
 - UI component changes require Storybook restart
 - Mobile app uses Expo SDK ~53.0.17 with React Native 0.79.5
-- Web app uses Next.js App Router with internationalization (next-intl)
+- Web app uses Next.js App Router with internationalization (next-intl)
+- **apps/web 작업 시 반드시 FSD 의존성 규칙을 따를 것** (상세: `apps/web/ARCHITECTURE.md`)
+- 새 코드는 반드시 `shared/`, `entities/`, `features/`, `widgets/` 중 적절한 레이어에 배치
+- `components/`(레거시)에 새 파일 추가 금지 — 적절한 FSD 레이어 사용