[2팀 김우정] Chapter3-1. UI 컴포넌트 모듈화와 디자인 시스템

[kimfriendship]

Chapter3-1. UI 컴포넌트 모듈화와 디자인 시스템

과제 목표

레거시 코드베이스를 현대적인 디자인 시스템으로 개편하는 실무 경험

1. 정리되지 않은 레거시 코드의 문제점 식별 및 분석
2. TailwindCSS, shadcn/ui, CVA 등의 현대 도구 활용
3. 일관된 디자인 토큰과 컴포넌트 API 구축
4. UI와 비즈니스 로직이 적절한 분리된 리팩토링

---

Before 패키지 분석 후 After 패키지 개편

개편 목표

디자인 시스템

• TailwindCSS 기반 일관된 디자인 토큰 정의
• 하드코딩 제거, 재사용 가능한 스타일 시스템 구축
• dark mode, 반응형 등 확장 가능한 구조

컴포넌트 아키텍처

• UI 컴포넌트는 순수하게 UI만 담당
• 도메인 로직은 적절히 분리
• 일관된 컴포넌트 API 설계

사용할 도구

TailwindCSS 4.x

• 디자인 토큰 기반 스타일링
• 유틸리티 클래스 활용
• dark mode, 반응형 내장 지원

shadcn/ui

• Radix UI 기반, 접근성 내장
• 복사 가능한 컴포넌트 (라이브러리가 아닌 소스코드)
• 자유로운 커스터마이징

CVA (Class Variance Authority)

• 선언적 variants 패턴
• 타입 안전한 스타일 조합
• 조건부 스타일링 처리

React Hook Form + Zod

• 선언적 폼 검증
• 타입 안전한 스키마
• 최소 리렌더링 최적화

---

필수 과제

1. 디자인 시스템 구축

• TailwindCSS 설정 및 디자인 토큰 정의
• shadcn/ui 컴포넌트 설치 (Button, Input, Select, Card, Table 등)
• CVA를 활용한 variants 패턴 적용
• 일관된 스타일 시스템 구축

2. Before 패키지 분석

• Before 패키지 실행 및 전체 코드 탐색
• 스타일링, 컴포넌트 설계, 폼 관리 측면에서 문제점 파악
• 개선이 필요한 부분과 그 이유 정리

3. 컴포넌트 개편

• UI와 비즈니스 로직 분리
• 순수한 UI 컴포넌트로 재구성
• 일관된 컴포넌트 API 설계
• 적절한 컴포넌트 구조 설계

---

심화 과제

• Dark Mode 완전 지원 (CSS Variables + Tailwind)
• Design Token 시스템 고도화 (색상 팔레트, 타이포그래피 스케일)
• 뷰와 비즈니스로직이 분리되도록

---

과제 회고

개선된 페이지 링크
스토리북 링크

Before 패키지에서 발견한 문제점

• UI에 비즈니스 로직이 너무 강하게 결합되어 있는 문제
  Button 같은 컴포넌트가 user, post 같은 도메인 개념을 알고 있었고, 각 도메인의 로직들이 하드코딩 되어 있었습니다. 코드를 이해하기도 너무 어려웠고 유지보수성이 떨어져 보였습니다. 또 Badge에서 사용하는 색상 값들이 시멘틱하지 않다는 생각이 들었습니다. 예를 들어 디자인 시스템이 잘 형성되어 있다면, A라는 케이스이가 warning과 전혀 관계가 없는데 배경을 warning 색이 아닌 yellow 색으로 만들었을 것 같았습니다. 이 부분에서 왜 디자인 토큰에 계층이 나눠져 있어야 하는지 좀 더 체감했던 것 같습니다. 근데 UI와 로직이 섞여있는 스파게티 코드가 그렇게 낯설지도 않은데,, 제3자가 보면 저의 코드도 그렇게 보여질 것 같아서 많이 찔렸습니다.. 이번 과제도 그러지 않으려고 노력한 거에 비해 결과가 만족스럽진 않아서 아쉽습니다.

• 스타일링 방법이 통일되지 않은 문제
  className으로 component.css에서 스타일링과 인라인 스타일링이 마구 섞여있었는데요. 불필요하게 중복되는 부분도 많고, 그래서 유지 보수가 힘들어 보였고, 어디서 스타일을 먹이고 있는지 파악하기도 힘들었습니다. 실제로 shadcn을 도입하면서 계속 패딩이 적용되지 않아서 뭔가 제가 잘못 설정했나 한참을 헤맸는데, component.css에서 일괄 적용했던 거였습니다... 그리고 스타일을 tailwind로 개선하면서 느낀 건데 확실히 AI가 다른 방식보다도 tailwind로 스타일링 해주는 데 더 탁월한 것 같다는 느낌을 받았습니다. 기존 인라인 스타일을 탭으로 아주 잘 교체해주었습니다.

• 모든 상태관리를 page단에서 한번에 하는 문제
  비즈니스 로직은 상위에서 할 수록 좋다고 생각하는데, 너무 많은 로직이 한번에 모여있어서 관심사 분리가 필요해보였습니다. 그리고 post, user 도메인이 다른데 비슷한 로직으로 보이면 handler를 다 공용으로 쓰다보니 코드가 점점 어지러워진 것 같습니다. 근데 직접 개선 작업을 하다보니 상위에서 대부분의 로직들을 다루려고 하다보면 로직들이 너무 많이 모여서 어떻게 관리할지 고민이 되더라구요. 저는 usePostAction, useUserAction과 같이 커스텀훅으로 나누었는데 이렇게 나눈 게 좋은 방법인지는 모르겠습니다.

개편 과정에서 집중한 부분

디자인 시스템이 주제였던만큼 디자인 시스템 구축에 집중하였습니다. 디자인 토큰을 정의(색상 팔레트, CSS 변수, Tailwind config 매핑)하고 TailwindCSS와 shadcn/ui를 활용한 일관된 스타일 시스템을 구축하려 노력했습니다. 생각보다 시간이 많이 들어 디자인 토큰을 세세하게 정의하진 못하였고 크게 색상, 폰트정도만 적용해보았습니다. 또 기존 디자인에서 더 예쁜 컴포넌트들로 바꾸고 싶었지만 디자인이 쉽지 않아 후반부로 갈수록 shadcn 기본 디자인을 활용하여 CSS 작업보다는 설계에 투자하게 됐던 것 같습니다.

또 컴포넌트 구조를 개선하면서 FSD를 도입해 보았습니다. 평소에 FSD 구조로 개발할 일이 많지 않아서 경험해보고 싶었고, 평소에 개발을 할 때 features 단위로 나누는 게 작업하기 편했던 것 같아서 좀 더 고도화 해보고 싶은 마음도 있었습니다. 하지만 과제를 하면서 FSD를 적용하기엔 좀 역시나 규모가 작은 프로젝트였던 것 같다는 생각도 계속 들었습니다. 그래서 entities는 제외하고 shared, features, widgets, pages로만 나눠보았습니다. 그런데도 컴포넌트나 유틸, 훅을 만들때 어디에 위치시켜야 할지 고민이 많이 되었습니다.

또 비즈니스 로직과 UI를 분리하는 데 초점을 맞췄는데요. 그래서 최대한 로직을 상단으로 끌어올리고 단방향 데이터 플로우를 구현하려고 했습니다. 어떻게 하면 좀 더 순수하게 만들 수 있을까? 고민을 많이 하면서 개선 작업을 하긴 했는데, 뒤로 갈 수록 특히 widgets 부분에서 코드가 더러워지는 느낌이 있어서 설계를 잘못했나 다시 생각해보게 되는 것 같습니다.

사용한 기술 스택 경험

• TailwindCSS
  회사에서 디자인 시스템을 사용하고 있지만 디자인 토큰과 CSS 변수를 정의하고 적용하는 건 처음 해보았습니다.
• shadcn/ui + CVA
  실무에서 차크라를 사용하다 shadcn으로 넘어가려고 하고 있는데 shadcn을 사용해보면서 좀 더 깊이 이해하게 된 것 같습니다.
• React Hook Form + Zod
  과제 필수요소가 아닌 줄 알고 Input, Select로 하나씩 폼에 추가해서 직접 상태관리 했다가 뒤늦게 도입했는데요, 그래서 더 효율성과 유용함을 많이 느꼈던 것 같아요.
• 다크모드
  다크모드 처음 구현해봤는데, 대부분 AI의 힘을 빌렸지만 재밌었습니다. (페이지 우측하단에 테마변경 버튼이 있습니다.)

어려웠던 점과 해결 방법

리뷰받고 싶거나 질문하고 싶은 내용

[kimfriendship]

비즈니스 로직을 최대한 상위로 끌어올리려다 보니, widgets단에 있는 PostDashboard 로직이 너무 모이게 되어 코드 복잡도가 올라가는 것 같다는 생각이 들었는데요. 그래서 usePostAction이라고 커스텀 훅으로 빼서 로직을 분산 시켜보았는데 이게 최선의 방법은 아닌 것 같아서, 다른 분들은 어떻게 구조를 짜셨는지 궁금합니다.

usePostAction에서 api만 다뤘으면 모르겠는데, 그게 아니라 alert 같이 ui 관련 로직도 섞여 들어간 것 같아서 찜찜하더라구요. 어떻게 개선하면 좋을까요?

[kimfriendship]

여러분들은 게시물 모달 만들때 컴포넌트를 어떻게 나누셨나요?

저는 PostFormModal을 하나로 만들까 하다가, Form에 대한 상태관리가 많아서 PostForm을 따로 만들어서 폼 조작에 관련된 로직만 넣어두고 그걸 PostFormModal에서 가져다 쓰게 했는데요. 그러다보니 또 로직이 복잡해진 포인트가, 생성 버튼이 모달 쪽에 있어야 할 것 같아서 게시물 생성/수정 로직이 양쪽에서 필요하게 되더라구요. 제가 react-hook-form을 처음 써봐서 뭔가 제대로 사용하지 못한 거 같은 기분도 드네요.