AI 네이티브 팀에 디자인 시스템이 필요한 이유

리블은 대표 한 명과 역할을 나눈 AI 에이전트들이 함께 만들어요. 화면을 그리는 손이 여럿인 팀에서 디자인 시스템이 어떤 일을 하는지 적었어요.

혼자여도 계약이 없으면 화면이 갈라졌어요

메인 저장소 전체 커밋의 약 84.7%(2,119/2,502)에 에이전트 공동 작성 표기가 있어요. 코드의 몇 %를 AI가 썼다는 뜻은 아니에요. 그래서 리블의 디자인 시스템은 사람 사이의 약속이라기보다, 어제의 나와 오늘의 에이전트, 다음 주의 나 사이의 약속이에요.

문제는 이 약속을 확인해 줄 사람이 없다는 점이에요. 에이전트는 시킨 화면을 잘 만들지만, 기준이 코드에 없으면 화면마다 그럴듯한 값을 새로 적어요. “토큰 하나 고치면 정말 다 바뀌나요?”라는 질문을 받고 처음 재 봤어요.

그날 오후 화면을 훑어보니 칸 사이 간격이 18종, 좌우 여백이 14종이었어요. 그래서 간격 규칙 파일(lib/ds.ts)을 만들고 머리에 “유일한 기준(SSOT)”이라고 적었어요. 그런데 한 시간 반 뒤 세어 보니, 그 규칙을 가져다 쓰는 파일은 디자인 페이지 하나뿐이었어요. 제품의 나머지 자리는 모두 여전히 값을 직접 적고 있었어요.

디자인 시스템 전체가 0%였던 건 아니에요. 간격 규범만 제품에서 참조되지 않았어요. 그때 lib/ds.ts는 규범 문서였지, 값을 바꾸면 제품 전체가 바뀌는 단일 원천은 아니었어요. 디자인 페이지에는 제품 화면을 손으로 베낀 카드도 다섯 개 있었어요.

“베낀 화면은 제품이 바뀌어도 바뀌지 않아요. 그래서 디자인 시스템 페이지가 가장 먼저 틀려요.”

토큰·부품·규칙을 코드로 두고 네 장치로 지켰어요

고른 기준은 하나, 사람이 기억해서 맞춰야 하는 곳을 없애는 것이었어요. 버린 안부터 적을게요.

네 가지를 서로 다른 역할로 나눴어요. 한 장치가 “재는 것”인지, “막는 것”인지, “한 번 만든 것”인지 섞이지 않게요.

린트의 앞쪽 번호(①~⑲)가 막는 건 이런 것들이에요. 이름 뒤에 조사를 손으로 붙이는 패턴(9월 8일에는 “래미안를”이 배포 전에 걸렸어요), 페이지 배경색을 선으로 쓰는 패턴, 그리드 자식의 최소 폭 누락, 붙는 바의 위치를 숫자로 적는 패턴 등이에요. 모두 실제로 화면이 깨졌던 기록에서 나왔어요.

베낀 카드는 모두 지웠어요. 이제 디자인 페이지는 제품이 쓰는 부품을 그대로 가져와 그리고, 이때 흩어져 있던 버튼 6형태도 한 파일로 모였어요. 간격은 적어 둔 값이 아니라 브라우저가 실제로 계산한 값(getComputedStyle)을 읽어 색으로 얹어요. 사본 때문에 생기는 마크업 불일치 위험은 줄었지만, 넣는 데이터나 화면 폭에 따라 달라지는 표시 상태는 따로 확인해야 해요.

제품 화면도 같은 방식으로 정리했어요. 11월 13일, 단지 상세에서 화면마다 손으로 조립한 카드 9곳을 공용 카드 부품 하나로 옮겼어요. 카드 안에 또 테두리 상자를 두르던 곳이 같은 면으로 정리됐고, 손으로 다시 만든 카드가 늘어나면 린트 뒤쪽 번호가 배포 빌드를 막아요.

9월 17일에는 코드에서 토큰과 컴포넌트 정의를 뽑아 Figma 파일도 만들었어요(라이트·다크, PC·모바일을 모드로). 다만 한 번 뽑은 결과라 이후 코드 변경을 자동으로 따라가지 않아요. 그래서 리블에서 Figma는 원본이 아니라, 제품과 맞는지 따로 확인해야 하는 참고 자료예요.

글 쓰는 규칙도 같은 방식으로 다뤄요. 리블 Open 문서의 간격 리듬과 글자색 세 단계(제목·본문·메타)는 디자인 시스템 문서에 표로 있고, 문장 검사가 문단 길이·글자색 섞임·형광펜을 빌드 전에 확인해요.

에이전트가 같은 원본을 읽게 했어요

기준이 코드에 있어도 에이전트가 읽지 않으면 소용이 없어요. 그래서 원본 하나를 세 갈래로 열었어요.

• 저장소의 규칙 파일: Claude Code는 시작할 때 CLAUDE.md를 통해 조직 규칙 묶음(디자인 시스템 규칙 포함)을 자동으로 불러오고, 프런트 화면을 만들 때는 리블 디자인 시스템 스킬이 정본 부품과 토큰을 먼저 안내해요. Codex 같은 다른 에이전트는 AGENTS.md로 같은 파일을 읽게 해 뒀어요. 설정이 그렇다는 뜻이고, 매번 끝까지 읽었는지를 기록으로 확인하지는 않아요.
• 생성되는 문서: 디자인 시스템 문서의 props 표·토큰 값·예시 코드는 소스에서 자동으로 뽑고, 스펙 표는 실제 미리보기의 계산값과 다르면 검사가 실패해요.
• 디자인 시스템 MCP: Claude·Cursor 같은 AI 도구가 같은 토큰과 컴포넌트, 레이아웃 규칙을 직접 조회할 수 있어요(get_component · get_tokens 등).

사람에게 보여 주는 문서와 에이전트가 읽는 자료가 같은 원본에서 나오니, 한쪽만 낡는 일이 줄었어요. 다만 문서가 있다는 것과 에이전트가 실제로 규칙을 지킨다는 건 따로 확인해야 해요.

그래서 문서와 별개로, 이 계약이 얼마나 지켜지고 있는지를 숫자로 재요.

같은 기준으로 비교할 수 있는 건 글자 크기뿐이에요

글자 크기는 같은 분류 기준에서 잰 실제 이전이에요. 7월 26일 저녁, 크기를 직접 적은 약 1,500곳을 역할 클래스로 옮겨서 역할 클래스 사용 비율이 28.1%에서 100%가 됐어요. 이 과정에서 하나를 더 확인했어요. 역할 클래스는 폰 폭에서 한 단계 커지는데, 직접 적은 px 값은 그대로였어요. 그렇게 모바일 분기 규칙을 받지 못하던 하드코딩 선언 919곳을 찾았어요.

간격은 사정이 달라요. 같은 날 재는 방법을 “간격 역할 이름(GAP.*)을 참조하나”에서 “정해진 숫자 스케일 안에 있나”로 바꿨어요. 지금 정해진 스케일 안의 선언은 4,071/4,085(99.7%)예요. 각 자리에 의미가 맞는 간격을 골랐는지는 측정하지 않았어요. 첫날의 0곳과는 다른 질문을 잰 값이라, 0%에서 99.7%로 올랐다고 말하지 않아요.

부품 목록은 기능을 만들수록 다시 낡았어요

8월과 9월에 화면을 늘리는 동안 목록에 오른 비율이 73.4%까지 내려갔어요. 디자인 페이지에 경고는 떠 있었지만, 기능을 만드느라 보러 가지 않았어요. 측정은 경고를 만들었지만, 행동까지 만들지는 못했어요.

9월 8일에 빠진 부품을 한 번에 채웠어요(커밋 기록 75개). 세는 범위를 줄이면 숫자는 금방 100%가 되지만, 그러지 않고 화면에 못 띄우는 부품까지 이유를 적어 목록에 올렸어요. 그래도 11월 11일에 다시 세니 7개가 빠져 있었어요. 이 숫자는 저절로 유지되지 않는다는 걸 인정해야 했어요.

찾은 문제는 고치고, 다시 못 들어오게 했어요

부품을 한곳에 모은 효과가 화면에 드러난 곳도 있어요. 9월 2일 빌라·청약·공공임대 상세를 아파트 상세와 같은 부품으로 맞췄어요. 빌라 정보 탭은 지도 하나뿐이던 화면에서 시세·브리핑·교통·공원·학군과 지도까지 늘었고, 자료가 없는 칸은 빈칸으로 두지 않고 그리지 않아요. 다만 모바일 글자 크기가 바뀐 전후 화면은 캡처로 남겨 두지 못했어요.

한동안 고치지 않고 넘어간 것도 있었어요. 9월 17일 Figma를 만들며 잰 대비에서, 라이트 테마 앱 바탕(#f7f8fa) 위의 상태 글자색 warn은 2.03:1, pos는 2.40:1이었어요. 11px 배지 4종(상승·하락·브랜드·왕관 배지, 옅은 바탕)은 3.2~3.3:1이었고요. 작은 본문 글자에 요구되는 4.5:1(WCAG AA)에 못 미치는 조합이에요. 같은 색의 진한 변형(-strong)은 4.88·5.01:1로 통과하고, 다크 테마는 모두 통과했어요. 두 달 가까이 그대로 두었다가, 11월 12일 이 글을 다듬다 다시 걸려서 그날 고쳤어요. 경고·정상 글자는 진한 변형(-strong)을 쓰게 바꾸고, 옅은 바탕 위 배지 글자에는 글자 전용 진한 색(-ink)을 새로 뒀어요(옅은 바탕 기준 브랜드 4.83 · 상승 4.59 · 왕관 4.96:1). 채움·선·아이콘 색과 다크 테마는 그대로예요. 그리고 같은 조합이 다시 들어오면 배포 빌드가 멈추도록 패턴 검사(⑰)에 넣었어요. 발견에서 끝나지 않고, 고친 뒤 같은 실수가 다시 들어오지 못하게 막은 첫 사례예요.

11월 13일, 시트·대화상자와 접근성 빈틈

화면마다 따로 있던 시트와 대화상자는 11월 13일 공용 부품 두 개로 옮겼어요. 포커스 가두기·뒤로 가기로 닫기·바깥을 눌러 닫기를 부품이 맡아서, 에이전트가 화면마다 다시 구현하지 않아요. 같은 날 대표 페이지 11곳을 브라우저로 자동으로 열어 재는 접근성 검사를 만들고, 걸린 곳을 고쳤어요. 자세한 과정은 손으로 만든 창 열 개, 접근성은 어디서 맞출까?에 따로 적었어요.

다음에 잴 것

수치는 규칙에서 벗어난 곳을 찾아 줬지만, 그것만으로 누락이 해결되지는 않았어요. 이제 할 일은 누락이 생긴 그 시점에 작업 흐름 안에서 발견하게 하는 것이에요. 아직 만들지 않은 계획이고, 아래 세 가지로 잴게요.

1. 부품 목록 누락이 생긴 커밋부터 발견될 때까지 걸린 시간 - 지금은 디자인 페이지를 열어야만 보임
2. 대비를 고친 라이트 화면의 배지·경고 글자 실기기 재측정, 동적으로 만든 클래스처럼 검사가 못 잡는 남은 조합 찾기
3. 목록을 다 채운 뒤 다시 누락이 생기는 횟수
4. 에이전트가 디자인 시스템 MCP로 부품·토큰을 조회해 만든 작업의 호출 기록과, 그 결과가 린트를 통과했는지

숫자 출처