7장. 라이브러리 운영 — 게시, 버전 관리, 팀 협업

좋은 시스템은 만들 때보다 굴릴 때 실력이 드러난다

디자인 시스템을 처음 만들 때는 대개 분위기가 좋다. 버튼이 정리되고, 색 토큰이 통일되고, 컴포넌트도 제법 그럴듯해 보인다. 문제는 그다음이다. 제품이 자라고, 참여 인원이 늘고, 급한 출시가 겹치면 라이브러리는 금방 진짜 성격을 드러낸다. 누가 바꿨는지 모르는 버튼, 어디가 최신인지 헷갈리는 파일, 조용히 깨진 인스턴스, 설명 없이 올라온 업데이트. 이때부터는 "잘 만든 시스템"보다 "잘 운영되는 시스템"이 훨씬 중요해진다.

라이브러리 운영은 화려한 기술이 아니다. 오히려 약속에 가깝다. 누구나 같은 부품을 찾을 수 있어야 하고, 바뀐 이유를 이해할 수 있어야 하며, 업데이트를 받아도 갑자기 화면이 무너지지 않아야 한다. 피그마에서 라이브러리는 단순히 자산을 모아 둔 파일이 아니라, 팀 전체가 같은 언어로 일하게 만드는 배포 장치다.¹

이 장에서 기억할 문장은 하나면 충분하다.

라이브러리는 만드는 순간보다, 바꾸는 순간의 태도로 품질이 결정된다.

라이브러리는 파일이 아니라 팀의 계약이다

피그마에서는 컴포넌트, 스타일, 변수를 만든다고 바로 팀 자산이 되는 것이 아니다. 처음엔 그 파일 안에서만 쓸 수 있고, 다른 파일에서 재사용하려면 라이브러리로 게시해야 한다.¹ 이 차이는 작아 보여도 운영에서는 매우 크다.

파일 안의 컴포넌트는 개인의 작업물이다. 하지만 게시된 라이브러리의 컴포넌트는 팀의 계약이 된다. 이름은 검색 가능해야 하고, 구조는 예측 가능해야 하며, 변경은 설명 가능해야 한다. 이제부터 그 버튼은 "내가 예쁘다고 바꾼 버튼"이 아니라 "팀 전체가 의존하는 버튼"이 된다.

그래서 라이브러리 운영의 첫 단계는 자산을 많이 만드는 것이 아니라, 무엇을 공용 계약으로 승격할지 결정하는 일이다. 아직 형태가 흔들리는 실험용 카드, 한 프로젝트에서만 쓰는 임시 배너, 이름도 덜 정리된 내부 부품까지 전부 게시하면 라이브러리는 금방 잡동사니 창고가 된다. 반대로 충분히 반복되고, 여러 화면에서 검증되었고, 다른 사람이 가져다 써도 의미가 분명한 것만 올리면 라이브러리는 가벼우면서도 강해진다.

운영은 게시 버튼보다 구조가 먼저다

게시를 잘하려면 먼저 구조를 잘 잡아야 한다. 피그마도 팀, 프로젝트, 파일 구조가 정돈되어 있어야 최신 버전을 찾고 권한을 관리하기 쉽다고 강조한다.² 실무에서는 특히 디자인 시스템을 일반 제품 파일과 분리해 두는 편이 좋다. 디자인 시스템 전용 팀이나 최소한 전용 프로젝트를 두면, 누가 수정할 수 있는지와 누가 소비만 하는지가 훨씬 선명해진다.²

가장 단순한 시작점은 이렇다. 라이브러리의 소스 파일은 하나로 정하고, 그 파일 이름은 팀이 한눈에 알아볼 수 있게 명확하게 짓는다. 피그마 라이브러리 이름은 소스 파일 이름을 그대로 따라가기 때문에, 파일명이 곧 배포 이름이 된다.¹ Core Design System, Mobile UI Library, Marketing Blocks 같은 식으로 역할이 드러나야 한다. new_final_real 같은 이름은 코미디로는 괜찮지만 운영에는 전혀 도움이 되지 않는다.

파일 내부도 역할별로 나누는 편이 좋다. 예를 들어 Foundations, Components, Patterns, Docs, Archive 같은 페이지 구조를 쓰면 신규 팀원이 들어와도 길을 잃지 않는다. 중요한 것은 멋진 체계가 아니라, 누구나 10초 안에 "어디를 봐야 하는지" 알 수 있는 체계다.

게시의 기본 원칙은 적게, 분명하게, 설명하며 올리는 것이다

피그마에서 라이브러리를 게시하려면 그 파일 안에 적어도 하나 이상의 컴포넌트, 스타일, 또는 변수가 있어야 하고, 드래프트가 아니라 프로젝트 안에 있어야 한다. 또한 라이브러리 소스 파일을 수정할 수 있는 권한이 필요하다.¹ 여기까지만 보면 기능 설명 같지만, 운영 관점에서는 중요한 뜻이 숨어 있다. 라이브러리는 개인 메모장이 아니라 팀 자산이므로, 처음부터 공유 가능한 위치와 권한 체계 안에 있어야 한다는 뜻이다.

게시할 때 가장 자주 놓치는 것이 범위 조절이다. 바뀐 것이 20개 보인다고 해서 20개를 다 올릴 필요는 없다. 피그마는 게시 흐름에서 어떤 자산을 이번 배포에 포함할지 선택할 수 있고, 아예 특정 자산을 게시 대상에서 숨길 수도 있다.¹ 이 기능은 아주 중요하다. 운영이 좋은 팀은 "만든 것"과 "배포할 것"을 구분한다.

쉽게 말해 이런 감각이다. 주방에서 요리하는 것과 식당에 내보내는 것은 다른 일이다. 내부 실험용 재료까지 손님 테이블에 올리면 안 된다. 라이브러리도 같다. 내부 구현을 돕는 원자 컴포넌트, 아직 검증되지 않은 실험 자산, 다음 분기용 초안은 팀 전체 라이브러리에 노출하지 않는 편이 더 친절하다.⁴

그리고 무엇보다 게시 설명을 성의 없이 쓰면 안 된다. 피그마는 라이브러리를 게시하거나 업데이트할 때 설명을 남기게 하고, 이 설명은 나중에 업데이트를 수락하는 사람과 파일 버전 기록에서 함께 보인다.¹ 즉, 게시 설명은 그냥 메모가 아니라 팀 커뮤니케이션의 핵심 채널이다.

좋은 설명은 길지 않아도 된다. 다만 최소한 세 가지는 담아야 한다. 무엇이 바뀌었는지, 왜 바꿨는지, 누가 영향을 받는지다. "버튼 수정"보다 "Primary Button의 세로 패딩을 12에서 14로 조정. 긴 다국어 라벨에서 높이 안정성 개선. 마케팅 랜딩과 온보딩 플로우 영향 가능"이 훨씬 낫다.

권한은 느슨하게 공유하되, 게시는 좁게 관리하자

협업이 잘 안 되는 팀은 보통 두 극단 중 하나로 간다. 아무도 못 건드리게 잠가 두거나, 반대로 누구나 언제든 올릴 수 있게 풀어 둔다. 둘 다 오래 못 간다.

좋은 운영에서는 사용 권한과 게시 권한을 분리한다. 라이브러리는 널리 사용되도록 열어 두되, 실제 게시와 구조 변경은 소수의 소유자가 책임진다. 피그마에서도 팀 관리자에게 어떤 라이브러리를 팀 파일에서 기본으로 사용할지 관리하는 권한이 있다.³ 이 말은 곧, 라이브러리 배포 범위가 개인 취향이 아니라 운영 정책의 문제라는 뜻이다.

특히 팀이 커질수록 "기본으로 켜지는 라이브러리"를 관리해야 한다. 모든 팀에 모든 라이브러리를 다 노출하면 검색 결과가 지저분해지고, 잘못된 컴포넌트를 끌어다 쓰는 일이 늘어난다. 반대로 모바일 팀에는 모바일 라이브러리, 마케팅 팀에는 캠페인 라이브러리, 전사 공통 파일에는 코어 시스템 라이브러리를 기본 제공하는 식으로 범위를 조절하면 훨씬 덜 헷갈린다.¹³

정리하면 원칙은 간단하다. 쓰는 사람은 많아도 좋다. 하지만 바꾸는 사람은 분명해야 한다.

버전 관리는 숫자놀이가 아니라 변경의 맥락을 남기는 일이다

디자인 팀이 버전 관리에서 가장 자주 하는 실수는 파일명으로 역사책을 쓰는 것이다. Library_v2, Library_v3_final, Library_v3_final_final 같은 풍경은 웃기지만, 사실 운영 실패의 전형이다. 라이브러리는 복제 파일로 버전을 쌓기보다, 같은 소스 안에서 변화의 맥락을 남기는 방식이 훨씬 안정적이다.

여기서 중요한 것은 "몇 번째 버전인가"보다 "무엇이 깨질 수 있는 변화인가"를 구분하는 감각이다. 실무에서는 보통 변경을 세 가지로 나눠 생각하면 편하다.

• 추가: 새 컴포넌트, 새 변형, 새 변수처럼 기존 사용처를 깨지 않는 변화

• 개선: 시각 정돈, 오토 레이아웃 보강, 설명 보완처럼 기존 사용처에 제한적 영향만 주는 변화

• 변경: 이름 수정, 구조 변경, 속성 삭제처럼 기존 인스턴스나 사용 습관에 영향을 주는 변화

이 분류가 중요한 이유는 배포 속도를 다르게 가져갈 수 있기 때문이다. 추가는 비교적 자주 배포해도 된다. 개선은 배포하되 영향 범위를 명확히 알려야 한다. 변경은 리뷰와 합의 없이 올리면 안 된다. 특히 컴포넌트 이름을 바꾸거나 속성을 없애는 일은 디자이너 한 명의 정리 작업이 아니라 팀 전체의 마이그레이션 작업에 가깝다.

운영이 성숙한 팀일수록 라이브러리 변경 로그를 사람이 읽을 수 있게 남긴다. 게시 설명, 버전 기록, 간단한 릴리스 노트 문서 중 무엇을 쓰든 좋다. 중요한 것은 팀원이 "업데이트가 떴다"를 보는 순간, 그 배경까지 함께 이해할 수 있어야 한다는 점이다.¹

안전한 배포는 한 번에 크게 바꾸지 않는 데서 시작한다

라이브러리 운영에서 가장 비싼 실수는 큰 정리를 큰 배포로 한 번에 밀어 넣는 것이다. 당장은 속이 시원하지만, 그날 오후부터 팀 채팅방은 불이 난다. "왜 카드가 다 달라졌죠?" "아이콘 검색이 안 돼요." "버튼 인스턴스가 이상해졌어요."

그래서 좋은 팀은 배포를 제품 출시처럼 다룬다. 아주 거창할 필요는 없지만, 최소한 다음 순서를 지키면 사고가 크게 줄어든다.

먼저 소스 파일 안에서 바꾼다. 다음으로 라이브러리 소유자끼리 미리 검토한다. 그다음 대표 화면 몇 개에서 실제 사용 인스턴스를 점검한다. 마지막으로 설명을 붙여 게시한다. 이 과정에서 "보기엔 예뻐졌는데 실제 파일에서는 불편해진 변화"를 꽤 많이 잡아낼 수 있다.

특히 대표 화면 검증이 중요하다. 버튼 컴포넌트를 고쳤다면 버튼 페이지만 보지 말고, 실제 가입 흐름·결제 화면·설정 화면에서 텍스트 길이, 줄바꿈, 오토 레이아웃, 오버라이드 유지 상태를 함께 봐야 한다. 라이브러리는 부품 창고가 아니라 실제 제품에 꽂히는 엔진 부품이기 때문이다.

협업 품질은 요청을 받는 방식에서 갈린다

운영이 나쁜 라이브러리 팀은 모든 요청이 채팅 한 줄로 들어온다. "버튼 하나 더 필요해요." "카드 종류 늘려 주세요." "색상 좀 추가해 주세요." 이 말들만으로는 아무 판단도 할 수 없다.

운영이 좋은 팀은 요청 양식을 가볍게라도 만든다. 꼭 거창한 티켓 시스템이 아니어도 된다. 최소한 다음 질문에는 답하게 하면 품질이 확 달라진다.

• 어떤 문제를 해결하려는가

• 기존 컴포넌트로 해결이 안 되는 이유는 무엇인가

• 이 변화는 한 화면의 예외인가, 반복될 패턴인가

• 누가 이 자산을 사용할 것인가

• 출시 일정상 언제 필요한가

이 다섯 가지만 명확해도 라이브러리 팀은 훨씬 좋은 결정을 내릴 수 있다. 새 컴포넌트를 만들지, 기존 변형으로 흡수할지, 그냥 사용 가이드를 보완할지 판단이 쉬워지기 때문이다.

여기서 중요한 것은 라이브러리 팀이 "부품 생산팀"이 아니라는 점이다. 정말 잘하는 팀은 요청받은 화면을 그대로 재현하는 대신, 그 뒤에 있는 반복 패턴을 찾아낸다. 한 번의 요구를 한 번의 예외로 끝내지 않고, 다음 요구까지 흡수할 구조로 바꾸는 것이다. 그게 운영 실력이다.

라이브러리 파일 안에도 문서가 있어야 한다

많은 팀이 라이브러리를 자산 창고로만 생각한다. 하지만 잘 운영되는 라이브러리에는 늘 짧은 문서가 붙어 있다. 꼭 외부 위키일 필요는 없다. 피그마 파일 안의 Docs 페이지 하나만 있어도 충분하다.

여기에는 최소한 이런 내용이 있으면 좋다. 이 라이브러리가 무엇을 다루는지, 어디까지가 공식 배포 대상인지, 어떤 페이지가 실험 영역인지, 요청과 변경은 어떻게 제안하는지, 최근 중요한 변경은 무엇인지. 이 정도만 있어도 신규 팀원이 적응하는 시간이 크게 줄어든다.

문서는 사용법을 가르치는 것 이상으로, 라이브러리의 경계를 알려 준다. 어디까지 믿고 써도 되는지, 무엇은 아직 미완성인지, 어떤 자산은 곧 사라질 예정인지가 보여야 소비하는 팀도 덜 불안하다.

자주 무너지는 운영 패턴 네 가지

라이브러리를 오래 보다 보면 비슷한 사고가 반복된다.

첫째, 소스 파일과 소비 파일의 경계가 흐려지는 경우다. 제품 파일에서 인스턴스를 손보다가, 어느 순간 메인 컴포넌트도 여기저기 생긴다. 그러면 최신 원본이 어디인지 아무도 확신하지 못한다. 메인 컴포넌트의 집은 소스 파일 하나여야 한다.

둘째, 게시 설명 없이 업데이트를 올리는 경우다. 바꾼 사람은 기억하지만, 받는 사람은 맥락이 없다. 라이브러리는 침묵할수록 신뢰를 잃는다.¹

셋째, 모든 것을 공개 라이브러리에 넣는 경우다. 아직 미완성인 부품, 내부 구현용 조각, 실험 중인 패턴까지 노출하면 검색 경험이 망가진다. 게시 대상은 큐레이션되어야 한다.¹⁴

넷째, 권한과 책임이 맞지 않는 경우다. 누구나 수정할 수 있는데 누구도 책임지지 않으면, 라이브러리는 민주주의가 아니라 무정부 상태가 된다. 반대로 한 사람만 다 할 수 있으면 병목이 생긴다. 소유자는 분명하되, 리뷰와 제안은 열려 있어야 한다.²³

현실적인 운영 모델 하나만 정하자

처음부터 거대한 거버넌스를 만들 필요는 없다. 작은 팀이라면 오히려 단순한 모델이 오래 간다. 예를 들어 이렇게 시작하면 충분하다.

라이브러리 오너 1명 또는 2명이 게시를 책임진다. 제품 디자이너는 요청을 남기고, 필요하면 초안을 제안한다. 주 1회 또는 격주 1회 짧은 시스템 리뷰 시간에 추가·개선·변경 요청을 모아서 본다. 긴급한 것은 예외 처리하되, 이름 변경이나 구조 변경 같은 큰 수정은 정기 슬롯에서만 배포한다.

이 모델의 장점은 리듬이 생긴다는 점이다. 모두가 언제 요청할지, 언제 반영될지, 언제 업데이트를 확인해야 할지 예측할 수 있다. 운영의 핵심은 통제가 아니라 예측 가능성이다.

결국 라이브러리 운영은 신뢰를 배포하는 일이다

팀이 라이브러리를 믿지 않으면 어떤 일이 벌어질까. 디자이너는 자산 패널 대신 로컬 복제를 쓰기 시작한다. 급한 일정이라는 이유로 임시 버튼을 만든다. 개발자는 "디자인 시스템이 있어도 매번 다르다"고 느낀다. 그 순간 라이브러리는 존재하지만, 시스템은 사라진다.

반대로 운영이 좋은 라이브러리는 팀의 속도를 올린다. 사람들은 검색 결과를 믿고, 업데이트 알림을 무서워하지 않고, 새 화면을 만들 때도 "이번엔 또 처음부터 그려야 하나?" 대신 "기존 구조에서 무엇을 조합하면 되지?"라고 생각한다. 그 상태가 되면 라이브러리는 단순한 자산 모음집이 아니라 팀의 작업 방식이 된다.

다음 장에서는 한 걸음 더 나아가, 이렇게 운영되는 파일이 왜 AI에게도 읽기 좋은 구조가 되는지 살펴볼 것이다. 결국 사람에게 이해하기 쉬운 시스템은, AI에게도 해석하기 쉬운 시스템이기 쉽다.

참고

¹Publish a library – Figma Learn - Help Center

²Team, project, and file organization

³Enable a library for a team

⁴Components, styles, and shared library best practices