사람과 AI가 같은 기준으로 구현하는 디자인 시스템, MBSW
2025년 초 입사 당시 뤼이도에는 디자인 시스템이 없었습니다.
도메인마다 UI를 복사해서 사용했고, global.css에는 어디에서, 어떤 목적으로 사용하는지 파악하기 어려운 class가 쌓여 있었습니다. 간단한 UI 하나를 구현하려고 해도, 먼저 비슷한 코드를 찾고 공통으로 쓸 수 있는 컴포넌트가 있는지, 왜 이런 스타일이 적용돼 있는지 그동안의 히스토리를 확인해야 했습니다.
기능 구현보다 파일을 찾고 퍼블리싱하는 데 많은 시간을 썼고, 디자인과 같은지 확인하는 QA도 반복됐습니다.
이 반복을 줄이기 위해 3주 동안 첫 디자인 시스템을 만들었습니다. 목표는 하나, 화면에서 공통으로 사용하는 컴포넌트를 한곳에 모아 재사용할 수 있게 하는 것이었습니다.
기존 화면에서 공통 패턴을 추출하는 방식으로 시작하다 보니, 컴포넌트의 구분과 프로퍼티도 당시 서비스의 사용처에 맞춰졌습니다. 조금씩 다른 화면을 수용하면서 유사한 컴포넌트가 여러 개 생겼고, 색상과 간격을 공통 토큰으로 관리하는 구조도 갖추지 못했습니다.
이 한계는 기능이 추가될 때 드러났습니다. 새로운 요구사항을 담으려면 공통 컴포넌트를 수정하거나, Figma에서 인스턴스를 detach해 해당 화면에 맞게 고치는 일이 잦아졌습니다. 화면별 예외가 늘어나면서 공통으로 유지해야 할 범위도 흐려졌습니다. 디자인 기준이 Figma에 있었기 때문에 Figma에서 컴포넌트가 바뀌면 클라이언트에 구현된 공용 컴포넌트도 수정해야 했습니다. 두 작업을 연결하는 것은 사람의 기억과 커뮤니케이션이었고, 새 기능을 만들 때마다 그 비용이 함께 쌓였습니다.
사람끼리 협업할 때는 감당 가능했습니다. 비효율적이긴 해도 조금 더 꼼꼼하게 신경 쓰면 됐으니까요.
하지만 우리 팀에 AI가 들어오자 감당할 수 없어졌습니다.
AI에게 디자인과 코드를 전달하면 매번 다른 결과가 나왔습니다. 이미 있는 컴포넌트 대신 새로 구현하거나, 토큰을 누락하거나, 비슷해 보이는 다른 값을 선택하는 경우가 빈번했습니다. 작업하는 사람과 AI의 맥락에 따라 결과가 조금씩 달라졌고, 그 차이는 다시 사람이 찾아야 했습니다.
히스토리를 아는 사람이 맥락을 설명하고, 리뷰에서 잡아내고, QA에서 다시 맞추는 방식은 지속적으로 제품팀의 병목이 됐습니다.
Riido 2.0을 준비하면서, 기존 컴포넌트를 보완하는 것을 넘어 어떤 기준으로 만들고, 그 기준에 맞게 구현됐는지 어떻게 확인할지까지 다시 설계해야겠다고 생각했습니다.
그렇게 첫 디자인 시스템을 만든 지 약 1년 만에 문방사우, MBSW를 새로 만들기 시작했습니다. 특정 시점의 화면을 모아놓은 시스템에서 나아가, 제품과 작업자가 바뀌어도 같은 기준으로 만들고 활용할 수 있는 구조가 필요했습니다.
이 글에서는 그 기준을 디자인 원본부터 구현, 검증과 배포까지 어떻게 연결했는지 이야기해 보려고 합니다.
1/ 사람과 AI가 함께 쓸 기준부터 정했습니다
목표는 분명했습니다. 누가 어떤 환경에서 퍼블리싱하든 99% 이상 디자인과 같은 결과가 나오게 하는 것. 궁극적으로는 이 과정에 사람의 리소스가 들어가지 않도록 하는 것입니다.
이미 합의한 값을 옮기고 대조하는 일은 자동화하고, 사람은 비즈니스 로직과 성능, 구조 설계와 같이 판단이 필요한 영역에 집중하고 싶었습니다.
Riido 2.0의 화면 설계와 제품 구현도 함께 진행해야 했기 때문에, 디자인 시스템을 완성한 뒤 화면에 적용하는 순서로 진행할 수 없었습니다. 컴포넌트를 만들고 사용하는 일이 병렬로 진행되는 만큼, 매번 서로에게 확인하지 않아도 작업을 이어갈 수 있는 기준이 필요했습니다.
그래서 설계에서 세 가지를 신경 썼습니다.
- 제품의 요구사항과 공통 컴포넌트의 책임을 나누는 것.
특정 화면에 맞춰 공통 프로퍼티를 계속 늘리지 않도록, 디자인 시스템이 제공할 형태와 동작, 클라이언트가 조합할 제품 기능의 경계를 정했습니다. 색상과 간격 같은 공통 값도 토큰으로 관리해 개별 화면의 스타일을 다시 해석하는 일을 줄이고자 했습니다. - 사람과 AI가 같은 입력에서 시작하게 하는 것.
Figma의 어느 버전을 보고 있는지, 그 값이 어떤 토큰을 의미하는지, 화면에 드러나지 않은 사용 규칙은 무엇인지 확인할 수 있어야 했습니다. 기계가 읽을 수 있는 값과 사람이 정해야 하는 의도를 구분하고, 한 번 확인한 관계는 다음 작업에서도 그대로 쓸 수 있어야 합니다. - 합의한 규칙을 구현과 검증까지 이어가는 것.
문서에 적혀 있어도 구현하는 사람이 기억해야만 지켜지는 규칙이라면 같은 문제가 반복됩니다. 코드로 확인할 수 있는 조건은 타입과 검사로 옮기고, 검증한 결과를 패키지로 배포해 클라이언트에서 함께 사용하도록 했습니다.
2/ 디자인 원본과 구현의 책임을 나눴습니다
먼저 디자인 시스템을 클라이언트 코드에서 완전히 분리했습니다. 제품 기능을 개발하다 공통 컴포넌트를 직접 고치는 흐름에서 벗어나, 공통 변경은 디자인 시스템에서 검토하고 배포한 뒤 제품이 가져다 쓰도록 경계를 두었습니다.
디자인 원본을 관리하는 mbsw-design-source와 구현·검증·배포를 담당하는 mbsw 저장소를 따로 뒀습니다. 디자인의 의도와 기준을 검토하는 일, 이를 React 코드로 구현하고 배포하는 일의 책임을 구분하기 위해서입니다.
디자인을 바꾸는 사람이 React API까지 결정해야 할까요? 반대로 컴포넌트를 구현하는 사람이 화면에 없는 동작을 임의로 정해도 될까요? 디자이너와 협업하려면 이런 책임 경계부터 명확하게 정해야 했습니다.
컴포넌트의 시각적 디자인은 Figma를 따르지만, 클라이언트가 쓸 수 있는 기능은 설치한 패키지 버전으로 결정됩니다. 디자인 원본에 새 기능이 있어도 구현과 검증, 배포를 거쳐야 제품에서 사용할 수 있습니다. 제품에 필요한 공통 기능이 빠져 있다면 디자인 시스템 쪽에서 다루도록 했습니다.
3/ Figma만으로 전달되지 않는 의도를 문서에 담았습니다
책임을 나누면서 많이 고민한 부분은 Figma에서 어디까지 읽어낼 수 있느냐는 것이었습니다.
padding이나 size, 연결된 변수는 도구로 읽을 수 있습니다. 하지만 키보드로 조작할 때의 동작이나 특정 상태가 갖는 의미까지 모두 알 수는 없습니다. Figma에 있는 프로퍼티도 코드에서는 다르게 다뤄야 할 때가 있습니다.
Button을 예로 들어보겠습니다. Figma에는 state라는 축으로 default, hover, disabled가 있습니다. 각 상태의 모양을 보여주기 위한 구분입니다. 코드에서는 hover 상태를 CSS의 :hover로 표현하고, 비활성화는 HTML의 disabled 속성으로 처리해야 합니다. state="hover"라는 prop을 만드는 것만으로는 실제 버튼이 완성되지 않습니다.
그래서 컴포넌트마다 두 종류의 파일을 두었습니다.
components/button/
├── button.md # 디자인 의도, 사용 규칙, 코드에서 필요한 동작
└── button.figma.json # 스크립트로 추출한 Figma 관측값
MD에는 디자인팀이 디자인 의도와 사용 규칙을 정리합니다. JSON은 개발팀에서 만든 스크립트로 자동 생성합니다. 이 스크립트는 Figma의 크기와 간격, 구조와 변수 연결처럼 도구가 실제로 읽어낸 사실을 정해진 형식으로 정리합니다.
Figma에서 읽을 수 없다고 해서 아직 결정되지 않은 것은 아닙니다. 화면에 그리지 않은 동작도 이미 합의했을 수 있습니다. 이 차이를 문서에 남겨 사람과 AI가 그 부분을 임의로 채우지 않도록 했습니다.
이 두 파일을 바탕으로 어떤 prop을 공개할지, 접근성과 이벤트를 어떻게 처리할지는 mbsw에서 정합니다. 디자인을 전달할 때 코드의 형태까지 미리 정할 필요가 없고, 구현하는 쪽에서도 의도를 확인하게 됩니다.
4/ 같은 원본에서 같은 JSON이 나오도록 바꿨습니다
Figma 컴포넌트를 MCP로 읽고, AI가 그 내용을 JSON으로 정리하니 같은 컴포넌트를 추출해도 결과가 조금씩 달랐습니다. AI가 어떤 정보를 남길지 선택하고 정리하는 과정에서 해석이 들어갔고, 실제로 읽은 값에 추론한 내용이 섞이기도 했습니다.
같은 원본을 보고 있다면, 누가 어떤 환경에서 추출하든 같은 결과가 나와야 합니다. 원본을 한곳에 모아두는 것만으로는 충분하지 않았습니다. 그 원본을 구현에 사용할 데이터로 옮길 때도 같은 규칙을 따라야, 사람과 AI가 함께 신뢰할 수 있는 SSOT가 될 수 있습니다.
그래서 Figma REST API를 활용한 스크립트로 컴포넌트 JSON을 생성하도록 바꿨습니다. API에서 읽은 데이터를 정해진 규칙에 따라 정리하도록 해, AI가 관측값을 해석하고 재작성하던 단계를 없앴습니다.
원본도 고정해야 했습니다. 매번 Figma의 최신 상태를 읽으면 작업 중에 디자인이 바뀔 수 있기 때문입니다. 디자인팀이 승인한 버전과 추출할 노드를 지정하고, API 응답은 스냅샷으로 보관했습니다. 스크립트의 버전과 추출 규칙도 함께 고정해 같은 입력으로 관측값을 다시 생성할 수 있게 했습니다.
5/ 읽어낸 값을 MBSW의 토큰과 연결했습니다
같은 원본을 일정한 방식으로 읽을 수 있게 된 뒤에도 한 가지 문제가 남았습니다. 읽어낸 값이 MBSW의 어떤 토큰을 의미하는지 알아야 했습니다.
Figma에서 받은 RGB(A) 값은 스크립트를 거쳐 #5D4FF9FF 같은 HEX 값으로 정리됩니다. 하지만 용도가 다른 토큰이 같은 색을 가질 수 있어, 색상 값만으로는 사용할 토큰을 결정할 수 없었습니다. 토큰과 정확히 매핑하려면 연결된 변수의 상세 정보가 필요했습니다. 당시 플랜에서는 Variables API를 사용할 수 없어, 읽기 전용 플러그인을 추출 과정에 붙이고 변수의 식별 정보와 Collection, 적용된 Mode, alias 관계를 함께 가져왔습니다.
가져온 정보는 Foundation 원본의 토큰과 연결했습니다. 변수와 Collection의 key, Mode를 기준으로 어떤 토큰에 해당하는지 확인하고, 그 관계를 매핑표로 남겼습니다. 한 번 확인한 연결은 다음 추출에서도 그대로 사용했습니다. 연결이 없거나 모호할 때는 이름이나 색상이 비슷하다는 이유로 AI가 토큰을 선택하게 두지 않고, 먼저 확인하도록 했습니다.
플러그인은 현재 열려 있는 문서를 읽기 때문에, 승인한 디자인과 같은지도 확인해야 했습니다. 승인 버전의 REST 스냅샷과 플러그인 추출 결과에서 공통으로 확인할 수 있는 구조와 값을 비교했습니다.
이렇게 원본 버전과 변수 정보, 매핑표를 함께 고정해 두고, 다음에 누가 추출하더라도 같은 디자인이 같은 토큰으로 이어지도록 했습니다.
6/ 명세를 제품에서 사용할 패키지로 옮겼습니다
이렇게 정리한 디자인 의도와 관측값은 mbsw에서 제품에 사용할 코드로 옮깁니다. 토큰 패키지와 React 컴포넌트, 토큰 변환 도구뿐 아니라 검증을 위한 Storybook과 사용 방법을 안내하는 공식 문서도 하나의 monorepo로 묶었습니다.
토큰이 바뀌면 이를 사용하는 컴포넌트와 검증 화면도 함께 확인해야 합니다. 디자인 원본과 구현은 책임에 따라 저장소를 나눴지만, 구현 안에서 함께 바뀌고 확인해야 하는 요소들은 같은 저장소에 두었습니다.
mbsw/
├── packages/
│ ├── tokens/ # 배포할 토큰 산출물
│ └── ui/ # 공개 React 컴포넌트
├── tools/
│ └── token-transform/ # 토큰 검증과 변환
└── apps/
├── storybook/ # 컴포넌트 예시와 검증 화면
└── docs/ # 공식 문서와 사용 가이드
기존 v1과의 호환성을 고려해 Tailwind CSS v4를 기반으로 구현하고, shadcn에서 활용 가능한 소스를 가져와 우리 디자인 토큰과 사용 규칙에 맞게 수정 및 확장했습니다. 상호작용과 접근성 구현에는 Radix를 활용하고, 대응하는 컴포넌트가 없는 경우에는 같은 조합과 확장 원칙에 따라 직접 구현했습니다.
클라이언트는 배포한 컴포넌트를 가져다 씁니다
검증한 구현은 @mbsw/tokens와 @mbsw/ui로 배포합니다. 클라이언트에서는 이 패키지의 공개 API와 스타일을 사용합니다.
버튼을 언제 보여주고 어떤 비즈니스 로직을 실행할지는 제품 코드에서 정합니다. 공통 버튼의 색상과 기본 동작은 디자인 시스템에서 관리합니다.
7/ 다음 사람이 같은 기준에서 시작할 수 있도록
첫 디자인 시스템은 흩어진 컴포넌트를 한곳에 모으는 데서 시작했습니다. 운영하면서는 새 기능을 수용하고 변경 사항을 맞추는 기준까지 필요하다는 것을 알게 됐습니다.
MBSW는 디자인 원본을 관리하는 것부터 패키지 배포와 클라이언트 사용까지 연결했습니다. 사람의 기억과 대화에 있던 기준을 파일과 코드, 검증 자료로 남길 수 있게 됐습니다.
이제 우리 팀은 사람이든 AI든 같은 자료에서 시작하고, 차이가 생기면 같은 근거로 확인할 수 있습니다.
앞으로도 MBSW를 지속적으로 개선할 예정입니다. 작업자와 도구가 바뀌어도 합의한 기준이 이어지고, 사람은 그 위에서 제품에 필요한 판단에 집중할 수 있었으면 합니다.
문방사우를 직접 사용해 보세요
문방사우는 React 컴포넌트와 디자인 토큰, light/dark 테마를 npm 패키지로 공개하고 있습니다. 설치 방법과 컴포넌트별 사용 예시는 아래 문서에서 확인할 수 있습니다.
사람과 AI가 함께 만드는 제품에서 일관된 UI를 위해 고민하고 있는 팀에게 문방사우가 도움이 되길 바랍니다.
김채원