[FE] Atomic 디자인 패턴 테크 스펙 - 100-hours-a-week/20-real-wiki GitHub Wiki

요약

프로젝트 전반의 컴포넌트 일관성과 재사용성을 높이기 위해 Atomic 디자인 패턴을 도입합니다.
프론트엔드 개발자 전원이 공통된 컴포넌트 설계 기준을 따르며, 유지보수성과 확장성을 향상시킵니다.

배경

컴포넌트 설계 시 명확한 기준이 없습니다. 페이지마다 각자의 기준으로 컴포넌트를 나누어,

  • 컴포넌트 책임이 과도하게 커지고
  • 재사용과 확장이 어렵고
  • 테스트 및 문서화가 어렵습니다.

Atomic 디자인 패턴을 도입해 컴포넌트를 계층적으로 관리함으로써 위 문제를 해결하고자 합니다.

목표

  • 프로젝트 전반에 Atomic Design 패턴을 적용한다.
  • 컴포넌트 재사용성을 높이고 중복 구현을 줄인다.
  • 컴포넌트 책임을 명확히 분리하여 유지보수를 용이하게 한다.
  • Storybook에 책임 단위로 컴포넌트/페이지를 문서화한다.
  • 신규 개발 시 모든 컴포넌트는 Atomic 기준에 맞게 설계한다.

설계 및 기술 자료

1. 개요

Atomic Design은 UI 설계 방법론으로, 다음과 같은 5단계로 컴포넌트를 구분합니다.

  1. Atom (원자)
    • 더 이상 분해할 수 없는 가장 작은 단위의 컴포넌트
    • ex) Button, Input, Icon, Label
  2. Molecule (분자)
    • 두 개 이상의 Atom이 결합된 컴포넌트
    • ex) InputField (Label + Input + Validation Message)
  3. Organism (유기체)
    • 여러 Molecule과 Atom이 결합된 복합 컴포넌트
    • UI에서 별개의 영역으로 나눌 수 있어야 함
    • ex) Header, Sidebar, FormSection
  4. Template (템플릿)
    • 페이지 레이아웃과 구조를 정의하지만 실제 데이터는 포함하지 않음
    • ex) AuthPageTemplate, DashboardTemplate
  5. Page (페이지)
    • Template에 실제 데이터를 주입하여 렌더링하는 완성된 화면
    • ex) LoginPage, DashboardPage

2. 설계 규칙

  • 디자인 시스템 컴포넌트 개발 시
    • 재사용성을 높이기 위해 마진, 패딩 등의 레이아웃 스타일은 컴포넌트 내부에 정의하지 않고 외부에서 주입받도록 한다.
  • Molecule과 Organism 구분 기준
    • 컨텍스트 또는 상태 관리가 필요한 경우 → Organism
    • 컨텍스트 없이 UI적인 요소로 SRP를 지킬 수 있고, 재사용이 쉬운 경우 → Molecule
    • 판단이 애매할 경우 우선 원하는 방향으로 구현하고, 추후 사용처와 역할에 따라 레이어를 재조정한다.
  • 디자인적으로 약간 다른 Organism이 있는 경우
    • 중복 컴포넌트, Props의 수정은 확장에 유연하지 않다.
    • 이 경우 Compound Component를 사용하여 유연하게 대응한다.
  • Template 사용 여부
    • Template은 우선 사용을 보류한다.
    • SSR 환경에서 인터랙션 처리를 위해 내부에 Client Component를 포함하게 되면, Organism 단에서 API 호출과 상태 관리가 발생하게 된다.
    • 이 경우 Template은 뷰 조립만 담당하고 책임을 가지지 않게 되어, Template 계층의 의미가 희석된다.

3. 폴더 구조 예시

src/
├── features/
│   ├── Post/
│   │   ├── atoms/
│   │   │   └── Tag.tsx
│   │   ├── molecules/
│   │   │   └── PostHeader.tsx
│   │   ├── organisms/
│   │   │   └── PostDetail.tsx
│   │   └── pages/
│   │       └── PostDetailPage.tsx
│   └── Chatbot/
│       ├── atoms/
│       │   └── MessageBubble.tsx
│       ├── molecules/
│       │   └── ChatInput.tsx
│       ├── organisms/
│       │   └── ChatScreen.tsx
│       └── pages/
│           └── ChatPage.tsx
├── commponents/
│   ├── atoms/
│   │   └── Badge.tsx
│   ├── molecules/
│   │   └── HeadlineBannerItem.tsx
│   ├── organisms/
└   └──   └── HeadlineBanner.tsx

4. 기존 컴포넌트를 Atomic 디자인 패턴으로 리팩토링

💡 빨간 테두리는 Organism, 파란 테두리는 Molecule을 의미

  1. 챗봇 페이지

image

  1. 공지 리스트

image

  1. 뉴스 리스트

image

  1. 게시글 상세

image