도입을 이끄는 문서화 (새 탭에서 열림)
디자인 시스템 문서는 컴포넌트 목록을 나열하는 자료가 아니라, 디자인 의도와 구현 방법을 연결해 팀의 실제 사용을 이끄는 제품이어야 한다. 좋은 문서는 디자이너와 개발자 사이의 언어 차이를 줄이고, 일관된 의사결정·효율적인 온보딩·플랫폼 간 품질 유지를 가능하게 한다. 이를 위해 조직에 맞는 단일 진실 공급원(source of truth)을 정하고, 시스템과 함께 계속 진화하는 문서로 운영해야 한다. ## 문서화가 필요한 이유 - Razorpay는 디자인 시스템 Blade를 도입하기 전 팀마다 버튼 상태나 텍스트 필드 오류 처리 방식을 놓치는 일이 있었다. - 문제의 본질은 단순한 품질 부족이 아니라 디자인 의도와 구현 방식이 제대로 전달되지 않는 커뮤니케이션 문제였다. - 개발자와 디자이너 사이의 언어 차이로 다음과 같은 불일치가 발생할 수 있다. - 컴포넌트와 속성의 명칭이 서로 다름 - 디자인의 상태와 실제 코드 구현이 다름 - 제품의 시각적·상호작용적 기대치가 어긋남 - 문서는 단순히 “무엇이 있는가”를 보여주는 데 그치지 않고, 각 결정의 **방법(how)** 과 **이유(why)** 를 설명해야 한다. - 효과적인 문서는 다음을 돕는다. - 디자인 원칙과 구현 세부 사항 이해 - 여러 제품과 플랫폼에서 일관된 결정 - 신규 팀원의 빠른 온보딩 - 디자이너와 개발자 간 협업 개선 ## 단일 진실 공급원 정하기 문서화를 시작할 때 가장 먼저 결정할 것은 무엇을 쓸지가 아니라 **어디에 둘지**다. - 디자인 시스템이 성장하고 조직이 커질수록 정보가 여러 도구에 분산되기 쉽다. - 공유 드라이브의 정적 PDF처럼 한 번 만들어 놓고 갱신하지 않는 방식은 빠르게 낡는다. - 전용 문서 사이트, 협업 워크스페이스 등 조직의 규모와 업무 흐름에 맞는 저장소를 선택해야 한다. - 중요한 것은 도구 자체보다 팀이 “최신 정보는 어디에 있는가”를 명확히 알 수 있게 하는 것이다. - 문서는 디자인 파일, 코드 저장소, 개발자 도구와 연결되어야 하며, 디자이너와 개발자가 같은 기준을 참조할 수 있어야 한다. ## 맞춤형 문서 사이트의 역할 본문은 대규모 조직의 경우 자체 문서 사이트가 디자인 시스템을 도구와 프로세스에 깊이 통합하는 데 유리하다고 설명한다. - 여러 제품과 플랫폼을 운영하는 조직은 전용 사이트를 통해 문서 구조와 탐색 경험을 직접 설계할 수 있다. - 컴포넌트의 시각적 예시뿐 아니라 사용법, 코드 구현, 상태, 접근성 지침까지 한곳에서 제공할 수 있다. - 디자인 시스템이 사용하는 도구와 개발 워크플로에 맞춰 문서를 확장할 수 있다. - 다만 자체 사이트를 구축하는 것만으로는 충분하지 않으며, 최신 상태를 유지하는 운영 체계가 함께 필요하다. ## 도입을 이끄는 살아 있는 문서 - 문서는 디자인 시스템과 별개로 관리되는 부가 자료가 아니라 시스템의 일부여야 한다. - 컴포넌트가 변경되면 관련 사용법과 코드 예시도 함께 갱신되어야 한다. - 문서에는 컴포넌트의 외형뿐 아니라 다음 정보가 포함되어야 한다. - 언제 사용하고 언제 사용하지 않는지 - 지원하는 상태와 속성 - 상호작용 및 오류 처리 방식 - 디자인 결정의 배경과 목적 - 개발자가 실제로 적용할 수 있는 구현 정보 - 사용자가 문서를 읽은 뒤 바로 디자인하거나 코드를 작성할 수 있어야 adoption으로 이어진다. ## 실용적인 결론 디자인 시스템 문서는 “보관용 설명서”가 아니라 팀의 공통 언어이자 제품 사용 경험의 일부로 운영해야 한다. 하나의 공식 출처를 정하고, 디자인·코드·문서의 변경을 연결하며, 각 컴포넌트의 사용법과 설계 이유까지 기록하는 방식이 가장 실용적이다.