디자인 시스템 빌더은(는) 무엇을 하나요?

이것은 일반적인 모범 사례 체크리스트가 아닙니다. 아래의 모든 규칙은 이를 건너뛰었을 때 실제로 출시된 버그가 발생했기 때문에 존재합니다. 대부분의 버그는 조용히 발생합니다(오류 없음, 빌드 실패 없음, 그저 브라우저에서 잘못 표시됨). references/bug-catalog.md에는 각 규칙 뒤에 있는 특정 인시던트가 기록되어 있습니다. 중요한 시스템을 시작하기 전에 한 번 읽어보세요.

핵심 원칙: 주석이나 문서에만 존재하는 규칙은 결국 실수로 위반될 것이며, 위반은 오류를 발생시키지 않습니다. 각 단계는 "이것이 자동으로 어떻게 적용되는가?"라는 질문으로 끝납니다. 만약 대답이 "누군가가 기억한다"라면, 그 단계는 완료된 것이 아닙니다.

두 가지 진입점:

새로 구축 → 1~7단계를 순서대로 진행합니다.
기존 시스템 감사 또는 개선 → 8단계로 이동하며, 필요에 따라 1~7단계를 참조합니다.

1단계 — 발견

구축하기 전에 질문하세요. 추측해서 만든 시스템은 아무도 원하지 않으며, 그 사실이 드러났을 때 수정하는 데 비용이 많이 듭니다.

참고 자료는 형용사가 아닌 구체적인 예시로 제시하세요. "모던하고 깔끔한"은 아무것도 명시하지 않습니다. 세 개의 스크린샷이 합니다.
색상이 의미를 전달하는지, 아니면 단순히 미적인지 결정하세요. 팔레트에 범주형 값(요소, 상태, 브랜드 라인)이 있는 경우, 각 값이 또한 동작(모션, 모양, 두께)인지 아니면 순전히 시각적인지 먼저 결정하세요. 외관 때문에 선택한 색상에 의미를 나중에 덧붙이는 것보다 처음에 결정하는 것이 훨씬 쉽습니다.
콘텐츠는 무엇 위에 놓이나요? 페이지 배경과 패널 배경이 "비슷하다"고 가정하지 마세요. 커밋하기 전에 가능한 조합을 측정하세요 — 2.3단계를 참조하세요.
범위: 새로 구축, 기존 시스템 개선, 또는 이전/형제 시스템과 비교. 완전히 새로운 구축이 아니라면 8단계로 이동합니다.
배포: 하나의 프로젝트인가요, 아니면 여러 프로젝트에서 재사용되나요? 이 단일 답변이 6단계(패키징) 적용 여부를 결정합니다. 잘못 판단하면 일회성 시스템을 과도하게 설계하거나, 곧 세 개의 저장소로 퍼져나갈 시스템을 과소 설계하게 됩니다.

2단계 — 토큰 작성

우선 순위 순서: 이것들을 잘못 만들면 그 위에 구축된 모든 것이 잘못된 기반을 물려받습니다.

2.1 — 색상은 한 번, 원시 채널 트리플릿으로 작성되며 절대 순수한 16진수로 작성되지 않습니다.

--fire-rgb: 170 0 0;                          /* 유일하게 작성된 값 */
--fire: rgb(var(--fire-rgb));                 /* 파생됨 */
--fire-soft: rgb(var(--fire-rgb) / 0.18);     /* 파생됨 */

이것은 스타일적인 것이 아닙니다. Tailwind(및 대부분의 유틸리티 시스템)의 불투명도 수정자(bg-fire/40)는 불투명한 var(--x) 16진수 값에 알파 채널을 합성할 수 없습니다 — 클래스는 조용히 아무것도 해결하지 못하며, 오류나 경고가 없습니다. 이 특정 버그는 이 패턴이 나오게 된 강화 과정을 시작했습니다. 색상당 하나의 작성된 숫자는 변경해야 할 장소가 항상 하나뿐이라는 것을 의미합니다.

2.2 — 텍스트로 렌더링될 수 있는 모든 색상은 -text 변형을 가지며, 글리프는 기본 색상이 아닌 이것을 사용합니다. WCAG 상대 휘도(assets/check-tokens.template.mjs의 공식)를 계산하여 대비를 검증하고, 눈으로 확인하지 마세요. 한 표면에 대해 4.5:1을 통과하는 색조가 다른 표면에서는 실패할 수 있습니다 — 이것이 바로 2.3이 중요한 이유입니다.

2.3 — 표면 계층(페이지 / 패널 / 함몰)이 두 개 이상인 경우, 실제 고도 스케일로 정의하고 계층 간의 분리를 커밋 전에 측정하세요. "조금 더 밝은"은 결정이 아니라 추측입니다. 실제 시스템은 출시 후에 전체 고도 모델(잉크-페이지 → 보이드-페이지)을 뒤집었는데, 그 이유는 누군가가 실제 합성 대비를 계산했기 때문입니다: 한 방향으로 1.04:1, 다른 방향으로 1.19:1. 이해 관계자가 "카드가 평평해 보인다"고 말한 후에가 아니라, 선택 전에 그 계산을 하세요.

스케일이 생기면, 모든 텍스트 안전 토큰은 나타날 수 있는 모든 계층에 대해 대비를 확인해야 하며, 설계된 계층 하나만 확인해서는 안 됩니다.

2.4 — 모션: 하나의 이징 곡선, 소수의 고정된 지속 시간 집합. 어떤 JS 애니메이션(framer-motion, GSAP, 수동 requestAnimationFrame)이 이것들을 사용할 경우, CSS 변수와 함께 JS 상수로 곡선과 지속 시간을 내보내세요 — CSS 변수는 JavaScript에서 보이지 않으며, 수동으로 입력한 베지어 곡선이나 지속 시간은 즉시 그리고 눈에 띄지 않게 변경됩니다. CSS와 JS 버전이 서로 일치하는지 확인하세요(4단계).

2.5 — 그라데이션이나 글로우 효과에 대한 숫자 상한선은 실제 출시된 값에 대해 확인된 실제 숫자여야 합니다. 여기에는 단순한 단일 알파 색상뿐만 아니라 그라데이션 중지점도 포함됩니다. "미묘한 글로우"에 강제된 상한선이 없으면, 각 구성 요소가 개별적으로는 합리적으로 보이지만 전체 페이지 주변 글로우가 한 구성 요소씩 다시 나타나게 됩니다.

2.6 — 모든 토큰은 단 한 줄의 주석을 포함해야 하며, 언제 사용해야 하는지 설명해야 합니다. 단순히 어떻게 렌더링되는지가 아니라.

3단계 — 프리미티브 구축

구성 요소는 토큰만 참조합니다. 16진수, 임의의 값, white/10 스타일의 리터럴은 없습니다 — 이것들은 정확히 4단계의 가드가 확인하는 대상이므로 지금 작성하면 나중에 검사에 실패하게 됩니다.
불투명도 수정자 사용(bg-x/10)은 2.1에 따라 실제로 알파 합성 가능한 토큰을 대상으로 해야 합니다 — 확인 가능하므로 눈으로 확인하지 말고 확인하세요.
속성이 재정의할 수 있는 변형을 구성 요소의 기본 클래스에 하드코딩하지 마세요. 모든 카드에 className="shadow-lg"가 내장되어 있고, shadow-root-earth를 바꿔 넣을 수 있는 속성이 있는 경우, 동일한 특이성을 가진 두 개의 상자 그림자 유틸리티가 생성됩니다. 승자는 생성된 스타일시트의 소스 순서에 의해 조용히 결정됩니다. 변형을 속성(Record<Variant, string>)으로 키가 지정된 조회 테이블로 만들고, 기본 클래스와 예상 재정의를 사용하지 마세요.
스타일링 속성은 실제 대화형 요소를 대체하지 않습니다. interactive 속성을 통해 클릭 가능해 보이는(cursor-pointer, 호버 리프트) 카드가 <div>인 경우, 마우스 사용자에게는 편의성을 제공하지만 키보드 사용자는 전혀 얻지 못합니다 — 포커스 링, 역할, 활성화가 없습니다. 클릭하도록 의도된 것이라면 <a> 또는 <button>(CardLink/CardButton 쌍)을 렌더링하고, 수동 버전에 대한 스타일링 토글을 사용하지 마세요.
진정으로 복잡한 대화형 구성 요소(모달, 탭, 토스트)의 경우, 플랫폼에 의존하세요. 네이티브 <dialog>는 포커스 트랩과 Escape-닫기를 무료로 제공합니다. 수동 구현은 이 중 하나를 확실히 잘못 구현합니다. 탭을 위한 로빙 tabindex는 수동 탭 구현이 가장 흔히 잘못 구현하는 부분입니다(모든 비활성 탭이 Tab 중단점으로 남아 있음) — 명시적으로 확인하고(tabindex가 화살표 키 탐색 시 [0,-1,-1,-1] → [-1,0,-1,-1]로 이동하는지) 가정하지 마세요.
시스템에 사용자 정의 아이콘/마크 자산이 필요한 경우, 그리기 규칙(그리드, 선 두께, 캡 스타일)을 먼저 수정하고 색상 규칙과 동일한 방식으로 적용하세요 — 이것도 4단계의 작업입니다.

4단계 — 가드하기

작고, 가능하면 종속성이 없는 검사 스크립트를 작성하세요. 이것은 전체 프로세스에서 단일 가장 높은 레버리지 아티팩트입니다. references/bug-catalog.md의 모든 버그는 누군가가 여기에 인코딩할 때까지 산문에만 존재했던 규칙이었습니다.

최소 적용 범위(assets/check-tokens.template.mjs를 조정):

구성 요소 또는 프리셋이 참조하는 모든 토큰이 실제로 존재합니다.
구성 요소 소스에 수동으로 입력된 16진수 또는 리터럴 불투명도 색상이 없습니다.
나타날 수 있는 모든 표면 계층에 대한 모든 텍스트 안전 토큰의 WCAG 대비(2.3).
문서화된 숫자 상한선이 실제 출시된 값(단순한 색상뿐만 아니라 그라데이션의 가장 밝은 중지점 포함)에 대해 숫자로 적용됩니다(2.5).
JS 모션 상수가 해당 CSS 토큰과 일치합니다(2.4).
실수로 위반하기 쉬운 구조적 규칙 — 예: "전체 페이지 배경 글로우 없음": 글로우 유틸리티가 페이지 수준 요소에 적용되지 않는지 확인하고, 토큰의 알파만 제한되지 않도록 합니다.
일반 산문과 일치할 수 있는 규칙(예: "두 번째 이징 곡선"에 대한 규칙)을 클래스 속성, CSS 값과 같은 실제 코드 컨텍스트로 제한하고 임의의 텍스트로 제한하지 않습니다. 자신의 문서에 플래그를 지정하는 린터는 비활성화되어 목적을 상실합니다.

검사는 궁극적으로 시스템 자체 저장소뿐만 아니라 소비 프로젝트에 대해서도 실행되어야 합니다. 이것은 여기서 얻을 수 있는 가장 큰 교훈입니다: 실제 시스템에서 실제로 발생한 모든 규칙 위반(24px 미만의 11가지 유형 크기, 한 사이트에서 3개의 다른 <h2> 크기, 5개의 경쟁 문자 간격 값, 두 번째 이징 곡선, 발명된 지속 시간)은 시스템을 소비하는 프로젝트에서 발생했으며 내부 검사는 그곳을 전혀 보지 않았습니다. 오랫동안 규칙을 위반한 적이 없는 코드를 보호하고 있었습니다. 체커를 임의의 소스에 대해 실행 가능하도록 출시하고(npx your-check ./src), 스코프가 지정된 예외 처리 메커니즘(진정한 예외에 대한 your-check-allow: <rule> — <reason> 주석 규칙)을 제공하여 사람들이 전체 검사를 비활성화하지 않도록 하세요.

검사를 신뢰하기 전에 각 검사를 부정 테스트하세요. 스크래치 복사본에서 각 규칙을 의도적으로 위반하고 스크립트가 실제로 실패하는지 확인하세요. 실패하는 것을 관찰한 적이 없는 검사는 검증되지 않은 것입니다 — 작동하는지 아니면 조용히 비활성화되어 있는지 알 수 없습니다.

5단계 — 문서화

대상별로 구분된 세 개의 파일을 작성하고, 네 번째 파일을 추가하고 싶은 충동을 억제하세요. 네 번째 문서(집계된 "design.md", 두 번째 스타일 가이드 문서)는 동일한 값이 표류할 수 있는 두 번째 장소이며, 각각 고유한 질문(이유 / 해야 할 일 / 결정된 사항)을 소유하는 세 개의 파일로 충분합니다.

philosophy.md — 이유, 정체성, 선택 뒤에 숨은 의미. 한 번 읽고, 거의 다시 읽지 않습니다.
foundations.md — 운영 규칙. 누군가가 새로운 것을 구축하기 전에 확인하는 사항. 4단계의 가드가 적용하는 것과 대략 1:1로 매핑되어야 합니다. 규칙이 하나에는 있고 다른 하나에는 없다면, 어느 것이 누락되었는지 선택하고 수정하세요.
decisions.md — 특정 판단 호출과 그 이유에 대한 최신 항목이 가장 먼저 나오는 실행 로그입니다. 대체된 항목을 절대 삭제하지 마세요. 대체되었음을 표시하고 무엇이 변경되었는지와 그 이유를 설명하세요. 종이 추적 없이 실제 결정(고도 모델, 강조 계층 구조)을 되돌리면 다음 사람(종종 미래의 당신)이 처음부터 추론을 다시 유도하거나, 더 나쁘게는 원래 결정이 수정한 것을 조용히 다시 깨뜨리게 됩니다.
실제 토큰과 구성 요소를 렌더링하는 라이브 쇼케이스 — 설명이 아닙니다. 패키지를 import할 수 없다면(정적 단일 파일 HTML 문서 등), 모든 값의 두 번째 인라인 복사본을 가지고 있는 것이며, 그 복사본은 표류할 것입니다: 실제 시스템의 쇼케이스는 실제 패키지를 가져오는 것으로 재구축되기 전에 자체 토큰보다 두 버전 뒤쳐졌습니다. 정적 쇼케이스가 잠시 동안 불가피하다면 가장 빠른 수정 방법은 4단계에서 인라인 복사본을 실제 소스에 대해 가드하는 것이지만, 시스템이 실제 소비자를 가질 만큼 안정화되는 대로 이를 폐기할 계획을 세우세요.
쇼케이스를 배포할 수 있다면, 실제 URL에 배포하고 실제 좁은 뷰포트에서 확인하세요. 특정 섹션이 콘텐츠보다 좁을 때만 나타나는 레이아웃 버그(의도적으로 오버플로되는 장식 요소가 전체 문서를 넓히는 등)는 모든 정적 검사에 보이지 않습니다 — 토큰 위반도, 대비 실패도, 린트 오류도 아닙니다. 실제 브라우저에서 실제 너비로만 존재합니다. 그러한 버그 중 하나가 출시되어 세 버전을 살아남았는데, 그 이유는 시스템이 보여진 유일한 장소가 로컬 파일이었기 때문입니다.
문서가 두 개 이상 있으면 버전 관리 정책과 문서를 읽는 순서를 기록하세요. 한 문단의 비용으로 누군가가 다시 유도하는 시간을 절약할 수 있습니다.

6단계 — 패키징 및 배포

1단계에서 "여러 프로젝트에서 재사용"이라고 답한 경우에만 해당됩니다.

설치 가능한 패키지로 출시하세요(exports 맵이 있는 package.json). "이 파일들을 프로젝트에 복사하세요"는 절대 하지 마세요 — 복사에는 다운스트림 수정이 업스트림으로 다시 흘러갈 경로가 없으며, 이것이 시스템 자체의 진실 공급원이 조용히 두 복사본 중 더 손상된 복사본이 되는 방법입니다. 이것은 전체 계보에서 첫 번째 버그의 근본 원인이었습니다.
Tailwind 프리셋을 배포하는 경우: 프리셋의 content 배열은 Tailwind에 의해 병합되지 않습니다. 소비자의 자체 content 배열은 프리셋의 것을 완전히 대체합니다. 이것은 카탈로그에서 두 번째로 비용이 많이 드는 버그이며, "명백한" 수정 방법(프리셋에서 glob을 선언하고 결합된다고 가정)은 작동하지 않습니다. 빌드는 바이트 단위로 동일하게 돌아오며, 이것이 신호입니다. 프리셋은 해당 glob을 내보내야 하며, 모든 온보딩 자료(README, 스캐폴드 명령이 있다면)는 소비자가 명시적으로 펼쳐서 사용하도록 보여야 합니다: content: [...preset.content, ...yourGlobs]. 번들러 자체의 구성 확인 API로 이를 검증하고 가정하지 마세요 — "수정" 후에 변경되지 않은 빌드 아티팩트는 우연이 아니라 버그 신호입니다.
태그로 버전을 관리하고, 브랜치만 사용하지 마세요. 브랜치 고정은 소스 저장소의 브랜치가 진보하는 순간 소비자 아래에서 조용히 움직입니다. 이것이 소비자가 아무도 결정하지 않은 상태에서 테스트되지 않은 버전을 출시할 수 있는 방법입니다. 소비자가 새 태그로 이동해야 하는 경우, 락파일이 package.json의 태그와 독립적으로 정확한 해결된 커밋을 고정할 수 있음을 기억하세요 — 재해결을 강제하고 node_modules가 실제로 새 버전을 보고하는지 확인한 후 재빌드를 신뢰하세요.
패키지가 새 소비자를 위한 스캐폴드/초기화 명령을 제공하는 경우, 첫날부터 올바른, 펼쳐진 콘텐츠 구성을 내보내도록 하세요. 자체 결정 로그 항목을 가질 만큼 심각한 함정에 대해 모든 소비자의 README 읽기 규율에 의존하지 마세요.

7단계 — 검증

계속해서 적용되며, 마지막에 한 번만 적용되는 것이 아닙니다.

작업 디렉토리가 아닌 새로 설치하거나 복제한 환경에서 테스트하세요. 작업 디렉토리는 실제 소비자가 첫날에 부딪힐 수 있는 누락된 내보내기, 커밋되지 않은 수정, 오래된 캐시를 숨깁니다.
"수정" 후에 변경되지 않은 빌드 아티팩트는 수정이 작동하지 않았다는 신호이지, 우연이 아닙니다. 실제 출력을 비교하여 변경된 것이 있다고 믿기 전에 확인하세요.
타입 검사는 검증이 아닙니다. 이 카탈로그에서 가장 심각한 버그(완전히 잘못된 서체로 렌더링되는 글꼴)는 사용 가능한 모든 정적 검사를 통과했으며, 실제 소비자에서 구성 요소를 렌더링하고 확인함으로써만 발견되었습니다. 완료되었다고 말하기 전에 실제 무언가에서 모든 것을 적어도 한 번 렌더링하세요.
검증 주장에 대해 편리해 보이는 플랫폼 API를 신뢰하지 마세요. document.fonts.check()는 "이 글꼴이 실제로 이 글리프를 포함하고 있는지" 확인하는 완벽한 도구처럼 보이지만 거짓말을 합니다(avail...

[번역을 위해 잘림]

(참고: SKILL.md의 마지막 부분이 원본에서 잘렸습니다. 전체 내용을 번역하려면 원본의 전체 텍스트가 필요합니다. 제공된 내용을 기준으로 번역했습니다.)

디자인 시스템 빌더