Vue 컴포넌트 설계 원칙 가이드

아키텍처 다이어그램 — 이 글에서 다루는 핵심 흐름, 아키텍처 구조, 주요 판단 포인트를 한눈에 이해할 수 있도록 정리한 그림입니다.

# Vue 컴포넌트 설계 원칙 가이드

Vue는 템플릿 기반 구조 덕분에 UI를 읽기 쉽게 만들 수 있지만, 프로젝트가 커질수록 컴포넌트 설계 품질이 전체 유지보수성을 결정한다. 컴포넌트를 많이 나눈다고 구조가 좋아지는 것은 아니며, 재사용을 많이 한다고 설계가 우수한 것도 아니다. 중요한 것은 각 컴포넌트가 어떤 책임을 갖고, 어떤 데이터를 받고, 어떤 이벤트를 방출하며, 어떤 문맥에서 재사용되는지를 명확히 하는 것이다.

아키텍처 그림 설명

[Page]
  |
  v
[Feature Component]
  |  props in
  |  events out
  v
[Base UI Components]
  |
  v
[Design Tokens / Style Rules]

좋은 컴포넌트 구조는 위에서 아래로 갈수록 더 표현 중심이 되고, 아래에서 위로 갈수록 더 문맥 중심이 됩니다. 페이지는 기능을 조합하고, Feature Component는 유스케이스를 표현하며, Base UI는 순수 표현에 집중합니다. 그래서 props와 events는 단순 문법이 아니라 각 층의 책임 경계를 드러내는 계약이 됩니다.

컴포넌트는 재사용 단위가 아니라 책임 단위다

많은 팀이 컴포넌트를 “나중에 또 쓸 수 있는 UI 조각”으로만 생각한다. 하지만 실무에서는 재사용보다 책임이 먼저다. 어떤 컴포넌트가 특정 도메인 규칙과 화면 표현을 동시에 떠안고 있다면, 재사용 가능해 보여도 실제로는 결합도가 높다.

Vue 컴포넌트는 보통 세 층으로 나눠 생각하는 편이 좋다.

Base UI 컴포넌트: 버튼, 입력창, 카드처럼 표현 중심
Feature 컴포넌트: 검색 필터, 상품 리스트, 결제 요약처럼 특정 기능 중심
Page Composition 컴포넌트: 페이지에서 여러 기능 블록을 조합하는 역할

이 구분이 없으면 모든 컴포넌트가 중간 레벨에서 뒤섞이고, 이름만 재사용 컴포넌트일 뿐 실제로는 특정 화면 전용 코드가 된다.

props는 데이터 전달이 아니라 계약이다

Vue에서 props는 부모가 자식에게 값을 주는 통로이지만, 설계 관점에서는 더 중요하게 “컴포넌트의 입력 계약”이다. 따라서 props를 설계할 때는 수를 줄이는 것보다 의미를 명확히 하는 것이 우선이다.

좋은 props 설계의 기준은 다음과 같다.

값 이름만 보고 역할이 드러나는가
서로 강하게 결합된 값이 지나치게 흩어져 있지 않은가
단순 표시용 값과 동작 제어용 값이 혼합되어 있지 않은가
부모가 자식 내부 구현을 과도하게 알고 있어야 하지 않는가

특히 boolean props가 많아질수록 컴포넌트는 여러 변형을 억지로 수용하는 구조가 되기 쉽다. 이 경우는 컴포넌트를 분리하거나 슬롯 전략을 재설계하는 편이 나을 수 있다.

이벤트는 행위로 표현하라

Vue에서는 자식이 부모에게 이벤트를 emit하는 구조가 자연스럽다. 여기서 흔한 실수는 이벤트 이름을 내부 구현 관점으로 짓는 것이다. 예를 들어 click-item보다 select-item, submit-filter, confirm-delete처럼 사용자의 행위를 표현하는 이름이 더 낫다.

이벤트 이름이 행위를 드러내면 컴포넌트 내부 구현이 바뀌어도 부모 계약은 안정적으로 유지된다. 반대로 구현 중심 이름은 나중에 인터랙션 방식이 바뀔 때 계약도 함께 흔들린다.

슬롯은 확장성 도구이지 탈출구가 아니다

Vue의 슬롯은 매우 강력하다. 헤더, 액션, 빈 상태, 커스텀 셀 같은 확장 지점을 표현할 때 큰 힘을 발휘한다. 하지만 슬롯을 남용하면 컴포넌트는 외형만 유지한 채 사실상 내부 구조를 부모가 다시 조립하는 형태가 된다.

좋은 슬롯 설계는 다음 특징을 가진다.

반복적으로 변형이 필요한 지점만 열어 둔다.
컴포넌트의 핵심 책임은 여전히 내부에 남아 있다.
슬롯 없이도 기본 사용 경험이 충분히 완성되어 있다.

컴포넌트 분리는 길이가 아니라 변경 이유 기준으로 하라

파일 길이가 길다고 무조건 나눌 필요는 없다. 반대로 짧은 컴포넌트라도 서로 다른 이유로 자주 수정된다면 분리할 가치가 있다. 실무적으로 더 중요한 질문은 이것이다.

이 부분은 다른 화면에서도 같은 책임으로 쓰이는가
이 블록은 다른 이유로 자주 수정되는가
이 로직을 테스트하거나 교체할 때 독립 단위가 필요한가

컴포넌트 분리 기준이 없으면 지나친 세분화로 인해 오히려 코드 읽기가 어려워진다.

도메인 로직을 템플릿에 밀어 넣지 마라

Vue 템플릿은 가독성이 좋지만, 필터링 조건, 권한 분기, 데이터 변환, 복잡한 표시 규칙이 늘어나면 금세 읽기 어려워진다. 이때는 computed, composable, presenter 성격의 함수로 로직을 끌어내야 한다.

템플릿은 “무엇을 보여주는가”에 가깝게 유지하고, “왜 이렇게 계산되는가”는 스크립트나 별도 계층에서 설명하는 편이 안정적이다.

composable은 로직 공유지만 상태 은닉 주의가 필요하다

Vue 3에서 composable은 강력한 재사용 도구지만, 내부에 상태와 부작용을 함께 숨기면 디버깅이 어려워질 수 있다. 특히 여러 composable이 암묵적으로 전역 상태처럼 동작하면 컴포넌트 구조보다 더 위험한 결합이 생긴다.

따라서 composable은 다음 기준으로 쓰는 것이 좋다.

명확한 책임이 있는 로직 묶음
입력과 출력이 설명 가능한 함수 형태
필요 시 상태 공유 여부를 명확히 드러내는 구조

자주 생기는 안티패턴

범용성을 높이려다 props와 슬롯이 과도하게 많아짐
화면 전용 비즈니스 로직이 base 컴포넌트까지 침투함
템플릿 내부 조건문이 비대해져 읽기 어려워짐
emit 이름이 구현 중심이라 상위 계약이 불안정해짐
composable이 숨은 전역 상태처럼 동작함

마무리

Vue 컴포넌트 설계의 핵심은 화면을 쪼개는 기술이 아니라, 책임과 계약, 확장 지점, 도메인 경계를 명확히 하는 것이다. 잘 설계된 컴포넌트는 재사용이 많아서 좋은 것이 아니라, 변경 이유가 분명하고 읽는 사람에게 구조가 드러나서 좋다.

결국 Vue에서 좋은 UI 구조를 만든다는 것은 예쁜 템플릿을 만드는 것이 아니라, 컴포넌트를 통해 애플리케이션의 책임 분리를 드러내는 일이다.

운영 환경에서 어려워지는 지점

Vue 컴포넌트 설계는 컴포넌트가 넓게 공유되는데도 계약, 토큰, 접근성 보장이 약하면 빠르게 실패한다.
진짜 어려움은 버튼 라이브러리를 만드는 것이 아니라 제품 요구가 다양해져도 일관성을 유지하는 일이다.
성숙한 시스템은 재사용, 탈출구, 거버넌스를 함께 균형 잡아야 한다.

중요한 아키텍처 결정

디자인 토큰, 프리미티브, 패턴, 제품 전용 컴포넌트를 분리한다.
접근성, 테마, 조합 API를 일급 아키텍처로 다룬다.
컴포넌트 계약과 마이그레이션 규칙을 의도적으로 버전 관리한다.

실무 예시

건강한 디자인 시스템 스택은 보통 계층이 분명하다.

tokens -> 색상, 간격, 타이포그래피
primitives -> Button, Input, Stack
patterns -> FormSection, DataTableToolbar
product features -> 페이지 전용 조합

피해야 할 안티패턴

제품 전용 로직을 범용 컴포넌트 안에 넣는 것.
조합 지점을 설계하지 않고 props만 끝없이 늘리는 것.
채택이 넓어진 뒤에야 접근성 부채를 보기 시작하는 것.

운영 체크리스트

공용 컴포넌트 API 표면 증가를 검토한다.
사용 예시와 제약을 문서화한다.
접근성과 테마 변형을 지속적으로 테스트한다.
팀이 시스템을 우회하는 지점과 이유를 추적한다.

최종 판단

Vue 디자인 시스템은 재사용 부품 모음이 아니라 신뢰할 수 있는 제약을 정의할 때 비로소 플래그십 자산이 된다. 시각적 일관성만큼 거버넌스와 계약 품질이 중요하다.

다음으로 읽기 좋은 글

🖥️ Frontend

AI 서비스 개발, 운영, 성능개선을 하나의 루프로 연결합니다