📚 지식 노트

왜 디자인 시스템인가

제품이 커지면 같은 결정을 여러 사람이 여러 번 한다. 버튼 모서리를 몇 픽셀로 둘지, 오류 문구를 무슨 색으로 쓸지, 대화상자의 확인 버튼을 왼쪽에 둘지 오른쪽에 둘지. 팀마다 따로 정하면 화면은 조금씩 어긋나고, 사용자는 같은 동작을 화면마다 다시 배워야 한다. 고칠 때도 같은 것을 여러 곳에서 찾아 고쳐야 하고, 하나를 빠뜨리면 어긋남은 더 커진다.

디자인 시스템(design system)은 이런 결정을 한 번 내려 모아 두고, 디자인 파일과 코드가 같은 것을 가져다 쓰게 하는 장치다. 목표는 예쁜 화면 하나가 아니라 일관성(같은 것은 같게), 속도(이미 정한 것은 다시 정하지 않음), 품질의 바닥(접근성·상태 처리가 기본으로 들어감)이다. 이 사이트도 같은 이유로 버튼·안내 문구 스타일을 공용 시트 한 곳에 모았다. 페이지마다 복제한 스타일이 버튼 여백을 조금씩 어긋나게 만든 일이 있었기 때문이다.

무엇으로 이루어지나: 원칙, 토큰, 컴포넌트, 패턴, 문서

디자인 시스템을 컴포넌트 라이브러리와 같은 말로 쓰는 경우가 많지만, 라이브러리는 한 층일 뿐이다. 보통 다음 다섯 가지를 함께 갖춘다.

• 원칙: "분명하게", "빠르게"처럼 둘 중 하나를 골라야 할 때의 기준이다. 문서에 없는 상황에서 판단을 맞춘다.
• 토큰: 색·간격·글꼴·모서리·그림자·움직임 같은 값에 붙인 이름이다. 디자인 파일과 코드가 같은 이름을 쓴다.
• 컴포넌트: 버튼·입력·대화상자처럼 반복되는 부품이다. 디자인 도구의 컴포넌트와 코드 컴포넌트가 짝을 이룬다.
• 패턴: 로그인, 빈 화면, 오류 처리처럼 컴포넌트를 엮어 한 가지 문제를 푸는 방식이다. 부품보다 크고 페이지보다 작다.
• 문서: 언제 쓰고 언제 쓰지 않는지, 접근성 메모, 코드 예시다. 문서가 없으면 부품은 있어도 쓰는 법이 사람마다 갈린다.

디자인 토큰 세 단계: 원시, 의미, 컴포넌트

디자인 토큰(design token)은 값에 이름을 붙인 것이다. #4263eb를 코드 곳곳에 적는 대신 이름을 쓰면, 값을 바꿀 때 이름이 가리키는 곳 하나만 고치면 된다. 핵심은 이름을 층으로 나누는 것이다.

• 원시 토큰(primitive): color.blue.500처럼 값 자체에 붙인 이름. 팔레트다. 어디에 쓰는지는 말하지 않는다.
• 의미 토큰(semantic): color.action.primary처럼 역할에 붙인 이름. 원시 토큰을 가리킨다. 화면을 만드는 사람이 주로 고르는 층이다.
• 컴포넌트 토큰(component): button.primary.fill처럼 부품의 한 자리에 붙인 이름. 의미 토큰을 가리킨다. 그 부품만 따로 바꿀 여지를 준다.

이렇게 이어 두면 바꿀 일이 생겼을 때 고칠 층이 정해진다. 브랜드 색을 바꾸면 원시 토큰, 다크 테마는 의미 토큰이 무엇을 가리키는지, 버튼만의 예외는 컴포넌트 토큰을 고친다. 아래 예에서 같은 파랑을 쓰는 자리 3곳에 값을 직접 적었다면 3곳을 고쳐야 하지만, 토큰을 거치면 원시 토큰 1줄만 고친다.

토큰을 파일로 주고받는 형식은 W3C 디자인 토큰 커뮤니티 그룹(DTCG)이 Design Tokens Format Module로 정리하고 있다. $value가 있는 객체가 토큰이고, $type은 생략하면 가장 가까운 부모 그룹의 것을 물려받으며, 다른 토큰은 중괄호 이름으로 가리킨다. 별칭이 별칭을 가리키는 사슬은 되지만 돌고 도는 참조는 오류다. W3C 표준이 아니라 커뮤니티 그룹 보고서라는 점은 알고 쓴다.

{
  "color": {
    "$type": "color",
    "blue": { "500": { "$value": "#4263eb" } },
    "action": {
      "primary": { "$value": "{color.blue.500}", "$description": "주 행동(저장, 보내기)" }
    }
  },
  "button": {
    "primary": { "fill": { "$type": "color", "$value": "{color.action.primary}" } }
  }
}

테마와 다크 모드를 토큰으로

다크 모드는 색을 뒤집는 일이 아니라 의미 토큰이 가리키는 값을 테마마다 다시 고르는 일이다. 컴포넌트는 --accent 같은 이름만 쓰고, 테마는 그 이름에 다른 값을 넣는다. 이 사이트가 그렇게 한다. 레이아웃이 :root에 --bg·--text·--accent 같은 CSS 변수를 다크 값으로 두고, 라이트 테마를 고르거나 운영체제가 라이트일 때 같은 이름에 라이트 값을 넣는다. 페이지 스타일은 색을 직접 적지 않고 이 변수만 쓴다. 웹 쪽 원리는 웹 개발 노트에 있다.

값을 다시 고를 때는 대비를 다시 잰다. 같은 강조색이라도 배경이 바뀌면 읽히는 정도가 달라진다. 이 사이트의 라이트 강조색 #4263eb를 다크 배경에 그대로 쓰면 대비가 3.79:1로 본문 글자 기준 4.5:1에 못 미친다. 그래서 다크 테마는 더 밝은 #6c8cff를 가리킨다. 기준은 WCAG 1.4.3이고(큰 글자는 3:1), 기준값은 반올림하지 않아 4.499:1은 미달이다. 대비를 고르는 법은 시각 디자인 글에 있다.

변수만으로 다루기 번거로운 한두 색은 CSS light-dark()로 적는다. 두 값을 받아 지금 색 구성이 라이트면 앞의 것, 다크면 뒤의 것을 쓴다. color-scheme이 light dark여야 동작하고, 2024년 5월부터 주요 브라우저가 모두 지원한다(Baseline 2024). 이 사이트 규칙도 "색은 변수로, 변수로 안 되는 테마별 색은 light-dark()로"다.

/* 이 사이트의 방식: 의미 토큰 이름은 하나, 테마마다 값만 바꾼다 */
:root { color-scheme: dark; --text: #e8eaf0; --accent: #6c8cff; }
:root[data-theme='light'] { color-scheme: light; --text: #1c2333; --accent: #4263eb; }

/* light-dark(): color-scheme이 light dark일 때 한 줄로 두 값을 적는다 */
:root { color-scheme: light dark; }
.badge { background: light-dark(#eef1fd, #1e2440); }

/* 컴포넌트는 값이 아니라 이름만 쓴다 */
.button-primary { background: var(--accent); color: var(--bg); }

컴포넌트 API: 변형, 크기, 상태, 슬롯

컴포넌트는 그림이 아니라 약속이다. 무엇을 바꿀 수 있고 무엇은 못 바꾸는지가 API로 드러나야 한다. 버튼이라면 보통 네 가지 축을 둔다.

• 변형(variant): primary·secondary·ghost·danger처럼 강조 정도와 의미. 이름은 모양("파란 버튼")이 아니라 역할로 짓는다. 테마가 바뀌어도 이름이 틀리지 않는다.
• 크기(size): sm·md·lg. 크기마다 글자·여백·최소 터치 크기가 토큰으로 정해진다.
• 상태(state): 기본·호버·포커스·누름·비활성·로딩. 사용자가 고르는 값이 아니라 상호작용이 만드는 값이라, 코드에서는 대개 속성이 아니라 브라우저 상태(:hover, :focus-visible)와 disabled·loading 같은 몇 가지 불리언으로 표현한다. 상태별 설계는 인터랙션과 상태 글에 있다.
• 슬롯(slot): 레이블, 앞·뒤 아이콘처럼 내용을 끼워 넣는 자리. 아무 것이나 넣게 하면 일관성이 깨지고, 너무 막으면 팀이 복제해 버린다. 자리마다 넣을 수 있는 것을 정한다.

축을 늘리면 조합은 곱으로 늘어난다. 변형 4 × 크기 3 × 상태 6이면 72가지이고, 앞·뒤 아이콘을 켜고 끄는 불리언 둘을 더하면 288가지다. 디자인 도구에 이 표를 모두 그려 두면 관리가 어렵다. 그래서 아이콘처럼 조합과 상관없는 것은 슬롯으로 빼고, 축은 정말 다른 모습이 필요한 것만 남긴다.

<Button
  variant="primary"
  size="md"
  loading={saving}
  iconStart={<SaveIcon />}
>
  저장하기
</Button>

아토믹 디자인: 작은 것을 조합해 큰 것을

브래드 프로스트(Brad Frost)의 아토믹 디자인은 인터페이스를 화학에 빗대 다섯 단계로 나눈다. 더 쪼개면 기능을 잃는 원자(레이블·입력·버튼), 원자 몇 개가 한 단위로 일하는 분자(검색 폼), 분자와 원자로 된 화면의 한 구역인 유기체(머리글), 부품을 배치해 내용의 구조를 보여 주는 템플릿, 템플릿에 실제 내용을 채운 페이지다.

쓸모는 이름보다 방향에 있다. 페이지를 통째로 그리지 않고 부품에서 출발해 조립하면 같은 부품이 여러 화면에 다시 쓰인다. 템플릿과 페이지를 나눠 보는 것도 중요하다. 빈 자리로는 멀쩡하던 카드가 긴 상품명이나 빈 이미지 같은 실제 내용에서 깨지는 일이 많기 때문이다. 다만 "이것이 분자인가 유기체인가"를 두고 오래 논쟁할 필요는 없다. 많은 팀이 단계 이름 대신 "기본 부품", "조합 부품", "패턴" 정도로 단순하게 나눈다.

피그마 컴포넌트·변수와 코드 동기화

디자인 시스템이 흔히 무너지는 곳이 디자인 파일과 코드의 틈이다. 피그마의 버튼과 코드의 버튼이 따로 고쳐지면 둘은 곧 다른 것이 된다. 그래서 원본을 한 곳에 두고 나머지는 거기서 만든다. 토큰이라면 그 한 곳은 대개 저장소의 토큰 파일이다.

피그마에서는 변수(variables)가 토큰 역할을 한다. 색·숫자 같은 값을 변수로 만들어 컬렉션으로 묶고, 한 변수에 라이트·다크 같은 모드별 값을 둔다. 변수가 다른 변수를 가리킬 수 있어 의미 토큰도 만든다. 팀 라이브러리로 변수를 공유하는 것은 유료·교육용 요금제의 기능이다. 이 변수를 플러그인이나 스크립트로 토큰 파일로 내보내고, Style Dictionary 같은 변환 도구가 같은 파일에서 CSS·자바스크립트·iOS·안드로이드 형식을 만든다.

컴포넌트는 토큰처럼 자동으로 옮기기 어렵다. 대신 이름과 속성을 맞춘다. 피그마 컴포넌트의 속성 이름(variant, size)과 값(primary, md)을 코드 API와 똑같이 지으면, 디자이너가 고른 조합을 개발자가 그대로 코드로 옮긴다. "피그마에 있는데 코드에 없는" 변형이 생기지 않게 둘을 같은 리뷰에서 함께 바꾼다.

문서와 사용 지침: Do와 Don't

부품만 있고 쓰는 법이 없으면 사람마다 다르게 쓴다. 컴포넌트 문서 한 장에는 보통 다음이 들어간다. 언제 쓰고 언제 다른 것을 쓰는지, 해부도(각 부분의 이름), 변형과 상태의 모습, 문구 지침(버튼은 동사로, 짧게), 접근성 메모(키보드 동작, 스크린 리더가 읽는 이름, 대비), 살아 있는 코드 예시다. 문구 지침은 UX 라이팅·평가·실험 글, 접근성은 반응형·모바일·접근성 글에 있다.

가장 잘 전달되는 형식이 Do/Don't 그림이다. 같은 장면을 옳은 쓰임과 틀린 쓰임으로 나란히 두고, 왜 틀렸는지 한 줄로 적는다. 규칙을 문장으로만 쓰면 "주 버튼은 한 화면에 하나"를 읽고도 막상 화면을 만들 때 놓친다. 틀린 예를 눈으로 보면 기억에 남는다.

버전 관리와 기여 모델

디자인 시스템은 여러 앱이 가져다 쓰는 라이브러리라, 바꿀 때마다 쓰는 쪽이 깨질지 알 수 있어야 한다. 흔히 유의적 버전(semantic versioning)을 쓴다. 호환되는 버그 수정은 PATCH, 호환되는 기능 추가는 MINOR, 호환이 깨지는 변경은 MAJOR를 올리고, 큰 자리를 올리면 아래 자리는 0으로 돌린다. 무언가를 폐기 예정(deprecated)으로 표시하는 것도 MINOR다. 바로 지우지 않고 경고로 알린 뒤 다음 MAJOR에서 지우면, 쓰는 팀이 옮겨 갈 시간을 번다. 토큰 이름을 바꾸거나 지우는 것도 호환이 깨지는 변경이다. 버전과 변경 기록의 일반론은 버전 관리 노트에 있다.

누가 만드느냐도 정해야 한다. 작은 시스템 팀이 모든 컴포넌트를 만들면 품질은 고르지만 속도가 따라가지 못하고, 쓰는 팀이 모두 만들게 두면 금세 중복과 어긋남이 생긴다. 그래서 많은 시스템이 쓰는 팀이 제안하고 함께 만들되, 시스템 팀이 기준을 지키는 기여 모델을 둔다. GOV.UK 디자인 시스템은 그 기준을 공개해 두었다. 제안 단계에서는 여러 팀에 쓸모 있다는 근거(유용)와 이미 있는 것과 겹치지 않음(고유)을 보고, 출시 전에는 장애인을 포함한 사용자 조사(사용성), 기존 스타일·컴포넌트 재사용(일관성), 여러 서비스·브라우저·보조 기술에서의 시험(다양성)을 본다.

널리 알려진 디자인 시스템

큰 회사들이 자사 디자인 시스템을 공개해 두어, 처음 만들 때 참고하거나 그대로 가져다 쓸 수 있다. 같은 생각을 다른 이름으로 부르는 경우가 많다. 토큰의 층만 봐도 Material Web 문서는 참조(--md-ref-*, 실제 값)·시스템(--md-sys-*, 역할)·컴포넌트 토큰으로 나누고 컴포넌트 토큰에는 comp 접두사를 붙이지 않으며, Fluent 2는 원시 값을 담는 전역(global) 토큰과 의미를 붙이는 별칭(alias) 토큰을 설명한다.

가져다 쓰는 길은 몇 단계가 있다. 그대로 쓰기, 토큰만 덮어써 테마를 입히기, 코드를 갈라 와 고쳐 쓰기, 직접 만들기다. 오른쪽으로 갈수록 자기 제품에 맞지만 비용이 든다. 특히 갈라 쓰기는 원본의 개선을 따라가기 어려워진다. 처음에는 공개 시스템에 테마를 입혀 쓰고, 자주 덮어쓰는 곳이 쌓이면 그 부분부터 자기 것으로 만드는 순서가 무난하다.

흔한 실패

• 쓰는 사람 없이 만든다: 시스템 팀이 이상적인 부품을 먼저 다 만들고 배포하면, 실제 화면에 필요한 변형이 빠져 있다. 지금 제품에서 가장 많이 반복되는 부품부터 실제 화면과 함께 만든다.
• 모양으로 이름 짓는다: blue-button, color.gray-light처럼 지으면 테마나 브랜드가 바뀔 때 이름이 거짓말이 된다. 의미 토큰과 변형은 역할로 짓는다.
• 토큰이 너무 많다: 모든 값에 컴포넌트 토큰을 만들면 이름이 수천 개가 되어 아무도 고르지 못한다. 컴포넌트 토큰은 정말 따로 바꿀 일이 있는 자리에만 둔다.
• 디자인과 코드가 따로 논다: 피그마와 코드가 각자 고쳐지면 둘 중 하나는 거짓이 된다. 원본을 하나로 정하고 같은 리뷰에서 바꾼다.
• 문을 닫는다: 기여 길이 없고 요청이 몇 달씩 밀리면 팀은 복제해 고쳐 쓴다. 그 사본이 쌓이면 시스템은 이름만 남는다. 아래 고리가 그 모습이다.

흔한 오해

• "디자인 시스템 = UI 키트": 부품 모음은 한 층일 뿐이다. 원칙·토큰·패턴·문서·운영 방식이 함께 있어야 사람들이 같은 결정을 내린다.
• "한 번 만들면 끝": 제품처럼 버전을 내고, 쓰는 팀의 요청을 받고, 폐기와 이전을 안내해야 한다. 운영이 멈추면 사본이 늘어난다.
• "다크 모드는 색을 뒤집으면 된다": 같은 강조색도 배경이 바뀌면 대비가 달라진다. 위 예에서 라이트 강조색을 다크 배경에 그대로 쓰면 3.79:1로 미달이었다. 의미 토큰마다 테마별 값을 골라 다시 잰다.
• "유명한 시스템을 가져오면 우리 시스템이 생긴다": 가져온 것은 남의 결정이다. 우리 제품의 원칙과 패턴, 문서는 여전히 직접 써야 한다.
• "디자인 시스템은 창의성을 죽인다": 매번 다시 정하던 버튼 여백 같은 결정을 덜어 주어, 정말 새로 풀어야 하는 문제에 시간을 쓰게 한다. 새 패턴이 필요하면 기여 길로 시스템에 더한다.
• "아토믹 디자인의 다섯 단계를 꼭 지켜야 한다": 다섯 단계는 생각하는 틀이다. 폴더 이름까지 그대로 따를 필요는 없다.

핵심 자료

화면 원리는 HCI와 UX 노트, 테마를 구현하는 웹 쪽 기술은 웹 개발 노트에 있다.