📘 구축 프로젝트를 위한 컴포넌트 & 스타일 설계 전략서

📚 목차

1. 개요 요약
2. 문제 정의 및 논의 목적
3. 실무에서 마주친 주요 과제들
4. 해결을 위한 전략 정리
   • 4.1 스타일 vs 컴포넌트 분리 체크리스트
   • 4.2 DDC 폴더 구조 제안 (core/ui 기반)
5. 추천 방안 정리
6. 실무 적용 기준 요약
7. 결론 및 향후 대응

🧭 1. 개요 요약

이 문서는 단기 구축형 프로젝트에서 다음 두 가지 중심축을 기준으로 실무 설계 전략을 정리한 것이다:

• UI 재사용을 위한 컴포넌트와 CSS의 이상적 분리 기준
• 현실적인 프로젝트 속도와 유지보수 가능성을 고려한 폴더 구조 및 설계 방안

🎯 2. 문제 정의 및 논의 목적

📌 목적

• 재사용성과 확장성을 고려한 이상적인 컴포넌트 구조를 구축 프로젝트에서 어디까지 추구해야 하는가?
• 스타일을 재사용하기 위해 컴포넌트로 분리하는 것이 과연 합리적인가?
• 스타일이 컴포넌트와 결합될 경우 유지보수성은 어떻게 확보할 수 있는가?

❗ 3. 실무에서 마주친 주요 과제들

고민 사례	설명	발생 원인
상품리스트 스타일 재사용	여러 화면에서 같은 레이아웃을 복붙, 클래스 순서 누락 시 UI 깨짐	CSS 기억 의존, 문서 부재
유틸 버튼 스타일을 복붙 사용	btn-primary, btn-lg 등 추상화는 되어 있으나, hover 시마다 다름	UI 의미와 클래스 명이 매핑되지 않음
개발자마다 DOM 구조 구성 다름	같은 카드라도 누락/과잉 구조가 생김	구조 캡슐화 부재
리팩토링 시 구조 변경 파급	UI가 CSS 기반일 경우 DOM 바뀌면 전면 수정 필요	구조-스타일 분리 실패
스타일만 필요하지만 컴포넌트화됨	단순 타이틀/섹션인데도 컴포넌트화	기준 없는 분리
기억 의존	3개월 뒤 class 조합, 순서, 구조 등 잊음	문서화 미흡, 캡슐화 부족

🛠 4. 해결을 위한 전략 정리

4.1 스타일 vs 컴포넌트 분리 체크리스트

항목	CSS 조립(스타일 분리)	컴포넌트 분리
DOM 구조 복잡도	단순	3단 이상 중첩
상태 제어 여부	없음	있음 (hover, loading, skeleton 등)
반복 재사용 빈도	낮음	높음
조립 시 실수 가능성	높음 (순서, 클래스 누락)	낮음
문서화 필요성	높음 (class 기억 필요)	낮음 (컴포넌트 추상화)
디자이너 → 개발자 전달 효율성	낮음	높음
디자인 변경 시 영향 범위	전역적 (클래스 재정의)	국지적 (컴포넌트 내부만 수정)
단기 구축에 적합	부분적으로	구조 고정 시 유리

4.2 DDC 폴더 구조 제안 (core/ui 기반)

/src
  ├── components/
  │   ├── core/
  │   │   ├── Button/
  │   │   │   ├── Button.tsx
  │   │   │   ├── Button.module.css
  │   │   │   └── index.ts
  │   │   └── Input/
  │   │       ├── Input.tsx
  │   │       ├── Input.module.css
  │   │       └── index.ts
  │   └── ui/
  │       ├── ProductCard/
  │       │   ├── ProductCard.tsx
  │       │   ├── ProductCard.module.css
  │       │   └── index.ts
  │       └── ProductList/
  │           ├── ProductList.tsx
  │           └── ProductList.module.css
  └── styles/
      ├── tokens.css
      ├── mixins.css
      └── globals.css

🥇 5. 추천 방안 정리

• 스타일만 존재하는 구조는 장기적 신뢰성 확보에 실패함 → 구조를 모르면 class를 잘못 조합할 가능성 높음
• UI 컴포넌트는 재사용 목적이 아닌, "조립을 단순화하고 문서화를 자동화하는 목적"으로 필요
• components/core와 components/ui는 목적, 재사용 범위, 설계 수준이 명확히 다르므로 반드시 분리

✅ 6. 실무 적용 기준 요약

분류	적용 기준	예시
core 컴포넌트	여러 화면/도메인에서 재사용, 기능 중심	Button, Input, Icon, Modal
ui 컴포넌트	특정 도메인 전용, 구조+스타일 캡슐화	ProductCard, SearchBox, FilterGroup
CSS 외부화	재사용 가능 스타일(변수, 함수, 리셋 등)만	tokens, mixins
스타일 로컬화	개별 컴포넌트에 종속된 스타일은 로컬 유지	ProductCard.module.css
UI 설계 실패 지점	class 순서 오류, DOM 누락, 기억 의존 등	복붙으로 동일 UI 복원 불가

🔚 7. 결론 및 향후 대응

• 단기 구축 프로젝트라 해도 UI 조립의 신뢰성과 구조 일관성 확보를 위해 일정 수준의 컴포넌트 분리는 필수적이다.
• 스타일 추상화만으로는 실제 개발자 경험에서 실수를 유발하며, 특히 다른 개발자와의 협업이나 장기 유지보수 측면에서는 독이 될 수 있다.
• 추천 구조는 components/core, components/ui, styles 세 레이어를 명확히 분리하고, “기억하지 않아도 되는 설계”를 지향하는 것이다.
• 이후 운영 프로젝트로 전환되거나 디자인 시스템 구축으로 발전할 경우, components/core는 라이브러리로 추출 가능한 구조를 전제로 설계해두는 것이 바람직하다.