디자인 시스템 문서는 대부분 같은 방식으로 죽습니다. 잘 만들어진 문서가 어딘가에 있고, 코드가 몇 번 바뀌고, 두 달쯤 지나면 문서와 화면이 서로 다른 말을 합니다. 그때부터 아무도 문서를 열지 않고, 열지 않으니 더 어긋납니다.
원인은 분량이 아니라 위치입니다. 코드와 다른 곳에 사는 문서는 코드와 함께 바뀌지 않습니다.
코드와 함께 사는 세 가지 형태
첫 번째가 가장 강력합니다. 토큰 이름이 역할을 정확히 말하고 있으면 그 자체가 문서입니다. --color-success-bg 는 설명이 필요 없습니다.
두 번째는 저장소 안의 문서 파일입니다. 핵심은 같은 커밋에서 함께 바뀐다는 점입니다. 토큰을 추가하면서 문서를 고치지 않으면 리뷰에서 드러납니다.
세 번째는 사이트 안에 두는 스타일 가이드 페이지입니다. 별도로 빌드하는 문서 사이트와 달리, 실제 사이트의 CSS 로 렌더되기 때문에 언제나 진짜입니다. 토큰이 바뀌면 그 페이지의 견본도 그 자리에서 바뀝니다. 색 견본 · 버튼 상태 · 간격 척도 · 타이포 계단이면 충분하고, 검색에는 노출하지 않습니다.
값이 아니라 이유를 적습니다
문서에 --space-4: 16px 이라고 적는 것은 낭비입니다. 그 값은 코드에 있고, 코드가 항상 더 정확합니다. 문서가 담당해야 하는 것은 코드가 적을 수 없는 것입니다.
특히 “하지 않기로 한 것” 을 적는 것이 값이 큽니다. 다음 사람이 반드시 다시 떠올릴 아이디어이기 때문입니다 — 왜 벤더 토큰을 직접 고치지 않는지, 왜 예외 간격을 허용하지 않는지, 왜 편집자의 색 선택기를 닫았는지. 이유가 적혀 있지 않으면 그 결정은 6개월 뒤에 조용히 되돌려집니다.
변경 절차를 짧게 못 박습니다
문서의 마지막 장은 규칙이 아니라 절차여야 합니다. 새 토큰이나 새 컴포넌트가 필요할 때 무엇을 하는지 네 줄이면 됩니다.
첫 칸이 가장 중요합니다. 대부분의 시스템은 필요해서가 아니라 이미 있는 것을 못 찾아서 부풉니다. 이름이 역할로 지어져 있고 문서가 코드 옆에 있으면, 찾는 데 드는 시간이 짧아지고 그만큼 중복이 줄어듭니다.
그리고 가능한 규약은 검색으로 검사할 수 있게 만들어 문서에 그 검색문까지 적어 둡니다. 사람이 지키는 규약은 사람이 바뀌면 사라지지만, 검사할 수 있는 규약은 남습니다.
연재를 마치며
여덟 회차 동안 이름을 붙이고(1~3), 테마와 편집 화면에 심고(4~6), 벤더 토큰과의 경계를 브릿지 한 파일로 좁히고(7), 그것을 넘길 문서를 세웠습니다(8). 워드프레스는 이 구조를 아주 잘 받아 줍니다 — 커스텀 프로퍼티도, theme.json 도, 자식 테마도 전부 코어가 제공하는 것들입니다. 문제가 되는 것은 도구가 아니라 구조 없이 쌓인 시간이고, 그것은 언제든 되돌릴 수 있습니다.
이어지는 실무 지식은 개발 워크플로우 아카이브에 쌓이고 있습니다. 이미 오래 운영된 사이트에 이 구조를 올리는 일 — 테마 정리 · 업그레이드 · 성능과 보안 점검 — 은 최적화 지원 사업에서 한 건으로 처리하며, 어떤 순서로 작업하는지는 작업 과정에 그대로 공개돼 있습니다.