🎧

팀내에서 디자인 시스템 설계시 기존 사용하던 폴더 구조를 따라가기에는 한계가 있엇다.

아래는 기존 폴더 구조이다.

해당 구조는 서비스 규모가 커지면서 유지보수성에 불리하게 되었다.

이 구조의 단점을 살펴보면 다음과 같다.

1. 관심사 혼합

components와 pages 폴더의 파일이 거의 1:1로 매핑되다 보니, 마치 특정 컴포넌트가 해당 페이지에서만 사용되는 것처럼 보인다. 하지만 예를 들어 user라는 컴포넌트가 다른 페이지에서도 사용된다면, 해당 컴포넌트를 사용해도 되는지 판단하기 위해 결국 코드를 직접 열어 확인해야 한다.

2. 확장 시 스케일 문제

• 기능별로 폴더가 아니라 레이어별(components, pages, utils)로만 나눠져 있어서,
  페이지나 기능이 많아지면 components/ 폴더 안이 너무 커지게 된다. 실제로 components내의 파일 개수는 1000개를 넘어가는 상황이다.
• 따라서 새로운 기능 개발 혹은 기존 기능 고도화 작업을 진행하게 되면 그 기능에만 관련된 파일만 봐야하는 것이 아닌, 어떤 것이 연관이 있는지 직접 찾아가며 사이드이펙트를 살펴봐야 한다.

3. 페이지와 컴포넌트 결합도 문제

• pages/와 components/가 물리적으로 멀리 떨어져 있음 → 유지보수 시 페이지-컴포넌트 간 맥락 파악 어렵다.
• 같은 기능을 위한 페이지와 컴포넌트를 서로 다른 폴더에서 찾아야 한다. → 쓰이는 곳을 찾아가며 경로를 이동하다 길을 잃을 수 있다 (;;)

이러한 단점들로 인해 우리 팀 내에서는 개선방향으로 프로젝트에 FSD 아키텍쳐를 적용하기로 하였다.

단, 프로젝트 규모가 워낙 크다보니 FSD(Feature-Sliced Design) 아키텍쳐를 한 번에 프로젝트에 적용할 수 없었고, 디자인 시스템 정립이 새로 진행되고 있었으므로 디자인 시스템에 이 아키텍쳐를 도입해 보기로 하였다. 

기본 골자는 아래와 같다.

📂 shared/

프로젝트 전역에서 공용으로 쓰이는 요소 모음

• tokens/
  • 색상, 폰트, spacing, z-index 등 디자인 토큰
  • ex) colors.ts, typography.ts, spacing.ts
• hooks/
  • 프로젝트 전역 공용 훅
  • ex) useMediaQuery, useTheme
• utils/
  • 포맷터, 헬퍼 함수 등 재사용 가능 로직
  • ex) formatDate, debounce, clsx

📂 entities/

하나의 독립적인 UI 엔티티(컴포넌트) 단위

• ex) button/, input/, avatar/
• 각 엔티티는 자기 완결적
  • ui/ → 실제 UI 컴포넌트 (styled-components + variant 스타일 정의 포함)
  • model/ → 타입 정의, 상태 관리, 내부 비즈니스 로직
  • index.ts → 해당 엔티티의 진입점 (외부에 노출할 API)

이렇게 하면, 버튼을 쓸 때 내부 구조를 몰라도 import { Button } from '@/entities/button' 식으로 가져올 수 있음.

📂 widgets/ (선택적)

엔티티들을 조합해 만든 복합 UI 컴포넌트 (단, 우리 프로젝트에서는 폴더 축소화를 위해 entities에 복합 ui를 포함하기도 하였다.)

• 예: Form, Navbar, Sidebar
• 페이지나 기능에 재사용 가능한 조합 단위
• 비즈니스 로직이 거의 없고 UI 결합 중심

📂 app/

애플리케이션 전역 환경과 데모 페이지

• 디자인 시스템 Storybook, 테스트 페이지 등
• 라우팅, 전역 Provider, App-level 설정 포함 가능
• ex) storybook/, App.tsx, global.css

이 구조의 특징을 살펴보자.

1. 관심사 분리
디자인 토큰, 공용 유틸, UI 엔티티, 복합 UI, 앱 환경이 물리적으로 분리되어 있음
2. 스케일 확장에 강함
새 컴포넌트를 만들 때 해당 엔티티 폴더만 생성하면 됨 → 폴더가 기능 중심으로 늘어남.
3. Storybook/TDD 친화적
각 엔티티/위젯 안에서 바로 스토리북과 테스트 작성 가능.
4. 재사용성 극대화
위젯·엔티티를 다른 프로젝트에 가져가기 쉬움.

현재까지 작업은 계속 진행중이다. 하루 빨리 디자인 시스템 및 FSD 아키텍처 도입이 정상화되어 일의 효율이 높아지면 좋겠다.

대규모 프로젝트에서는 FSD 패턴, 즉 기능별 디자인 아키텍쳐가 필수적이라고 생각하는 요즘이다!