디자인 시스템, 컴포넌트와 문서화는 어떻게 함께 커가야 할까

 

신규 입사 디자이너가 Figma 라이브러리를 열었을 때 가장 먼저 마주치는 감정은 대부분 "이 버튼은 언제 써야 하지?"라는 막막함이다.

컴포넌트는 잘 만들어져 있는데, 그 컴포넌트가 왜 존재하고 어떤 상황에 써야 하는지 알려주는 문서가 없는 경우가 특히 국내 스타트업에서는 흔하다. 디자인 시스템이 진짜로 힘을 발휘하는 순간은 컴포넌트와 문서가 한 몸처럼 움직일 때다.

 

컴포넌트를 만들 때 자주 놓치는 세 가지

컴포넌트 하나를 만드는 일은 생각보다 손이 많이 가는 작업이다. 버튼 하나만 봐도 색상, 크기, 아이콘 유무에 따라 조합이 수십 가지로 늘어난다. 이 과정에서 자주 놓치는 부분들이 있다.

 

1) 상태(State)를 끝까지 정의하지 않는다

많은 팀이 기본 상태와 눌렀을 때 상태 정도만 만들어두고 개발 단계로 넘어간다. 그런데 실제 서비스에서는 로딩 중, 비활성화, 에러, 포커스 상태까지 모두 필요하다. 예를 들어 회원가입 폼의 '인증번호 받기' 버튼은 입력값이 없을 때 비활성화되어야 하고, 요청을 보내는 동안에는 로딩 스피너가 돌아야 하며, 서버 응답이 늦어지면 재요청 안내 문구가 떠야 한다. 이 네 가지 상태 중 하나라도 디자인 단계에서 빠지면, 개발자는 결국 자기 판단으로 상태를 만들게 되고 그 순간부터 서비스 곳곳의 버튼 동작이 조금씩 달라진다.

 

버튼 하나에도 최소 여섯 개의 상태가 필요할 수 있다

 

 

2) 이름 짓는 방식이 팀마다 제각각이다

'Primary Button', '주요 버튼', 'btn-main'처럼 같은 대상을 부르는 이름이 디자인, 기획, 개발 문서에서 전부 다른 경우가 많다. 이렇게 되면 QA 단계에서 "이 화면에 있는 버튼이 어떤 컴포넌트인지" 확인하는 데만 시간이 걸린다. 처음부터 하나의 이름 체계를 정하고, 디자인 파일과 코드 저장소, 기획 문서 모두 같은 이름을 쓰도록 맞춰두는 편이 훨씬 효율적이다.

 

3) 접근성은 나중 문제로 미룬다

글자와 배경의 명도 대비, 키보드만으로 이동했을 때의 포커스 표시, 스크린리더가 읽을 대체 텍스트는 출시 직전에 급하게 챙기기보다 컴포넌트를 처음 만드는 시점에 함께 정의하는 것이 훨씬 수월하다. 공공기관이나 금융 서비스처럼 접근성 심사가 있는 프로젝트라면 더더욱 그렇다.

 

 

컴포넌트 구조를 그림으로 먼저 그려보기

프로덕트가 커지고 팀원이 늘어날수록 "이 컴포넌트, 저 컴포넌트랑 뭐가 다른 거예요?"라는 질문이 자주 나온다. 카드형 컴포넌트가 세 개나 있는데 서로 미묘하게 겹치거나, 이미 있는 컴포넌트를 모르고 새로 만드는 일도 벌어진다.

 

이럴 때는 코드를 짜기 전에, 컴포넌트의 구조와 관계를 마인드맵처럼 그림으로 먼저 정리해보는 것이 도움이 된다.

 

어떤 하위 요소로 이루어져 있는지, 어떤 화면에서 쓰이는지를 한눈에 보이게 만들면 디자이너와 개발자가 같은 그림을 보고 이야기할 수 있다.

 

하위 유형과 실제 사용 화면까지 함께 표시하면 중복 제작을 막을 수 있다

 

 

새 컴포넌트를 등록하기 전에 이 세 가지만 문서에 적어도 절반은 해결된다: 어떤 데이터를 보여주는가, 어느 화면에서 쓰이는가, 기존 컴포넌트와 무엇이 다른가.

 

 

문서화는 네 개의 축으로 나누면 정리가 쉽다

"문서화를 잘하자"는 말은 누구나 하지만, 막상 시작하면 어디부터 손대야 할지 막막하다. 실무에서는 아래 네 가지 축으로 나누어 정리하면 빠뜨리는 부분 없이 진행할 수 있다.

 

타이포그래피, 색상, 컴포넌트, 플로우 - 문서화의 네 축

 

 

타이포그래피와 색상: '숫자'가 아니라 '용도'로 설명하기

"본문은 15px, 회색은 #6B7280"이라는 정보만 적어두면 나중에 그 값이 왜 그렇게 정해졌는지 아무도 기억하지 못한다. 대신 "본문(body)은 모바일 화면에서 가장 많이 읽히는 텍스트이므로 15px 이하로 내려가지 않는다", "경고 색상은 결제 실패나 재고 부족처럼 사용자의 행동이 필요한 상황에만 사용한다"처럼 용도와 함께 기록해두면, 새로 합류한 팀원도 규칙을 이해하고 응용할 수 있다.

 

컴포넌트 문서: 코드와 디자인이 같은 언어를 쓰게 만들기

컴포넌트 문서에는 사용 예시, 언제 쓰면 안 되는지, 관련 컴포넌트와의 차이점이 함께 들어가야 한다.

예를 들어 배달 앱의 '가게 카드' 컴포넌트라면 "리스트형과 그리드형 두 가지 레이아웃이 있으며, 그리드형은 즐겨찾기 목록에서만 사용한다"처럼 조건을 명확히 적어두는 식이다. 이렇게 해두면 개발자가 새로운 화면을 만들 때 디자이너에게 매번 물어보지 않고도 문서만으로 판단할 수 있다.

 

사용자 플로우: 화면과 화면 사이의 맥락을 남기기

개별 컴포넌트는 잘 정리되어 있어도, 그 컴포넌트들이 어떤 순서로 이어지는지에 대한 기록이 없으면 새로운 기능을 추가할 때마다 처음부터 흐름을 다시 파악해야 한다. 회원가입, 결제, 예약 변경처럼 여러 화면을 거치는 흐름은 별도의 다이어그램으로 남겨두면 기획자, 디자이너, 개발자가 같은 그림을 보며 논의할 수 있다.

 

문서는 한 번 쓰고 끝나는 게 아니다

디자인 시스템 문서를 만들고 나서 가장 흔하게 실패하는 지점은 '업데이트'다. 컴포넌트는 계속 바뀌는데 문서는 처음 만들었을 때 모습 그대로 남아 있으면, 시간이 지날수록 아무도 문서를 신뢰하지 않게 된다.

 

• 스프린트 회고 때 "이번에 바뀐 컴포넌트가 있는지" 5분만 확인하는 루틴을 넣는다
• 디자인 시스템 전용 슬랙 채널을 만들어 변경 사항과 질문을 한곳에 모은다
• 컴포넌트에 버전을 붙여서 어떤 화면이 구버전을 쓰고 있는지 추적한다
• 실제로 문서를 보는 사람들(디자이너, 개발자, PM)에게 분기마다 피드백을 받는다

결국 좋은 디자인 시스템은 한 번 완성하고 끝내는 결과물이 아니라, 제품과 함께 계속 손이 가는 살아있는 규칙집에 가깝다.

 

 

출처:

https://medium.com/design-systems-collective/design-system-best-practices-components-and-documentation-bdb020e02172