디자인 시스템에서 문서는 코드 뒤에 덧붙이는 부록이 아니라 코드 그 자체입니다. 토큰과 컴포넌트에 어떻게 이름을 붙이고 주석을 달고 사용 예를 나란히 두는지, 코드가 곧 살아 있는 문서가 되는 방법을 하나씩 코드로 보여 드리겠습니다.
41.1 토큰 이름을 규칙으로 짓기
토큰 이름은 기분 따라 짓는 게 아니라 한 벌의 규칙을 정해 그 틀에 맞춰 지어야 합니다. 저는 분류, 역할, 단계를 이어 붙이는 방식을 씁니다.
:root {
/* --{category}-{role}-{scale} */
--color-text-strong: #111827;
--color-text-weak: #6b7280;
--color-brand-500: #2563eb;
--color-brand-600: #1d4ed8;
--space-inline-md: 16px;
--radius-control-md: 6px;
--font-size-md: 14px;
}
이름만 봐도 무엇에 쓰는 값인지 읽힙니다. color-text-strong은 색 분류의 본문 강조용이고, space-inline-md는 가로 방향 중간 간격이지요. 규칙이 이름에 스며 있으면 새 토큰을 지을 때도 헤매지 않습니다.
41.2 나쁜 이름과 좋은 이름
같은 값이라도 이름을 어떻게 붙이느냐로 문서의 수명이 갈립니다. 먼저 흔히 저지르는 나쁜 이름부터 봅니다.
:root {
--blue: #2563eb;
--blue2: #1d4ed8;
--gray: #6b7280;
--m8: 8px;
--big: 20px;
}
blue2는 blue와 무슨 사이인지 알 수 없고, 브랜드 색이 초록으로 바뀌면 --blue라는 이름이 거짓말이 됩니다. --big은 무엇보다 큰지 말해 주지 않아 다음 크기를 넣을 자리가 없지요. 역할과 단계로 다시 지으면 이렇게 됩니다.
:root {
--color-brand-500: #2563eb;
--color-brand-600: #1d4ed8;
--color-text-weak: #6b7280;
--space-inline-sm: 8px;
--font-size-lg: 20px;
}
이제 색이 바뀌어도 이름은 그대로 살아남고, 500과 600 사이에 550을 끼워 넣을 수도 있습니다. 이름 자체가 이 값의 쓰임을 설명하는 짧은 문장이 된 셈입니다.
41.3 컴포넌트 옆에 사용 예 붙이기
토큰을 참조하는 컴포넌트 CSS는 반드시 그것을 실제로 쓰는 마크업과 짝지어 문서에 둡니다. 코드를 보는 사람이 곧바로 복사해 갈 수 있게요.
.btn {
padding: var(--space-inline-sm) var(--space-inline-md);
border-radius: var(--radius-control-md);
font-size: var(--font-size-md);
cursor: pointer;
}
.btn--primary {
background: var(--color-brand-500);
color: var(--color-on-brand);
}
바로 옆에 이 클래스를 어떻게 붙이는지 마크업 예를 함께 둡니다.
<button class="btn btn--primary">저장</button>
<button class="btn btn--secondary">취소</button>
스타일과 마크업이 한자리에 있으면, 읽는 이는 무엇을 보고 무엇을 붙여 넣어야 하는지 고민하지 않습니다. 눈으로 고른 모습을 그대로 집어다 제 화면에 붙이면 되니까요.
41.4 주석으로 토큰의 뜻 남기기
토큰 값 옆에 붙인 주석은 그 자리에서 바로 읽히는 문서입니다. 언제 써야 하고 언제 쓰지 말아야 하는지를 값 바로 곁에 적어 둡니다.
:root {
/* 본문 기본 글자색. 배경 대비 7:1 이상 보장 */
--color-text-strong: #111827;
/* 보조 설명과 캡션 전용. 강조에는 쓰지 말 것 */
--color-text-weak: #6b7280;
/* 컴포넌트 사이 기본 세로 간격 */
--space-stack-md: 16px;
}
이 주석은 코드에서 멀리 떨어진 별도 문서가 아니라 값에 딱 붙어 있어서, 값을 고치는 사람이 설명을 놓치기 어렵습니다. 문서가 코드 곁에 살면 하나를 고칠 때 다른 하나가 자연히 눈에 들어옵니다.
41.5 @property로 토큰 타입 밝히기
커스텀 프로퍼티에 @property를 얹으면 그 토큰이 색인지 길이인지를 코드 스스로 선언하게 됩니다. 주석보다 한 걸음 더 나아간 문서지요.
@property --color-brand-500 {
syntax: "<color>";
inherits: true;
initial-value: #2563eb;
}
@property --space-inline-md {
syntax: "<length>";
inherits: false;
initial-value: 16px;
}
syntax가 이 토큰의 타입을 못박아 두니, 실수로 색 토큰에 16px 같은 값을 넣으면 브라우저가 그 값을 무시하고 기본값으로 되돌립니다. initial-value 덕에 어디서든 최소한의 안전한 값이 보장되고, 선언 자체가 이 토큰은 색이라는 문서 역할을 합니다.
41.6 좋은 쓰임과 나쁜 쓰임 대조
토큰을 만들어 두고도 컴포넌트가 날값을 직접 쓰면 문서는 금세 거짓이 됩니다. 흔한 나쁜 쓰임을 먼저 봅니다.
.card-title {
color: #111827; /* 토큰을 두고 날값을 씀 */
margin-bottom: 15px; /* 간격 스케일 밖의 값 */
}
이러면 강조색을 한 번에 바꿀 수도 없고, 15px는 어느 단계에도 속하지 않아 다음 사람이 따라 하기도 애매합니다. 정해 둔 토큰만 참조하도록 고칩니다.
.card-title {
color: var(--color-text-strong);
margin-bottom: var(--space-stack-md);
}
이제 이 컴포넌트는 시스템의 약속 안에서만 움직입니다. 토큰 한 곳을 고치면 이 제목을 쓰는 모든 화면이 함께 따라오고, 코드가 곧 규칙을 지키는 살아 있는 예제가 됩니다.
41.7 상태를 실물로 나열하기
버튼의 여러 상태를 글로만 적으면 읽는 이가 머릿속으로 그려야 합니다. 문서에는 각 상태를 실제 스타일로 죽 늘어놓아 눈으로 바로 보게 합니다.
.btn--primary:hover {
background: var(--color-brand-600);
}
.btn--primary:focus-visible {
outline: 2px solid var(--color-brand-600);
outline-offset: 2px;
}
.btn--primary:disabled {
background: var(--color-brand-200);
cursor: not-allowed;
}
기본, 가리킴, 초점, 비활성이 저마다 어떤 토큰을 쓰는지 한자리에 드러납니다. 상태마다 실제 모습을 보여 주는 문서가 오해를 가장 적게 남깁니다.
41.8 코드가 곧 문서다
규칙을 담은 이름, 값 곁의 주석, @property가 밝힌 타입, 마크업까지 붙은 사용 예. 이것들이 모이면 문서는 코드 밖에 따로 존재하지 않고 코드 안에 녹아듭니다. 이렇게 코드와 함께 사는 문서는 부품이 바뀌는 순간 함께 젊어져서, 낡은 설명이 사람을 속이는 일이 사라집니다.